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:	unitcell (`hoomd.lattice.unitcell`) – The unit cell of the lattice. n (list) – Number of replicates in each direction.

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.