SCoP Language Summary

A text-based language to define a simulation model

Directive Definitions

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

Operators

~

Introduces linear equations, nonlinear equations, kinetic reactions, and partial differential equations.

~+

Add the following equation of the form <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.

@n

Postfix operator (n is an integer) creates a local variable for the value of the previous variable n steps earlier

:

Introduces in-line comment

Arithmetic Operators (infix)

+

Addition

–

Subtraction

*

Multiplication

/

Division

^ Exponentiation

Logical Operators (infix except for NOT)

Note that these logical operators are in the style of the C language for consistency with VERBATIM blocks.

&&

Logical “and”

$||$

Logical “inclusive or”

!

Logical “not” (prefix)

==

Logical equality test

!=

Logical “not equals”

>

Greater than

<

Less than

>=

Greater than or equals

<=

Less than or equals

Reserved Words

C Math Library Functions

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.

acos(x) – compute the arc cosine
: Returns the arc cosine of its argument ($arccosx$). The argument must be in the range -1.0 to 1.0.

asin(x) – compute the arc sine
: Returns the arc sine of its argument ($arcsinx$). The argument must be in the range -1.0 to 1.0.

atan(x) – compute the arc tangent
: Returns the arc tangent of its argument ($arctanx$).

atan2(y,x) – compute the arc tangent of y/x
: Returns the arc tangent of the ratio $y/x$ ($arctany/x$).

ceil(x) – round upwards
: Returns the smallest integral value greater than or equal to its argument ($x$).

cos(x) – compute the cosine
: Returns the cosine of its argument ($cosx$). The angle is expressed in radians.

cosh(x) – compute the hyperbolic cosine
: Returns the hyperbolic cosine for a real argument ($coshx$).

exp(x) – compute the exponential function
: Returns the value of $e$ raised to the argument power ($ex$).

fabs(x) – compute the absolute value of a floating point number
: Returns the absolute value of its argument ($|x|$).

floor(x) – round downwards
: Returns the largest integral value less than or equal to its argument ($x$).

fmod(x,y) – compute x modulo y
: Returns the value of $x$ modulo $y$ ($x\; y$), the remainder resulting from $x/y$.

log(x) – compute the natural logarithm
: Returns the natural logarithm of its argument ($lnx$).

log10(x) – compute the base 10 logarithm
: Returns the base 10 logarithm of its argument ($log$₁₀ x).

pow(x,y) – compute x raised to the y power
: Returns the value of $x$ raised to the power of $y$ ($xy$).

sin(x) – compute the sine
: Returns the sine of its argument ($sinx$). The angle is expressed in radians.

sinh(x) – compute the hyperbolic sine
: Returns the hyperbolic sine for a real argument ($sinhx$).

sqrt(x) – compute the square root
: Returns the positive square root of its argument ($x$).

tan(x) – compute the tangent
: Returns the tangent of its argument ($tanx$). The angle is expressed in radians.

tanh(x) – compute the hyperbolic tangent
: Returns the hyperbolic tangent for a real argument ($tanhx$).

SCoP Library Functions

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.

Program Interaction Functions

prterr(message_string) – print message and wait
: Takes a single argument which is a message string (e.g. $message\_string$ might be "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

Curve-fitting and Interpolation Functions

derivs(nbase, x, y, mesh, der) – compute second derivatives
: This function computes the second derivatives at the base points for cubic spline interpolation. This function is called once prior to calling spline() for each interpolation (see spline() below). Inputs:
$nbase$
number of base points (an integer)
$x$
vector of X values at the base points (vector of double-precision floating point values)
$y$
vector of Y values at the base points (vector of double-precision floating point values)
Outputs:
$mesh$
vector containing base point spacing (vector of double-precision floating point values)
$der$
vector containing the second derivatives of the base points (vector of double-precision floating point values)
Return Value:
• derivs() returns an integer which is 0 on success, and 1 if tridiagonal matrix is singular or ill-conditioned.

spline(nbase, x, y, mesh, der, x_inter) – compute cubic spline
: This function evaluates the cubic spline at the point for which an interpolation is desired. Call this function once for each interpolation to be performed (Note: the function derivs() (see above) must be called prior to calling spline() for each interpolation).
Inputs:
$nbase$
number of base points (an integer)
$x$
vector of X values at the base points (vector of double-precision floating point values)
$y$
vector of Y values at the base points (vector of double-precision floating point values)
$mesh$
vector containing base point spacing (vector of double-precision floating point values)
$der$
vector containing the second derivatives of the base points (vector of double-precision floating point values)
$x\_inter$
value at which interpolation is desired (a double-precision floating point value)
Return Value:
• spline() returns the value of the cubic spline at the requested point (a double-precision floating point value).

force(t, filename) – generalized forcing function
: This function reads a file containing the coordinates of a forcing function in reference data file format. The argument $filename$ is a string containing the name of the file to be read (e.g. $filename$ might be "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:
• force() returns the requested value of the (interpolated) forcing function (a double-precision floating point value).

deflate(degree, coeff, root) – compute roots of a polynomial
: This function finds the real roots of a polynomial with real coefficients by Newtonian deflation.
Inputs:
$degree$
degree of the polynomial (an integer value)
coeff
vector of real coefficients of the polynomial (vector of double-precision floating point values)
Outputs:
$root$
vector of real roots of the polynomial (vector of double-precision floating point values)
Return Value:
• deflate() returns the number of real roots found (an integer value).

expfit(terms, reffile, amplitude, lambda, error) – exponential fit
: This function performs a fit to reference data using Handscomb’s modification to Prony’s method for exponential curve peeling. Only the real poles are found. The data must be sampled at even intervals and stored in reference data file format. Up to 201 data points are allowed.
Inputs:
$terms$
maximum number of terms to try to fit (an integer value). If , discard exponentials with amplitudes .
reffile
a string containing the name of the file to be read (e.g. reffile might be "C:\MODEL\REFDATA.DAT")
Outputs:
$amplitude$
vector of pre-exponential coefficients (vector of double-precision floating point values)
$lambda$
vector of time constants (vector of double-precision floating point values)
$error$
standard error of estimate (a double-precision floating point value). Set to -1 if $terms\; >\; 0$
Return Value:
• expfit() returns the number of exponentials in the fit to the data (an integer value).

      nexp = expfit(terms, reffile, amplitude, lambda, error);