Crate hoomd_interaction 

Particle interactions and physical models that apply to microstates.

hoomd-interaction defines traits that describe site and body interactions needed to perform Monte Carlo and molecular dynamics simulations.

Hamiltonian

A type that describes a Hamiltonian (or a single term in a multi-part Hamiltonian) implements one or more of the following traits: TotalEnergy, DeltaEnergyOne, DeltaEnergyInsert, and DeltaEnergyRemove. Given a microstate, the total_energy method computes the total energy of the Hamiltonian. The various delta_energy_* methods compute the change in total energy when updating, inserting, or removing a body (often needed for Monte Carlo simulation). Total energy computations typically cost $O(N)$ while delta_energy methods typically cost $O(1)$. These costs may vary based on the specific interaction type and/or the microstate’s spatial data structure.

As a convenience, most Hamiltonian types also implement MaximumInteractionRange, so that callers can easily determine the maximum site-site interaction range in a given model.

All the Hamiltonian traits can be automatically derived using a #[derive()] macro of the same name. The derived implementation sums over all the fields in the struct.

Force interaction models

Molecular dynamics simulations are driven by the forces and torques that act on the bodies in the simulation (NetBodyForceAndVirial, NetBodyForceVirialAndTorque). The body forces and torques result from forces and torques on the sites NetSiteForceAndVirial, NetSiteForceVirialAndTorque). When an MD model is Hamiltonian, the same types that implement DeltaEnergyOne (and related traits) also implement NetSiteForceAndVirial and/or NetSiteForceVirialAndTorque. Virials are always calculated alongside forces.

Given a microstate and the index of a site in that microstate, NetSiteForceAndVirial and/or NetSiteForceVirialAndTorque compute the net force and virial (and torque) acting on that site. Thus, you can use your hamiltonian variable to compute both energy and force properties on the system. Use Rigid(hamiltonian) with MD integration methods. The Rigid type implements NetBodyForceAndVirial and/or NetBodyForceVirialAndTorque for types that implement NetSiteForceAndVirial or NetSiteForceVirialAndTorque respectively.

Not all MD models are Hamiltonian, so types may implement NetSiteForceAndVirial but but not TotalEnergy. Similarly, not all Hamiltonian types are differentiable and may implement DeltaEnergyOne but not NetSiteForceAndVirial.

All the force interaction model traits can be automatically derived using a #[derive()] macro of the same name. The derived implementation sums over all the fields in the struct.

Univariate interactions

Many interaction potentials are a function of one variable, typically the distance between two sites but sometimes the distance between a site and surface, or an angle. hoomd-interaction implements the most commonly used univariate potentials, such as LennardJones in univariate. These types are not Hamiltonian terms on their own, but can be combined with other types to create interaction models.

To implement your own univariate interactions, implement the UnivariateEnergy and/or UnivariateForce traits.

Interactions between sites and external objects

The SiteEnergy trait describes a type that computes the contribution of a single site to the total energy as a function only of that site’s properties along with fixed external parameters. SiteForceAndVirial and SiteForceVirialAndTorque describe the force (and torque) on the site commensurate with that energy. The External type implements all the Hamiltonian and force interaction model traits. It applies the wrapped type’s SiteEnergy, SiteForceAndVirial, and/or SiteForceVirialAndTorque implementations to all the sites in the microstate. See external for a list of built-in SiteEnergy, SiteForceAndVirial and SiteForceVirialAndTorque implementations.

Interactions between all pairs of sites

The SitePairEnergy trait describes a type that computes the energy that a pair of sites contributes to the Hamiltonian as a function of the properties of the two sites. Similarly, SitePairForceAndVirial and SitePairForceVirialAndTorque describe the force (and torque) between the pair commensurate with that energy. The PairwiseCutoff type implements all the Hamiltonian and force interaction model traits. It applies the wrapped type’s SitePairEnergy, SitePairForceAndVirial, and/or SitePairForceVirialAndTorque to all pairs of sites that are within the maximum interaction range.

The pairwise module provides numerous types that implement SitePairEnergy, SitePairForceAndVirial, and SitePairForceVirialAndTorque including Isotropic (which wraps any univariate potential), HardShape (which wraps a shape from hoomd_geometry, and many others.

Zero

Zero implements all Hamiltonian and force interaction traits. It represents $H=0$.

Complete documentation

hoomd-interaction is is a part of hoomd-rs. Read the complete documentation for more information.

Modules

external

External interactions.

pairwise

Pairwise interactions.

univariate

Interactions as a function of one variable.

Structs

External

Interactions between sites and external fields.

PairwiseCutoff

Short-ranged pairwise interactions between sites.

Rigid

Rigid body interactions.

Zero

Hamiltonian with H = 0.

Traits

DeltaEnergyInsert

Compute the change in energy when a single body is inserted.

DeltaEnergyOne

Compute the change in energy as a function of a single modified body.

DeltaEnergyRemove

Compute the change in energy when a single body is removed.

MaximumInteractionRange

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

NetBodyForceAndVirial

Sum all the forces and virials that act on a given body in a microstate.

NetBodyForceVirialAndTorque

Sum all the forces, virials, and torques that act on a given body in a microstate.

NetSiteForceAndVirial

Sum all the forces and virials that act on a given site in a microstate.

NetSiteForceVirialAndTorque

Sum all the forces, virials, and torques that act on a given site in a microstate.

SiteEnergy

Compute the energy contribution of a single site.

SiteForceAndVirial

Compute the force and virial on a single site as a function of its properties.

SiteForceVirialAndTorque

Compute the force, virial, and torque on a single site as a function of its properties.

SitePairEnergy

Compute the energy contribution from a pair of sites.

SitePairForceAndVirial

Compute the pairwise force and virial on one site from another site.

SitePairForceVirialAndTorque

Compute the pairwise force, virial, and torque on one site from another site.

TotalEnergy

Compute the total energy of a potential applied to the microstate.

Derive Macros

DeltaEnergyInsert

Automatically implement the hoomd_interaction::DeltaEnergyInsert trait.

DeltaEnergyOne

Automatically implement the hoomd_interaction::DeltaEnergyOne trait.

DeltaEnergyRemove

Automatically implement the hoomd_interaction::DeltaEnergyRemove trait.

MaximumInteractionRange

Automatically implement the hoomd_interaction::MaximumInteractionRange trait.

NetSiteForceAndVirial

Automatically implement the hoomd_interaction::NetSiteForceAndVirial trait.

NetSiteForceVirialAndTorque

Automatically implement the hoomd_interaction::NetSiteForceVirialAndTorque trait.

SitePairEnergy

Automatically implement the hoomd_interaction::SitePairEnergy trait.

TotalEnergy

Automatically implement the hoomd_interaction::TotalEnergy trait.