Struct PairwiseCutoff 

pub struct PairwiseCutoff<E>(pub E);

Short-ranged pairwise interactions between sites.

A PairwiseCutoff newtype wrapping a type that implements SitePairEnergy represents:

U_\mathrm{total} = \sum_{i=0}^{N-1}\sum_{j=i+1}^{N-1} U\left(s_i, s_j \right) \left[ \left|\vec{r}_j - \vec{r}_i\right| \lt r_\mathrm{cut} \right]\left[b_i \ne b_j\right]

where $U(s_i, s_j)$ is the potential computed by SitePairEnergy, $s_i$ is the full set of site properties for site i, $\vec{r}_i$ is the position of site i, $b_i$ is the body tag that holds site i, and $\left[ \ \right]$ denotes the Iverson bracket.

In other words, PairwiseCutoff sums the energy for all pairs that are separated by a distance less than the maximum interaction range r_cut and belong to different bodies.

A PairwiseCutoff newtype wrapping a type that implements SitePairForceAndVirial and/or SitePairForceVirialAndTorque represents:

\vec{F}_i = \sum_{j \ne i} \vec{F}\left(s_i, s_j \right) \left[ \left|\vec{r}_j - \vec{r}_i\right| \lt r_\mathrm{cut} \right]\left[b_i \ne b_j\right]

\vec{\tau}_i = \sum_{j \ne i} \vec{\tau}\left(s_i, s_j \right) \left[ \left|\vec{r}_j - \vec{r}_i\right| \lt r_\mathrm{cut} \right]\left[b_i \ne b_j\right]

where $\vec{F}(s_i, s_j)$ is the force computed by SitePairForceAndVirial (or SitePairForceVirialAndTorque) and $\vec{\tau}(s_i, s_j)$ is the torque computed by SitePairForceVirialAndTorque.

A type that implements both SitePairEnergy and SitePairForceAndVirial (or SitePairForceVirialAndTorque) must compute forces and torques that are derivatives of the energy.

Use PairwiseCutoff with Anisotropic, Isotropic, HardShape, or your own custom type that implements SitePairEnergy, SitePairForceAndVirial and/or SitePairForceVirialAndTorque.

Example

Basic usage:

use hoomd_interaction::{
    PairwiseCutoff, pairwise::Isotropic, univariate::LennardJones,
};

let lennard_jones: LennardJones = LennardJones {
    epsilon: 1.5,
    sigma: 2.0,
};
let pairwise_cutoff = PairwiseCutoff(Isotropic {
    interaction: lennard_jones,
    r_cut: 5.0,
});

Set a custom potential using a closure (implements only SitePairEnergy):

use hoomd_interaction::{PairwiseCutoff, pairwise::Isotropic};

let pairwise_cutoff = PairwiseCutoff(Isotropic {
    interaction: |r: f64| 1.0 / (r.powi(12)),
    r_cut: 3.0,
});

Implement a custom potential via a type:

use hoomd_interaction::{
    PairwiseCutoff, pairwise::Isotropic, univariate::UnivariateEnergy,
};

struct Custom {
    a: f64,
}

impl UnivariateEnergy for Custom {
    fn energy(&self, r: f64) -> f64 {
        self.a / r.powi(12)
    }
}

let custom = Custom { a: 2.0 };
let pairwise_cutoff = PairwiseCutoff(Isotropic {
    interaction: custom,
    r_cut: 2.0,
});

Hard sphere:

use hoomd_interaction::{PairwiseCutoff, pairwise::HardSphere};
use hoomd_microstate::property::Point;
use hoomd_vector::Cartesian;

let hard_sphere = PairwiseCutoff(HardSphere { diameter: 1.0 });

Hard ellipse:

use hoomd_geometry::shape::Ellipse;
use hoomd_interaction::{PairwiseCutoff, pairwise::HardShape};
use hoomd_microstate::property::Point;
use hoomd_vector::Cartesian;
let ellipse = Ellipse::with_semi_axes([4.0.try_into()?, 1.0.try_into()?]);
let hard_ellipse = PairwiseCutoff(HardShape(ellipse));

Tuple Fields

0: E

Implementations

impl<E> PairwiseCutoff<E>

pub fn site_pair_force_and_virial<V, S>( &self, site_i: &Site<S>, site_j: &Site<S>, ) -> (V, V::Tensor)

where E: SitePairForceAndVirial<S, Force = V>, V: Default + Outer, V::Tensor: Default,

Calculate the pairwise force and virial on site i caused by site j.

Use this method to compute an individual term in the net force and virial on site i, subject to the the maximum interaction range r_cut and inter-body checks:

\begin{align*}
\vec{F}_{i} &= \sum_{j \in N_s} \vec{F}_{ji}
\mathbf{W}_{i} &= \sum_{j \in N_s} \mathbf{W}_{ji}
\end{align*}

where $N_s$ is the set of neighboring sites in other bodies for which $\left|\vec{r}_j - \vec{r}_i\right| \lt r_\mathrm{cut}$ and the subscript $ji$ means “from j on i”.

Example

use approxim::assert_relative_eq;
use hoomd_interaction::{
    PairwiseCutoff, pairwise::Isotropic, univariate::LennardJones,
};
use hoomd_linear_algebra::matrix::Matrix;
use hoomd_microstate::{Body, Microstate, Site, property::Point};
use hoomd_vector::Cartesian;

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

let lennard_jones: LennardJones = LennardJones {
    epsilon: 1.0,
    sigma: 1.0,
};

let force = PairwiseCutoff(Isotropic {
    interaction: lennard_jones,
    r_cut: 2.5,
});

let sites = microstate.sites();
let (force_0, virial_0) =
    force.site_pair_force_and_virial(&sites[0], &sites[1]);
let (force_1, virial_1) =
    force.site_pair_force_and_virial(&sites[1], &sites[0]);

assert_relative_eq!(force_0, Cartesian::from([-24.0, 0.0, 0.0]));
assert_eq!(
    virial_0,
    Matrix {
        rows: [[12.0, 0.0, 0.0], [0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]
    }
);

assert_relative_eq!(force_1, Cartesian::from([24.0, 0.0, 0.0]));
assert_eq!(
    virial_1,
    Matrix {
        rows: [[12.0, 0.0, 0.0], [0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]
    }
);

pub fn site_pair_force_virial_and_torque<V, S>( &self, site_i: &Site<S>, site_j: &Site<S>, ) -> (V, V::Tensor, V::Bivector)

where E: SitePairForceVirialAndTorque<S, Force = V>, V: Default + Wedge + Outer, V::Bivector: Default, V::Tensor: Default,

Calculate the pairwise force, virial, and torque on site i caused by site j.

Use this method to compute an individual term in the net force, virial, and torque on site i, subject to the the maximum interaction range r_cut and inter-body checks:

\begin{align*}
\vec{F}_{i} &= \sum_{j \in N_s} \vec{F}_{ji} \\
\mathbf{W}_{i} &= \sum_{j \in N_s} \mathbf{W}_{ji} \\
\vec{\tau}_{i} &= \sum_{j \in N_s} \vec{\tau}_{ji} \\
\end{align*}

where $N_s$ is the set of neighboring sites in other bodies for which $\left|\vec{r}_j - \vec{r}_i\right| \lt r_\mathrm{cut}$ and the subscript $ji$ means “from j on i”.

pub fn site_pair_energy<S>(&self, site_i: &Site<S>, site_j: &Site<S>) -> f64

where E: SitePairEnergy<S>,

Compute the pair energy between two sites.

Use this method to compute an individual term in the total pair energy, subject to the the maximum interaction range r_cut and inter-body checks:

U\left(s_i, s_j \right) \left[ \left|\vec{r}_j - \vec{r}_i\right| \lt r_\mathrm{cut} \right]\left[b_i \ne b_j\right]

Example

use approxim::assert_relative_eq;
use hoomd_interaction::{
    PairwiseCutoff, pairwise::Isotropic, univariate::LennardJones,
};
use hoomd_microstate::{Body, Microstate, Site};
use hoomd_vector::Cartesian;

let lennard_jones: LennardJones = LennardJones {
    epsilon: 1.0,
    sigma: 1.0,
};
let pairwise_cutoff = PairwiseCutoff(Isotropic {
    interaction: lennard_jones,
    r_cut: 2.5,
});

let body_a = Body::point(Cartesian::from([0.0, 0.0]));
let body_b = Body::point(Cartesian::from([0.0, 3.0]));
let body_c = Body::point(Cartesian::from([0.0, -2.0_f64.powf(1.0 / 6.0)]));

let microstate = Microstate::builder()
    .bodies([body_a, body_b, body_c])
    .try_build()?;

let sites = microstate.sites();
let energy_ab = pairwise_cutoff.site_pair_energy(&sites[0], &sites[1]);
let energy_ac = pairwise_cutoff.site_pair_energy(&sites[0], &sites[2]);

assert_eq!(energy_ab, 0.0);
assert_relative_eq!(energy_ac, -1.0);

Trait Implementations

impl<E: Clone> Clone for PairwiseCutoff<E>

fn clone(&self) -> PairwiseCutoff<E>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<E: Debug> Debug for PairwiseCutoff<E>

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

Formats the value using the given formatter.

impl<P, B, S, X, C, E> DeltaEnergyInsert<B, S, X, C> for PairwiseCutoff<E>

where E: SitePairEnergy<S> + MaximumInteractionRange, B: Transform<S>, S: Position<Position = P>, X: PointsNearBall<P, SiteKey>, C: Wrap<B> + Wrap<S>,

fn delta_energy_insert( &self, initial_microstate: &Microstate<B, S, X, C>, new_body: &Body<B, S>, ) -> f64

Evaluate the change in energy contributed by PairwiseCutoff when one body is inserted.

Example

Boxcar:

use hoomd_interaction::{
    DeltaEnergyInsert, PairwiseCutoff, pairwise::Isotropic,
    univariate::Boxcar,
};
use hoomd_microstate::{Body, Microstate, property::Point};
use hoomd_vector::Cartesian;

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

let epsilon = 2.0;
let (left, right) = (0.0, 1.5);
let boxcar = Boxcar {
    epsilon,
    left,
    right,
};
let pairwise_cutoff = PairwiseCutoff(Isotropic {
    interaction: boxcar,
    r_cut: 1.5,
});

let delta_energy = pairwise_cutoff
    .delta_energy_insert(&microstate, &Body::point([-1.0, 0.0].into()));
assert_eq!(delta_energy, 2.0);

Hard circle:

use hoomd_geometry::shape::Circle;
use hoomd_interaction::{
    DeltaEnergyInsert, PairwiseCutoff, pairwise::HardSphere,
};
use hoomd_microstate::{Body, Microstate, property::Point};
use hoomd_vector::{Angle, Cartesian};

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

let hard_circle = PairwiseCutoff(HardSphere { diameter: 1.0 });

let delta_energy = hard_circle
    .delta_energy_insert(&microstate, &Body::point([0.4, 0.0].into()));
assert_eq!(delta_energy, f64::INFINITY);

let delta_energy = hard_circle
    .delta_energy_insert(&microstate, &Body::point([1.5, 0.0].into()));
assert_eq!(delta_energy, 0.0);

impl<P, B, S, X, C, E> DeltaEnergyOne<B, S, X, C> for PairwiseCutoff<E>

where E: SitePairEnergy<S> + MaximumInteractionRange, B: Transform<S>, S: Position<Position = P>, X: PointsNearBall<P, SiteKey>, C: Wrap<B> + Wrap<S>,

fn delta_energy_one( &self, initial_microstate: &Microstate<B, S, X, C>, body_index: usize, final_body: &Body<B, S>, ) -> f64

Evaluate the change in energy contributed by PairwiseCutoff when one body is updated.

Examples

Boxcar:

use hoomd_interaction::{
    DeltaEnergyOne, PairwiseCutoff, pairwise::Isotropic, univariate::Boxcar,
};
use hoomd_microstate::{Body, Microstate, property::Point};
use hoomd_vector::Cartesian;

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

let epsilon = 2.0;
let (left, right) = (0.0, 1.5);
let boxcar = Boxcar {
    epsilon,
    left,
    right,
};
let pairwise_cutoff = PairwiseCutoff(Isotropic {
    interaction: boxcar,
    r_cut: 1.5,
});

let delta_energy = pairwise_cutoff.delta_energy_one(
    &microstate,
    0,
    &Body::point([-1.0, 0.0].into()),
);
assert_eq!(delta_energy, -2.0);

Hard circle:

use hoomd_geometry::shape::Circle;
use hoomd_interaction::{
    DeltaEnergyOne, PairwiseCutoff, pairwise::HardSphere,
};
use hoomd_microstate::{Body, Microstate, property::Point};
use hoomd_vector::{Angle, Cartesian};

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

let hard_circle = PairwiseCutoff(HardSphere { diameter: 1.0 });

let delta_energy = hard_circle.delta_energy_one(
    &microstate,
    1,
    &Body::point([0.4, 0.0].into()),
);
assert_eq!(delta_energy, f64::INFINITY);

let delta_energy = hard_circle.delta_energy_one(
    &microstate,
    1,
    &Body::point([1.5, 0.0].into()),
);
assert_eq!(delta_energy, 0.0);

impl<P, B, S, X, C, E> DeltaEnergyRemove<B, S, X, C> for PairwiseCutoff<E>

where E: SitePairEnergy<S> + MaximumInteractionRange, S: Position<Position = P>, X: PointsNearBall<P, SiteKey>,

fn delta_energy_remove( &self, initial_microstate: &Microstate<B, S, X, C>, body_index: usize, ) -> f64

Evaluate the change in energy contributed by PairwiseCutoff when one body is removed.

Example

Boxcar:

use hoomd_interaction::{
    DeltaEnergyRemove, PairwiseCutoff, pairwise::Isotropic,
    univariate::Boxcar,
};
use hoomd_microstate::{Body, Microstate, property::Point};
use hoomd_vector::Cartesian;

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

let epsilon = 2.0;
let (left, right) = (0.0, 1.5);
let boxcar = Boxcar {
    epsilon,
    left,
    right,
};
let pairwise_cutoff = PairwiseCutoff(Isotropic {
    interaction: boxcar,
    r_cut: 1.5,
});

let delta_energy = pairwise_cutoff.delta_energy_remove(&microstate, 0);
assert_eq!(delta_energy, -2.0);

Hard circle:

use hoomd_geometry::shape::Circle;
use hoomd_interaction::{
    DeltaEnergyRemove, PairwiseCutoff, pairwise::HardSphere,
};
use hoomd_microstate::{Body, Microstate, property::Point};
use hoomd_vector::{Angle, Cartesian};

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

let hard_circle = PairwiseCutoff(HardSphere { diameter: 1.0 });

let delta_energy = hard_circle.delta_energy_remove(&microstate, 1);
assert_eq!(delta_energy, 0.0);

impl<'de, E> Deserialize<'de> for PairwiseCutoff<E>

where E: Deserialize<'de>,

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<E> MaximumInteractionRange for PairwiseCutoff<E>

where E: MaximumInteractionRange,

fn maximum_interaction_range(&self) -> f64

The largest distance between two sites where the pairwise interaction may be non-zero.

impl<V, B, S, X, C, E> NetSiteForceAndVirial<B, S, X, C> for PairwiseCutoff<E>

where V: Vector + Default + InnerProduct + Metric + Outer, B: Transform<S>, S: Position<Position = V>, E: MaximumInteractionRange + SitePairForceAndVirial<S, Force = V>, X: PointsNearBall<V, SiteKey>, V::Tensor: Default + AddAssign,

fn net_site_force_and_virial( &self, microstate: &Microstate<B, S, X, C>, site_index: usize, ) -> (V, V::Tensor)

Compute the net force and virial on a given site.

\begin{align*}
\vec{F}_{i} &= \sum_{j \in N_s} \vec{F}_{ji} \\
\mathbf{W}_{i} &= \sum_{j \in N_s} \mathbf{W}_{ji} \\
\end{align*}

where $N_s$ is the set of neighboring sites in other bodies for which $\left|\vec{r}_j - \vec{r}_i\right| \lt r_\mathrm{cut}$ and the subscript $ji$ means “from j on i”. The pairwise forces and virials are given by E’s implementation of SitePairForceAndVirial.

Example

use approxim::assert_relative_eq;
use hoomd_interaction::{
    NetSiteForceAndVirial, PairwiseCutoff, pairwise::Isotropic,
    univariate::LennardJones,
};
use hoomd_microstate::{Body, Microstate, Site, property::Point};
use hoomd_vector::Cartesian;

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

let lennard_jones: LennardJones = LennardJones {
    epsilon: 1.0,
    sigma: 1.0,
};

let force = PairwiseCutoff(Isotropic {
    interaction: lennard_jones,
    r_cut: 2.5,
});

let (force_0, virial_0) = force.net_site_force_and_virial(&microstate, 0);
let (force_1, virial_1) = force.net_site_force_and_virial(&microstate, 1);

assert_relative_eq!(force_0, Cartesian::from([-24.0, 0.0, 0.0]));
assert_relative_eq!(force_1, Cartesian::from([24.0, 0.0, 0.0]));

type Force = V

The type of the result force.

impl<V, B, S, X, C, E> NetSiteForceVirialAndTorque<B, S, X, C> for PairwiseCutoff<E>

where V: Vector + Default + InnerProduct + Metric + Wedge + Outer, B: Transform<S>, S: Position<Position = V>, E: MaximumInteractionRange + SitePairForceVirialAndTorque<S, Force = V>, V::Bivector: AddAssign + Default, X: PointsNearBall<V, SiteKey>, V::Tensor: Default + AddAssign,

fn net_site_force_virial_and_torque( &self, microstate: &Microstate<B, S, X, C>, site_index: usize, ) -> (V, V::Tensor, V::Bivector)

Compute the net force, virial, and torque on a given site.

\begin{align*}
\vec{F}_{i} &= \sum_{j \in N_s} \vec{F}_{ji} \\
\mathbf{W}_{i} &= \sum_{j \in N_s} \mathbf{W}_{ji} \\
\vec{\tau}_{i} &= \sum_{j \in N_s} \vec{\tau}_{ji} \\
\end{align*}

where $N_s$ is the set of neighboring sites in other bodies for which $\left|\vec{r}_j - \vec{r}_i\right| \lt r_\mathrm{cut}$ and the subscript $ji$ means “from j on i”. The pairwise forces, virials, and torques are given by E’s implementation of SitePairForceVirialAndTorque.

type Force = V

The type of the result force.

impl<E: PartialEq> PartialEq for PairwiseCutoff<E>

fn eq(&self, other: &PairwiseCutoff<E>) -> 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<E> Serialize for PairwiseCutoff<E>

where E: Serialize,

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<P, B, S, X, C, E> TotalEnergy<Microstate<B, S, X, C>> for PairwiseCutoff<E>

where E: SitePairEnergy<S> + MaximumInteractionRange, S: Position<Position = P>, X: PointsNearBall<P, SiteKey>,

fn total_energy(&self, microstate: &Microstate<B, S, X, C>) -> f64

Compute the total energy of the microstate contributed by functions on pairs of sites.

Examples

Lennard-Jones:

use hoomd_interaction::{
    PairwiseCutoff, SitePairEnergy, TotalEnergy, pairwise::Isotropic,
    univariate::LennardJones,
};
use hoomd_microstate::{
    Body, Microstate,
    property::{Point, Position},
};
use hoomd_vector::{Cartesian, InnerProduct};

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

let lennard_jones: LennardJones = LennardJones {
    epsilon: 1.5,
    sigma: 1.0 / 2.0_f64.powf(1.0 / 6.0),
};
let pairwise_cutoff = PairwiseCutoff(Isotropic {
    interaction: lennard_jones,
    r_cut: 2.5,
});

let total_energy = pairwise_cutoff.total_energy(&microstate);
assert_eq!(total_energy, -3.0);

Hard circle:

use hoomd_geometry::shape::Circle;
use hoomd_interaction::{
    PairwiseCutoff, TotalEnergy, pairwise::HardSphere,
};
use hoomd_microstate::{Body, Microstate, property::Point};
use hoomd_vector::{Angle, Cartesian};

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

let hard_circle = PairwiseCutoff(HardSphere { diameter: 1.0 });

let total_energy = hard_circle.total_energy(&microstate);
assert_eq!(total_energy, f64::INFINITY);

microstate.update_body_properties(0, Point::new([0.0, -2.0].into()));
let total_energy = hard_circle.total_energy(&microstate);
assert_eq!(total_energy, 0.0);

fn delta_energy_total( &self, initial_microstate: &Microstate<B, S, X, C>, final_microstate: &Microstate<B, S, X, C>, ) -> f64

Compute the difference in energy between two microstates.

Returns $E_\mathrm{final} - E_\mathrm{initial}$.

Example

use hoomd_interaction::{
    PairwiseCutoff, SitePairEnergy, TotalEnergy, pairwise::Isotropic,
    univariate::LennardJones,
};
use hoomd_microstate::{
    Body, Microstate,
    property::{Point, Position},
};
use hoomd_vector::{Cartesian, InnerProduct};

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

let mut microstate_b = Microstate::new();
microstate_b.extend_bodies([
    Body::point(Cartesian::from([0.0, 0.0])),
    Body::point(Cartesian::from([5.0, 0.0])),
])?;

let lennard_jones: LennardJones = LennardJones {
    epsilon: 1.5,
    sigma: 1.0 / 2.0_f64.powf(1.0 / 6.0),
};
let pairwise_cutoff = PairwiseCutoff(Isotropic {
    interaction: lennard_jones,
    r_cut: 2.5,
});

let delta_energy_total =
    pairwise_cutoff.delta_energy_total(&microstate_a, &microstate_b);
assert_eq!(delta_energy_total, 1.5);

impl<E> StructuralPartialEq for PairwiseCutoff<E>