hoomd.init

Overview

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.

Details

Data initialization commands

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

hoomd.init.create_lattice(unitcell, n)

Create a lattice.

Parameters

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.

Examples:

hoomd.init.create_lattice(unitcell=hoomd.lattice.sc(a=1.0),
                          n=[2,4,2]);

hoomd.init.create_lattice(unitcell=hoomd.lattice.bcc(a=1.0),
                          n=10);

hoomd.init.create_lattice(unitcell=hoomd.lattice.sq(a=1.2),
                          n=[100,10]);

hoomd.init.create_lattice(unitcell=hoomd.lattice.hex(a=1.0),
                          n=[100,58]);
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.

Parameters
  • 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.

Example:

# 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.

Parameters
  • 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. Negative values index from the end of the 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 filename. time_step is not applied when the file restart is read.

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

hoomd.dump.gsd

hoomd.init.read_snapshot(snapshot)

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. Snapshots are set to time_step 0, and should not be used to restart a simulation.

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

Example:

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

See also

hoomd.data

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().

Parameters
  • filename (str) – Name of the file to read from

  • modes (dict) – dictionary of {property: frame} values, as described in read_getar()