warp-pack Command Reference

CPU-first packer for building initial molecular coordinates from small molecule templates. Compatible with Packmol configuration format.

Synopsis

warp-pack --config CONFIG [--output PATH] [--format FORMAT]

Options

-c, --config

string

required

Path to configuration file (.json, .yaml, or .inp)

-o, --output

string

Output file path (overrides config setting)

-f, --format

string

Output format override: pdb, xyz, mol2, cif, gro, lammps, crd

Configuration Format

JSON/YAML Config

{
  "box": {
    "size": [40.0, 40.0, 40.0],
    "shape": "orthorhombic"
  },
  "seed": 0,
  "min_distance": 2.0,
  "add_box_sides": true,
  "add_box_sides_fix": 0.0,
  "relax_steps": 10,
  "relax_step": 0.5,
  "output": {
    "path": "packed.pdb",
    "format": "pdb",
    "scale": 1.0
  },
  "structures": [
    {
      "path": "water.pdb",
      "count": 200,
      "rotate": true,
      "constraints": [
        {
          "mode": "inside",
          "shape": "sphere",
          "center": [20.0, 20.0, 20.0],
          "radius": 18.0
        }
      ]
    },
    {
      "path": "ethanol.mol2",
      "count": 20,
      "filetype": "mol2",
      "changechains": true
    }
  ]
}

Packmol .inp Format

warp-pack supports native Packmol input files:

tolerance 2.0
filetype pdb
output packed.pdb
add_box_sides 1.0

structure water.pdb
  number 200
  inside sphere 20.0 20.0 20.0 18.0
end structure

structure ethanol.pdb
  number 20
  inside box 0.0 0.0 0.0 40.0 40.0 40.0
end structure

Configuration Parameters

Global Settings

box

object

required

Box configuration:

size: [x, y, z] dimensions
shape: orthorhombic (only supported shape)

min_distance

float

default:"2.0"

Minimum inter-atomic distance (Angstrom)

seed

integer

Random seed for reproducibility

add_box_sides

boolean

default:"false"

Add box dimensions to CRYST1 record

add_box_sides_fix

float

default:"0.0"

Fixed offset to add to each box side (Angstrom)

pbc

boolean

default:"false"

Enable periodic boundary conditions

pbc_min

array

Explicit PBC minimum bounds [x, y, z]

pbc_max

array

Explicit PBC maximum bounds [x, y, z]

ignore_conect

boolean

default:"false"

Skip writing CONECT records in PDB output

hexadecimal_indices

boolean

default:"false"

Use hexadecimal atom indices for large systems

Relaxation Settings

relax_steps

integer

default:"0"

Number of post-packing overlap relaxation steps

relax_step

float

default:"0.5"

Step size for relaxation (Angstrom)

Optimizer Settings (GENCAN)

gencan_maxit

integer

Maximum GENCAN iterations per call

gencan_step

float

GENCAN step size

nloop

integer

Outer GENCAN loop count (default: 200 * num_structures)

nloop0

integer

Initial GENCAN loop count (default: 20 * num_structures)

discale

float

Initial GENCAN radius scale (decays toward 1.0)

fbins

float

Spatial hashing cell size scale (cell = min_distance * fbins)

Restart Files

restart_from

string

Read initial positions from Packmol restart file

restart_to

string

Write final positions to Packmol restart file

Progress Output

writeout

float

Write periodic snapshots every N seconds

writebad

boolean

default:"false"

Write partial structure on failure

Output Settings

output

object

Output configuration:

path: Output file path
format: Output format
scale: Coordinate scale factor

write_crd

string

Optional additional .crd output path

Structure Definitions

structures

array

required

List of molecule structures to pack (see Structure Parameters below)

Structure Parameters

Each structure in the structures array:

path

string

required

Path to molecule template file

count

integer

required

Number of copies to pack

filetype

string

Override input format detection

rotate

boolean

default:"true"

Enable random rotation

changechains

boolean

default:"false"

Assign unique chain IDs to each copy

radius

float

Override per-atom radius

fscale

float

Per-atom radius scale factor

short_radius

float

Short-distance penalty radius

short_radius_scale

float

Short-distance radius scale

use_short_tol

boolean

Enable soft penalty zone between short_tol_dist and min_distance

short_tol_dist

float

Short tolerance distance threshold

nloop

integer

Per-structure GENCAN loop count override

nloop0

integer

Per-structure initial GENCAN loop override

positions

array

Fixed positions [[x,y,z], …] for each copy

fixed_eulers

array

Fixed Euler angles [[β,γ,θ], …] for each copy

rot_bounds

object

Rotation constraints:

beta: [min, max]
gamma: [min, max]
theta: [min, max]

restart_from

string

Per-structure restart file

atom_overrides

array

Per-atom parameter overrides (array of objects with index, radius, etc.)

constraints

array

Spatial constraints (see Constraint Types below)

Constraint Types

Inside Sphere

{
  "mode": "inside",
  "shape": "sphere",
  "center": [x, y, z],
  "radius": r
}

Outside Sphere

{
  "mode": "outside",
  "shape": "sphere",
  "center": [x, y, z],
  "radius": r
}

Inside Box

{
  "mode": "inside",
  "shape": "box",
  "min": [x1, y1, z1],
  "max": [x2, y2, z2]
}

Outside Box

{
  "mode": "outside",
  "shape": "box",
  "min": [x1, y1, z1],
  "max": [x2, y2, z2]
}

Inside Cylinder

{
  "mode": "inside",
  "shape": "cylinder",
  "axis": "z",
  "center": [x, y],
  "radius": r,
  "z_min": z1,
  "z_max": z2
}

Over/Below Plane

{
  "mode": "over",  // or "below"
  "shape": "plane",
  "axis": "z",
  "coordinate": z0
}

Supported Input Formats

pdb

format

Protein Data Bank format

xyz

format

XYZ coordinate format

mol2

format

Tripos MOL2 format

cif / mmcif / pdbx

format

Crystallographic Information File

gro

format

GROMACS coordinate format

lammps / lmp / lammps-data

format

LAMMPS data file

crd

format

Amber coordinate format

tinker / txyz

format

TINKER XYZ format

amber / inpcrd / rst / rst7

format

Amber restart/coordinate files (requires topology for metadata)

Supported Output Formats

pdb - Full CONECT, TER, CRYST1 support
xyz - Simple coordinate format
cif / mmcif / pdbx - Crystallographic format
gro - GROMACS format
lammps / lmp - LAMMPS data format
mol2 - Tripos format
crd - Amber coordinates

Examples

Basic Water Box

warp-pack --config water.json --output water_box.pdb

water.json:

{
  "box": {"size": [30.0, 30.0, 30.0]},
  "min_distance": 2.0,
  "add_box_sides": true,
  "output": {"path": "water.pdb", "format": "pdb"},
  "structures": [
    {"path": "tip3p.pdb", "count": 500}
  ]
}

Mixed System with Constraints

{
  "box": {"size": [50.0, 50.0, 50.0]},
  "min_distance": 2.0,
  "seed": 42,
  "relax_steps": 10,
  "output": {"path": "mixed.pdb", "format": "pdb"},
  "structures": [
    {
      "path": "protein.pdb",
      "count": 1,
      "rotate": false,
      "positions": [[25.0, 25.0, 25.0]]
    },
    {
      "path": "water.pdb",
      "count": 1000,
      "constraints": [
        {
          "mode": "outside",
          "shape": "sphere",
          "center": [25.0, 25.0, 25.0],
          "radius": 15.0
        }
      ]
    }
  ]
}

Using Packmol .inp Format

warp-pack --config packmol.inp

packmol.inp:

tolerance 2.0
filetype pdb
output system.pdb
add_box_sides 1.0
seed 123

structure protein.pdb
  number 1
  center
  fixed 25.0 25.0 25.0 0.0 0.0 0.0
end structure

structure water.pdb
  number 800
  inside box 0.0 0.0 0.0 50.0 50.0 50.0
  outside sphere 25.0 25.0 25.0 12.0
end structure

With Restart Files

{
  "box": {"size": [40.0, 40.0, 40.0]},
  "min_distance": 2.0,
  "restart_to": "system.restart",
  "writeout": 30.0,
  "writebad": true,
  "output": {"path": "system.pdb"},
  "structures": [
    {
      "path": "molecule.pdb",
      "count": 100
    }
  ]
}

Resume from restart:

{
  "box": {"size": [40.0, 40.0, 40.0]},
  "min_distance": 2.0,
  "restart_from": "system.restart",
  "output": {"path": "system.pdb"},
  "structures": [
    {
      "path": "molecule.pdb",
      "count": 100
    }
  ]
}

Using Bundled Water Models

warp-pack includes bundled single-molecule water templates:

from warp_md.pack import PackConfig, Structure, water_pdb

cfg = PackConfig(
    structures=[Structure(water_pdb("tip3p"), count=200)],
    box={"size": [30.0, 30.0, 30.0]},
    min_distance=2.0,
)

Available models: tip3p, tip4p, spce, opc, etc. List all models:

warp-md water-models --json

Exit Codes

Code	Meaning
0	Success
1	Configuration error or runtime failure

Notes

All distances are in Angstrom
Restart files use Packmol format: x y z beta gamma theta per line
When initial placement satisfies constraints, GENCAN is skipped
LAMMPS input supports full, atomic, charge, molecular atom styles
Amber topology requires prmtop with ATOM_NAME, RESIDUE_LABEL, etc.
Use hexadecimal_indices=true for systems > 99999 atoms (PDB limitation)

Packing Guide

Complete guide to molecule packing workflows

Python API

Python API for programmatic packing

Commands

warp-pack Command

warp-pack Command Reference

Synopsis

Options

Configuration Format

JSON/YAML Config

Packmol .inp Format

Configuration Parameters

Global Settings

Relaxation Settings

Optimizer Settings (GENCAN)

Restart Files

Progress Output

Output Settings

Structure Definitions

Structure Parameters

Constraint Types

Inside Sphere

Outside Sphere

Inside Box

Outside Box

Inside Cylinder

Over/Below Plane

Supported Input Formats

Supported Output Formats

Examples

Basic Water Box

Mixed System with Constraints

Using Packmol .inp Format

With Restart Files

Using Bundled Water Models

Exit Codes

Notes

Packing Guide

Python API

Build docs developers (and LLMs) love

Commands

​warp-pack Command Reference

​Synopsis

​Options

​Configuration Format

​JSON/YAML Config

​Packmol .inp Format

​Configuration Parameters

​Global Settings

​Relaxation Settings

​Optimizer Settings (GENCAN)

​Restart Files

​Progress Output

​Output Settings

​Structure Definitions

​Structure Parameters

​Constraint Types

​Inside Sphere

​Outside Sphere

​Inside Box

​Outside Box

​Inside Cylinder

​Over/Below Plane

​Supported Input Formats

​Supported Output Formats

​Examples

​Basic Water Box

​Mixed System with Constraints

​Using Packmol .inp Format

​With Restart Files

​Using Bundled Water Models

​Exit Codes

​Notes

Packing Guide

Python API

Build docs developers (and LLMs) love

warp-pack Command Reference

Synopsis

Options

Configuration Format

JSON/YAML Config

Packmol .inp Format

Configuration Parameters

Global Settings

Relaxation Settings

Optimizer Settings (GENCAN)

Restart Files

Progress Output

Output Settings

Structure Definitions

Structure Parameters

Constraint Types

Inside Sphere

Outside Sphere

Inside Box

Outside Box

Inside Cylinder

Over/Below Plane

Supported Input Formats

Supported Output Formats

Examples

Basic Water Box

Mixed System with Constraints

Using Packmol .inp Format

With Restart Files

Using Bundled Water Models

Exit Codes

Notes