Q = 2 e is the charge of a Ca2+ ion. grid 20 20 20 ; stretch.factor = 1.07
Ca.bc Noflux Noflux Noflux Noflux ...
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).
| ! |
| ^ |
| - |
| * | / | mod |
| + | - |
| < | <= | > | >= |
| == (equal) | != (not equal) |
| and |
| or |
"..." or '...';
the closing quote must be the same as the opening quote:
doubleQuote = '"' fileName = "var." "param" is equal to var.4, not var.param.
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.: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 geometry | |
| spherical | r | Fully spherically symmetric geometry | |
2D |
cartesian.2D | x y | 2D model in cartesian coordinates |
| cylindrical | r z | 2D model in cylindrical coordinates | |
| polar | r phi | 2D model in polar 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 |
| spherical.3D | r theta phi | Full 3D model in spherical coordinates | |
| cylindrical.3D | r phi z | Full 3D model in cylindrical 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 Ca[0.2,0,0] |
plot Ca[0.2,0] |
plot 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 |
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."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."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.
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
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:
R, Theta specify the location of the source, and optional
parameters dR, dZ specify the spread of the source."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.
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
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. R, Theta specify the location of the source, and optional parameters
dR, dTheta specify the spread of the source."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.
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.
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,
Noflux (zero flux reflective) or Dirichlet (zero concentration
at the boundaries). "bc_name" at all
six boundaries of a corresponding volume element, use
A, the value of the last argument P is ignored,
and the corresponding boundary condition is of Dirichlet type: [F]b is the Ca2+ or buffer concentration at the boundary. A, the corresponding boundary condition is
d[F]b / dn is the
concentration gradient in the direction perpendicular to the boundary,
and [F]0 is the background concentration.
P is zero by default. Non-zero values of P allow to implement
a saturable calcium pump. For instance, to simulate calcium pumps on the bottom and top ("zmin" and "zmax")
surfaces of a volume, with maximal pump rate of Vm=0.01 µM µm / ms,
and dissociation rate of KP=0.2 µM, use
A = 1, B = - Vm / (KP DCa) = -0.227 (µm-1),
where DCa=0.220 µm2 / ms is the calcium diffusion coefficient,
and set P = 1 / KP = 5 (µM-1):
Noflux (zero flux) 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); for instance:
total concentration, using
total concentration definition, for instance:
total concentration (see table)
depth
over the entire boundary surface, using instruction
depth is an optional numerical constant expression determining the thickness of the
buffer layer surrounding the boundary. depth is zero (which is its default value),
the buffer will be localized to one grid layer around the membrane, and the total
concentration should be specified in units of molecules per µm2.
[ Note that in this case the buffer concentration will be higher in the corners of an enclosure,
since the corner voxels will include contributions from the buffer bound to all surfaces meeting in that
corner. ]
dx, dy and dz specify the width of the
source (square brackets indicate that parameters are optional; do not include brackets 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, unless the calcium concentration in the
microdomain of a single channel is studied, one
should set the width parameters so that the source covers at least 2-3 grid intervals.
This will improve the numerical accuracy and the convergence properties of the method.
If only the
"dx" parameter is defined, the source spread in all three directions is assumed to be the same.
[x - dx, x + dx] * [y - dy, y + dy] * [z - dz, z + dz].
{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[].
dvariable / dt = expression_for_derivative, for example
"`" instead of the d/dt
construct, i.e.:
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.
"variable := expression", i.e.
"t"
"tn f(tn)", without a comma or other delimiter in between):
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.
var on an interval [T1,T2],
use
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.
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.
stateNumber specifies the number of markovian states,
and the parameter initialState specifies the state of the variable at simulation
start. variableName.i.j. The following example
specifies a markov gating variable with two states:
0 to state 1 is
constant at 0.2 per millisecond,
while the backward transition probability 1 -> 0 depends on the concentration of Ca2+
at the origin. markov variable, since the Ca2+ and
buffer PDEs are integrated deterministically, assuming no stochasticity. In particular, only
a fixed time-step PDE integration method should be used in this
situation, with a small time step
(see an example).
Using markov variables in ODE-only
mode is not recommended.
longInteger is a 32-bit integer value that will be used to intitialize
the high-order 32 bits of the random number generator state.
On Unix platforms, a standard 48-bit random number generator
drand48() is used.
Time is the total integration time (in ms).
The values in brackets are optional and specify the parameters for the adaptive algorithm.
The initial time-step is dt0, which is reduced if the error tolerance
accuracy is not met.
Each successive time-step is increased by a multiplicative factor
dtStretch, slightly
greater than one.
Accuracy checks are performed every n steps: if accuracy check is successful,
n is increased by one, otherwise the time step is halved, and n is reset
depending on the number of steps since last time step reduction.
If the error is greater than five times the accuracy tolerance,
the integrator takes a reverse step back to the previous successful accuracy check.
Finally, the value ODEaccuracy specifies the error tolerance for integration of the
system of ODEs (e.g., corresponding to the user-defined calcium binding receptor kinetics).
Default values are: dt0=1µs, accuracy=1e-4, dtStretch=1.05,
ODEaccuracy=1.0e-4.
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.accuracy = 1e-8.
Finally, there are two parameters that control the minimal and the maximal number of
integrator steps between successive accuracy checks:
adaptive.steps = 3; adaptive.maxSteps = 20.
There is little need to change these default values under most circumstances.
Run statement should be accompanied by its own
current definition statement, which accepts one of the following two forms:
expression is a numerical expression, variable name or
a constant specifying the calcium current per
channel. The first form of the current statement is used when the same
current flows through each of the defined Ca++ channels.
The second form of the current statement is
used when several channels are present, with distinct Ca++ current
magnitudes. In this case the keyword currents should be followed by a list of varible names,
with the number of variables in the list equal to the number of channels defined by the
Ca.source commands.
currents
keyword specifies the current through each of the two Ca++ sources,
defined elsewhere in the script.
The Ca++ current through the first channel is 0.1 pA,
while the current through the second channel is time-dependent
(linearly increasing with time).
"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).Run statement should be accompanied by
a current definition statement, described above.
I_Ca1 and I_Ca2 through the
two channels (two Ca.source commands should be present in the script),
where I_Ca1
and I_Ca2 are either constants or time-dependent variables defined by the user.
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:
plot.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 simple (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. The format of the data files produced
in this case is the same as the format used by the
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 simple 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.
coord2 should be omitted.
For all 1D geometries,
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).
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 preceding string.
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
file_name is
the name of the file to be read. file_name
at simulation time T.
Export.
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.
print command use commands
print command, except that file_name has to exist
when this command is invoked.
4=4. However, the command print stderr "var=" var
will produce the expected result var=4.
file_name argument can be omitted, and instead a single output file can be
specified for all print / append commands, using the statement
file_name
for each print / append command.
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.
track
command to monitor the results:
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.
track
statements; instead, assign it to a variable and track the variable, i.e.
X := Ca[0.5,0.5,0.5]; track X
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.
if statement allows conditional processing of the
script (this is analogous to C preprocessor commands):
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.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 ...).
CalC to use
an alternative difference scheme, include an additional parameter in simulation definition
commands Run (non-adaptive) and Run adaptive:
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) |
verbose = 0.
The default level value is 2. Values higher than 5 are only useful for debugging.
debug statement, as the file is parsed.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.