| name | packmol |
| description | Use when writing, reviewing, debugging, or explaining packmol input files and packing strategies for molecular dynamics simulations. |
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
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.
