packmol

Packmol

Overview

Packmol is a tool for building initial configurations of molecular systems by packing molecules subject to geometric constraints. It is commonly used as a pre-processing step for molecular dynamics (MD) simulations.

When to Use Packmol vs. Other Tools

Scenario	Recommended Tool	Why
Solvating a solute, building bulk mixtures, or creating droplets/slabs for MD	Packmol	Purpose-built for packing with geometric constraints
Building crystalline supercells or surfaces from unit cells	ASE / pymatgen	Better support for periodic symmetry and space groups
Generating polymer chains or highly branched topologies	polymer-build / custom scripts	Packmol requires pre-built monomer structures as inputs

Key rule: Use Packmol when you need to combine pre-existing molecular structures into an initial MD configuration with control over spatial placement and density.

Requirements

Packmol must be installed and the packmol binary available in PATH. The repo includes local references for syntax, examples, and troubleshooting.

Core Capabilities

1. Draft and Validate Inputs

Use local references to write correct input files:

• references/syntax.md — Complete keyword reference, nesting rules, and unit conventions.
• references/examples.md — Copy-pasteable patterns for bulk mixtures, solvated solutes, droplets, slabs, and multi-region systems.
• references/troubleshooting.md — Common errors, convergence issues, and quick sanity-check heuristics.

2. Run Packmol

packmol < input.inp

Anti-Patterns (Do Not Do These)

• Do not set tolerance smaller than the intended van-der-Waals contact distance. Overly tight tolerances prevent convergence (default 2.0 is a safe starting point for liquids).
• Do not place inside and outside boundaries closer than tolerance. This creates contradictory constraints.
• Do not omit a seed when reproducibility matters. Packmol uses random initial placements.
• Do not use XYZ when you need residue or chain information. Prefer pdb or mol2 for systems that will be processed by MD topology builders.
• Do not pack a system into a box that is barely larger than the required volume. Leave at least 20–30% extra volume so the optimizer has room to move molecules.

Best Practices

• All distances are in angstroms (Å).
• Provide a seed for reproducibility.
• Match tolerance to the force-field vdW radii if they are known (typical range 1.5–3.0 Å).
• Include a buffer larger than tolerance between any inside and outside regions.
• For dense liquids, tolerance 2.0 is a robust default.
• Use volume heuristics from references/troubleshooting.md to sanity-check box dimensions before running.
• For questions about the latest Packmol features, newly supported keywords, or version-specific syntax changes, use WebFetch on http://m3g.iqm.unicamp.br/packmol/home.shtml before answering.

Common Errors and Fixes

Error / Symptom	Likely Cause	Fix
"Final objective function > 1e-3"	Poor convergence	Increase box size, loosen tolerance, change seed, or increase nloop / maxit
"The structure file could not be opened"	Wrong relative path or missing file	Verify paths and working directory
"Number of atoms in structure file ..."	filetype mismatches actual format	Correct filetype to match pdb, xyz, or mol2
"Inconsistent constraints"	Contradictory inside / outside directives	Ensure boundaries are separated by more than tolerance
Very slow optimization	Over-constrained or near-critical packing	Increase volume margin or slightly loosen tolerance

References

• Official Website / Manual: http://m3g.iqm.unicamp.br/packmol/home.shtml
• GitHub: https://github.com/m3g/packmol
• Local Syntax Guide: references/syntax.md
• Local Examples: references/examples.md
• Local Troubleshooting: references/troubleshooting.md

Getting Live Information

If the user asks about recently added features, new options, or version-specific syntax changes, use WebFetch on the official documentation at http://m3g.iqm.unicamp.br/packmol/home.shtml before answering.