hoomd.init.create_lattice Create a lattice.
hoomd.init.read_getar Initialize a system from a trajectory archive (.tar, .getar, .sqlite) file.
hoomd.init.read_gsd Read initial system state from an GSD file.
hoomd.init.read_snapshot Initializes the system from a snapshot.


Data initialization commands

Commands in the hoomd.init package initialize the particle system.

hoomd.init.create_lattice(unitcell, n)

Create a lattice.


create_lattice() take a unit cell and replicates it the requested number of times in each direction. The resulting simulation box is commensurate with the given unit cell. A generic hoomd.lattice.unitcell may have arbitrary vectors \(\vec{a}_1\), \(\vec{a}_2\), and \(\vec{a}_3\). create_lattice() will rotate the unit cell so that \(\vec{a}_1\) points in the \(x\) direction and \(\vec{a}_2\) is in the \(xy\) plane so that the lattice may be represented as a HOOMD simulation box.

When n is a single value, the lattice is replicated n times in each direction. When n is a list, the lattice is replicated n[0] times in the \(\vec{a}_1\) direction, n[1] times in the \(\vec{a}_2\) direction and n[2] times in the \(\vec{a}_3\) direction.





hoomd.init.read_getar(filename, modes={'any': 'any'})

Initialize a system from a trajectory archive (.tar, .getar, .sqlite) file. Returns a HOOMD system_data object.

  • filename (str) – Name of the file to read from
  • modes (dict) – dictionary of {property: frame} values; see below

Getar files are a simple interface on top of archive formats (such as zip and tar) for storing trajectory data efficiently. A more thorough description of the format and a description of a python API to read and write these files is available at the libgetar documentation.

The modes argument is a dictionary. The keys of this dictionary should be either property names (see the Supported Property Table below) or tuples of property names.

If the key is a tuple of property names, data for those names will be restored from the same frame. Other acceptable keys are “any” to restore any properties which are present from the file, “angle_any” to restore any angle-related properties present, “bond_any”, and so forth. The values associated with each key in the dictionary should be “any” (in which case any frame present for the data will be restored, even if the frames are different for two property names in a tuple), “latest” (grab the most recent frame data), “earliest”, or a specific timestep value.


# creating file to initialize beforehand using libgetar
with gtar.GTAR('init.zip', 'w') as traj:
    traj.writePath('position.f32.ind', positions)
    traj.writePath('velocity.f32.ind', velocities)
    traj.writePath('metadata.json', json.dumps(metadata))
system = hoomd.init.read_getar('init.zip')
# using the backup created in the `hoomd.dump.getar.simple` example
system = hoomd.init.read_getar('backup.tar')

Supported Property Table

Name Type Shape Notes
angle_type_names JSON [String] (N_angle_types,) list containing the name of each angle type in JSON format
angle_tag unsigned int (N_angle, 3) array of particle tags for each angle interaction
angle_type unsigned int (N_angle,) array of angle interaction types
angular_momentum float (N, 4) per-particle angular momentum quaternion
body int (N,) particle rigid body index
bond_type_names JSON [String] (N_bond_types,) list containing the name of each bond type in JSON format
bond_tag unsigned int (N_bond, 2) array of particle tags for each bond interaction
bond_type unsigned int (N_bond,) array of bond interaction types
box float (6,) vector of box lengths (x, y, z, tilt_xy, tilt_xz, tilt_yz); can be high precision
charge float (N,) particle charge
diameter float (N,) particle diameter
dihedral_type_names JSON [String] (N_dihedral_types,) list containing the name of each dihedral type in JSON format
dihedral_tag unsigned int (N_dihedral, 4) array of particle tags for each dihedral interaction
dihedral_type unsigned int (N_dihedral,) array of dihedral interaction types
dimensions unsigned int 1 number of dimensions of the system
image int (N, 3) how many times each particle has passed through the periodic boundary conditions
improper_type_names JSON [String] (N_improper_types,) list containing the name of each improper type in JSON format
improper_tag unsigned int (N_improper, 4) array of particle tags for each improper interaction
improper_type unsigned int (N_improper,) array of improper interaction types
mass float (N,) particle mass
moment_inertia float (N, 3) moment of inertia of each particle (diagonalized).
orientation float (N, 4) particle orientation, expressed as a quaternion in the order (real, imag_i, imag_j, imag_k); can be high precision
position float (N, 3) the position of each particle in the system (can be high precision)
potential_energy float (N,) per-particle potential energy; can’t be used in MPI runs
type unsigned int (N,) particle numerical type index
type_names JSON [String] (N_types,) list containing the name of each particle type in JSON format
velocity float (N, 3) velocity of each particle in the system
hoomd.init.read_gsd(filename, restart=None, frame=0, time_step=None)

Read initial system state from an GSD file.

  • filename (str) – File to read.
  • restart (str) – If it exists, read the file restart instead of filename.
  • frame (int) – Index of the frame to read from the GSD file.
  • time_step (int) – (if specified) Time step number to initialize instead of the one stored in the GSD file.

All particles, bonds, angles, dihedrals, impropers, constraints, and box information are read from the given GSD file at the given frame index. To read and write GSD files outside of hoomd, see http://gsd.readthedocs.io/. hoomd.dump.gsd writes GSD files.

For restartable jobs, specify the initial condition in filename and the restart file in restart. hoomd.init.read_gsd() will read the restart file if it exists, otherwise it will read filename.

If time_step is specified, its value will be used as the initial time step of the simulation instead of the one read from the GSD file.

The result of hoomd.init.read_gsd() can be saved in a variable and later used to read and/or change particle properties later in the script. See hoomd.data for more information.

See also



Initializes the system from a snapshot.

Parameters:snapshot (hoomd.data snapshot) – The snapshot to initialize the system.

Snapshots temporarily store system data. Snapshots contain the complete simulation state in a single object. They can be used to start or restart a simulation.

Example use cases in which a simulation may be started from a snapshot include user code that generates initial particle positions.


snapshot = my_system_create_routine(.. parameters ..)
system = init.read_snapshot(snapshot)

See also


hoomd.init.restore_getar(filename, modes={'any': 'any'})

Restore a subset of the current system’s parameters from a trajectory archive (.tar, .zip, .sqlite) file. For a detailed discussion of arguments, see read_getar().

  • filename (str) – Name of the file to read from
  • modes (dict) – dictionary of {property: frame} values, as described in read_getar()