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 frame 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.Frame
, 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.