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.

Vision

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.

Capabilities

One crate, molcrafts-molrs, whose sub-systems are feature-gated modules (core is always on; full enables everything):

Module (feature)	Capability
core (always on)	Frame / Block column store, MolGraph topology, elements, rings, stereochemistry, Gasteiger charges, hydrogen perception, simulation boxes, neighbor search (LinkCell / brute force)
io	Readers / writers for PDB, XYZ, mol2, SDF, CIF, GRO, POSCAR, CHGCAR, Cube, LAMMPS data/dump, DCD, Zarr V3 trajectories (SMILES/SMARTS parser under the smiles feature)
compute	Trajectory analysis: RDF, MSD, clustering, gyration / inertia tensors, PCA, k-means, density, diffraction, PMFT, order parameters, dielectric, environment matching
ff	Force fields and potentials — MMFF94 bond/angle/torsion/oop/vdW/electrostatics, LJ, PME — with an atom typifier
conformer	3D conformer generation: ETKDGv3 distance geometry, experimental-torsion refinement, MMFF94 cleanup, stereo guards
signal	Signal processing — FFT-based autocorrelation, window functions, frequency grids

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

Install

cargo add molcrafts-molrs

Opt into sub-systems via feature flags; full enables everything:

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

Python: pip install molcrafts-molrs (import as molrs). Browser: npm install @molcrafts/molrs.

Python nightly. Bleeding-edge Python wheels are published to the separate project molcrafts-molrs-nightly (versioned X.Y.Z.devN) on every push to the nightly branch — Python only; crates.io and npm ship exclusively from v* tags. Install with pip install --pre molcrafts-molrs-nightly. It imports as molrs, so it cannot be installed alongside the stable molcrafts-molrs.

Build from source

Building from source needs the Rust toolchain. The pinned channel, the rustfmt / clippy components, and the wasm32-unknown-unknown target are all declared in rust-toolchain.toml, so rustup selects them automatically on the first build.

git clone https://github.com/MolCrafts/molrs.git
cd molrs
cargo build --workspace            # compile the library + the C bridge crate
bash scripts/fetch-test-data.sh    # fetch test fixtures (first run only)
cargo test --all-features          # run the test suite

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.parse_smiles('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.

Quick start

use molrs::conformer::{Conformer, ConformerOptions};
use molrs::smiles::{parse_smiles, to_atomistic};

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

Python and JavaScript/TypeScript quickstarts live in the documentation.

Documentation

• Documentation site — guides and references
• Getting started — Rust, Python, and WASM quickstarts
• Guides — data model, SMILES, neighbor search, 3D embedding, force fields, I/O, trajectory analysis
• Rust API reference — full rustdoc on docs.rs

MolCrafts ecosystem

Project	Role
molpy	Python toolkit — the shared molecular data model & workflow layer
molrs	Rust core — molecular data structures & compute kernels (native + WASM) — this repo
molpack	Packmol-grade molecular packing (Rust + Python)
molvis	WebGL molecular visualization & editing
molexp	Workflow & experiment-management platform
molnex	Molecular machine-learning framework
molq	Unified job queue — local / SLURM / PBS / LSF
molcfg	Layered configuration library
mollog	Structured logging, stdlib-compatible
molhub	Molecular dataset hub
molmcp	MCP server for the ecosystem
molrec	Atomistic record specification

Contributing

See CONTRIBUTING for development setup and guidelines.

License

BSD-3-Clause — see LICENSE.

---