molrs

molrs is a Rust library for molecular modeling: a column-oriented data model, format readers and writers, trajectory analysis, force fields, and 3D structure generation. The same code runs natively, from Python (PyO3), and in the browser (WASM).

Under active development. Public APIs may change between minor releases.

Molecular modeling tools have long forced a choice between fast and reusable. The performance-critical kernels live in aging C and Fortran, while the science is written in Python wrappers that cannot run anywhere a Python interpreter does not. molrs exists to dissolve that split: one correct, well-tested implementation of the molecular data model and its compute kernels, written once in Rust.

That single implementation is meant to be portable everywhere molecules are studied — a native library, a Python package, and a WebAssembly module that runs in a browser tab with no install. The aspiration is that a researcher, a pipeline, and an interactive web tool can all reach for the exact same neighbor search, the same RDF, the same force-field evaluation, and get identical numbers.

By becoming the dependable core the rest of the MolCrafts ecosystem builds on, molrs aims to make high-performance, reference-grade molecular computation something you take for granted rather than something you reimplement.

One crate, molcrafts-molrs, whose sub-systems are feature-gated modules (core and perceive are always on):

A separate molcrafts-molrs-cxxapi crate (built from source, not published) provides a CXX bridge for zero-copy integration with Atomiverse C++.

cargo add molcrafts-molrs

The default build is core only (core, perceive, the optimize contract) plus rayon. Every sub-system is opt-in: name the modules you need, or full for all of them (builder, io, smiles, compute, voronoi, ff, conformer, md). full does not enable stream or filesystem (path-backed Zarr); add them explicitly. default-features = false also drops rayon (wasm, Pyodide).

molcrafts-molrs = { version = "0.19", features = ["io", "smiles", "conformer"] }

PyPI ships desktop wheels (manylinux / macOS / Windows) and a Pyodide (Emscripten) wheel for micropip. The npm package is a separate wasm-bindgen build used by MolVis; it is not the Python extension.

# In Pyodide (browser or Node)
import micropip
await micropip.install("molcrafts-molrs")
import molrs

Python nightly. Bleeding-edge wheels go to molcrafts-molrs-nightly (X.Y.Z.devN) on the nightly branch. pip install --pre molcrafts-molrs-nightly imports as molrs and cannot sit beside stable molcrafts-molrs.

Building from source needs the Rust toolchain. rust-toolchain.toml pins one exact rustc / rustfmt / clippy release plus the wasm32-unknown-unknown target, so rustup selects them automatically on the first build, and local builds, the prek hooks and CI all use the same compiler.

git clone https://github.com/MolCrafts/molrs.git
cd molrs
# `mrs-*` are cargo aliases committed in .cargo/config.toml. They pin one
# feature set, so every command reuses the same build instead of compiling
# the crate again under a slightly different spelling.
cargo mrs-build   # compile the Rust library
cargo mrs-test    # unit tests
cargo mrs-doctest # rustdoc examples
scripts/check.sh verify  # the pre-push gate: every check, once

Binding crates are standalone workspaces. Build each with cargo build --manifest-path <crate>/Cargo.toml.

Python bindings are built from the molrs-python crate with maturin. maturin develop compiles the PyO3 extension and installs it editable into the active virtualenv under the import name molrs:

pip install maturin
maturin develop -m molrs-python/Cargo.toml --release
python -c "import molrs; print(molrs.io.smiles.SmilesIr('O').n_components)"

WASM / npm is built with wasm-pack, using the same flags as release publishing:

cd molrs-wasm
wasm-pack build --release --target bundler --scope molcrafts --out-name molrs

See the installation guide for environment-verification snippets and the contributing guide for the documentation loop.

use molrs::conformer::{Conformer, ConformerOptions};
use molrs::io::read_smiles_str;

let mol = read_smiles_str("c1ccccc1").unwrap();      // benzene
let (mol3d, _report) = Conformer::new(ConformerOptions::default()).generate(&mol).unwrap();

Python and JavaScript/TypeScript quickstarts live in the documentation.

• Documentation site — guides and references
• Getting started — Rust, Python, and WASM quickstarts
• Python reference — the binding surface, rendered from the installed package
• Task-oriented guides — data model, SMILES, neighbor search, 3D embedding, force fields, I/O, trajectory analysis (molpy, the Python library built on molrs)
• Rust API reference — full rustdoc on docs.rs
• Record files — saving frames, trajectories and force fields as *.mrec

See CONTRIBUTING for development setup and guidelines. The release checklist covers local verification, package inspection, and the tag-triggered publishing workflow.

BSD-3-Clause — see LICENSE.