molio

molio is a Rust library for reading and writing chemistry files used in computational chemistry simulations. It provides a unified interface to access atomic (positions, velocities, atomic symbols) and trajectory (frames, topology) information and other data across various chemical file formats.

Currently supports

This project is heavily inspired by chemfiles, a modern C++ library with the same purpose.

Usage

Reading Trajectories

use std::path::Path;
use molio::trajectory::Trajectory;

// Open a trajectory file
let path = Path::new("./src/tests-data/xyz/extended.xyz");
let mut trajectory = Trajectory::open(path).unwrap();

// Read a specific frame
let frame = trajectory.read_at(0).unwrap().unwrap();

// Access frame properties
let energy = frame.properties["ENERGY"].expect_double();

// Access atomic properties
let atom = &frame[0];
let unit_cell = frame.unit_cell;

Writing Trajectories

use std::path::Path;
use molio::{trajectory::Trajectory, frame::Frame, atom::Atom};

// Create a trajectory file for writing
let path = Path::new("output.pdb");
let mut writer = Trajectory::create(path).unwrap();

// Populate Frame with a single C atom with position [1.0, 2.0, 3.0]
let mut frame = Frame::new();
frame.add_atom(Atom::new("C".to_string()), [1.0, 2.0, 3.0]);
// ..add other properties here

// Write frames
writer.write(&frame).unwrap();

// Optionally, explicitly finalize the file (for example, adds END record for PDB)
// If not called explicitly, finalization happens when writer is dropped
writer.finish().unwrap();

Format specific notes

• AMBER: we use netcdf3, a pure Rust implementation for reading and writing NetCDF-3 files, to read AMBER trajectories. However, due to the way that lib performs, writes to disk won't happen until we hit finish(). There are no partial writes.

This also means that we can only read AMBER trajectories based on NetCDF-3 files.

When reading the topology, we assume that the topology file has the same name as the .nc file. For example, if the trajectory file is titled trajectory.nc, the topology must exist in trajectory.parm7. Otherwise, topology data won't be read.

Contributions

Contributions are very welcome! Please open an issue to discuss bugs or new features.

Citation

Consider citing the original chemfiles library.