HOOMD-blue File Writers

Write GSD (General Simulation Data)

Default data file format for HOOMD-blue

GSD format.

https://gsd.readthedocs.io/en/stable/

mbuild.formats.gsdwriter.write_gsd(structure, filename, ref_distance=1.0, ref_mass=1.0, ref_energy=1.0, rigid_bodies=None, shift_coords=True, write_special_pairs=True, **kwargs)

Output a GSD file (HOOMD v2 default data format).

Parameters:

structureparmed.Structure

ParmEd Structure object

filenamestr

Path of the output file.

ref_distancefloat, optional, default=1.0

Reference distance for conversion to reduced units

ref_massfloat, optional, default=1.0

Reference mass for conversion to reduced units

ref_energyfloat, optional, default=1.0

Reference energy for conversion to reduced units

rigid_bodieslist of int, optional, default=None

List of rigid body information. An integer value is required for each atom corresponding to the index of the rigid body the particle is to be associated with. A value of None indicates the atom is not part of a rigid body.

shift_coordsbool, optional, default=True

Shift coordinates from (0, L) to (-L/2, L/2) if necessary.

write_special_pairsbool, optional, default=True

Writes out special pair information necessary to correctly use the OPLS fudged 1,4 interactions in HOOMD.

Notes

Force field parameters are not written to the GSD file and must be included manually into a HOOMD input script.

Create HOOMD-blue force field (>= 3.0)

HOOMD v3 forcefield format.

Create HOOMD-blue Simulation (v2.x)

HOOMD simulation format.

HOOMD-blue Snapshot

HOOMD snapshot format.

mbuild.formats.hoomd_snapshot.from_snapshot(snapshot, scale=1.0)

Convert a Snapshot to a Compound.

Snapshot can be a hoomd.Snapshot or a gsd.hoomd.Frame.

Parameters:

snapshothoomd.Snapshot or gsd.hoomd.Frame

Snapshot from which to build the mbuild Compound.

scalefloat, optional, default 1.0

Value by which to scale the length values

Returns:

compCompound

mbuild.formats.hoomd_snapshot.to_hoomdsnapshot(structure, ref_distance=1.0, ref_mass=1.0, ref_energy=1.0, rigid_bodies=None, shift_coords=True, write_special_pairs=True, auto_scale=False, parmed_kwargs={}, hoomd_snapshot=None)

Convert a Compound or parmed.Structure to hoomd.Snapshot.

Parameters:

structureparmed.Structure

ParmEd Structure object Reference distance for unit conversion ((Angstrom) / (desired units))

ref_massfloat, optional, default=1.0

Reference mass for unit conversion ((Dalton) / (desired units))

ref_energyfloat, optional, default=1.0

Reference energy for unit conversion ((kcal/mol) / (desired units))

rigid_bodieslist of int, optional, default=None

List of rigid body information. An integer value is required for each atom corresponding to the index of the rigid body the particle is to be associated with. A value of None indicates the atom is not part of a rigid body.

shift_coordsbool, optional, default=True

Shift coordinates from (0, L) to (-L/2, L/2) if necessary.

auto_scalebool, optional, default=False

Automatically use largest sigma value as ref_distance, largest mass value as ref_mass and largest epsilon value as ref_energy

write_special_pairsbool, optional, default=True

Writes out special pair information necessary to correctly use the OPLS fudged 1,4 interactions in HOOMD.

hoomd_snapshothoomd.Snapshot, optional, default=None

Initial snapshot to which to add the ParmEd structure object. The box information of the initial snapshot will be overwritten. (useful for rigid bodies)

Returns:

hoomd_snapshothoomd.Snapshot

ReferenceValuesnamedtuple

Values used in scaling

Notes

This method does not create hoomd forcefield objects and the snapshot returned does not store the forcefield parameters. See mbuild.formats.hoomd_forcefield.create_hoomd_forcefield()

About units: This method operates on a Parmed.Structure object

where the units used differ from those used in mBuild and Foyer which may have been used when creating the typed Parmed.Structure.

The default units used when writing out the HOOMD Snapshot are: Distance (Angstrom) Mass (Dalton) Energy (kcal/mol)

If you wish to convert this unit system to another, you can use the reference parameters (ref_distance, ref_mass, ref_energy). The values used here should be expected to convert from the Parmed Structure units (above) to your desired units. The Parmed.Structure values are divided by the reference values.

If you wish to used a reduced unit system, set auto_scale = True. When auto_scale is True, the reference parameters won’t be used.

Examples

To convert the energy units from kcal/mol to kj/mol:

use ref_energy = 0.2390057 (kcal/kj)

To convert the distance units from Angstrom to nm:

use ref_distance = 10 (angstroms/nm)

To use a reduced unit system, where mass, sigma, and epsilon are scaled by the largest value of each:

use auto_scale = True, ref_distance = ref_energy = ref_mass = 1