From 281b3298406fcd3ed883b390a97cf1be327fa6ff Mon Sep 17 00:00:00 2001 From: IAlibay Date: Mon, 29 Jan 2024 15:49:08 +0000 Subject: [PATCH] Lots of docstring --- openfe/protocols/openmm_utils/omm_settings.py | 115 ++++++++++++++++-- 1 file changed, 108 insertions(+), 7 deletions(-) diff --git a/openfe/protocols/openmm_utils/omm_settings.py b/openfe/protocols/openmm_utils/omm_settings.py index 24d686420..14c91dc5a 100644 --- a/openfe/protocols/openmm_utils/omm_settings.py +++ b/openfe/protocols/openmm_utils/omm_settings.py @@ -75,31 +75,132 @@ class Config: class OpenMMSolvationSettings(BaseSolvationSettings): """Settings for controlling how a system is solvated using OpenMM tooling. - Note - ---- - No solvation will happen if a SolventComponent is not passed. + Defining the number of waters + ----------------------------- + + The number of waters is controlled by either: + a) defining a solvent padding (``solvent_padding``) in combination + with a box shape + b) defining the number of solvent molecules + (``number_of_solvent_molecules``) + alongside the box shape (``box_shape``) + c) defining the box directly either through the box vectors + (``box_vectors``) or rectangular box lengths (``box_size``) + + When using ``solvent_padding``, ``box_vectors``, or ``box_size``, + the exact number of waters added is determined automatically by OpenMM + through :meth:`openmm.app.Modeller.addSolvent` internal heuristics. + Briefly, the necessary volume required by a single water is estimated + and then the defined target cell is packed with waters avoiding clashes + with existing solutes and box edges. + + + Defining the periodic cell size + ------------------------------- + + The periodic cell size is defined by one, and only one, of the following: + * ``solvent_padding`` in combination with ``box_shape``, + * ``box_vectors``, + * ``box_size`` + + Defining the pertiodic cell shape + --------------------------------- + + The periodic cell shape is defined by one, and only one, of the following: + * ``box_shape``, + * ``box_vectors``, + * ``box_size`` + + Default settings will create a cubic box, although more space efficient + shapes (e.g. ``dodecahedrons``) are recommended to improve simulation + performance. + + + Notes + ----- + * The number of water molecules added will be affected by the number of + ions defined in SolventComponent. For example, the value of + ``number_of_solvent_molecules`` is the sum of the number of counterions + added and the number of water molecules added. + * Solvent addition does not account for any pre-existing waters explicitly + defined in the :class:`openfe.ChemicalSystem`. Any waters will be added + in addition to those pre-existing waters. + * No solvation will happen if a SolventComponent is not passed. + + + See Also + -------- + :mod:`openmm.app.Modeller` """ solvent_model: Literal['tip3p', 'spce', 'tip4pew', 'tip5p'] = 'tip3p' """ - Force field water model to use. + Force field water model to use when solvating and defining the model + properties (e.g. adding virtual site particles). + Allowed values are; `tip3p`, `spce`, `tip4pew`, and `tip5p`. """ solvent_padding: Optional[FloatQuantity['nanometer'] = 1.2 * unit.nanometer] """ Minimum distance from any solute atoms to the edge of the solvent box. + + When used, the number of waters to add is defined by OpenMM.Modeller's + internal heuristics. These heuristics are based on a geometric estimate + of the volume required by each water molecule. + + + Note + ---- + * Cannot be defined alongside ``number_of_solvent_molecules``, + ``box_size``, or ``box_vectors``. """ box_shape: Literal['cube', 'dodecahedron', 'octahedron'] = 'cube' """ + The shape of the periodic box to create. + + Notes + ----- + * Must be one of `cube`, `dodecahedron`, or `octahedron`. + * Cannot be defined alongside ``box_vectors`` or ``box_size``. """ number_of_solvent_molecules: Optional[int] = None """ - The number of solvent molecules to add. + The number of solvent molecules (water + ions) to add. + + When defined, the size of the cell will be defined by OpenMM.Modeller's + internal heuristics, automatically selecting a padding value that + is large enough to contain the number of waters based on a geometric + estimate of the volume required by each water molecule. - If ``None``, it should be determined either by setting + + Note + ---- + * Cannot be defined alongside ``solvent_padding``, ``box_size``, + or ``box_vectors``. """ - box_vectors: Optional[FloatQuantity[...]] = None + box_vectors: Optional[ArrayQuantity['nanometer']] = None """ + `OpenMM reduced form box vectors `. + + Notes + ----- + * Cannot be defined alongside ``solvent_padding``, + ``number_of_solvent_molecules``, or ``box_size``. + + See Also + -------- + :mod:`openff.interchange.components.interchange` + :mod:`openff.interchange.components._packmol` """ + box_size: Optional[FloatQuantity['nanometer']] = None + """ + X, Y, and Z lengths of the unit cell for a rectangular box. + + Notes + ----- + * Cannot be defined alongside ``solvent_padding``, + ``number_of_solvent_molecules``, or ``box_vectors``. + """ + class AlchemicalSamplerSettings(SettingsBaseModel):