Using your AI agent
A coding agent (Claude Code, or another assistant that can write and run code on your computer) can build a Packmol system from a description in plain language. It works best when it writes a Julia script that uses the Julia API of Packmol.jl, rather than an input file: in a single script it can download the structures of the molecules (with PDBTools.jl), select, center and orient them, compute their masses and charges, the numbers of molecules from densities or concentrations, and the size of the box, pack the system, check the result, and write it. The script is a record of how the system was built, and it can be changed and run again.
The Lipid nanoparticle tutorial shows a system designed this way, from an illustration and a few sentences, in a conversation with an agent.
This page has guidelines for the prompt, an example, and, at the end, a section written for the agent: a summary of what Packmol.jl provides and how to use it. Point your agent to that section in the prompt.
Writing the prompt
Describe the system as you would to a colleague, and say what the agent should find out by itself:
- The molecules. Give PDB IDs, file names, or names of molecules the agent can build (water, ions, common solvents); say which chains, ligands or waters of a PDB structure to keep. For lipids, name them: the Membrane recipe has conformations of POPC, POPE, POPS, POPG, DPPC, DOPC and DMPC. Provide the structures of the molecules the agent cannot get reliably (coarse-grained models, molecules of a specific force field): it can build rough models, but not ones fit for a simulation. Have it confirm with you which atoms orient each molecule (the head and the chain ends of a lipid, for example) before it builds the system.
- The amounts. Numbers of molecules, or what determines them: a density, a concentration (mol/L, molality, mole fraction), a salt concentration, the neutralization of a charged protein, an area per lipid. The agent can compute the numbers.
- The box. Its shape (cubic, orthorhombic, rhombic dodecahedron, truncated octahedron), and its size, or a margin around a solute. Periodic boundary conditions are the usual choice for a simulation.
- The regions and orientations. Where each kind of molecule goes (inside a sphere, above a plane, in a layer), and how molecules are oriented (lipid heads toward the water, molecules aligned along an axis).
- The output. The file and its format (PDB or XYZ), and what you will do with it (a molecular dynamics simulation with a given force field, for example).
- The workflow. Ask the agent to check the initial placement before packing, to verify the result (no overlaps, the molecules in their regions, the densities), and to keep the script.
If something is not clear in your request (the protonation of a protein, how much margin around it), say how you want it decided, or ask the agent to ask you before deciding.
An example prompt
Write a Julia script that uses Packmol.jl to build a system for a molecular
dynamics simulation of lysozyme (PDB 1AKI, without crystal waters) in water
with 0.15 M NaCl, neutralizing the charge of the protein, in a periodic rhombic
dodecahedron with at least 12 Å between the protein and the faces of the cell.
Use PDBTools.jl to download the structure and to compute what you need. Check
the initial placement first, then pack, and verify that the water has a
density close to 1 g/mL. Write the system to lysozyme.pdb, in the shape of the
dodecahedron. Before starting, read the section "For AI agents" of
https://m3g.github.io/Packmol.jl/stable/tutorials/ai_agent/#For-AI-agentsFor AI agents
This section is written for an AI agent that builds systems with Packmol.jl. It summarizes the package and how to use it in practice; the rest of this documentation has the details.
Approach
- Write a Julia script, and run it with
julia --project=<environment> -t auto script.jl(-tsets the number of threads; packing is multithreaded). Install withimport Pkg; Pkg.add(["Packmol", "PDBTools"]). - Build the system with the Julia API (
structure_type,PackmolSystem,packmol) or a recipe, not by writing an input file, unless an input file is asked for (thenwrite_packmol_inputwrites one from a recipe, or write the file directly; the syntax is that of Fortran Packmol, see Input files). - Use PDBTools.jl for the structures:
wget("1AKI", "protein")downloads a structure (with a selection),read_pdb/read_mmcifread files,write_pdbwrites them,massgives masses,center_of_mass,maxminthe extent of a structure,moveto!moves it, andselectselects atoms.structure_typetakes the name of a structure file, so write each molecule to a file first. - Units: Å for lengths and coordinates, g/mol for masses, g/mL for densities.
Core API
using Packmolwater = structure_type("water.pdb"; # number of molecules number = 1000, # whole molecule constraints = [InsideBox([0., 0., 0.], [40., 40., 40.])], # some atoms only atom_constraints = [[1] => AbovePlane([0., 0., 1.], 10.)], # orientation (atoms 1 to 2) constrain_rotation = Dict(:z => (0.0, 20.0, [1], [2])),)protein = structure_type("protein.pdb"; number = 1, # position and Euler angles (radians) fixed = ([0., 0., 0.], [0., 0., 0.]), # or :mass, or :none (coordinates as given) center = :geometric,)system = PackmolSystem([protein, water]; # PDB, or XYZ (by the extension, .xyz) output = "system.pdb", # minimum distance between atoms of different molecules (Å) tolerance = 2.0, # periodic cell (columns: cell vectors), centered at the origin unitcell = [50. 0. 0.; 0. 50. 0.; 0. 0. 50.], # write the initial placement only, without packing check_initial_placement = true,)# packs, writes `output`, returns `system`packmol(system)# :packing_ready, :failed_packing, :failed_initial_approximation, :not_packedsystem.status# the packed atoms (PDBTools atoms), for analysis or visualizationatoms = get_atoms(system)packmol("input.inp") packs an input file. packmol(system; nloop, maxit, nthreads) changes the number of loops, the iterations per loop and the threads.
Constraints
Of whole molecules (constraints) or of some atoms of each molecule (atom_constraints, pairs of atom indices and constraints); the input-file keywords are in parentheses:
InsideBox(lo, hi),OutsideBox(inside box xmin ymin zmin xmax ymax zmax)InsideCube(corner, side),OutsideCube(inside cube xmin ymin zmin side)InsideSphere(center, radius),OutsideSphere(inside sphere x y z r)InsideCylinder(center, axis, radius, length),OutsideCylinder:centeris the center of one cap (inside cylinder x y z ax ay az r l)InsideEllipsoid(center, a, b, c, scale),OutsideEllipsoid(inside ellipsoid x y z a b c s)AbovePlane(normal, d),BelowPlane:normal ⋅ x ≥ d(above plane nx ny nz d, alsoover)- Curved surfaces, Packmol.jl only:
AboveGaussian,AboveSin,AboveExponential, theirBelow..., and the radial ones (AboveRadialGaussian, ...) - Surfaces given by points, Packmol.jl only:
WithinSurface(surface, distance; offset),NotWithinSurface, forsurface = PointSurface(points, normals)orread_surface(file)(x y z [nx ny nz]per line, Å, or a TS2CG.datpoint file, nm):|h - offset| ≤ distance(or≥),hthe distance to the surface, signed (positive on the side of the normals) if there are normals (within surface file d [offset],not within surface file d [offset]); for closed surfaces with outward normals,InsideSurface(surface; offset)(h ≤ offset,inside surface file [offset]) andOutsideSurface(h ≥ offset,outside surface file [offset]) CustomConstraint(f; gradient), Julia only: the regionf(x) ≤ 0of any function of the position (Å); the gradient by finite differences if not given, or, for example,gradient = x -> ForwardDiff.gradient(f, x)constrain_rotation: the angle between an axis (:x,:y,:z) and a vector of the molecule withincenter ± halfwidthdegrees; the vector joins the centers of two sets of atoms,(center, halfwidth, from, to), or is the longest axis of the molecule,(center, halfwidth). This is not Fortran Packmol'sconstrain_rotation, which bounds Euler angles.
A structure file with several models (or a vector of files) is packed as several conformations of the molecule, with number divided among them.
Periodic cells
unitcell(a 3×3 matrix, columns the cell vectors, centered atunitcell_center, the origin by default); in input files,pbc xmin ymin zmin xmax ymax zmaxorpbc a b c(from the origin),unitcell a b c α β γ.- Rhombic dodecahedron and truncated octahedron:
dodecahedral_unitcell(Float64, d),octahedral_unitcell(Float64, d)(dthe distance between opposite faces; in input files,pbc dodecahedral x y z d). The output is a triclinic cell; to write it in the shape of the polyhedron, calltriclinic_to_dodecahedral(system)(ortriclinic_to_octahedral) beforepackmol, or setperiodic_boundary_style. - With periodic boundary conditions, molecules interact through the faces of the cell, and the constraints are evaluated at the periodic image of each molecule in the cell.
Recipes
Systems from densities and concentrations, built directly (packmol(recipe)) or written as input files (write_packmol_input(recipe)):
SolutionBoxUS: a solute in a solvent.SolutionBoxUSC: a solute in a mixture of two solvents, at a concentration of the cossolvent (with a table of densities).SolutionBoxUWI: a solute in water with ions, at a salt concentration, neutralizing the charge of the solute. The shape of the cell is thepbckeyword ofwrite_packmol_inputandpackmol(:cubic,:orthorhombic,:dodecahedralor:octahedral).Membrane: a lipid bilayer or monolayer, in water by default. Built-in lipids by name:Membrane(lipids = ["POPC", "POPE"], lipid_molar_ratio = [3, 1], total_lipids = 200). Other lipids from files, withlipid_head,lipid_tail(the chain ends) andarea_per_lipid.
Volumes and numbers of molecules
guess_volume(input_or_system; density), or with pairs"file.pdb" => number: the volume of the molecules at a density, and the side of a cube.free_volume(input_or_system): the volume of the region of each structure type, given its constraints and the fixed molecules, by Monte Carlo, and the density at which its molecules fill it. Use it to check the numbers of molecules: water fills its region at about 1 g/mL; much more means too many molecules.- From the command line:
packmol --guess-volume --density d input.inpandpackmol --free-volume input.inp.
Tools for building systems by hand
Public functions, not exported (call them with the Packmol. prefix):
Packmol.builtin_lipid(name): the structure file of a built-in lipid (POPC, POPE, POPS, POPG, DPPC, DOPC, DMPC), the indices of its head atom and of its chain ends, its area per lipid and its length: what the constraints of a membrane of any shape need (see the Nanoliposomes tutorial for vesicles: heads in a narrow band, chain ends within 6 Šof the middle of the bilayer).Packmol.cross_section(atoms; z = (z1, z2), radius = 2.0): the area (Ų) of the projection onxyof the atoms in a slab; the area a membrane protein (oriented as in OPM) takes from the lipids of a leaflet, to compute their number.shape_descriptorsandselect_conformations: the shape of molecules (how elongated or spherical), and the most extended conformations of a multi-model file.
Workflow and checks
- Compute the numbers of molecules from the volumes of their regions (subtracting solutes) and the densities, or use a recipe.
- Pack with
check_initial_placement = true: it takes a fraction of the time of the packing and shows whether the constraints put the molecules where intended (molecules may still overlap).:failed_initial_approximationmeans the constraints are incompatible or too tight for the molecules. - Pack.
:packing_readymeans that no atoms of different molecules are closer than the tolerance, and the constraints are satisfied.:failed_packingwrites the best solution; usually there are too many molecules, or regions too tight. - Verify: the minimum distance between molecules, the molecules in their regions (for example, with PDBTools
select), the densities, the total charge.
Practical advice
- Use a tolerance of 2.0 Å for any system, all-atom or coarse-grained, unless the user asks for another value for a specific reason.
radscale(in an input file, globally or per structure block;radscalekeyword ofstructure_type) scales the radii of the atoms at the start of the packing, decaying to their values in the first loops (radscale_decay_loops, 20). The default is 5.0 for free molecules of more than 20 atoms, which spreads lipids over their layers, and 1.0 for the others. Set 5.0 for lipids of fewer atoms (coarse-grained lipids) in layers; keep 1.0 for molecules that fill an enclosed region densely (a lipid phase between layers, for example), which may not fit in it inflated. If the first loop of a packing does not end, check theradscaleof the molecules of the crowded regions.- Rigid molecules are packed as given: prefer compact, extended conformations. Lipids pack fastest when straight, with the chains side by side, and with the head atoms constrained to a narrow band (the
Membranerecipe does this). Bilayers of extended lipids are thicker than relaxed ones; an equilibration of the simulation brings them to their thickness. - Do not constrain the same molecules with redundant regions; with periodic boundary conditions, a constraint for the whole cell is not needed.
- Large systems (millions of atoms) take minutes to hours and several GB of memory: check the initial placement first.
- The packed system has no overlaps, but it is not equilibrated: minimize its energy and equilibrate it at constant pressure (NPT; semi-isotropic for membranes) before a production simulation, with position restraints on solutes such as proteins, released gradually.
MembraneProteininserts a membrane protein, oriented as in the OPM database (normal along z, middle of the bilayer at z = 0, without itsDUMatoms), in a bilayer of a given composition, with water and ions.