IMP logo

IMP::Restraint Class Reference


Detailed Description

Abstract class for representing restraints.

Restraints should take their score function or UnaryFunction as the first argument. Restraints which act on large numbers of particles should allow the particle list to be skipped in the constructor and should provide methods so that the set of particles can be modified after construction.

A restraint can be added to the model multiple times or to multiple restraint sets in the same model.

Note:
When logging is VERBOSE, restraints should print enough information in evaluate to reproduce the the entire flow of data in evaluate. When logging is TERSE the restraint should print out only a constant number of lines per evaluate call.

Physical restraints should use the units of kcal/mol for restraint values and kcal/mol/A for derivatives.

Restraints will print a warning message if they are destroyed without ever having been added to a model as this is an easy mistake to make. To disable this warning for a particular restraint, call set_was_used(true).

Implementors
Developers who wish to implement a Restraint should inherit from this class and use the IMP_RESTRAINT() macro to help define the needed functions. IMP::example::ExampleRestraint provides an example to start from.
Inheritance diagram for IMP::Restraint:

Inheritance graph
[legend]

Public Member Functions

def __disown__
double evaluate (bool calc_derivs) const
 Return the score for this restraint for the current state of the model.
bool get_is_part_of_model () const
 Return true if this particle is part of a model.
Modelget_model () const
 Return the model containing this restraint.
ObjectsTemp get_output_objects () const
 Restraints cannot update other objects.
ParticlesTemp get_output_particles () const
 Restraints cannot update other particles.
 Restraint (std::string name="Restraint %1%")
virtual void set_model (Model *model)
 The restraint can override this in order to take action when added to a Model.
Interactions
Certain sorts of operations, such as evaluation of restraints in isolation, benefit from being able to determine which containers and particles are needed by which restraints.

virtual ContainersTemp get_input_containers () const =0
virtual ParticlesTemp get_input_particles () const =0
virtual ParticlesList get_interacting_particles () const =0
Incremental Evaluation
When optimizers move the particles a few at a time, scoring can be made more efficient by incremental score evaluation. To do so, a Restraint must implement Restraint::get_is_incremental() so that it returns true and implement Restraint::incremental_evaluate() to do the following

  • the return value should be the total score given the new conformation

  • for a Particle p, the sum of the derivatives of p->get_prechange_particle()

and p should be equal to the difference in derivatives between the current and prior conformations. This is most easily done by accumulating the negative of the prior derivative in p->get_prechange_particle() and the new derivative in p, for any particle touched.

virtual bool get_is_incremental () const
 Return true if the incremental_evaluate() function is implemented.

Friends

template<class T >
void IMP::internal::unref (T *)

Member Function Documentation

double IMP::Restraint::evaluate ( bool  calc_derivs  )  const

Return the score for this restraint for the current state of the model.

Returns:
Current score.
This method is equivalent to calling:
      model->evaluate(RestraintsTemp(1,this), calc_derivs)

virtual ParticlesTemp IMP::Restraint::get_input_particles (  )  const [pure virtual]

Given that the containers are up to date.

virtual void IMP::Restraint::set_model ( Model model  )  [virtual]

The restraint can override this in order to take action when added to a Model.

Users should generally not call this method directly; instead they should just use Model::add_restraint() to add the restraint to the Model.

Restraints that want to take action when they are added to the model can override this method (but be sure to call Restraint::set_model() to set the actual model pointer).


The documentation for this class was generated from the following files:

Generated on Mon Mar 8 23:08:45 2010 for IMP by doxygen 1.5.8