A text-based language to define a simulation model
SCoP uses a text-based language to define a simulation model, its variables, and the numerical method(s) used to solve the model equations. The SCoP language is block oriented and there are two types of blocks: definition blocks for variables and constants and equation blocks to define the model structure. In addition, the language contains directives to specify numerical methods and other control actions. The format of the model file is mostly up to the user since there are only a few specific rules that must be followed. All symbols are delimited by “white space” (spaces, tabs, or end of line) except in lists, where they are delimited by commas. Devices such as indents, tabbed columns, and blank lines can thus be used freely to define a style that is easy to read and understand. All definition blocks must come first in the model source file before the equation blocks; within each group (definition and equation), the block order is arbitrary. All blocks are optional except where indicated. In the descriptions below, pairs of angle brackets and their contents (e.g. ) are to be replaced by strings or numbers supplied by the user. Square brackets indicate optional directives (except when they indicate array subscripts).
Variable Declaration Blocks
Names for variables and constants can be defined by the user according to the following rules:
- Names can contain from 1 to 20 characters. Generally, longer and more descriptive names are recommended to make model files easy to read. There are, however, some circumstances where compound names are constructed from variable names and extensions (e.g. submodels and sensitivity calculations). In these cases, shorter variable names are advisable to avoid compound names longer than 20 characters.
- The following characters are legal in names: upper and lower case alphabet, numerals 0 through 9, and the underbar. The first character in a name must be alphabetic. Cases are distinguished;
TotalNa is different from totalna, for example. Block names, directives, and other key words in SCoP are defined with all capital letters to help distinguish them from user-defined names.
- Reserved words defined in the SCoP language must not be redefined by the user. The list of reserved words is given in a later section and includes block names, directives, logical operations, and names of library functions.
PARAMETER
{
<variable_name> [= <value> (<units_string>)]
}
Defines parameters whose value can be changed within SCoP
and optionally assigns values and units.
A default value of zero is inserted if none is specified.
CONSTANT
{
<variable_name> [= <value> (<units_string>)]
}
Defines constants whose value cannot be changed within SCoP
and optionally assigns values and units.
A default value of zero is inserted if none is specified.
STEPPED
{
<variable_name> = <value_list> [(<units_string>)]
}
Defines a single constant that has a list of from two to five values in
its “value string”. Ordinary constants can be changed into
stepped constants at run time, but only one constant can be stepped at a
time.
INDEPENDENT
{
<name> FROM <value> TO <value> WITH <# breakpoints> [START <value>]
[(<units_string>)]
}
There must be exactly one INDEPENDENT block and one variable defined – no more and no less.As with state variables, a CONSTANT <name0> is created to hold the starting value,
set to the FROM value. An additional CONSTANT <delta_name> is also created as an increment for numerical solvers (e.g. a time step for integrators) and given a default value
equal to the spacing of the breakpoints. Another CONSTANT <maxerr> is created for specifying the error limit for integrators with automatic time step adjustment.
The FROM-TO values are used for the min and max of the scale when plotting the independent variable. Model solution begins with the independent variable set to the START value, if one is specified. If a START value is not specified, the independent variable begins with the FROM value. A SWEEP directive can be inserted in the INDEPENDENT block to change the effective independent variable; the SWEEP directive is described in a following section. Note that the minimum model file that produces a running SCoP program consists of one line: INDEPENDENT { t FROM 0 TO 1 WITH 1 }
STATE
{
<name> [FROM <number> TO <number> START <number> (<units_string>)]
}
Solvers in the SCoP library assign values to STATE variables so they should appear only in state equations (denoted with a tilde ~ at the beginning of the line) and on the right-hand side of other forms of equations. If <name> is followed by an integer in square brackets (e.g. <name>[n]), the line defines a vector variable containing n double-precision values, numbered from 0 to n-1.
Definitions of state variables may also appear within other blocks, where they are treated as local variables. The optional FROM-TO range is used only by the SCoP graphics routines to determine the plot scale when the state variable is selected for plotting, i.e. the range does not affect calculations. If a FROM-TO range is not supplied, default values of 0 and 1 are assumed. If the optional START (initial) value is not supplied, a default initial value of zero is supplied. Two additional variables are created to accompany each state variable: a CONSTANT <name0> for the initial value of <name> and an
ASSIGNED <Dname> for the derivative.
ASSIGNED
{
<name> [FROM <number> TO <number> (<units_string>)]
}
ASSIGNED variables have values calculated and assigned to them by appearing on the left-hand side of ordinary assignment statements (i.e. not state equations).
If <name> is followed by an integer in square brackets (e.g. <name>[n]), the line defines a vector variable containing n double-precision values. The optional FROM-TO range is used only by the SCoP graphics routines to determine the plot scale when the assigned variable is selected for plotting, i.e. the range does not affect calculations. If a FROM-TO range is not supplied, default values of 0 and 1 are assumed. Constants and variables may only be declared once; multiple declarations are considered to be an error.
Equation Block Definitions
Unless otherwise indicated, there may be multiple blocks of the following types. In the blocks below,
- Equations assigning values to assigned variables, of the form
<var_name> = <expression>
- Directive statements (listed below)
- Conditional sub-blocks
- Lists of statments enclosed in braces. This is functionally
equivalent to
IF (1) {...}
<expression> refers to a combination of variable and constant names,
literal constants, the arithmetic operators defined below, parentheses,
and function calls. SCoP expressions follow the rules used by most
computer languages; for specifics, refer to a description of the C language.
INITIAL
{
<statement list>
}
The optional INITIAL block is run once at the beginning of each simulation run. All state variables are automatically assigned initial values supplied in their definitions, but these default values can be superceded or other one-time calculations carried out by statements in an INITIAL block. If multiple INITIAL blocks exist, their contents are concatenated.
BREAKPOINT
{
<statement list>
}
This is the main block specifying model calculations. Statements within the BREAKPOINT block are executed once for each output breakpoint. Typical statements appearing in the BREAKPOINT block are SOLVE directives, conditional sub-blocks, and assignment statements for assigned variables.
TERMINAL
{
<statement list>
}
Statements in the optional TERMINAL block may be executed once at the end of asimulation run through a selection in the End-Run menu of SCoP.
LINEAR <block_name>
{
[ <statement list> ]
~ <expression> = <expression>
[ <statement list> ]
}
A LINEAR block contains linear algebraic equations for state variables, i.e. each <expression> is made up of a sum of terms containing no more than one state variable as a multiplier. Equations marked by the tilde (~) in the LINEAR block are parsed so that
state variables to be solved for can appear on either or both sides of such equations.
Additional terms can be added to either side of a state variable equation in a LINEAR block by following the equation line with a statement of the form
~+ <expression> = <expression>
The expressions on either side of the equal sign are added to their respective sides of the preceeding state equation. Assignments and equations can be mixed in any order and also occur in
conditional sub-blocks. Each LINEAR block must be accompanied by a SOLVE directive in some other
block, usually an EQUATION block. Solvers require the number of independent equations in a LINEAR block to be equal to the number of state variables solved for.
NONLINEAR <block_name>
{
[ <statement list> ]
~ <expression> = <expression>
[ <statement list> ]
}
A NONLINEAR block contains nonlinear algebraic equations for state variables.
Equations marked by the tilde in the NONLINEAR block are parsed so that
state variables to be solved for can appear on either or both sides of
such equations.
Additional terms can be added to either side of a state variable equation in a NONLINEAR block by following the equation line with a statement of the form
~+ <expression> = <expression>
The expressions on either side of the equal sign are added to their respective sides of the preceeding state equation. Each NONLINEAR block must be accompanied by a SOLVE directive in the EQUATION block.
Solvers require the number of independent equations in a NONLINEAR block to be equal to the number of state variables to be solved for.
DERIVATIVE <block_name>
{
[ <statement list> ]
var’ = <expression>
[ <statement list> ]
}
A DERIVATIVE block defines a group of ordinary differential equations to be solved together by the same numerical method and with the same time step. The numerical solvers in the SCoP library are designed for sets of first order differential equations. Higher order equations may be included, however; SCoP reduces these to sets of first order equations by creating the state variables and equations for lower derivatives. Higher order derivatives are indicated by repeating the single
prime symbol: is the second derivative, the third derivative, etc. (i.e. do not use the double prime symbol).
Each differential equation must be rearranged to isolate the highest derivative on the left-hand side of the equals sign with all other terms and factors moved to the right-hand side.
As indicated in the standard form above, ordinary assignment statements may be included in DERIVATIVE blocks, before or after or mixed in with differential equations. Nonlinear algebraic equations may also be included (marked with a tilde as in the NONLINEAR block) and will be solved along with the differential equations. Initial conditions for the state variables in DERIVATIVE blocks can be supplied by any one of four methods:
- Starting values can be included with the declaration of the state variables by adding
START <value> after the FROM-TO range in the STATE block. For a variable named y SCoP creates a constant named y0 for this starting value.
- The constant y0 can be declared in the CONSTANT block,
along with its value, by the user.
- If neither of the preceeding two methods are utilized, SCoP will
still create the constant y0 automatically and give it a value
of zero. This value can be changed interactively at run time.
- The INITIAL block can also be used to assign a value to y0.
This method is most often used when calculations are
necessary to arrive at the starting value.
Each DERIVATIVE block must be accompanied by a SOLVE directive in the EQUATION block.
PARTIAL <block_name>
{
[ <statement list> ]
~ var’ = f_val * DEL2(var) + g_val
[ <boundary conditions> ]
[ <statement list> ]
}
The PARTIAL block defines a parabolic partial differential equation, i.e. a partial differential equation with a first-order time derivative term and a second-order space derivative term (no mixed derivative term or first-order space derivative term). var, f_val, and g_val are vector variables of equal length. f_val and g_val contain the coefficients in the partial differential equation. A boundary condition on the state variable or its derivative must be supplied at each spatial limit. The default boundary conditions are zero spatial derivatives at both limits. Explicit boundary conditions are indicated by one of the following forms,
~ var[<limit>] = <expression>
for values of the state variable itself (Dirichlet or first kind) or
~ DEL var[<limit>] = <expression>
for values of the derivative (Neumann or second kind).
In either of these forms, <limit> takes on one of the values FIRST
(equivalent to x = 0) or LAST.
Each PARTIAL block must be accompanied by a matching SOLVE directive in the EQUATION block.
DISCRETE <block_name>
{
[ <statement list> ]
var1 = f(var1@1,var1@2,…,var2@1,…)
[ <statement list> ]
}
A DISCRETE block defines a group of discrete equations, where the current value of var1 is a function of variables at previous time steps. <var@n> is the stored value of <var> at the end of the nth previous step (var@0 is not allowed).
Histories of each variable in a DISCRETE block are automatically maintained for the required number of time steps. Variables used in DISCRETE equations must be declared as state variables
and may be vector variables as well.
Each DISCRETE block must be accompanied by a matching SOLVE directive in the EQUATION block.
KINETIC <block_name>
{
[<statement list>]
~ <stoic> <var> [ + …] <-> … (kf, kr)
[<statement list>]
}
A KINETIC block contains a set of equations describing reactions of the chemical reaction type.
On each side of the double arrow <-> in a reaction is a sum of terms consisting of
an optional stoichiometric number (small integer) multiplying any type of SCoP variable (CONSTANT, ASSIGNED, STATE, INDEPENDENT, STEPPED, or SWEEP). The space between the number and the variable is optional. f_flux and b_flux following each reaction (kf and kr)
are forward and reverse rate coefficients for the reaction and can be arbitrary expressions.
The effect of any type of variable other than a state variable is to multiply one of the rate coefficients by the variable raised to the power of its stoichiometric number.
If the variable appears on the left-hand side of the reaction, it multiplies the forward rate coefficient and if it is on the right-hand side it multiplies the reverse rate coefficient.
Three additional types of equations are also possible in KINETIC blocks.
~ <var> -> (<rate expression>)
represents a flux out of a state with the specified rate coefficient.
~ <var> << (<flux expression>)
represents a flux into a state.
CONSERVE <state expression> = <constant expression>
represents a form of algebraic equation (such as a conservation law) that is solved with the equations from the specified reactions. Each CONSERVE equation added to a KINETIC block results in the deletion of an appropriate equation from the reaction set (to keep the total number of equations constant for the numerical solvers).
<state expression> must be a linear equation in the KINETIC state variables.
Reactions in a KINETIC block are transformed into ordinary differential equations for the state variables that can be integrated via a SOLVE directive in the EQUATION block.
Solvers require that the number of state equations in a KINETIC block be equal to the number of state variables in the block.
Immediately following each reaction equation, the variables f_flux and b_flux contain the unidirectional fluxes of the reaction from left to right (“forward”) and right to left (“backward”), respectively. If these flux values are needed, they must be stored by the user before the next reaction equation since the same variables are used for all reaction equations.
PROCEDURE <proc_name> [(<argument list>)]
{
<statement list>
}
A PROCEDURE block defines a subroutine of user-written code to be called elsewhere in the file. A PROCEDURE block is called in the manner of a subroutine call in C, i.e. by giving the PROCEDURE name with a matching list of arguments. Note that arguments are passed by value only, so that numerical results can be returned only in global variables. PROCEDURE blocks do not return values.
FUNCTION <func_name> [(<argument list>)]
{
<statement list>
<func_name> = <expression>
}
A FUNCTION block contains user-written code producing a double-precision numeric result. A FUNCTION block is used in the manner of a function in C, i.e. by naming the FUNCTION with its matching list of
arguments in an expression. Note that arguments are passed by value only. As in C, the FUNCTION block must contain at least one statement assigning a value to <func_name>.
COMMENT
<text>
ENDCOMMENT
Text in a COMMENT block is ignored and does not contribute to model equations. Any text on a line following a colon is also treated as a comment and ignored.
VERBATIM
<C code>
ENDVERBATIM
The VERBATIM block permits C code to be inserted anywhere in model calculations without modification by the SCoP preprocessor.
Conditional Sub-blocks
As in C, conditional sub-blocks may be nested. Note that unlike the C language, the curly braces are not optional in conditional sub-blocks in SCoP and must be used even if they surround only a single statement.
IF [<unary_logical_operator>] <expression>
[<binary_logical_operator> <expression>]
{
<statement list>
}
[ELSE
{
<statement list>
}]
WHILE [<unary_logical_operator>] <expression>
[<binary_logical_operator> <expression>]
{
<statement list>
}
FROM <index> = <expression> TO <expression> [BY <positive increment>]
{
<statement list>
}
|
