# API¶

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

## Client Side API¶

 ConnectionOptions The options to use when connecting to an EvaluatorServer EvaluatorClient The object responsible for connecting to, and submitting physical property estimation requests 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 property estimator. 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 SolvationFreeEnergy A class representation of a solvation free energy 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.

## 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.

## 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 a property estimator backend. ComputeResources An object which stores how many of each type of computational resource (threads or gpu’s) is available to a calculation worker.

 BaseDaskBackend A base dask backend class, which implements functionality which is common to all other dask based backends. BaseDaskJobQueueBackend A property estimator backend which uses a dask_jobqueue.JobQueueCluster object to run calculations within an existing HPC queuing system. DaskLocalCluster A property estimator backend which uses a dask LocalCluster object to run calculations on a single machine. DaskLSFBackend A property estimator backend which uses a dask_jobqueue.LSFCluster object to run calculations within an existing LSF queue. DaskPBSBackend A property estimator backend which uses a dask_jobqueue.PBSCluster object to run calculations within an existing PBS queue. QueueWorkerResources An extended resource object with properties specific to calculations which will run on queue based resources, such as LSF, PBS or SLURM.

## Storage API¶

 StorageBackend An abstract base representation of how the property estimator 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. StoredSimulationData A representation of data which has been cached from a single previous simulation.

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. SimulationDataQuery A class used to query a StorageBackend for StoredSimulationData 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

 BaseMergeBehaviour A base class for enums which will describes how attributes should be handled when attempting to merge similar protocols. MergeBehaviour A enum which describes how attributes should be handled when attempting to merge similar protocols. InequalityMergeBehaviour 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

 AveragePropertyProtocol An abstract base class for protocols which will calculate the average of a property and its uncertainty via bootstrapping. AverageTrajectoryProperty An abstract base class for protocols which will calculate the average of a property from a simulation trajectory. ExtractAverageStatistic Extracts the average value from a statistics file which was generated during a simulation. ExtractUncorrelatedData An abstract base class for protocols which will subsample a data set, yielding only equilibrated, uncorrelated data. ExtractUncorrelatedTrajectoryData A protocol which will subsample frames from a trajectory, yielding only uncorrelated frames as determined from a provided statistical inefficiency and equilibration time. ExtractUncorrelatedStatisticsData A protocol which will subsample entries from a statistics array, 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.

 BaseGradientPotentials A base class for protocols which will evaluate the reduced potentials of a series of configurations using a set of force field parameters which have been slightly increased and slightly decreased. CentralDifferenceGradient A protocol which employs the central diference method to estimate the gradient of an observable A, such that

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.

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. OpenMMReducedPotentials Calculates the reduced potential for a given set of configurations using OpenMM. OpenMMGradientPotentials A protocol to estimates the the reduced potential of the configurations of a trajectory using reverse and forward perturbed simulation parameters for use with estimating reweighted gradients using the central difference method.

Reweighting

 ConcatenateTrajectories A protocol which concatenates multiple trajectories into a single one. ConcatenateStatistics A protocol which concatenates multiple trajectories into a single one. BaseReducedPotentials A base class for protocols which will re-evaluate the reduced potential of a series of configurations for a given set of force field parameters. BaseMBARProtocol Reweights a set of observables using MBAR to calculate the average value of the observables at a different state than they were originally measured. ReweightStatistics Reweights a set of observables from a StatisticsArray 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

 BaseYankProtocol An abstract base class for protocols which will performs a set of alchemical free energy simulations using the YANK framework. LigandReceptorYankProtocol A protocol for performing ligand-receptor alchemical free energy calculations using the YANK framework. SolvationYankProtocol A protocol for performing solvation alchemical free energy calculations using the YANK framework.

## Workflow Construction Utilities¶

 BaseReweightingProtocols BaseSimulationProtocols generate_base_reweighting_protocols Constructs a set of protocols which, when combined in a workflow schema, may be executed to reweight a set of existing data to estimate a particular property. generate_base_simulation_protocols Constructs a set of protocols which, when combined in a workflow schema, may be executed to run a single simulation to estimate a particular property. generate_gradient_protocol_group Constructs a set of protocols which, when combined in a workflow schema, may be executed to reweight a set of existing data to estimate a particular property.

## 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.

## 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.