IMP logo
IMP Reference Guide  develop.4390929e3e,2024/11/12
The Integrative Modeling Platform
PairScore.h
Go to the documentation of this file.
1 // Autogenerated by ../../../../tmp/nightly-build-388/imp-20241112.develop.4390929e3e/tools/build/make_containers.py
2 // from ../../../../tmp/nightly-build-388/imp-20241112.develop.4390929e3e/tools/build/container_templates/kernel/ClassnameScore.h
3 // Do not edit - any changes will be lost!
4 
5 /**
6  * \file IMP/PairScore.h
7  * \brief Define PairScore.
8  *
9  * Copyright 2007-2022 IMP Inventors. All rights reserved.
10  */
11 
12 #ifndef IMPKERNEL_PAIR_SCORE_H
13 #define IMPKERNEL_PAIR_SCORE_H
14 
15 #include <IMP/kernel_config.h>
16 #include "base_types.h"
17 #include "DerivativeAccumulator.h"
18 #include "internal/container_helpers.h"
19 #include <IMP/utility_macros.h>
20 #include <cereal/access.hpp>
21 #include <cereal/types/base_class.hpp>
22 #include "model_object_helpers.h"
23 
24 IMPKERNEL_BEGIN_NAMESPACE
25 
26 //! Abstract class for scoring object(s) of type ParticleIndexPair.
27 /** PairScore will evaluate the score and derivatives
28  for passed object(s) of type ParticleIndexPair.
29 
30  Use in conjunction with various
31  restraints such as IMP::container::PairsRestraint or
32  IMP::core::PairRestraint. The restraints couple the score
33  functions with appropriate lists of object(s) of type ParticleIndexPair.
34 
35  It is possible to call the various evaluate* methods directly, but
36  this is not recommended as they do not ensure that Model invariants
37  (e.g. ScoreStates) are preserved. Use a Restraint or ScoringFunction
38  to score the model instead.
39 
40  Implementers should check out IMP_PAIR_SCORE_METHODS().
41 
42  \see PredicatePairRestraint
43 */
44 class IMPKERNELEXPORT PairScore : public ParticleInputs,
45  public Object {
46  public:
47  typedef ParticlePair Argument;
49  typedef const ParticlePair& PassArgument;
50  typedef const ParticleIndexPair& PassIndexArgument;
51  typedef PairModifier Modifier;
52  PairScore(std::string name = "PairScore %1%");
53 
54  //! Compute the score and the derivative if needed.
55  /** @param m the model of vt
56  @param vt the index in m of an object of type ParticlePair
57  @param da a DerivativeAccumulator that weights
58  computed derivatives. If nullptr, derivatives
59  will not be computed.
60  */
61  virtual double evaluate_index(Model *m, const ParticleIndexPair& vt,
62  DerivativeAccumulator *da) const = 0;
63 
64  //! Compute the score and the derivative if needed over a set.
65  /** @param m the model of o
66  @param o objects of type ParticlePair, specified by index
67  @param da a derivative accumulator that weights
68  computed derivatives. If nullptr, derivatives
69  will not be computed.
70  @param lower_bound index of first item in o to evaluate
71  @param upper_bound index one past last item in o to evaluate
72 
73  @note An implementation for this is provided by
74  the IMP_PAIR_SCORE_METHODS() macro.
75  */
76  virtual double evaluate_indexes(Model *m, const ParticleIndexPairs &o,
78  unsigned int lower_bound,
79  unsigned int upper_bound) const;
80 
81  //! Compute the score and the derivative if needed over a set.
82  /** Like regular evaluate_indexes(), but the score for each o[x] is also
83  returned as score[x].
84 
85  @note An implementation for this is provided by
86  the IMP_PAIR_SCORE_METHODS() macro.
87  */
88  virtual double evaluate_indexes_scores(
89  Model *m, const ParticleIndexPairs &o,
91  unsigned int lower_bound,
92  unsigned int upper_bound,
93  std::vector<double> &score) const;
94 
95  //! Compute the change in score and the derivative if needed over a set.
96  /** The score for each o[indexes[x]] is updated in score[indexes[x]]
97  and the total difference between the old and new score values (over the
98  set) is returned.
99 
100  @note An implementation for this is provided by
101  the IMP_PAIR_SCORE_METHODS() macro.
102  */
103  virtual double evaluate_indexes_delta(
104  Model *m, const ParticleIndexPairs &o,
106  const std::vector<unsigned> &indexes,
107  std::vector<double> &score) const;
108 
109  //! Compute the score and the derivative if needed, only if "good".
110  /** This functions similarly to evaluate_index(),
111  but may terminate the computation early if the score is higher than max.
112 
113  @return the score if score<= max or some arbitrary value > max otherwise.
114  */
115  virtual double evaluate_if_good_index(Model *m, const ParticleIndexPair& vt,
117  double max) const;
118 
119  /** Compute the score and the derivative if needed over a set, only if "good".
120  This functions similarly to evaluate_indexes(), but may terminate
121  the computation early if the total score is higher than max.
122 
123  @return the score if score<= max or some arbitrary value > max otherwise.
124 
125  @note An implementation for this is provided by
126  the IMP_PAIR_SCORE_METHODS() macro.
127  */
128  virtual double evaluate_if_good_indexes(Model *m,
129  const ParticleIndexPairs &o,
130  DerivativeAccumulator *da, double max,
131  unsigned int lower_bound,
132  unsigned int upper_bound) const;
133 
134  //! Decompose this PairScore into a set of
135  //! currently positive restraints over vt.
136  /** The scoring function and derivatives should
137  be equal to the current score. The default implementation
138  returns a single restraint with this score bound to vt,
139  or zero restraints if the score equals zero.
140  */
141  Restraints create_current_decomposition(Model *m,
142  const ParticleIndexPair& vt) const;
143 
144  protected:
145  //! Override this to return your own decomposition.
146  virtual Restraints do_create_current_decomposition(Model *m,
147  const ParticleIndexPair& vt) const;
148 
150 
151  private:
152  friend class cereal::access;
153 
154  template<class Archive> void serialize(Archive &ar) {
155  // Neither we nor ParticleInputs stores data, but Object does
156  ar(cereal::base_class<Object>(this));
157  }
158 };
159 
160 IMPKERNEL_END_NAMESPACE
161 
162 #endif /* IMPKERNEL_PAIR_SCORE_H */
Abstract class for scoring object(s) of type ParticleIndexPair.
Definition: PairScore.h:44
Basic types used by IMP.
A class to store a fixed array of same-typed values.
Definition: Array.h:40
Class for adding derivatives from restraints to the model.
Base class for objects that take particle arguments and read from them.
#define IMP_REF_COUNTED_DESTRUCTOR(Name)
Set up destructor for a ref counted object.
A base class for modifiers of ParticlePairsTemp.
Definition: PairModifier.h:32
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:86
Common base class for heavy weight IMP objects.
Definition: Object.h:111
Classes used in the construction of ModelObjects.
Various general useful macros for IMP.
Class for adding derivatives from restraints to the model.