EvaluatorClient

class openff.evaluator.client.EvaluatorClient(connection_options=None)[source]

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

Examples

These examples assume that an EvaluatorServer has been set up and is running (either synchronously or asynchronously). This server can be connect to be creating an EvaluatorClient:

>>> from openff.evaluator.client import EvaluatorClient
>>> property_estimator = EvaluatorClient()

If the EvaluatorServer is not running on the local machine, you will need to specify its address and the port that it is listening on:

>>> from openff.evaluator.client import ConnectionOptions
>>>
>>> connection_options = ConnectionOptions(server_address='server_address',
>>>                                        server_port=8000)
>>> property_estimator = EvaluatorClient(connection_options)

To asynchronously submit a request to the running server using the default estimation options:

>>> # Load in the data set of properties which will be used for comparisons
>>> from openff.evaluator.datasets.thermoml import ThermoMLDataSet
>>> data_set = ThermoMLDataSet.from_doi('10.1016/j.jct.2016.10.001')
>>>
>>> # Filter the dataset to only include densities measured between 130-260 K
>>> from openff.evaluator import unit
>>> from openff.evaluator.properties import Density
>>>
>>> data_set.filter_by_property_types(Density)
>>> data_set.filter_by_temperature(
>>>     min_temperature=130*unit.kelvin,
>>>     max_temperature=260*unit.kelvin
>>> )
>>>
>>> # Load in the force field parameters
>>> from openff.evaluator.forcefield import SmirnoffForceFieldSource
>>> force_field_source = SmirnoffForceFieldSource.from_path('smirnoff99Frosst-1.1.0.offxml')
>>>
>>> # Submit the estimation request to a running server.
>>> request = property_estimator.request_estimate(data_set, force_field_source)

The status of the request can be asynchronously queried by calling

>>> results = request.results()

or the main thread can be blocked until the results are available by calling

>>> results = request.results(synchronous=True)

How the property set will be estimated can easily be controlled by passing a RequestOptions object to the estimate commands.

The calculations layers which will be used to estimate the properties can be controlled for example like so:

>>> from openff.evaluator.layers.reweighting import ReweightingLayer
>>> from openff.evaluator.layers.simulation import SimulationLayer
>>>
>>> options = RequestOptions(calculation_layers=[
>>>     "ReweightingLayer",
>>>     "SimulationLayer"
>>> ])
>>>
>>> request = property_estimator.request_estimate(data_set, force_field_source, options)

Options for how properties should be estimated can be set on a per property, and per layer basis by providing a calculation schema to the options object.

>>> from openff.evaluator.properties import DielectricConstant
>>>
>>> # Generate a schema to use when estimating densities directly
>>> # from simulations.
>>> density_simulation_schema = Density.default_simulation_schema()
>>> # Generate a schema to use when estimating dielectric constants
>>> # from cached simulation data.
>>> dielectric_reweighting_schema = DielectricConstant.default_reweighting_schema()
>>>
>>> options.workflow_options = {
>>>     'Density': {'SimulationLayer': density_simulation_schema},
>>>     'Dielectric': {'SimulationLayer': dielectric_reweighting_schema}
>>> }
>>>
>>> property_estimator.request_estimate(
>>>     data_set,
>>>     force_field_source,
>>>     options,
>>> )

The gradients of the observables of interest with respect to a number of chosen parameters can be requested by passing a parameter_gradient_keys parameter. In the below example, gradients will be calculated with respect to both the bond length parameter for the [#6:1]-[#8:2] chemical environment, and the bond angle parameter for the [:1]-[#8:2]-[:3] chemical environment:

>>> from openff.evaluator.forcefield import ParameterGradientKey
>>>
>>> parameter_gradient_keys = [
>>>     ParameterGradientKey('Bonds', '[#6:1]-[#8:2]', 'length')
>>>     ParameterGradientKey('Angles', '[*:1]-[#8:2]-[*:3]', 'angle')
>>> ]
>>>
>>> property_estimator.request_estimate(
>>>     data_set,
>>>     force_field_source,
>>>     options,
>>>     parameter_gradient_keys
>>> )
__init__(connection_options=None)[source]
Parameters

connection_options (ConnectionOptions, optional) – The options used when connecting to the calculation server. If None, default options are used.

Methods

__init__([connection_options])

param connection_options

The options used when connecting to the calculation

default_request_options(data_set, …)

Returns the default RequestOptions options used to estimate a set of properties if None are provided.

request_estimate(property_set, …[, …])

Submits a request for the EvaluatorServer to attempt to estimate the data set of physical properties using the specified force field parameters according to the provided options.

retrieve_results(request_id[, synchronous, …])

Retrieves the current results of a request from the server.

Attributes

server_address

The address of the server that this client is connected to.

server_port

The port of the server that this client is connected to.
property server_address

The address of the server that this client is connected to.

Type

str

property server_port

The port of the server that this client is connected to.

Type

int

static default_request_options(data_set, force_field_source)[source]

Returns the default RequestOptions options used to estimate a set of properties if None are provided.

Parameters
Returns

The default options.

Return type

RequestOptions

request_estimate(property_set, force_field_source, options=None, parameter_gradient_keys=None)[source]

Submits a request for the EvaluatorServer to attempt to estimate the data set of physical properties using the specified force field parameters according to the provided options.

Parameters

  • property_set (PhysicalPropertyDataSet) – The set of properties to estimate.

  • force_field_source (ForceFieldSource or openforcefield.typing.engines.smirnoff.ForceField) – The force field parameters to estimate the properties using.

  • options (RequestOptions, optional) – A set of estimator options. If None default options will be used (see default_request_options).

  • parameter_gradient_keys (list of ParameterGradientKey, optional) – A list of the parameters that the physical properties should be differentiated with respect to.

Returns

  • Request – An object which will provide access to the results of this request.

  • EvaluatorException, optional – Any exceptions raised while attempting the submit the request.

retrieve_results(request_id, synchronous=False, polling_interval=5)[source]

Retrieves the current results of a request from the server.

Parameters

  • request_id (str) – The server assigned id of the request.

  • synchronous (bool) – If true, this method will block the main thread until the server either returns a result or an error.

  • polling_interval (float) – If running synchronously, this is the time interval (seconds) between checking if the request has completed.

Returns

  • RequestResult, optional – Returns the current results of the request. This may be None if any unexpected exceptions occurred while retrieving the estimate.

  • EvaluatorException, optional – The exception raised will trying to retrieve the result, if any.