htmd.builder.solvate module#

htmd.builder.solvate.solvate(mol, pad=None, minmax=None, centersel=None, boxsize=None, shape='rectangular', exclude_z=None, negx=0, posx=0, negy=0, posy=0, negz=0, posz=0, buffer=2.4, watsize=65.4195, prefix='W', rotate=False, spdb=None)#

Solvate a molecular system in a water box.

Places water molecules around the input molecule by tiling a pre-built water box and removing waters that clash with existing atoms or fall outside the specified box boundaries.

Parameters:

  • mol (Molecule) – The molecule to solvate.

  • pad (float | None) – Uniform padding in Angstroms to add around the molecule in all six directions. Overrides negx, posx, negy, posy, negz, posz.

  • minmax (list | ndarray | None) – Explicit box boundaries as a 2D array of the form [[minx, miny, minz], [maxx, maxy, maxz]]. If None, derived from the molecule’s own coordinates.

  • centersel (str | ndarray | None) – An atom selection string, a boolean mask, or an integer index array (see Molecule.atomselect) defining the center of the solvation box. The geometric center of the selected atoms is used. With shape left as "rectangular" it must be combined with boxsize; with any other shape it may be combined with pad instead, and it then only moves the cell center, because the width is still measured from that center to the furthest atom of the whole molecule, so an off-center selection enlarges the cell rather than clipping the molecule.

  • boxsize (float | list | ndarray | None) – Dimensions of the solvation box. A single float creates a cubic box; a 3-element list [sx, sy, sz] creates an axis-aligned box. Must be combined with centersel.

  • shape (str) – Unit cell shape. "rectangular" (the default) uses the per-axis region defined by pad, minmax, boxsize or the negx-posz arguments, and reproduces the historical behavior. "cube", "octahedron" (truncated octahedron) and "dodecahedron" (rhombic dodecahedron) are equilateral cells that need a single width, taken from pad or from a scalar boxsize. A non-rectangular cell reaches the same minimum image distance with less water: 77.0% of a cube’s volume for the truncated octahedron, 70.7% for the rhombic dodecahedron.

  • exclude_z (tuple | list | None) – A (zlo, zhi) pair, strictly interpreted: water whose z lies strictly between the two values is removed, and water exactly on either boundary is kept. Water is not placed between these two z values. Use it to keep water out of a membrane’s hydrophobic slab in a single solvate call: without it, a call spanning the full z range of a bilayer places water inside the tail region, where there is enough free volume for a water molecule to sit further than buffer from any lipid atom.

  • negx (float) – Padding in Angstroms in the -x direction.

  • posx (float) – Padding in Angstroms in the +x direction.

  • negy (float) – Padding in Angstroms in the -y direction.

  • posy (float) – Padding in Angstroms in the +y direction.

  • negz (float) – Padding in Angstroms in the -z direction.

  • posz (float) – Padding in Angstroms in the +z direction.

  • buffer (float) – Minimum distance in Angstroms between water molecules and other atoms.

  • watsize (float) – Edge length in Angstroms of the pre-built water box tile.

  • prefix (str) – Prefix string used for water segment names.

  • rotate (bool) – If True, rotate the molecule to minimize box volume (not yet implemented).

  • spdb (str | None) – Path to a custom solvent box file, in any format Molecule can read. If None, uses the built-in water box. Bonds are read from the file if present and guessed from the coordinates otherwise.

Returns:

mol – A copy of the input molecule with water molecules added.

Return type:

Molecule

Raises:

ValueError – If shape is not a known shape name; if a non-rectangular shape is combined with minmax, a 3-element boxsize, or any of the per-axis padding arguments; if a non-rectangular shape is given neither pad nor boxsize; if the resulting cell width is not positive; if centersel matches no atoms; or if exclude_z is not an increasing (zlo, zhi) pair of finite numbers.

Examples

>>> smol = solvate(mol, pad=10)
>>> smol = solvate(mol, minmax=[[-20, -20, -20],[20, 20, 20]])
>>> smol = solvate(mol, centersel="protein", boxsize=100)
>>> smol = solvate(mol, centersel="protein", boxsize=[80, 80, 120])
>>> smol = solvate(mol, pad=12, shape="octahedron")