The CalC ("Calcium Calculator") Reference Manual

Length: [l] = µm
Time: [t] = ms
Concentration: [c] = µM
Current: [I] = 2 e [c] [l]³ / [t] = 2 e 10^-21 moles / ms,
where "2 e" is the charge of a Ca²⁺ ion.
Current can also be specified in pA using the built-in constant pA = 5.182134 [I].

Units for other quantities are derived from the above; for example, units for the diffusion coefficient are [l]²/[t] = µm²/ms
Of course, one is free to use a different choice of units; in that case one should ignore the unit symbols prompted by the program in various text messages.

Δ General syntax

A script file can import another script file using command include file_name. The script file_name will be inserted at the point where the include command appears. One may also use a string variable as a file name, if it is defined earlier in the file, i.e.:
script = path "/script"
include script
Command-line arguments passed to CalC are accessible within the script; the n-th argument is denoted $n (note that the 1st argument is the script file name itself).
Definition language is Case-Sensitive.
Comment character is "%": % this is a comment
Semicolon (";") separates statements that follow one another on the same line:
grid 20 20 20 ; stretch.factor = 1.07
To continue a definition on another line, put a line continuation string "..." at the end of the previous line:
Ca.bc Neumann Neumann Neumann Neumann ... Pump Pump
A parameter name can be used wherever a numerical value is expected:
grid N N N ; N = 40
A constant numerical expression may be used for defining any parameter, i.e. grid N M M ; N = 2 * M ; M = 10
If a parameter or construct is defined multiple times within the script, only the first definition will be used.
Parameter definitions may appear in arbitrary order throughout the script, unless the conditional if .. then .. else .. endif statement is used, in which case the order of appearance of definitions is arbitrary within each of the then .. else/endif and else .. endif blocks. The only exception are Run and current statements which specify the simulation runs themselves and are executed in the order of their appearance.
Non-trivial program flow can only be arranged via combined use of the for loop statement, the conditional "if" .. "then" .. "else" .. "endif" statement, the "include" statement and the "print/append" statements (see the description of the "if" statement).
Parameter/identifier names can include all kinds of special characters, if the names are enclosed in quotes: "Ca\s0\N\S2+\N" = 0.1 (this creates an xmgr-friendly name with a subscript and a superscript).

Δ Mathematical expression syntax

A space between two numerical values implies multiplication:
x = 20 exp( y ) is equivalent to x = 20 * exp( y )
The following functions can be used in numerical expressions:
sinh, cosh, tanh, sin, cos, tan, atan, exp, log, log10, sqr, cube, sqrt, theta, sigma (sigma(x) = ( 1 + tanh(x) )/2 ), int (integer part of float), not (logical negation)
Time variable is "t" (to be used only in time-dependent variable definitions - see below).
Operator execution priorities:
Operators are executed in the same order as in the C programming language. Below all operators are listed according to their execution order, from highest to lowest:

Unary boolean not operator:
!
Binary exponentiation operator:

^

Unary sign operator:
-
Binary arithmetic operators:

* / mod

+ -

Binary logical operators:

< <= > >=

== (equal) != (not equal)

and

or
Boolean operations: logical operations evaluate to 1 if true, and to 0 if false. An argument of a logical operator is considered true if greater than zero, and false otherwise. Logical operators include the binary operators from the table above, and the not( ) function. The primary use of logical expressions is in the "if" conditional statement, but they may also be used in other expressions:

F := 2 * (t > 1.0) + (t <= 1.0)
- defines a function of time equal to 1.0 when simulation time is less than 1.0 ms, and equal to 2.0 otherwise.
Constant arrays may be defined, using a space-separated list; the 1st entry index is "0" (as in C):
Data = 1.2 0.9 0.8 1.1 1.3 1.5 % defines the array
entry = Data{3} % getting the 4th element (Data{3} = 1.1)
The curly-bracket references can also be used to extract arguments of a compound definition, such as the grid definition. Example:
grid 20 40 30
gridString = "The grid size is " grid{0} " by " grid{1} " by " grid{2} " points"

Δ Mathematical expressions may be used in the following definitions:

Constant (time-independent) expressions - evaluated before the simulation starts:

Parameter definitions: k = 20 / ( 1 + exp( 2.1 ) ) ; Ca.D = 0.5 * k + 0.02.
In the for loop index initialization: for I = a / 1000 to sqrt(x) step 0.5
In the preprocessor if statement clause: if log( x ) < b * exp( y ) then ...

In the latter two cases, the order of definitions is not completely arbitrary: the expressions in preprocessor for and if statements may only depend on parameters defined earlier in the script file.

Time-dependent definitions:

When defining an ODE: dV / dt = - V / tau_leak + IK + INa + Iapp
When defining an auxiliary time-dependent variable: Iapp := 0.2 pA ( 1 + tanh( t - 5 ) )
When specifying Ca channel current strength: current = 0.2 pA * sigma( 0.5 * ( t - 2 ) )
In "print" / "append" statements: print stderr "result=" Ca[0.1,0.1,0.1] / Ca.bgr - 1.0. The expression will only be computed once, at the end of the simulation.

Δ String expressions

A string is a sequence of characters in quotes (any quotes will do: either "..." or '...' or `...`; the closing quote must be the same as the opening quote):

string_variable = "@#$%^!"

To include quote characters in a string, mix-and-match quote types: doubleQuote = '"'
Any string label/name (for instance, a file name) can be defined as a concatenation of several substrings:

string = token1 token2 ...

where token1, token2, ... are either strings or numerical expressions. The latter will be evaluated and their values converted to strings. Example:

param = 4
fileName = "var." 2 * param
plot mute var fileName

The time dependence of a user-defined variable "var" will be saved in file "var.8". This feature is particularly useful when running a for loop over a parameter value.

There is a side-effect of this free-form mixing of string and numerical expressions: if a string expression matches a variable name, it will be interpreted as a variable. In the above example, string defined as fileName = "var." "param" is equal to var.4, not var.param.

Δ Implemented Geometries

Although the description of various definition commands that follow below assume a 3D model in cartesian coordinates (the default geometry), various lower-dimensional geometries have also been implemented. To specify the model geometry, use the command

geometry = geometry_name

where the geometry_name is a geometry label that assumes one of the string values listed in the table below:

`Dimensionality`	`Geometry label`	`Axis labels`	`Geometry description`
`1D`	cartesian.1D	x	1D model: diffusion along a line
	disc	r	Diffusion inside a disc: rotationally symmetric 2D geometry
	spherical	r	Fully spherically symmetric 3D geometry
`2D`	cartesian.2D	x y	2D model in cartesian coordinates
	cylindrical	r z	3D model in cylindrical coordinates
	conical	r theta	Model in spherical coordinates, symmetric with respect to phi azimuth angle
`3D`	cartesian.3D default	x y z	Full 3D model in cartesian coordinates
`3D`	spherical.3D not yet implemented	r theta phi	Full 3D model in spherical coordinates

When using any of the lower-dimensionality geometries listed above, the argument lists of many of the definition instructions described below should be shortened. Additionally, some commands (e.g., plot and axis stretch instructions) use axis labels as arguments, which assume different string values depending on the geometry, as listed in the above table. Below is an example comparing some of the statements for the full 3D geometry in cartesian coordinates (geometry = cartesian.3D), and the reduced rotationally-symmetric geometry in conical and spherical coordinates:

geometry = cartesian.3D	geometry = conical	geometry = spherical
`volume 0 1 0 1 0 1`	`volume 0 1 0 1.57`	`volume 0 1`
`grid 30 30 30`	`grid 30 30`	`grid 30`
`stretch x 0 0.1`	`stretch r 0 0.1`	`stretch r 0 0.1`
`stretch y 0 0.1`	`stretch theta 0 0.1`
`stretch x 0 0.1`
`Ca.source 0 0 0`	`Ca.source 0 0`	`Ca.source 0`
`plot point Ca[0.2,0,0]`	`plot point Ca[0.2,0]`	`plot point Ca[0.2]`
`plot 1D Ca x 0 0`	`plot 1D Ca r 0`	`plot 1D Ca`
`plot 2D Ca z 0.2`	`plot 2D Ca`

Few special geometry cases (spherical, cylindrical and conical) are described in more detail below, as an example.

Δ Spherically-symmetric geometry

When the geometry is spherically symmetric, the 3D problem reduces to a 1D problem in spherical coordinates. Examples are: a source in the center of a sphere, or a current uniformly distributed over the surface of a spherical cell. In this case it is much more efficient to solve the resulting one-dimensional problem. To do so, use the command

geometry = spherical

and only use two parameters when defining the volume:

volume R0 R1

where R0 and R1 are the inner and outer radii of the spherical shell that serves as the diffusion space in this case. Only two boundary conditions need to be defined, one for the inner and one for the outer surfaces of the shell.
Similarly, only two parameters specify the Ca current source:

Ca.source R dR

where "R" specifies the radius of the spherical surface over which the current is uniformly distributed (R=0 for a problem with a source in the center of a sphere), and "dR" specifies the width of the source current layer in radial direction.
All other commands also remain unchanged; wherever an axis name is needed, use "r", and omit the "y", "z" coordinates. For example, use stretch r rmin rmax to stretch the grid outside of the shell [rmin, rmax], use Ca[r] to access calcium concentration at distance r from the center, and plot 1D Ca to plot the calcium concentration as a function of distance from the center of the sphere.

Δ Cylindrical geometry

If the geometry of the problem is symmetric with respect to the azimuth angle phi in cylindrical coordinates, the 3D problem reduces to a 2D problem in coordinates r and z. To solve the corresponding 2D problem, include the command

geometry = cylindrical

and only use four parameters when defining the volume:

volume R0 R1 Z0 Z1

where R0 and R1 are the inner and outer radii of the volume, and Z0 and Z1 are the limiting z-values. Only four boundary conditions need to be defined. Similarly, only four parameters specify the Ca current source:

Ca.source R Z [ dR dZ weight ]

where R, Theta specify the location of the source, and optional parameters dR, dZ specify the spread of the source.
All other commands are also analogous to their 3D counterparts. Wherever an axis name is needed, use "r" for the radial coordinate, "z" for the 2nd coordinate. and omit the "z" coordinate. For example, use stretch z zmin zmax to stretch the grid outside of the domain [zmin, zmax], use Ca[r,z] to access calcium concentration at location {r, z}, use plot 1D Ca z r0 to plot the calcium concentration as a function of z, at a distance r0 from the center of the sphere.

Δ Conical geometry

If the geometry of the problem is symmetric with respect to the azimuth angle phi in spherical coordinates, the 3D problem reduces to a 2D problem in coordinates r and theta (e.g., see Klingauf and Neher (1997) Biophys J 72: 674). To solve the corresponding 2D problem, include the command

geometry = conical

and only use four parameters when defining the volume:

volume R0 R1 Theta0 Theta1

where R0 and R1 are the inner and outer radii of the volume, and Theta0 and Theta1 are the limiting angle values, in radian (0 < Theta0, Theta1 < pi). For Theta0=0, the volume is a cone.
Only four boundary conditions need to be defined. Similarly, only four parameters specify the Ca current source:

Ca.source R Theta [ dR dTheta weight ]

where R, Theta specify the location of the source, and optional parameters dR, dTheta specify the spread of the source.
All other commands are also analogous to their 3D counterparts. Wherever an axis name is needed, use "r" for the radial coordinate, "theta" for the angle coordinate, and omit the "z" coordinate. For example, use stretch theta thetamin thetamax to stretch the grid outside of the angle domain [thetamin, thetamax], use Ca[r,theta] to access calcium concentration at location {r, theta}, use plot 1D Ca theta r0 to plot the calcium concentration as a function of angle, at a distance r0 from the center of the sphere.

Δ Geometry definitions:

The simulation space volume can be composed of (is a union of) an arbitrary number of "boxes", each defined via keyword "volume", with an arbitrary number of obstacles (barriers to diffusion of calcium and buffers), each defined using keyword "obstacle". Calcium and buffer concentration fields are computed on a mesh of points, specified using keyword "grid", covering the entire diffusion space. The grid may be non-uniform.

volume xmin xmax ymin ymax zmin zmax

- defines a box spanning area {xmin < x < xmax, ymin < y < ymax, zmin < z < zmax}. All bounding coordinates should be in micrometers. If the diffusion space is composed of several boxes, several volume definitions should be included.

obstacle xmin xmax ymin ymax zmin zmax

- defines a diffusion obstacle spanning an area {xmin < x < xmax, ymin < y < ymax, zmin < z < zmax}
An arbitrary number of obstacle definitions may be used.

grid nx ny nz

- defines a nx by ny by nz grid. The number of points in each direction should be an odd integer; an even number will be increased by 1.

When using geometries with spatial dimensionality of 1 or 2, include only part of the argument list corresponding to the actual number of existing spatial directions.

Δ Non-uniform grid:

For the same number of grid points, the accuracy of the computation can be improved by increasing the density of grid point in the vicinity of calcium channel(s), where the concentration gradients are the greatest. If the channel array is enclosed within a region {xmin < x < xmax, ymin < y < ymax, zmin < z < zmax}, one should use:

stretch x xmin xmax
stretch y ymin ymax
stretch z zmin zmax

- each successive grid interval further away from the region {xmin < x < xmax, ymin < y < ymax, zmin < z < zmax} will be multiplied by a factor specified by stretch.factor, which should be slightly greater than 1.0: The grid may also be stretched along a single direction (x, y, or z) only.

stretch.factor = value

- sets the grid non-uniformity factor used by stretch. Recommended values for the factor value are between 1.05 and 1.2. Using larger values, while making the results converge faster with increasing grid dimensions (i.e. spatial resolution), will cause the results to converge to a slightly wrong answer (stretching the grid introduces an additional systematic computation error).

In cases when the grid is relatively coarse, it may be desirable to have a grid node pass through some special coordinate in space:

clamp x y z

- forces the closest grid node to assume coordinates [x,y,z]. Since this will change the neighboring grid spacings, this will distort the grid, so it's better to do without clamping, if possible.

The stretch command syntax is the same for spherical, disc, cylindrical and conical geometries, except that one may use, respectively, the direction labels "r", "r" and "z", or "r" and "theta", i.e.

stretch r rMin rMax
stretch theta angleMin angleMax

Δ Calcium and buffer definitions:

Definition of each Ca²⁺ property starts with a label Ca followed by a period, then followed by the property name:

Ca.bgr = expression

- defines the initial background calcium concentration (in units of µM)

Ca.D = expression

- defines the value of the calcium diffusion coefficient (in units of µm²/ms)

Buffer properties definitions have the same syntax. For example, definition of a diffusion coefficient of a buffer named Bf is Bf.D = expression

In order to define a diffusion coefficient which is non-uniform in space, use the command

Ca.tortuosity = f(x,y,z)

The diffusion coefficient of Ca²⁺ will be a product of a space-independent term defined by Ca.D and the space-dependent term defined by a user-specified function f(x,y,z) Example:

Ca.tortuosity = 1 - 0.5 exp( - 20 ( xx + yy + z*z ) )

- in this case the Ca²⁺ diffusion will be reduced in the vicinity of point x = y = z = 0.
Diffusion coefficient of a buffer can be modified the same way, for instance:

buffer Fura
Fura.tortuosity = 1 - 0.5 sigma( 50 (z - 0.2) )
Fura.D = 0.118
............

To define the same tortuosity function for Ca²⁺ and all the buffers, simply use

tortuosity = f(x,y,z) or all.tortuosity = f(x,y,z)

Non-uniform diffusion coefficient is currently only implemented in cartesian coordinates (1D, 2D and 3D). The tortuosity correction for spherical, disc, cylindrical and conical geometries are not yet implemented, but can be easily added upon request to the author.

Δ Boundary condition definitions:

By default, both calcium and buffers satisfy Neumann (i.e. reflective) boundary conditions at all surfaces of all geometry elements. However, boundary conditions may be specified by the user for each volume and obstacle composing the diffusion space:

Ca.bc bcxmin bcxmax bcymin bcymax bczmin bczmax

- specifies the boundary condition for each of the six surfaces of a volume element. Each of the labels bcxmin ... bczmax is either defined by the user via a bc.define instruction described below, or is one of the two predefined types, Neumann (i.e. reflective) or Dirichlet (zero concentration at the boundaries).

Ca.bc all bc_name

- use if calcium satisfies boundary condition of type "bc_name" at all six boundaries of the corresponding volume element.

bc.define bc_name a b c

- defines boundary condition bc_name with a, b and c satisfying:

a * d[Ca]_b / dn + b * [Ca]_b = c

where [Ca]_b is [Ca] at the boundary, and d[Ca]_b / dn is the gradient of [Ca] in the direction perpendicular to the boundary.

For instance, for simulating a uniform density of calcium pumps on the bottom and top ("zmin" and "zmax") surfaces of a volume, with pump rate P=50 µm/ms, assuming zero background [Ca] and calcium diffusion coefficient of D=223 µm²/ms, one should use:

bc.define Pump 1.0 -0.224 0.0 `% d[Ca]/dn = P/D[Ca]; P/D = 0.224/um`
Ca.bc Neumann Neumann Neumann Neumann Pump Pump

The Neumann and Dirichlet boundary condition types are defined internally using

bc.define Neumann 1 0 0
bc.define Dirichlet 0 1 0

Note that if the background rest concentration of calcium or buffer is non-zero, user has to provide his own definition for the Dirichlet boundary condition (using a different type label/name, since the bc's already defined may not be redefined).

If several volumes and/or obstacles are specified, the first several boundary condition definitions will correspond to volume definitions (in the order those were defined), and the later boundary condition definitions will correspond to the obstacles.

Δ Buffer definitions:

An arbitrary number of buffers can be included in the simulation, each defined using

buffer buffer_name

Values specified for calcium should also be specified for each of the buffers. However, instead of defining the background concentration for the buffer, it is usually more useful to define its total concentration, assumed to be homogeneously spread throughout the diffusion space. In this case the initial buffer concentration will be computed automatically assuming equilibrium with the defined background [Ca²⁺].

buffer Bfixed
Bfixed.D = 0.0
Bfixed.total = 2000
Bfixed.bc all Neumann `% (default setting)`

In addition, calcium binding kinetics should be specified for each of the buffers, by defining two of the following three parameters:

buffer_name.kplus = expression `% defines calcium binding rate, in 1/(ms uM)`
buffer_name.kminus = expression `% defines calcium unbinding rate, in 1/ms`
buffer_name.KD = expression `% defines calcium affinity of buffer (in uM): KD = kminus/kplus`

Δ Calcium channels:

An arbitrary number of calcium channels can be defined. For each, channel location and width of the spatial distribution of the current (which is of gaussian shape) need to be defined, using

Ca.source x y z `[` dx dy dz weight `]`

where the optional parameters dx, dy and dz specify the width of the source (square brackets indicate that parameters are optional; do not include them in the argument list!) The default value for the width parameters is zero, which corresponds to a point-like source. However, the point-like nature of calcium channels introduces a spatial singularity into the problem, degrading the performance of the numerical method. Therefore, to achieve high degree of numerical accuracy, one should set the width parameters so that the source covers at least 2-3 grid intervals. If only the "dx" parameter is defined, the source spread in all three directions is assumed to be the same.

The default parameter weight specifies the multiplier for the current magnitude, and is used when it is desirable to have different current strengths coming through different channels. The channel current will be then given by the product of weight and the current value defined by the command "current" (see section on simulation specification).

Channels can be located anywhere, either inside the simulation volume or on the boundary.

Δ Local concentration variable:

Local concentration of Ca²⁺ at some location {x,y,z} is accessed using the following time-dependent construct: Ca[x,y,z].

Buffer concentration at a given location can be accessed the same way, via variable buffer_name[x,y,z]. If the coordinate {x,y,z} does not coincide with any grid node locations, linear nearest-neighbor interpolation is used.

Δ Average concentration:

To monitor the average concentration of Ca²⁺, use the built-in variable Ca[]; analogously, the variable tracking average concentration of unbound buffer named buffer_name is buffer_name[].

Δ Current and Charge variables

Built-in time dependent variable ICa gives the current value of the total Ca²⁺ current entering the volume through all defined channels. Another predefined variable, Charge, gives the total Ca²⁺ charge that entered since the simulation start (it is defined via Charge = dICa / dt). The discrepancy between the value of the Charge variable and the actual integral of Ca²⁺ over the simulation volume is output at the end of each simulation, and can be accessed through the built-in variable Charge.loss. In the absence of pump boundary conditions (which would cause the charge to escape through the surface), this variable can be used as a simulation accuracy measure.

Δ Defining ODEs

To simulate binding of calcium to putative neurosecretory/facilitation sensors, corresponding system of differential equations (ODEs) has to be defined. A differential equation is defined using dvariable / dt = expression_for_derivative, for example

dR / dt = - koff R + kon Ca[0.0,0.0,0.1] ( 1 - R )

Alternatively, one may use the special character sequence "->" instead of the d/dt construct, i.e.:

R -> - koff R + kon Ca[0.0,0.0,0.1] ( 1 - R )

In the above, the construct Ca[x,y,z] denotes calcium concentration at point {x,y,z} (see above).

For each equation, initial boundary condition can be defined:

R(0) = 0.0

The default initial condition is zero.

Δ Finding the steady state of the ODE system

In order to integrate (see Run definition) the declared system of ODEs starting from a steady state, rather than from the initial conditions, include the command

equilibrate step_num accuracy initial_time_step

where step_num is the maximal number of equilibration steps, accuracy is the desired accuracy (for the zero derivative condition), and time_step is the initial equilibration time. Default values are step_num = 40000, accuracy = 1.0e-6 and initial_time_step = 1 ms.

Δ Time-dependent variables:

It may be necessary to introduce additional time-dependent variables that are functions of ODE variables; this is done using a command of the form "variable := expression", i.e.

dR / dt = - koff R + kon Ca[0.0,0.0,0.1] U `% same equation as before`
U := 1 - R `% variable denoting the unbound receptor`

Variables (and expressions for derivatives) may depend on time explicitly, through time variable "t"

There are two more user-defined time-dependent variable types, in addition to variables defined via "d /dt", ":=", "ICa"/"Charge", and "Ca[x,y,z]"/"Ca[]" (or "buffer_name[x,y,z]"/"buffer_name[]"). These are table and min (max) variables described below:

Δ Data table from a file:

A time-dependent variable can be defined using a two-column data file (satisfying the format "t_n f(t_n)", without a comma or other delimeter in between):

variable_name table file_name

Time points don't have to be regularly spaced; linear interpolation will be used to fill in for other time values.

This command may be useful in cases when one wants to change parameters of the calcium binding kinetics without having to re-calculate the time-course of calcium concentration. For instance, in the example script demo.par, one may save [Ca] evolution at the site x=y=z=30 nm, assigned to a variable named ca, using plot mute ca "ca.dat", and then run the ODE-only version of the script after including the command ca table "ca.dat". Since at this second step only the ODEs corresponding to the calcium binding scheme have to be re-calculated, one should also include the mode = ODE command.

Δ Tracking extremum of a variable:

To obtain the maximum of a variable var on an interval [T1,T2], use

`[` time_var_name `]` max_var_name max var T1 T2

where max_var_name is the name of the variable tracking the maximum of var, and time_var_name (optional) specifies the name of the variable that will contain the time value at which the maximum of var is achieved.
Although one is only interested in the value of max_var_name once the time point T2 is reached, CalC treats max_var_name as a time-dependent variable, so usual plotting routines may be used to monitor max_var_name.

This object is particularly useful in modeling synaptic facilitation, where one is interested in the peak value of [Ca²⁺], or a peak of a variable simulating calcium binding site occupancy (such as "S" in example file demo.par).

The syntax is analogous for tracking the minimum of a variable:

`[` time_var_name `]` min_var_name min var T1 T2

Δ Simulation specifications:

The simulation run itself is defined using instruction Run, and requires specifying the integration time and the value of the calcium channel current during the run. There are two main variation for the Run command, corresponding to the adaptive (variable time-step) and the non-adaptive (fixed time-step) methods.
In both cases, it is also possible to change a particular finite-difference scheme used by the integrator: see Appendix A.

Δ Adaptive time-step method

When using the adaptive time-step method, the size of the integration time step is constantly modified to maintain some given level of accuracy. The simulation definition syntax in this case is

Run adaptive Time `[` dt0 dtMax accuracy accuracy0 maxError dtStretch n0 nStretch nMax ODEaccuracy `]`
current = expression

where Time is the total integration time (in ms) and expression is a numerical expression, variable name or constant specifying the calcium current through each of the defined calcium channels (set the weight parameters in the source command to have different currents go through different channels).

The values in brackets are optional and specify the parameters for the adaptive algorithm. The initial time-step is dt0, which is reduced unless the initial error tolerance accuracy0 is met. Each successive time-step in between accuracy checks is increased by a multiplicative factor dtStretch (slightly greater than one), unless it reaches its maximal value, specified by dtMax. Accuracy checks are performed every n steps: if accuracy check is successful, and n is less than nMax, n is multiplied by a factor of nStretch (slightly greater than one), otherwise n is reduced back to its initial value, n0, and the time step is halved. If an instability is encountered, then the error will eventually reach a value greater than maxError, at which point the method will handle the instability by taking one step back, parameters n0 and nMax will be decreased by one, and parameters nStretch and dtStretch will be reduced through multiplication by a constant adaptive.reduce, which is less than one. Finally, the value ODEaccuracy specifies the error tolerance for integration of the system of ODEs (e.g., corresponding to the calcium binding receptor kinetics). Default values are: dt0=1µs, dtMax=0.1ms, accuracy=1e-4, accuracy0=1e-3, maxError=0.05, dtStretch=1.05, n0=2, nStretch=1.2, nMax=22, ODEaccuracy=1.0e-4, reduce=0.8.

Initial values of the adaptive scheme parameters can also be set individually by assigning values to corresponding pre-defined identifiers (which are the properties of the adaptive method), i.e.: adaptive.dtStretch = 1.1; adaptive.n0 = 1

If the simulation error exceeds the value determined by parameter adaptive.maxError (which has a default value of 0.05), the simulation is deemed unstable, a warning message is produced, and the adaptive parameters dtStretch, nStretch, nMax and n0 are automatically modified to regain stability.

Example:

Run adaptive 1.0 0.001 0.1 1e-6
current = 0.2 pA

- Runs the adaptive scheme for 1 ms, with Ca⁺⁺ current of 0.2 pA per channel, with the initial time step of 1 µsec, maximal time step of 0.1 ms, and error tolerance of 1.0e-6.

Δ Fixed time-step method

The syntax for the non-adaptive simulation run is:

Run Time dt `[` ODEaccuracy `]`
current = expression

where "Time" is the total simulation time (in ms), "dt" is the simulation time-step, ODEaccuracy is an optional parameter setting the accuracy for the integration of ODEs (if any are defined), and "expression" is a numerical expression specifying the calcium current through each of the defined calcium channels.

Example:

Run 1.0 0.001 1e-5
current = 0.2 pA

- Runs the fixed time-step scheme for 1 ms, with Ca⁺⁺ current of 0.2 pA per channel, with the initial time step of 1 µsec, and Runge-Kutta ODE integration error tolerance of 1.0e-5.

Δ Multiple "Run" definitions

The simulation may be broken down into an arbitrary number of shorter simulations; in this case, there should be a current definition for each Run definition. Different algorithms may be used for successive runs.

Breaking up the simulation into multiple "runs" is desirable when the calcium channel currents change abruptly during the run, as when simulating channel opening and closing events. If an adaptive method is used, it is important that the channel current is continuous during each of the individual "runs". This will limit the error arising from large current discontinuity. Thus, it is desirable to use

Run adaptive 1.0 `% 1 ms-long channel opening`
current = 0.2 pA
Run adaptive 3.0 `% 3 ms-long channel closed period`
current = 0

rather than

Run adaptive 4.0 `% 4 ms-long channel opening`
current = 0.2 pA theta( 3 - t )

although formally the above two definitions are equivalent.

Δ Integrating ODEs only

It is also possible to run the ODEs only (see also the table command), using instruction

mode = ODE

In this case the current definitions are ignored, and the Run command syntax becomes

Run Time `[` dt0 accuracy `]`

The adaptive 5th-order Cash-Karp Runge-Kutta scheme is used to integrate the ODEs. Here Time is the total integration time (in ms), dt0 is the initial time step, and accuracy is the accuracy setting. Default values are: dt0 = 1 ms, accuracy = 1.0e-6. These values can be also set through assignment to the pre-defined constant names ODE.dt0 and ODE.accuracy:

model = ODE
Run 2.0
ODE.dt0 = 0.1 ; ODE.accuracy = 1e-5

Δ Graphics / data output

To plot or save the simulation results, plot instructions should be included. The type of output produced by plot instructions is controlled by the plot.method command.

To view the results in real time using the xmgr or the xmgrace programs, include the following command:

plot.method xmgr `[` rows cols `]`

This instructs the program to produce an ASCII stream of commands interpretable by xmgrace/xmgr. Xmgrace / xmgr is a powerful GNU data graphing application. Optional parameters "rows" and "cols" specify the arrangement of graphs within xmgr session window. If this plot method is used, the program output should be piped into an xmgr/xmgrace session, using "calc file.par | xmgr -pipe". The program is optimized to work with xmgr, but in the future it will be tuned more for xmgrace. Only point and 1D plot types will work in this regime; other plot types will be ignored. xmgr is the recommended plot method, since in this case data goes directly into a dedicated graphics application that can be used to produce publication-quality graphs. Note that to run xmgr/xmgrace under Windows environment, an X-server must be installed first.

The default plot method is

plot.method mute

- instructs the program to ignore all plot commands with the exception of mute, 1D.mute and 2D.mute file plots.

To instruct the program to generate plots using the gl / Ygl graphics library (works only on SGI / Linux platforms), use

plot.method gl

Data for each of the (non-mute) plots will be written to a file, if one includes the following command:

plot.print file_prefix

File names will be composed of the file_prefix and the name of the variable to be plotted. This will work even in the plot.method mute regime. The format of the data files produced in this case is the same as the format used by the point.mute, 1D.mute and 2D.mute plot types (see below).

Below follows a list of implemented plot types.

Δ "Point" plot (simple plot)

Plot of a time-dependent variable (defined via "d /dt=", ":=", "Ca[x,y,z]" (or "buffer_name[x,y,z]"), "peak" or "table").

Syntax in the plot.method xmgr mode is

plot point variable1 `[` variable2 variable3 ... `]`

where variable1, variable2, variable3, ... is a sequence of variable names to be plotted on the same panel of an xmgr graph.

In the gl mode, syntax is

plot point variable `[` xsize ysize `]`

where variable is the name of the variable to be plotted, and (xsize, ysize) are optional parameters specifying the size of the graph window in pixels.

To produce a data file instead of plotting, use

plot point.mute variable file_name or
plot mute variable file_name

where variable is the name of the variable to be saved to file file_name, in the two-column format "time variable(time)". One can also use the plot.print command to write all defined point plots to two-column data files.

Δ "1D" plot

Plot of a concentration field (calcium or buffer) along an axis.
Syntax in the plot.method xmgr mode is

plot 1D field axis coord1 coord2 `[` sets `]`

where field is the concentration field label (either Ca or the buffer name defined via buffer command), axis is the axis label ("x", "y" or "z" for 3D geometry, "r" or "theta" for the conical geometry, etc.), {coord1,coord2} is the coordinate of the point in the plane perpendicular to the chosen axis, at the intersection with that axis, and the optional parameter sets denotes the number of data sets (corresponding to several previous time steps) that will be shown (default is 5). The number of times the plot is refreshed during the simulation time is 200 by default; this number can be changed by assigning a value to parameter plot.1D.steps.

Syntax in the gl mode (only works on SGI and Linux platforms) is

plot 1D field axis coord1 coord2 `[` xsize ysize `]`

where the first four arguments are the same as in the plot.method xmgr plot mode, and {xsize, ysize} is the size of the graph window in pixels (optional).

To produce a data file instead of plotting, use

plot 1D.mute field axis coord1 coord2 filename

Data will be saved as a 3-column ASCII file filename, for several different time values; in each row the 1st number is the time, the 2nd value is the space coordinate along the chosen direction, and the third value is the corresponding value of the concentration field. The number of refresh (plot update) steps is by default equal to 200; it may be changed by assigning a value to the parameter plot.1D.steps. If this number is equal to "1", the concentration field values are only saved at the end of the simulation, as a two-column ASCII file, with the first column specifying the coordinate along the chosen axis, and the second number specifying the concentration value.

Note that for all 2D geometries, the argument coord2 should be omitted. For all 1D geometries, one should omit all three arguments axis, coord1 and coord2.

One can also use the plot.print command to write 1D non-mute plot data to a file.

Δ "2D" plot

To produce a file plot of the concentration profile in a 2D plane, use the command

plot 2D.mute field axis coord Time filename

where field is the concentration field label (either Ca or the buffer name defined via the buffer command), axis is the name of the axis perpendicular to the plane of the 2D plot ("x", "y" or "z"), and coord is the coordinate of a point along this axis at which it intersects the chosen 2D plane. This command will produce a 3-column ASCII file; in each row the first two numbers specify the 2D coordinate in the chosen plane, and the 3rd number is the value of the field at that point, at time T. The file format is chosen for compatibility with the gnuplot plotting program, available for both Unix and Windows platforms.

In the gl mode (only works on SGI and Linux platforms), one can make a pseudo-color plot of a 2D section of a concentration field (calcium or buffer), using

plot 2D field axis coord `[` xsize ysize `]`

where the first three arguments are the same as above, and (xsize, ysize) is the size of the graph window in pixels (optional).

Note that for all 2D geometries, the two arguments axis and coord should be omitted.

One can also use the plot.print command to save 2D non-mute plot data to a file.

Δ "Raster" plot

Pseudo-color plot of a concentration field (calcium or buffer) along an axis, as a function of time (gl mode only; only works on SGI and Linux platforms). Syntax is similar to that of a 1D plot (since this is a time-dependent 1D plot):

plot raster field axis coord1 coord2 `[` xsize ysize `]`

Δ "Dump" plot: saving the concentration field to disc

It may be desirable to store the entire 3D concentration field to disc in binary format, in order to read it back into another simulation using command import; this can be done using command

plot dump field T file_name

where field is the concentration field (either Ca or the buffer name defined via buffer command), to be saved in file file_name at simulation time T.
To save all of the concentration fields and ODE variables to a file, use command Export.

Δ Logarithmic plots

To plot data on a linear-log scale, simply append the suffix .log to a corresponding plot type, i.e.

plot point.mute.log Ca[0.1,0.1,0.1] "Ca.dat"
plot 2D.log Ca z 0.2

Δ Putting text on the graphs

This feature is currently implemented for the xmgr plot mode only. To print a string anywhere within the xmgr plot, use the command

plot.string string `[` x y charSize font color `]`

where string is the string to be plotted, {x, y} is the string position within the graph in xmgr viewport coordinates (between 0 and 1), charSize is the character size (default is 0.8), font it the xmgr font code (default is 4), and color it the xmgr color code (default is 4 - blue).

If several plot.string commands are included, and the optional coordinate arguments are omitted, each successive string will be printed directly below the preceding string.

Δ More data input / output

Δ Importing 3D concentration field from a file:

Instead of initializing the concentration of a field (where field is either Ca or the buffer name defined via buffer command) with the defined resting background value or the value derived from the total value, one can read the 3D concentration field from a file (generated via the plot dump command), using

field.import file_name

where file_name is the name of the file to be read.
To import all of the defined concentration fields (i.e., calcium plus buffers) at once, use command Import described below.

Δ Saving and retrieving data from a file: Import/Export commands

Apart from the import command and the plot dump command used to read and save the data corresponding to a single concentration field, one can also store and retrieve the entire simulation state (calcium and buffer fields plus the values of ODE variables) via a single command:

Export T file_name

- instructs the program to store the entire simulation state to file file_name at simulation time T.

Import filename

- instructs the program to import the simulation state stored using command Export.

Δ Printing strings and numbers to a file: print / append commands

To write the values of parameters and variables to a file at the end of the simulation, use

print file_name token1 token2 token3 ...

where file_name is the name of the file to which the output is directed, and token1, token2, ... are either strings or numerical expressions. To print the data to the terminal, use the names of the standard i/o streams stderr or stdout for the file_name.

To write several lines of output to a file, after the first print command use commands

append file_name token1 token2 token3 ...

- same as the print command, except that file_name has to exist when this command is invoked.

Any string that can be interpreted as a numerical expression will be converted to a numerical value, so the statement

var = 4
print stderr "var" "=" var

will print 4=4. However, the command print stderr "var=" var will produce the expected result var=4.

The first file_name argument can be omitted, and instead a single output file can be specified for all print / append commands, using the statement

print.file = file_name

A carriage-return (new line) control character is added to the file file_name for each print / append command.

Note that the print statements are invoked only after the end of the simulation runs, so all expressions in the argument list will be computed based on the final values of time-dependent variables

Δ Flow control statements (preprocessor commands)

Instructions described below are special in the sense that they are not definitions, like other commands described above, but represent tools controlling the parsing of the script itself. To this extend they are analogous to the C language pre-processor statement. Also, unlike the "usual" definition statements, the effect of these pre-processor statements may depend on their exact position in the script file.

Δ Repeating the simulation for multiple parameter values

If it is necessary to run the entire simulation many times as one or several simulation parameters are changed, one can use the "for" command. The syntax of the for cycle is:

for parameter_name = initial_value_expression to end_value_expression step increment_expression

For instance, one may want to explore the convergence of the results as spacial resolution is increased, using:

grid N N N
for N = 10 to 40 step 2

Nested for loops are realized by using several "for" commands. The top-most for loop is the outer loop, and each successive for command implies a cycle nested within the preceding cycle.

If the "for" loop command is present, then all non-mute plot commands are ignored, and one can use the track command to monitor the results:

track var1 var2 ....

where var1, var2, ... are names of variable to be monitored. The results will be automatically printed to a file, and graph plots will be produced also, depending on the specified plot.method. The data is output in the form of pairs of values "parameterValue varValueAtEndOfSimulation". The file names will be composed of the file prefix specified by the plot.print command, if it is present, and followed by the name of the variable. When using xmgr plot method, arguments of the same track command will be plotted in a single graph panel. To plot different variables in separate graph panels, use several track commands.

Do not use concentration construct variables in the track statements; instead, assign it to a variable and track the variable, i.e.
X := Ca[0.5,0.5,0.5]; track X

NOTE: Although the for statement can appear anywhere within the script, like all parameter definitions, in the presence of the conditional if statement one has to make sure that it is in the accessible part of the if .. then .. else block.

Δ The conditional statement: if / then / else / endif

The conditional if statement allows conditional processing of the script (this is analogous to C preprocessor commands):

if expression then
  ...........
  statements
  ...........
else
  ...........
  statements
  ...........
endif

where the else clause is optional and the expression is a logical expression. Note that the if statement is really a "preprocessor" command, meaning that this logical instruction controls the parsing of the script. Therefore, the logical expression may only depend on parameters defined earlier in the script.

Although the expression only depends on the predefined time-independent parameters, the if statement allows implementing non-trivial algorithms when used in conjunction with the for loop statement, the include command, and the print/append commands. Here's how it works: at each for loop iteration the results of the simulation can be printed to a file using the print/append commands, in the format of parameter definitions (i.e. print file "x0=" x). If the include statement appearing at the beginning of the script file imports the resulting file, then at each new for loop iteration the results of the previous iteration may influence the execution. For instance, an if conditional statement may contain a clause depending on the value of the saved parameter (i.e., if x0 > 1.0 then ...).

Δ Program termination command: exit

When both "if" and "for" statements are used, it may be desirable to terminate the program once a certain condition is satisfied. For this purpose, include the statement

exit

If this statement appears in an accessible part of the script file (as determined by conditional "if" statements), the program will be terminated before any useful action is performed.

Δ Appendix A: specifying the difference scheme

While the numerical engine uses the Douglas-Gunn difference scheme (second-order accurate in time) by default, few other difference schemes have also been implemented. To force CalC to use an alternative difference scheme, include an additional parameter in simulation definition commands Run (non-adaptive) and Run adaptive:

Run `[` method `]` Time dt `[` ODEaccuracy `]`

Run adaptive `[` method `]` Time `[` dt0 dtMax accuracy accuracy0 maxError dtStretch n0 nStretch nMax ODEaccuracy ]

where the optional parameter method can assume one of the following string values:

Geometry	Default method	Alternative method	Alternative method
3D (cartesian.3D)	`DG` (Douglas-Gunn implicit)	`FI` (fully implicit)	`EU` (forward Euler)
2D (cartesian.2D, conical, cylindrical)	`DG` (2D Douglas-Gunn/Crank-Nicholson)	`FI` (fully implicit)	`EU` (forward Euler)
1D (cartesian.1D, disc, spherical)	`CN` (Crank-Nicholson)

For example, to integrate the PDEs for 10 ms using the (adaptive) Euler method, instead of the default Douglas-Gunn method, use command

Run adaptive EU 10

Alternatively, one can define the scheme by simply assigning a value to the corresponding control constant:

PDE.scheme = EU

Δ Appendix B: controlling verbosity level

To control the program's commentary, use

verbose = level

To stop the program from commenting on everything it does, use verbose = 0. The default level value is 2. Values higher than 5 are only useful for debugging.

Δ Appendix C: debugging the script

When using the if/then/else/endif statement for conditional processing of the parameter file, it may be necessary to track the parsing of the file to ensure the desired order of processing of definitions. There are two tools for such debugging:

Instruction
debug
will cause the parser to print out to the terminal every token following the debug statement, as the file is parsed.
The command
echo string
will cause the parser to print out the value of the string at parse time. If string matches a name of a parameter (either string or numerical) defined earlier in the file, the value of that parameter will be printed instead.

[back to top]

Victor Matveev

This server is running a Redhat distribution of Linux.
Last modified: Thu May 29, 2003

Table of Contents

Δ Physical Units