propertyestimator.protocols.utils.generate_gradient_protocol_group(template_reweighting_protocol, reference_force_field_paths, target_force_field_path, coordinate_file_path, trajectory_file_path, statistics_file_path='', replicator_id='repl', perturbation_scale=0.0001, substance_source=None, id_suffix='', enable_pbc=True, use_subset_of_force_field=True, effective_sample_indices=None)[source]

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. The reweighted observable of interest will be calculated by following the passed in analysis_protocol.

  • template_reweighting_protocol (BaseMBARProtocol) –

    A template protocol which will be used to reweight the observable of interest to small perturbations to the parameter of interest. These will then be used to calculate the finite difference gradient. This utility takes care of setting the target and reference reduced potentials.

    In the case that the template is of type ReweightStatistics and the observable is an energy, the statistics path will automatically be pointed to the energies evaluated using the perturbed parameter as opposed to the energy measured during the reference simulation.

  • reference_force_field_paths (ProtocolPath or list of ProtocolPath) – The paths to the force field parameters which were used to generate the trajectories from which the observables of interest were calculated.

  • target_force_field_path (ProtocolPath) –

    The path to the force field parameters which the observables are being

    estimated at (this is mainly only useful when estimating the gradients of reweighted observables).

  • coordinate_file_path (ProtocolPath) – A path to the initial coordinates of the simulation trajectory which was used to estimate the observable of interest.

  • trajectory_file_path (ProtocolPath) – A path to the simulation trajectory which was used to estimate the observable of interest.

  • statistics_file_path (ProtocolPath, optional) – A path to the statistics where were generated from the trajectory passed to the trajectory_file_path parameter. This is optional in cases where multiple reference force fields are passed to this method.

  • replicator_id (str) – A unique id which will be used for the protocol replicator which will replicate this group for every parameter of interest.

  • perturbation_scale (float) – The default amount to perturb parameters by.

  • substance_source (PlaceholderInput, optional) – An optional protocol path to the substance whose gradient is being estimated. If None, the global property substance is used.

  • id_suffix (str) – An optional string to append to the end of each of the protocol ids.

  • enable_pbc (bool) – If true, periodic boundary conditions are employed when recalculating the reduced potentials.

  • use_subset_of_force_field (bool) – If True, any reduced potentials will only be calculated from a subset of the force field which depends on the parameter of interest.

  • effective_sample_indices (ProtocolPath, optional) – A placeholder variable which can be used to make the gradient protocols dependant on an MBAR protcol to ensure gradients aren’t calcuated when the MBAR protocol failed due to insufficient samples.


  • ProtocolGroup – The protocol group which will estimate the gradient of an observable with respect to one parameter.

  • ProtocolReplicator – The replicator which will copy the gradient group for every parameter of interest.

  • ProtocolPath – A protocol path which points to the final gradient value.