Previous Section - ChemCell WWW Site - ChemCell Documentation - ChemCell Commands

7. Errors

This section describes the various kinds of errors you can encounter when using ChemCell.

7.1 Common problems
7.2 Reporting bugs
7.3 Error & warning messages

7.1 Common problems

If two ChemCell runs do not produce the same answer on different machines or different numbers of processors, this is typically not a bug. In theory you should get identical answers on any number of processors and on any machine. In practice, the use of random numbers by ChemCell will cause differences in spatial simulations (see the sort command for more info) leading to divergent trajectories for two simulations. Even non-spatial simulations can incur numerical round-off which can cause slight differences and eventual divergence of phase space trajectories within a few 100s or few 1000s of timesteps. However, the statistical properties of the two runs (e.g. average energy or temperature) should still be the same.

A ChemCell simulation typically has two stages, setup and run. Most ChemCell errors are detected at setup time; others may not occur until the middle of a run.

ChemCell tries to flag errors and print informative error messages so you can fix the problem. Of course ChemCell cannot figure out your physics mistakes, like choosing too big a timestep, specifying invalid reaction rates, or building an invalid geometry! If you find errors that ChemCell doesn't catch that you think it should flag, please send us an email.

If you get an error message about an invalid command in your input script, you can determine what command is causing the problem by looking in the log.ChemCell file or using the echo command to see it on the screen. For a given command, ChemCell expects certain arguments in a specified order. If you mess this up, ChemCell will often flag the error, but it may read a bogus argument and assign a value that is valid, but not what you wanted. E.g. trying to read the string "abc" as an integer value and assigning the associated variable a value of 0.

Generally, ChemCell will print a message to the screen and exit gracefully when it encounters a fatal error. Sometimes it will print a WARNING and continue on; you can decide if the WARNING is important or not. If ChemCell crashes or hangs without spitting out an error message first then it could be a bug (see this section) or one of the following cases:

ChemCell runs in the available memory a processor allows to be allocated. Most reasonable runs are compute limited, not memory limited, so this shouldn't be a bottleneck on most platforms. Almost all large memory allocations in the code are done via C-style malloc's which will generate an error message if you run out of memory. Smaller chunks of memory are allocated via C++ "new" statements. If you are unlucky you could run out of memory just when one of these small requests is made, in which case the code will crash or hang (in parallel), since ChemCell doesn't trap on those errors.

Illegal arithmetic can cause ChemCell to run slow or crash. This is typically due to invalid physics and numerics that your simulation is computing. If you see wild thermodynamic values or NaN values in your ChemCell output, something is wrong with your simulation.

In parallel, one way ChemCell can hang is due to how different MPI implementations handle buffering of messages. If the code hangs without an error message, it may be that you need to specify an MPI setting or two (usually via an environment variable) to enable buffering or boost the sizes of messages that can be buffered.

7.2 Reporting bugs

If you are confident that you have found a bug in ChemCell, we'd like to know about it via email.

First, check the "New features and bug fixes" section of the ChemCell WWW site to see if the bug has already been reported or fixed.

If not, the most useful thing you can do for us is to isolate the problem. Run it on the smallest number of atoms and fewest number of processors and with the simplest input script that reproduces the bug.

Send an email that describes the problem and any ideas you have as to what is causing it or where in the code the problem might be. We'll request your input script and data files if necessary.

7.3 Error & warning Messages

These are two alphabetic lists of the ERROR and WARNING messages ChemCell prints out and the reason why. If the explanation here is not sufficient, the documentation for the offending command may help. Grepping the source files for the text of the error message and staring at the source code and comments is also not a bad idea! Note that sometimes the same message can be printed from multiple places in the code.

Errors:

%d local particles on proc %d are in ghost cells after compact
Debug test to insure particles have moved to correct processors. This error should not occur.
%d particles assigned to procs
Particles read from file, but not all assigned correctly to processors.
2d particle move hit a triangle vertex
Particle moving on a surface went exactly through a triangle vertex. Should not occur.
Alias %s already exists
Cannot reuse a species name.
All universe/uloop variables must have same # of values
All variables in next command must be same style
Self-explanatory.
Another input script is already being processed
Cannot attempt to open a 2nd input script, when the original file is still being processed.
Arccos of invalid value in variable formula
Argument of arccos() must be between -1 and 1.
Arcsin of invalid value in variable formula
Argument of arcsin() must be between -1 and 1.
Bin size of 0.0
Self-explanatory.
Bins are already setup
Global and boundary command must be used before bins command. Bins command can only be used once.
Cannot add triangles to a region surface
Triangles can only be added to a trianguated surface.
Cannot change dimension of existing particles
Particles are either 2d or 3d. Cannot be changed.
Cannot check for a 2d species
Check command for inside/outside a surface can only be done for 3d species.
Cannot do move_test with timestep = 0
Timestep must be non-zero to perform a move test.
Cannot have 0-reactant reactions with spatial simulation
This is because the volume within which to create the particles is not well-defined.
Cannot open fix conc/random file %s
Self-explanatory.
Cannot open fix conc/set file %s
Self-explanatory.
Cannot open input script %s
Self-explanatory.
Cannot open logfile %s
The ChemCell log file specified in the input script cannot be opened. Check that the path and name are correct.
Cannot open restart file %s
Self-explanatory.
Cannot perform match with two or more wildcard *
A string with a wildcard character "*" can only have one wildcard.
Cannot redefine variable as a different style
An equal-style variable can be re-defined but only if it was originally an equal-style variable.
Cannot set permeability for a 2d species
Permeability only makes sense for a 3d species hitting a surface.
Cannot use balance command with non-spatial simulation
Self-explanatory.
Cannot use bin command with non-spatial simulation
Self-explanatory.
Cannot use count command with spatial simulation
Self-explantory.
Cannot use diffusion command with non-spatial simulation
Self-explantory.
Cannot use dimension command with non-spatial simulation
Self-explantory.
Cannot use dump command with non-spatial simulation
Self-explantory.
Cannot use fix conc/random with non-spatial simulations
Self-explantory.
Cannot use fix conc/set with spatial simulations
Self-explantory.
Cannot use fix dna/toggle with spatial simulations
Self-explantory.
Cannot use fix rate/saturate with spatial simulations
Self-explantory.
Cannot use global command with non-spatial simulation
Self-explantory.
Cannot use move_style command with non-spatial simulation
Self-explantory.
Cannot use move_test command with non-spatial simulation
Self-explantory.
Cannot use particle command with non-spatial simulation
Self-explantory.
Cannot use permeable command with non-spatial simulation
Self-explantory.
Cannot use probability command with non-spatial simulation
Self-explantory.
Cannot use region command with non-spatial simulation
Self-explantory.
Cannot use this run style in parallel
Only some run styles support parallel execution.
Cannot use timestep command with gillespie simulation
Stochastic simulations set the timestep for each reaction.
Cannot use triangles command with non-spatial simulation
Self-explantory.
Cannot use volume command with spatial simulation
Self-explantory.
Cannot write dump files for non-spatial simulation
Self-explantory.
Cannot write restart files for non-spatial simulation
Restart files only contain particle info, so they are not used for non-spatial simulations.
Code is not compiled with move debug option
Debug command cannot be used unless ChemCell was compiled with -DDEBUG_MOVE flag or with the "#define DEBUG_MOVE" line uncommented at the top of src/move.cpp.
Could not find reaction ID
Self-explantory.
Could not find undump ID
Self-explantory.
Could not find unfix ID
Self-explantory.
Could not find unreact ID
Self-explantory.
Could not open balance file
The output file used by the balance command could not be opened.
Could not open dump file
The output file used by the dump command could not be opened.
Could not open input script
Self-explantory.
Could not open log.ccell
Self-explantory.
Could not open logfile
Self-explantory.
Could not open move_test file
The output file used by the move_test command could not be opened.
Could not open screen file
The screen file specified as a command-line argument cannot be opened. Check that the directory you are running in allows for files to be created.
Could not open universe log file
For a multi-partition run, the master log file cannot be opened. Check that the directory you are running in allows for files to be created.
Could not open universe screen file
For a multi-partition run, the master screen file cannot be opened. Check that the directory you are running in allows for files to be created.
Cound not find dump_modify ID
Self-explanatory.
Did not assign all particles correctly
Reading of restart file did not assign all particles to processors correctly.
Did not find matching reaction particle
After particle communication, matching particle on another processor could not be found. This error should not occur.
Divide by 0 in variable formula
Self-explanatory.
Dump species count does not match particle species count
Species count has changed since dump file was defined.
Failed to allocate %d bytes for array %s
Your ChemCell simulation has run out of memory. You need to run a smaller simulation or on more processors.
Failed to reallocate %d bytes for array %s
Your ChemCell simulation has run out of memory. You need to run a smaller simulation or on more processors.
Global bin does not map to local domain
Problem with converting global bin ID to a local bin ID. This error should not occur.
Illegal ... command
Self-explanatory. Check the input script syntax and compare to the documentation for the command. You can use -echo screen as a command-line option when running ChemCell to see the offending line.
Invalid diffusion constant
Diffusion coefficient must be >= 0.
Invalid dimensionality
Dimensionality must be 2 or 3.
Invalid dump frequency
Dump frequency must be 1 or greater.
Invalid fix style
Self-explanatory.
Invalid region style
Self-explanatory.
Invalid run style
Self-explanatory.
Input line too long after variable substitution
This is a hard (very large) limit defined in the input.cpp file.
Input line too long: %s
This is a hard (very large) limit defined in the input.cpp file.
Invalid 2d particle move
Problem occured with 2d particle moving on a triangle. This error should not occur.
Invalid command-line argument
One or more command-line arguments is invalid. Check the syntax of the command you are using to launch ChemCell.
Invalid flag in header of restart file
Format of restart file was not recognized. This error should not occur unless restart file is corrupted.
Invalid math function in variable formula
The math or group function is not recognized.
Invalid reaction ID in fix dna/toggle command
Self-explanatory.
Invalid reaction ID in fix rate/saturate command
Self-explanatory.
Invalid region arguments
Number of arguments doesn't match region style.
Invalid settings for reaction %s
One or more settings for a reaction are invalid. This error should not occur.
Invalid species %s in stats command
Self-explanatory.
Invalid species ID in fix conc/random command
Self-explanatory.
Invalid species ID in fix conc/set command
Self-explanatory.
Invalid species ID in fix dna/toggle command
Self-explanatory.
Invalid species ID in fix rate/saturate command
Self-explanatory.
Invalid syntax in variable formula
Self-explanatory.
Invalid variable evaluation in variable formula
A variable used in a formula could not be evaluated.
Invalid variable in next command
Self-explanatory.
Invalid variable name in variable formula
Variable name is not recognized.
Invalid variable name
Variable name used in an input script line is invalid.
Invalid variable style with next command
Variable styles equal and world cannot be used in a next command.
Label wasn't found in input script
Self-explanatory.
Log of zero/negative in variable formula
Self-explanatory.
Max 2d move distance > bin size
Move distance exceeds bin size. Must increase bin size or reduce move size.
Max 3d move distance > bin size
Move distance exceeds bin size. Must increase bin size or reduce move size.
Max reaction distance > bin size
Binary reaction distance exceeds bin size. Must increase bin size or reduce reaction distance.
Move to next bin out of range
Particle moved into bin not owned by this processor. This error should not occur.
Must be 2 or more bins in periodic dimensions
Binning of global domain has resulted in only one bin in a particular dimension.
Must print stats in count units for spatial simulation
Self-explanatory.
Must set bins before defining region
Use bin command before using region command.
Must set bins before read restart
Use bin command before using read_restart command.
Must set bins before reading particles
Use bin command before using particles command.
Must set bins before reading surface
Use bin command before using triangles command.
Must set bins before run
Use bin command before using run command.
Must set global domain before bins
Use global command before using bin command.
Must set run_style first
Cannot use this command before the run style is set
Must set simulation domain via global command
Global command has not been used before a simulation is being initialized.
Must set volume for run style gillespie
This run style requires that the volume command be used.
Must set volume for run style ode/rk
This run style requires that the volume command be used.
Must set volume for run style ode
This run style requires that the volume command be used.
Must use -in switch with multiple partitions
A multi-partition simulation cannot read the input script from stdin. The -in command-line option must be used to specify a file.
No matching move style parameters
Style of requested move does not exist.
No particle species match dump species
Requested dump species does not exist.
Part,spec %d,%d on step %d exceeds MAXITER
Movement of particle has exceeded preset iteration count. This error should not occur unless there is a problem with the move.
Particle %d is outside global domain
Particle being read from file is outside the global domain.
Particle %d's triangle does not exist
Could not successfully assign a read-in particle to a triangle on a 2d surface. Probably because it is too far from any triangle.
Particle is outside global domain
Particle being read from restart file is outside the global domain.
Particles surf-ID does not exist
2d particles read from file are assigned to a surface ID that does not exist.
Permeability is set for 2d species
Permeability can only be set for 3d species.
Permeable probabilities do not sum to 1.0
Self-explanatory.
Permeable stick species is not 2d
When a 3d species sticks to a surface, it must become a 2d species.
Post-migrate: %d particles on proc %d are not in correct bin
Particle migration to a new processor has resulted in incorrect bin assignments. This error shoud not occur.
Power by 0 in variable formula
Self-explanatory.
Pre-migrate: %d particles on proc %d are not in correct bin
Particle migration to a new processor is occuring with incorrect bin assignments. This error shoud not occur.
Probability %g for reaction %s is too large
The computed probability exceeds 1.0. You need to reduce the reaction distance so the probability will shrink.
Processor partitions are inconsistent
The total number of processors in all partitions must match the number of processors ChemCell is running on.
Reaction ID %s already exists
A reaction ID can only be used once.
Reaction cannot have more than MAX_PRODUCT products
This is a hard limit in react.cpp.
Reaction has no numeric rate
Self-explanatory.
Reaction must have 0,1,2 reactants
Self-explanatory.
Reading 2d particles for a 3d species
3d particles cannot be assigned to a surface.
Reading 3d particles for a 2d species
2d particles must be assigned to a surface.
Region extends outside global domain
Self-explantory.
Region intersects bin next to periodic boundary
For a periodic dimension, there must be a bin at each boundary which has no region interesecting it.
Region surf-ID already exists
Surface IDs must be unique.
Replacing a fix, but new style != old style
A fix ID can be used a 2nd time, but only if the style matches the previous fix. In this case it is assumed you with to reset a fix's parameters. This error may mean you are mistakenly re-using a fix ID when you do not intend to.
Reuse of dump ID
A dump ID cannot be used twice.
Run style does not support checking
Not all run styles can use check command.
Simulation domain is already set
Cannot use global command twice.
Species already exists and no new aliases are defined
Cannot use a species name more than once.
Sqrt of negative in variable formula
Self-explanatory.
Sticking species is not 2d
A membrane-bound species must be defined as dimension = 2d.
Substitution for illegal variable
Input script line contained a variable that could not be substituted for.
Summed probability %g for species %s & %s is too large
Probabilities for all reactions involving this pair of species > 1.0
Summed probability %g for species %s is too large
Probabilities for all reactions involving this species > 1.0
Triangle intersects bin next to periodic boundary
For a periodic dimension, there must be a bin at each boundary which has no trinagles interesecting it.
Two or more wildcard * in count species ID
A string with a wildcard character "*" can only have one wildcard.
Two or more wildcard * in diffusion species ID
A string with a wildcard character "*" can only have one wildcard.
Two or more wildcard * in dimension species ID
A string with a wildcard character "*" can only have one wildcard.
Two or more wildcard * in stats species ID
A string with a wildcard character "*" can only have one wildcard.
Unbalanced quotes in input line
No matching end double quote was found following a leading double quote.
Unexpected end of file
ChemCell hit the end of the file while attempting to read particles or surface info. Something is wrong with the format of the file.
Universe/uloop variable count < # of partitions
A universe or uloop style variable must specify a number of values >= to the number of processor partitions.
Unknown command: %s
The command is not known to ChemCell. Check the input script.
Unknown species %s in check command
Self-explantory.
Unknown species %s in permeable command
Self-explanatory.
Unknown species in count command
Self-explanatory.
Unknown species in diffusion command
Self-explanatory.
Unknown species in dimension command
Self-explanatory.
Unknown species in move_test command
Self-explanatory.
Unknown species in particles command
Self-explanatory.
Unknown species in reaction command
Self-explanatory.
Unknown surface %s in check command
Self-explanatory.
Unknown surface %s in permeable command
Self-explanatory.
Variable name must be alphanumeric or underscore characters
Self-explanatory.
Vertex %d in surf %s is outside global domain
One or more vertices in triangles being read in are outside global domain.
World variable count doesn't match # of partitions
A world-style variable must specify a number of values equal to the number of processor partitions.

Warnings:

Particle is inside surface
Check determined a particle is inside surface when it should be outside.
Particle is outside surface
Check determined a particle is outside surface when it should be inside.
Restart file used different # of processors
The restart file was written by a simulation run on a different number of processors.
Restart file version does not match ChemCell version
The restart file was written with an older version of ChemCell.
Run styles do not match
The restart file was written by a simulation that defined a different run style.