Q: How do I implement time-dependent conditionals?

A: Conditional statements traditionally provide a mechanism for switching an execution path or the value assigned to one or more variables. In many programming languages the conditional takes the form of an if statement. In SAAM II, the conditional is combined with the syntax for a general assignment statement like:

This acts like a switch such that the first value is assigned to x if the condition is true, and the second value is assigned to x if it’s false.

In SAAM II there are two types of conditionals defined as explicit and implicit. An explicit conditional is one where the time during the experiment at which the switching action is to take place can be predicted in advance. An implicit conditional is one where the time is unknown until the condition itself is evaluated. An example of each type would be:

In the explicit case, the application can predict in advance that the value of x will change at time t= 10.0. In the implicit case, however, there is no way to predict in advance when the value of q1 will be less than q2. This distinction is critically important in the SAAM II Compartmental application because of the integration that occurs during a Solve or Fit. In order for the integrator to calculate correct results, the function upon which it is operating must be both differentiable and continuous. Discontinuities within an experiment are acceptable if the time at which they occur is known in advance so that the integrator can be reset and restarted. For this reason, implicit conditionals are not allowed in the Compartmental application.

Explicit conditionals are allowed in the Compartmental application, but are implemented as Change Conditions to provide ease of entry and added flexibility. In a Change Condition, the time or times at which the change is to be active are specified along with an equation, such as x = 1.0. This equation remains active for the duration of the specified time period (see the SAAM II User Guide for more information on Change Conditions).

There are no Change Conditions in the Numerical application, but the explicit form of the if statement is allowed. The conditional within the statement may only contain the independent variable (usually time). The explicit example shown above would be permitted in the Numerical application.

There is workaround for the implicit conditional problem, however, that involves using an approximation for the switch that is both continuous and differentiable, known as a Heaviside function. One approximation uses the normalized arctangent (one of the built-in functions of SAAM II):

In this implementation the (x - xlag) expression acts as the switch. When it’s positive, the value of heaviside will be approximately 1.0; when it’s negative, heaviside will be approximately 0.0. Lambda controls the sharpness of the value of heaviside, i.e. how quickly the value switches, and how closely to 1.0 and 0.0 that values become. Lambda should be tuned during each use to work best with the magnitude of (x - xlag).

This approximation can be used in SAAM II in the following manner:

When (x - xlag) is positive, the value of heaviside will be approximately 1.0, and y will be set equal to expression1. When (x - xlag) becomes negative, the value of heaviside will become approximately 0.0, and y will be set equal to expression2. Expression1 and expression2 can be a single value or an expression like (q1 / vol).

Figure 1

As an example, supposing the exogenous input in the model in Figure 1 is an infusion of magnitude 5000.0 that is active throughout the experiment, but it must be turned on or off in order to maintain the concentration in compartment q1 at a value of 1.0e5. There is no way of predicting in advance when and how many times this will occur. To implement this switch, write the following equations in the Equations window:

In this example, condition will be positive, heaviside will be approximately 1.0, and input will be 5000.0 whenever q1 is less than 1.0e5. Note that the second part of the approximation containing expression2 is not required in this case since the value for the infusion input will be 0.0 (off) whenever q1 exceeds 1.0e5. The only remaining task is to open the Exogenous Input box and create the infusion by selecting the Input Type equation, setting the duration to the entire experiment, and entering the equation as ex1 = input. 

When the model is solved, the contents of q1 will increase to 1.0e5, and then the infusion will switch on and off several times to maintain the concentration in q1 at approximately that level. A sample output is shown in Figure 2.

Figure 2

This type of approximation can be safely used anywhere within SAAM II when a conditional switch is required.

As an aside, the SAAM II if statement shown at the top is fully implemented in both the Compartmental and Numerical applications but its full functionality is turned off to prevent it from being used improperly in implicit cases where it will work but will produce incorrect results.

<< Back to Support Page