packmm is a simple python package that allows to build atomistic and molecular systems which are of interest for materials and molecular modelling.
It tries to generate realistic starting configuration by employing machine learnt interatomic potential for describing interactions between atoms and Monte Carlo, Molecular Dynamics and hybrid Monte Carlo.
It is using janus-core for MLIPs (mace mp is the default) and for MD and Geometry optimisation routines.
It provides both a cli and a python api, with some examples below.
python3 -m pip install pack-mm # or
uv pip install pack-mm
or install the latest
python3 -m pip install git+https://github.com/ddmms/pack-mm.git # or
uv pip install git+https://github.com/ddmms/pack-mm.git
by default runs on cpu, if you want to use gpus (recommended for big systems) pass --device cuda to cli or device="cuda" to python API.
packmm --system examples/data/UiO-66.cif --molecule H2O --nmols 10 --where sphere --centre 10.0,10.0,10.0 --radius 5.0 --geometry
packmm --system examples/data/MFI.cif --molecule H2O --nmols 30 --where cylinderY --centre 10.0,10.0,13.0 --radius 3.5 --height 19.00 --no-geometry
packmm --system examples/data/NaCl.cif --molecule H2O --nmols 30 --where box --centre 8.5,8.5,16.0 --a 16.9 --b 16.9 --c 7.5 --no-geometry
first add a methanol
packmm --system examples/data/Cu2L.cif --molecule examples/data/Ethanol.xyz --nmols 1 --where sphere --centre 5.18,8.15,25.25 --radius 1 --model small-0b2 --geometry
packmm --system Cu2L-ethanol.cif --molecule H2O --nmols 10 --where ellipsoid --centre 5.18,8.15,25.25 --a 5.18 --b 8.15 --c 8.25 --no-geometry --model small-0b2
packmm --molecule H2O --nmols 33 --where anywhere --cell-a 10.0 --cell-b 10.0 --cell-c 10.0 --model small-0b2
packmm --system Pd-super.cif --molecule H2 --nmols 50 --where anywhere --model small-0b2
before optimisation
after optimisation
packmm --help
Usage: packmm [OPTIONS]
Pack molecules into a system based on the specified parameters.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --system TEXT The original box in which │
│ you want to add particles. │
│ If not provided, an empty │
│ box will be created. │
│ [default: None] │
│ --molecule TEXT Name of the molecule to be │
│ processed, ASE-recognizable │
│ or ASE-readable file. │
│ [default: H2O] │
│ --nmols INTEGER Target number of molecules │
│ to insert. │
│ [default: -1] │
│ --ntries INTEGER Maximum number of attempts │
│ to insert each molecule. │
│ [default: 50] │
│ --seed INTEGER Random seed for │
│ reproducibility. │
│ [default: 2025] │
│ --where [anywhere|sphere|box|cylin Where to insert the │
│ derZ|cylinderY|cylinderX|e molecule. Choices: │
│ llipsoid] 'anywhere', 'sphere', │
│ 'box', 'cylinderZ', │
│ 'cylinderY', 'cylinderX', │
│ 'ellipsoid'. │
│ [default: anywhere] │
│ --centre TEXT Centre of the insertion │
│ zone, coordinates in Å, │
│ e.g., '5.0, 5.0, 5.0'. │
│ [default: None] │
│ --radius FLOAT Radius of the sphere or │
│ cylinder in Å, depending on │
│ the insertion volume. │
│ [default: None] │
│ --height FLOAT Height of the cylinder in │
│ Å. │
│ [default: None] │
│ --a FLOAT Side of the box or │
│ semi-axis of the ellipsoid, │
│ in Å, depends on the │
│ insertion method. │
│ [default: None] │
│ --b FLOAT Side of the box or │
│ semi-axis of the ellipsoid, │
│ in Å, depends on the │
│ insertion method. │
│ [default: None] │
│ --c FLOAT Side of the box or │
│ semi-axis of the ellipsoid, │
│ in Å, depends on the │
│ insertion method. │
│ [default: None] │
│ --device TEXT Device to run calculations │
│ on (e.g., 'cpu' or 'cuda'). │
│ [default: cpu] │
│ --model TEXT ML model to use. │
│ [default: medium-omat-0] │
│ --arch TEXT MLIP architecture to use. │
│ [default: mace_mp] │
│ --temperature FLOAT Temperature for the Monte │
│ Carlo acceptance rule. │
│ [default: 300.0] │
│ --cell-a FLOAT Side of the empty box along │
│ the x-axis in Å. │
│ [default: 20.0] │
│ --cell-b FLOAT Side of the empty box along │
│ the y-axis in Å. │
│ [default: 20.0] │
│ --cell-c FLOAT Side of the empty box along │
│ the z-axis in Å. │
│ [default: 20.0] │
│ --fmax FLOAT force tollerance for │
│ optimisation if needed. │
│ [default: 0.1] │
│ --geometry --no-geometry Perform geometry │
│ optimization at the end. │
│ [default: geometry] │
│ --out-path TEXT path to save various │
│ outputs. │
│ [default: .] │
│ --install-completion Install completion for the │
│ current shell. │
│ --show-completion Show completion for the │
│ current shell, to copy it │
│ or customize the │
│ installation. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯