Substance

class propertyestimator.substances.Substance[source]

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

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

get_amount(component)

Returns the amount 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[source]

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

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

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

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

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

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

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

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) – 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 sufficently 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

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

Returns the amount of the component in this substance.

Parameters

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

Returns

The amount of the component in this substance.

Return type

Substance.Amount

get_molecules_per_component(maximum_molecules)[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.

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