minitpr/
lib.rs

1// Released under Apache License 2.0 / MIT License.
2// Copyright (c) 2024 Ladislav Bartos
3
4//! # minitpr
5//!
6//! `minitpr` is a pure Rust library designed for parsing Gromacs tpr files, focusing on extracting system topology and structure.
7//!
8//! ## Capabilities and Limitations
9//! - Supports parsing of tpr files from version 103 onwards (Gromacs 5.1 and later).
10//! - Extracts system topology and structure: atoms, their basic properties (including positions, velocities, and forces), and bonds between atoms (including intermolecular bonds).
11//! - Does **not** support parsing of force-field and simulation parameters, nor does it offer capabilities to write tpr files.
12//!
13//! ## Usage
14//!
15//! To include `minitpr` in your project, add it as a dependency using Cargo:
16//!
17//! ```shell
18//! cargo add minitpr
19//!```
20//!
21//! ### Parsing a tpr file
22//! Example usage to parse a tpr file and handle potential errors:
23//! ```rust
24//! use minitpr::TprFile;
25//!
26//! fn main() {
27//!     let tpr = match TprFile::parse("topol.tpr") {
28//!         Ok(file) => file,
29//!         Err(error) => {
30//!             eprintln!("{}", error);
31//!             return;
32//!         },
33//!     };
34//!
35//!     // now you can work with the `tpr` object, accessing its properties and data
36//!     // for instance, to iterate through the atoms of the molecular system, use:
37//!     for atom in tpr.topology.atoms.iter() {
38//!         // perform some operation with the atom
39//!     }
40//! }
41//! ```
42//!
43//! ### Data Structures
44//! The [`TprFile`](`crate::TprFile`) structure encapsulates the following information:
45//!
46//! - Header: Metadata about the tpr file (see [`TprHeader`](`crate::TprHeader`) structure).
47//! - Molecular System Name: The name of the simulated system.
48//! - Simulation Box Dimensions: Available within the [`SimBox`](`crate::SimBox`) structure if present.
49//! - System Topology: Topology of the molecular system containing atoms and bonds (see [`TprTopology`](`crate::TprTopology`) structure).
50//!
51//! Each atom (see [`Atom`](`crate::Atom`)) represented in the system topology includes:
52//! - Atom name.
53//! - Sequential atom number, starting from 1.
54//! - Residue name.
55//! - Sequential residue number, starting from 1.
56//! - Mass.
57//! - Charge.
58//! - Element (`None` if unidentifiable).
59//! - Position (`None` if not present).
60//! - Velocity (`None` if not present).
61//! - Force (`None` if not present).
62//!
63//! ## Features
64//! ### Serialization/Deserialization
65//! Enable (de)serialization support for `TprFile` with `serde` by adding the feature flag during installation:
66//! ```shell
67//! cargo add minitpr --features serde
68//! ```
69//!
70//! ## License
71//! `minitpr` is open-sourced under either the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) or the [MIT License](https://opensource.org/license/MIT) at your option.
72//!
73//! ## Disclaimer
74//! Due to the huge number of various force field and simulation parameters and Gromacs options, it is very difficult to *comprehensively* test the `minitpr` library.
75//! Your contributions in the form of tests, tpr files with unusual parameters, or new functionality are very welcome. See [github.com/Ladme/minitpr](https://github.com/Ladme/minitpr).
76//!
77//! If the library is unable to parse your tpr file, but you believe it should be able to, please open a [GitHub issue](https://github.com/Ladme/minitpr/issues) and **upload your tpr file**.
78//!
79
80use errors::ParseTprError;
81use std::path::Path;
82
83pub mod errors;
84mod parse;
85pub mod structures;
86
87pub use structures::*;
88
89/// Current version of the `minitpr` library.
90pub const MINITPR_VERSION: &str = env!("CARGO_PKG_VERSION");
91
92/// Number of spatial dimensions.
93pub(crate) const DIM: usize = 3;
94/// Number of fields in the `F_RBDIHS` and `F_FOURDIHS` function types
95pub(crate) const NR_RBDIHS: usize = 6;
96/// Number of fields in the `F_CBTDIHS` function type
97pub(crate) const NR_CBTDIHS: usize = 6;
98/// Number of group types (TemperatureCoupling, EnergyOutput, Acceleration, etc.).
99pub(crate) const NR_GROUP_TYPES: usize = 10;
100
101impl TprFile {
102    /// Parse a Gromacs tpr file.
103    ///
104    /// ## Parameters
105    /// - `filename`: path to the tpr file to read
106    ///
107    /// ## Returns
108    /// - [`TprFile`](`crate::TprFile`) structure, if successful.
109    /// - Otherwise [`ParseTprError`](`crate::errors::ParseTprError`).
110    ///
111    /// ## Notes
112    /// - Only tpr files version 103 or higher are supported (Gromacs 5.1 onwards).
113    /// - The function only parses the following information: tpr file header,
114    ///   name of the system, simulation box, system topology (atoms and bonds),
115    ///   positions, velocities, and forces (if present).
116    /// - Force-field properties and simulation parameters are NOT parsed.
117    /// - If the tpr file does not contain topology information, this function will return an error.
118    pub fn parse(filename: impl AsRef<Path>) -> Result<Self, ParseTprError> {
119        parse::parse_tpr(filename)
120    }
121}
minitpr/lib.rs

minitpr/
lib.rs
