Expand description
Store and manage the simulation state.
§Microstate
Microstate facilitates simulations of particle systems. It is the central
data structure used by MC, MD, and supporting calculations implemented in
hoomd-rs. Microstate holds a set of bodies that exist in a space defined
by the boundary conditions. The degrees of freedom consist of the properties of
the bodies and the parameters of the boundary conditions.
Microstate also stores many auxiliary data structures and implements
convenience methods to facilitate the efficient implementation of simulation
models. These include a set of all interaction sites in the system frame
of reference, ghost sites near the periodic boundaries, and spatial data
structures.
§Step, substep and seed
Microstate tracks the current simulation step (Microstate::step),
substep (Microstate::substep), and seed (Microstate::seed)
that allow models to generate uncorrelated random number streams via
Microstate::counter.
The step is the current step in the simulation as defined by the user.
For example, a single step could be one MD timestep or the application
of a set of MC moves. Users should call Microstate::increment_step
after each step in the model is completed. The substep is a running
counter tracking the number of operations called so far during the current
step. Model methods in hoomd-rs (such as the MC trial move apply) call
increment_substep internally. Users should
call it at the end of any custom methods that implement new substeps.
A failure to call increment_substep
will cause the reuse of the same random numbers from one substep to the next!**
The seed allows users to select independent random number streams for
simulations that would otherwise be identical. It may only be set once on
creation by MicrostateBuilder::seed.
§Bodies and sites
Microstate differentiates between the degrees of freedom of the system and
points where interactions take place. Each Body in the microstate has one
or more interaction sites (Site). The bodies have degrees of freedom that
are evolved by the simulation model, which defines how bodies interact through
their sites. The properties of the sites in the system frame are a function
of the body’s properties and the site properties in the body frame. In a
particle-only simulation model each body has one site at the origin in the body
frame. In a simulation of squares, each body might be made up of four sites on
the vertices. In both cases, the net force on the body is the sum of the forces
applied to all of its sites.
In Microstate, the body properties (the generic type B throughout) and the
site properties (the generic type S) do not need to be the same. For example,
a body might have mass, position and velocity while that body’s sites have
position and type.
The property module provides a number of property types. It also defines
traits that you can use to implement custom property types. At a minimum, both
B and S MUST implement property::Position so that Microstate can
place your body’s and sites inside the boundary conditions and maintain spatial
data structures. Some model methods (such as shape overlap energies) will
require other traits (such as property::Orientation). The property module
documentation provides more details on using the types it provides and how to
define custom types.
Microstate::add_body and Microstate::extend_bodies add new bodies (and
their sites) to the microstate. Similarly, Microstate::remove_body removes a
body (and all associated sites). Microstate::update_body_properties modifies
the properties of a given body and correspondingly the properties of all sites
associated with that body. All these methods have a cost proportional to the
number of sites in the body.
Microstate::bodies provides direct (immutable) access to the bodies in
the microstate, including their properties and sites in the body frame. While
some algorithms may find this useful, many model algorithms instead operate
on site properties in the system frame. Microstate::sites provides direct
(immutable) access to a slice of all sites in the system frame for this
purpose. Any method that adds, removes, or changes a body immediately updates
Microstate::sites accordingly. Microstate::iter_body_sites iterates over
all the sites (in the system frame) associated with a given body.
§Tags
The elements of Microstate::bodies and Microstate::sites are stored in
no particular order to allow efficient addition and removal of bodies and
for the possibility sorting to improve cache coherency. Callers are welcome
to iterate over these data structures when computing order-independent overall
properties. However, a caller should never maintain indices into these vectors.
Instead, the caller should store the appropriate tag when it needs to
persistently refer to a specific body or site.
Elements in Microstate::bodies have the type Tagged<Body>.
The item field holds the body itself while the
tag field is a unique identifier that identifies this
specific body. The tag will remain the same even when Microstate::bodies is
reordered. Use Microstate::body_indices to find the current index of a body
with a given tag.
Elements in Microstate::sites have the type Site<S>. As with bodies,
each site has a unique site_tag that remains the same even
when sites are reordered. Each site also has a body_tag that
identifies which body the site is part of. Use Microstate::site_indices
to find the current index of a site with a given site tag and
Microstate::iter_body_sites to find all the sites associated with a given
body index.
§Boundary conditions
The positions of all bodies and all sites must be inside the microstate’s boundary at all times. Periodic boundaries can wrap positions outside to a corresponding point on the inside. When a boundary is aperiodic (or partially aperiodic), the wrapping process may fail. MC models reject trial moves that cannot be wrapped. MD models fail with an error should bodies or sites move in a way that cannot be wrapped.
Microstate is generic on the type of boundary condition. The boundary
module implements standard types and explains how you can provide custom
implementations.
§Spatial searches
Microstate maintains a internal spatial data structure (see hoomd_spatial).
It is kept in sync with every body insertion, removal, and update. Callers
can query the spatial data directly with spatial_data and efficiently iterate
over all sites near a point in space with iter_sites_near.
§Ghost sites
Periodic boundary conditions place ghost sites within a given maximum
interaction range outside the boundary. These ghost sites are images of real
sites that are inside the boundary. Access all of the ghosts with the
ghosts method. iter_sites_near will find both primary and ghost sites
as it searches for sites near the requested point.
When using Open or Closed boundary conditions, ghosts will always
be empty.
§I/O
Use HoomdGsdFile and AppendMicrostate to write to GSD
files that can be read by the Ovito, HOOMD-blue,
the GSD Python package, and other applications. There is currently no
high-level API to read a GSD file and produce a Microstate. You can
implement your own solution using the low level GsdFile.
Microstate derives the serde Serialize and Deserialize traits,
along with all other types in hoomd-rs. You can use serde to read and
write entire Simulation models. Use serde serialized files (in a
format of your choice, postcard is a good starting point) to save the
simulation state and continue running where it left off. The format is NOT
well-defined for long-term use. It will change from one simulation model
to the next, and may change with each major release of hoomd-rs. Share
your simulation code along with GSD data with the community.
§Complete documentation
hoomd-microstate is is a part of hoomd-rs. Read the complete documentation
for more information.
Modules§
- boundary
- Traits that describe boundary conditions and a selection of types that implement them.
- property
- Traits that describe body and/or site properties a a selection types that implement them.
Structs§
- Body
- A collection of interaction sites that can be placed in a
Microstate. - Microstate
- Store and manage all the degrees of freedom of a single microstate in phase space.
- Microstate
Builder - Choose parameters when constructing a
Microstate. - Site
- Interactions in
hoomd-rsapply between sites. - Tagged
- Track a unique identifier for an item in
Microstate.
Enums§
- Error
- Enumerate possible sources of error in fallible microstate methods.
- SiteKey
- Either a primary site index or a ghost site index.
Traits§
- Append
Microstate - Write a frame to a GSD file with the contents of a microstate.
- Transform
- Take
Siteproperties in the body frame into the system frame.