def default_simulation_schema(absolute_tolerance=UNDEFINED,
relative_tolerance=UNDEFINED,
n_molecules=1000) -> SimulationSchema:
"""Returns the default calculation schema to use when estimating
this class of property from direct simulations.
Parameters
----------
absolute_tolerance: openff.evaluator.unit.Quantity, optional
The absolute tolerance to estimate the property to within.
relative_tolerance: float
The tolerance (as a fraction of the properties reported
uncertainty) to estimate the property to within.
n_molecules: int
The number of molecules to use in the simulation.
Returns
-------
SimulationSchema
The schema to follow when estimating this property.
"""
assert absolute_tolerance == UNDEFINED or relative_tolerance == UNDEFINED
calculation_schema = SimulationSchema()
calculation_schema.absolute_tolerance = absolute_tolerance
calculation_schema.relative_tolerance = relative_tolerance
use_target_uncertainty = (absolute_tolerance != UNDEFINED
or relative_tolerance != UNDEFINED)
# Define the protocols which will run the simulation itself.
protocols, value_source, output_to_store = generate_simulation_protocols(
analysis.AverageObservable("average_density"),
use_target_uncertainty,
n_molecules=n_molecules,
)
# Specify that the average density should be estimated.
protocols.analysis_protocol.observable = ProtocolPath(
f"observables[{ObservableType.Density.value}]",
protocols.production_simulation.id,
)
# Build the workflow schema.
schema = WorkflowSchema()
schema.protocol_schemas = [
protocols.build_coordinates.schema,
protocols.assign_parameters.schema,
protocols.energy_minimisation.schema,
protocols.equilibration_simulation.schema,
protocols.converge_uncertainty.schema,
protocols.decorrelate_trajectory.schema,
protocols.decorrelate_observables.schema,
]
schema.outputs_to_store = {"full_system": output_to_store}
schema.final_value_source = value_source
calculation_schema.workflow_schema = schema
return calculation_schema
def _get_schema(self):
"""Returns the schema that describes this workflow.
Returns
-------
WorkflowSchema
The schema that describes this workflow.
"""
schema = WorkflowSchema()
schema.id = self.uuid
schema.protocol_schemas = [
copy.deepcopy(x.schema) for x in self._protocols
]
if self._final_value_source != UNDEFINED:
schema.final_value_source = self._final_value_source.copy()
schema.outputs_to_store = copy.deepcopy(self._outputs_to_store)
return schema
def default_simulation_schema(
cls,
absolute_tolerance=UNDEFINED,
relative_tolerance=UNDEFINED,
n_molecules=1000,
) -> SimulationSchema:
"""Returns the default calculation schema to use when estimating
this class of property from direct simulations.
Parameters
----------
absolute_tolerance: openff.evaluator.unit.Quantity, optional
The absolute tolerance to estimate the property to within.
relative_tolerance: float
The tolerance (as a fraction of the properties reported
uncertainty) to estimate the property to within.
n_molecules: int
The number of molecules to use in the simulation.
Returns
-------
SimulationSchema
The schema to follow when estimating this property.
"""
assert absolute_tolerance == UNDEFINED or relative_tolerance == UNDEFINED
calculation_schema = SimulationSchema()
calculation_schema.absolute_tolerance = absolute_tolerance
calculation_schema.relative_tolerance = relative_tolerance
use_target_uncertainty = (absolute_tolerance != UNDEFINED
or relative_tolerance != UNDEFINED)
# Define the protocols to use for the fully mixed system.
(
mixture_protocols,
mixture_value,
mixture_stored_data,
) = generate_simulation_protocols(
analysis.AverageObservable("extract_observable_mixture"),
use_target_uncertainty,
id_suffix="_mixture",
n_molecules=n_molecules,
)
# Specify the average observable which should be estimated.
mixture_protocols.analysis_protocol.observable = ProtocolPath(
f"observables[{cls._observable_type().value}]",
mixture_protocols.production_simulation.id,
)
(
mixture_protocols.analysis_protocol.divisor,
mixture_n_molar_molecules,
) = cls._n_molecules_divisor(
ProtocolPath("output_number_of_molecules",
mixture_protocols.build_coordinates.id),
"_mixture",
)
# Define the protocols to use for each component, creating a replicator that
# will copy these for each component in the mixture substance.
component_replicator = ProtocolReplicator("component_replicator")
component_replicator.template_values = ProtocolPath(
"components", "global")
component_substance = ReplicatorValue(component_replicator.id)
component_protocols, _, component_stored_data = generate_simulation_protocols(
analysis.AverageObservable(
f"extract_observable_component_{component_replicator.placeholder_id}"
),
use_target_uncertainty,
id_suffix=f"_component_{component_replicator.placeholder_id}",
n_molecules=n_molecules,
)
# Make sure the protocols point to the correct substance.
component_protocols.build_coordinates.substance = component_substance
# Specify the average observable which should be estimated.
component_protocols.analysis_protocol.observable = ProtocolPath(
f"observables[{cls._observable_type().value}]",
component_protocols.production_simulation.id,
)
(
component_protocols.analysis_protocol.divisor,
component_n_molar_molecules,
) = cls._n_molecules_divisor(
ProtocolPath("output_number_of_molecules",
component_protocols.build_coordinates.id),
f"_component_{component_replicator.placeholder_id}",
)
# Weight the component value by the mole fraction.
weight_by_mole_fraction = miscellaneous.WeightByMoleFraction(
f"weight_by_mole_fraction_{component_replicator.placeholder_id}")
weight_by_mole_fraction.value = ProtocolPath(
"value", component_protocols.analysis_protocol.id)
weight_by_mole_fraction.full_substance = ProtocolPath(
"substance", "global")
weight_by_mole_fraction.component = component_substance
component_protocols.converge_uncertainty.add_protocols(
weight_by_mole_fraction)
# Make sure the convergence criteria is set to use the per component
# uncertainty target.
if use_target_uncertainty:
component_protocols.converge_uncertainty.conditions[
0].right_hand_value = ProtocolPath("per_component_uncertainty",
"global")
# Finally, set up the protocols which will be responsible for adding together
# the component observables, and subtracting these from the mixture system value.
add_component_observables = miscellaneous.AddValues(
"add_component_observables")
add_component_observables.values = ProtocolPath(
"weighted_value",
component_protocols.converge_uncertainty.id,
weight_by_mole_fraction.id,
)
calculate_excess_observable = miscellaneous.SubtractValues(
"calculate_excess_observable")
calculate_excess_observable.value_b = mixture_value
calculate_excess_observable.value_a = ProtocolPath(
"result", add_component_observables.id)
# Build the final workflow schema
schema = WorkflowSchema()
schema.protocol_schemas = [
component_protocols.build_coordinates.schema,
component_protocols.assign_parameters.schema,
component_protocols.energy_minimisation.schema,
component_protocols.equilibration_simulation.schema,
component_protocols.converge_uncertainty.schema,
component_protocols.decorrelate_trajectory.schema,
component_protocols.decorrelate_observables.schema,
mixture_protocols.build_coordinates.schema,
mixture_protocols.assign_parameters.schema,
mixture_protocols.energy_minimisation.schema,
mixture_protocols.equilibration_simulation.schema,
mixture_protocols.converge_uncertainty.schema,
mixture_protocols.decorrelate_trajectory.schema,
mixture_protocols.decorrelate_observables.schema,
add_component_observables.schema,
calculate_excess_observable.schema,
]
if component_n_molar_molecules is not None:
schema.protocol_schemas.append(component_n_molar_molecules.schema)
if mixture_n_molar_molecules is not None:
schema.protocol_schemas.append(mixture_n_molar_molecules.schema)
schema.protocol_replicators = [component_replicator]
schema.final_value_source = ProtocolPath(
"result", calculate_excess_observable.id)
schema.outputs_to_store = {
"full_system":
mixture_stored_data,
f"component_{component_replicator.placeholder_id}":
component_stored_data,
}
calculation_schema.workflow_schema = schema
return calculation_schema
def default_simulation_schema(
absolute_tolerance=UNDEFINED, relative_tolerance=UNDEFINED, n_molecules=1000
):
"""Returns the default calculation schema to use when estimating
this class of property from direct simulations.
Parameters
----------
absolute_tolerance: openff.evaluator.unit.Quantity, optional
The absolute tolerance to estimate the property to within.
relative_tolerance: float
The tolerance (as a fraction of the properties reported
uncertainty) to estimate the property to within.
n_molecules: int
The number of molecules to use in the simulation.
Returns
-------
SimulationSchema
The schema to follow when estimating this property.
"""
assert absolute_tolerance == UNDEFINED or relative_tolerance == UNDEFINED
calculation_schema = SimulationSchema()
calculation_schema.absolute_tolerance = absolute_tolerance
calculation_schema.relative_tolerance = relative_tolerance
use_target_uncertainty = (
absolute_tolerance != UNDEFINED or relative_tolerance != UNDEFINED
)
# Define a custom conditional group which will ensure both the liquid and
# gas enthalpies are estimated to within the specified uncertainty tolerance.
converge_uncertainty = groups.ConditionalGroup("conditional_group")
converge_uncertainty.max_iterations = 100
# Define the protocols to perform the simulation in the liquid phase.
average_liquid_energy = analysis.AverageObservable("average_liquid_potential")
average_liquid_energy.divisor = n_molecules
(
liquid_protocols,
liquid_value_source,
liquid_output_to_store,
) = generate_simulation_protocols(
average_liquid_energy,
use_target_uncertainty,
"_liquid",
converge_uncertainty,
n_molecules=n_molecules,
)
liquid_output_to_store.property_phase = PropertyPhase.Liquid
liquid_protocols.analysis_protocol.observable = ProtocolPath(
f"observables[{ObservableType.PotentialEnergy.value}]",
liquid_protocols.production_simulation.id,
)
# Define the protocols to perform the simulation in the gas phase.
average_gas_energy = analysis.AverageObservable("average_gas_potential")
(
gas_protocols,
gas_value_source,
gas_output_to_store,
) = generate_simulation_protocols(
average_gas_energy,
use_target_uncertainty,
"_gas",
converge_uncertainty,
n_molecules=1,
)
gas_output_to_store.property_phase = PropertyPhase.Gas
gas_protocols.analysis_protocol.observable = ProtocolPath(
f"observables[{ObservableType.PotentialEnergy.value}]",
gas_protocols.production_simulation.id,
)
# Specify that for the gas phase only a single molecule in vacuum should be
# created.
gas_protocols.build_coordinates.max_molecules = 1
gas_protocols.build_coordinates.mass_density = (
0.01 * unit.gram / unit.milliliter
)
# Run the gas phase simulations in the NVT ensemble without PBC
gas_protocols.energy_minimisation.enable_pbc = False
gas_protocols.equilibration_simulation.ensemble = Ensemble.NVT
gas_protocols.equilibration_simulation.enable_pbc = False
gas_protocols.production_simulation.ensemble = Ensemble.NVT
gas_protocols.production_simulation.enable_pbc = False
gas_protocols.production_simulation.steps_per_iteration = 15000000
gas_protocols.production_simulation.output_frequency = 5000
gas_protocols.production_simulation.checkpoint_frequency = 100
# Due to a bizarre issue where the OMM Reference platform is
# the fastest at computing properties of a single molecule
# in vacuum, we enforce those inputs which will force the
# gas calculations to run on the Reference platform.
gas_protocols.equilibration_simulation.high_precision = True
gas_protocols.equilibration_simulation.allow_gpu_platforms = False
gas_protocols.production_simulation.high_precision = True
gas_protocols.production_simulation.allow_gpu_platforms = False
# Combine the values to estimate the final energy of vaporization
energy_of_vaporization = miscellaneous.SubtractValues("energy_of_vaporization")
energy_of_vaporization.value_b = ProtocolPath("value", average_gas_energy.id)
energy_of_vaporization.value_a = ProtocolPath("value", average_liquid_energy.id)
ideal_volume = miscellaneous.MultiplyValue("ideal_volume")
ideal_volume.value = 1.0 * unit.molar_gas_constant
ideal_volume.multiplier = ProtocolPath(
"thermodynamic_state.temperature", "global"
)
enthalpy_of_vaporization = miscellaneous.AddValues("enthalpy_of_vaporization")
enthalpy_of_vaporization.values = [
ProtocolPath("result", energy_of_vaporization.id),
ProtocolPath("result", ideal_volume.id),
]
# Add the extra protocols and conditions to the custom conditional group.
converge_uncertainty.add_protocols(
energy_of_vaporization, ideal_volume, enthalpy_of_vaporization
)
if use_target_uncertainty:
condition = groups.ConditionalGroup.Condition()
condition.type = groups.ConditionalGroup.Condition.Type.LessThan
condition.left_hand_value = ProtocolPath(
"result.error",
converge_uncertainty.id,
enthalpy_of_vaporization.id,
)
condition.right_hand_value = ProtocolPath("target_uncertainty", "global")
gas_protocols.production_simulation.total_number_of_iterations = (
ProtocolPath("current_iteration", converge_uncertainty.id)
)
liquid_protocols.production_simulation.total_number_of_iterations = (
ProtocolPath("current_iteration", converge_uncertainty.id)
)
converge_uncertainty.add_condition(condition)
# Build the workflow schema.
schema = WorkflowSchema()
schema.protocol_schemas = [
liquid_protocols.build_coordinates.schema,
liquid_protocols.assign_parameters.schema,
liquid_protocols.energy_minimisation.schema,
liquid_protocols.equilibration_simulation.schema,
liquid_protocols.decorrelate_trajectory.schema,
liquid_protocols.decorrelate_observables.schema,
gas_protocols.build_coordinates.schema,
gas_protocols.assign_parameters.schema,
gas_protocols.energy_minimisation.schema,
gas_protocols.equilibration_simulation.schema,
gas_protocols.decorrelate_trajectory.schema,
gas_protocols.decorrelate_observables.schema,
converge_uncertainty.schema,
]
schema.outputs_to_store = {
"liquid_data": liquid_output_to_store,
"gas_data": gas_output_to_store,
}
schema.final_value_source = ProtocolPath(
"result", converge_uncertainty.id, enthalpy_of_vaporization.id
)
calculation_schema.workflow_schema = schema
return calculation_schema
def default_simulation_schema(
absolute_tolerance=UNDEFINED, relative_tolerance=UNDEFINED, n_molecules=1000
):
"""Returns the default calculation schema to use when estimating
this class of property from direct simulations.
Parameters
----------
absolute_tolerance: pint.Quantity, optional
The absolute tolerance to estimate the property to within.
relative_tolerance: float
The tolerance (as a fraction of the properties reported
uncertainty) to estimate the property to within.
n_molecules: int
The number of molecules to use in the simulation.
Returns
-------
SimulationSchema
The schema to follow when estimating this property.
"""
assert absolute_tolerance == UNDEFINED or relative_tolerance == UNDEFINED
calculation_schema = SimulationSchema()
calculation_schema.absolute_tolerance = absolute_tolerance
calculation_schema.relative_tolerance = relative_tolerance
use_target_uncertainty = (
absolute_tolerance != UNDEFINED or relative_tolerance != UNDEFINED
)
# Define the id of the replicator which will clone the gradient protocols
# for each gradient key to be estimated.
gradient_replicator_id = "gradient_replicator"
# Set up a workflow to calculate the molar volume of the full, mixed system.
(
full_system_protocols,
full_system_molar_molecules,
full_system_volume,
full_output,
full_system_gradient_group,
full_system_gradient_replicator,
full_system_gradient,
) = ExcessMolarVolume._get_simulation_protocols(
"_full",
gradient_replicator_id,
use_target_uncertainty=use_target_uncertainty,
n_molecules=n_molecules,
)
# Set up a general workflow for calculating the molar volume of one of the system components.
component_replicator_id = "component_replicator"
component_substance = ReplicatorValue(component_replicator_id)
# Make sure to weight by the mole fractions of the actual full system as these may be slightly
# different to the mole fractions of the measure property due to rounding.
full_substance = ProtocolPath(
"output_substance", full_system_protocols.build_coordinates.id
)
(
component_protocols,
component_molar_molecules,
component_volumes,
component_output,
component_gradient_group,
component_gradient_replicator,
component_gradient,
) = ExcessMolarVolume._get_simulation_protocols(
"_component",
gradient_replicator_id,
replicator_id=component_replicator_id,
weight_by_mole_fraction=True,
component_substance_reference=component_substance,
full_substance_reference=full_substance,
use_target_uncertainty=use_target_uncertainty,
n_molecules=n_molecules,
)
# Finally, set up the protocols which will be responsible for adding together
# the component molar volumes, and subtracting these from the mixed system molar volume.
add_component_molar_volumes = miscellaneous.AddValues(
"add_component_molar_volumes"
)
add_component_molar_volumes.values = component_volumes
calculate_excess_volume = miscellaneous.SubtractValues(
"calculate_excess_volume"
)
calculate_excess_volume.value_b = full_system_volume
calculate_excess_volume.value_a = ProtocolPath(
"result", add_component_molar_volumes.id
)
# Create the replicator object which defines how the pure component
# molar volume estimation protocols will be replicated for each component.
component_replicator = ProtocolReplicator(replicator_id=component_replicator_id)
component_replicator.template_values = ProtocolPath("components", "global")
# Combine the gradients.
add_component_gradients = miscellaneous.AddValues(
f"add_component_gradients" f"_$({gradient_replicator_id})"
)
add_component_gradients.values = component_gradient
combine_gradients = miscellaneous.SubtractValues(
f"combine_gradients_$({gradient_replicator_id})"
)
combine_gradients.value_b = full_system_gradient
combine_gradients.value_a = ProtocolPath("result", add_component_gradients.id)
# Combine the gradient replicators.
gradient_replicator = ProtocolReplicator(replicator_id=gradient_replicator_id)
gradient_replicator.template_values = ProtocolPath(
"parameter_gradient_keys", "global"
)
# Build the final workflow schema
schema = WorkflowSchema()
schema.protocol_schemas = [
component_protocols.build_coordinates.schema,
component_protocols.assign_parameters.schema,
component_protocols.energy_minimisation.schema,
component_protocols.equilibration_simulation.schema,
component_protocols.converge_uncertainty.schema,
component_molar_molecules.schema,
full_system_protocols.build_coordinates.schema,
full_system_protocols.assign_parameters.schema,
full_system_protocols.energy_minimisation.schema,
full_system_protocols.equilibration_simulation.schema,
full_system_protocols.converge_uncertainty.schema,
full_system_molar_molecules.schema,
component_protocols.extract_uncorrelated_trajectory.schema,
component_protocols.extract_uncorrelated_statistics.schema,
full_system_protocols.extract_uncorrelated_trajectory.schema,
full_system_protocols.extract_uncorrelated_statistics.schema,
add_component_molar_volumes.schema,
calculate_excess_volume.schema,
component_gradient_group.schema,
full_system_gradient_group.schema,
add_component_gradients.schema,
combine_gradients.schema,
]
schema.protocol_replicators = [gradient_replicator, component_replicator]
# Finally, tell the schemas where to look for its final values.
schema.gradients_sources = [ProtocolPath("result", combine_gradients.id)]
schema.final_value_source = ProtocolPath("result", calculate_excess_volume.id)
schema.outputs_to_store = {
"full_system": full_output,
f"component_$({component_replicator_id})": component_output,
}
calculation_schema.workflow_schema = schema
return calculation_schema
def default_simulation_schema(
absolute_tolerance=UNDEFINED, relative_tolerance=UNDEFINED, n_molecules=1000
):
"""Returns the default calculation schema to use when estimating
this class of property from direct simulations.
Parameters
----------
absolute_tolerance: pint.Quantity, optional
The absolute tolerance to estimate the property to within.
relative_tolerance: float
The tolerance (as a fraction of the properties reported
uncertainty) to estimate the property to within.
n_molecules: int
The number of molecules to use in the simulation.
Returns
-------
SimulationSchema
The schema to follow when estimating this property.
"""
assert absolute_tolerance == UNDEFINED or relative_tolerance == UNDEFINED
calculation_schema = SimulationSchema()
calculation_schema.absolute_tolerance = absolute_tolerance
calculation_schema.relative_tolerance = relative_tolerance
use_target_uncertainty = (
absolute_tolerance != UNDEFINED or relative_tolerance != UNDEFINED
)
# Define the protocol which will extract the average density from
# the results of a simulation.
extract_density = analysis.ExtractAverageStatistic("extract_density")
extract_density.statistics_type = ObservableType.Density
# Define the protocols which will run the simulation itself.
protocols, value_source, output_to_store = generate_base_simulation_protocols(
extract_density,
use_target_uncertainty,
n_molecules=n_molecules,
)
# Set up the gradient calculations
coordinate_source = ProtocolPath(
"output_coordinate_file", protocols.equilibration_simulation.id
)
trajectory_source = ProtocolPath(
"trajectory_file_path",
protocols.converge_uncertainty.id,
protocols.production_simulation.id,
)
statistics_source = ProtocolPath(
"statistics_file_path",
protocols.converge_uncertainty.id,
protocols.production_simulation.id,
)
reweight_density_template = reweighting.ReweightStatistics("")
reweight_density_template.statistics_type = ObservableType.Density
reweight_density_template.statistics_paths = statistics_source
reweight_density_template.reference_reduced_potentials = statistics_source
(
gradient_group,
gradient_replicator,
gradient_source,
) = generate_gradient_protocol_group(
reweight_density_template,
ProtocolPath("force_field_path", "global"),
coordinate_source,
trajectory_source,
statistics_source,
)
# Build the workflow schema.
schema = WorkflowSchema()
schema.protocol_schemas = [
protocols.build_coordinates.schema,
protocols.assign_parameters.schema,
protocols.energy_minimisation.schema,
protocols.equilibration_simulation.schema,
protocols.converge_uncertainty.schema,
protocols.extract_uncorrelated_trajectory.schema,
protocols.extract_uncorrelated_statistics.schema,
gradient_group.schema,
]
schema.protocol_replicators = [gradient_replicator]
schema.outputs_to_store = {"full_system": output_to_store}
schema.gradients_sources = [gradient_source]
schema.final_value_source = value_source
calculation_schema.workflow_schema = schema
return calculation_schema