Builder (packmol)
*****************

To build systems consisting of many different molecules, randomly put
together, the GUI includes the Builder. This is a graphical interface
to the packmol program, using only a few possibilities of it. The most
common use will be to set up a big system for  Molecular Dynamics with
Force Field, ReaxFF, ML Potential, or DFTB.

See also:

  * Tutorial on the most important Builder features

  * PLAMS Python interface to Packmol (maintained by SCM)

  * Packmol website

  * Packmol citation: L. Martínez, R. Andrade, E. G. Birgin, J. M.
    Martínez. *Packmol: A package for building initial configurations
    for molecular dynamics simulations*. Journal of Computational
    Chemistry, 30(13):2157-2164, 2009


The five starting modes of the Builder
======================================

The Builder can be started in five modes, depending on the current
system when the Builder is launched:

1. *Packing in an empty box*: The Builder is started for an **empty
   system**. The Builder will then pack the molecules **and** modify
   the lattice vectors of the system.

2. *Packing in an empty box, replacing current system*: The Builder is
   started for a **non-empty non-periodic system**. This is identical
   to the previous mode. The current molecule is discarded. To pack
   the current molecule, first export it to a .in or .xyz file, and
   import the file from the Builder.

3. *Packing inside the crystal*: The Builder is started for a **non-
   empty 3D-periodic system**. The Builder will then pack molecules
   **around** the existing system, into a space defined by the lattice
   vectors. The lattice vectors will **not** change.

4. *Packing around the slab*: The Builder is started for a **non-empty
   2D-periodic system**. This is similar to the previous mode, but you
   must specify the box bound along *z*.

5. *Packing around the chain*: The Builder is started for a **non-
   empty 1D-periodic system**. This is similar to the previous mode,
   but you must specify the box bounds along *y* and *z*.

Tip:

  Activate the engine that you want to use for your calculation
  *before* starting the Builder, for example by switching from [image:
  ADFPanel][image] → [image: ForceFieldPanel][image].Why? The Builder
  is most commonly used to build a 3D-periodic system. However, the
  ADF engine (default in AMSinput) cannot handle 3D-periodic systems.
  If the ADF engine is active when you start the builder, then the
  lattice vectors will be removed when you close the builder, since
  ADF cannot handle them.


Note on non-orthorhombic systems
--------------------------------

The Builder for periodic systems is most reliable if the lattice
vectors are oriented along *x*, *y*, and *z* with 90 degree angles.

For non-orthorhombic systems, the Builder removes molecules that fall
outside the unit cell. This usually means that you pack fewer
molecules than you specify.

For non-orthorhombic systems, always **carefully** check the resulting
structure to see if it matches your expectations.


The Builder has flexible input
==============================

The Builder has flexible input. This means that you specify only some
of the input options, and appropriate or approximate values for the
remaining input options will be automatically determined.

* **Density**: The mass density of the molecules to be packed.

* **Approximate number of atoms**: The approximate number of atoms to
  pack. Cannot be combined with *Number of molecules* (see below).

* **Box Dimensions (X, Y, Z)**: Pack the molecules into a box defined
  by these dimensions

* **Tolerance**: Approximate interatomic distance between molecules.
  To allow for more tight packing, decrease this number.

* **Use number of molecules**: Explicitly specify the number of
  molecules to pack in the *N mols* column.

* **Use mole fractions**: Specify relative mole fractions of different
  components in the *Mole fraction* column. The actual number of
  molecules to pack is determined by other input options.

You can choose how many types of molecules to pack. Click the [image:
AddButton][image] to add more molecules. For each type of molecule,
you may specify:

* **SMILES or file**: (i) SMILES code for a molecule: enter "CCO" for
  ethanol, *or* (ii) a file from the SCM library: enter "ethanol" and
  click on the match in the drop-down, *or* any file on disk: click
  the [image: DirButton][image] icon

* **N mols**: The number of molecules to pack for this type

* **Mole fraction**: Relative mole fraction for this molecule

* **Region**: Assign a region name for this molecule. By default, all
  packed molecules are placed into a region called "Builder".

Finally, there is an option to perform a *Dry run*. This will generate
a Python script that you can use a starting point for running the
Builder from Python (for example, to automate the generation of
different box sizes, mole fractions, ...).
