A restraint is a term in an IMP ScoringFunction. More...

#include "IMP/Restraint.h"

Inheritance diagram for IMP::kernel::Restraint:

Public Member Functions
	Restraint (Model *m, std::string name)

void	add_score_and_derivatives (ScoreAccumulator sa) const

Restraint *	create_current_decomposition () const
	Decompose this restraint into constituent terms for the current conf. More...

Restraint *	create_decomposition () const
	Decompose this restraint into constituent terms. More...

virtual ScoringFunction *	create_scoring_function (double weight=1.0, double max=NO_MAX) const

ContainersTemp	get_input_containers () const

ParticlesTemp	get_input_particles () const

virtual double	get_last_score () const

double	get_score () const

bool	get_was_good () const

Public Member Functions inherited from IMP::kernel::ModelObject
	ModelObject (Model *m, std::string name)

ModelObjectsTemp	get_inputs () const

ModelObjectsTemps	get_interactions () const

Model *	get_model () const

ModelObjectsTemp	get_outputs () const

Public Member Functions inherited from IMP::base::Object
virtual void	clear_caches ()

virtual IMP::base::VersionInfo	get_version_info () const =0
	Get information about the module and version of the object.

void	set_check_level (CheckLevel l)

void	set_log_level (LogLevel l)
	Set the logging level used in this object. More...

void	set_was_used (bool tf) const

void	show (std::ostream &out=std::cout) const

const std::string &	get_name () const

void	set_name (std::string name)

Protected Member Functions
virtual void	do_add_score_and_derivatives (ScoreAccumulator sa) const

virtual Restraints	do_create_current_decomposition () const

virtual Restraints	do_create_decomposition () const

ModelObjectsTemp	do_get_outputs () const

virtual void	do_update_dependencies ()

Protected Member Functions inherited from IMP::kernel::ModelObject
virtual ModelObjectsTemp	do_get_inputs () const =0

virtual ModelObjectsTemps	do_get_interactions () const

virtual void	update_dependencies ()

Protected Member Functions inherited from IMP::base::Object
	Object (std::string name)
	Construct an object with the given name. More...

Related Functions
(Note that these are not member functions.)
typedef IMP::base::Vector < IMP::base::WeakPointer < Restraint > >	RestraintsTemp

Related Functions inherited from IMP::kernel::ModelObject
typedef IMP::base::Vector < IMP::base::WeakPointer < ModelObject > >	ModelObjectsTemp

Related Functions inherited from IMP::base::Object
typedef IMP::base::Vector < IMP::base::WeakPointer < Object > >	ObjectsTemp

Weights
Each restraint's contribution to the model score is weighted. The total weight for the restraint is the some over all the paths containing it. That is, if a restraint is in a RestraintSet with weight .5 and another with weight 2, and the restaint itself has weight 3, then the total weight of the restraint is \(.5 \cdot 3 + 2 \cdot 3 = 7.5 \).
void	set_weight (Float weight)

Float	get_weight () const

Filtering
We are typically only interested in "good" conformations of the model. These are described by specifying maximum scores per restraint and for the whole model. Samplers, optimizers etc are free to ignore configurations they encounter which go outside these bounds. Note The maximum score is for the unweighted restraint. That is, the restraint evaluation is bad if the value is greater than the maximum score divided by the weight.
double	get_maximum_score () const

void	set_maximum_score (double s)

Detailed Description

Note: 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).

To implement a new restraint, just implement the two methods:

IMP::Restraint::do_add_score_and_derivatives() (or IMP::Restraint::unprotected_evaluate())
IMP::ModelObject::do_get_inputs(); and use the macro to handle IMP::base::Object
IMP_OBJECT_METHODS()

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.

When implementing an expensive restraint it makes sense to support early abort of evaluation if the user is only interested in good scores or scores below a threshold. To do this, look at the fields of the ScoreAccumulator object such as

See IMP::example::ExampleRestraint for an example.

Definition at line 57 of file kernel/declare_Restraint.h.

Constructor & Destructor Documentation

IMP::kernel::Restraint::Restraint	(	Model *	m,
		std::string	name
	)

Create a restraint and register it with the model. The restraint is not added to implicit scoring function in the Model.

Member Function Documentation

void IMP::kernel::Restraint::add_score_and_derivatives ( ScoreAccumulator sa ) const

This methid is called in order to perform the actual restraint scoring. The restraints should assume that all appropriate ScoreState objects have been updated and so that the input particles and containers are up to date. The returned score should be the unweighted score.

Restraint* IMP::kernel::Restraint::create_current_decomposition ( ) const

Return a decomposition that is value for the current conformation, but will not necessarily be valid if any of the particles are changed. This is the same as create_decomposition() for non-conditional restraints.

The restraints returned have had set_model() called and so can be evaluated.

Restraint* IMP::kernel::Restraint::create_decomposition ( ) const

Given the set of input particles, decompose the restraint into as simple parts as possible. For many restraints, the simplest part is simply the restraint itself.

If a restraint can be decomposed, it should return a RestraintSet so that the maximum score and weight can be passed properly.

The restraints returned have had set_model() called and so can be evaluated.

virtual ScoringFunction* IMP::kernel::Restraint::create_scoring_function	(	double	weight = `1.0`,
		double	max = `NO_MAX`
	)		const

virtual

Create a scoring function with only this restarint.

Note: This method cannot be implemented in python due to memory management issues (and the question of why you would ever want to).

virtual void IMP::kernel::Restraint::do_add_score_and_derivatives ( ScoreAccumulator sa ) const

protectedvirtual

A restraint should override this to compute the score and derivatives.

Reimplemented in IMP::container::PredicatePairsRestraint, IMP::container::PredicateQuadsRestraint, IMP::container::PredicateSingletonsRestraint, IMP::container::PredicateTripletsRestraint, and IMP::example::ExampleRestraint.

virtual Restraints IMP::kernel::Restraint::do_create_current_decomposition ( ) const

protectedvirtual

A Restraint should override this if they want to decompose themselves for display and other purposes. The returned restraints will be made in to a RestraintSet, if needed and the weight and maximum score set for the restraint set.

The returned restraints should be only the non-zero terms and should have their last scores set appropriately;

Reimplemented in IMP::core::MSConnectivityRestraint, IMP::core::ExcludedVolumeRestraint, and IMP::core::ConnectivityRestraint.

Definition at line 239 of file kernel/declare_Restraint.h.

virtual Restraints IMP::kernel::Restraint::do_create_decomposition ( ) const

protectedvirtual

A Restraint should override this if they want to decompose themselves for domino and other purposes. The returned restraints will be made in to a RestraintSet, if needed and the weight and maximum score set for the restraint set.

Reimplemented in IMP::core::ExcludedVolumeRestraint.

Definition at line 228 of file kernel/declare_Restraint.h.

ModelObjectsTemp IMP::kernel::Restraint::do_get_outputs ( ) const

protectedvirtual

No outputs.

Implements IMP::kernel::ModelObject.

Definition at line 249 of file kernel/declare_Restraint.h.

virtual void IMP::kernel::Restraint::do_update_dependencies ( )

protectedvirtual

There is no interesting dependency tracking.

Reimplemented from IMP::kernel::ModelObject.

Definition at line 247 of file kernel/declare_Restraint.h.