Pack

Spatial packing of molecules into periodic simulation boxes via Packmol.

Quick reference

Symbol	Summary	Preferred for
Molpack	High-level packing interface	Multi-component systems
InsideBoxConstraint	Cubic/orthorhombic box constraint	Standard periodic boxes
InsideSphereConstraint	Spherical region constraint	Droplet / cluster geometries
Target	One molecule species + count + constraint	Defining packing targets

Canonical example

import numpy as np
from molpy.pack import Molpack, InsideBoxConstraint

packer = Molpack(workdir="pack_output")
constraint = InsideBoxConstraint(
    length=np.array([30.0, 30.0, 30.0]),
    origin=np.zeros(3),
)
packer.add_target(water_frame, number=100, constraint=constraint)
packer.add_target(ion_frame, number=10, constraint=constraint)

packed = packer.optimize(max_steps=10000, seed=42)

Related

• Guide: Crosslinked Networks
• Guide: Polydisperse Systems

---

Full API

MolPack

molpack

Molpack - High-level molecular packing interface.

This module provides the main entry point for molecular packing using Packmol.

Molpack

Molpack(workdir)

High-level molecular packing interface.

This class provides a clean API for molecular packing using Packmol backend.

Usage

packer = Molpack(workdir=Path("packing")) packer.add_target(frame, number=100, constraint=box_constraint) result = packer.optimize(max_steps=1000, seed=42)

Initialize Molpack.

Parameters:

Name	Type	Description	Default
workdir	Path	Working directory for packing operations	required

add_target

add_target(frame, number, constraint)

Add a packing target.

Parameters:

Name	Type	Description	Default
frame	Frame	Frame containing the molecule structure	required
number	int	Number of copies to pack	required
constraint	Constraint	Spatial constraint for packing	required

Returns:

Type	Description
Target	Target object

optimize

optimize(max_steps=1000, seed=None, pbc=None)

Run packing optimization.

Parameters:

Name	Type	Description	Default
max_steps	int	Maximum optimization steps	1000
seed	int | None	Random seed. If None, uses random seed.	None
pbc	ndarray | list[float] | None	Periodic boundary conditions. 3 values [lx, ly, lz] for a box with origin at zero, or 6 values [xmin, ymin, zmin, xmax, ymax, zmax]. Requires Packmol >= 20.15.0.	None

Returns:

Type	Description
Frame	Packed Frame

Constraint

constraint

Constraint

Base class for all packing constraints.

dpenalty

dpenalty(points)

Calculate gradient of penalty with respect to points.

penalty

penalty(points)

Calculate penalty for given points. Lower is better.

Target

target

Target

Target(frame, number, constraint, is_fixed=False, name='')

points property

points

Get all points (coordinates replicated for each copy).

Packer

packer

Packer

Packer()

Bases: ABC

Base class for all packer implementations.

add_target

add_target(target)

Add a target to the packer.

def_target

def_target(frame, number, constraint, is_fixed=False, name='')

Define a target for packing.

Parameters:

Name	Type	Description	Default
frame	Frame	Frame containing the molecule structure	required
number	int	Number of copies to pack	required
constraint	Constraint	Spatial constraint for packing	required
is_fixed	bool	Whether this target is fixed	False
name	str	Optional name for this target	''

Returns:

Type	Description
Target	Created Target object

pack abstractmethod

pack(targets=None, max_steps=1000, seed=None)

Pack molecules according to targets.

Parameters:

Name	Type	Description	Default
targets	list[Target] | None	List of packing targets. If None, uses stored targets.	None
max_steps	int	Maximum optimization steps	1000
seed	int | None	Random seed for packing	None

Returns:

Type	Description
Frame	Packed Frame

Packmol

Packmol(executable=None, workdir=None)

Bases: Packer

Packer implementation using Packmol binary.

This class provides a packer that uses Packmol binary for packing molecules.

Usage

packer = Packmol(executable="packmol") result = packer(targets, max_steps=1000, seed=4628)

Initialize Packmol packer.

Parameters:

Name	Type	Description	Default
executable	str | None	Path to packmol executable. If None, uses: 1. PACKMOL_BIN environment variable 2. "packmol" on PATH	None
workdir	Path | None	Working directory for temporary files. If None, creates a temporary directory.	None

generate_input_only

generate_input_only(targets=None, max_steps=1000, seed=4628, tolerance=2.0, workdir=None)

Generate Packmol input file without running the packing.

Parameters:

Name	Type	Description	Default
targets	list[Target] | None	List of packing targets. If None, uses stored targets.	None
max_steps	int	Maximum optimization steps	1000
seed	int	Random seed for packing	4628
tolerance	float	Distance tolerance in Angstroms	2.0
workdir	Path | None	Optional working directory	None

Returns:

Type	Description
Path	Path to generated input file

generate_input_script

generate_input_script(targets=None, max_steps=1000, seed=4628, tolerance=2.0, workdir=None)

Generate Packmol input script as a Script object without saving.

This allows you to preview, edit, or format the script before saving.

Parameters:

Name	Type	Description	Default
targets	list[Target] | None	List of packing targets. If None, uses stored targets.	None
max_steps	int	Maximum optimization steps	1000
seed	int	Random seed for packing	4628
tolerance	float	Distance tolerance in Angstroms	2.0
workdir	Path | None	Optional working directory (for structure file paths)	None

Returns:

Type	Description
Script	Script object containing Packmol input

Raises:

Type	Description
ValueError	If no targets provided

pack

pack(targets=None, max_steps=1000, seed=None)

Pack molecules using Packmol backend.

This method implements the abstract pack() method from Packer base class. It delegates to call() for the actual implementation.

get_packer

get_packer(*args, **kwargs)

Factory function to get a packer instance.

Currently only supports Packmol backend.

Parameters:

Name	Type	Description	Default
*args	Any	Positional arguments passed to Packmol constructor	()
**kwargs	Any	Keyword arguments passed to Packmol constructor	{}

Returns:

Type	Description
Packmol	Packmol instance