IMP logo
IMP Reference Guide  2.17.0
The Integrative Modeling Platform
PairScore.h
Go to the documentation of this file.
1 // Autogenerated by ../../../../tmp/nightly-build-402/imp-2.17.0/tools/build/make_containers.py
2 // from ../../../../tmp/nightly-build-402/imp-2.17.0/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 "model_object_helpers.h"
21 
22 IMPKERNEL_BEGIN_NAMESPACE
23 
24 //! Abstract class for scoring object(s) of type ParticleIndexPair.
25 /** PairScore will evaluate the score and derivatives
26  for passed object(s) of type ParticleIndexPair.
27 
28  Use in conjunction with various
29  restraints such as IMP::container::PairsRestraint or
30  IMP::core::PairRestraint. The restraints couple the score
31  functions with appropriate lists of object(s) of type ParticleIndexPair.
32 
33  It is possible to call the various evaluate* methods directly, but
34  this is not recommended as they do not ensure that Model invariants
35  (e.g. ScoreStates) are preserved. Use a Restraint or ScoringFunction
36  to score the model instead.
37 
38  Implementers should check out IMP_PAIR_SCORE().
39 
40  \see PredicatePairRestraint
41 */
42 class IMPKERNELEXPORT PairScore : public ParticleInputs,
43  public Object {
44  public:
45  typedef ParticlePair Argument;
47  typedef const ParticlePair& PassArgument;
48  typedef const ParticleIndexPair& PassIndexArgument;
49  typedef PairModifier Modifier;
50  PairScore(std::string name = "PairScore %1%");
51 
52  //! Compute the score and the derivative if needed.
53  /** @param m the model of vt
54  @param vt the index in m of an object of type ParticlePair
55  @param da a DerivativeAccumulator that weights
56  computed derivatives. If nullptr, derivatives
57  will not be computed.
58  */
59  virtual double evaluate_index(Model *m, const ParticleIndexPair& vt,
60  DerivativeAccumulator *da) const = 0;
61 
62  //! Compute the score and the derivative if needed over a set.
63  /** @param m the model of o
64  @param o objects of type ParticlePair, specified by index
65  @param da a derivative accumulator that weights
66  computed derivatives. If nullptr, derivatives
67  will not be computed.
68  @param lower_bound index of first item in o to evaluate
69  @param upper_bound index one past last item in o to evaluate
70 
71  @note Implementations for these are provided by
72  the IMP_PAIR_SCORE() macro.
73  */
74  virtual double evaluate_indexes(Model *m, const ParticleIndexPairs &o,
76  unsigned int lower_bound,
77  unsigned int upper_bound) const;
78 
79  //! Compute the score and the derivative if needed over a set.
80  /** Like regular evaluate_indexes(), but the score for each o[x] is also
81  returned as score[x]. */
82  virtual double evaluate_indexes_scores(
83  Model *m, const ParticleIndexPairs &o,
85  unsigned int lower_bound,
86  unsigned int upper_bound,
87  std::vector<double> &score) const;
88 
89  //! Compute the change in score and the derivative if needed over a set.
90  /** The score for each o[indexes[x]] is updated in score[indexes[x]]
91  and the total difference between the old and new score values (over the
92  set) is returned. */
93  virtual double evaluate_indexes_delta(
94  Model *m, const ParticleIndexPairs &o,
96  const std::vector<unsigned> &indexes,
97  std::vector<double> &score) const;
98 
99  //! Compute the score and the derivative if needed, only if "good".
100  /** This functions similarly to evaluate_index(),
101  but may terminate the computation early if the score is higher than max.
102 
103  @return the score if score<= max or some arbitrary value > max otherwise.
104  */
105  virtual double evaluate_if_good_index(Model *m, const ParticleIndexPair& vt,
107  double max) const;
108 
109  /** Compute the score and the derivative if needed over a set, only if "good".
110  This functions similarly to evaluate_indexes(), but may terminate
111  the computation early if the total score is higher than max.
112 
113  @return the score if score<= max or some arbitrary value > max otherwise.
114 
115  @note Implementations for these are provided by the IMP_PAIR_SCORE()
116  macro.
117  */
118  virtual double evaluate_if_good_indexes(Model *m,
119  const ParticleIndexPairs &o,
120  DerivativeAccumulator *da, double max,
121  unsigned int lower_bound,
122  unsigned int upper_bound) const;
123 
124  //! Decompose this PairScore into a set of
125  //! currently positive restraints over vt.
126  /** The scoring function and derivatives should
127  be equal to the current score. The default implementation
128  returns a single restraint with this score bound to vt,
129  or zero restraints if the score equals zero.
130 . */
131  Restraints create_current_decomposition(Model *m,
132  const ParticleIndexPair& vt) const;
133 
134  protected:
135  //! Override this to return your own decomposition.
136  virtual Restraints do_create_current_decomposition(Model *m,
137  const ParticleIndexPair& vt) const;
138 
140 };
141 
142 IMPKERNEL_END_NAMESPACE
143 
144 #endif /* IMPKERNEL_PAIR_SCORE_H */
Abstract class for scoring object(s) of type ParticleIndexPair.
Definition: PairScore.h:42
Basic types used by IMP.
A class to store an fixed array of same-typed values.
Definition: Array.h:33
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)
Ref counted objects should have private destructors.
A base class for modifiers of ParticlePairsTemp.
Definition: PairModifier.h:32
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:73
Common base class for heavy weight IMP objects.
Definition: Object.h:106
Classes used in the construction of ModelObjects.
Various general useful macros for IMP.
Class for adding derivatives from restraints to the model.