original_docstring: 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`.
  
      Parameters
      ----------
      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.
  
      Returns
      -------
      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.
      
docstring: 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`.
  
  Parameters
  
  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.
  
  Returns
  
  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.
docstring_tokens: 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 ` . Parameters 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 . Returns 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 .
code: def 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=1.0e-4,
                                       substance_source=None,
                                       id_suffix='',
                                       enable_pbc=True,
                                       use_subset_of_force_field=True,
                                       effective_sample_indices=None):
      """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`.
  
      Parameters
      ----------
      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.
  
      Returns
      -------
      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.
      """
  
      assert isinstance(template_reweighting_protocol, reweighting.BaseMBARProtocol)
  
      id_suffix = f'_$({replicator_id}){id_suffix}'
  
      # Set values of the optional parameters.
      substance_source = ProtocolPath('substance', 'global') if substance_source is None else substance_source
      effective_sample_indices = effective_sample_indices if effective_sample_indices is not None else []
  
      # Define the protocol which will evaluate the reduced potentials of the
      # reference, forward and reverse states using only a subset of the full
      # force field.
      reduced_potentials = gradients.GradientReducedPotentials(f'gradient_reduced_potentials{id_suffix}')
  
      reduced_potentials.substance = substance_source
      reduced_potentials.thermodynamic_state = ProtocolPath('thermodynamic_state', 'global')
      reduced_potentials.reference_force_field_paths = reference_force_field_paths
      reduced_potentials.reference_statistics_path = statistics_file_path
      reduced_potentials.force_field_path = target_force_field_path
      reduced_potentials.trajectory_file_path = trajectory_file_path
      reduced_potentials.coordinate_file_path = coordinate_file_path
      reduced_potentials.parameter_key = ReplicatorValue(replicator_id)
      reduced_potentials.perturbation_scale = perturbation_scale
      reduced_potentials.use_subset_of_force_field = use_subset_of_force_field
      reduced_potentials.enable_pbc = enable_pbc
      reduced_potentials.effective_sample_indices = effective_sample_indices
  
      # Set up the protocols which will actually reweight the value of the
      # observable to the forward and reverse states.
      template_reweighting_protocol.bootstrap_iterations = 1
      template_reweighting_protocol.required_effective_samples = 0
      template_reweighting_protocol.reference_reduced_potentials = ProtocolPath('reference_potential_paths',
                                                                                reduced_potentials.id)
  
      # We need to make sure we use the observable evaluated at the target state
      # if the observable depends on the parameter being reweighted.
      use_target_state_energies = (isinstance(template_reweighting_protocol, reweighting.ReweightStatistics) and
                                   (template_reweighting_protocol.statistics_type == ObservableType.PotentialEnergy or
                                    template_reweighting_protocol.statistics_type == ObservableType.ReducedPotential or
                                    template_reweighting_protocol.statistics_type == ObservableType.TotalEnergy or
                                    template_reweighting_protocol.statistics_type == ObservableType.Enthalpy))
  
      template_reweighting_schema = template_reweighting_protocol.schema
  
      # Create the reweighting protocols from the template schema.
      reverse_mbar_schema = copy.deepcopy(template_reweighting_schema)
      reverse_mbar_schema.id = f'reverse_reweight{id_suffix}'
      reverse_mbar = available_protocols[reverse_mbar_schema.type](reverse_mbar_schema.id)
      reverse_mbar.schema = reverse_mbar_schema
      reverse_mbar.target_reduced_potentials = [ProtocolPath('reverse_potentials_path', reduced_potentials.id)]
  
      forward_mbar_schema = copy.deepcopy(template_reweighting_schema)
      forward_mbar_schema.id = f'forward_reweight{id_suffix}'
      forward_mbar = available_protocols[forward_mbar_schema.type](forward_mbar_schema.id)
      forward_mbar.schema = forward_mbar_schema
      forward_mbar.target_reduced_potentials = [ProtocolPath('forward_potentials_path', reduced_potentials.id)]
  
      if use_target_state_energies:
          reverse_mbar.statistics_paths = [ProtocolPath('reverse_potentials_path', reduced_potentials.id)]
          forward_mbar.statistics_paths = [ProtocolPath('forward_potentials_path', reduced_potentials.id)]
  
      # Set up the protocol which will actually evaluate the parameter gradient
      # using the central difference method.
      central_difference = gradients.CentralDifferenceGradient(f'central_difference{id_suffix}')
      central_difference.parameter_key = ReplicatorValue(replicator_id)
      central_difference.reverse_observable_value = ProtocolPath('value', reverse_mbar.id)
      central_difference.forward_observable_value = ProtocolPath('value', forward_mbar.id)
      central_difference.reverse_parameter_value = ProtocolPath('reverse_parameter_value', reduced_potentials.id)
      central_difference.forward_parameter_value = ProtocolPath('forward_parameter_value', reduced_potentials.id)
  
      # Assemble all of the protocols into a convenient group wrapper.
      gradient_group = groups.ProtocolGroup(f'gradient_group{id_suffix}')
      gradient_group.add_protocols(reduced_potentials, reverse_mbar, forward_mbar, central_difference)
  
      # Create the replicator which will copy the group for each parameter gradient
      # which will be calculated.
      parameter_replicator = ProtocolReplicator(replicator_id=replicator_id)
      parameter_replicator.template_values = ProtocolPath('parameter_gradient_keys', 'global')
  
      return gradient_group, parameter_replicator, ProtocolPath('gradient', gradient_group.id, central_difference.id)
code_tokens: def 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 = 1.0e-4 , substance_source = None , id_suffix = '' , enable_pbc = True , use_subset_of_force_field = True , effective_sample_indices = None ) : assert isinstance ( template_reweighting_protocol , reweighting . BaseMBARProtocol ) id_suffix = f'_$({replicator_id}){id_suffix}' substance_source = ProtocolPath ( 'substance' , 'global' ) if substance_source is None else substance_source effective_sample_indices = effective_sample_indices if effective_sample_indices is not None else [ ] reduced_potentials = gradients . GradientReducedPotentials ( f'gradient_reduced_potentials{id_suffix}' ) reduced_potentials . substance = substance_source reduced_potentials . thermodynamic_state = ProtocolPath ( 'thermodynamic_state' , 'global' ) reduced_potentials . reference_force_field_paths = reference_force_field_paths reduced_potentials . reference_statistics_path = statistics_file_path reduced_potentials . force_field_path = target_force_field_path reduced_potentials . trajectory_file_path = trajectory_file_path reduced_potentials . coordinate_file_path = coordinate_file_path reduced_potentials . parameter_key = ReplicatorValue ( replicator_id ) reduced_potentials . perturbation_scale = perturbation_scale reduced_potentials . use_subset_of_force_field = use_subset_of_force_field reduced_potentials . enable_pbc = enable_pbc reduced_potentials . effective_sample_indices = effective_sample_indices template_reweighting_protocol . bootstrap_iterations = 1 template_reweighting_protocol . required_effective_samples = 0 template_reweighting_protocol . reference_reduced_potentials = ProtocolPath ( 'reference_potential_paths' , reduced_potentials . id ) use_target_state_energies = ( isinstance ( template_reweighting_protocol , reweighting . ReweightStatistics ) and ( template_reweighting_protocol . statistics_type == ObservableType . PotentialEnergy or template_reweighting_protocol . statistics_type == ObservableType . ReducedPotential or template_reweighting_protocol . statistics_type == ObservableType . TotalEnergy or template_reweighting_protocol . statistics_type == ObservableType . Enthalpy ) ) template_reweighting_schema = template_reweighting_protocol . schema reverse_mbar_schema = copy . deepcopy ( template_reweighting_schema ) reverse_mbar_schema . id = f'reverse_reweight{id_suffix}' reverse_mbar = available_protocols [ reverse_mbar_schema . type ] ( reverse_mbar_schema . id ) reverse_mbar . schema = reverse_mbar_schema reverse_mbar . target_reduced_potentials = [ ProtocolPath ( 'reverse_potentials_path' , reduced_potentials . id ) ] forward_mbar_schema = copy . deepcopy ( template_reweighting_schema ) forward_mbar_schema . id = f'forward_reweight{id_suffix}' forward_mbar = available_protocols [ forward_mbar_schema . type ] ( forward_mbar_schema . id ) forward_mbar . schema = forward_mbar_schema forward_mbar . target_reduced_potentials = [ ProtocolPath ( 'forward_potentials_path' , reduced_potentials . id ) ] if use_target_state_energies : reverse_mbar . statistics_paths = [ ProtocolPath ( 'reverse_potentials_path' , reduced_potentials . id ) ] forward_mbar . statistics_paths = [ ProtocolPath ( 'forward_potentials_path' , reduced_potentials . id ) ] central_difference = gradients . CentralDifferenceGradient ( f'central_difference{id_suffix}' ) central_difference . parameter_key = ReplicatorValue ( replicator_id ) central_difference . reverse_observable_value = ProtocolPath ( 'value' , reverse_mbar . id ) central_difference . forward_observable_value = ProtocolPath ( 'value' , forward_mbar . id ) central_difference . reverse_parameter_value = ProtocolPath ( 'reverse_parameter_value' , reduced_potentials . id ) central_difference . forward_parameter_value = ProtocolPath ( 'forward_parameter_value' , reduced_potentials . id ) gradient_group = groups . ProtocolGroup ( f'gradient_group{id_suffix}' ) gradient_group . add_protocols ( reduced_potentials , reverse_mbar , forward_mbar , central_difference ) parameter_replicator = ProtocolReplicator ( replicator_id = replicator_id ) parameter_replicator . template_values = ProtocolPath ( 'parameter_gradient_keys' , 'global' ) return gradient_group , parameter_replicator , ProtocolPath ( 'gradient' , gradient_group . id , central_difference . id )
short_docstring: 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.
short_docstring_tokens: 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 .
comment: """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`.
  
      Parameters
      ----------
      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.
  
      Returns
      -------
      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.
      """$SEP$# Set values of the optional parameters.$SEP$# Define the protocol which will evaluate the reduced potentials of the$SEP$# reference, forward and reverse states using only a subset of the full$SEP$# force field.$SEP$# Set up the protocols which will actually reweight the value of the$SEP$# observable to the forward and reverse states.$SEP$# We need to make sure we use the observable evaluated at the target state$SEP$# if the observable depends on the parameter being reweighted.$SEP$# Create the reweighting protocols from the template schema.$SEP$# Set up the protocol which will actually evaluate the parameter gradient$SEP$# using the central difference method.$SEP$# Assemble all of the protocols into a convenient group wrapper.$SEP$# Create the replicator which will copy the group for each parameter gradient$SEP$# which will be calculated.