Simple First Order System¶

Let us consider an extremely simple differential equation:

Looking at this equation, we see there is only one variable, . This equation can be represented in Modelica as follows:

model FirstOrder
  Real x;
equation
  der(x) = 1-x;
end FirstOrder;

This code starts with the keyword model which is used to indicate the start of the model definition. The model keyword is followed by the model name, FirstOrder. This, in turn, is followed by a declaration of all the variables we are interested in.

Since the variable in our equation is clearly meant to be a continuous real valued variable, its declaration in Modelica takes the form Real x;. The Real type is just one of the types we can use (a more complete description of the various possibilities will be discussed in the upcoming section on Variables).

Once all the variables have been declared, we can begin including the equations that describe the behavior of our model. In this case, we can use the der operator to represent the time derivative of x. Thus,

der(x) = (1-x)

is equivalent to:

Unlike most programming languages, we don’t approach code like this as a “program” that can be interpreted as a set of instructions to be executed one after the other. Instead, we use a Modelica compiler to transform this model into something that we can simulate. This simulation step essentially amounts to solving (usually numerically) the equation and providing a solution trajectory like this:

This gives you the first initial hint at one of the compelling aspects about using a modeling language to describe mathematical behavior. We didn’t need to describe how to solve this differential equation. The focus is entirely on behavior. As we work our way through more complex examples, we will see that much of the tedious work involving the solution process is handled automatically by the Modelica compiler.

Adding Some Documentation¶

Now that we’ve solved this simple mathematical equation, let’s turn our attention briefly to how we can make the model a bit more readable. Consider the following model:

model FirstOrderDocumented "A simple first order differential equation"
  Real x "State variable";
equation
  der(x) = 1-x "Drives value of x toward 1.0";
end FirstOrderDocumented;

Note the quoted text in this model.

It is important to understand that the quoted text blocks, called “strings” in computer science, are not comments. They are “descriptive strings” and, unlike comments, they cannot be added in arbitrary places. Instead, they can only be inserted in specific places to provide additional documentation about the elements of the model they are associated with.

For example, the first string “A simple first order differential equation” is used to describe what this is a model of. Note how it follows the name of the model. If you wish to include such documentation about the model, it must appear immediately after the model name as shown.

As we will see later, this kind of documentation can be used by tools in many ways. For example, when searching for models, a tool may use these descriptive strings when identifying matches. This text may also be associated with a graphical representation of the models. And, of course, this kind of documentation is very useful for anybody reading the model.

As this example demonstrates, there are other places that the descriptive text can appear. For example, it may be included after the declaration of a variable or equation to document them.

Initialization¶

As we have seen already, Modelica allows us to describe model behavior in terms of differential equations. But the initial conditions we choose are just as important as the equations.

For this reason, Modelica also provides constructs for describing the initialization of our system of equations. For example, if we wanted the initial value of x in our model to be 2, we could add an initial equation section to our model as follows:

model FirstOrderInitial "First order equation with initial value"
  Real x "State variable";
initial equation
  x = 2 "Used before simulation to compute initial values";
equation
  der(x) = 1-x "Drives value of x toward 1.0";
end FirstOrderInitial;

Note that the only difference between this model and the previous one, presented in the section on Adding Some Documentation, is the addition of the initial equation section which contains the equation x = 2. In the previous example, the initial value of x at the start of the simulation was unspecified. Generally speaking, this means that the initial value for x will be the value of its start attribute (which is zero by default). However, because each tool uses their own specific algorithms to formulate the final system of equations, it is always best to state initial conditions explicitly, as we have done here. By adding this equation to the initial equation section, we are explicitly specifying the initial condition for x.

As a result, the solution trajectory is quite different as we can see in the following figure:

The model FirstOrderInitial shows a typical way of initializing a system by providing explicit initial values for the states of the system. In fact, a system of differential equations is incomplete without a specification for how the initial conditions are determined. Our FirstOrderInitial model would be represented mathematically as:

However, there are many cases where you want a more sophisticated type of initialization. An initial equation section can contain more than just explicit equations for the initial values of the state variables.

For example, we might want our initial conditions to be such that the derivative of was zero at the start of the simulation. In this case, only a bit of trivial algebra is required to realize that this could be accomplished by specifying an initial condition of . However, for more complex systems, it is far from trivial to determine the initial state values that would satisfy such a requirement. In those cases, it is possible to express the constraint that directly in Modelica as follows:

model FirstOrderSteady
  "First order equation with steady state initial condition"
  Real x "State variable";
initial equation
  der(x) = 0 "Initialize the system in steady state";
equation
  der(x) = 1-x "Drives value of x toward 1.0";
end FirstOrderSteady;

Simulating this system gives the following solution:

As we see from these results, the initial derivative of is zero at the start of the simulation and remains zero because there are no external influences acting on this system that would disrupt this equilibrium.

This provides a glimpse of the initialization capablities in Modelica. More complete coverage of the initialization topic can be found in the Initialization section later in this chapter.

Experimental Conditions¶

When building a model, the model developer might wish to associate specific experimental conditions with the model. This can be done using something called an annotation. An annotation includes information that is not directly related to the behavior of the model.

For example, experimental conditions describe information like the start time of the simulation, the stop time, solution tolerance and so on. This is not information about the behavior of the model itself, but rather information about how to approach simulating that behavior. Experimental conditions are stored in a model using a specific annotation called the experiment annotation.

There are four pieces of information that can be specified in an experiment annotation. All of them are optional. The following is a model of our first order system that includes an experiment annotation:

model FirstOrderExperiment "Defining experimental conditions"
  Real x "State variable";
initial equation
  x = 2 "Used before simulation to compute initial values";
equation
  der(x) = 1-x "Drives value of x toward 1.0";
  annotation ...
end FirstOrderExperiment;

The following trajectory was simulated using these experimental conditions:

The trajectory terminates at 8 seconds because the simulator used the experiment annotation to determine how long to run the simulation.

Annotation Support

The experiment annotation is widely supported. But it is important to keep in mind that, in general, a tool is free to ignore any or all annotations.