IMP logo
IMP Reference Guide  develop.4390929e3e,2024/11/12
The Integrative Modeling Platform
SingletonScore.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/SingletonScore.h
7  * \brief Define SingletonScore.
8  *
9  * Copyright 2007-2022 IMP Inventors. All rights reserved.
10  */
11 
12 #ifndef IMPKERNEL_SINGLETON_SCORE_H
13 #define IMPKERNEL_SINGLETON_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 ParticleIndex.
27 /** SingletonScore will evaluate the score and derivatives
28  for passed object(s) of type ParticleIndex.
29 
30  Use in conjunction with various
31  restraints such as IMP::container::SingletonsRestraint or
32  IMP::core::SingletonRestraint. The restraints couple the score
33  functions with appropriate lists of object(s) of type ParticleIndex.
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_SINGLETON_SCORE_METHODS().
41 
42  \see PredicateSingletonRestraint
43 */
44 class IMPKERNELEXPORT SingletonScore : public ParticleInputs,
45  public Object {
46  public:
47  typedef Particle* Argument;
49  typedef Particle* PassArgument;
52  SingletonScore(std::string name = "SingletonScore %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 Particle
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, ParticleIndex 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 Particle, 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_SINGLETON_SCORE_METHODS() macro.
75  */
76  virtual double evaluate_indexes(Model *m, const ParticleIndexes &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_SINGLETON_SCORE_METHODS() macro.
87  */
88  virtual double evaluate_indexes_scores(
89  Model *m, const ParticleIndexes &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_SINGLETON_SCORE_METHODS() macro.
102  */
103  virtual double evaluate_indexes_delta(
104  Model *m, const ParticleIndexes &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, ParticleIndex 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_SINGLETON_SCORE_METHODS() macro.
127  */
128  virtual double evaluate_if_good_indexes(Model *m,
129  const ParticleIndexes &o,
130  DerivativeAccumulator *da, double max,
131  unsigned int lower_bound,
132  unsigned int upper_bound) const;
133 
134  //! Decompose this SingletonScore 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  ParticleIndex vt) const;
143 
144  protected:
145  //! Override this to return your own decomposition.
146  virtual Restraints do_create_current_decomposition(Model *m,
147  ParticleIndex 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_SINGLETON_SCORE_H */
A base class for modifiers of ParticlesTemp.
Basic types used by IMP.
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.
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
Abstract class for scoring object(s) of type ParticleIndex.
Classes used in the construction of ModelObjects.
Various general useful macros for IMP.
Class to handle individual particles of a Model object.
Definition: Particle.h:43
Class for adding derivatives from restraints to the model.