molcrafts-molpack

Packmol-grade molecular packing in pure Rust, with Python bindings. Part of the molrs toolkit.

Install

CLI

cargo install molcrafts-molpack --features cli

Rust library

cargo add molcrafts-molpack

Python

pip install molcrafts-molpack molcrafts-molrs

CLI

The molpack binary accepts the same .inp script format as Packmol, making it a drop-in replacement. Relative file paths in the script are resolved against the script's own directory (file-arg mode) or the current directory (stdin mode).

# File argument (paths resolved relative to the .inp file's directory)
molpack mixture.inp

# Stdin — compatible with Packmol usage
molpack < mixture.inp
cat mixture.inp | molpack

Supported .inp keywords

All 12 box/cube/sphere/ellipsoid/cylinder/plane restraints are reachable from both whole-molecule and atoms … end atoms blocks. The Gaussian-surface restraints (AboveGaussianRestraint / BelowGaussianRestraint) are available through the Rust/Python API but not yet exposed as .inp keywords. To drive a whole species onto a target spatial distribution, use the collective ProfileMatch restraint via the Rust/Python API (with_collective_restraint).

Extended format support — beyond Packmol's PDB/XYZ, molpack also reads SDF/MOL, LAMMPS dump, and LAMMPS data files. Set filetype to sdf, lammps_dump, or lammps_data, or use the matching file extension:

Quick start

Rust

use molpack::{InsideBoxRestraint, Molpack, Target};

let positions = [[0.0, 0.0, 0.0], [0.96, 0.0, 0.0], [-0.24, 0.93, 0.0]];
let radii = [1.52, 1.20, 1.20];

let target = Target::from_coords(&positions, &radii, 100)
    .with_name("water")
    .with_restraint(InsideBoxRestraint::new([0.0; 3], [40.0; 3], [false; 3]));

// `pack` returns the packed, topology-complete `molrs::Frame`.
// Every tuning knob has a Packmol-matching default, so `new().pack(...)`
// is a complete call; `200` is the outer-loop budget.
let frame = Molpack::new().pack(&[target], 200)?;

// For full diagnostics, use `pack_with_report` → `PackResult`
// (`frame`, `fdist`, `frest`, `converged`).
let report = Molpack::new().pack_with_report(&[target], 200)?;

Python

import molrs
from molpack import InsideBoxRestraint, Molpack, Target

frame = molrs.read_pdb("water.pdb")

water = (
    Target(frame, count=100)
    .with_name("water")
    .with_restraint(InsideBoxRestraint([0, 0, 0], [40, 40, 40]))
)
frame = Molpack().pack([water], max_loops=200)

Examples

Five canonical workloads ship in examples/ (they need the io feature to read the bundled structure files):

cargo run --release --example pack_mixture     --features io   # 1000 water + 400 urea in a cube
cargo run --release --example pack_bilayer     --features io   # membrane leaflets via per-atom plane restraints
cargo run --release --example pack_interface   --features io   # water + chloroform around a fixed molecule
cargo run --release --example pack_spherical   --features io   # concentric lipid/water shells (largest case)
cargo run --release --example pack_solvprotein --features io   # fixed protein solvated in a sphere (avoid_overlap)

The same workloads run through the CLI from their bundled .inp scripts, e.g. cargo run --release --features cli --bin molpack -- examples/pack_mixture/mixture.inp. Python equivalents are in python/examples/.

A measurement harness also lives under examples/: mt_scaling (parallel speed-up-vs-size sweep, needs --features rayon).

Testing

cargo test                                                  # unit + integration
cargo test --release --test examples_batch -- --ignored     # Packmol regression (all 5 workloads)
cargo bench --benches                                       # criterion regression benches (no io)
cd python && maturin develop --release && pytest            # Python wheel

Documentation

• Guide — the Markdown chapters under docs/: install, getting started, concepts, examples, Packmol parity, architecture, and extending.
• Rust API — cargo doc --open, or docs.rs. The four long-form chapters (getting started, concepts, architecture, extending) are also embedded in the rustdoc as molpack::getting_started, molpack::concepts, molpack::architecture, and molpack::extending.
• Python — the binding docs under docs/python/ (installation, guide, examples, and the Python API reference), published as the Python section of the same Zensical site.

Contributing

See CONTRIBUTING.md. Bugs and feature requests via GitHub Issues.

License

BSD-3-Clause

References

• Martínez, L.; Andrade, R.; Birgin, E. G.; Martínez, J. M. PACKMOL: A package for building initial configurations for molecular dynamics simulations. J. Comput. Chem. 2009, 30 (13), 2157–2164. https://doi.org/10.1002/jcc.21224