Chapter 3 Operators and Expressions

The built-in operators in this section trigger events if used outside of a when-clause and outside of a clocked discrete-time partition (see section 16.8.1). These expression for div, ceil, floor, and integer are event generating expression. The event generating expression for mod(x,y) is floor(x/y), and for rem(x,y) it is div(x,y) - i.e. events are not generated when mod or rem changes continuously in an interval, but when they change discontinuously from one interval to the next. [ If this is not desired, the noEvent function can be applied to them. E.g. noEvent(integer(v)) ]

The following built-in mathematical functions are available in Modelica and can be called directly without any package prefix added to the function name. They are also available as external built-in functions in the Modelica.Math library.

[The delay() operator allows a numerical sound implementation by interpolating in the (internal) integrator polynomials, as well as a more simple realization by interpolating linearly in a buffer containing past values of expression expr. Without further information, the complete time history of the delayed signals needs to be stored, because the delay time may change during simulation. To avoid excessive storage requirements and to enhance efficiency, the maximum allowed delay time has to be given via delayMax.

This gives an upper bound on the values of the delayed signals which have to be stored. For real-time simulation where fixed step size integrators are used, this information is sufficient to allocate the necessary storage for the internal buffer before the simulation starts. For variable step size integrators, the buffer size is dynamic during integration. In principle, a delay operator could break algebraic loops. For simplicity, this is not supported because the minimum delay time has to be give as additional argument to be fixed at compile time. Furthermore, the maximum step size of the integrator is limited by this minimum delay time in order to avoid extrapolation in the delay buffer.]

[Many applications involve the modelling of variable-speed transport of properties. One option to model this infinite-dimensional system is to approximate it by an ODE, but this requires a large number of state variables and might introduce either numerical diffusion or numerical oscillations. Another option is to use a built-in operator that keeps track of the spatial distribution of z(x, t), by suitable sampling, interpolation, and shifting of the stored distribution. In this case, the internal state of the operator is hidden from the ODE solver.]

The spatialDistribution() operator allows to approximate efficiently the solution of the infinite-dimensional problem

where $z(y,t)$ is the transported quantity, y is the normalized spatial coordinate ($0.0\le y\le 1.0$), $t$ is the time, $v(t)=\mathrm{der}(x)$ is the normalized transport velocity and the boundary conditions are set at either $y=0.0$ or $y=1.0$, depending on the sign of the velocity. The calling syntax is:

where in0, in1, out0, out1, x, v are all subtypes of Real, positiveVelocity is a Boolean, initialPoints and initialValues are arrays of subtypes of Real of equal size, containing the y coordinates and the z values of a finite set of points describing the initial distribution of z(y, t0). The out0 and out1 are given by the solutions at z(0.0, t) and z(1.0, t); and in0 and in1 are the boundary conditions at z(0.0, t) and z(1.0, t) (at each point in time only one of in0 and in1 is used). Elements in the initialPoints array must be sorted in non-descending order. The operator can not be vectorized according to the vectorization rules described in section 12.4.6. The operator can be vectorized only with respect to the arguments in0 and in1 (which must have the same size), returning vectorized outputs out0 and out1 of the same size; the arguments initialPoints and initialValues are vectorized accordingly.

The solution, z(..), can be described in terms of characteristics:
$z(y+{\int }_t^{t+\beta }v(\alpha )𝑑\alpha ,t+\beta )=z(y,t),$ for all $\beta$ as long as staying inside the domain.

This allows to directly compute the solution based on interpolating the boundary conditions.

The spatialDistribution operator can be described in terms of the pseudo-code given as a block:

[Note that the implementation has an internal state and thus cannot be described as a function in Modelica; initialPoints and initialValues are declared as parameters to indicate that they are only used during initialization.

The infinite-dimensional problem stated above can then be formulated in the following way:

Events are generated at the exact instants when the velocity changes sign – if this is not needed, noEvent() can be used to suppress event generation.

If the velocity is known to be always positive, then out0 can be omitted, e.g.:

Technically relevant use cases for the use of the spatialDistribution() operator are modeling of electrical transmission lines, pipelines and pipeline networks for gas, water and district heating, sprinkler systems, impulse propagation in elongated bodies, conveyor belts, and hydraulic systems. Vectorization is needed for pipelines where more than one quantity is transported with velocity v in the example above.]

[The cardinality operator is deprecated for the following reasons and will be removed in a future release:

• •

  Reflective operator may make early type checking more difficult.

• •

  Almost always abused in strange ways

• •

  Not used for Bond graphs even though it was originally introduced for that purpose.

]

[The cardinality() operator allows the definition of connection dependent equations in a model, for example:

]

The cardinality is counted after removing conditional components. and may not be applied to expandable connectors, elements in expandable connectors, or to arrays of connectors (but can be applied to the scalar elements of array of connectors). The cardinality operator should only be used in the condition of assert and if-statements – that do not contain connect (and similar operators – see section 16.8.1).

[During the initialization phase of a dynamic simulation problem, it often happens that large nonlinear systems of equations must be solved by means of an iterative solver. The convergence of such solvers critically depends on the choice of initial guesses for the unknown variables. The process can be made more robust by providing an alternative, simplified version of the model, such that convergence is possible even without accurate initial guess values, and then by continuously transforming the simplified model into the actual model. This transformation can be formulated using expressions of this kind:

in the formulation of the system equations, and is usually called a homotopy transformation. If the simplified expression is chosen carefully, the solution of the problem changes continuously with $\lambda$, so by taking small enough steps it is possible to eventually obtain the solution of the actual problem.

The operator can be called with ordered arguments or preferably with named arguments for improved readability.

It is recommended to perform (conceptually) one homotopy iteration over the whole model, and not several homotopy iterations over the respective non-linear algebraic equation systems. The reason is that the following structure can be present:

Here, a non-linear equation system $f_2$ is present. The homotopy operator is, however used on a variable that is an “input” to the non-linear algebraic equation system, and modifies the characteristics of the non-linear algebraic equation system. The only useful way is to perform the homotopy iteration over $f_1$ and $f_2$ together.

The suggested approach is “conceptual”, because more efficient implementations are possible, e.g. by determining the smallest iteration loop, that contains the equations of the first BLT block in which a homotopy operator is present and all equations up to the last BLT block that describes a non-linear algebraic equation system.

A trivial implementation of the homotopy operator is obtained by defining the following function in the global scope:

Example 1:

In electrical systems it is often difficult to solve non-linear algebraic equations if switches are part of the algebraic loop. An idealized diode model might be implemented in the following way, by starting with a “flat” diode characteristic and then move with the homotopy operator to the desired “steep” characteristic:

Example 2:

In electrical systems it is often useful that all voltage sources start with zero voltage and all current sources with zero current, since steady state initialization with zero sources can be easily obtained. A typical voltage source would then be defined as:

Example 3:

In fluid system modelling, the pressure/flowrate relationships are highly nonlinear due to the quadratic terms and due to the dependency on fluid properties. A simplified linear model, tuned on the nominal operating point, can be used to make the overall model less nonlinear and thus easier to solve without accurate start values. Named arguments are used here in order to further improve the readability.

Example 4:

Note that the homotopy operator shall not be used to combine unrelated expressions, since this can generate singular systems from combining two well-defined systems.

The initial equation is expanded into

and you can solve the two equations to give

which has the correct value of $x_{\mathrm{0}}$ at $\lambda \mathrm{=}\mathrm{0}$ and of 1 at $\lambda \mathrm{=}\mathrm{1}$, but unfortunately has a singularity at $\lambda \mathrm{=}\mathrm{0.5}$ . ]

(See definition of semiLinear in section 3.7.2). In some situations, equations with the semiLinear() function become underdetermined if the first argument (x) becomes zero, i.e., there are an infinite number of solutions. It is recommended that the following rules are used to transform the equations during the translation phase in order to select one meaningful solution in such cases:

Rule 1: The equations

may be replaced by

Rule 2: The equations

may be replaced by

[For symbolic transformations, the following property is useful (this follows from the definition):

is identical to :

The semiLinear function is designed to handle reversing flow in fluid systems, such as

i.e., the enthalpy flow rate H_flow is computed from the mass flow rate m_flow and the upstream specific enthalpy depending on the flow direction.

]

Returns a string with the name of the model/block that is simulated, appended with the fully qualified name of the instance in which this function is called.

[Example:

If MyLib.Vehicle is simulated, the call of getInstanceName() returns:”Vehicle.engine.controller”

]

If this function is not called inside a model or block (e.g. the function is called in a function or in a constant of a package), the return value is not specified.

[The simulation result should not depend on the return value of this function. ]

A new event is triggered if at least for one variable v “pre(v)<> v” after the active model equations are evaluated at an event instant. In this case the model is at once reevaluated. This evaluation sequence is called “event iteration”. The integration is restarted, if for all v used in pre-operators the following condition holds: “pre(v) == v”.

[If v and pre(v) are only used in when-clauses, the translator might mask event iteration for variable v since v cannot change during event iteration. It is a “quality of implementation” to find the minimal loops for event iteration, i.e., not all parts of the model need to be reevaluated.

The language allows mixed algebraic systems of equations where the unknown variables are of type Real, Integer, Boolean, or an enumeration. These systems of equations can be solved by a global fix point iteration scheme, similarly to the event iteration, by fixing the Boolean, Integer, and/or enumeration unknowns during one iteration. Again, it is a quality of implementation to solve these systems more efficiently, e.g., by applying the fix point iteration scheme to a subset of the model equations.]

The noEvent operator implies that real elementary relations/functions are taken literally instead of generating crossing functions, section 8.5. The smooth operator should be used instead of noEvent, in order to avoid events for efficiency reasons. A tool is free to not generate events for expressions inside smooth. However, smooth does not guarantee that no events will be generated, and thus it can be necessary to use noEvent inside smooth. [Note that smooth does not guarantee a smooth output if any of the occurring variables change discontinuously.]

[Example:

]