This module provides a pymatgen I/O interface to packmol.

This adopts the minimal core I/O interface (see pymatgen/io/core). In this case, only a two classes are used. PackmolSet(InputSet) is the container class that provides a run() method for running packmol locally.

PackmolBoxGen(InputGenerator) provides a recipe for packing molecules into a box, which returns a PackmolSet object.

For the run() method to work, you need to install the packmol package See or for download and setup instructions. Note that packmol versions prior to 20.3.0 do not support paths with spaces. After installation, you may need to manually add the path of the packmol executable to the PATH environment variable.

class PackmolBoxGen(tolerance: float = 2.0, seed: int = 1, control_params: dict | None = None, inputfile: str | Path = 'packmol.inp', outputfile: str | Path = '', stdoutfile: str | Path = 'packmol.stdout')[source]

Bases: InputGenerator

Generator for a Packmol InputSet that packs one or more molecules into a rectangular simulation box.

Instantiate a PackmolBoxGen class. The init method defines simulations parameters like filenames, random seed, tolerance, etc.

  • tolerance – Tolerance for packmol, in Å.

  • seed – Random seed for packmol. Use a value of 1 (default) for deterministic output, or -1 to generate a new random seed from the current time.

  • inputfile – Path to the input file. Default to ‘packmol.inp’.

  • outputfile – Path to the output file. Default to ‘’.

  • stdoutfile – Path to the file where stdout will be recorded. Default to ‘packmol.stdout’

get_input_set(molecules: list[dict], box: list[float] | None = None)[source]

Generate a Packmol InputSet for a set of molecules.

  • molecules

    A list of dict containing information about molecules to pack into the box. Each dict requires three keys:

    1. ”name” - the structure name

    2. ”number” - the number of that molecule to pack into the box

    3. ”coords” - Coordinates in the form of either a Molecule object or

      a path to a file.


    {“name”: “water”,

    ”number”: 500, “coords”: “/path/to/input/”}

  • box – A list of box dimensions xlo, ylo, zlo, xhi, yhi, zhi, in Å. If set to None (default), pymatgen will estimate the required box size based on the volumes of the provided molecules.

class PackmolSet(inputs: dict[str | Path, str | InputFile] = None, **kwargs)[source]

Bases: InputSet

InputSet for the Packmol software. This class defines several attributes related to

Instantiate an InputSet.

  • inputs – The core mapping of filename: file contents that defines the InputSet data. This should be a dict where keys are filenames and values are InputFile objects or strings representing the entire contents of the file. If a value is not an InputFile object nor a str, but has a __str__ method, this str representation of the object will be written to the corresponding file. This mapping will become the .inputs attribute of the InputSet.

  • **kwargs – Any kwargs passed will be set as class attributes e.g. InputSet(inputs={}, foo=’bar’) will make == ‘bar’.

classmethod from_directory(directory: str | Path)[source]

Construct an InputSet from a directory of one or more files.


directory – Directory to read input files from

run(path: str | Path, timeout=30)[source]

Run packmol and write out the packed structure. :param path: The path in which packmol input files are located. :param timeout: Timeout in seconds.

  • ValueError if packmol does not succeed in packing the box.

  • TimeoutExpiredError if packmold does not finish within the timeout.