# Modelica Aspects and Modeling Advice

This chapter explains some important aspects of the Modelica language and gives you advice on things to keep in mind when working with *SystemModeler*.

## Initial Values

There are several ways to set initial values in a Modelica model. Here, the most common ways are explained.

### Start Attribute

Start values for state variables can be set either by using the start attribute or by including equations in the initial equation/algorithm section. If a variable is a state variable, a start value is often needed in order to make sure that the variable has a suitable value at the start of a simulation. The default start value is 0 for numerical variables (Integer and Real), false for Boolean variables, and the empty string "" for String variables.

While a state variable will always have the value of the start attribute at the start of a simulation, a variable that is not a state variable may not. For non-state variables, the start attribute value is treated as a guess value. In the example below, x is a state variable (since it is used in a der expression) and the start value is set to 1, hence the value of x will be 1 at the start of the simulation.

model A

Real x(start=1);

equation

der(x)=-x + 1;

end A;

#### Guess Values

The start attribute can also be used to help the solver in finding the correct value for a non-state variable. The equation z^{2} = 6 - z has two solutions, 2 and -3 respectively. To help the solver find the desired solution, a start (guess) value may be given for z. This value should be chosen to be as close as possible to the real solution. For example, if a start value of 4 is used for z, the solution will be z=2. If a start value of -5 is used, the solution will be z=-3. See models B1 and B2 below.

model B1

Real z(start=4);

equation

z^2=6-z;

end B1;

Result B1: z=2

model B2

Real z(start=-5);

equation

z^2=6-z;

end B2;

Result B2: z=-3

Guess values are useful when working with nonlinear equations, and in particular if the objective is to start in a steady state. In that case, start values for state variables may be used as guess values.

### Initial Equations and Algorithms

Another method to set initial values of variables is to use the initial equation or initial algorithm section.

model C

Real x;

initial algorithm

x:=1;

equation

der(x)=-x + 1;

end C;

In model C, x will always start with its value equal to 1, while in model A (above), the start value of x could easily be changed by a modification. It is not possible to change an initial equation section by a modification. An initial equation section is more powerful than the start attribute, since you could calculate a start value using equations. For example, in model D the variable x will start in steady state, since der(x)=0 is used as an initial equation.

model D

Real x;

Real y(start=3);

initial equation

der(x)=0;

equation

der(x)=-x + y + 1;

der(y)=-y +2;

end D;

## Events

An event is generated during simulation, for example when the Boolean expression of an if equation changes its value. When an event occurs, the solver stops and iterates to find the exact point in time of the event. These iterations can take some time and it is advised to try to minimize them if possible.

One method to avoid unnecessary iterations is to use the built-in operator noEvent in order to give a hint to the solver that event generation is not needed. This operator can only be used if an expression is continuous during the event (not necessarily differentiable).

model EventTest

Real x1;

Real x2;

equation

x1=if time<3 then time else 3 "Event generated at time=3";

x2=noEvent(if time<3 then time else 3) "No event generated";

end EventTest;

The noEvent operator can also be used to protect against illegal evaluation. In the following example sin(x)/x is calculated. To guard against division by zero, noEvent is used around abs(x) > 0 to make sure that sin(x)/x is not evaluated if x = 0.

model GuardEval

Real x;

Real y;

equation

x=time - 1;

y=if noEvent(abs(x) > 0) then sin(x)/x else 1;

end GuardEval;

## The MultiBody Library

Modelica.MultiBody is a Modelica library for 3D mechanical modeling. Working with 3D models can be complicated, since all parts need to be connected in space and initial values need to be correct in order for the system to start. *SystemModeler* contains visualization for models created with the MultiBody library to aid the user in analyzing the movement in a convenient way. Below are some important things to consider when working with the MultiBody library. An introduction to the library as well as information about its components can be found by accessing the embedded documentation of the Modelica.MultiBody package and its classes. The figure below shows a model of a planar loop built with the MultiBody library.

### Initial Values

It is important to get the system to initialize the states properly to get a physically correct model. In this example, we have chosen to use the states in the revolute3 component by setting the parameter stateSelect in revolute3 to StateSelect.always. When the model is translated or built, appropriate states are selected. The initial values of these states are shown in the Variables tab in *Simulation Center*.

Selected states for the model in the previous screen shot.

As seen in the screen shot above, the angle of the joint revolute1 will start with the speed 0.0 rad/s and at the angle 1.56 rad. These values can also be changed directly in the model in the General tab in *Model Center*.

### Angle and Position of Objects

It is very important to get a physically correct model, otherwise the system will likely fail to start a simulation. Try to use simple directions, e.g. r={1, 0, 0}, r={0, -1, 0} for components like BodyCylinder, BodyBox, etc. If another direction is needed, change phi in a joint or use the FixedRotation and FixedTranslation components available in MultiBody.Parts.

### Animations

Some of the MultiBody components contain animation information. These are the Body, BodyBox, BodyCylinder, and BodyShape components in MultiBody.Parts. There are also visualizers that show properties like velocity, acceleration, etc. in MultiBody.Visualizers.

Animation of a simple loop model containing three bars from the model above.

As indicated by their respective names, the BodyBox is box shaped and the BodyCylinder is cylinder shaped. If more variants of animated shapes are needed, e.g. sphere, cone, gearwheel, etc., the BodyShape can be used, setting the parameter shapeType to the desired shape. If only a pure animation is needed without physical properties, the Shape object can be used.

The figure below shows an example of a pendulum with a sphere at the end, where the BodyShape component has been used to animate the sphere.

A pendulum model with a sphere shape at the end.

### CAD Shapes

CAD shapes are specified by setting the shapeType parameter to a Modelica URI that points to the CAD file. A Modelica URI has the following structure:

modelica://<Modelica-name>/<relative-file-path>

This specifies the path relative to the location of the Modelica library <Modelica-name>.

*SystemModeler* supports the following CAD shape formats:

Animation view of Modelica.Mechanics.MultiBody.Examples.Systems.RobotR3.fullRobot.

## General Advice

Below is a collection of general tips that may prove useful to avoid some common problems.

- Debugging equation-based languages is a different task compared to algorithm-based languages, since it is not possible to add break points, solve step by step, etc. Therefore, try to build up your model step by step, i.e. make small tests of partial systems of your complete model. If an error occurs, it will be a lot easier to locate if the model is small.

- Use the Validate Class feature, described here, when creating components. If a component validation is successful, it is more likely that the component will work together with other components. A complete component should always return an equal number of variables and equations from the validation. Note that a partial model naturally often returns a different number of equations than variables.

- If a simulation takes a long time, it could be due to a large number of events. The number of events can be found in the simulation log after a simulation is finished. If possible, try to reduce the number of events by using the noEvent operator (see above) or try to change your model. Note that when modeling sampled systems, an event is generated at each sample time, which is normal.

- Try to avoid the automatic setting of output intervals when simulating a well-known system. Since data is written to file at each solver step, this could drastically reduce the simulation performance for larger systems. When the model behavior is known, it is recommended to switch to a fixed number of output intervals or use an interval length setting instead.