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