Packmol interface¶
Packmol (Packmol website) is a program for creating liquid or gas mixtures. The PLAMS interface only supports
uniform mixtures
solid/liquid interfaces
packing inside voids in a crystal
microsolvation
The following functions eixst:
packmol
(for fluids with 1 or more components)packmol_on_slab
(for solid/liquid or solid/gas interfaces with 1 or more components in the fluid)packmol_in_void
(for packing molecules inside crystal voids)packmol_microsolvation
(for microsolvation of a solute with a solvent)
See the Packmol example for all the ways these functions can be used.
The above functions accept an executable
argument, which should
contain the path to the packmol program. If it is not specified, the path to
the packmol program included with the Amsterdam Modeling Suite will be used.
-
packmol
(molecules, mole_fractions=None, density=None, n_atoms=None, box_bounds=None, n_molecules=None, sphere=False, fix_first=False, keep_bonds=True, keep_atom_properties=True, region_names=None, return_details=False, tolerance=2.0, executable=None)[source]¶ Create a fluid of the given
molecules
. The function will use the given input parameters and try to obtain good values for the others. You must specifydensity
and/orbox_bounds
.- molecules
Molecule
or list of Molecule The molecules to pack
- mole_fractionslist of float
The mole fractions (in the same order as
molecules
). Cannot be combined withn_molecules
. If not given, an equal (molar) mixture of all components will be created.- density: float
The total density (in g/cm^3) of the fluid
- n_atoms: int
The (approximate) number of atoms in the final mixture
- box_bounds: list of float (length 6)
The box in which to pack the molecules. The box is orthorhombic and should be specified as [xmin, ymin, zmin, xmax, ymax, zmax]. The minimum values should all be set to 0, i.e. set box_bounds=[0., 0., 0., xmax, ymax, zmax]. If not specified, a cubic box of appropriate dimensions will be used.
- n_moleculesint or list of int
The (exact) number of molecules for each component (in the same order as
molecules
). Cannot be combined withmole_fractions
.- sphere: bool
Whether the molecules should be packed in a sphere. The radius is determined by getting the volume from the box bounds!
- fix_first: bool
Whether to keep the first molecule fixed. This can only be used with
n_molecules=[1, ..., ...]
. Defaults to False.- keep_bondsbool
If True, the bonds from the constituent molecules will be kept in the returned Molecule
- keep_atom_propertiesbool
If True, the atom.properties (e.g. force-field atom types) of the constituent molecules will be kept in the returned Molecule
- region_namesstr or list of str
Populate the region information for each atom. Should have the same length and order as
molecules
. By default the regions are namedmol0
,mol1
, etc.- tolerance: float
The packmol tolerance (approximately the minimum intermolecular distance). When packing a periodic box, half the tolerance will be excluded from each face of the box.
- return_detailsbool
Return a 2-tuple (Molecule, dict) where the dict has keys like ‘n_molecules’, ‘mole_fractions’, ‘density’, etc. They contain the actual details of the returned molecule, which may differ slightly from the requested quantities.
Returned keys:
‘n_molecules’: list of integer with actually added number of molecules
‘mole_fractions’: list of float with actually added mole fractions
‘density’: float, gives the density in g/cm^3
‘n_atoms’: int, the number of atoms in the returned molecule
‘molecule_type_indices’: list of int of length n_atoms. For each atom, give an integer index for which TYPE of molecule it belongs to.
‘molecule_indices’: list of int of length n_atoms. For each atom, give an integer index for which molecule it belongs to
‘atom_indices_in_molecule’: list of int of length n_atoms. For each atom, give an integer index for which position in the molecule it is.
‘volume’: float. The volume of the bounding box / packed sphere in ang^3.
- executablestr
The path to the packmol executable. If not specified,
$AMSBIN/packmol.exe
will be used (which is the correct path for the Amsterdam Modeling Suite).
Useful combinations:
mole_fractions
,density
,n_atoms
: Create a mixture with a given density and approximate number of atoms (a cubic box will be created)mole_fractions
,density
,box_bounds
: Create a mixture with a given density inside a given box (the number of molecules will approximately match the density and mole fractions)n_molecules
,density
: Create a mixture with the given number of molecules and density (a cubic box will be created)n_molecules
,box_bounds
: Create a mixture with the given number of molecules inside the given box
Example:
packmol(molecules=[from_smiles('O'), from_smiles('C')], mole_fractions=[0.8, 0.2], density=0.8, n_atoms=100)
- Returns: a
Molecule
or tuple (Molecule, dict) If return_details=False, return a Molecule. If return_details=True, return a tuple.
- molecules
-
packmol_on_slab
(slab, molecules, mole_fractions=None, density=1.0, keep_bonds=True, keep_atom_properties=True, region_names=None, executable=None)[source]¶ Creates a solid/liquid interface with an approximately correct density. The density is calculated for the volume not occupied by the slab (+ 1.5 angstrom buffer at each side of the slab).
Returns: a
Molecule
- slab
Molecule
The system must have a 3D lattice (including a vacuum gap along z) and be orthorhombic. The vacuum gap will be filled with the liquid.
For the other arguments, see
packmol
.Example:
packmol_on_slab(slab=slab_3d_with_vacuum_gap, molecules=[from_smiles('O'), from_smiles('C')], mole_fractions=[0.8, 0.2], density=0.8)
- slab
-
packmol_in_void
(host, molecules, n_molecules, keep_bonds=True, keep_atom_properties=True, region_names=None, tolerance=2.0, return_details=False, executable=None)[source]¶ Pack molecules inside voids in a crystal.
- host: Molecule
The host molecule. Must be 3D-periodic and the cell must be orthorhombic (all angles 90 degrees) with the lattice vectors parallel to the cartesian axes (all off-diagonal components must be 0).
For the other arguments, see the
packmol
function.Note:
region_names
needs to have one more element than the list ofmolecules
. For exampleregion_names=['host', 'guest1', 'guest2']
.
-
packmol_microsolvation
(solute, solvent, density=1.0, threshold=3.0, keep_bonds=True, keep_atom_properties=True, region_names=['solute', 'solvent'], executable=None)[source]¶ Microsolvation of a
solute
with asolvent
with an approximatedensity
.- solute:
Molecule
The solute to be surrounded by solvent molecules
- solvent:
Molecule
The solvent molecule
- density: float
Approximate density in g/cm^3
- threshold: float
Distance in angstrom. Any solvent molecule for which at least 1 atom is within this threshold to the solute molecule will be kept
For the other arguments, see
packmol
.- solute: