packmol

Packmol Skill

Build initial configurations for molecular dynamics simulations using Packmol.

What is Packmol?

Packmol creates initial configurations for MD simulations by packing molecules according to spatial constraints. It places molecules in boxes, around proteins, at interfaces, or within complex geometries (spheres, cylinders, ellipsoids) while ensuring no overlaps.

Installation

Install Packmol via pip:

pip install packmol

Verify installation:

packmol -h

For more installation options, see the Packmol website.

Quick Start

Basic Box Packing

Create a simple box of water molecules:

# water_box.inp
tolerance 2.0
filetype pdb
output water_box.pdb

structure water.pdb
  number 1000
  inside box 0. 0. 0. 40. 40. 40.
end structure

Run Packmol:

packmol < water_box.inp

Solvate a Protein

Solvate a protein with water and ions:

# solvation.inp
tolerance 2.0
filetype pdb
output solvated.pdb

structure protein.pdb
  number 1
  fixed 0. 0. 0. 0. 0. 0.
  center
end structure

structure water.pdb
  number 5000
  inside box -10. -10. -10. 50. 50. 50.
end structure

structure SOD.pdb
  number 10
  inside box -10. -10. -10. 50. 50. 50.
end structure

structure CLA.pdb
  number 10
  inside box -10. -10. -10. 50. 50. 50.
end structure

Liquid-Liquid Interface

Build a water/chloroform interface:

# interface.inp
tolerance 2.0
filetype pdb
output interface.pdb
pbc -20. -20. -30. 20. 20. 30.

structure water.pdb
  number 1000
  below plane 0. 0. 1. 0.
end structure

structure chloroform.pdb
  number 200
  above plane 0. 0. 1. 0.
end structure

Core Concepts

Input File Structure

Every Packmol input file requires:

1. tolerance: Minimum distance between atoms (Å)
2. output: Output filename
3. filetype: Format (pdb, xyz, tinker)
4. structure blocks: Define molecules to place

Structure Block Syntax

structure molecule.pdb
  number <N>                          # Number of molecules
  inside|outside <constraint>         # Spatial constraint
  [optional parameters]
end structure

Common Constraint Types

• box: inside box xmin ymin zmin xmax ymax zmax
• sphere: inside sphere xcenter ycenter zcenter radius
• cylinder: inside cylinder x1 y1 z1 dx dy dz radius length
• plane: above plane a b c d or below plane a b c d
• ellipsoid: inside ellipsoid xc yc zc xa yb zc scale

See [references/constraints.md](references/constraints.md) for complete constraint documentation.

Workflows

1. Basic Molecular Packing

Build boxes with multiple molecule types.

Example: Water/ethanol mixture

tolerance 2.0
output mixture.pdb
filetype pdb

structure water.pdb
  number 800
  inside box 0. 0. 0. 40. 40. 40.
end structure

structure ethanol.pdb
  number 200
  inside box 0. 0. 0. 40. 40. 40.
end structure

2. Protein Solvation

Solvate biomolecules with water and ions for neutralization.

Key parameters:

• Use fixed with center for the protein
• Add Na+/Cl- ions for neutrality and concentration
• Calculate box size based on protein + solvent shell

Automatic solvation helper:

python scripts/solvate_helper.py protein.pdb --shell 15.0 --charge +4

3. Interface Systems

Build liquid-liquid or liquid-vapor interfaces using plane constraints.

Example: Water/hexane interface

tolerance 2.0
output interface.pdb
pbc -20. -20. -30. 20. 20. 30.

structure water.pdb
  number 1000
  below plane 0. 0. 1. 0.
end structure

structure hexane.pdb
  number 200
  above plane 0. 0. 1. 0.
end structure

4. Advanced Constraints

Use spherical, cylindrical, or ellipsoidal constraints for complex geometries.

Example: Spherical vesicle

structure lipid.pdb
  number 2000
  inside sphere 0. 0. 0. 40.
  atoms 1 2 3 4
    outside sphere 0. 0. 0. 35.
  end atoms
end structure

structure water.pdb
  number 2000
  inside sphere 0. 0. 0. 35.
end structure

structure water.pdb
  number 5000
  outside sphere 0. 0. 0. 45.
end structure

Input Parameters

Required Parameters

• tolerance <distance>: Minimum intermolecular distance (Å). Default: 2.0 for all-atom
• output <filename>: Output file name
• filetype <format>: pdb, xyz, or tinker

Optional Parameters

• pbc <dimensions>: Periodic boundary conditions (e.g., pbc 30. 30. 60.)
• seed <integer>: Random seed for reproducibility
• discale <factor>: Distance scaling for optimization (default: 1.0)
• maxit <N>: Maximum iterations (default: 20)
• precision <value>: Convergence precision (default: 0.01)

See [references/parameters.md](references/parameters.md) for complete parameter reference.

Structure Block Options

Positioning Options

• number: Molecule count
• inside/outside: Spatial constraint
• fixed: Fix position and rotation (6 parameters: x, y, z, α, β, γ)
• center: Use center of mass for positioning

Rotation Constraints

constrain_rotation x 180. 20.  # Constrain rotation around x-axis
constrain_rotation y 180. 20.  # Constrain rotation around y-axis
constrain_rotation z 180. 20.  # Constrain rotation around z-axis

Atom Selection

Apply constraints to specific atoms within molecules:

structure molecule.pdb
  number 100
  inside box 0. 0. 0. 30. 30. 30.
  atoms 1 2 3
    inside box 0. 0. 25. 30. 30. 30.
  end atoms
end structure

Running Packmol

Basic Execution

packmol < input.inp

Output Interpretation

Success message:

------------------------------
Success!
Final objective function value: .22503E-01
Maximum violation of target distance: 0.000000
Maximum violation of the constraints: .78985E-02
------------------------------

Check that both violations are < 0.01 for a valid solution.

Validation

Check Overlaps

python scripts/check_overlaps.py output.pdb --tolerance 2.0

Verify Success

python scripts/verify_success.py input.inp output.pdb

Analyze Density

python scripts/analyze_density.py output.pdb

Validate Input

python scripts/validate_input.py input.inp

Troubleshooting

Common Issues

1. "Killed" error: System too large
2. Reduce number of molecules
3. Use restart files to build incrementally
4. See [references/troubleshooting.md](references/troubleshooting.md)

1. No convergence:
2. Try discale 1.5 to scale distances
3. Reduce molecule count
4. Simplify constraints
5. Increase maxit

1. Strange geometries:
2. Add check keyword to validate constraints without packing
3. Verify constraint syntax
4. Check for conflicting constraints

1. Incorrect atom count:
2. Verify structure files are readable
3. Check for duplicate atoms in input files
4. Validate with scripts/validate_input.py

See [references/troubleshooting.md](references/troubleshooting.md) for detailed solutions.

Examples

Explore example input files in the examples/ directory:

• Basic: [examples/basic/](examples/basic/) - Simple boxes and mixtures
• Solvation: [examples/solvation/](examples/solvation/) - Proteins with water and ions
• Interface: [examples/interface/](examples/interface/) - Liquid-liquid interfaces
• Advanced: [examples/advanced/](examples/advanced/) - Vesicles, bilayers, complex geometries

Templates

Use templates in templates/ as starting points:

• [templates/basic_template.inp](templates/basic_template.inp): Minimal template for simple packing
• [templates/solvation_template.inp](templates/solvation_template.inp): Protein solvation setup
• [templates/interface_template.inp](templates/interface_template.inp): Interface systems

Helper Scripts

Use Python scripts in scripts/ for automation:

• generate_input.py: Generate inputs programmatically
• **va