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:
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
parameter file!)
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 is the initial time-step, which is further reduced
unless initial accuracy of accuracy0 is satisfied.
Each successive time-step in between accuracy checks is increased by a factor
dtStretch (slightly
greater than one), unless it reaches some maximal value 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.
Default values are: dt0=1µs, dtMax=0.1ms,
accuracy0=1e-3, accuracy=1e-4, dtStretch=1.05, n0=2, nStretch=1.2, nMax=22.
adaptive.accuracy0=1e-5; 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, eps 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
polish the plot.
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
mute and mute_1D plot types (see below).
Ygl (default) mode, syntax is
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 (Ygl mode only).
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 saved to file file_name,
in the two-column format
"time variable(time)". One can also use the plot.print
command to write a point plot to a file.
Ygl mode is
field is the concentration field (either Ca or the buffer name defined
via buffer command), axis is the axis name (x, y or
z), {coord1,coord2} is the coordinate of the point in the
plane perpendicular to axis at the intersection with the axis, and {xsize, ysize}
is the size of the graph window in pixels (optional).
Ygl mode,
optional parameter steps specifies the number of times the plot will be updated during
the entire integration run (default is 700), and optional parameter sets denotes the number
of most recent updates that will be shown (default is 5).
1D plot to a file.
Ygl mode only).
field is the concentration field (either Ca or the buffer name defined
via buffer command), plane is the name of the section plane
(x, y or z), coord is the coordinate of a point along an axis
perpendicular to plane at which the axis and the plane intersect,
and (xsize, ysize) is the size of the graph window in pixels (optional).
Ygl mode only). Syntax is similar to that of a 1D plot (since
this is a time-dependent 1D plot):
field is the concentration field (either Ca or the buffer name defined
via buffer command), axis is the axis name (x, y or
z), {coord1,coord2} is the coordinate of the point in the
plane perpendicular to axis at the intersection with the 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 prefix 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 after the end of 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.
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.
A new-line control character is added at the end of each print statement.
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 envoked.
Note that the print statements are envoked 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 (this is in contrast to expressions used in parameter
definitions).
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 ouput 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.
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 termintation commmand: 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 "x",
and set the "x", "y" coordinates to zero. For example,
use stretch x 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 x 0 0 to plot the calcium concentration as a function of
distance 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 dR Theta dTheta
where R, Theta specify the location of the source, and dR, dTheta specify
the spread of the source.
All other commands also remain unchanged; wherever an axis name is needed, use "x"
for the radial coordinate, "y" for the angle coordinate.
and set the "z" coordinate to zero. For example,
use stretch y 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 y r0 0 to plot the calcium concentration as a function of
angle, at a distance r0 from the center of the sphere, and use
plot 2D Ca z 0 0 to see the entire concentration field.
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 and Run adaptive:
Run [ method ] Time dt
Run adaptive [ method ] Time
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)
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:
Run.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.
Victor Matveev
Last modified: Tue June 26, 2001