kernel/PairScore.h

Go to the documentation of this file.

/**
 *  \file IMP/kernel/PairScore.h
 *  \brief Define PairScore.
 *
 *  WARNING This file was generated from PairScore.h
 *  in /tmp/nightly-build-29065/imp-2.3.1/tools/build/container_templates/kernel
 *  by tools/build/make_containers.py.
 *
 *  Copyright 2007-2014 IMP Inventors. All rights reserved.
 */

#ifndef IMPKERNEL_PAIR_SCORE_H
#define IMPKERNEL_PAIR_SCORE_H

#include <IMP/kernel/kernel_config.h>
#include "base_types.h"
#include "ParticleTuple.h"
#include "DerivativeAccumulator.h"
#include "internal/container_helpers.h"
#include <IMP/base/utility_macros.h>
#include "model_object_helpers.h"

IMPKERNEL_BEGIN_NAMESPACE

//! Abstract class for scoring object(s) of type ParticlePair
/** PairScore will evaluate the score and derivatives
    for passed object(s) of type ParticlePair.

    Use in conjunction with various
    restraints such as IMP::core::PairsRestraint or
    IMP::core::PairRestraint. The restraints couple the score
    functions with appropariate lists of object(s) of type ParticlePair.

    Implementers should check out IMP_PAIR_SCORE().

    \see PredicatePairRestraint
*/
class IMPKERNELEXPORT PairScore : public ParticleInputs,
                                       public base::Object {
 public:
  typedef kernel::ParticlePair Argument;
  typedef kernel::ParticleIndexPair IndexArgument;
  typedef const kernel::ParticlePair& PassArgument;
  typedef const kernel::ParticleIndexPair& PassIndexArgument;
  typedef PairModifier Modifier;
  PairScore(std::string name = "PairScore %1%");
  //! Compute the score and the derivative if needed.
  /** \deprecated_at{2.1} Use the index-based evaluate instead. */
  IMPKERNEL_DEPRECATED_METHOD_DECL(2.1)
  virtual double evaluate(const kernel::ParticlePair& vt, DerivativeAccumulator *da) const;

  //! Compute the score and the derivative if needed.
  /** evaluate the score and the derivative if needed over vt

      @param m the model of vt
      @param vt the index in m of an object of type ParticlePair
      @param da a derivative accumulator that reweighting
                computed derivatives. If nullptr, derivatives
                will not be computed
   */
  virtual double evaluate_index(kernel::Model *m, const kernel::ParticleIndexPair& vt,
                                DerivativeAccumulator *da) const;

  //! Compute the score and the derivative if needed over a set.
  /** evaluate the score and the derivative if needed over a set
      of objects in o

      @param m the model of o
      @param o objects of type ParticlePair, specified by index
      @param da a derivative accumulator that reweighting
                computed derivatives. If nullptr, derivatives
                will not be computed
      @param lower_bound index of first item in o to evaluate
      @param upper_bound index of last item in o to evaluate

      @note Implementations
      for these are provided by the IMP_PAIR_SCORE()
      macro.
  */
  virtual double evaluate_indexes(kernel::Model *m, const kernel::ParticleIndexPairs &o,
                                  DerivativeAccumulator *da,
                                  unsigned int lower_bound,
                                  unsigned int upper_bound) const;

  //! Compute the score and the derivative if needed.
  /** Compute the score and the derivative if needed as in evaluate_index().
      but may terminate the computation early if the score is higher than max.

      @return the score if score<= max or some arbitrary value > max otherwise.
  */
  virtual double evaluate_if_good_index(kernel::Model *m, const kernel::ParticleIndexPair& vt,
                                        DerivativeAccumulator *da,
                                        double max) const;

  /** Compute the score and the derivative if needed as in evaluate_index().
      but may terminate the computation early if the total score is higher than max.

      @return the score if score<= max or some arbitrary value > max otherwise.

      Implementations
      for these are provided by the IMP_PAIR_SCORE()
      macro.
  */
  virtual double evaluate_if_good_indexes(kernel::Model *m,
                                          const kernel::ParticleIndexPairs &o,
                                          DerivativeAccumulator *da, double max,
                                          unsigned int lower_bound,
                                          unsigned int upper_bound) const;
  /** Decompose this pair score acting on the pair into a set of
      restraints. The scoring function and derivatives should
      be equal to the current score. The defualt implementation
      just returns this object bound to the pair.*/
  Restraints create_current_decomposition(kernel::Model *m,
                                          const kernel::ParticleIndexPair& vt) const;

 protected:
  /** Overide this to return your own decomposition.*/
  virtual Restraints do_create_current_decomposition(kernel::Model *m,
                                                     const kernel::ParticleIndexPair& vt) const;

  IMP_REF_COUNTED_DESTRUCTOR(PairScore);
};

IMPKERNEL_END_NAMESPACE

#endif /* IMPKERNEL_PAIR_SCORE_H */