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. <name>
) are to be replaced by strings or numbers
supplied by the user.
Square brackets indicate optional directives (except when they
indicate array subscripts).
Names for variables and constants can be defined by the user according to the following rules:
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.
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.
Unless otherwise indicated, there may be multiple blocks of the
following types.
In the blocks below, <statement list>
denotes an arbitrary
number of statements including
<var_name> = <expression>
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 a simulation 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: $y\text{'}\hspace{0.17em}\text{'}$ is the second derivative, $y\text{'}\hspace{0.17em}\text{'}\hspace{0.17em}\text{'}$ 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:
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.
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.
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> }
TITLE <title string>
Text from the first non-blank character to the end of the line is used as
the name of the model in SCoP displays. Subsequent TITLE lines are
ignored. If there is no TITLE line, the name of the model is an empty
string. Two characters that might be used in TITLE lines receive special
treatments in C and have to be preceeded by a backslash: the double quote
must be entered as \"
and the backslash must be written as
\\
.
DEFINE <string> <integer>
This directive defines a macro for replacement prior to processing.
SWEEP <var> FROM <value> TO <value> WITH <# breakpoints> [(<units_string>)]
This directive is used inside the INDEPENDENT block to change the
effective independent variable.
When this directive is used, the solver generates a solution to the final
value of the independent variable for each value of the SWEEP variable.
LOCAL <variable list>
This directive defines double-precision variables for use only within the
block containing the directive. LOCAL variables do not appear in the
variable file. The LOCAL directive must always be the first thing in a block.
LOCAL directives not enclosed in a block declare variables that can be
used in any block, but do not appear in the variable file.
SOLVE <block_name> [METHOD <method_name>]
SOLVE directives accompany equation blocks of types requiring numerical
solution: LINEAR, NONLINEAR, DERIVATIVE, KINETIC, PARTIAL. Each type has
a default solution method that is used if the METHOD is not specified.
SOLVE directives normally appear in the EQUATION block.
RESET
This directive re-initializes multi-step integrators to handle
discontinuities in the derivative functions.
At a discontinuity (e.g. the application of a step as a driving function)
the previous history of the solution is no longer a good indicator of the
future behavior of the solution and the numerical method must be
restarted.
The RESET directive should be used in some kind of logical structure to
determine when it is to be executed.
PLOT <vert_var_list> VS <horiz_var_name>
The PLOT directive sets up the initial choices of variables to be plotted
on the horizontal and vertical axes in the graphic mode or displayed in
columns in the tabular mode. <vert_var_list>
can be either a
single variable or a list of up to five variables, separated by commas.
The selections in the PLOT directive can be overridden by the user at
run time from the Output Format Menu. If there is no PLOT directive,
SCoP uses as default selections the independent variable for the
horizontal axis and the first state variable for the vertical axis.
Single elements of vector variables may be used as variable names, e.g.
V[5]
.
If the name of a vector variable is used without a specific index value
(e.g. V where V is a vertor variable), the default selection is
V[size]
.
This form is used to call for the special plot of one vector variable
against another of the same length.
SENS <parameter list>
Generates one call to the sensitivity equations
evaluation function for each parameter in the list and can be used
within the LINEAR, NONLINEAR, DERIVATIVE, and KINETIC blocks.
Note that SENS can, at present, only be used with the non-default
integrators in the KINETIC block. SENS also creates
the following additional variables for each parameter in the list:
S_<state>_<param>
State variable for the parameter variations
DS_<state>_<param>
Derivative for the state variable if a
trajectory sensitivity is being calculated.
U_<parameter>
The relative uncertainty of the parameter value
(default = 0.05)
EP_<state>_<parameter>
Envelope for positive parameter uncertainty
EM_<state>_<parameter>
Envelope for negative parameter uncertainty
<expression> = <expression>
to the last LINEAR or NONLINEAR
state equation defined. Note that if one expression is 0,
only one side of the equation is changed.
^
Exponentiation
Note that these logical operators are in the style of the C language for consistency with VERBATIM blocks.
acos | fmod | revhyperbol |
asin | force | revsawtooth |
ASSIGNED | FROM | revsigmoid |
atan | FUNCTION | sawtooth |
atan2 | gauss | SENS |
b_flux | harmonic | set_seed |
BY | hyperbol | sigmoid |
ceil | IF | sin |
COMMENT | INDEPENDENT | sinh |
CONSERVE | INITIAL | SOLVE |
CONSTANT | KINETIC | spline |
cos | lag | squarewave |
cosh | LINEAR | sqrt |
DEFINE | LOCAL | START |
deflate | log | STATE |
DEL | log10 | step |
DERIVATIVE | maxerror | STEPPED |
derivs | METHOD | SWEEP |
DISCRETE | NONLINEAR | tan |
ELSE | normrand | tanh |
ENDCOMMENT | PARTIAL | TERMINAL |
ENDVERBATIM | perpulse | threshold |
EQUATION | perstep | TITLE |
erf | PLOT | TO |
exp | poisrand | VERBATIM |
expfit | poisson | VS |
exprand | pow | WHILE |
f_flux | prterr | WITH |
fabs | pulse | |
factorial | ramp | |
floor | random | |
RESET |
The functions described here are intrinsic (built-in) functions which are provided by the C language math library. These functions may be utilized in the equations the modeler uses to describe his SCoP model. For each function, we provide a synopsis describing the function, the arguments it expects, and the value which it returns. With the exception of abs(), all of these functions return double-precision floating point values and expect arguments which are double-precision floating point values.
Many of the functions which make up the SCoP library are used by SCoP internally and are of no direct interest to the user. However, there are some functions which the SCoP library provides which are of a more general nature and which may be utilized by the user's model.
"This is another fine mess\n"
). prterr() then prints
that message on the screen, followed by this prompt to the user:
Press <Enter> to continue
and waits until the user presses the <Enter> key (also sometimes referred to as Return, <CR>, or $$, it is the carriage return key for the terminal, PC or workstation in use).
Return Value: None
Return Value:
Inputs:
Return Value:
"FORFUNC.DAT"
). (Remember that the backslash \
is an
escape character in C strings and thus must be preceeded by a second
backslash if used in directory names in the DOS operating system.)
The first argument $t$ is the value of the test
variable at which the (interpolated) value of the forcing function is
requested (Note: force() calls derivs() and spline() as
necessary to accomplish the interpolation).
Return Value:
Inputs:
Return Value:
Inputs:
"C:\MODEL\REFDATA.DAT"
)
Return Value:
nexp = expfit(terms, reffile, amplitude, lambda, error);then the resulting function is:
$y\; =\; amplitude[0]*exp(lambda[0])*t)\; +\; \&ldots;+\; amplitude[terms-1]*exp(lambda[terms-1]*t)$
if $terms\; >\; 0$, and$y\; =\; amplitude[0]*exp(lambda[0])*t)\; +\; \&ldots;+\; amplitude[nexp-1]*exp(lambda[nexp-1]*t)$
if $terms\; <\; 0$ ($nexp\; \le terms$).
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
$erf(z)\; =\; \{2\pi \}\; \int $_{0}^{z}
Return Value:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Inputs:
Return Value:
Return Value:
Return Value:
Inputs:
Return Value: None