Struct Microstate 

pub struct Microstate<B, S = B, X = AllPairs<SiteKey>, C = Open> { /* private fields */ }

Store and manage all the degrees of freedom of a single microstate in phase space.

Microstate implements the main logic of the crate. See the crate-level documentation for a full overview and the method-specific documentation for additional details.

The generic type names are:

• B: The Body::properties type.
• S: The Site::properties type.
• X: The spatial data structure type.
• C: The boundary condition type.

Constructing Microstate

You will find many examples in this documentation using Microstate::new. It is designed to be terse, and is inflexible as a consequence. Microstate::new always sets Open boundary conditions and initializes the seed and step to 0.

use hoomd_microstate::Microstate;

let mut microstate = Microstate::new();

When you need more control, use MicrostateBuilder to set the boundary conditions, use a different seed or starting step:

use hoomd_geometry::shape::Rectangle;
use hoomd_microstate::{Body, Microstate, boundary::Closed};
use hoomd_vector::Cartesian;

let square = Closed(Rectangle::with_equal_edges(10.0.try_into()?));

let microstate = Microstate::builder()
    .boundary(square)
    .seed(0x43abf1)
    .step(100_000)
    .bodies([Body::point(Cartesian::from([0.0, 0.0]))])
    .try_build()?;

Implementations

impl<B, S> Microstate<B, S, AllPairs<SiteKey>, Open>

pub fn new() -> Self

Construct an empty microstate with open boundary conditions.

The microstate starts at step 0, substep 0, random number seed 0, and has no bodies. Use the AllPairs spatial search algorithm.

Example

use hoomd_microstate::Microstate;

let mut microstate = Microstate::new();
assert_eq!(microstate.step(), 0);
assert_eq!(microstate.substep(), 0);
assert_eq!(microstate.seed(), 0);
assert_eq!(microstate.bodies().len(), 0);
assert_eq!(microstate.sites().len(), 0);

pub fn builder() -> MicrostateBuilder<B, S, AllPairs<SiteKey>, Open>

Set microstate parameters before construction.

The builder defaults to:

• step = 0
• seed = 0
• spatial_data = AllPairs
• boundary = Open
• No bodies.

Call MicrostateBuilder methods in a chain to set these parameters.

Example

use hoomd_geometry::shape::Rectangle;
use hoomd_microstate::{
    Body, Microstate, boundary::Closed, property::Point,
};
use hoomd_spatial::VecCell;
use hoomd_vector::Cartesian;

let cell_list = VecCell::builder()
    .nominal_search_radius(2.5.try_into()?)
    .build();
let square = Closed(Rectangle::with_equal_edges(10.0.try_into()?));

let microstate = Microstate::builder()
    .boundary(square)
    .spatial_data(cell_list)
    .step(100_000)
    .seed(0x1234abcd)
    .bodies([
        Body::point(Cartesian::from([1.0, 0.0])),
        Body::point(Cartesian::from([-1.0, 2.0])),
    ])
    .try_build()?;

assert_eq!(microstate.boundary().0.edge_lengths[0].get(), 10.0);
assert_eq!(microstate.step(), 100_000);
assert_eq!(microstate.seed(), 0x1234abcd);
assert_eq!(microstate.bodies().len(), 2);

impl<B, S, X, C> Microstate<B, S, X, C>

Access and manage the simulation step, substep, RNG seeds.

pub fn step(&self) -> u64

Get the simulation step.

Examples

Get the step:

use hoomd_microstate::Microstate;

let mut microstate = Microstate::new();
assert_eq!(microstate.step(), 0);

Initialize a microstate with a given step:

use hoomd_microstate::Microstate;

let microstate = Microstate::builder()
    .step(100_000)
    .try_build()?;
assert_eq!(microstate.step(), 100_000);

pub fn increment_step(&mut self)

Increment the simulation step.

Also set the substep to 0.

Examples

Increment the simulation step:

use hoomd_microstate::Microstate;

let mut microstate = Microstate::new();
microstate.increment_step();

assert_eq!(microstate.step(), 1);

Confirm that substep resets to 0:

use hoomd_microstate::Microstate;

let mut microstate = Microstate::new();

microstate.increment_substep();
microstate.increment_substep();
microstate.increment_substep();
assert_eq!(microstate.substep(), 3);

microstate.increment_step();

assert_eq!(microstate.step(), 1);
assert_eq!(microstate.substep(), 0);

pub fn substep(&self) -> u32

Get the simulation substep.

Example

use hoomd_microstate::Microstate;

let mut microstate = Microstate::new();
microstate.increment_substep();

assert_eq!(microstate.substep(), 1);

pub fn increment_substep(&mut self)

Increment the simulation substep.

Example

use hoomd_microstate::Microstate;

let mut microstate = Microstate::new();
microstate.increment_substep();

assert_eq!(microstate.substep(), 1);

pub fn seed(&self) -> u32

Get the simulation seed.

Examples:

Get the simulation seed.

use hoomd_microstate::Microstate;

let mut microstate = Microstate::new();

assert_eq!(microstate.seed(), 0);

Initialize a microstate with a given seed:

use hoomd_microstate::Microstate;

let microstate = Microstate::<BodyProperties, SiteProperties>::builder()
    .seed(0x1234abcd)
    .try_build()?;
assert_eq!(microstate.seed(), 0x1234abcd);

pub fn counter(&self) -> Counter

Create a partially constructed Counter from the current step, substep, and seed.

Use the produced Counter to make a independent random number generator at each substep. Call additional methods on the Counter first to further differentiate the stream.

Example

Make a random number generator unique to this substep:

use hoomd_microstate::Microstate;

let mut microstate = Microstate::new();

let rng = microstate.counter().make_rng();

Make a random number generator unique to a particular particle on this substep:

use hoomd_microstate::Microstate;

let mut microstate = Microstate::new();

let tag = 10;
let rng = microstate.counter().index(tag).make_rng();

impl<B, S, X, C> Microstate<B, S, X, C>

Access and manage the boundary condition.

pub fn boundary(&self) -> &C

Get the boundary condition.

Example

use hoomd_geometry::shape::Rectangle;
use hoomd_microstate::{Microstate, boundary::Closed};

let square = Closed(Rectangle::with_equal_edges(10.0.try_into()?));
let microstate = Microstate::builder()
    .boundary(square)
    .try_build()?;

assert_eq!(microstate.boundary().0.edge_lengths[0].get(), 10.0);

impl<P, B, S, X, C> Microstate<B, S, X, C>

where P: Copy, B: Transform<S> + Position<Position = P>, S: Position<Position = P> + Default, C: Wrap<B> + Wrap<S> + GenerateGhosts<S>, X: PointUpdate<P, SiteKey>,

Manage bodies in the microstate.

pub fn add_body(&mut self, body: Body<B, S>) -> Result<usize, Error>

Add a new body to the microstate.

Each body is assigned a unique tag. The first body is given tag 0, the second is given tag 1, and so on. When a body is removed (see Microstate::remove_body()), its tag becomes unused. The next call to add_body will assign the smallest unused tag.

add_body also adds the body’s sites to the microstate’s sites (in system coordinates) and assigns unique tags to the sites similarly. It wraps the body’s position (and the positions of its sites in system coordinates) into the boundary (see boundary).

Cost

The cost of adding a body is proportional to the number of sites in the body.

Returns

Ok(tag) with the tag of the added body on success.

Errors

Error::AddBody when the body cannot be added to the microstate because the body position or any site position cannot be wrapped into the boundary

Example

use hoomd_microstate::{Body, Microstate};
use hoomd_vector::Cartesian;

let mut microstate = Microstate::new();
let first_tag =
    microstate.add_body(Body::point(Cartesian::from([1.0, 0.0])))?;
let second_tag =
    microstate.add_body(Body::point(Cartesian::from([-1.0, 2.0])))?;

assert_eq!(microstate.bodies().len(), 2);
assert_eq!(first_tag, 0);
assert_eq!(second_tag, 1);

pub fn extend_bodies<T>(&mut self, bodies: T) -> Result<(), Error>

where T: IntoIterator<Item = Body<B, S>>,

Add multiple bodies to the microstate.

See Microstate::add_body() for details.

Errors

Error::AddBody when any of the bodies cannot be added to the microstate. extend_bodies adds each body one by one. When an error occurs, it short-circuits and does not attempt to add any further bodies. The bodies added before the error will remain in the microstate.

Example

use hoomd_microstate::{Body, Microstate};
use hoomd_vector::Cartesian;

let mut microstate = Microstate::new();
microstate.extend_bodies([
    Body::point(Cartesian::from([1.0, 0.0])),
    Body::point(Cartesian::from([-1.0, 2.0])),
])?;

assert_eq!(microstate.bodies().len(), 2);

pub fn remove_body(&mut self, body_index: usize)

Remove a body at the given index from the microstate.

Also remove all the body’s sites. The body’s tag (and the tags of its sites) are then free to be reused by Microstate::add_body.

Removing a body will change the index order of the bodies and sites arrays. Microstate does not guarantee any specific ordering in these arrays after calling remove_body.

Cost

The cost of removing a body is proportional to the number of sites in the body.

Panics

Panics when index is out of bounds.

Example

use hoomd_microstate::{Body, Microstate};
use hoomd_vector::Cartesian;

let mut microstate = Microstate::builder()
    .bodies([
        Body::point(Cartesian::from([1.0, 0.0])),
        Body::point(Cartesian::from([-1.0, 2.0])),
    ])
    .try_build()?;

microstate.remove_body(0);

assert_eq!(microstate.bodies().len(), 1);

pub fn update_body_properties( &mut self, body_index: usize, properties: B, ) -> Result<(), Error>

where B: Transform<S> + Position<Position = P>, S: Position<Position = P>, C: Wrap<B> + Wrap<S>,

Sets the properties of the given body.

update_body_properties also updates the properties of the sites (in the system frame) associated with the body accordingly.

Errors

Error::UpdateBody the body properties cannot be updated because the body position or any site position cannot be wrapped into the boundary. When an error occurs, update_body_properties makes no change to the Microstate.

Example

use hoomd_microstate::{Body, Microstate, property::Point};
use hoomd_vector::Cartesian;

let mut microstate = Microstate::builder()
    .bodies([Body::point(Cartesian::from([1.0, 0.0]))])
    .try_build()?;

microstate
    .update_body_properties(0, Point::new(Cartesian::from([-2.0, 3.0])))?;
assert_eq!(
    microstate.bodies()[0].item.properties.position,
    [-2.0, 3.0].into()
);
assert_eq!(
    microstate.sites()[0].properties.position,
    [-2.0, 3.0].into()
);

pub fn clear(&mut self)

Remove all bodies from the microstate.

The step, substep, seed, and boundary are left unchanged.

Example

use hoomd_microstate::{Body, Microstate, property::Point};
use hoomd_vector::Cartesian;

let mut microstate = Microstate::builder()
    .bodies([Body::point(Cartesian::from([1.0, 0.0]))])
    .try_build()?;

microstate.clear();
assert_eq!(microstate.bodies().len(), 0);
assert_eq!(microstate.sites().len(), 0);

impl<B, S, X, C> Microstate<B, S, X, C>

Access contents of the microstate.

pub fn bodies(&self) -> &[Tagged<Body<B, S>>]

Access the microstate’s tagged bodies in index order.

Microstate stores bodies in a flat memory region. The Tagged type holds the unique identifier for each body in Tagged::tag and the Body itself in Tagged::item.

bodies provides direct immutable access to this slice. To mutate a body (and by extension, its sites), see Microstate::update_body_properties().

Examples

Identify the tag of a body at a given index:

use hoomd_microstate::{Body, Microstate};
use hoomd_vector::Cartesian;

let microstate = Microstate::builder()
    .bodies([
        Body::point(Cartesian::from([1.0, 0.0])),
        Body::point(Cartesian::from([-1.0, 2.0])),
    ])
    .try_build()?;

assert_eq!(microstate.bodies()[0].tag, 0);
assert_eq!(microstate.bodies()[1].tag, 1);

Compute system-wide properties that are order-independent:

use hoomd_microstate::{Body, Microstate};
use hoomd_vector::{Cartesian, Vector};

let microstate = Microstate::builder()
    .bodies([
        Body::point(Cartesian::from([1.0, 0.0])),
        Body::point(Cartesian::from([-1.0, 2.0])),
    ])
    .try_build()?;

let average_position = microstate
    .bodies()
    .iter()
    .map(|tagged_body| tagged_body.item.properties.position)
    .sum::<Cartesian<2>>()
    / (microstate.bodies().len() as f64);

pub fn body_indices(&self) -> &[Option<usize>]

Identify the index of a body given a tag.

Use body_indices to locate a specific body in Microstate::bodies.

body_indices()[tag] is:

• None when there is no body with the given tag in the microstate.
• Some(index) when the body with the given tag is in the microstate. index is the index of the body in Microstate::bodies.

Example

use anyhow::anyhow;
use hoomd_microstate::{Body, Microstate};
use hoomd_vector::Cartesian;

let mut microstate = Microstate::builder()
    .bodies([
        Body::point(Cartesian::from([1.0, 2.0])),
        Body::point(Cartesian::from([3.0, 4.0])),
        Body::point(Cartesian::from([5.0, 6.0])),
        Body::point(Cartesian::from([7.0, 8.0])),
    ])
    .try_build()?;

let index =
    microstate.body_indices()[0].ok_or(anyhow!("body 0 is not present"))?;
microstate.remove_body(index);

assert_eq!(microstate.body_indices()[0], None);
assert!(matches!(microstate.body_indices()[3], Some(_)));

let index =
    microstate.body_indices()[2].ok_or(anyhow!("body 2 is not present"))?;
assert_eq!(
    microstate.bodies()[index].item.properties.position,
    [5.0, 6.0].into()
);

pub fn sites(&self) -> &[Site<S>]

Access the microstate’s sites (in the system frame) in index order.

Microstate stores sites twice. Each body in bodies stores its sites in the body frame of reference. Microstate also stores a flat vector of sites that have been transformed (see Transform) to the system reference frame. The Site type holds the unique identifier for each site in Site::site_tag, the associated body tag in Site::body_tag and the site’s properties in Site::properties.

sites provides direct immutable access to the slice of all sites. To mutate a body (and by extension, its sites), see Microstate::update_body_properties().

Examples

Identify the site and body tags of a site at a given index:

use hoomd_microstate::{Body, Microstate};
use hoomd_vector::Cartesian;

let microstate = Microstate::builder()
    .bodies([
        Body::point(Cartesian::from([1.0, 0.0])),
        Body::point(Cartesian::from([-1.0, 2.0])),
    ])
    .try_build()?;

assert_eq!(microstate.sites()[0].site_tag, 0);
assert_eq!(microstate.sites()[0].body_tag, 0);

assert_eq!(microstate.sites()[1].body_tag, 1);
assert_eq!(microstate.sites()[1].body_tag, 1);

Compute system-wide properties that are order-independent:

use hoomd_microstate::{Body, Microstate};
use hoomd_vector::{Cartesian, Vector};

let microstate = Microstate::builder()
    .bodies([
        Body::point(Cartesian::from([1.0, 0.0])),
        Body::point(Cartesian::from([-1.0, 2.0])),
    ])
    .try_build()?;

let average_position = microstate
    .sites()
    .iter()
    .map(|site| site.properties.position)
    .sum::<Cartesian<2>>()
    / (microstate.sites().len() as f64);

pub fn ghosts(&self) -> &[Site<S>]

Access the ghost sites in the system frame.

Each ghost site shares a site_tag and body_tag with a primary site (in sites). Ghost sites are only placed when using periodic boundary conditions and are outside the edges of the boundary.

pub fn site_indices(&self) -> &[Option<usize>]

Identify the index of a site given a tag.

Use site_indices to locate a specific site in Microstate::sites.

See body_indices for details.

pub fn iter_body_sites( &self, body_index: usize, ) -> impl Iterator<Item = &Site<S>>

Iterate over all the sites (in the system reference frame) associated with a body.

Use iter_body_sites to perform computations in the system reference frame on all sites that are associated with a given body index. The borrowed sites are immutable. Call Microstate::update_body_properties() to mutate a body.

iter_body_sites always iterates over primary sites. In periodic boundary conditions, these sites may be split across one or more parts of the boundary.

Example

use hoomd_microstate::{Body, Microstate};
use hoomd_vector::{Cartesian, Vector};

let microstate = Microstate::builder()
    .bodies([
        Body::point(Cartesian::from([1.0, 0.0])),
        Body::point(Cartesian::from([-1.0, 2.0])),
    ])
    .try_build()?;

let average_position = microstate
    .iter_body_sites(0)
    .map(|site| site.properties.position)
    .sum::<Cartesian<2>>()
    / (microstate.bodies()[0].item.sites.len() as f64);

pub fn iter_sites_tag_order(&self) -> impl Iterator<Item = &Site<S>>

Iterate over all sites in monotonically increasing tag order.

iter_sites_tag_order is especially useful when implementing AppendMicrostate, as GSD files must be written in tag order.

Example

use hoomd_microstate::{Body, Microstate};
use hoomd_vector::Cartesian;

let mut microstate = Microstate::builder()
    .bodies([
        Body::point(Cartesian::from([1.0, 0.0])),
        Body::point(Cartesian::from([-1.0, 2.0])),
    ])
    .try_build()?;

microstate.remove_body(0);
microstate.add_body(Body::point(Cartesian::from([3.0, 1.0])))?;

let positions_tag_order: Vec<_> = microstate
    .iter_sites_tag_order()
    .map(|s| s.properties.position)
    .collect();
assert_eq!(
    positions_tag_order,
    vec![[3.0, 1.0].into(), [-1.0, 2.0].into()]
);

pub fn spatial_data(&self) -> &X

Get the spatial data structure.

impl<P, B, S, X, C> Microstate<B, S, X, C>

where S: Position<Position = P>, X: PointsNearBall<P, SiteKey>,

pub fn iter_sites_near( &self, point: &P, r: f64, ) -> impl Iterator<Item = &Site<S>>

Find sites near a point in space.

Iterate over all sites and ghost sites within a distance r of the given point, and possibly other sites as well. All sites produced by this iterator will be in the system reference frame. No wrapping is required for ghost sites, which will be slightly outside the boundary condition. When a ghost site is provided by the iterator, its site_tag and body_tag will match that of the actual site.

The iterator does not filter on distance to avoid duplicating effort as many callers already perform circumsphere checks.

The caller may provide a value for r that is larger than the maximum interaction range. In the current implementation, this is not an error. However, in such cases iter_sites_near will only iterate over the placed ghosts which are within the boundary’s maximum_interaction_range.

In other words, iter_sites_near is meant for use with pairwise functions that follow the minimum image convention.

impl<P, B, S, X, C> Microstate<B, S, X, C>

where P: Copy, B: Clone + Transform<S> + Position<Position = P>, S: Clone + Position<Position = P> + Default, C: Clone + Wrap<B> + Wrap<S> + GenerateGhosts<S> + MapPoint<P>, X: Clone + PointUpdate<P, SiteKey>,

Manipulate the microstate as a whole.

pub fn clone_with_boundary<F>( &self, new_boundary: C, should_map_body: F, ) -> Result<Microstate<B, S, X, C>, Error>

where F: Fn(&Tagged<Body<B, S>>) -> bool,

Clone the microstate, mapping or wrapping bodies into a new boundary.

The resulting microstate contains the same bodies and sites as the source. All bodies and sites maintain the same index order and tags.

should_map_body will be called on every body in the microstate. When it returns true, clone_with_boundary will map the body’s position from self.boundary to new_boundary using MapPoint. When should_map_body returns false, the clone_with_boundary wraps the body’s unmodified position into new_boundary. That wrap may fail, especially in closed (or partially closed) boundary conditions.

Errors

Error::UpdateBody when some body or site cannot be wrapped into the new boundary.

Example

use hoomd_geometry::shape::Rectangle;
use hoomd_microstate::{
    Body, Microstate,
    boundary::Closed,
    property::{Point, Position},
};
use hoomd_vector::Cartesian;

let square = Closed(Rectangle::with_equal_edges(10.0.try_into()?));
let microstate = Microstate::builder()
    .boundary(square)
    .bodies([Body::point(Cartesian::from([1.0, 2.0]))])
    .bodies([Body::point(Cartesian::from([3.0, 4.0]))])
    .try_build()?;

let new_square = Closed(Rectangle::with_equal_edges(20.0.try_into()?));

let new_microstate =
    microstate.clone_with_boundary(new_square, |body| body.tag > 0)?;

assert_eq!(
    *new_microstate.bodies()[0].item.properties.position(),
    Cartesian::from([1.0, 2.0])
);
assert_eq!(
    *new_microstate.bodies()[1].item.properties.position(),
    Cartesian::from([6.0, 8.0])
);

impl<P, B, S, X, C, L> Microstate<B, S, X, C>

where S: Position<Position = P>, X: IndexFromPosition<P, Location = L>, L: Ord, Site<S>: Copy,

pub fn sort_sites(&mut self)

Sort the sites spatially.

sort_sites reorders the sites in memory based on their spatial location. PairwiseCutoff interactions compute in less them when the sites are sorted because the interacting sites are more likely to be nearby in memory.

CPUs have large caches. Typical simulations start to see benefits from sorting when there are more than 100,000 sites. sort is a quick operation, so there is no harm in sorting the microstate every few hundred steps regardless of the system size.

Trait Implementations

impl<B: Clone, S: Clone, X: Clone, C: Clone> Clone for Microstate<B, S, X, C>

fn clone(&self) -> Microstate<B, S, X, C>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<B: Debug, S: Debug, X: Debug, C: Debug> Debug for Microstate<B, S, X, C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<B, S> Default for Microstate<B, S, AllPairs<SiteKey>, Open>

fn default() -> Self

Construct an empty microstate with open boundary conditions.

See Microstate::new.

impl<'de, B, S, X, C> Deserialize<'de> for Microstate<B, S, X, C>

where B: Deserialize<'de>, S: Deserialize<'de>, X: Deserialize<'de>, C: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<B, S, X, C> Display for Microstate<B, S, X, C>

where X: Display,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Summarize the contents of the microstate.

This is a slow operation. It is meant to be printed to logs only occasionally, such as at the end of a benchmark or simulation.

Example

use hoomd_spatial::VecCell;
use log::info;

let vec_cell = VecCell::<usize, 3>::default();

info!("{vec_cell}");

impl<B, S, X, C> Serialize for Microstate<B, S, X, C>

where B: Serialize, S: Serialize, X: Serialize, C: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.