Crate molpack 

molpack

Packmol-grade molecular packing in pure Rust. Produces a non-overlapping arrangement of N molecule types with copy counts and geometric restraints, using a faithful port of Packmol’s GENCAN-driven three-phase algorithm (Martínez et al. 2009). Correctness is checked against Packmol’s reference output for five canonical workloads.

This crate was split out of the molrs workspace in 2026 and is now maintained independently. It depends on the unified molcrafts-molrs crate for shared data structures (always-on core) and, behind feature flags, its file I/O (io) and force-field (ff) modules.

Documentation map

This crate is documented in four dedicated modules; start with getting_started if you are new.

• getting_started — install, hello-world packing, the three restraint scopes, handlers, relaxers, PBC, running the canonical examples.
• concepts — every abstraction defined in one place: AtomRestraint, Region, Relaxer, Handler, Objective, Target, Molpack, PackContext; the scope equivalence law; the two-scale contract; the direction-3 extension pattern.
• architecture — module map, dependency graph, core-type relationships, full pack() lifecycle diagram, hot-path evaluate() walkthrough, invariants, design decisions.
• extending — tutorials for writing your own AtomRestraint / Region / Handler / Relaxer; testing + benchmarking discipline; common pitfalls; contributing flow.

Reference material (not rustdoc):

• Packmol parity — kind-number ↔ Rust struct mapping with Fortran pointers.

Quick example

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, 40.0, 40.0], [false; 3]));

let frame = Molpack::new()
    .with_tolerance(2.0)
    .with_precision(0.01)
    .with_seed(42)
    .pack(&[target], 200)?;

let natoms = frame.get("atoms").and_then(|b| b.nrows()).unwrap_or(0);
println!("packed {natoms} atoms");

Public surface at a glance

Category	Items
Builder	Molpack, MolpackLogLevel, PackResult
Target	Target, CenteringMode
AtomRestraint trait + 14 concrete structs	AtomRestraint + InsideBox / InsideCube / InsideSphere / InsideEllipsoid / InsideCylinder / Outside* variants / AbovePlane / BelowPlane / AboveGaussian / BelowGaussian — each suffixed …AtomRestraint
Region trait + combinators + lift	Region, RegionExt, And, Or, Not, RegionRestraint, InsideBoxRegion, InsideSphereRegion, OutsideSphereRegion, Aabb
Handler trait + built-ins	Handler, NullHandler, LammpsLogHandler, ProgressHandler, EarlyStopHandler, XYZHandler, StepInfo, PhaseInfo, PhaseReport
Relaxer trait + built-ins	Relaxer, RelaxerRunner, TorsionMcRelaxer, LBFGSRelaxer (ff feature)
Errors	PackError
Validation	validate_from_targets, ValidationReport, ViolationMetrics
Examples harness	[ExampleCase], [build_targets], [example_dir_from_manifest], [render_inp_script]

Feature flags

• rayon — opt into the parallel evaluator (also forwards to molrs’s rayon).
• io — pull in molrs’s io module so [script::Script::build] can read PDB / SDF / XYZ / LAMMPS files directly. PyO3 / WASM / embedding hosts that bring their own loader leave this off and use script::Script::lower with script::StructurePlan::apply instead.
• cli — build the molpack binary and its integration tests (pulls in clap and implies io).
• ff — pull in molrs’s ff module (MMFF typifier + L-BFGS) and enable the LBFGSRelaxer, which relaxes a flexible molecule’s internal geometry during packing under a caller-supplied force field.

Precision is fixed at f64 via molrs::types::F.

Re-exports

pub use context::PackContext;

pub use error::PackError;

pub use frame::compute_mol_ids;

pub use frame::context_to_frame;

pub use frame::finalize_frame;

pub use frame::frame_to_coords;

pub use handler::EarlyStopHandler;

pub use handler::Handler;

pub use handler::LammpsLogHandler;

pub use handler::MolpackLogLevel;

pub use handler::NullHandler;

pub use handler::PhaseInfo;

pub use handler::PhaseReport;

pub use handler::ProgressHandler;

pub use handler::StepInfo;

pub use handler::XYZHandler;

pub use packer::Molpack;

pub use packer::PackResult;

pub use region::Aabb;

pub use region::And;

pub use region::InsideBoxRegion;

pub use region::InsideSphereRegion;

pub use region::Not;

pub use region::Or;

pub use region::OutsideSphereRegion;

pub use region::Region;

pub use region::RegionExt;

pub use region::RegionRestraint;

pub use relaxer::Relaxer;

pub use relaxer::RelaxerRunner;

pub use relaxer::TorsionMcRelaxer;

pub use restraint::AboveGaussianRestraint;

pub use restraint::AbovePlaneRestraint;

pub use restraint::AtomRestraint;

pub use restraint::BelowGaussianRestraint;

pub use restraint::BelowPlaneRestraint;

pub use restraint::InsideBoxRestraint;

pub use restraint::InsideCubeRestraint;

pub use restraint::InsideCylinderRestraint;

pub use restraint::InsideEllipsoidRestraint;

pub use restraint::InsideSphereRestraint;

pub use restraint::OutsideBoxRestraint;

pub use restraint::OutsideCubeRestraint;

pub use restraint::OutsideCylinderRestraint;

pub use restraint::OutsideEllipsoidRestraint;

pub use restraint::OutsideSphereRestraint;

pub use target::Angle;

pub use target::Axis;

pub use target::CenteringMode;

pub use target::Placement;

pub use target::Target;

pub use validation::ValidationReport;

pub use validation::ViolationMetrics;

pub use validation::validate_from_targets;

pub use constraints::Constraints;

pub use constraints::EvalMode;

pub use constraints::EvalOutput;

pub use objective::Objective;

Modules

architecture

Architecture

assemble

Build a topology-complete molrs::Frame from packed coordinates.

cell

3D linked cell list implementation. Exact port of cell_indexing.f90, resetcells.f90 and pbc.f90 from Packmol.

concepts

Core Concepts

constraints

Constraints container layer.

context

Context layer for packmol-aligned packing runtime.

error

euler

Exact port of polartocart.f90 from Packmol.

extending

Extending the Crate

frame

Helpers for converting between molrs_core::Frame and packing inputs.

gencan

GENCAN optimizer — faithful Rust port of gencan.f and pgencan.f90.

getting_started

Getting Started

handler

Handler trait and built-in handlers for packing progress callbacks.

initial

Initialization procedures. Port of initial.f90, restmol.f90, cenmass.f90.

movebad

movebad heuristic and flashsort. Port of heuristics.f90 and flashsort.f90.

objective

Objective function and gradient computation. Exact port of computef.f90, computeg.f90, fparc.f90, gparc.f90.

packer

Main packing orchestration. Port of the outer loop in app/packmol.f90.

prelude

Bulk re-export of the items a typical packing script needs.

region

Geometric Region trait and composition combinators.

relaxer

Per-target in-loop relaxer system for molecular packing.

restraint

AtomRestraint trait and concrete soft-penalty types for molecular packing.

script

Script loader: parse molpack’s .inp input format and turn it into a configured Molpack plus a list of Targets.

target

Target builder for molecular packing.

validation

Enums

Element

Chemical element with complete periodic table (elements 1-118)

Type Aliases

F

Primary floating-point scalar type — always f64.