// Copyright (c) 2009-2016 The Regents of the University of Michigan
// This file is part of the HOOMD-blue project, released under the BSD 3-Clause License.


/*! \page page_xml_file_format XML File Format
<center><b>Version 1.7</b></center>

\section sec_xml_overview Overview

Both \link hoomd_script.init.read_xml init.read_xml\endlink and \link hoomd_script.dump.xml dump.xml\endlink
work with the same XML file format for specifying the system of particles. The format requires a minimal
amount of meta-information in an easy to understand human-readable format. One of the key advantages of using
XML is that it is also easily machine readable and commonly used, so many parsers exist for it.

The basic outline of a HOOMD-blue xml file looks like this
\code
<?xml version="1.0" encoding="UTF-8"?>
<hoomd_xml version="1.7">
<!-- this is a comment, you can put as many of these in the file
    wherever you wish to. -->
<configuration time_step="0">
    <!-- data nodes go here -->
</configuration>
</hoomd_xml>
\endcode

The first line of the file
~~~~
<?xml version="1.0" encoding="UTF-8"?>
~~~~
**must** be there to identify that this is an XML file.

\code
<hoomd_xml version="1.7">
    <!-- contents of root node -->
</hoomd_xml>
\endcode

The second and last lines signify the start and end of the root node `hoomd_xml`.
The contents of the root node are between these begin and end markers. The `version="1.7"`
attribute specifies the version of the xml file format used when writing this file.
Files with the same major version are fully backward and partially forward compatible
with each other, i.e. a version 1.3 reader should be able to read a version 1.1
file without a problem and use it for as long as the simulation requires no node
that was introduced in a later version and is thus not available. A version 1.0
reader will skip nodes that were not available at that time.

Inside the root node is the configuration node.
\code
<configuration time_step="0" dimensions="3" vizsigma="1.5">
    <!-- data nodes go here -->
</configuration>
\endcode
`time_step="0"` is an attribute assigned to the configuration node. You can leave if off if you want
and the time step will default to 0. It is used as the initial time step in the simulation when read
by \link hoomd_script.init.read_xml init.read_xml\endlink. In files written by hoomd, `time_step`
will be set to the value of the time step when the system snapshot was taken.

(Version 1.2 and newer)<br>
`dimensions="#"` specifies the dimensionality of the system. Valid values are 2 and 3, the
default is 3 when `dimensions` is not specified. Setting `dimensions="2"` does \b NOT change anything else in the file.
For example, you still must specify 3 components for position and velocity, just set the 3rd component to 0
for 2D simulations. Specify a small, but non-zero z-dimension for the box when `dimensions="2"`.

(Version 1.4 and newer)<br>
`vizsigma="#"` specifies a scaling factor for the radius of particles. It is used by VMD when no `diameter` node
is present. It is ignored when read by \link hoomd_script.init.read_xml init.read_xml\endlink.

(all versions)
- All node names and attributes are in all lower case. As XML is a case
    sensitive file format, all readers and writers must adhere to this. However, \link hoomd_script.init.read_xml init.read_xml\endlink
    will try to be generous and handle any possible typos that a user makes on entering data and will accept
    files with varying cases.
- The \b content of any node is always case sensitive.

A number of data nodes can be included inside the configuration node <b>in any order</b>.

 - \b box (\ref sec_xml_box)
 - \b position (\ref sec_xml_position)
 - \b image (\ref sec_xml_image)
 - \b velocity (\ref sec_xml_velocity)
 - \b acceleration (\ref sec_xml_acceleration)
 - \b mass (\ref sec_xml_mass)
 - \b charge (\ref sec_xml_charge)
 - \b diameter (\ref sec_xml_diameter)
 - \b type (\ref sec_xml_type)
 - \b body (\ref sec_xml_body)
 - \b orientation (\ref sec_xml_orientation)
 - \b angmom (\ref sec_xml_angmom)
 - \b moment_inertia (\ref sec_xml_moment_inertia)
 - \b bond (\ref sec_xml_bond)
 - \b angle (\ref sec_xml_angle)
 - \b dihedral (\ref sec_xml_dihedral)
 - \b improper (\ref sec_xml_improper)
 - \b constraint (\ref sec_xml_constraint)

\section sec_xml_box Simulation box specification

The \<box\> node defines the dimensions of the simulation box which particles are placed in.<br>
\link hoomd_script.dump.xml dump.xml\endlink \b always writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink \b requires this node be specified.<br>
Version: 1.0 and newer

\b Example:
~~~~
<box lx="5.1" ly="9.6" lz="15.8" xy="1" yz="0" lz="0">
~~~~
\b Attributes:
 - \a lx Box length in the \b x direction
 - \a ly Box length in the \b y direction
 - \a lz Box length in the \b z direction
 - \a xy Box tilt factor in the \b xy plane (defaults to 0 if not specified)
 - \a xz Box tilt factor in the \b xz plane (defaults to 0 if not specified)
 - \a yz Box tilt factor in the \b yz plane (defaults to 0 if not specified)

(Version 1.5 and newer)<br>
`xy="#" xz="#" yz="#"` specifies the tilt factors for the triclinic unit cell. If they are zero, the box is orthorhombic.

\section sec_xml_position Particle positions

The `<position>` node sets the position of each particle in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink \b requires this node.<br>
Version: 1.0 and newer

\b Example:
~~~~
<position>
-1.45 2.21 1.56
8.76 1.02 5.60
5.67 8.30 4.67
</position>
~~~~
\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

In between the begin and end markers `<position>` and `</position>` is a series of floating point
numbers in plain-text separated by whitespace. These are read in order <i>x0 y0 z0 x1 y1 z1 x2
y2 z2 ... x(N-1) y(N-1) z(N-1)</i>. Note that you do not need to specify the number of particles
anywhere, just add as many as you want and \link hoomd_script.init.read_xml init.read_xml\endlink
will count them. The particular form of the whitespace used does not matter (space, tab, newline,
etc...), the example above uses spaces between \em x, \em y, and \em z and newlines between
particles merely to make it more easily human-readable.

All particles in the simulation can be referenced by a *tag*. \<position\> (and all other XML nodes that list
per-particle properties) list particles in <b>tag order</b>. That is, the first particle listed has tag 0, the
second has tag 1, ..., and the last has tag <i>N</i>-1 where \a N is the number of particles in the simulation.

All particles must be in the box:<br>
\f$ x > -Lx/2 + (xz-xy*yz)*z + xy * y\f$  and \f$ x < Lx/2 + (xz-xy*yz)*z + xy * y \f$ <br>
\f$ y > -Ly/2 + yz * z\f$  and \f$ y < Ly/2 + yz*z\f$<br>
\f$ z > -Lz/2\f$  and \f$ z < Lz/2 \f$<br>

\section sec_xml_image Particle images
The `<image>` node sets the box image for each particle in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node.<br>
Version: 1.0 and newer<br>
When used in an input file, the images specified are used as the initial condition for the simulation.

\b Example:
~~~~
<image>
-1 -5 12
18 2 -10
13 -5 0
</image>
~~~~
\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The format of the node data is the same as for `<position>` (see \ref sec_xml_position), except that the
values must be integers. If specifying both position and image in an input file, include the
same number of particles in each.

Image flags are used to track the movement of particles across the periodic boundary conditions. To unwrap
the position of a single particle and see its trajectory as if it did not wrap around the boundary,
compute

~~~~
x0 = x + ix * Lx + xy * iy * Ly + xz * iz * Lz
y0 = x + iy * Ly + yz * iz * Lz
z0 = z + iz * Lz
~~~~
where `x`, `y`, `z` are the wrapped particle coordinates, `x0`, `y0`, `z0` are the unwrapped
particle coordinates, `ix`, `iy`, `iz` are the periodic image flags, `Lx`, `Ly`, `Lz` are the
box lengths, and `xy`, `xz`, `yz` are the tilt factors.

\section sec_xml_velocity Particle velocities

The `<velocity>` node sets the velocity of each particle in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node.<br>
Version: 1.0 and newer<br>
When used in an input file, the velocities specified are used as the initial condition for the simulation.

\b Example:
~~~~
<velocity>
-0.5 -1.2 0.4
0.6 2.0 0.01
-0.4 3.0 0.0
</velocity>
~~~~
\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The format of the node data is the same as for `<position>` (see \ref sec_xml_position). If specifying
both position and velocity in an input file, include the same number of particles in each.

\section sec_xml_acceleration Particle accelerations
The `<accelleration>` node indicates the instantaneous acceleration of each particle in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink \b ignores this node - acceleration is a computed quantity.<br>
Version: 1.2 and newer<br>

The format of the node data is the same as for `<position>` (see \ref sec_xml_position).

\section sec_xml_mass Particle masses

The `<mass>` node sets the mass of each particle in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node (all masses default to 1.0 if it is not specified).<br>
Version: 1.0 and newer

\b Example:
~~~~
<mass>
1.0
2.0
1.0
</mass>
~~~~
\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The format of the node data is the same as for `<position>` (see \ref sec_xml_position), except that only one value
per particle is specified.

\section sec_xml_charge Particle charges
The `<charge>` node sets the charge of each particle in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node (all charges default to 0.0 when it is not specified).<br>
Version: 1.3 and newer

\b Example:
~~~~
<charge>
1.0
2.0
-3.0
</charge>
~~~~

\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The format of the node data is the same as for `<position>` (see \ref sec_xml_position), except that only one value
per particle is specified.

\section sec_xml_diameter Particle diameters

The `<diameter>` node sets the diameter of each particle in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node (all diameters default to 1.0 when it is not specified).<br>
Version: 1.0 and newer

\b Example:
~~~~
<diameter>
1.0
2.0
1.0
</diameter>
~~~~

\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The format of the node data is the same as for `<position>` (see \ref sec_xml_position), except that only one value
per particle is specified.

\section sec_xml_type Particle types

The `<type>` node sets the type name of each particle in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink \b requires this node be specified.<br>
Version: 1.0 and newer

\b Example:
~~~~
<type>
A
long_type_name
A
</type>
~~~~

\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The format of the node data is similar to that of `<position>` (see \ref sec_xml_position),
except that only one type is specified for each particle. A particle type can be *any*
string you want that does not include whitespace (as whitespace is used to signify
the next particle in the list). HOOMD-blue does not interpret type names in any special way, assign your type names
to any string meaningful to you. When setting the coefficients of a \link hoomd_script.pair pair\endlink
force, the type strings are matched up to those specified in the xml file.

If specifying both position and type in an input file, include the same number of particles in each.

\section sec_xml_body Rigid body assignments

The `<body>` node specifies the rigid body (if any) in which each particles belongs.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node<br>
Version: 1.4 and newer

\b Example:
~~~~
<body>
-1
0
0
</body>
~~~~

\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The format of the node data is similar to that of `<position>` (see \ref sec_xml_position),
except that only one integer is specified for each particle. Set a value of -1 to particles that are not part
of any rigid body. For all of the particles contained within each rigid body, set the same integer value for each
of them. The value assigned also serves as the index of the rigid body in an array, so all rigid bodies must be numbered
from 0 up to the number of rigid bodies minus one. All body flags default to -1 if the `<body>` node is not specified.

When specifying both position and body in an input file, include the same number of particles in each.

\section sec_xml_orientation Particle orientation

The `<orientation>` node specifies the orientation of each particle as a quaternion.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node<br>
Version: 1.4 and newer

\b Example:
~~~~
<orientation>
1 0 0 0
0.0333   -0.0667    0.1000    0.1333
</orientation>
~~~~

\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The format of the node data is similar to that of `<position>` (see \ref sec_xml_position),
except that four scalar values are specified for each particle. Each group of four values represents a quaternion,
where (1 0 0 0) is the unit quaternion.

When specifying both position and orientation in an input file, include the same number of particles in each.

\section sec_xml_angmom Particle angular momentum

The `<angmom>` node specifies the angular momentum of each particle as a quaternion.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node<br>
Version: 1.6 and newer

\b Example:
~~~~
<angmom>
1 0 0 0
0.0333   -0.0667    0.1000    0.1333
</angmom>
~~~~

\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The format of the node data is similar to that of `<position>` (see \ref sec_xml_position),
except that four scalar values are specified for each particle. Each group of four values represents a quaternion,
where (1 0 0 0) is the unit quaternion.

When specifying both position and angmom in an input file, include the same number of particles in each.

\section sec_xml_moment_inertia Particle moment of inertia

The `<moment_inertia>` node specifies the principal moments of inertia of each particle \f$(I_{xx}, I_{yy}, I_{zz})\f$.<br>
With 1.4 <= XML version < 1.6, this property contained all six components of the inertia tensor, \f$I_{ij}\f$.
If an XML file within that version range is read, only the diagonal components of the tensor are taken.
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node<br>
Version: 1.4-1.5 (tensor version), 1.6 and newer

\b Example:
~~~~
<moment_inertia>
1 2 3
1 4 6
</moment_inertia>
~~~~

\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The format of the node data is similar to that of `<position>` (see \ref sec_xml_position).
Each group of three values represents a moment of inertia tensor elements (in order) \f$I_{xx}\f$ \f$I_{yy}\f$ \f$I_{zz}\f$.

When specifying both position and moment_inertia in an input file, include the same number of particles in each.

\section sec_xml_bond Bonds between particles

The `<bond>` node specifies any number of bonds between particles in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node<br>
Version: 1.0 and newer

Example:
~~~~
<bond>
polymer 0 1
backbone 1 2
</bond>
~~~~

\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The above example creates a bond of type \em polymer between particle 0 and 1 and one of type
*backbone* between 1 and 2. The general format is <i>type0 idx_a0 idx_b0 type1 idx_a1 idx_b1 ....</i>
where type is any string without whitespace, idx_a is the index of the first particle in the bond and
idx_b is the index of the second particle in the bond. Each field is separated from the next by
whitespace (any number of spaces, tabs, or newlines).

Specifying the bonds themselves does not result in any additional forces on particles. For
that, you must specify a bond force (see \link hoomd_script.bond bond\endlink). Coefficients for the associated bond
force can be set separately for each bond type by name (for example, see \link hoomd_script.bond.harmonic
bond.harmonic\endlink).

\section sec_xml_angle Angles between three particles

The `<angle>` node specifies any number of angles between particles in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node<br>
Version: 1.1 and newer

Example:
~~~~
<angle>
A-B-A 0 1 2
B-A-A 1 2 3
</angle>
~~~~

\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The above example creates a angle of type \em A-B-A between particles 0, 1, and 2 and one of type
\em B-A-A between particles 1, 2, and 3. The general format is <i>type0 idx_a0 idx_b0 idx_c0 type1 idx_a1 idx_b1 idx_c1....</i>
where type is any string without whitespace, idx_a is the index of the first particle in the angle,
idx_b is the index of the middle particle in the angle, and idx_c the index of the third particle of the angle.
Each field is separated from the next by whitespace (any number of spaces, tabs, or newlines).

Specifying the angles themselves doesn't result in any additional forces on particles. For
that, you must specify a angle force (see \link hoomd_script.angle angle\endlink).
Coefficients for the associated angle force can be set separately for each angle type by name (for example, see
\link hoomd_script.angle.harmonic angle.harmonic\endlink).

\section sec_xml_dihedral Dihedral Angles between four particles

The `<dihedral>` node specifies any number of dihedrals between particles in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node<br>
Version: 1.1 and newer

Example:
~~~~
<dihedral>
A-B-A-A 0 1 2 3
B-A-A-C 1 2 3 4
</dihedral>
~~~~

\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The above example creates a dihedral of type \em A-B-A-A between particles 0, 1, 2, and 3 and one of type
\em B-A-A-C between particles 1, 2, 3, and 4. The general format is <i>type0 idx_a0 idx_b0 idx_c0 idx_d0 type1 idx_a1 idx_b1 idx_c1 idx_d1....</i>
where type is any string without whitespace, idx_a is the index of the first particle in the dihedral,
idx_b and idx_c are the indices of the bond around which the dihedral is considered, and idx_d the index of the last particle of the dihedral.
Each field is separated from the next by whitespace (any number of spaces, tabs, or newlines).

Specifying the dihedrals themselves doesn't result in any additional forces on particles. For
that, you must specify a dihedral force (see \link hoomd_script.dihedral dihedral\endlink). Coefficients for the
associated dihedral force can be set separately for each dihedral type by name
(for example, see \link hoomd_script.dihedral.harmonic dihedral.harmonic\endlink).

\section sec_xml_improper Improper Dihedral Angles between four particles

The `<improper>` node specifies any number of improper dihedrals between particles in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node<br>
Version: 1.1 and newer

Example:
~~~~
<improper>
A-B-A-A 0 1 2 3
B-A-A-C 1 2 3 4
</improper>
~~~~

\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The above example creates an improper dihedral of type \em A-B-A-A between particles 0, 1, 2, and 3 and one of type
\em B-A-A-C between particles 1, 2, 3, and 4. The general format is <i>type0 idx_a0 idx_b0 idx_c0 idx_d0 type1 idx_a1 idx_b1 idx_c1 idx_d1....</i>
where type is any string without whitespace, idx_a is the index of the first particle in the improper dihedral,
idx_b and idx_c are the indices of the bond around which the improper dihedral is considered, and idx_d the index
of the last particle of the dihedral. Each field is separated from the next by whitespace (any number of spaces,
tabs, or newlines).

Specifying the improper dihedrals themselves doesn't result in any additional forces on particles. For
that, you must specify an improper force (see \link hoomd_script.improper improper\endlink). Coefficients for the
associated improper force can be set separately for each improper type by name (for example,
see \link hoomd_script.improper.harmonic improper.harmonic\endlink).

\section sec_xml_constraint Pairwise distance constraints

The `<constraint>` node specifies any number of constraints between particles in the simulation.<br>
\link hoomd_script.dump.xml dump.xml\endlink \em optionally writes this node.<br>
\link hoomd_script.init.read_xml init.read_xml\endlink does not require this node<br>
Version: 1.7 and newer

Example:
~~~~
<constraint>
0 1 1.5
1 2 2.5
</constraint>
~~~~

\b Attributes:

- \a num (\b optional) number of particles coming in the node content. This attribute is written by
    \link hoomd_script.dump.xml dump.xml\endlink to potentially aid in making parsers easier to write.

The above example creates two constraints: the first constraint between particles 0 and 1, with a
fixed distance of 1.5, the second constraint between particles 1 and 2, with a distance of 2.5.

Specifying the constraints themselves doesn't result in any additional forces on particles. For
that, you must specify a distance constraint force (see \link hoomd_script.constrain.distance distance \endlink).

*/
