Struct Molpack 

pub struct Molpack { /* private fields */ }

The packer.

Implementations

impl Molpack

pub fn new() -> Self

Create a packer with default settings and no handlers.

All tuning knobs are set via with_* methods below; they all have defensible defaults, so Molpack::new().pack(&targets, max_loops) is a valid invocation. The one argument that has no default is max_loops — it depends on system size and convergence difficulty, so it lives on the terminal pack call, not on the builder.

pub fn with_handler(self, h: impl Handler + 'static) -> Self

Append a progress handler. Multiple handlers compose in call order.

pub fn with_global_restraint(self, r: impl AtomRestraint + 'static) -> Self

Append a global restraint — applied to every atom of every target at pack() time.

Semantic equivalence (scope law):

molpack.with_global_restraint(r)
  ≡ for each target: target.with_restraint(r.clone())

Implementation mirrors the equivalence — no separate “global restraint” storage path in PackContext; the restraint is cloned into each target’s molecule_restraints when pack() is invoked.

pub fn with_precision(self, p: F) -> Self

Convergence precision for fdist and frest (default 0.01).

pub fn with_tolerance(self, t: F) -> Self

Minimum atom-atom distance tolerance (default 2.0 Å). Atom radii are set to tolerance / 2.

pub fn with_inner_iterations(self, n: usize) -> Self

GENCAN inner iteration count (default 20; Packmol maxit).

pub fn with_avoid_overlap(self, enabled: bool) -> Self

Whether to reject initial random placements that overlap a fixed molecule (default true; Packmol’s avoid_overlap). Leave on unless you have a specific reason to allow solvent to seed inside a fixed solute — disabling it can slow dense-solvation packing by 10× or more.

pub fn with_init_passes(self, n: usize) -> Self

Initialization outer-loop passes (Packmol nloop0). 0 restores the Packmol default of 20 * ntype.

pub fn with_init_box_half_size(self, f: F) -> Self

Maximum half-size of the initial placement box (default 1000.0; Packmol sidemax).

pub fn with_periodic_box(self, min: [F; 3], max: [F; 3]) -> Self

Declare a global periodic-boundary box (Packmol pbc). Every axis is treated as periodic. When set, the packer’s cell grid is built from max - min, bypassing the fallback that derives a box from post-Phase-1 atom positions — which can be ±sidemax wide when the script has no spatial constraints and drives ncells to 10⁸+ cells.

If any restraint also declares a periodic_box(), the two must match exactly (bounds + flags) or pack() returns PackError::ConflictingPeriodicBoxes.

pub fn with_perturb_fraction(self, f: F) -> Self

Fraction of molecules re-sampled when packing stalls (default 0.05; Packmol movefrac).

pub fn with_random_perturb(self, enabled: bool) -> Self

Randomize perturbation target selection (default false; Packmol movebadrandom).

pub fn with_perturb(self, enabled: bool) -> Self

Enable the stall-perturbation heuristic (default true; inverts Packmol’s disable_movebad). Pass false to disable.

pub fn with_seed(self, seed: u64) -> Self

Seed for the internal RNG (default 1_234_567, matching Packmol; deterministic — the same seed reproduces the same packing).

pub fn with_parallel_eval(self, enabled: bool) -> Self

Run the pair-kernel reductions on rayon worker threads (default false).

Parallelism is opt-in because the crossover where rayon pays off is workload-shaped, not size-shaped — the per-call parallel speedup measured on isolated compute_fg doesn’t predict end-to-end Molpack::pack wall clock (task-dispatch overhead accumulates across thousands of calls per pack; the perturbation pass skips the parallel path entirely; real workloads often regress even when active_cells.len() clears any naive threshold). The user knows their workload shape; the library doesn’t.

Compile with --features rayon for this flag to have any effect. Without the feature the pair kernel is serial unconditionally and this setting is silently ignored.

pub fn with_lammps_output(self, enabled: bool) -> Self

Enable or disable built-in LAMMPS-style screen output.

This is intentionally a builder-level concern: pack() returns the packed molrs::Frame, while timing, optimization diagnostics, and system summaries are streamed to stderr when enabled.

pub fn with_log_level(self, level: MolpackLogLevel) -> Self

Set built-in screen-log detail.

Quiet is the default. Summary prints system/phase/final summaries, Progress also prints thermo-style per-step lines, and Verbose adds extra diagnostic columns.

pub fn with_log_frequency(self, n: usize) -> Self

Print every n outer iterations for progress/verbose logs.

Values below 1 are clamped to 1.

pub fn pack( &mut self, targets: &[Target], max_loops: usize, ) -> Result<Frame, PackError>

Run the packing.

max_loops is the outer iteration budget; it is positional because there is no defensible default (the right value depends on system size and convergence difficulty). Every other knob lives on the builder.

Returns the packed molrs::Frame. Enable built-in screen logging with with_lammps_output or with_log_level for timing, optimization diagnostics, and system summaries.

pub fn pack_with_report( &mut self, targets: &[Target], max_loops: usize, ) -> Result<PackResult, PackError>

Run the packing and retain structured convergence diagnostics.

This is mainly for tests, bindings, and advanced programmatic callers. The primary user-facing API is pack, which returns only the packed frame.

Trait Implementations

impl Default for Molpack

fn default() -> Self

Returns the “default value” for a type.