Struct Periodic 

pub struct Periodic<T> { /* private fields */ }

Describe a simulation space that repeats in one or more directions.

Periodic is a newtype that wraps a shape. Use it to set the boundary for a Microstate.

When bodies or sites exit the shape through one of the periodic sides of the shape, they are wrapped to the other side. Similarly, sites that are within the interaction range of one of the periodic sides appear as ghost sites just outside the opposite side. Depending on the shape type T, Periodic<T> might implement fully periodic boundaries or ones that are periodic in some directions and closed in others.

Periodic is implemented for the following shapes:

• EightEight
• Hypercuboid<2> (also known as Rectangle)
• Hypercuboid<3> (also known as Cuboid)

Example

use hoomd_geometry::shape::Rectangle;
use hoomd_microstate::boundary::Periodic;

let periodic =
    Periodic::new(2.5, Rectangle::with_equal_edges(10.0.try_into()?))?;

Implementations

impl<T> Periodic<T>

where T: MaximumAllowableInteractionRange,

pub fn new(maximum_interaction_range: f64, shape: T) -> Result<Self, Error>

Construct a new periodic boundary condition.

Errors

Error::InteractionRangeTooLarge when maximum_interaction_range is larger than the maximum allowable interaction range by the shape.

Example

use hoomd_geometry::shape::Rectangle;
use hoomd_microstate::boundary::Periodic;

let periodic =
    Periodic::new(2.5, Rectangle::with_equal_edges(10.0.try_into()?))?;

impl<T> Periodic<T>

pub fn shape(&self) -> &T

Access the boundary’s shape.

Example

use hoomd_geometry::shape::Rectangle;
use hoomd_microstate::boundary::Periodic;

let periodic =
    Periodic::new(2.5, Rectangle::with_equal_edges(10.0.try_into()?))?;

assert_eq!(periodic.shape().edge_lengths[0].get(), 10.0);

pub fn maximum_interaction_range(&self) -> f64

Access the boundary’s maximum interaction range.

Example

use hoomd_geometry::shape::Rectangle;
use hoomd_microstate::boundary::Periodic;

let periodic =
    Periodic::new(2.5, Rectangle::with_equal_edges(10.0.try_into()?))?;

assert_eq!(periodic.maximum_interaction_range(), 2.5);

Trait Implementations

impl<B, X> AppendMicrostate<B, OrientedPoint<Cartesian<2>, Angle>, X, Periodic<Hypercuboid<2>>> for HoomdGsdFile

fn append_microstate( &mut self, microstate: &Microstate<B, OrientedPoint<Cartesian<2>, Angle>, X, Periodic<Hypercuboid<2>>>, ) -> Result<Frame<'_>, AppendError>

Append the contents of the microstate as a frame in a GSD file.

impl<B, X> AppendMicrostate<B, OrientedPoint<Cartesian<3>, Versor>, X, Periodic<Hypercuboid<3>>> for HoomdGsdFile

fn append_microstate( &mut self, microstate: &Microstate<B, OrientedPoint<Cartesian<3>, Versor>, X, Periodic<Hypercuboid<3>>>, ) -> Result<Frame<'_>, AppendError>

Append the contents of the microstate as a frame in a GSD file.

impl<B, X> AppendMicrostate<B, Point<Cartesian<2>>, X, Periodic<Hypercuboid<2>>> for HoomdGsdFile

fn append_microstate( &mut self, microstate: &Microstate<B, Point<Cartesian<2>>, X, Periodic<Hypercuboid<2>>>, ) -> Result<Frame<'_>, AppendError>

Append the contents of the microstate as a frame in a GSD file.

impl<B, X> AppendMicrostate<B, Point<Cartesian<3>>, X, Periodic<Hypercuboid<3>>> for HoomdGsdFile

fn append_microstate( &mut self, microstate: &Microstate<B, Point<Cartesian<3>>, X, Periodic<Hypercuboid<3>>>, ) -> Result<Frame<'_>, AppendError>

Append the contents of the microstate as a frame in a GSD file.

impl<T: Clone> Clone for Periodic<T>

fn clone(&self) -> Periodic<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Periodic<T>

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

Formats the value using the given formatter.

impl<'de, T> Deserialize<'de> for Periodic<T>

where T: Deserialize<'de>,

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T, V> Distribution<V> for Periodic<T>

where T: Distribution<V>,

fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> V

Generate points uniformly distributed in the wrapped shape.

Example

use rand::{SeedableRng, distr::Distribution, rngs::StdRng};

use hoomd_geometry::{IsPointInside, shape::Hypercuboid};
use hoomd_microstate::boundary::Periodic;

let cuboid = Hypercuboid {
    edge_lengths: [6.0.try_into()?, 8.0.try_into()?],
};
let periodic = Periodic::new(2.5, cuboid)?;
let mut rng = StdRng::seed_from_u64(1);

let point = periodic.sample(&mut rng);
assert!(periodic.shape().is_point_inside(&point));

fn sample_iter<R>(self, rng: R) -> Iter<Self, R, T>

where R: Rng, Self: Sized,

Create an iterator that generates random values of T, using rng as the source of randomness.

fn map<F, S>(self, func: F) -> Map<Self, F, T, S>

where F: Fn(T) -> S, Self: Sized,

Map sampled values to type S

impl GenerateGhosts<OrientedHyperbolicPoint<3, Angle>> for Periodic<EightEight>

fn generate_ghosts( &self, site_properties: &OrientedHyperbolicPoint<3, Angle>, ) -> ArrayVec<OrientedHyperbolicPoint<3, Angle>, MAX_GHOSTS>

Place periodic images of sites near the edge of the periodic boundary

fn maximum_interaction_range(&self) -> f64

The largest interaction distance between sites.

impl GenerateGhosts<OrientedHyperbolicPoint<3, Angle>> for Periodic<TwelveTwelve>

fn generate_ghosts( &self, site_properties: &OrientedHyperbolicPoint<3, Angle>, ) -> ArrayVec<OrientedHyperbolicPoint<3, Angle>, MAX_GHOSTS>

Place periodic images of sites near the edge of the periodic boundary.

fn maximum_interaction_range(&self) -> f64

The largest interaction distance between sites.

impl GenerateGhosts<Point<Hyperbolic<3>>> for Periodic<EightEight>

fn generate_ghosts( &self, site_properties: &Point<Hyperbolic<3>>, ) -> ArrayVec<Point<Hyperbolic<3>>, MAX_GHOSTS>

Place periodic images of sites near the edge of the periodic boundary

fn maximum_interaction_range(&self) -> f64

The largest interaction distance between sites.

impl GenerateGhosts<Point<Hyperbolic<3>>> for Periodic<TwelveTwelve>

fn generate_ghosts( &self, site_properties: &Point<Hyperbolic<3>>, ) -> ArrayVec<Point<Hyperbolic<3>>, MAX_GHOSTS>

Place periodic images of sites near the edges of the periodic boundary

fn maximum_interaction_range(&self) -> f64

The largest interaction distance between sites.

impl<S> GenerateGhosts<S> for Periodic<Hypercuboid<2>>

where S: Position<Position = Cartesian<2>> + Copy + Default,

fn generate_ghosts(&self, site_properties: &S) -> ArrayVec<S, MAX_GHOSTS>

Place periodic images of sites near the edge of the periodic boundary.

For 2D cuboids, generate_ghosts places ghosts near the 4 edges and 4 vertices.

fn maximum_interaction_range(&self) -> f64

The largest interaction distance between sites.

impl<S> GenerateGhosts<S> for Periodic<Hypercuboid<3>>

where S: Position<Position = Cartesian<3>> + Copy + Default,

fn generate_ghosts(&self, site_properties: &S) -> ArrayVec<S, MAX_GHOSTS>

Place periodic images of sites near the edge of the periodic boundary.

For 3D cuboids, generate_ghosts places ghosts near the 6 faces, 12 edges, and 8 vertices.

fn maximum_interaction_range(&self) -> f64

The largest interaction distance between sites.

impl<P, T> MapPoint<P> for Periodic<T>

where T: MapPoint<P>,

fn map_point(&self, point: P, other: &Self) -> Result<P, Error>

Map points in from the wrapped shape into another periodic boundary.

Errors

hoomd_geometry::Error::PointOutsideShape when point is outside self.shape().

Example

use hoomd_geometry::{MapPoint, shape::Rectangle};
use hoomd_microstate::boundary::Periodic;
use hoomd_vector::Cartesian;

let periodic_a =
    Periodic::new(2.5, Rectangle::with_equal_edges(10.0.try_into()?))?;
let periodic_b =
    Periodic::new(2.5, Rectangle::with_equal_edges(20.0.try_into()?))?;

let mapped_point =
    periodic_a.map_point(Cartesian::from([-1.0, 1.0]), &periodic_b);

assert_eq!(mapped_point, Ok(Cartesian::from([-2.0, 2.0])));
assert_eq!(
    periodic_a.map_point(Cartesian::from([-100.0, 1.0]), &periodic_b),
    Err(hoomd_geometry::Error::PointOutsideShape)
);

impl<T: PartialEq> PartialEq for Periodic<T>

fn eq(&self, other: &Periodic<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Scale for Periodic<T>

where T: Debug + Scale + MaximumAllowableInteractionRange,

fn scale_length(&self, v: PositiveReal) -> Self

Scale the wrapped shape.

Panics

When scaling the wrapped shape, scale_length will panic if the scaled maximum allowable interaction range is smaller than maximum_interaction_range.

Examples

use hoomd_geometry::{Scale, shape::Rectangle};
use hoomd_microstate::boundary::Periodic;

let periodic =
    Periodic::new(2.5, Rectangle::with_equal_edges(10.0.try_into()?))?;

let scaled_periodic = periodic.scale_length(0.5.try_into()?);

assert_eq!(scaled_periodic.maximum_interaction_range(), 2.5);
assert_eq!(scaled_periodic.shape().edge_lengths[0].get(), 5.0);

use hoomd_geometry::{Scale, shape::Rectangle};
use hoomd_microstate::boundary::Periodic;

let periodic =
    Periodic::new(2.5, Rectangle::with_equal_edges(10.0.try_into()?))?;

let scaled_periodic = periodic.scale_length(0.2.try_into()?);

fn scale_volume(&self, v: PositiveReal) -> Self

Scale the wrapped shape.

Panics

When scaling the wrapped shape, scale_length will panic if the scaled maximum allowable interaction range is smaller than maximum_interaction_range.

Examples

use hoomd_geometry::{Scale, shape::Rectangle};
use hoomd_microstate::boundary::Periodic;

let periodic =
    Periodic::new(2.5, Rectangle::with_equal_edges(10.0.try_into()?))?;

let scaled_periodic = periodic.scale_volume(4.0.try_into()?);

assert_eq!(scaled_periodic.maximum_interaction_range(), 2.5);
assert_eq!(scaled_periodic.shape().edge_lengths[0].get(), 20.0);

use hoomd_geometry::{Scale, shape::Rectangle};
use hoomd_microstate::boundary::Periodic;

let periodic =
    Periodic::new(2.5, Rectangle::with_equal_edges(10.0.try_into()?))?;

let scaled_periodic = periodic.scale_volume(0.2.try_into()?);

impl<T> Serialize for Periodic<T>

where T: Serialize,

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T> Volume for Periodic<T>

where T: Volume,

fn volume(&self) -> f64

Volume of the wrapped shape.

Examples

use hoomd_geometry::{Volume, shape::Rectangle};
use hoomd_microstate::boundary::Periodic;

let periodic =
    Periodic::new(2.5, Rectangle::with_equal_edges(10.0.try_into()?))?;

let volume = periodic.volume();

assert_eq!(volume, 100.0);

impl Wrap<OrientedHyperbolicPoint<3, Angle>> for Periodic<EightEight>

fn wrap( &self, properties: OrientedHyperbolicPoint<3, Angle>, ) -> Result<OrientedHyperbolicPoint<3, Angle>, Error>

Wrap the positions and orientations of oriented bodies in two-dimensional hyperbolic space under the {8,8} tiling.

impl Wrap<OrientedHyperbolicPoint<3, Angle>> for Periodic<TwelveTwelve>

fn wrap( &self, properties: OrientedHyperbolicPoint<3, Angle>, ) -> Result<OrientedHyperbolicPoint<3, Angle>, Error>

Wrap the positions and orientations of oriented bodies in hyperbolic space under the {12,12} tiling.

impl<const N: usize, P> Wrap<P> for Periodic<Hypercuboid<N>>

where P: Position<Position = Cartesian<N>>,

fn wrap(&self, properties: P) -> Result<P, Error>

Wrap any cartesian vector to the inside of the given cuboid.

Example

use hoomd_geometry::shape::Rectangle;
use hoomd_microstate::{
    boundary::{Periodic, Wrap},
    property::Point,
};
use hoomd_vector::Cartesian;

let periodic =
    Periodic::new(2.5, Rectangle::with_equal_edges(10.0.try_into()?))?;
let point = Point::new(Cartesian::from([6.0, -15.0]));

let wrapped_point = periodic.wrap(point)?;
assert_eq!(wrapped_point.position, [-4.0, -5.0].into());

impl Wrap<Point<Hyperbolic<3>>> for Periodic<EightEight>

fn wrap( &self, properties: Point<Hyperbolic<3>>, ) -> Result<Point<Hyperbolic<3>>, Error>

Wrap a point in hyperbolic space to the inside of the {8,8} tile.

Note that the function fails to wrap points that are outside the octagon and further than EightEight::EDGE_LENGTH/2 from any of the vertices. In this case, the function returns Error::CannotWrapProperties

Example

use approxim::assert_relative_eq;
use hoomd_geometry::shape::EightEight;
use hoomd_manifold::Hyperbolic;
use hoomd_microstate::{
    boundary::{Periodic, Wrap},
    property::Point,
};
use std::f64::consts::PI;

const EIGHTEIGHT: f64 = EightEight::EIGHTEIGHT;
let offset = PI / 8.0;
let boost = 2.0;
let point =
    Hyperbolic::<3>::from_polar_coordinates(boost, offset + PI / 4.0);
let point = Point::new(point);
let periodic = Periodic::new(0.5, EightEight {})?;

let wrapped_point = periodic.wrap(point)?;

let new_boost = 2.0
    * (EIGHTEIGHT.tanh()
        / (offset.cos() - offset.sin() * (1.0 - (2.0_f64).sqrt())))
    .atanh()
    - boost;
let ans = Hyperbolic::<3>::from_polar_coordinates(
    new_boost,
    6.0 * PI / 4.0 - offset,
);
assert_relative_eq!(
    ans.coordinates()[0],
    wrapped_point.position.coordinates()[0],
    epsilon = 1e-12
);
assert_relative_eq!(
    ans.coordinates()[1],
    wrapped_point.position.coordinates()[1],
    epsilon = 1e-12
);
assert_relative_eq!(
    ans.coordinates()[2],
    wrapped_point.position.coordinates()[2],
    epsilon = 1e-12
);

impl Wrap<Point<Hyperbolic<3>>> for Periodic<TwelveTwelve>

fn wrap( &self, properties: Point<Hyperbolic<3>>, ) -> Result<Point<Hyperbolic<3>>, Error>

Wrap a point in hyperbolic space to the inside of the {12,12} tile.

Note that the function fails to wrap points that are outside the dodecagon and further than TwelveTwelve::EDGE_LENGTH/2 from any of the vertices.

impl<T> StructuralPartialEq for Periodic<T>