hoomd_simulation/
macrostate.rs

1// Copyright (c) 2024-2026 The Regents of the University of Michigan.
2// Part of hoomd-rs, released under the BSD 3-Clause License.
3
4//! Traits that describe system macrostates and types that implement them.
5//!
6//! ## Macrostate
7//!
8//! Use a built-in macrostate type, such as [`Isothermal`], [`IsothermalIsobaric`]
9//! or [`Isobaric`] store the temperature and/or pressure set points for use
10//! with thermostats, barostats, and/or Monte Carlo trial moves:
11//!
12//! ```
13//! use hoomd_simulation::macrostate::Isothermal;
14//!
15//! let macrostate = Isothermal { temperature: 1.2 };
16//! ```
17//!
18//! The *actual* ensemble that your simulation samples is set by the methods
19//! that you apply to it. These macrostate types exist merely to pass
20//! parameters to methods that need them. For example, you could choose an
21//! [`IsothermalIsobaric`] macrostate and use it only with local Monte Carlo
22//! moves. Without boundary moves, the simulation will be in the NVT ensemble.
23//!
24//! ## Traits
25//!
26//! When you need additional macrostate parameters, use a custom type.
27//! Implement [`Temperature`] and/or [`Pressure`] for your type as needed.
28
29use serde::{Deserialize, Serialize};
30
31/// Set the thermodynamic temperature of a system.
32///
33/// Macrostates with the [`Temperature`] trait set the temperature
34/// of the simulation. In *hoomd-rs*, temperature is given in units of
35/// $` [\mathrm{energy}] `$: $` \mathrm{temperature} = kT `$.
36///
37/// # Example
38/// ```
39/// use hoomd_simulation::macrostate::Isothermal;
40///
41/// let macrostate = Isothermal { temperature: 1.2 };
42/// ```
43pub trait Temperature {
44    /// The system's temperature $` ([\mathrm{energy}]) `$.
45    fn temperature(&self) -> &f64;
46
47    /// The system's temperature $` ([\mathrm{energy}]) `$.
48    fn temperature_mut(&mut self) -> &mut f64;
49}
50
51/// Set the thermodynamic pressure of a system.
52///
53/// Macrostates with the [`Pressure`] trait set the pressure
54/// of the simulation. In *hoomd-rs*, pressure is given in units of
55/// $` [\mathrm{energy}] \cdot [\mathrm{length}]^{-D} `$ where $` D `$
56/// is the dimensionality of the system.
57///
58/// # Example
59/// ```
60/// use hoomd_simulation::macrostate::Isobaric;
61///
62/// let macrostate = Isobaric { pressure: 0.4 };
63/// ```
64pub trait Pressure {
65    /// The system's pressure $` ([\mathrm{energy}] \cdot [\mathrm{length}]^{-D}) `$.
66    fn pressure(&self) -> &f64;
67
68    /// The system's pressure $` ([\mathrm{energy}] \cdot [\mathrm{length}]^{-D}) `$.
69    fn pressure_mut(&mut self) -> &mut f64;
70}
71
72/// Constant temperature macrostate.
73///
74/// Use [`Isothermal`] to set the system temperature using a thermostat or Monte
75/// Carlo trial moves. Temperature is given in units of $` [\mathrm{energy}] `$:
76/// $` \mathrm{temperature} = kT `$.
77///
78/// # Example
79/// ```
80/// use hoomd_simulation::macrostate::Isothermal;
81///
82/// let macrostate = Isothermal { temperature: 1.2 };
83/// ```
84#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
85pub struct Isothermal {
86    /// The system's temperature $` ([\mathrm{energy}]) `$.
87    pub temperature: f64,
88}
89impl Temperature for Isothermal {
90    #[inline]
91    fn temperature(&self) -> &f64 {
92        &self.temperature
93    }
94
95    #[inline]
96    fn temperature_mut(&mut self) -> &mut f64 {
97        &mut self.temperature
98    }
99}
100
101/// Constant pressure macrostate.
102///
103/// Use [`Isobaric`] to set the system pressure using a thermostat or Monte
104/// Carlo trial moves. Pressure is given in units of $` [\mathrm{energy}] \cdot
105/// [\mathrm{length}]^{-D} `$ where $` D `$ is the dimensionality of the system.
106///
107/// # Example
108/// ```
109/// use hoomd_simulation::macrostate::Isobaric;
110///
111/// let macrostate = Isobaric { pressure: 0.4 };
112/// ```
113#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
114pub struct Isobaric {
115    /// The system's pressure $` ([\mathrm{energy}] \cdot [\mathrm{length}]^{-D}) `$.
116    pub pressure: f64,
117}
118
119/// Constant temperature, constant pressure macrostate.
120///
121/// Use [`IsothermalIsobaric`] to set both the system temperature and pressure
122/// using a thermostat and barostat or Monte
123/// Carlo trial moves.
124///
125/// * Temperature is given in units of $` [\mathrm{energy}] `$:
126///   $` \mathrm{temperature} = kT `$.
127/// * Pressure is given in units of $` [\mathrm{energy}] \cdot
128///   [\mathrm{length}]^{-D} `$ where $` D `$ is the dimensionality of the system.
129///
130/// # Example
131/// ```
132/// use hoomd_simulation::macrostate::Isothermal;
133///
134/// let macrostate = Isothermal { temperature: 1.2 };
135/// ```
136#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
137pub struct IsothermalIsobaric {
138    /// Kinetic temperature of the system.
139    pub temperature: f64,
140    /// Pressure of the system.
141    pub pressure: f64,
142}
143impl Temperature for IsothermalIsobaric {
144    #[inline]
145    fn temperature(&self) -> &f64 {
146        &self.temperature
147    }
148
149    #[inline]
150    fn temperature_mut(&mut self) -> &mut f64 {
151        &mut self.temperature
152    }
153}
154impl Pressure for IsothermalIsobaric {
155    #[inline]
156    fn pressure(&self) -> &f64 {
157        &self.pressure
158    }
159
160    #[inline]
161    fn pressure_mut(&mut self) -> &mut f64 {
162        &mut self.pressure
163    }
164}
hoomd_simulation/macrostate.rs

hoomd_simulation/
macrostate.rs
