Reference
These are the public functions of Packmol.jl. The functions of the recipes are documented on the Recipes page, and the volume estimates, guess_volume and free_volume, on the Volume estimates page.
Packing engine
Packmol.packmol — Function
packmol(input_file::String; options...)Read a Packmol input file, run the packing optimization, and write the output. Returns the built PackmolSystem (see packmol(::PackmolSystem) for details, and for the keyword arguments, which are the same).
Paths in the input file (structure files, output, restart_from) are relative to the directory of the input file.
With no input file, a file explorer is opened to choose it (see Packmol.pick_file). To disable the file explorer, set the environment variable PACKMOL_GUI="false".
packmol(; options...)Choose a Packmol input file in a file browser, and run it.
The same as packmol(input_file; options...), with the file chosen in the file browser of Packmol.pick_file (disabled by setting the environment variable PACKMOL_GUI="false", in which case the file is asked for in the terminal).
packmol(packmol_system::PackmolSystem; options...)Run the packing optimization on a PackmolSystem, mutating it in place (final molecule_positions, ...) and returning that same object — not a bare Bool — so callers can keep using it afterwards (e.g. to postprocess or re-write_output the packed coordinates, or to convert their representation, as with triclinic_to_dodecahedral).
The packing outcome is recorded in packmol_system.status: :packing_ready if it converged within nloop loops (both tolerance_precision and constraint_precision satisfied), :failed_packing if it did not, or :failed_initial_approximation if the initial approximation could not satisfy the constraints (written to the output file; the packing continues only if packmol_system.continue_failed_initial_packing is set), or :not_packed if packmol_system.check_initial_placement was set (initial approximation written, no packing attempted).
Global options. Every global keyword of the input files (see Global keywords) can be given as a keyword argument, with the name of the keyword: tolerance, output, filetype, seed, nloop, maxit, movefrac, radscale, radscale_decay_loops, writeout, tolerance_precision, constraint_precision, nthreads, avoid_overlap, screen_log, connect, add_box_sides, add_amber_ter, amber_ter_preserve, periodic_boundary_style, max_random_init, adjust_constraints_on_init, check_initial_placement, continue_failed_initial_packing, restart_from, pbc and unitcell. They are set in packmol_system, replacing the values of the input file (or of the constructor), before the packing. For example, packmol(system; tolerance = 2.5, maxit = 50, output = "out.pdb"). The values are those of the input keywords: numbers, strings or symbols for the options (periodic_boundary_style = :octahedral), true/false for the flags; pbc takes the values of the input keyword (pbc = [40, 40, 40], pbc = (:octahedral, 0, 0, 0, 80)), and unitcell the six cell parameters or a unit cell matrix. A new tolerance sets the radius of the atoms that have the default one (tolerance / 2).
The defaults: nloop 500, maxit (optimizer iterations per loop) 30, movefrac (maximum fraction of the molecules of each type moved per loop) 0.05, writeout (minimum time, in seconds, between two writes of the output during the packing: the best solution so far is written after a loop that improves it, if the end of the last write, or the start of the packing, was at least writeout seconds before; the final solution is always written) 60, nthreads (maximum number of threads used) all the threads of the Julia session, and radscale_decay_loops 20: the number of loops in which the radii of the atoms, multiplied at the start by the radscale of their structure type (see PackmolSystem; by default 5.0 for the free molecules of more than 20 atoms, 1.0 for the others), decay exponentially to their values (to within 0.1% of the initial excess).
Options of the run.
active_set (default true): after the first loop, optimize only the molecules with overlaps or constraint violations that may block the convergence, and the molecules with an atom within active_radius (default 2 * tolerance) of them, with the other molecules frozen. Used in a loop when the atoms of the active molecules are at most active_max_fraction (default 0.7) of the atoms of the free molecules; otherwise the whole system is optimized. Each loop reports the fractions of active molecules and atoms. Short loops with the active subsystem pack large systems fastest: about 2.5x faster than whole-system loops of 800 iterations for a nanoliposome of 600,000 atoms.
rotation_scaling (default true): the optimizer works on rotation variables scaled by the inertia of each molecule (a unit change moves its atoms by 1 Å RMS), instead of its Euler angles. With false, the Euler angles themselves, much slower for systems of elongated molecules (lipids, polymers); for comparisons only.
movebad_tolerance (default 0.10): after the first loop, the bad molecules are moved (see movefrac) when a loop improves the objective function by less than 100 * movebad_tolerance percent.
parallel (default true): false computes the objective function in a single thread.
packmol(
system::SolutionBoxUS;
output="system.pdb",
# box size
box_sides::AbstractVector{<:Number}, # or
margin::Number,
pbc::Symbol = :cubic, # or :orthorhombic, :dodecahedral, :octahedral
kwargs...,
)Builds and packs a Solute + Solvent system, without writing an input file.
It is equivalent to calling write_packmol_input followed by packmol on the resulting file.
output, box_sides, margin, and pbc (see Cell shapes) behave as in write_packmol_input. Any other keyword (nloop, maxit, seed, ...) is forwarded to the packing engine — see packmol(::PackmolSystem).
Returns the built PackmolSystem, with the packing outcome in its .status field — see packmol(::PackmolSystem).
packmol(
system::SolutionBoxUSC;
concentration::Number,
concentration_units::Union{Nothing,String} = nothing,
output="system.pdb",
# box size
box_sides::AbstractVector{<:Number}, # or
margin::Number,
pbc::Symbol = :cubic, # or :orthorhombic, :dodecahedral, :octahedral
kwargs...,
)Builds and packs a Solute + Solvent + Cossolvent system, without writing an input file.
It is equivalent to calling write_packmol_input followed by packmol on the resulting file.
concentration, concentration_units, output, box_sides, margin, and pbc (see Cell shapes) behave as in write_packmol_input. Any other keyword (nloop, maxit, seed, ...) is forwarded to the packing engine — see packmol(::PackmolSystem).
Returns the built PackmolSystem, with the packing outcome in its .status field — see packmol(::PackmolSystem).
packmol(
system::SolutionBoxUWI;
ionic_concentration::Number=0.15u"mol/L",
output="system.pdb",
# box size
box_sides::AbstractVector{<:Number}, # or
margin::Number,
pbc::Symbol = :cubic, # or :orthorhombic, :dodecahedral, :octahedral
kwargs...,
)Builds and packs a Solute + Water + Ions system, without writing an input file.
It is equivalent to calling write_packmol_input followed by packmol on the resulting file.
ionic_concentration, output, box_sides, margin, and pbc (see Cell shapes) behave as in write_packmol_input. Any other keyword (nloop, maxit, seed, ...) is forwarded to the packing engine — see packmol(::PackmolSystem).
Returns the built PackmolSystem, with the packing outcome in its .status field — see packmol(::PackmolSystem).
packmol(
system::Membrane;
output="membrane.pdb",
kwargs...,
)Builds and packs a lipid membrane system, without writing an input file.
It is equivalent to calling write_packmol_input followed by packmol on the resulting file.
output behaves as in write_packmol_input. Any other keyword (nloop, maxit, seed, ...) is forwarded to the packing engine — see packmol(::PackmolSystem).
Returns the built PackmolSystem, with the packing outcome in its .status field — see packmol(::PackmolSystem).
packmol(system::MembraneProtein; output = "membrane_protein.pdb", kwargs...)Builds and packs a membrane protein system, without writing an input file (as write_packmol_input followed by packmol). Any other keyword is forwarded to the packing engine; returns the PackmolSystem.
Packmol.read_packmol_input — Function
read_packmol_input(input_file::String)
read_packmol_input(io::IO)Reads a Packmol input file and returns the PackmolSystem it describes, not packed (pack it with packmol(system)). Paths in the input are relative to the directory of input_file, or to the current directory if the input is read from an IO stream (e.g. stdin).
Packmol.structure_type — Function
structure_type(filename; number, constraints=Constraint[], tolerance=2.0, radius=nothing,
fixed=nothing, center=:none, residue_numbering=-1, D=3, T=Float64)Build a StructureType for number copies of the molecule read from the PDB file filename, without going through an input file. Every constraint in constraints applies to the whole molecule.
atom_constraints gives constraints that apply only to some atoms of the molecule (as the atoms ... end atoms blocks of an input file): a vector of indices => constraints pairs, with the indices of the atoms in the structure file and one constraint or a vector of them. For example, atom_constraints = [[31, 32] => BelowPlane([0,0,1], 2.0)].
filename can also be a vector of structure files, or a file with several models, for several conformations of the molecule (they must have the same atoms, in the same order): a vector of structure types is then returned, one per conformation, among which number is divided as evenly as possible, and which PackmolSystem takes as a single structure type (e.g. PackmolSystem([lipids, water]; ...)).
radius sets a uniform atom radius; if not given, it defaults to tolerance/2 (so that two touching atoms' radii sum to tolerance, matching the input file default).
radscale sets the scale of the radii of the atoms of this type at the start of the packing (see the radscale field of PackmolSystem).
fixed, if given, is a (cm, angles) pair of 3-vectors that fixes the molecule at that position/orientation instead of packing it; center (:none, :geometric, or :mass) then controls how the molecule is centered before that transformation is applied — equivalent to the input file's fixed/center/centerofmass keywords.
Example
julia> using Packmoljulia> st = structure_type("water.pdb"; number=1000, constraints=[InsideBox([0,0,0],[40,40,40])])Packmol.PackmolSystem — Type
PackmolSystem(structure_types::Vector{<:StructureType}; output::String, kwargs...)Build a PackmolSystem directly from a vector of StructureTypes (see structure_type), without going through an input file. output sets the output file path; any other PackmolSystem field (tolerance, seed, unitcell, ...) can be given as a keyword argument.
PDBToolsBase.get_atoms — Function
get_atoms(packmol_system::PackmolSystem)Returns the atoms of the packed system, with their current coordinates.
The result is a Vector{PDBToolsBase.Atom}, generated from packmol_system.molecule_positions on each call (never cached on packmol_system itself), the same way write_output computes what it writes to file. Residue numbering follows each structure type's residue_numbering (resnumbers) setting, and chain identifiers follow chain/changechains.
When periodic boundary conditions are set (packmol_system.unitcell), each molecule's center of mass is wrapped into the unit cell as a rigid unit (a molecule straddling a periodic boundary is never torn in two across it), in the representation selected by packmol_system.periodic_boundary_style: the ordinary skewed-parallelepiped shape (:triclinic, the default), or, after triclinic_to_dodecahedral/triclinic_to_octahedral (packmol_system) has been called, the corresponding Wigner-Seitz "compact" shape (:dodecahedral/:octahedral) — see those functions and their dodecahedral_to_triclinic/octahedral_to_triclinic counterparts.
Packmol.write_output — Function
write_output(packmol_system::PackmolSystem)Write packed coordinates to the output file specified in packmol_system.output_file. Residue numbering follows each structure type's residue_numbering (resnumbers) setting, chain identifiers follow chain/changechains, and a CRYST1 record is added when add_box_sides is set or the system has periodic boundary conditions. Returns the path of the file that was written. See get_atoms for how the written coordinates are computed (including PBC wrapping and packmol_system.periodic_boundary_style).
Placement on a grid
A direct port to Julia of the placement algorithm of Bentopy: see Placement on a grid (Bentopy).
Packmol.voxel_place — Function
voxel_place(system::PackmolSystem; resolution, radius, max_tries_mult = 1000, max_tries_rot_div = 100, seed)
voxel_place(input_file::String; kwargs...)Places the free molecules of a system without overlaps, dropping those that do not fit. A direct port to Julia of the placement algorithm of Bentopy (its packing step; Westendorp et al., Protein Science 2026, doi:10.1002/pro.70480), whose algorithm this is.
The space is a grid of voxels of side resolution (default 2.5 times the largest atomic radius of the free molecules; Bentopy's models use 5 Å voxels and beads of 2 Å). The molecules are voxelized, the voxels that intersect a sphere of the radius of each atom (or of radius, Bentopy's bead radius, if given), and placed by type, the types of the largest moment first, each molecule at a random free voxel where none of its voxels is taken by the fixed molecules or those already placed, and within the compartment of its type: the voxels whose corners satisfy the constraints that apply to all its atoms. The rotation changes after each placement and after max_tries ÷ max_tries_rot_div unsuccessful tries; a type gives up after max_tries = max_tries_mult × number unsuccessful tries. Without periodic boundary conditions, each type needs a constraint that bounds its region (inside box, cube, sphere, ellipsoid or cylinder); periodic cells must be orthorhombic.
Returns (placed, dropped): placed, a new system with the molecules that fit, which starts from their positions (its restart_from is set to them, so that packmol(placed) starts from this placement), and dropped, the number of molecules of each structure type of system that did not fit.
placed, dropped = voxel_place(system)packmol(placed)Tools for building systems
Public, but not exported: call them as Packmol.cross_section, Packmol.builtin_lipid.
Packmol.cross_section — Function
Packmol.cross_section(atoms; z = (-Inf, Inf), radius = 2.0, spacing = 0.25)The area (Ų) of the projection on the xy plane of the atoms with z[1] ≤ z ≤ z[2]: the union of the discs of radius radius around them, computed on a grid of spacing spacing. atoms is a vector of Atoms (as read by PDBTools.read_pdb) or of coordinates.
It is the area that a membrane protein takes from the lipids of a leaflet: with the protein oriented along z and the middle of the bilayer at z = 0 (as the structures of the OPM database), the number of lipids of the upper leaflet of a membrane of area A is (A - cross_section(protein; z = (0, h))) / area_per_lipid, with h the half-thickness of the membrane (about 15 to 17 Å for the hydrophobic core). With radius equal to the tolerance of the packing, it is the area that the atoms of the lipids cannot occupy.
Example
using Packmol, PDBToolsprotein = read_pdb("protein.pdb") # oriented as in OPMPackmol.cross_section(protein; z = (0, 17))Packmol.builtin_lipid — Function
Packmol.builtin_lipid(name)The data of a built-in lipid of the Membrane recipe, given by its name ("POPC", "POPE", "POPS", "POPG", "DPPC", "DOPC" or "DMPC", case insensitive), as a named tuple:
file: the structure file (PDB, CHARMM36 atom names);head: the index of the atom of the polar head (the nitrogen, or the phosphorus);chain_ends: the indices of the last carbon atoms of the chains;area: the area per lipid of the actual membrane (Ų);length: the distance from the head atom to the middle of the chain ends (Å).
These are the data needed to build membranes of other shapes (vesicles, curved or asymmetric bilayers) with constraints on the heads and on the chain ends: in a flat bilayer, the Membrane recipe places the chain ends within 6 Å of the middle, and the heads beyond 6 + 0.85 * length (see Membrane system).
Example
julia> lipid = Packmol.builtin_lipid("POPC");julia> lipid.head, lipid.chain_ends, lipid.area(1, [88, 131], 64.0)Shape of molecules
Packmol.shape_descriptors — Function
shape_descriptors(atoms_or_coordinates)
shape_descriptors(filename)Descriptors of the shape of a molecule, from its gyration tensor.
They are computed from the eigenvalues λ₁ ≥ λ₂ ≥ λ₃ of the gyration tensor (the variances of the coordinates of its atoms along its principal axes, all atoms with the same weight). Returns a named tuple with:
principal_variances:(λ₁, λ₂, λ₃), in Ų;radius_of_gyration:√(λ₁ + λ₂ + λ₃), in Å;asphericity:λ₁ - (λ₂ + λ₃)/2, in Ų: how much the first principal axis dominates the others. It is zero for a spherically symmetric molecule and greatest, among conformations of a molecule, for the most elongated (rod-like) one;acylindricity:λ₂ - λ₃, in Ų: zero for a molecule with cylindrical symmetry;anisotropy: the relative shape anisotropy,(b² + 3c²/4)/R_g⁴(bthe asphericity,cthe acylindricity), from 0 (sphere-like) to 1 (atoms on a line); 1/4 for a flat disc.
The argument is a vector of atoms or of coordinates, or a structure file. For a file with several models (conformations, see structure_type), a vector with the descriptors of each is returned.
Molecules are rigid in Packmol: the shape of the conformations affects how densely they pack. Rod-like conformations (large asphericity) pack best in membranes, and sphere-like conformations (small anisotropy) in homogeneous mixtures. See select_conformations.
Example
julia> shape_descriptors("water.pdb").anisotropyPackmol.select_conformations — Function
select_conformations(input, output; n=1, shape=:rod, filetype="pdb")The most rod-like (or sphere-like) conformations of a molecule, written to a file.
Writes to output a structure file with the n (by default, one) conformations of a molecule, from those of input (a structure file with several models, or a vector of files), that are most rod-like (shape = :rod: greatest asphericity) or most sphere-like (shape = :sphere: smallest relative shape anisotropy), as models, the best first. The output file can be used in a structure block of an input file, or in structure_type, for a molecule packed in these conformations. Returns the indices of the selected conformations in input, and their shape descriptors (see shape_descriptors).
The conformations can be the frames of a simulation of a single molecule (in vacuum, at a high temperature, to sample many conformations), saved as the models of a PDB file, or the molecules of an equilibrated system.
Rod-like conformations pack best in membranes: a POPC bilayer packs at its actual area per lipid (64 Ų) from copies of the most rod-like conformation of an equilibrated membrane, but not from all its conformations. Sphere-like conformations pack best in homogeneous mixtures. A single conformation packs best: the same bilayer packs less often from the 5 most rod-like conformations, and even less from the 10 most rod-like.
Example
julia> index, descriptors = select_conformations("popc_conformations.pdb", "popc_rod.pdb")Constraints
The constraints of the input files, with their parameters in the same order (see Constraints). The surfaces given by points are documented in Surfaces given by points, and CustomConstraint in Custom constraints.
Packmol.InsideBox — Function
InsideBox(lower, upper; weight)
InsideBox(; center, sides, weight)Keeps the atoms inside an axis-aligned box. With positional arguments, the box spans from the lower to the upper corner, as the input file line inside box xmin ymin zmin xmax ymax zmax. With keyword arguments, it is given by its center and the lengths of its sides.
Example
julia> using Packmoljulia> InsideBox([0.0, 0.0, 0.0], [40.0, 40.0, 40.0]) == InsideBox(center=[20.0, 20.0, 20.0], sides=[40.0, 40.0, 40.0])truePackmol.OutsideBox — Function
OutsideBox(lower, upper; weight)
OutsideBox(; center, sides, weight)Keeps the atoms outside an axis-aligned box, given as in InsideBox.
Packmol.InsideCube — Function
InsideCube(lower_corner, side; weight)
InsideCube(; center, side, weight)Keeps the atoms inside an axis-aligned cube. With positional arguments, the cube spans from lower_corner to lower_corner .+ side, as the input file line inside cube xmin ymin zmin side. With keyword arguments, it is given by its center.
Example
julia> using Packmoljulia> InsideCube([0.0, 0.0, 0.0], 40.0) == InsideCube(center=[20.0, 20.0, 20.0], side=40.0)truePackmol.OutsideCube — Function
OutsideCube(lower_corner, side; weight)
OutsideCube(; center, side, weight)Keeps the atoms outside an axis-aligned cube, given as in InsideCube.
Packmol.InsideSphere — Function
InsideSphere(center, radius; weight)
InsideSphere(; center, radius, weight)Keeps the atoms inside a sphere, as the input file line inside sphere cx cy cz radius.
Packmol.OutsideSphere — Function
OutsideSphere(center, radius; weight)
OutsideSphere(; center, radius, weight)Keeps the atoms outside a sphere, given as in InsideSphere.
Packmol.InsideCylinder — Function
InsideCylinder(center, axis, radius, length; weight)
InsideCylinder(; center, axis, radius, length, weight)Keeps the atoms inside a capped cylinder. As the input file line inside cylinder cx cy cz vx vy vz radius length: center is the center of one end, axis the direction of the axis (normalized internally), and length the length along it from center.
Packmol.OutsideCylinder — Function
OutsideCylinder(center, axis, radius, length; weight)
OutsideCylinder(; center, axis, radius, length, weight)Keeps the atoms outside a capped cylinder, given as in InsideCylinder.
Packmol.InsideEllipsoid — Function
InsideEllipsoid(center, a, b, c, scale; weight)
InsideEllipsoid(; center, a, b, c, scale, weight)Keeps the atoms inside an axis-aligned ellipsoid, as the input file line inside ellipsoid cx cy cz a b c scale: semi-axes a, b and c, all multiplied by scale.
Packmol.OutsideEllipsoid — Function
OutsideEllipsoid(center, a, b, c, scale; weight)
OutsideEllipsoid(; center, a, b, c, scale, weight)Keeps the atoms outside an axis-aligned ellipsoid, given as in InsideEllipsoid.
Packmol.AbovePlane — Function
AbovePlane(normal, d; weight)
AbovePlane(; normal, d, weight)Keeps the atoms above a plane, normal⋅x ≥ d, as the input file line above plane a b c d.
Packmol.BelowPlane — Function
BelowPlane(normal, d; weight)
BelowPlane(; normal, d, weight)Keeps the atoms below a plane, normal⋅x ≤ d, given as in AbovePlane.
Packmol.AboveGaussian — Function
AboveGaussian(up, along, d0, amplitude, center, sigma; weight)
AboveGaussian(; up, along, d0, amplitude, center, sigma, weight)Keeps the atoms above a Gaussian ridge, up⋅x ≥ h(along⋅x), with h(s) = d0 + amplitude * exp(-(s - center)^2 / (2sigma^2)), as the input file line above gaussian. See Gaussian, wave, and exponential surfaces.
Packmol.BelowGaussian — Function
BelowGaussian(up, along, d0, amplitude, center, sigma; weight)
BelowGaussian(; up, along, d0, amplitude, center, sigma, weight)Keeps the atoms below a Gaussian ridge, given as in AboveGaussian.
Packmol.AboveSin — Function
AboveSin(up, along, d0, amplitude, wavelength, phase; weight)
AboveSin(; up, along, d0, amplitude, wavelength, phase, weight)Keeps the atoms above a sinusoidal surface, up⋅x ≥ h(along⋅x), with h(s) = d0 + amplitude * sin(2π s / wavelength + phase), as the input file line above sin (AboveCos: the same, with a cosine). See Gaussian, wave, and exponential surfaces.
Packmol.BelowSin — Function
BelowSin(up, along, d0, amplitude, wavelength, phase; weight)
BelowSin(; up, along, d0, amplitude, wavelength, phase, weight)Keeps the atoms below a sinusoidal surface, given as in AboveSin (BelowCos: the same, with a cosine).
Packmol.AboveExponential — Function
AboveExponential(up, along, d0, amplitude, center, rate; weight)
AboveExponential(; up, along, d0, amplitude, center, rate, weight)Keeps the atoms above an exponential ramp, up⋅x ≥ h(along⋅x), with h(s) = d0 + amplitude * exp(rate * (s - center)), as the input file line above exponential. See Gaussian, wave, and exponential surfaces.
Packmol.BelowExponential — Function
BelowExponential(up, along, d0, amplitude, center, rate; weight)
BelowExponential(; up, along, d0, amplitude, center, rate, weight)Keeps the atoms below an exponential ramp, given as in AboveExponential.
Packmol.AboveRadialGaussian — Function
AboveRadialGaussian(up, center, d0, amplitude, sigma; weight)
AboveRadialGaussian(; up, center, d0, amplitude, sigma, weight)Keeps the atoms above a Gaussian dome. That is, up⋅x ≥ h(r), with h(r) = d0 + amplitude * exp(-r^2 / (2sigma^2)) and r the distance to the axis along up through center, as the input file line above radial_gaussian. See Gaussian, wave, and exponential surfaces.
Packmol.BelowRadialGaussian — Function
BelowRadialGaussian(up, center, d0, amplitude, sigma; weight)
BelowRadialGaussian(; up, center, d0, amplitude, sigma, weight)Keeps the atoms below a Gaussian dome, given as in AboveRadialGaussian.
Packmol.AboveRadialSin — Function
AboveRadialSin(up, center, d0, amplitude, wavelength, phase; weight)
AboveRadialSin(; up, center, d0, amplitude, wavelength, phase, weight)Keeps the atoms above concentric ripples. That is, up⋅x ≥ h(r), with h(r) = d0 + amplitude * sin(2π r / wavelength + phase) and r the distance to the axis along up through center, as the input file line above radial_sin (AboveRadialCos: the same, with a cosine). See Gaussian, wave, and exponential surfaces.
Packmol.BelowRadialSin — Function
BelowRadialSin(up, center, d0, amplitude, wavelength, phase; weight)
BelowRadialSin(; up, center, d0, amplitude, wavelength, phase, weight)Keeps the atoms below concentric ripples, given as in AboveRadialSin (BelowRadialCos: the same, with a cosine).
Packmol.AboveRadialExponential — Function
AboveRadialExponential(up, center, d0, amplitude, rate; weight)
AboveRadialExponential(; up, center, d0, amplitude, rate, weight)Keeps the atoms above a cone-like spike. That is, up⋅x ≥ h(r), with h(r) = d0 + amplitude * exp(rate * r) and r the distance to the axis along up through center, as the input file line above radial_exponential. See Gaussian, wave, and exponential surfaces.
Packmol.BelowRadialExponential — Function
BelowRadialExponential(up, center, d0, amplitude, rate; weight)
BelowRadialExponential(; up, center, d0, amplitude, rate, weight)Keeps the atoms below a cone-like spike, given as in AboveRadialExponential.
Dodecahedral periodic box
Packmol.dodecahedral_unitcell — Function
dodecahedral_unitcell(::Type{T}, d) where {T}3x3 unit cell matrix (columns are the cell vectors) for a rhombic dodecahedron of "size" d, using the standard MD convention (matching GROMACS's editconf -bt dodecahedron -d d):
v1 = (d, 0, 0)v2 = (0, d, 0)v3 = (d/2, d/2, d/√2)equivalently a = b = c = d, α = β = 60°, γ = 90° in CRYST1 terms. d is the guaranteed minimum-image distance in every direction — the point of the shape is that, for a given cell volume, it gets a bigger minimum-image distance than a cube does, by trading away the cube's wasted corner volume relative to a sphere (about 70.7% of a cube's volume for the same d).
Use as PackmolSystem(structure_types; unitcell=dodecahedral_unitcell(Float64, d), unitcell_center=[cx,cy,cz], ...) — equivalent to the input file's pbc dodecahedral cx cy cz d.
Packmol.triclinic_to_dodecahedral — Function
triclinic_to_dodecahedral(x, unitcell, center)Remaps the position(s) x to the rhombic-dodecahedron shape of the periodic cell.
x is mapped to its periodic image closest to center: the rhombic-dodecahedron (Wigner-Seitz) fundamental domain of the cell, as opposed to the skewed-parallelepiped one of wrap_to_center. x can be a single SVector{3} or a vector of them.
See also dodecahedral_to_triclinic for the reverse mapping.
triclinic_to_dodecahedral(x, packmol_system::PackmolSystem)Remaps the position(s) x to the rhombic-dodecahedron shape of the periodic cell of packmol_system.
The same as triclinic_to_dodecahedral(x, packmol_system.unitcell, packmol_system.unitcell_center).
triclinic_to_dodecahedral(packmol_system::PackmolSystem)Selects the rhombic-dodecahedron shape for the output of packmol_system, and returns it.
It sets packmol_system.periodic_boundary_style = :dodecahedral; unlike the coordinate-remapping methods above, it touches no coordinates itself. It just selects, for subsequent calls to get_atoms/write_output, which fundamental-domain shape molecule positions get wrapped into: the rhombic-dodecahedron (Wigner-Seitz) "compact" shape instead of the default triclinic one. The actual remapping happens on demand each time get_atoms runs, not here.
Requires packmol_system.unitcell to already be set (typically to a dodecahedral cell — e.g. via dodecahedral_unitcell or the input file's pbc dodecahedral ... — though any triclinic cell works).
Packmol.dodecahedral_to_triclinic — Function
dodecahedral_to_triclinic(x, unitcell, center)Remaps the position(s) x to the parallelepiped shape of the periodic cell.
The other direction of triclinic_to_dodecahedral: x is mapped into the skewed-parallelepiped fundamental domain of the cell (the ordinary unitcell representation, as in the CRYST1 record of PDB files), with wrap_to_center. x can be a single SVector{3} or a vector of them.
dodecahedral_to_triclinic(x, packmol_system::PackmolSystem)Remaps the position(s) x to the parallelepiped shape of the periodic cell of packmol_system.
The same as dodecahedral_to_triclinic(x, packmol_system.unitcell, packmol_system.unitcell_center).
dodecahedral_to_triclinic(packmol_system::PackmolSystem)Selects the parallelepiped shape (the default) for the output of packmol_system, and returns it.
The other direction of triclinic_to_dodecahedral(packmol_system): it sets packmol_system.periodic_boundary_style = :triclinic, so get_atoms/write_output go back to wrapping molecule positions into the ordinary skewed-parallelepiped shape.
Octahedral periodic box
Packmol.octahedral_unitcell — Function
octahedral_unitcell(::Type{T}, d) where {T}3x3 unit cell matrix (columns are the cell vectors) for a truncated octahedron of "size" d, using the standard MD convention (matching GROMACS's editconf -bt octahedron -d d):
v1 = (d, 0, 0)v2 = (d/3, 2√2 d/3, 0)v3 = (-d/3, √2 d/3, √6 d/3)equivalently a = b = c = d, α = γ = acosd(1/3) ≈ 70.53°, β = acosd(-1/3) ≈ 109.47° in CRYST1 terms — the Wigner-Seitz cell of a BCC lattice, built from a Minkowski-reduced (shortest-vectors) basis for it. d is the guaranteed minimum-image distance in every direction. For a given cell volume this gets a bigger minimum-image distance than a cube does (about 77.0% of a cube's volume for the same d) — a bit more volume than the rhombic dodecahedron needs for the same d (see dodecahedral_unitcell, ≈70.7%), but its shape is still often preferred for solvating a single roughly-spherical solute.
Use as PackmolSystem(structure_types; unitcell=octahedral_unitcell(Float64, d), unitcell_center=[cx,cy,cz], ...) — equivalent to the input file's pbc octahedral cx cy cz d.
Packmol.triclinic_to_octahedral — Function
triclinic_to_octahedral(x, unitcell, center)Remaps the position(s) x to the truncated-octahedron shape of the periodic cell.
x is mapped to its periodic image closest to center: the truncated-octahedron (Wigner-Seitz) fundamental domain of the cell, as opposed to the skewed-parallelepiped one of wrap_to_center. x can be a single SVector{3} or a vector of them.
See also octahedral_to_triclinic for the reverse mapping.
triclinic_to_octahedral(x, packmol_system::PackmolSystem)Remaps the position(s) x to the truncated-octahedron shape of the periodic cell of packmol_system.
The same as triclinic_to_octahedral(x, packmol_system.unitcell, packmol_system.unitcell_center).
triclinic_to_octahedral(packmol_system::PackmolSystem)Selects the truncated-octahedron shape for the output of packmol_system, and returns it.
It sets packmol_system.periodic_boundary_style = :octahedral; unlike the coordinate-remapping methods above, it touches no coordinates itself. It just selects, for subsequent calls to get_atoms/write_output, which fundamental-domain shape molecule positions get wrapped into: the truncated-octahedron (Wigner-Seitz) "compact" shape instead of the default triclinic one. The actual remapping happens on demand each time get_atoms runs, not here.
Requires packmol_system.unitcell to already be set (typically to an octahedral cell — e.g. via octahedral_unitcell or the input file's pbc octahedral ... — though any triclinic cell works).
Packmol.octahedral_to_triclinic — Function
octahedral_to_triclinic(x, unitcell, center)Remaps the position(s) x to the parallelepiped shape of the periodic cell.
The other direction of triclinic_to_octahedral: x is mapped into the skewed-parallelepiped fundamental domain of the cell (the ordinary unitcell representation, as in the CRYST1 record of PDB files), with wrap_to_center. x can be a single SVector{3} or a vector of them.
octahedral_to_triclinic(x, packmol_system::PackmolSystem)Remaps the position(s) x to the parallelepiped shape of the periodic cell of packmol_system.
The same as octahedral_to_triclinic(x, packmol_system.unitcell, packmol_system.unitcell_center).
octahedral_to_triclinic(packmol_system::PackmolSystem)Selects the parallelepiped shape (the default) for the output of packmol_system, and returns it.
The other direction of triclinic_to_octahedral(packmol_system): it sets packmol_system.periodic_boundary_style = :triclinic, so get_atoms/write_output go back to wrapping molecule positions into the ordinary skewed-parallelepiped shape.
Legacy (Fortran) Packmol and the file browser
Packmol.run_packmol_legacy — Function
run_packmol_legacy()
run_packmol_legacy(input_file::String)Runs the packmol executable with the input file input_file. This will run the classical http://m3g.iqm.unicamp.br/packmol program, which is a pre-compiled binary. The input file is a text file with the same syntax as the packmol input files.
The binary is provided by the Packmol_jll package, which must be installed and loaded (using Packmol_jll) for run_packmol_legacy to be available.
If no input file is provided, a file explorer will be opened to choose the input file (see Packmol.pick_file).
To disable the file explorer, set the environment variable PACKMOL_GUI="false".
Packmol.pick_file — Function
pick_file()Opens a file dialog to choose the Packmol input file, and returns its path.
The dialog is provided by tools that come with the operating system — osascript on macOS, PowerShell on Windows, and zenity or kdialog on Linux — so no GUI toolkit is bundled with Packmol. If none of them is available, the path is read from the terminal instead.
To disable the file dialog, set the environment variable PACKMOL_GUI="false".