Equations

Events

Avoid events where possible.

Division

Only divide by quantities that cannot take on zero. For example, if x may take on zero, use y=x, not 1=y/x, as the second version indicates to a simulator that it is save to divide by x.

Assert

Use the assert function to check for invalid values of parameters or variables, i.e. use assert(phi>=0, "Relative humidity must not be negative.")

Graphical Modelling vs. Textual Code

Use either graphical modelling or textual code. A class should only contain connect() rows or concrete equations - but not a mixture of both

Continuously Differentiable Equations

For computational efficiency, equations shall where possible be differentiable and have a continuous first derivative.

Differentiable Equations

Avoid equations where the first derivative with respect to another variable is zero. For example, if x, y are variables, and x = f(y), avoid y = 0 for x<0 and y=x^2 otherwise. The reason is that if a simulator tries to solve 0=f(x), then any value of x <= 0 is a solution, which can cause instability in the solver.

Note that this problem does not exist for constant functions, as their first derivative will replaced due to optimization within the solver.

Replacing Equations

Do not replace an equation by a constant for a single value, unless the derivative of the original equation is zero for this value. If computing a pressure drop_dp may involve computing a long equation, but one knows that the result is always zero if the volume flow rate V_flow is zero, one may be inclined to use a construct of the form: dp = smooth(1, if V_flow == 0 then 0 else f(V_flow));

The problem with this formulation is that for V_flow=0, the derivative is dp/dV_flow = 0. However, the limit dp/dV_flow, as |V_flow| tends to zero, may be non-zero. Hence, the first derivative has a discontinuity at V_flow=0, which can cause a solver to fail to solve the equation because the smooth statement declared that the first derivative exists and is continuous.

Bounded Equations

Make sure that the derivatives of equations are bounded on compact sets, i.e., instead of using y=sign(x) * sqrt(abs(x)), approximate the equation with a differentiable function that has a finite derivative near zero.

Numerical Jacobians

Whenever possible, a Modelica tool should not have to do numerical differentiation. For example in Dymola, if your model translation log shows Number of numerical Jacobians: 1 (or any number other than zero), then enter on the command line Hidden.PrintFailureToDifferentiate = true;. Next, translate the model again to see what functions cannot be differentiated symbolically. Then, implement symbolic derivatives for this function.

If... ElseIf... Else

Each if ... elseif section needs an else condition even if the else condition contains just a message like "This should never happen".

---

Functions