Skip to content

molpack Manual

molpack

Packmol-compatible molecular packing in pure Rust — a CLI for `.inp` scripts, a Python package for notebooks and pipelines, and a native Rust crate.

molpack

Start here

Find the right page

This page is an index into the manual. Every surface lowers to the same model: molecule templates, copy counts, geometric restraints, then one packing run.

Workflows

Same packing model, four entry points

All entry points lower to the same target / count / restraint model. Pick the surface that matches how the rest of your workflow is written.

Path 01 · Script

Run a .inp job

Use the CLI for reproducible packing jobs that already live as Packmol-style input files. See the CLI guide.

structure water.pdb
  number 1000
  inside box 0. 0. 0. 40. 40. 40.
end structure
Path 02 · Python

Pack from a notebook or pipeline

Load or build a frame, create immutable targets, and pass the packed frame to the writer or analysis code you already use. See the Python API.

water = Target(frame, 100).with_restraint(
    molrs.Cuboid([0, 0, 0], [40, 40, 40])
)
packed = GenCanPack().with_seed(42).run([water], max_loops=200).frame
Path 03 · Rust

Embed the engine in a crate

Use the native builder API for applications, services, and tests. See the Rust API.

let result = GenCanPack::new()
    .with_seed(42)
    .run(&[water], 200)?;
Path 04 · Handler

Observe or stop a run

Handlers receive structured events from the packing loop. See Handlers and optimizers.

impl Handler for WatchFdist {
    fn on_step(&mut self, info: &StepInfo, _sys: &PackContext) {
        eprintln!("fdist={}", info.fdist);
    }
}

Features

Core capabilities

Dense summary of what the engine and each surface cover.

Targets
Molecule templates, copy counts, fixed placements, centering, and rotation bounds.
Restraints
Geometric boxes and spheres, planes, and collective distribution-matching terms.
Packer
GENCAN outer loop, pair-distance objective, optional rayon evaluation, seed control.
Scripts
Packmol-compatible `.inp` keywords, path resolution, and extra filetypes (SDF, LAMMPS).
Python
Frame-in / frame-out packing for notebooks and pipelines via molrs.
Rust
Native builders, handlers, in-loop optimizers, and feature-gated IO / FF / rayon.

Map

Documentation map

A compact mirror of the navigation tree for returning users.

Tutorial

Install, quickstart, concepts, examples, and Packmol parity notes.

Packmol Script

`.inp` overview, script notes, formats, and CLI examples.

Python

Installation, targets, restraints, packer options, PBC, and API reference.

Rust

Builders, restraints, PBC, handlers, in-loop optimizers, and example programs.

Development

Contributing, architecture, and extending the engine.

Surfaces

Jump to a surface

Packmol script Reproducible `.inp` jobs with familiar keywords. Python Notebooks, pipelines, and frame-based packing. Rust Native builders, handlers, and in-loop optimizers.