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.
Methods
__init__
()Constructs a new Substance object.
add_component
(component, amount)Add a component to the Substance.
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
A list of all of the components in this substance.
A unique str representation of this substance, which encodes all components and their amounts in the substance.
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
-
property
smiles
¶ The smiles pattern which describes this component, which may be None for complex (e.g protein) molecules.
- Type
-
property
role
¶ The role of this component in the system, such as a ligand or a receptor.
- Type
-
json
()¶ Creates a JSON representation of this class.
- Returns
The JSON representation of this class.
- Return type
-
property
-
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, 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
-
property
-
class
MoleFraction
(value=1.0)[source]¶ Represents the amount of a component in a substance as a mole fraction.
-
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, 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
-
property
-
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
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, 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
-
property
-
property
identifier
¶ A unique str representation of this substance, which encodes all components and their amounts in the substance.
- Type
-
property
components
¶ A list of all of the components in this substance.
- Type
list of Substance.Component
-
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 (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
-
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 (Substance.Component) – The component to add to the system.
amount (Substance.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 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)[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.
- 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
-
json
()¶ Creates a JSON representation of this class.
- Returns
The JSON representation of this class.
- Return type
-
class