XML File Format

Version 1.0

Overview

Both init.read_xml and dump.xml 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 xml file looks like this 

<?xml version="1.0" encoding="UTF-8"?>
<hoomd_xml version="1.0">
<!-- 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>

The first line of the file 

<?xml version="1.0" encoding="UTF-8"?>
is just something that must be there to identify that this is an XML file.

The second and last lines signify the start and end of the root node hoomd_xml. The contents of the root node is between these begin and end markers. The version="1.0" attribute specifies the version of the xml file format used when writing this file. 

<hoomd_xml version="1.0">
        <!-- contents of root node -->
</hoomd_xml>

Inside the root node is the configuration node. 

<configuration time_step="0">
        <!-- data nodes go here -->
</configuration>
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 init.read_xml. In files written by HOOMD, time_step will be set to the value of the time step when the system snapshot was taken.

A note on case-sensitivity:

  • 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, init.read_xml 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 content of any node is of course case sensitive.

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

Detailed documentation for each node is below.

Simulation box specification

The <box> node defines the dimensions of the simulation box which particles are placed in.
dump.xml always writes this node.
init.read_xml requires this node be specified.

Example: 

<box units="sigma"  lx="5.1" ly="9.6" lz="15.8"/>
Attributes:
  • units Currently unused. Potentially used for a future feature in HOOMD supporting different units for length, energy, etc...
  • lx Box length in the x direction
  • ly Box length in the y direction
  • lz Box length in the z direction

Particle positions

The <position> node sets the position of each particle in the simulation.
dump.xml optionally writes this node.
init.read_xml requires this node be specified.

Example: 

<position units="sigma">
-1.45 2.21 1.56
8.76 1.02 5.60
5.67 8.30 4.67
</position>
Attributes:
  • units Currently unused. Potentially used for a future feature in HOOMD supporting different units for length, energy, etc...\
  • num (optional) number of particles coming in the node content. This attribute is written by init.read_xml 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 x0 y0 z0 x1 y1 z1 x2 y2 z2 ... x(N-1) y(N-1) z(N-1). Note that you do not need to specify the number of particles anywhere, just add as many as you want and init.read_xml will count them. The particular form of the whitespace used does not matter (space, tab, newline, etc...), the example above uses spaces between x, y, and z and newlines between particles merely to make it more easily human-readable.

All particles must be in the box: x > -Lx/2.0 and x < Lx/2.0 and similarly for y and z.

Particle images

The <image> node sets the box image for each particle in the simulation.
dump.xml optionally writes this node.
init.read_xml does not require this node.
When used in an input file, the images specified are used as the initial condition for the simulation.

Example: 

<image>
-1 -5 12
18 2 -10
13 -5 0
</image>
Attributes:
  • num (optional) number of images coming in the node content. This attribute is written by init.read_xml to potentially aid in making parsers easier to write.

The format of the node data is the same as for <position> (see Particle positions), except that the values must be integers. If specifying both position and image in an input file, be certain to include the same number of particles in each, or init.read_xml will generate an error.

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 

 x + ix * Lx
where x is the particle coordinate, ix is the image and Lx is the box dimension.

Particle velocities

The <velocity> node sets the velocity of each particle in the simulation.
dump.xml optionally writes this node.
init.read_xml does not require this node.
When used in an input file, the velocities specified are used as the initial condition for the simulation.

Example: 

<velocity units="sigma/tau">
-0.5 -1.2 0.4
0.6 2.0 0.01
-0.4 3.0 0.0
</velocity>
Attributes:
  • units Currently unused. Potentially used for a future feature in HOOMD supporting different units for length, energy, etc...
  • num (optional) number of velocities coming in the node content. This attribute is written by init.read_xml to potentially aid in making parsers easier to write.

The format of the node data is the same as for <position> (see Particle positions). If specifying both position and velocity in an input file, be certain to include the same number of particles in each, or init.read_xml will generate an error.

Particle masses

The <mass> node sets the mass of each particle in the simulation.
dump.xml optionally writes this node.
init.read_xml does not require this node (all masses default to 1.0 if it is not specified).

Example: 

<mass>
1.0
2.0
1.0
</mass>
Attributes:
  • num (optional) number of masses coming in the node content. This attribute is written by init.read_xml to potentially aid in making parsers easier to write.

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

Particle diameters

The <diameter> node sets the diameter of each particle in the simulation.
dump.xml optionally writes this node.
init.read_xml does not require this node (all diameters default to 1.0 if it is not specified).

Example: 

<diameter units="sigma">
1.0
2.0
1.0
</diameter>
Attributes:
  • units Currently unused. Potentially used for a future feature in HOOMD supporting different units for length, energy, etc...
  • num (optional) number of masses coming in the node content. This attribute is written by init.read_xml to potentially aid in making parsers easier to write.

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

Particle types

The <type> node sets the type name of each particle in the simulation.
dump.xml optionally writes this node.
init.read_xml requires this node be specified.

Example: 

<type>
A
long_type_name
A
</type>
Attributes:
  • num (optional) number of types coming in the node content. This attribute is written by init.read_xml to potentially aid in making parsers easier to write.

The format of the node data is similar to that of <position> (see Particle positions), 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). Internally, HOOMD assigns no meaning whatsoever to the value of the string you specify so name your particles in ways that are meaningful to you. When performing tasks such as setting the coefficients of a pair force, the type strings given are simply matched up to those specified in the xml file.

If specifying both position and type in an input file, be certain to include the same number of particles in each, or init.read_xml will generate an error.

Bonds between particles

The <bond> node specifies any number of bonds between particles in the simulation.
dump.xml optionally writes this node.
init.read_xml does not require this node

Example: 

<bond>
polymer 0 1
backbone 1 2
</bond>
Attributes:
  • num (optional) number of bonds coming in the node content. This attribute is written by init.read_xml to potentially aid in making parsers easier to write.

The above example creates a bond of type polymer between particle 0 and 1 and one of type backbone between 1 and 2. The general format is type0 idx_a0 idx_b0 type1 idx_a1 idx_b1 .... 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 doesn't result in any additional forces on particles. For that, you must specify a bond force (see bond).

A typical usage would list many bonds of the same type. Coefficients for the associated bond force can be set separately for each bond type by name (for example, see bond.harmonic).

Walls in the simulation box

The <wall> node specifies any number of walls in the simulation box. Walls have no meaning unless a wall force such as wall.lj is specified in the simulation.
dump.xml optionally writes this node.
init.read_xml does not require this node

Example: 

<wall>
<coord ox="1.0" oy="2.0" oz="3.0" nx="4.0" ny="5.0" nz="6.0"/>
<coord ox="7.0" oy="8.0" oz="9.0" nx="10.0" ny="11.0" nz="-12.0"/>
</wall>

Every wall is specified by a plane. The vector (ox, oy, oz) is the origin, a point in the plane and (nx, ny, nz) is the normal.

Generated on Tue Mar 24 17:40:34 2009 for HOOMD by doxygen 1.5.7.1

Home