Conditional equations and simulation time

Until now every equation in this series has been one formula that applies at every moment of a run: a rate times a state, a conductance times a temperature difference. Real systems are not always like that. A valve closes at a set time, a pump stops once a tank is empty, a heater switches on below a threshold. This page covers the two things an equation needs for that: knowing what time it is, and choosing between formulas.

The model is as small as it can be, so the behavior is easy to check by hand. A tank holds 10 units. It drains at 1 unit a second while its valve is open, and the valve closes at 5 seconds.

Time is a reference like any other

Every equation can refer to the simulation time. In an equation editor it appears among the Available references, next to the model's states and parameters, as t (time). Clicking it inserts the symbol. If a model already uses t for something else, time takes another letter instead, and the chip shows which.

To build the tank, add a node called Tank with one state, Level, starting at 10. Open the node and add a source term, which is an equation that belongs to one node and changes one of its states. Give the source term two parameters: Drain rate (drainRate, 1) and Valve closes at (closeTime, 5 seconds).

Choosing between formulas with cases

Switch the equation to LaTeX and write it as a cases block, the way a piecewise function is written on paper:

-\begin{cases}
  \mathrm{drainRate} & t < \mathrm{closeTime} \\
  0 & \text{otherwise}
\end{cases}

Read it top to bottom: the drain is drainRate while t is less than closeTime, and 0 otherwise. The leading minus turns a drain rate into a falling level. The Visual view shows the same equation typeset.

The rules are few, and the editor checks them as you type:

• The first condition that is true wins, and only that branch is evaluated. A branch that would divide by zero is safe as long as an earlier condition catches the case.
• The last branch must be otherwise, so that there is always a value.
• Conditions compare with <, \le, >, \ge, = and \ne, and join with \land (and), \lor (or) and \lnot (not). A chain such as 0 < x < 1 needs every neighboring pair to hold.
• A comparison is only allowed as a condition. It cannot stand in as a number anywhere else in the equation.

Conditions can read states as well as time. \begin{cases} \mathrm{rate} & \text{if } \mathrm{level} > 0 \\ 0 & \text{otherwise} \end{cases} drains at the full rate until the tank is empty, then stops, with no time involved.

Running it

Run the model for 10 seconds and open the tank's Results tab.

The level falls in a straight line from 10 to 5, then stays flat. Change Valve closes at and the knee in the plot moves with it. Make the parameter live and it can be changed during an online run or at a fork, as "Forking a run to try a what-if" shows, which turns "what if the valve closed earlier?" into a one-step experiment.

Setting a value instead of a rate

A source term's Sets field decides what the equation means. The default, The derivative, treats the result as a rate that is added to the state's other contributions and integrated. The value directly instead makes the equation compute the state's value itself at every step, with nothing integrated. This is for a quantity that is a function of other things, such as a price that follows time or a temperature set by a controller, rather than something that accumulates. The state then has to be set by that one equation alone, so no other source term or relationship may contribute to it, and the editor says so when you choose it.

Conditional equations and time work the same way in both cases, and in relationships between two nodes as well as in source terms. Exported code and FMUs carry them across, since they are part of the model and not the editor.

Where to go from here

"Writing a relationship in C++ or Python" covers what to do when a formula, even a conditional one, is not enough and a relationship needs real code.