# Substance

class `openff.evaluator.substances.``Substance`

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

  Examples

  A neat liquid containing only a single component:

      >>> from openff.evaluator.substances import Component, ExactAmount, MoleFraction
      >>> liquid = Substance()
      >>> liquid.add_component(Component(smiles='O'), MoleFraction(1.0))

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

      >>> binary_mixture = Substance()
      >>> binary_mixture.add_component(Component(smiles='O'), MoleFraction(0.2))
      >>> binary_mixture.add_component(Component(smiles='CO'), 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 = Component(smiles='C1=CC=CC=C1', role=Component.Role.Solute)
      >>> water = Component(smiles='O', role=Component.Role.Solvent)
      >>>
      >>> infinite_dilution = Substance()
      >>> infinite_dilution.add_component(component=benzene, amount=ExactAmount(1)) # Infinite dilution.
      >>> infinite_dilution.add_component(component=water, amount=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__`()

    Initialize self. See help(type(self)) for accurate signature.

  Methods

  `__init__` | Initialize self.
  `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.
  `from_json`(file_path) | Create this object from a JSON file.
  `get_amounts`(component) | Returns the amounts of the component in this substance.
  `get_attributes`([attribute_type]) | Returns all attributes of a specific attribute_type.
  `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`([file_path, format]) | Creates a JSON representation of this class.
  `parse_json`(string_contents[, encoding]) | Parses a typed json string into the corresponding class structure.
  `validate`([attribute_type]) | Validate the values of the attributes.

  Attributes

  `amounts` | the amounts of the component in this substance This attribute is read-only.
  `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.

  `components`

    A list of all of the components in this substance. The default value of this attribute is `()`. This attribute is read-only.

    Type

      tuple

  `amounts`

    the amounts of the component in this substance This attribute is read-only.

    Type

      dict

  property `identifier`

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

    Type

      str

  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 (Component or str) – The components to add to the substance. These may either be full 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 (Component) – The component to add to the system.

      - amount (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 Component) – The component (or it’s identifier) to retrieve the amount of.

    Returns

      The amounts of the component in this substance.

    Return type

      tuple of 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 (pint.Quantity) – The ionic string in units of molar.

    Returns

      The mole fraction of ions.

    Return type

      float

  `validate`(attribute_type=None)

    Validate the values of the attributes. If attribute_type is set, only attributes of that type will be validated.

    Parameters

      attribute_type (type of Attribute, optional) – The type of attribute to validate.

    Raises

      ValueError or AssertionError –

  classmethod `from_json`(file_path)

    Create this object from a JSON file.

    Parameters

      file_path (str) – The path to load the JSON from.

    Returns

      The parsed class.

    Return type

      cls

  classmethod `get_attributes`(attribute_type=None)

    Returns all attributes of a specific attribute_type.

    Parameters

      attribute_type (type of Attribute, optional) – The type of attribute to search for.

    Returns

      The names of the attributes of the specified type.

    Return type

      list of str

  `json`(file_path=None, format=False)

    Creates a JSON representation of this class.

    Parameters

      - file_path (str, optional) – The (optional) file path to save the JSON file to.

      - format (bool) – Whether to format the JSON or not.

    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