Skip to content

Pack

Spatial packing of molecules into simulation boxes via molpack (molcrafts-molpack).

Install separately:

pip install molcrafts-molpack

Packing is not a molpy runtime dependency and is not part of the docs build. Examples below are frozen illustrations — full API lives in the molpack Python guide.

Quick reference

Symbol Package Preferred for
GencanPack molpack Rigid-body packing of several species
Target molpack One species + count + restraints
Cuboid / Sphere / HalfSpace molpy (molrs regions) Restraints: box, droplet, slab; combine with &, \|, ~
State molpack run result: .frame, .converged, .fdist, …
PackingTemplate molpy.builder A built molecule's .frame plus the .hydrogens indices into it, for per-atom settings such as Target(...).with_atom_radius(...)

Canonical example

# docs: skip — optional molcrafts-molpack; not a molpy runtime/doc dep
import molpy as mp
from molpack import GencanPack, Target

water = mp.Atomistic(name="water")
o = water.add_atom(atomic_number=8, x=0.0, y=0.0, z=0.0)
water.add_bond(o, water.add_atom(atomic_number=1, x=0.957, y=0.0, z=0.0))
water.add_bond(o, water.add_atom(atomic_number=1, x=-0.239, y=0.927, z=0.0))

ion = mp.Atomistic(name="sodium")
ion.add_atom(atomic_number=11, x=0.0, y=0.0, z=0.0, charge=1.0)

box = mp.core.Cuboid([0.0, 0.0, 0.0], [30.0, 30.0, 30.0])
targets = [
 Target(water.to_frame(), count=100).with_name("water").with_restraint(box),
 Target(ion.to_frame(), count=10).with_name("na").with_restraint(box),
]
packed = GencanPack().with_seed(42).run(targets, max_loops=200).frame

A built polymer goes in through mp.builder.PackingTemplate, so the atom indices a Target takes are read off the same frame it packs. molpack already treats element-H atoms as hydrogens, so the indices are only for per-atom settings such as a smaller radius:

# docs: skip — optional molcrafts-molpack; not a molpy runtime/doc dep
template = mp.builder.PackingTemplate(chain)  # chain: an assembled mp.Atomistic
target = (
    Target(template.frame, count=10)
    .with_restraint(box)
    .with_atom_radius(template.hydrogens, 0.2)
)