# Substance

class `propertyestimator.substances.``Substance`

  Defines the components, their amounts, and their roles in a system.

  Examples

  A neat liquid containing only a single component:

      >>> liquid = Substance()
      >>> liquid.add_component(Substance.Component(smiles='O'), Substance.MoleFraction(1.0))

  A binary mixture containing two components, where the mole fractions are explicitly stated:

      >>> binary_mixture = Substance()
      >>> binary_mixture.add_component(Substance.Component(smiles='O'), Substance.MoleFraction(0.2))
      >>> binary_mixture.add_component(Substance.Component(smiles='CO'), Substance.MoleFraction(0.8))

  The infinite dilution of one molecule within a bulk solvent or mixture may also be specified by defining the exact number of copies of that molecule, rather than a mole fraction:

      >>> benzene = Substance.Component(smiles='C1=CC=CC=C1', role=Substance.ComponentRole.Solute)
      >>> water = Substance.Component(smiles='O', role=Substance.ComponentRole.Solvent)
      >>>
      >>> infinite_dilution = Substance()
      >>> infinite_dilution.add_component(component=benzene, amount=Substance.ExactAmount(1)) # Infinite dilution.
      >>> infinite_dilution.add_component(component=water, amount=Substance.MoleFraction(1.0))

  In this example we explicitly flag benzene as being the solute and the water component the solvent. This enables workflow’s to easily identify key molecules of interest, such as the molecule which should be ‘grown’ into solution during solvation free energy calculations.

  `__init__`()

    Constructs a new Substance object.

  Methods

  `__init__`() | Constructs a new Substance object.
  `add_component`(component, amount) | Add a component to the Substance.
  `calculate_aqueous_ionic_mole_fraction`(…) | Determines what mole fraction of ions is needed to yield
  `from_components`(*components) | Creates a new Substance object from a list of components.
  `get_amounts`(component) | Returns the amounts of the component in this substance.
  `get_molecules_per_component`(maximum_molecules) | Returns the number of molecules for each component in this substance, given a maximum total number of molecules.
  `json`() | Creates a JSON representation of this class.
  `parse_json`(string_contents[, encoding]) | Parses a typed json string into the corresponding class structure.

  Attributes

  `components` | A list of all of the components in this substance.
  `identifier` | A unique str representation of this substance, which encodes all components and their amounts in the substance.
  `number_of_components` | The number of different components in this substance.

  class `ComponentRole`

    An enum which describes the role of a component in the system, such as whether the component is a solvent, a solute, a receptor etc.

    These roles are mainly only used by specific protocols to identify the correct species in a system, such as when doing docking or performing solvation free energy calculations.

  class `Component`(smiles=None, label=None, role=None)

    Defines a single component in a system, as well as properties such as it’s relative proportion in the system.

    property `identifier`

      A unique identifier for this component, which is either a smiles descriptor or the supplied label.

      Type

        str

    property `label`

      A string label which describes this compound, for example, CB8.

      Type

        str

    property `smiles`

      The smiles pattern which describes this component, which may be None for complex (e.g protein) molecules.

      Type

        str

    property `role`

      The role of this component in the system, such as a ligand or a receptor.

      Type

        ComponentRole

    `json`()

      Creates a JSON representation of this class.

      Returns

        The JSON representation of this class.

      Return type

        str

    classmethod `parse_json`(string_contents, encoding='utf8')

      Parses a typed json string into the corresponding class structure.

      Parameters

        - string_contents (str or bytes) – The typed json string.

        - encoding (str) – The encoding of the string_contents.

      Returns

        The parsed class.

      Return type

        Any

  class `Amount`(value=None)

    An abstract representation of the amount of a given component in a substance.

    property `value`

      The value of this amount.

    property `identifier`

      A string identifier for this amount.

    abstract `to_number_of_molecules`(total_substance_molecules, tolerance=None)

      Converts this amount to an exact number of molecules

      Parameters

        - total_substance_molecules (int) – The total number of molecules in the whole substance. This amount will contribute to a portion of this total number.

        - tolerance (float , optional) – The tolerance with which this amount should be in. As an example, when converting a mole fraction into a number of molecules, the total number of molecules may not be sufficiently large enough to reproduce this amount.

      Returns

        The number of molecules which this amount represents, given the total_substance_molecules.

      Return type

        int

  class `MoleFraction`(value=1.0)

    Represents the amount of a component in a substance as a mole fraction.

    property `value`

      The value of this amount.

      Type

        float

    property `identifier`

      A string identifier for this amount.

    `to_number_of_molecules`(total_substance_molecules, tolerance=None)

      Converts this amount to an exact number of molecules

      Parameters

        - total_substance_molecules (int) – The total number of molecules in the whole substance. This amount will contribute to a portion of this total number.

        - tolerance (float , optional) – The tolerance with which this amount should be in. As an example, when converting a mole fraction into a number of molecules, the total number of molecules may not be sufficiently large enough to reproduce this amount.

      Returns

        The number of molecules which this amount represents, given the total_substance_molecules.

      Return type

        int

  class `ExactAmount`(value=1)

    Represents the amount of a component in a substance as an exact number of molecules.

    The expectation is that this amount should be used for components which are infinitely dilute (such as ligands in binding calculations), and hence do not contribute to the total mole fraction of a substance

    property `value`

      The value of this amount.

      Type

        int

    property `identifier`

      A string identifier for this amount.

    `to_number_of_molecules`(total_substance_molecules, tolerance=None)

      Converts this amount to an exact number of molecules

      Parameters

        - total_substance_molecules (int) – The total number of molecules in the whole substance. This amount will contribute to a portion of this total number.

        - tolerance (float , optional) – The tolerance with which this amount should be in. As an example, when converting a mole fraction into a number of molecules, the total number of molecules may not be sufficiently large enough to reproduce this amount.

      Returns

        The number of molecules which this amount represents, given the total_substance_molecules.

      Return type

        int

  property `identifier`

    A unique str representation of this substance, which encodes all components and their amounts in the substance.

    Type

      str

  property `components`

    A list of all of the components in this substance.

    Type

      list of Substance.Component

  property `number_of_components`

    The number of different components in this substance.

    Type

      int

  classmethod `from_components`(*components)

    Creates a new Substance object from a list of components. This method assumes that all components should be present with equal mole fractions.

    Parameters

      components (Substance.Component or str) – The components to add to the substance. These may either be full Substance.Component objects or just the smiles representation of the component.

    Returns

      The substance containing the requested components in equal amounts.

    Return type

      Substance

  `add_component`(component, amount)

    Add a component to the Substance. If the component is already present in the substance, then the mole fraction will be added to the current mole fraction of that component.

    Parameters

      - component (Substance.Component) – The component to add to the system.

      - amount (Substance.Amount) – The amount of this component in the substance.

  `get_amounts`(component)

    Returns the amounts of the component in this substance.

    Parameters

      component (str or Substance.Component) – The component (or it’s identifier) to retrieve the amount of.

    Returns

      The amounts of the component in this substance.

    Return type

      list of Substance.Amount

  `get_molecules_per_component`(maximum_molecules, tolerance=None)

    Returns the number of molecules for each component in this substance, given a maximum total number of molecules.

    Parameters

      - maximum_molecules (int) – The maximum number of molecules.

      - tolerance (float , optional) – The tolerance within which this amount should be represented. As an example, when converting a mole fraction into a number of molecules, the total number of molecules may not be sufficiently large enough to reproduce this amount.

    Returns

      A dictionary of molecule counts per component, where each key is a component identifier.

    Return type

      dict of str and int

  static `calculate_aqueous_ionic_mole_fraction`(ionic_strength)
    Determines what mole fraction of ions is needed to yield

      an aqueous system of a given ionic strength.

    Parameters

      ionic_strength (unit.Quantity) – The ionic string in units of molar.

    Returns

      The mole fraction of ions.

    Return type

      float

  `json`()

    Creates a JSON representation of this class.

    Returns

      The JSON representation of this class.

    Return type

      str

  classmethod `parse_json`(string_contents, encoding='utf8')

    Parses a typed json string into the corresponding class structure.

    Parameters

      - string_contents (str or bytes) – The typed json string.

      - encoding (str) – The encoding of the string_contents.

    Returns

      The parsed class.

    Return type

      Any