HOOMD Schema
HOOMDblue supports a wide variety of per particle attributes and properties.
Particles, bonds, and types can be dynamically added and removed during
simulation runs. The hoomd
schema can handle all of these situations in a
reasonably space efficient and high performance manner. It is also backwards
compatible with previous versions of itself, as we only add new additional data
chunks in new versions and do not change the interpretation of the existing data
chunks. Any newer reader will initialize new data chunks with default values
when they are not present in an older version file.
 Schema name
hoomd
 Schema version
1.4
See also
hoomd.State
for a full description of how HOOMD interprets this
data.
Usecases
The GSD schema hoomd
provides:
Every frame of GSD output is viable to restart a simulation
Support varying numbers of particles, bonds, etc…
Support varying attributes (type, mass, etc…)
Support orientation, angular momentum, and other fields.
Binary format on disk
High performance file read and write
Support logging computed quantities
Data chunks
Each frame the hoomd
schema may contain one or more data chunks. The layout
and names of the chunksmatch that of the binary snapshot API in HOOMDblue
itself. Data chunks are organized in categories. These categories have no
meaning in the hoomd
schema specification, and are simply an organizational
tool. Some file writers may implement options that act on categories (i.e. write
attributes out to every frame, or just frame 0).
Values are well defined for all fields at all frames. When a data chunk is present in frame i, it defines the values for the frame. When it is not present, the data chunk of the same name at frame 0 defines the values for frame i (when N is equal between the frames). If the data chunk is not present in frame 0, or N differs between frames, values are default. Default values allow files sizes to remain small. For example, a simulation with point particles where orientation is always (1,0,0,0) would not write any orientation chunk to the file.
N may be zero. When N is zero, an index entry may be written for a data chunk with no actual data written to the file for that chunk.
Name 
Category 
Type 
Size 
Default 
Units 

Configuration 

uint64 
1x1 
0 
number 

uint8 
1x1 
3 
number 

float 
6x1 
varies 

Particle data 

attribute 
uint32 
1x1 
0 
number 

attribute 
int8 
NTxM 
[‘A’] 
UTF8 

attribute 
uint32 
Nx1 
0 
number 

attribute 
int8 
NTxM 
UTF8 

attribute 
float 
Nx1 
1.0 
mass 

attribute 
float 
Nx1 
0.0 
charge 

attribute 
float 
Nx1 
1.0 
length 

attribute 
int32 
Nx1 
1 
number 

attribute 
float 
Nx3 
0,0,0 
mass * length^2 

property 
float 
Nx3 
0,0,0 
length 

property 
float 
Nx4 
1,0,0,0 
unit quaternion 

momentum 
float 
Nx3 
0,0,0 
length/time 

momentum 
float 
Nx4 
0,0,0,0 
quaternion 

momentum 
int32 
Nx3 
0,0,0 
number 

Bond data 

topology 
uint32 
1x1 
0 
number 

topology 
int8 
NTxM 
UTF8 

topology 
uint32 
Nx1 
0 
number 

topology 
uint32 
Nx2 
0,0 
number 

Angle data 

topology 
uint32 
1x1 
0 
number 

topology 
int8 
NTxM 
UTF8 

topology 
uint32 
Nx1 
0 
number 

topology 
uint32 
Nx3 
0,0,0 
number 

Dihedral data 

topology 
uint32 
1x1 
0 
number 

topology 
int8 
NTxM 
UTF8 

topology 
uint32 
Nx1 
0 
number 

topology 
uint32 
Nx4 
0,0,0,0 
number 

Improper data 

topology 
uint32 
1x1 
0 
number 

topology 
int8 
NTxM 
UTF8 

topology 
uint32 
Nx1 
0 
number 

topology 
uint32 
Nx4 
0,0,0,0 
number 

Constraint data 

topology 
uint32 
1x1 
0 
number 

topology 
float 
Nx1 
0 
length 

topology 
uint32 
Nx2 
0,0 
number 

Special pairs data 

topology 
uint32 
1x1 
0 
number 

topology 
int8 
NTxM 
utf8 

topology 
uint32 
Nx1 
0 
number 

topology 
uint32 
Nx2 
0,0 
number 
Configuration
 configuration/step
 Type
uint64
 Size
1x1
 Default
0
 Units
number
Simulation time step.
 configuration/dimensions
 Type
uint8
 Size
1x1
 Default
3
 Units
number
Number of dimensions in the simulation. Must be 2 or 3.
Note
When using
gsd.hoomd.Snapshot
, the object will try to intelligently default to a dimension. When setting a box with \(L_z = 0\),dimensions
will default to 2 otherwise 3. Explicit setting of this value by users always takes precedence.
 configuration/box
 Type
float
 Size
6x1
 Default
[1,1,1,0,0,0]
 Units
varies
Simulation box. Each array element defines a different box property. See the hoomd documentation for a full description on how these box parameters map to a triclinic geometry.
box[0:3]
: \((l_x, l_y, l_z)\) the box length in each direction, in length unitsbox[3:]
: \((xy, xz, yz)\) the tilt factors, dimensionless values
Particle data
Within a single frame, the number of particles N and NT are fixed for all chunks. N and NT may vary from one frame to the next. All values are stored in hoomd native units.
Attributes
 particles/N
 Type
uint32
 Size
1x1
 Default
0
 Units
number
Define N, the number of particles, for all data chunks
particles/*
.
 particles/types
 Type
int8
 Size
NTxM
 Default
[‘A’]
 Units
UTF8
Implicitly define NT, the number of particle types, for all data chunks
particles/*
. M must be large enough to accommodate each type name as a null terminated UTF8 character string. Row i of the 2D matrix is the type name for particle type i.
 particles/typeid
 Type
uint32
 Size
Nx1
 Default
0
 Units
number
Store the type id of each particle. All id’s must be less than NT. A particle with type id has a type name matching the corresponding row in
particles/types
.
 particles/type_shapes
 Type
int8
 Size
NTxM
 Default
empty
 Units
UTF8
Store a pertype shape definition for visualization. A dictionary is stored for each of the NT types, corresponding to a shape for visualization of that type. M must be large enough to accommodate the shape definition as a nullterminated UTF8 JSONencoded string. See: Shape Visualization for examples.
 particles/mass
 Type
float (32bit)
 Size
Nx1
 Default
1.0
 Units
mass
Store the mass of each particle.
 particles/charge
 Type
float (32bit)
 Size
Nx1
 Default
0.0
 Units
charge
Store the charge of each particle.
 particles/diameter
 Type
float (32bit)
 Size
Nx1
 Default
1.0
 Units
length
Store the diameter of each particle.
 particles/body
 Type
int32
 Size
Nx1
 Default
1
 Units
number
Store the composite body associated with each particle. The value 1 indicates no body. The body field may be left out of input files, as hoomd will create the needed constituent particles.
 particles/moment_inertia
 Type
float (32bit)
 Size
Nx3
 Default
0,0,0
 Units
mass * length^2
Store the moment_inertia of each particle \((I_{xx}, I_{yy}, I_{zz})\). This inertia tensor is diagonal in the body frame of the particle. The default value is for point particles.
Properties
 particles/position
 Type
float (32bit)
 Size
Nx3
 Default
0,0,0
 Units
length
Store the position of each particle (x, y, z).
All particles in the simulation are referenced by a tag. The position data chunk (and all other per particle data chunks) list particles in tag order. The first particle listed has tag 0, the second has tag 1, …, and the last has tag N1 where N is the number of particles in the simulation.
All particles must be inside the box:
\(l_x/2 + (xzxy \cdot yz) \cdot z + xy \cdot y \le x < l_x/2 + (xzxy \cdot yz) \cdot z + xy \cdot y\)
\(l_y/2 + yz \cdot z \le y < l_y/2 + yz \cdot z\)
\(l_z/2 \le z < l_z/2\)
Where \(l_x\), \(l_y\), \(l_z\), \(xy\), \(xz\), and \(yz\) are the simulation box parameters (
configuration/box
).
 particles/orientation
 Type
float (32bit)
 Size
Nx4
 Default
1,0,0,0
 Units
unit quaternion
Store the orientation of each particle. In scalar + vector notation, this is \((r, a_x, a_y, a_z)\), where the quaternion is \(q = r + a_xi + a_yj + a_zk\). A unit quaternion has the property: \(\sqrt{r^2 + a_x^2 + a_y^2 + a_z^2} = 1\).
Momenta
 particles/velocity
 Type
float (32bit)
 Size
Nx3
 Default
0,0,0
 Units
length/time
Store the velocity of each particle \((v_x, v_y, v_z)\).
 particles/angmom
 Type
float (32bit)
 Size
Nx4
 Default
0,0,0,0
 Units
quaternion
Store the angular momentum of each particle as a quaternion. See the HOOMD documentation for information on how to convert to a vector representation.
 particles/image
 Type
int32
 Size
Nx3
 Default
0,0,0
 Units
number
Store the number of times each particle has wrapped around the box \((i_x, i_y, i_z)\). In constant volume simulations, the unwrapped position in the particle’s full trajectory is
\(x_u = x + i_x \cdot l_x + xy \cdot i_y \cdot l_y + xz \cdot i_z \cdot l_z\)
\(y_u = y + i_y \cdot l_y + yz \cdot i_z \cdot l_z\)
\(z_u = z + i_z \cdot l_z\)
Topology
 bonds/N
 Type
uint32
 Size
1x1
 Default
0
 Units
number
Define N, the number of bonds, for all data chunks
bonds/*
.
 bonds/types
 Type
int8
 Size
NTxM
 Default
empty
 Units
UTF8
Implicitly define NT, the number of bond types, for all data chunks
bonds/*
. M must be large enough to accommodate each type name as a null terminated UTF8 character string. Row i of the 2D matrix is the type name for bond type i. By default, there are 0 bond types.
 bonds/typeid
 Type
uint32
 Size
Nx1
 Default
0
 Units
number
Store the type id of each bond. All id’s must be less than NT. A bond with type id has a type name matching the corresponding row in
bonds/types
.
 bonds/group
 Type
uint32
 Size
Nx2
 Default
0,0
 Units
number
Store the particle tags in each bond.
 angles/N
 Type
uint32
 Size
1x1
 Default
0
 Units
number
Define N, the number of angles, for all data chunks
angles/*
.
 angles/types
 Type
int8
 Size
NTxM
 Default
empty
 Units
UTF8
Implicitly define NT, the number of angle types, for all data chunks
angles/*
. M must be large enough to accommodate each type name as a null terminated UTF8 character string. Row i of the 2D matrix is the type name for angle type i. By default, there are 0 angle types.
 angles/typeid
 Type
uint32
 Size
Nx1
 Default
0
 Units
number
Store the type id of each angle. All id’s must be less than NT. A angle with type id has a type name matching the corresponding row in
angles/types
.
 angles/group
 Type
uint32
 Size
Nx3
 Default
0,0,0
 Units
number
Store the particle tags in each angle.
 dihedrals/N
 Type
uint32
 Size
1x1
 Default
0
 Units
number
Define N, the number of dihedrals, for all data chunks
dihedrals/*
.
 dihedrals/types
 Type
int8
 Size
NTxM
 Default
empty
 Units
UTF8
Implicitly define NT, the number of dihedral types, for all data chunks
dihedrals/*
. M must be large enough to accommodate each type name as a null terminated UTF8 character string. Row i of the 2D matrix is the type name for dihedral type i. By default, there are 0 dihedral types.
 dihedrals/typeid
 Type
uint32
 Size
Nx1
 Default
0
 Units
number
Store the type id of each dihedral. All id’s must be less than NT. A dihedral with type id has a type name matching the corresponding row in
dihedrals/types
.
 dihedrals/group
 Type
uint32
 Size
Nx4
 Default
0,0,0,0
 Units
number
Store the particle tags in each dihedral.
 impropers/N
 Type
uint32
 Size
1x1
 Default
0
 Units
number
Define N, the number of impropers, for all data chunks
impropers/*
.
 impropers/types
 Type
int8
 Size
NTxM
 Default
empty
 Units
UTF8
Implicitly define NT, the number of improper types, for all data chunks
impropers/*
. M must be large enough to accommodate each type name as a null terminated UTF8 character string. Row i of the 2D matrix is the type name for improper type i. By default, there are 0 improper types.
 impropers/typeid
 Type
uint32
 Size
Nx1
 Default
0
 Units
number
Store the type id of each improper. All id’s must be less than NT. A improper with type id has a type name matching the corresponding row in
impropers/types
.
 impropers/group
 Type
uint32
 Size
Nx4
 Default
0,0,0,0
 Units
number
Store the particle tags in each improper.
 constraints/N
 Type
uint32
 Size
1x1
 Default
0
 Units
number
Define N, the number of constraints, for all data chunks
constraints/*
.
 constraints/value
 Type
float
 Size
Nx1
 Default
0
 Units
length
Store the distance of each constraint. Each constraint defines a fixed distance between two particles.
 constraints/group
 Type
uint32
 Size
Nx2
 Default
0,0
 Units
number
Store the particle tags in each constraint.
 pairs/N
 Type
uint32
 Size
1x1
 Default
0
 Units
number
Define N, the number of special pair interactions, for all data chunks
pairs/*
.New in version 1.1.
 pairs/types
 Type
int8
 Size
NTxM
 Default
empty
 Units
UTF8
Implicitly define NT, the number of special pair types, for all data chunks
pairs/*
. M must be large enough to accommodate each type name as a null terminated UTF8 character string. Row i of the 2D matrix is the type name for particle type i. By default, there are 0 special pair types.New in version 1.1.
 pairs/typeid
 Type
uint32
 Size
Nx1
 Default
0
 Units
number
Store the type id of each special pair interaction. All id’s must be less than NT. A pair with type id has a type name matching the corresponding row in
pairs/types
.New in version 1.1.
 pairs/group
 Type
uint32
 Size
Nx2
 Default
0,0
 Units
number
Store the particle tags in each special pair interaction.
New in version 1.1.
Logged data
Users may store logged data in log/*
data chunks. Logged data encompasses
values computed at simulation time that are too expensive or cumbersome to
recompute in post processing. This specification does not define specific chunk
names or define logged data. Users may select any valid name for logged data
chunks as appropriate for their workflow.
For any named logged data chunks present in any frame frame the file: If a chunk is not present in a given frame i != 0, the implementation should provide the quantity as read from frame 0 for that frame. GSD files that include a logged data chunk only in some frames i != 0 and not in frame 0 are invalid.
By convention, perparticle and perbond logged data should have a chunk name
starting with log/particles/
and log/bonds
, respectively. Scalar,
vector, and string values may be stored under a different prefix starting with
log/
. This specification may recognize additional conventions in later
versions without invalidating existing files.
Name 
Type 
Size 
Units 

n/a 
NxM 
userdefined 

n/a 
NxM 
userdefined 

n/a 
NxM 
userdefined 
 log/particles/user_defined
 Type
userdefined
 Size
NxM
 Units
userdefined
This chunk is a place holder for any number of user defined perparticle quantities. N is the number of particles in this frame. M, the data type, the units, and the chunk name (after the prefix
log/particles/
) are userdefined.New in version 1.4.
 log/bonds/user_defined
 Type
userdefined
 Size
NxM
 Units
userdefined
This chunk is a place holder for any number of user defined perbond quantities. N is the number of bonds in this frame. M, the data type, the units, and the chunk name (after the prefix
log/bonds/
) are userdefined.New in version 1.4.
 log/user_defined
 Type
userdefined
 Size
NxM
 Units
userdefined
This chunk is a place holder for any number of user defined quantities. N, M, the data type, the units, and the chunk name (after the prefix
log/
) are userdefined.New in version 1.4.
State data
HOOMD stores auxiliary state information in state/*
data chunks. Auxiliary
state encompasses internal state to any integrator, updater, or other class that
is not part of the particle system state but is also not a fixed parameter. For
example, the internal degrees of freedom in integrator. Auxiliary state is
useful when restarting simulations.
HOOMD only stores state in GSD files when requested explicitly by the user. Only a few of the documented state data chunks will be present in any GSD file and not all state chunks are valid. Thus, state data chunks do not have default values. If a chunk is not present in the file, that state does not have a welldefined value.
Note
HOOMDblue >= v3.0.0 do not write state data.
Name 
Type 
Size 
Units 

HPMC integrator state 

double 
1x1 
length 

double 
1x1 
number 

float 
NTx1 
length 

uint8 
NTx1 
boolean 

float 
NTx1 
length 

float 
NTx1 
length 

float 
NTx1 
length 

uint32 
NTx1 
number 

float 
sum(N)x3 
length 

uint32 
NTx1 
number 

float 
sum(N)x3 
length 

float 
NTx1 
length 

uint32 
NTx1 
number 

float 
sum(N)x2 
length 

uint32 
NTx1 
number 

float 
sum(N)x2 
length 

float 
NTx1 
length 

uint32 
NTx1 
number 

float 
sum(N)x2 
length 
HPMC integrator state
NT is the number of particle types.
 state/hpmc/integrate/d
 Type
double
 Size
1x1
 Units
length
d is the maximum trial move displacement.
New in version 1.2.
 state/hpmc/integrate/a
 Type
double
 Size
1x1
 Units
number
a is the size of the maximum rotation move.
New in version 1.2.
 state/hpmc/sphere/radius
 Type
float
 Size
NTx1
 Units
length
Sphere radius for each particle type.
New in version 1.2.
 state/hpmc/sphere/orientable
 Type
uint8
 Size
NTx1
 Units
boolean
Orientable flag for each particle type.
New in version 1.3.
 state/hpmc/ellipsoid/a
 Type
float
 Size
NTx1
 Units
length
Size of the first ellipsoid semiaxis for each particle type.
New in version 1.2.
 state/hpmc/ellipsoid/b
 Type
float
 Size
NTx1
 Units
length
Size of the second ellipsoid semiaxis for each particle type.
New in version 1.2.
 state/hpmc/ellipsoid/c
 Type
float
 Size
NTx1
 Units
length
Size of the third ellipsoid semiaxis for each particle type.
New in version 1.2.
 state/hpmc/convex_polyhedron/N
 Type
uint32
 Size
NTx1
 Units
number
Number of vertices defined for each type.
New in version 1.2.
 state/hpmc/convex_polyhedron/vertices
 Type
float
 Size
sum(N)x3
 Units
length
Position of the vertices in the shape for all types. The shape for type 0 is the first N[0] vertices, the shape for type 1 is the next N[1] vertices, and so on…
New in version 1.2.
 state/hpmc/convex_spheropolyhedron/N
 Type
uint32
 Size
NTx1
 Units
number
Number of vertices defined for each type.
New in version 1.2.
 state/hpmc/convex_spheropolyhedron/vertices
 Type
float
 Size
sum(N)x3
 Units
length
Position of the vertices in the shape for all types. The shape for type 0 is the first N[0] vertices, the shape for type 1 is the next N[1] vertices, and so on…
New in version 1.2.
 state/hpmc/convex_spheropolyhedron/sweep_radius
 Type
float
 Size
NTx1
 Units
length
Sweep radius for each type.
New in version 1.2.
 state/hpmc/convex_polygon/N
 Type
uint32
 Size
NTx1
 Units
number
Number of vertices defined for each type.
New in version 1.2.
 state/hpmc/convex_polygon/vertices
 Type
float
 Size
sum(N)x2
 Units
length
Position of the vertices in the shape for all types. The shape for type 0 is the first N[0] vertices, the shape for type 1 is the next N[1] vertices, and so on…
New in version 1.2.
 state/hpmc/convex_spheropolygon/N
 Type
uint32
 Size
NTx1
 Units
number
Number of vertices defined for each type.
New in version 1.2.
 state/hpmc/convex_spheropolygon/vertices
 Type
float
 Size
sum(N)x2
 Units
length
Position of the vertices in the shape for all types. The shape for type 0 is the first N[0] vertices, the shape for type 1 is the next N[1] vertices, and so on…
New in version 1.2.
 state/hpmc/convex_spheropolygon/sweep_radius
 Type
float
 Size
NTx1
 Units
length
Sweep radius for each type.
New in version 1.2.
 state/hpmc/simple_polygon/N
 Type
uint32
 Size
NTx1
 Units
number
Number of vertices defined for each type.
New in version 1.2.
 state/hpmc/simple_polygon/vertices
 Type
float
 Size
sum(N)x2
 Units
length
Position of the vertices in the shape for all types. The shape for type 0 is the first N[0] vertices, the shape for type 1 is the next N[1] vertices, and so on…
New in version 1.2.