Substance

class openff.evaluator.substances.Substance[source]

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__()

Methods

__init__()

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)

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)[source]

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)[source]

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)[source]

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, count_exact_amount=True, truncate_n_molecules=True)[source]

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.

  • count_exact_amount (bool) –

    Whether components present in an exact amount (i.e. defined with an ExactAmount) should be considered when apply the maximum number

    of molecules constraint. This may be set false, for example, when building a separate solvated protein (n = 1) and solvated protein + ligand complex (n = 2) system but wish for both systems to have the same number of solvent molecules.

  • truncate_n_molecules (bool) –

    Whether or not to attempt to truncate the number of molecules in the substance if the total number is over the specified maximum. If False, an exception will be raised in this case.

    The truncation works by iteratively removing one molecule of the predominant component up to a limit of removing a total number of molecules equal to the number of components in the substance (e.g. for a binary substance a maximum of two molecules can be removed). An exception is raised if the number of molecules cannot be sensibly truncated.

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)[source]
Determines what mole fraction of ions is needed to yield

an aqueous system of a given ionic strength.

Parameters

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

Returns

The mole fraction of ions.

Return type

float

validate(attribute_type=None)[source]

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)

Parses a typed json string into the corresponding class structure.

Parameters

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

Returns

The parsed class.

Return type

Any