API

Documentation for each of the classes contained within the openff.evaluator framework.

Client Side API

EvaluatorClient

The object responsible for connecting to, and submitting physical property estimation requests to an EvaluatorServer.

BatchMode

The different modes in which a server can batch together properties to estimate.

ConnectionOptions

The options to use when connecting to an EvaluatorServer

Request

An estimation request which has been sent to a EvaluatorServer instance.

RequestOptions

The options to use when requesting a set of physical properties be estimated by the server.

RequestResult

The current results of an estimation request - these results may be partial if the server hasn't yet completed the request.

Exceptions

EvaluatorException

A serializable wrapper around an Exception.

Server Side API

EvaluatorServer

The object responsible for coordinating all properties estimations to be ran using the openff-evaluator framework.

Batch

Represents a batch of physical properties which are being estimated by the server for a given set of force field parameters.

Physical Property API

PhysicalProperty

Represents the value of any physical property and it's uncertainty if provided.

PropertyPhase

An enum describing the phase that a property was collected in.

Source

Container class for information about how a property was measured / calculated.

CalculationSource

Contains any metadata about how a physical property was calculated.

MeasurementSource

Contains any metadata about how a physical property was measured by experiment.

Built-in Properties

Density

A class representation of a density property

ExcessMolarVolume

A class representation of an excess molar volume property

DielectricConstant

A class representation of a dielectric property

EnthalpyOfMixing

A class representation of an enthalpy of mixing property

EnthalpyOfVaporization

A class representation of an enthalpy of vaporization property

HostGuestBindingAffinity

A class representation of a host-guest binding affinity property

Substance Definition

Substance

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

Component

Defines a single component in a chemical system, as well as it's role within the system (if any).

Amount

A representation of the amount of a given component in a Substance.

ExactAmount

The exact number of instances of a Component in a Substance.

MoleFraction

The mole fraction of a Component in a Substance.

State Definition

ThermodynamicState

Data specifying a physical thermodynamic state obeying Boltzmann statistics.

Data Set API

PhysicalPropertyDataSet

An object for storing and curating data sets of both physical property measurements and estimated.

NIST ThermoML Archive

ThermoMLDataSet

A dataset of physical property measurements created from a ThermoML dataset.

register_thermoml_property

A function used to map a property from the ThermoML archive to an internal PhysicalProperty object of the correct type.

thermoml_property

A decorator which wraps around the register_thermoml_property method.

Taproom

TaproomDataSet

A dataset of host-guest binding affinity measurements which sources its data from the taproom package.

TaproomSource

Contains metadata about the source of a host-guest binding affinity measurement which was pulled from the taproom package.

Data Set Curation

CurationComponent

A base component for curation components which apply a particular operation (such as filtering or data conversion) to a data set.

CurationComponentSchema

A base class for schemas which specify how particular curation components should be applied to a data set.

CurationWorkflow

A convenience class for applying a set of curation components sequentially to a data set.

CurationWorkflowSchema

A schemas which encodes how a set of curation components should be applied sequentially to a data set.

Filtering

FilterDuplicatesSchema

FilterDuplicates

A component to remove duplicate data points (within a specified precision) from a data set.

FilterByTemperatureSchema

FilterByTemperature

A component which will filter out data points which were measured outside of a specified temperature range

FilterByPressureSchema

FilterByPressure

A component which will filter out data points which were measured outside of a specified pressure range.

FilterByMoleFractionSchema

FilterByMoleFraction

A component which will filter out data points which were measured outside of a specified mole fraction range.

FilterByRacemicSchema

FilterByRacemic

A component which will filter out data points which were measured for racemic mixtures.

FilterByElementsSchema

FilterByElements

A component which will filter out data points which were measured for systems which contain specific elements.

FilterByPropertyTypesSchema

FilterByPropertyTypes

A component which will apply a filter which only retains properties of specified types.

FilterByStereochemistrySchema

FilterByStereochemistry

A component which filters out data points measured for systems whereby the stereochemistry of a number of components is undefined.

FilterByChargedSchema

FilterByCharged

A component which filters out data points measured for substances where any of the constituent components have a net non-zero charge.

FilterByIonicLiquidSchema

FilterByIonicLiquid

A component which filters out data points measured for substances which contain or are classed as an ionic liquids.

FilterBySmilesSchema

FilterBySmiles

A component which filters the data set so that it only contains either a specific set of smiles, or does not contain any of a set of specifically excluded smiles.

FilterBySmirksSchema

FilterBySmirks

A component which filters a data set so that it only contains measurements made for molecules which contain (or don't) a set of chemical environments represented by SMIRKS patterns.

FilterByNComponentsSchema

FilterByNComponents

A component which filters out data points measured for systems with specified number of components.

FilterBySubstancesSchema

FilterBySubstances

A component which filters the data set so that it only contains properties measured for particular substances.

FilterByEnvironmentsSchema

FilterByEnvironments

A component which filters a data set so that it only contains measurements made for substances which contain specific chemical environments.

FreeSolv

ThermoML

ImportThermoMLDataSchema

ImportThermoMLData

A component which will import all supported data from the NIST ThermoML archive for (optionally) specified journals.

Data Point Selection

SelectSubstancesSchema

SelectSubstances

A component for selecting a specified number data points which were measured for systems containing a specified set of chemical functionalities.

SelectDataPointsSchema

SelectDataPoints

A component for selecting a set of data points which are measured as close as possible to a particular set of states.

State

TargetState

FingerPrintType

An enumeration.

Data Conversion

ConvertExcessDensityDataSchema

ConvertExcessDensityData

A component for converting binary mass density data to excess molar volume data and vice versa where pure density data measured for the components is available.

Force Field API

ForceFieldSource

A helper object to define the source of a force field and any associated meta data, such as version, file paths, or generation options.

SmirnoffForceFieldSource

A wrapper around force fields based on the SMIRks Native Open Force Field (SMIRNOFF) specification.

TLeapForceFieldSource

A wrapper around Amber force fields which may be applied via the tleap software package.

LigParGenForceFieldSource

A wrapper and the OPLSAAM force field which can be applied via the LigParGen server.

Gradient Estimation

Calculation Layers API

CalculationLayer

An abstract representation of a calculation layer whose goal is to estimate a set of physical properties using a single approach, such as a layer which employs direct simulations to estimate properties, or one which reweights cached simulation data to the same end.

CalculationLayerResult

The result of attempting to estimate a property using a CalculationLayer.

CalculationLayerSchema

A schema which encodes the options that a CalculationLayer should use when estimating a given class of physical properties.

calculation_layer

A decorator which registers a class as being a calculation layer which may be used in property calculations.

register_calculation_layer

Registers a class as being a calculation layer which may be used in property calculations.

register_calculation_schema

Registers the default calculation schema to use when estimating a class of properties (e.g.

Built-in Calculation Layers

WorkflowCalculationLayer

An calculation layer which uses the built-in workflow framework to estimate sets of physical properties.

WorkflowCalculationSchema

A schema which encodes the options and the workflow schema that a CalculationLayer should use when estimating a given class of physical properties using the built-in workflow framework.

SimulationLayer

A calculation layer which employs molecular simulation to estimate sets of physical properties.

SimulationSchema

A schema which encodes the options and the workflow schema that the SimulationLayer should use when estimating a given class of physical properties using the built-in workflow framework.

ReweightingLayer

A CalculationLayer which attempts to 'reweight' cached simulation data to evaluate the values of properties at states which have not previously been simulated directly, but where simulations at similar states have been run previously.

ReweightingSchema

A schema which encodes the options and the workflow schema that the SimulationLayer should use when estimating a given class of physical properties using the built-in workflow framework.

default_storage_query

Return the default query to use when retrieving cached simulation

Calculation Backends API

CalculationBackend

An abstract base representation of an openff-evaluator calculation backend.

ComputeResources

An object which stores how many of each type of computational resource (threads or gpu's) is available to a calculation worker.

QueueWorkerResources

An extended resource object with properties specific to calculations which will run on queue based resources, such as LSF, PBS or SLURM.

Dask Backends

BaseDaskBackend

A base dask backend class, which implements functionality which is common to all other dask based backends.

BaseDaskJobQueueBackend

An openff-evaluator backend which uses a dask_jobqueue.JobQueueCluster object to run calculations within an existing HPC queuing system.

DaskLocalCluster

An openff-evaluator backend which uses a dask LocalCluster object to run calculations on a single machine.

DaskLSFBackend

An openff-evaluator backend which uses a dask_jobqueue.LSFCluster object to run calculations within an existing LSF queue.

DaskPBSBackend

An openff-evaluator backend which uses a dask_jobqueue.PBSCluster object to run calculations within an existing PBS queue.

Storage API

StorageBackend

An abstract base representation of how the openff-evaluator will interact with and store simulation data.

Built-in Storage Backends

LocalFileStorage

A storage backend which stores files in directories on the local disk.

Data Classes

BaseStoredData

A base representation of cached data to be stored by a storage backend.

HashableStoredData

Represents a class of data objects which can be rapidly compared / indexed by their hash values.

ForceFieldData

A data container for force field objects which will be saved to disk.

ReplaceableData

Represents a piece of stored data which can be replaced in a StorageBackend by another piece of data of the same type.

BaseSimulationData

A base class for classes which will store the outputs of a molecular simulation

StoredSimulationData

A representation of data which has been cached from a single previous simulation.

StoredFreeEnergyData

A representation of data which has been cached from an free energy calculation which computed the free energy difference between a start and end state.

Data Queries

BaseDataQuery

A base class for queries which can be made to a StorageBackend.

SubstanceQuery

A query which focuses on finding data which was collected for substances with specific traits, e.g which contains both a solute and solvent, or only a solvent etc.

ForceFieldQuery

A class used to query a StorageBackend for ForceFieldData which meet the specified criteria.

BaseSimulationDataQuery

The base class for queries which will retrieve BaseSimulationData derived data.

SimulationDataQuery

A class used to query a StorageBackend for StoredSimulationData objects which meet the specified set of criteria.

FreeEnergyDataQuery

A class used to query a StorageBackend for FreeEnergyData objects which meet the specified set of criteria.

Attributes

FilePath

Represents a string file path.

StorageAttribute

A descriptor used to mark attributes of a class as those which store information about a cached piece of data.

QueryAttribute

A descriptor used to add additional metadata to attributes of a storage query.

Workflow API

Workflow

Encapsulates and prepares a workflow which is able to estimate a physical property.

WorkflowException

An exception which was raised while executing a workflow protocol.

WorkflowGraph

A hierarchical structure for storing and submitting the workflows which will estimate a set of physical properties..

WorkflowResult

The result of executing a Workflow as part of a WorkflowGraph.

Protocol

The base class for a protocol which would form one step of a larger property calculation workflow.

ProtocolGraph

A graph of connected protocols which may be executed together.

ProtocolGroup

A group of workflow protocols to be executed in one batch.

workflow_protocol

A decorator which registers a class as being a protocol which may be included in workflows.

register_workflow_protocol

Registers a class as being a protocol which may be included in workflows.

Schemas

ProtocolSchema

A json serializable representation of a workflow protocol.

ProtocolGroupSchema

A json serializable representation of a workflow protocol group.

ProtocolReplicator

A protocol replicator contains the information necessary to replicate parts of a property estimation workflow.

WorkflowSchema

The schematic for a property estimation workflow.

Attributes

BaseMergeBehavior

A base class for enums which will describes how attributes should be handled when attempting to merge similar protocols.

MergeBehavior

A enum which describes how attributes should be handled when attempting to merge similar protocols.

InequalityMergeBehavior

A enum which describes how attributes which can be compared with inequalities should be merged.

InputAttribute

A descriptor used to mark an attribute of an object as an input to that object.

OutputAttribute

A descriptor used to mark an attribute of an as an output of that object.

Placeholder Values

ReplicatorValue

A placeholder value which will be set by a protocol replicator with the specified id.

ProtocolPath

Represents a pointer to the output of another protocol.

Built-in Workflow Protocols

Analysis

BaseAverageObservable

An abstract base class for protocols which will calculate the average value of an observable and its uncertainty via bootstrapping.

AverageObservable

Computes the average value of an observable as well as bootstrapped uncertainties for the average.

AverageDielectricConstant

Computes the average value of the dielectric constant from a set of dipole moments (M) and volumes (V) sampled over the course of a molecular simulation such that eps = 1 + (<M^2> - <M>^2) / (3.0 * eps_0 * <V> * kb * T) [1]_.

AverageFreeEnergies

A protocol which computes the Boltzmann weighted average (ΔG° = -RT × Log[ Σ_{n} exp(-βΔG°_{n}) ]) of a set of free energies which were measured at the same thermodynamic state.

ComputeDipoleMoments

A protocol which will compute the dipole moment for each configuration in a trajectory and for a given parameterized system.

BaseDecorrelateProtocol

An abstract base class for protocols which will subsample a set of data, yielding only equilibrated, uncorrelated data.

DecorrelateTrajectory

A protocol which will subsample frames from a trajectory, yielding only uncorrelated frames as determined from a provided statistical inefficiency and equilibration time.

DecorrelateObservables

A protocol which will subsample a trajectory of observables, yielding only uncorrelated entries as determined from a provided statistical inefficiency and equilibration time.

Coordinate Generation

BuildCoordinatesPackmol

Creates a set of 3D coordinates with a specified composition using the PACKMOL package.

SolvateExistingStructure

Solvates a set of 3D coordinates with a specified solvent using the PACKMOL package.

BuildDockedCoordinates

Creates a set of coordinates for a ligand bound to some receptor.

Force Field Assignment

BaseBuildSystem

The base class for any protocol whose role is to apply a set of force field parameters to a given system.

BuildSmirnoffSystem

Parametrise a set of molecules with a given smirnoff force field using the OpenFF toolkit.

BuildLigParGenSystem

Parametrise a set of molecules with the OPLS-AA/M force field.

BuildTLeapSystem

Parametrise a set of molecules with an Amber based force field.

Gradients

ZeroGradients

Zeros the gradients of an observable with respect to a specified set of force field parameters.

Groups

ConditionalGroup

A collection of protocols which are to execute until a given condition is met.

Miscellaneous

AddValues

A protocol to add together a list of values.

SubtractValues

A protocol to subtract one value from another such that:

MultiplyValue

A protocol which multiplies a value by a specified scalar

DivideValue

A protocol which divides a value by a specified scalar

WeightByMoleFraction

Multiplies a value by the mole fraction of a component in a Substance.

FilterSubstanceByRole

A protocol which takes a substance as input, and returns a substance which only contains components whose role match a given criteria.

DummyProtocol

A protocol whose only purpose is to return an input value as an output value.

OpenMM

OpenMMEnergyMinimisation

A protocol to minimise the potential energy of a system using OpenMM.

OpenMMSimulation

Performs a molecular dynamics simulation in a given ensemble using an OpenMM backend.

OpenMMEvaluateEnergies

Re-evaluates the energy of a series of configurations for a given set of force field parameters using OpenMM.

Reweighting

ConcatenateTrajectories

A protocol which concatenates multiple trajectories into a single one.

ConcatenateObservables

A protocol which concatenates multiple ObservableFrame objects into a single ObservableFrame object.

BaseEvaluateEnergies

A base class for protocols which will re-evaluate the energy of a series of configurations for a given set of force field parameters.

BaseMBARProtocol

Re-weights a set of observables using MBAR to calculate the average value of the observables at a different state than they were originally measured.

ReweightObservable

Reweight an array of observables to a new state using MBAR.

ReweightDielectricConstant

Computes the avergage value of the dielectric constant be re-weighting a set a set of dipole moments and volumes using MBAR.

Simulation

BaseEnergyMinimisation

A base class for protocols which will minimise the potential energy of a given system.

BaseSimulation

A base class for protocols which will perform a molecular simulation in a given ensemble and at a specified state.

Storage

UnpackStoredSimulationData

Loads a StoredSimulationData object from disk, and makes its attributes easily accessible to other protocols.

YANK Free Energies

Workflow Construction Utilities

SimulationProtocols

The common set of protocols which would be required to estimate an observable by running a new molecule simulation.

ReweightingProtocols

The common set of protocols which would be required to re-weight an observable from cached simulation data.

generate_base_reweighting_protocols

Constructs a set of protocols which, when combined in a workflow schema, may be executed to reweight a set of cached simulation data to estimate the average value of an observable.

generate_reweighting_protocols

generate_simulation_protocols

Constructs a set of protocols which, when combined in a workflow schema, may be executed to run a single simulation to estimate the average value of an observable.

Attribute Utilities

Attribute

A custom descriptor used to add useful metadata to class attributes.

AttributeClass

A base class for objects which require well defined attributes with additional metadata.

UNDEFINED

A custom type used to differentiate between None values, and an undeclared optional value.

PlaceholderValue

A class to act as a place holder for an attribute whose value is not known a priori, but will be set later by some specialised code.

Observable Utilities

Observable

A class which stores the mean value of an observable as well as the standard error in the mean.

ObservableArray

A class which stores the value(s) of an observable obtained via molecule simulation (or simulation data) as well as optionally the derivatives of the value with respect to certain force field parameters.

ObservableType

An enumeration of the common observables which may be extracted from molecular simulations (or simulation data) and stored in an ObservableFrame.

ObservableFrame

A data object for storing and retrieving frames of the thermodynamic observables enumerated by the ObservableType enum.

bootstrap

Bootstrapping a set of observables to compute the average value of the observables as well as the the standard error in the average.

Plug-in Utilities

Plug-ins

register_default_plugins

Registers the built-in workflow protocols, calculation layers and physical properties with the plugin system.

register_external_plugins

Registers any supported plugins found in external packages with the plugin system.