Modelica.UsersGuide

Package Modelica is a standardized and pre-defined package that is developed together with the Modelica language from the Modelica Association, see https://www.Modelica.org. It is also called Modelica Standard Library. It provides constants, types, connectors, partial models and model components in various disciplines.

This is a short User's Guide for the overall library. Some of the main sublibraries have their own User's Guides that can be accessed by the following links:

Extends from Modelica.Icons.Information (Icon for general information packages).

Package Content

Name	Description
Overview	Overview of Modelica Library
Connectors	Connectors
Conventions	Conventions
ParameterDefaults	Parameter defaults
ReleaseNotes	Release notes
Contact	Contact

Modelica.UsersGuide.Overview

The Modelica Standard Library consists of the following main sub-libraries:

Library Components	Description
	Analog Analog electric and electronic components, such as resistor, capacitor, transformers, diodes, transistors, transmission lines, switches, sources, sensors.
	Digital Digital electrical components based on the VHDL standard, like basic logic blocks with 9-value logic, delays, gates, sources, converters between 2-, 3-, 4-, and 9-valued logic.
	Machines Electrical asynchronous-, synchronous-, and DC-machines (motors and generators) as well as 3-phase transformers.
	FluxTubes Based on magnetic flux tubes concepts. Especially to model electro-magnetic actuators. Nonlinear shape, force, leakage, and material models. Material data for steel, electric sheet, pure iron, Cobalt iron, Nickel iron, NdFeB, Sm2Co17, and more.
	Translational 1-dim. mechanical, translational systems, e.g., sliding mass, mass with stops, spring, damper.
	Rotational 1-dim. mechanical, rotational systems, e.g., inertias, gears, planetary gears, convenient definition of speed/torque dependent friction (clutches, brakes, bearings, ..)
	MultiBody 3-dim. mechanical systems consisting of joints, bodies, force and sensor elements. Joints can be driven by drive trains defined by 1-dim. mechanical system library (Rotational). Every component has a default animation. Components can be arbitrarily connected together.
	Fluid 1-dim. thermo-fluid flow in networks of vessels, pipes, fluid machines, valves and fittings. All media from the Modelica.Media library can be used (so incompressible or compressible, single or multiple substance, one or two phase medium).
	Media Large media library providing models and functions to compute media properties, such as h = h(p,T), d = d(p,T), for the following media: 1240 gases and mixtures between these gases. incompressible, table based liquids (h = h(T), etc.). compressible liquids dry and moist air high precision model for water (IF97).
	FluidHeatFlow, HeatTransfer Simple thermo-fluid pipe flow, especially to model cooling of machines with air or water (pipes, pumps, valves, ambient, sensors, sources) and lumped heat transfer with heat capacitors, thermal conductors, convection, body radiation, sources and sensors.
	Blocks Input/output blocks to model block diagrams and logical networks, e.g., integrator, PI, PID, transfer function, linear state space system, sampler, unit delay, discrete transfer function, and/or blocks, timer, hysteresis, nonlinear and routing blocks, sources, tables.
	StateGraph Hierarchical state machines with a similar modeling power as Statecharts. Modelica is used as synchronous action language, i.e., deterministic behavior is guaranteed
A = [1,2,3; 3,4,5; 2,1,4]; b = {10,22,12}; x = Matrices.solve(A,b); Matrices.eigenValues(A);	Math, Utilities Functions operating on vectors and matrices, such as for solving linear systems, eigen and singular values etc., and functions operating on strings, streams, files, e.g., to copy and remove a file or sort a vector of strings.

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica.UsersGuide.Connectors

The Modelica standard library defines the most important elementary connectors in various domains. If any possible, a user should utilize these connectors in order that components from the Modelica Standard Library and from other libraries can be combined without problems. The following elementary connectors are defined (the meaning of potential, flow, and stream variables is explained in section "Connector Equations" below):

domain	potential variables	flow variables	stream variables	connector definition	icons
electrical analog	electrical potential	electrical current		Modelica.Electrical.Analog.Interfaces Pin, PositivePin, NegativePin
electrical multi-phase	vector of electrical pins			Modelica.Electrical.MultiPhase.Interfaces Plug, PositivePlug, NegativePlug
electrical space phasor	2 electrical potentials	2 electrical currents		Modelica.Electrical.Machines.Interfaces SpacePhasor
quasi stationary single phase	complex electrical potential	complex electrical current		Modelica.Electrical.QuasiStationary.SinglePhase.Interfaces Pin, PositivePin, NegativePin
quasi stationary multi-phase	vector of quasi stationary single phase pins			Modelica.Electrical.QuasiStationary.MultiPhase.Interfaces Plug, PositivePlug, NegativePlug
electrical digital	Integer (1..9)			Modelica.Electrical.Digital.Interfaces DigitalSignal, DigitalInput, DigitalOutput
magnetic flux tubes	magnetic potential	magnetic flux		Modelica.Magnetic.FluxTubes.Interfaces MagneticPort, PositiveMagneticPort, NegativeMagneticPort
magnetic fundamental wave	complex magnetic potential	complex magnetic flux		Modelica.Magnetic.FundamentalWave.Interfaces MagneticPort, PositiveMagneticPort, NegativeMagneticPort
translational	distance	cut-force		Modelica.Mechanics.Translational.Interfaces Flange_a, Flange_b
rotational	angle	cut-torque		Modelica.Mechanics.Rotational.Interfaces Flange_a, Flange_b
3-dim. mechanics	position vector orientation object	cut-force vector cut-torque vector		Modelica.Mechanics.MultiBody.Interfaces Frame, Frame_a, Frame_b, Frame_resolve
simple fluid flow	pressure specific enthalpy	mass flow rate enthalpy flow rate		Modelica.Thermal.FluidHeatFlow.Interfaces FlowPort, FlowPort_a, FlowPort_b
thermo fluid flow	pressure	mass flow rate	specific enthalpy mass fractions	Modelica.Fluid.Interfaces FluidPort, FluidPort_a, FluidPort_b
heat transfer	temperature	heat flow rate		Modelica.Thermal.HeatTransfer.Interfaces HeatPort, HeatPort_a, HeatPort_b
blocks	Real variable Integer variable Boolean variable			Modelica.Blocks.Interfaces RealSignal, RealInput, RealOutput IntegerSignal, IntegerInput, IntegerOutput BooleanSignal, BooleanInput, BooleanOutput
complex blocks	Complex variable			Modelica.ComplexBlocks.Interfaces ComplexSignal, ComplexInput, ComplexOutput
state machine	Boolean variables (occupied, set, available, reset)			Modelica.StateGraph.Interfaces Step_in, Step_out, Transition_in, Transition_out

In all domains, usually 2 connectors are defined. The variable declarations are identical, only the icons are different in order that it is easy to distinguish connectors of the same domain that are attached at the same component.

Hierarchical Connectors

Modelica supports also hierarchical connectors, in a similar way as hierarchical models. As a result, it is, e.g., possible, to collect elementary connectors together. For example, an electrical plug consisting of two electrical pins can be defined as:

connector Plug
   import Modelica.Electrical.Analog.Interfaces;
   Interfaces.PositivePin phase;
   Interfaces.NegativePin ground;
end Plug;

With one connect(..) equation, either two plugs can be connected (and therefore implicitly also the phase and ground pins) or a Pin connector can be directly connected to the phase or ground of a Plug connector, such as "connect(resistor.p, plug.phase)".

Connector Equations

The connector variables listed above have been basically determined with the following strategy:

1. State the relevant balance equations and boundary conditions of a volume for the particular physical domain.
2. Simplify the balance equations and boundary conditions of (1) by taking the limit of an infinitesimal small volume (e.g., thermal domain: temperatures are identical and heat flow rates sum up to zero).
3. Use the variables needed for the balance equations and boundary conditions of (2) in the connector and select appropriate Modelica prefixes, so that these equations are generated by the Modelica connection semantics.

The Modelica connection semantics is sketched at hand of an example: Three connectors c1, c2, c3 with the definition

connector Demo
  Real        p;  // potential variable
  flow   Real f;  // flow variable
  stream Real s;  // stream variable
end Demo;

are connected together with

   connect(c1,c2);
   connect(c1,c3);

then this leads to the following equations:

  // Potential variables are identical
  c1.p = c2.p;
  c1.p = c3.p;

  // The sum of the flow variables is zero
  0 = c1.f + c2.f + c3.f;

  /* The sum of the product of flow variables and upstream stream variables is zero
     (this implicit set of equations is explicitly solved when generating code;
     the "<undefined>" parts are defined in such a way that
     inStream(..) is continuous).
  */
  0 = c1.f*(if c1.f > 0 then s_mix else c1.s) +
      c2.f*(if c2.f > 0 then s_mix else c2.s) +
      c3.f*(if c3.f > 0 then s_mix else c3.s);

  inStream(c1.s) = if c1.f > 0 then s_mix else <undefined>;
  inStream(c2.s) = if c2.f > 0 then s_mix else <undefined>;
  inStream(c3.s) = if c3.f > 0 then s_mix else <undefined>;

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica.UsersGuide.ParameterDefaults

In this section the convention is summarized how default parameters are handled in the Modelica Standard Library (since version 3.0).

Many models in this library have parameter declarations to define constants of a model that might be changed before simulation starts. Example:

model SpringDamper
parameter Real c(final unit="N.m/rad")    = 1e5 "Spring constant";
parameter Real d(final unit="N.m.s/rad")  = 0   "Damping constant";
parameter Modelica.SIunits.Angle phi_rel0 = 0   "Unstretched spring angle";
...
end SpringDamper;

In Modelica it is possible to define a default value of a parameter in the parameter declaration. In the example above, this is performed for all parameters. Providing default values for all parameters can lead to errors that are difficult to detect, since a modeler may have forgotten to provide a meaningful value (the model simulates but gives wrong results due to wrong parameter values). In general the following basic situations are present:

1. The parameter value could be anything (e.g., a spring constant or a resistance value) and therefore the user should provide a value in all cases. A Modelica translator should warn, if no value is provided.
2. The parameter value is not changed in > 95 % of the cases (e.g., initialization or visualization parameters, or parameter phi_rel0 in the example above). In this case a default parameter value should be provided, in order that the model or function can be conveniently used by a modeler.
3. A modeler would like to quickly utilize a model, e.g.,
   • to automatically check that the model still translates and/or simulates (after some changes in the library),
   • to make a quick demo of a library by drag-and-drop of components,
   • to implement a simple test model in order to get a better understanding of the desired component.
   In all these cases, it would be not practical, if the modeler would have to provide explicit values for all parameters first.

To handle the conflicting goals of (1) and (3), the Modelica Standard Library uses two approaches to define default parameters, as demonstrated with the following example:

model SpringDamper
parameter Real c(final unit="N.m/rad"  , start=1e5) "Spring constant";
parameter Real d(final unit="N.m.s/rad", start=  0) "Damping constant";
parameter Modelica.SIunits.Angle phi_rel0 = 0       "Unstretched spring angle";
...
end SpringDamper;

SpringDamper sp1;              // warning for "c" and "d"
SpringDamper sp2(c=1e4, d=0);  // fine, no warning

Both definition forms, using a "start" value (for "c" and "d") and providing a declaration equation (for "phi_rel0"), are valid Modelica and define the value of the parameter. By convention, it is expected that Modelica translators will trigger a warning message for parameters that are not defined by a declaration equation, by a modifier equation or in an initial equation/algorithm section. A Modelica translator might have options to change this behavior, especially, that no messages are printed in such cases and/or that an error is triggered instead of a warning.

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica.UsersGuide.Contact

The Modelica Standard Library (this Modelica package) is developed by contributors from different organizations (see list below). It is licensed under the BSD 3-Clause License by:

Modelica Association

(Ideella Föreningar 822003-8858 in Linköping)

c/o PELAB, IDA, Linköpings Universitet

S-58183 Linköping

Sweden

email: Board@Modelica.org

web: https://www.Modelica.org

The development of this Modelica package, starting with version 3.2.3, is organized by:

Thomas Beutlich and Dietmar Winkler

The development of this Modelica package of version 3.2.2 was organized by:

Anton Haumer

Technical Consulting & Electrical Engineering

D-93049 Regensburg

Germany

email: A.Haumer@Haumer.at

The development of this Modelica package up to and including version 3.2.1 was organized by:

Martin Otter

German Aerospace Center (DLR)

Robotics and Mechatronics Center (RMC)

Institute of System Dynamics and Control (SR)

Postfach 1116

D-82230 Wessling

Germany

email: Martin.Otter@dlr.de

Since end of 2007, the development of the sublibraries of package Modelica is organized by personal and/or organizational library officers assigned by the Modelica Association. They are responsible for the maintenance and for the further organization of the development. Other persons may also contribute, but the final decision for library improvements and/or changes is performed by the responsible library officer(s). In order that a new sublibrary or a new version of a sublibrary is ready to be released, the responsible library officers report the changes to the members of the Modelica Association and the library is made available for beta testing to interested parties before a final decision. A new release of a sublibrary is formally decided by voting of the Modelica Association members.

As of March 21st, 2018, the following library officers are assigned:

The following people have directly contributed to the implementation of the Modelica package (many more people have contributed to the design):

Extends from Modelica.Icons.Contact (Icon for contact information).