# API

A set of API documents for this projects classes and modules.

## Client Side API

`PropertyEstimatorClient` | The PropertyEstimatorClient is the main object that users of the property estimator will interface with.
`PropertyEstimatorOptions` | Represents the options options that can be passed to the property estimation server backend.
`PropertyEstimatorSubmission` | Represents a set of properties to be estimated by the server backend, the parameters which will be used to estimate them, and options about how the properties will be estimated.
`PropertyEstimatorResult` | Represents the results of attempting to estimate a set of physical properties using the property estimator server backend.
`ConnectionOptions` | The set of options to use when connecting to a PropertyEstimatorServer

Force Field Sources

`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

`ParameterGradientKey` |
`ParameterGradient` |

## Server Side API

`PropertyEstimatorServer` | The object responsible for coordinating all properties estimations to to be ran using the property estimator, in addition to deciding at which fidelity a property will be calculated.

## Physical Property API

`PhysicalProperty` | Represents the value of any physical property and it’s uncertainty.
`PropertyPhase` | An enum describing the phase a property was collected in.
`Source` | Container class for information about how a property was measured / calculated.
`MeasurementSource` | Contains any metadata about how a physical property was measured by experiment.
`CalculationSource` | Contains any metadata about how a physical property was calculated.

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.

State Definition

`ThermodynamicState` | Data specifying a physical thermodynamic state obeying Boltzmann statistics.

Metadata

`PropertyPhase` | An enum describing the phase a property was collected in.
`Source` | Container class for information about how a property was measured / calculated.
`MeasurementSource` | Contains any metadata about how a physical property was measured by experiment.
`CalculationSource` | Contains any metadata about how a physical property was calculated.

## 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 decorator which registers information on how to parse a given ThermoML property

## Calculation Layers API

`PropertyCalculationLayer` | 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.
`register_calculation_layer` | A decorator which registers a class as being a calculation layer which may be used in property calculations.

Built-in Calculation Layers

`ReweightingLayer` | A calculation layer which aims to calculate physical properties by reweighting the results of previous calculations.
`SimulationLayer` | A calculation layer which aims to calculate physical properties directly from molecular simulation.

## Calculation Backends API

`PropertyEstimatorBackend` | 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.
`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.
`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.

## Storage Backends API

`PropertyEstimatorStorage` | 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.
`StoredSimulationData` | A representation of data which has been cached from a single previous simulation.
`StoredDataCollection` | A collection of stored StoredSimulationData objects, all generated at the same state and using the same force field parameters.

## Workflow API

`Workflow` | Encapsulates and prepares a workflow which is able to estimate a physical property.
`WorkflowGraph` | A hierarchical structure for storing and submitting the workflows which will estimate a set of physical properties..
`WorkflowOptions` | A set of convenience options used when creating estimation workflows.
`IWorkflowProperty` | Defines the interface a property must implement to be estimable by a workflow.

Schema

`WorkflowSchema` | Outlines the workflow which should be followed when calculating a certain property.
`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.
`WorkflowOutputToStore` | An object which describes which data should be cached after a workflow has finished executing, and from which completed protocols should the data be collected from.
`WorkflowSimulationDataToStore` | An object which describes which data should be cached after a workflow has finished executing, and from which completed protocols should the data be collected from.
`WorkflowDataCollectionToStore` | An object which describes which data should be cached after a workflow has finished executing, and from which completed protocols should the data be collected from.

Base Protocol API

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

Input / Output Utilities

`PlaceholderInput` | A class to act as a place holder for a protocols input value, for when the value of an input is not known a priori, and does not come from another protocol.
`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.

Decorators

`protocol_input` | A custom decorator used to mark a protocol attribute as a possible input.
`protocol_output` | A custom decorator used to mark a protocol attribute as an output of the protocol.
`BaseProtocolInputObject` | A custom decorator used to mark class attributes as either a required input, or output, of a protocol.
`MergeBehaviour` | A enum which describes how attributes should be handled when attempting to merge similar protocols.

## Built-in Workflow Protocols

Coordinate Generation

`BuildCoordinatesPackmol` | Creates a set of 3D coordinates with a specified composition.
`SolvateExistingStructure` | Creates a set of 3D coordinates with a specified composition.
`BuildDockedCoordinates` | Creates a set of coordinates for a ligand bound to some receptor.

Force Field Assignment

`BuildSmirnoffSystem` | Parametrise a set of molecules with a given smirnoff force field using the OpenFF toolkit.
`BuildTLeapSystem` | Parametrise a set of molecules with an Amber based force field.

Simulation

`RunEnergyMinimisation` | A protocol to minimise the potential energy of a system.
`RunOpenMMSimulation` | Performs a molecular dynamics simulation in a given ensemble using an OpenMM backend.
`BaseYankProtocol` | An abstract base class for protocols which will performs a set of alchemical free energy simulations using the YANK framework.
`LigandReceptorYankProtocol` | An abstract base class for protocols which will performs a set of alchemical free energy simulations using the YANK framework.

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

Reweighting

`ConcatenateTrajectories` | A protocol which concatenates multiple trajectories into a single one.
`ConcatenateStatistics` | A protocol which concatenates multiple trajectories into a single one.
`CalculateReducedPotentialOpenMM` | Calculates the reduced potential for a given set of configurations.
`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.

Gradients

`GradientReducedPotentials` | A protocol to estimates the gradient of an observable with respect to a number of specified force field parameters.
`CentralDifferenceGradient` | A protocol which employs the central diference method to estimate the gradient of an observable A, such that

Groups

`ProtocolGroup` | A collection of protocols to be executed in one batch.
`ConditionalGroup` | A collection of protocols which are to execute until a given condition is met.

Storage

`UnpackStoredDataCollection` | Loads a StoredDataCollection object from disk, and makes its inner data objects easily accessible to other protocols.
`UnpackStoredSimulationData` | Loads a StoredSimulationData object from disk, and makes its attributes easily accessible to other protocols.

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
`FilterSubstanceByRole` | A protocol which takes a substance as input, and returns a substance which only contains components whose role match a given criteria.
`BaseWeightByMoleFraction` | Multiplies a value by the mole fraction of a component in a mixture substance.
`WeightByMoleFraction` | Multiplies a value by the mole fraction of a component in a Substance.

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