Physical Units
Physical UnitsGeneral syntaxgrid 20 20 20 ; stretch.factor = 1.07
Ca.bc Neumann Neumann Neumann Neumann ...
Pump Pump
grid N N N ; N = 40 grid N M M ; N = 2 * M ; M = 10 "Ca\s0\N\S2+\N" = 0.1 (this creates an
xmgr-friendly name with a subscript and a superscript).
| + | - | ! (logical not) |
| ^ (exponentiation) |
| * | / | mod |
| + | - |
| < | <= | > | >= |
| == (equal) | != (not equal) |
| and |
| or |
k = 20 / ( 1 + exp( 2.1 ) ) ; Ca.D = 0.5 * k + 0.02. dV / dt = - V / tau_leak + IK + INa + Iapp
Iapp := 0.2 pA ( 1 + tanh( t - 5 ) )
current = 0.2 pA * sigma( 0.5 * ( t - 2 ) )
print stderr "result=" Ca[0.1,0.1,0.1] / Ca.bgr - 1.0
doubleQuote = '"' fileName = "var." "param" is equal to var.4, not var.param.
Geometry definitions:stretch command syntax is the same for spherical,
cylindrical and conical geometries, except that
one may use, respectively, the direction labels "r", "r" and "z",
or "r" and "theta", i.e.
Calcium and buffer definitions:Ca followed by a period, then
followed by the property name:
Bf is Bf.D = expression
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).
"bc_name" at all
six boundaries of the corresponding volume element.
bc_name with a, b and c satisfying: a * d[Ca]b / dn + b * [Ca]b = c [Ca]b is [Ca] at the boundary, and d[Ca]b / dn is the
gradient of [Ca] in the direction perpendicular to the boundary.
P=50 µm/ms, assuming zero background [Ca]
and calcium diffusion coefficient
of D=223 µm2/ms, one should use:
Neumann and Dirichlet boundary condition types are defined internally using
Dirichlet boundary condition (using a different type
label/name, since the bc's already defined may not be redefined).
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 [Ca2+].
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.
{x,y,z} is accessed using the
following time-dependent construct: Ca[x,y,z].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.
Ca[]; analogously, the variable tracking average concentration of
unbound buffer named buffer_name is
buffer_name[].
Defining ODEs"dvariable / dt = expression for derivative", for example
Ca[x,y,z]
denotes calcium concentration at point {x,y,z} (see above).
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:"variable := expression", i.e.
"t"
"tn f(tn)", without a comma or other delimeter in between):
plot mute Ca[0,0,0.1] "Ca1.dat",
and then run the program again after including the command Ca1 table "Ca1.dat".
Since only the ODEs corresponding to calcium binding scheme have to be integrated
in this case, one should use the mode = ODE command.
var on an interval [T1,T2],
use
peak_object_name is the name of the variable tracking the maximum of var.
peak_object_name.
Simulation specifications: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).
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.
adaptive.dtStretch = 1.1; adaptive.n0 = 1 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."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.Run command syntax becomes
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:
Graphics / data outputplot.method command.
"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.
file_prefix
and the name of the variable to be plotted. This will work even in the
plot.method mute regime. This is equivalent to using the
point.mute, 1D.mute and 2D.mute
plot types (see below).
variable1, variable2, variable3, ... is a sequence of variable names to be plotted
on the same panel of an xmgr graph.
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.
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.
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.
{xsize, ysize} is the size of the graph window in pixels (optional). 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.
2D geometries (conical and cylindrical), the
argument coord2 should be omitted. For the 1D spherical
geometry, one should omit all three arguments axis, coord1 and coord2.
1D non-mute plot data to a file.
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.
(xsize, ysize) is the size of the graph window in pixels (optional).
2D geometries (conical and
cylindrical),
the two arguments axis and coord should be omitted.
2D non-mute
plot data to a file.
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 {xsize, ysize}
is the size of the graph window in pixels (optional).
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.
linear-log scale, simply append the suffix .log to
a corresponding plot type, i.e.
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).plot.string commands are included, and the optional
coordinate arguments are omitted, each successive string will be printed directly
below the preceeding string.
More data input / outputfield (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
file_name is
the name of the file to be read. 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
Program flow control statements
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 (recall that
any numerical value used in the parameter file can be replaced with a symbolic
parameter name). The syntax of the for cycle is:
for parameter_name =
initial_value to end_value
step increment
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 loops are not implemented; if several "for" commands are used, then
several parameters will be changed simultaneously.
If the "for" loop command is present, then all
plotting commands are ignored,
and one has to 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, unless
the command "plot.method mute" is present.
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 in the parameter file,
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
parameter file (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 which depends
on the values of parameters defined in the part of the parameter file preceeding
the if statement. This is the only case where the order of appearance
of definitions matters (not counting the ordered processing of Run
simulation statements).
Although the expression only depends on the predefined time-independent parameters,
the conditional statement allows for 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 following the CalC parameter file syntax. If the include
statement appearing in the beginning of the parameter file reads the resulting file,
then the if statement condition evaluated at a given iteration may
depend on the results of the previous iteration.
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 the accessible part of the parameter file (as determined
by conditional "if" statements), the program will be terminated before
any useful action is performed.
Spherical symmetry: 1D simulations
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
uniformally 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:
source R dR
where "R" specifies the radius of the spherical surface over which the current
is uniformally 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: 2D simulations
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:
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: 2D simulations
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 conus.
Only four boundary
conditions need to be defined.
Similarly, only four parameters specify the Ca current source:
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.
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
DG (Douglas-Gunn implicit)FI (fully implicit)EU (forward Euler)
2D conical
DG (2D Douglas-Gunn/Crank-Nicholson)FI (fully implicit)EU (forward Euler)
2D cylindrical
DG (2D Douglas-Gunn/Crank-Nicholson)FI (fully implicit)EU (forward Euler)
1D 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 parameter file
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:
- Including the word
debug
in the parameter file 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 parsing time. If string matches a name of a parameter defined earlier in the
file, its value will be printed instead.
[back to top]
Victor Matveev
This server is running a
Redhat distribution of
Linux.
Last modified: Thu Jul 25, 2002