hoomd_simulation/lib.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#![doc(
5 html_favicon_url = "https://raw.githubusercontent.com/glotzerlab/hoomd-rs/7352214172a490cc716492e9724ff42720a0018a/doc/theme/favicon.svg"
6)]
7#![doc(
8 html_logo_url = "https://raw.githubusercontent.com/glotzerlab/hoomd-rs/7352214172a490cc716492e9724ff42720a0018a/doc/theme/favicon.svg"
9)]
10
11//! Interact with simulations.
12//!
13//! ## Simulation
14//!
15//! `hoomd-simulation` defines the [`Simulation`] trait. Implement it for a type
16//! that holds the simulation parameters, types that implement the simulation
17//! model, and the microstate (or microstates) that it operates on.
18//!
19//! See the tutorials in the documentation for numerous examples.
20//!
21//! ## Macrostate
22//!
23//! The [`macrostate`] module provides types that set the parameters of the
24//! simulation. For example, set the temperature of the simulation with:
25//! ```
26//! use hoomd_simulation::macrostate::Isothermal;
27//!
28//! let macrostate = Isothermal { temperature: 1.2 };
29//! ```
30//!
31//! # Complete documentation
32//!
33//! `hoomd-simulation` is is a part of *hoomd-rs*. Read the [complete documentation]
34//! for more information.
35//!
36//! [complete documentation]: https://hoomd-rs.readthedocs.io
37
38pub mod macrostate;
39
40/// Store parameters, the model and the microstate(s) it acts on.
41///
42/// A [`Simulation`] type stores the microstate, all model actors, and any
43/// macrostate parameters in fields. A given [`Simulation`] can be advanced
44/// forward one step at a time via the `advance` method.
45pub trait Simulation {
46 /// Advance the simulation forward one step.
47 ///
48 /// # Errors
49 ///
50 /// When an error occurs, return an `Err` with any type that implements
51 /// [`Error`]. The caller will catch the error and
52 /// display it when exiting.
53 ///
54 /// [`Error`]: std::error::Error
55 fn advance(&mut self) -> anyhow::Result<()>;
56
57 /// Get the simulation step.
58 fn step(&self) -> u64;
59}