Troubleshooting
===============
Input errors
------------
- *not well-formed (invalid token)*: Seen if the input file does not
have the correct xml syntax. Should be accompanied by a line number
giving the point in the file where the syntax is incorrect.
- *mismatched tag*: One of the closing tags does not have the same name
as the corresponding opening tag. Could be caused either by a
misspelling of one of the tags, or by having the closing tag in the
wrong place. This last one is a standard part of the xml syntax, if
the opening tag of one item is after the opening tag of a second,
then its closing tag should be before the closing tag of the second.
Should be accompanied by a line number giving the position of the
closing tag.
- *Uninitialized value of type \_\_* or *Attribute/Field name \_\_ is
mandatory and was not found in the input for property \_\_*: The xml
file is missing a mandatory tag, i.e. one without which the
simulation cannot be initialized. Find which tag name is missing and
add it.
- *Attribute/tag name \_\_ is not a recognized property of \_\_
objects*: The first tag should not be found within the second set of
tags. Check that the first tag is spelt correctly, and that it has
been put in the right place.
- *\_\_ is not a valid option (___)*: This attribute/tag only allows a
certain range of inputs. Pick one of the items from the list given.
- *\_\_ is an undefined unit for kind \_\_* or *\_\_ is not a valid
unit prefix* or *Unit \_\_ is not structured with a prefix+base
syntax*: The unit input by the user is not correct. Make sure it
corresponds to the correct dimensionality, and is spelt correctly.
- *Invalid literal for int() with base 10: \_\_* or *Invalid literal
for float(): \_\_* or *\_\_ does not represent a bool value*: The
data input by the user does not have the correct data type. See
section :ref:`ifilestructure` for what constitutes a valid
integer/float/boolean value.
- *Error in list syntax: could not locate delimiters*: The array input
data did not have the required braces. For a normal array use [], for
a dictionary use {}, and for a tuple use ().
- *The number of atom records does not match the header of xyz file*:
Self-explanatory.
- *list index out of range*: This will normally occur if the
configuration is initialized from an invalid input file. This will
either cause the code to try to read part of the input file that does
not exist, or to set the number of beads to zero which causes this
error in a different place. Check that the input file has the correct
syntax.
Initialization errors
---------------------
- *Negative \_\_ parameter specified.*: Self-explanatory.
- *If you are initializing cell from cell side lengths you must pass
the ’cell’ tag an array of 3 floats*: If you are attempting to
initialize a cell using the “abc” mode, the code expects three floats
corresponding to the three side lengths.
- *If you are initializing cell from cell side lengths and angles you
must pass the ’cell’ tag an array of 6 floats*: If you are attempting
to initialize a cell using the “abcABC” mode, the code expects six
floats corresponding to the three side lengths, followed by the three
angles in degrees.
- *Cell objects must contain a 3x3 matrix describing the cell
vectors.*: If you are attempting to initialize a cell using the
“manual” mode, the code expects nine floats corresponding to the cell
vector matrix side lengths. Note that the values of the
lower-diagonal elements will be set to zero.
- *Array shape mismatch in q/p/m/names in beads input*: The size of the
array in question does not have the correct number of elements given
the number of atoms and the number of beads used in the rest of the
input. If the number of beads is nbeads and the number of atoms
natoms, then q and p should have shape (nbeads, 3\*natoms) and m and
names should have shape (natoms,).
- *No thermostat/barostat tag provided for NVT/NPT simulation*: Some
ensembles can only be sampled if a thermostat and/or barostat have
been defined, and so for simulations at constant temperature and/or
pressure these tags are mandatory. If you wish to not use a
thermostat/barostat, but still want to keep the ensemble the same,
then use “dummy” mode thermostat/barostat, which simply does nothing.
- *Pressure/Temperature should be supplied for constant
pressure/temperature simulation*: Since in this case the ensemble is
defined by these parameters, these must be input by the user. Add the
appropriate tags to the input file.
- *Manual path mode requires (nbeads-1) frequencies, one for each
internal mode of the path.*: If the “mode” tag of “normal_modes” is
set to “manual”, it will expect an array of frequencies, one for each
of the internal normal modes of the ring polymers.
- *PA-CMD mode requires the target frequency of all the internal
modes.*: If the “mode” tag of “normal_modes” is set to “pa-cmd”, it
will expect an array of one frequency, to which all the internal
modes of the ring polymers will be set.
- *WMAX-CMD mode requires [wmax, wtarget]. The normal modes will be
scaled such that the first internal mode is at frequency wtarget and
all the normal modes coincide at frequency wmax.*: If the “mode” tag
of “normal_modes” is set to “wmax-cmd”, it will expect an array of
two frequencies, one two set the lowest frequency normal mode, and
one for the other normal mode frequencies.
- *Number of beads \_\_ doesn’t match GLE parameter nb= \_\_*: The
matrices used to define the generalized Langevin equations of motion
do not have the correct first dimension. If matrices have been
downloaded from ``_
make sure that you have input the correct number of beads.
- *Initialization tries to match up structures with different atom
numbers*: If in the initialization any of the matrices has an array
shape which do not correspond to the same number of atoms, then they
cannot correspond to the same system. Check the size of the arrays
specified if they have been input manually.
- *Cannot initialize single atom/bead as atom/bead index \_\_ is
larger than the number of atoms/beads*: Self-explanatory. However,
note that indices are counted from 0, so the first replica/atom is
defined by an index 0, the second by an index 1, and so on.
- *Cannot initialize the momenta/masses/labels/single atoms before the
size of the system is known.*: In the code, a beads object is created
to hold all the information related to the configuration of the
system. However, until a position vector has been defined, this
object is not created. Therefore, whichever arrays are being
initialized individually, the position vector must always be
initialized first.
- *Trying to resample velocities before having masses.*: A
Maxwell-Boltzmann distribution is partly defined by the atomic
masses, and so the masses must be defined before the velocities can
be resampled from this distribution.
- *Cannot thermalize a single bead*: It does not make sense to
initialize the momenta of only one of the beads, and so i-PI does not
give this functionality.
- *Initializer could not initialize \_\_*: A property of the system
that is mandatory to properly run the simulation has not been
initialized in either the “initialize” section or the appropriate
section in beads.
- *Ensemble does not have a thermostat to initialize* or *There is
nothing to initialize in non-GLE thermostats* or *Checkpoint file
does not contain usable thermostat data*: These are raised if the
user has tried to initialize the matrices for the GLE thermostats
with a checkpoint file that either does not have a GLE thermostat or
does not have a thermostat at all.
- *Size mismatch in thermostat initialization data*: Called if the
shape of the GLE matrices defined in the checkpoint file is different
from those defined in the new simulation.
- *Replay can only read from PDB or XYZ files – or a single frame from
a CHK file*: If the user specifies a replay ensemble, the state of
the system must be defined by either a configuration file or a
checkpoint file, and cannot be specified manually.
Output errors
-------------
- *The stride length for the \_\_ file output must be positive.*:
Self-explanatory
- *\_\_ is not a recognized property/output trajectory*: The string as
defined in the “properties”/”trajectory” tag does not correspond to
one of the available trajectories. Make sure that both the syntax is
correct, and that the property has been spelt correctly.
- *Could not open file \_\_ for output*: Raised if there is a problem
opening the file defined by the “filename” attribute.
- *Selected bead index \_\_ does not exist for trajectory \_\_*: You
have asked for the trajectory of a bead index greater than the number
of the replicas of the system. Note that indices are counted from 0,
so the first replica is defined by an index 0, the second by an index
1, and so on.
- *Incorrect format in unit specification \_\_*: Usually raised if one
of the curly braces has been neglected.
- *Incorrect format in argument list \_\_*: This will be raised either
if one of the brackets has been neglected, or if the delimiters
between arguments, in this case “;”, are not correct. This is usually
raised if, instead of separating the arguments using “;”, they are
instead separated by “,”, since this causes the property array to be
parsed incorrectly.
- *\_\_ got an unexpected keyword argument \_\_*: This will occur if
one of the argument lists of one of the properties specified by the
user has a keyword argument that does not match any of those in the
function to calculate it. Check the properties.py module to see which
property this function is calculating, and what the correct keyword
arguments are. Then check the “properties” tag, and find which of the
arguments has been misspelt.
- *Must specify the index of atom_vec property*: Any property which
prints out a vector corresponding to one atom needs the index of that
atom, as no default is specified.
- *Cannot output \_\_ as atom/bead index \_\_ is larger than the
number of atoms/beads*: Self-explanatory. However, note that indices
are counted from 0, so the first replica/atom is defined by an index
0, the second by an index 1, and so on.
- *Couldn’t find an atom that matched the argument of \_\_*: For
certain properties, you can specify an atom index or label, so that
the property is averaged only over the atoms that match it. If
however no atom labels match the argument given, then the average
will be undefined. Note that for properties which are cumulatively
counted rather than averaged, this error is not raised, and if no
atom matches the label given 0 will be returned.
Socket errors
-------------
- *Address already in use*: This is called if the server socket is
already being used by the host network. There are several possible
reasons for getting this error. Firstly, it might simply be that two
simulations are running concurrently using the same host and port
number. In this case simply change the port number of one of the
simulations. Secondly, you can get this error if you try to rerun a
simulation that previously threw an exception, since it takes a
minute or so before the host will disconnect the server socket if it
is not shut down cleanly. In this case, simply wait for it to
disconnect, and try again. Finally, you will get this error if you
try to use a restricted port number (i.e. below 1024) while not root.
You should always use a non-restricted port number for i-PI
simulations.
- *Error opening unix socket. Check if a file /tmp/ipi__\_ exists, and
remove it if unused.*: Similar to the above error, but given if you
are using a unix socket rather than an internet socket. Since this
binds locally the socket can be removed by the user, which means that
it is not necessary to wait for the computer to automatically
disconnect an unused server socket.
- *Port number \_\_ out of acceptable range*: The port number must be
between 1 and 65535, and should be greater than 1024. Change the port
number accordingly.
- *Slot number \_\_ out of acceptable range*: The slot number must be
between 1 and 5. Change the slot number accordingly.
- *’NoneType’ object has no attribute ’Up’*: This is called if an
exception is raised during writing the data to output, and so the
thread that deals with the socket is terminated uncleanly. Check the
stack trace for the original exception, since this will be the actual
source of the problem. Also note that, since the socket thread was
not cleaned up correctly, the server socket may not have been
disconnected properly and you may have to wait for a minute before
you can restart a simulation using the same host and port number.
Mathematical errors
-------------------
- *math domain error*: If the cell parameters are defined using the
side lengths and angles, with either a pdb file or using the “abcABC”
initialization mode, then for some value of the angles it is
impossible to construct a valid cell vector matrix. This will cause
the code to attempt to take the square root of a negative number,
which gives this exception.
- *overflow encountered in exp*: Sometimes occurs in *NPT* runs when
the simulation box “explodes”. Make sure you have properly
equilibrated the system before starting and that the timestep is
short enough to not introduce very large integration errors.
I-PI is slow!
-------------
i-PI is not designed to be highly efficient, but it should not be the
bottleneck in your calculations. Most of the time, if you see a major
slow-down, there is a problem with your setup. Here are some tricks
you can try.
- *use a UNIX domain socket*: if you run on a single node, it is much
faster to use `mode="unix"` in your `` classes. This uses
a shared-memory communication process, that avoids much of the
network latency of a TCP/IP socket.
- *reduce latency*: if you have a VERY fast forcefield (with force
evaluation below ~1ms) it might help to set the `` parameter
of `` to a small value, 1e-4s or less
- *reduce I/O*: outputting hundreds of beads configurations at each time
step is going to be slow in any scenario, but particularly so when
using text files and Python. Reduce the output frequency using a larger
`stride`, and/or `flush` less often.
- *reduce the stride of internal checkpoints*: to guarantee that soft
exits leave the simulation in a state that can be restarted safely,
i-PI stores the internal state of the simulation at each step.
Particularly for complicated setups, the overhead can be substantial.
You can reduce the frequency by which the internal state is stored using
the `safe_stride` attribute in the `` tag. Note that doing
so increases the risk that the RESTART file saved upon soft exit will be
inconsistent with the sate of the outputs, so that restarting a simulaiton
will leave broken or discontinuous output files.
- *profile i-PI*: if you still think i-PI is being unreasonably slow,
you can contact the developers - your setup might have revealed some
kind of bottleneck. It will help us if you can also generate a profiler
output from your run (possibly with only a small number of steps).
You can generate a profiler log by running i-PI with `-p` option,
e.g. `i-pi -p input.xml`.
You will need to install the `yappi` profiler.