def 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 :py:func:`read_getar`.
Args:
filename (str): Name of the file to read from
modes (dict): dictionary of {property: frame} values, as described in :py:func:`read_getar`
"""
# the getar initializer opens the file on all ranks: need to broadcast the string from rank 0
filename_bcast = _hoomd.mpi_bcast_str(filename, hoomd.context.current.device.cpp_exec_conf);
initializer = _hoomd.GetarInitializer(hoomd.context.current.device.cpp_exec_conf, filename_bcast);
newModes = _parse_getar_modes(modes);
initializer.restore(newModes, hoomd.context.current.system_definition);
del initializer;
def read_getar(filename, modes={'any': 'any'}):
"""Initialize a system from a trajectory archive (.tar, .getar,
.sqlite) file. Returns a HOOMD `system_data` object.
Args:
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 <http://libgetar.readthedocs.io>`_.
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**
.. tabularcolumns:: |p{0.25 \textwidth}|p{0.1 \textwidth}|p{0.2 \textwidth}|p{0.45 \textwidth}|
.. csv-table::
:header: "Name", "Type", "Shape", "Notes"
:widths: 1, 1, 1, 5
"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.context._verify_init();
# check if initialization has already occurred
if is_initialized():
raise RuntimeError("Cannot initialize more than once\n");
newModes = _parse_getar_modes(modes);
# read in the data
initializer = _hoomd.GetarInitializer(hoomd.context.current.device.cpp_exec_conf, filename);
snapshot = initializer.initialize(newModes);
# broadcast snapshot metadata so that all ranks have _global_box (the user may have set box only on rank 0)
snapshot._broadcast_box(hoomd.context.current.device.cpp_exec_conf);
try:
box = snapshot._global_box;
except AttributeError:
box = snapshot.box;
my_domain_decomposition = _create_domain_decomposition(box);
if my_domain_decomposition is not None:
hoomd.context.current.system_definition = _hoomd.SystemDefinition(
snapshot, hoomd.context.current.device.cpp_exec_conf, my_domain_decomposition);
else:
hoomd.context.current.system_definition = _hoomd.SystemDefinition(
snapshot, hoomd.context.current.device.cpp_exec_conf);
hoomd.context.current.system = _hoomd.System(
hoomd.context.current.system_definition, initializer.getTimestep());
_perform_common_init_tasks();
if (hoomd.data.get_snapshot_box(snapshot).dimensions == 2 and
any(abs(z) > 1e-5 for z in snapshot.particles.position[:, 2])):
raise RuntimeWarning('Initializing a 2D system with some z '
'components out-of-plane');
return hoomd.data.system_data(hoomd.context.current.system_definition);
