IMP::Restraint Class Reference

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

#include "IMP/Restraint.h"

Inherits IMP::ModelObject.

Inherited by IMP::atom::CAAngleRestraint, IMP::atom::CADihedralRestraint, IMP::atom::CHARMMStereochemistryRestraint, IMP::atom::EzRestraint, IMP::atom::HelixRestraint, IMP::bayesianem::GaussianEMRestraint, IMP::container::MinimumPairRestraint, IMP::container::MinimumQuadRestraint, IMP::container::MinimumSingletonRestraint, IMP::container::MinimumTripletRestraint, IMP::container::PairsRestraint, IMP::container::PredicatePairsRestraint, IMP::container::PredicateQuadsRestraint, IMP::container::PredicateSingletonsRestraint, IMP::container::PredicateTripletsRestraint, IMP::container::QuadsRestraint, IMP::container::SingletonsRestraint, IMP::container::TripletsRestraint, IMP::core::ConnectivityRestraint, IMP::core::ConstantRestraint, IMP::core::DiameterRestraint, IMP::core::DihedralRestraint, IMP::core::DistanceRestraint, IMP::core::ExcludedVolumeRestraint, IMP::core::MinimumRestraint, IMP::core::MSConnectivityRestraint, IMP::core::MultipleBinormalRestraint, IMP::core::PairRestraint, IMP::core::QuadRestraint, IMP::core::RigidBodyUmbrella, IMP::core::SingletonRestraint, IMP::core::TripletRestraint, IMP::core::VolumeRestraint, IMP::em2d::DummyRestraint, IMP::em2d::Em2DRestraint, IMP::em2d::Fine2DRegistrationRestraint, IMP::em2d::ParticlesDummyRestraint, IMP::em2d::PCAFitRestraint, IMP::em2d::RigidBodiesImageFitRestraint, IMP::em::DensityFillingRestraint, IMP::em::EnvelopeFitRestraint, IMP::em::EnvelopePenetrationRestraint, IMP::em::FitRestraint, IMP::em::PCAFitRestraint, IMP::example::ExampleComplexRestraint, IMP::example::ExampleRestraint, IMP.example.PythonExampleRestraint, IMP::isd::AmbiguousNOERestraint, IMP::isd::AmbiguousRestraint, IMP::isd::AtomicCrossLinkMSRestraint, IMP::isd::CrossLinkMSRestraint, IMP::isd::CysteineCrossLinkRestraint, IMP::isd::FretRestraint, IMP::isd::GammaPrior, IMP::isd::GaussianEMRestraint, IMP::isd::GaussianProcessInterpolationRestraint, IMP::isd::GaussianRestraint, IMP::isd::ISDRestraint, IMP::isd::JeffreysRestraint, IMP::isd::LognormalAmbiguousRestraint, IMP::isd::LognormalRestraint, IMP::isd::MarginalHBondRestraint, IMP::isd::MarginalNOERestraint, IMP::isd::NOERestraint, IMP::isd::NormalSigmaPCRestraint, IMP::isd::StudentTRestraint, IMP::isd::TALOSRestraint, IMP::isd::UniformPrior, IMP::isd::vonMisesKappaConjugateRestraint, IMP::isd::vonMisesKappaJeffreysRestraint, IMP::isd::WeightRestraint, IMP.modeller.ModellerRestraints, IMP::multifit::ComplementarityRestraint, IMP::multifit::DummyRestraint, IMP::multifit::RadiusOfGyrationRestraint, IMP::multifit::WeightedExcludedVolumeRestraint, IMP::npc::AssemblySymmetryByDihedralRestraint, IMP::npc::AssemblySymmetryByDistanceRestraint, IMP::npc::CompositeRestraint, IMP::npc::MembraneExclusionRestraint, IMP::npc::MembraneSurfaceLocationConditionalRestraint, IMP::npc::MembraneSurfaceLocationRestraint, IMP::npc::PerinuclearVolumeLocationRestraint, IMP::npc::PoreSideVolumeLocationRestraint, IMP::npc::ProteinChainRestraint, IMP::npc::ProteinContactRestraint, IMP::npc::ProteinProximityRestraint, IMP::npc::XYRadialPositionLowerRestraint, IMP::npc::XYRadialPositionRestraint, IMP::npc::XYRadialPositionUpperRestraint, IMP::npc::YAxialPositionLowerRestraint, IMP::npc::YAxialPositionRestraint, IMP::npc::YAxialPositionUpperRestraint, IMP::npc::ZAxialPositionLowerRestraint, IMP::npc::ZAxialPositionRestraint, IMP::npc::ZAxialPositionUpperRestraint, IMP::pmi1::CompositeRestraint, IMP.pmi1.restraints.basic.BiStableDistanceRestraint, IMP.pmi1.restraints.basic.CylinderRestraint, IMP.pmi1.restraints.proteomics.ConnectivityNetworkRestraint, IMP.pmi1.restraints.proteomics.FuzzyRestraint, IMP::pmi1::SigmoidRestraintSphere, IMP::pmi::CompositeRestraint, IMP.pmi.restraints.basic.BiStableDistanceRestraint, IMP.pmi.restraints.basic.CylinderRestraint, IMP.pmi.restraints.proteomics.ConnectivityNetworkRestraint, IMP.pmi.restraints.proteomics.FuzzyRestraint, IMP::RestraintSet, IMP::saxs::Restraint, IMP::spb::DiameterRgyrRestraint, IMP::spb::DistanceTerminiRestraint, IMP::spb::ISDRestraint, IMP::spb::TwoStateGoModelRestraint, and write_a_restraint.MyRestraint.

Detailed Description

A restraint is a term in an IMP ScoringFunction.

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

• IMP::Restraint::do_add_score_and_derivatives()
• IMP::ModelObject::do_get_inputs(); and use the macro to handle IMP::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

• ScoreAccumulator::get_is_evaluate_if_below(),
• ScoreAccumulator::get_is_evaluate_if_good()
• ScoreAccumulator::get_maximum()

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

Definition at line 54 of file Restraint.h.

Public Member Functions
	Restraint (Model *m, std::string name)
void	add_score_and_derivatives (ScoreAccumulator sa) const
	Perform the actual restraint scoring. More...
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
	Create a scoring function with only this restraint. More...
virtual RestraintInfo *	get_dynamic_info () const
virtual double	get_last_score () const
double	get_score () const
virtual RestraintInfo *	get_static_info () const
bool	get_was_good () const
Public Member Functions inherited from IMP::ModelObject
	ModelObject (Model *m, std::string name)
bool	get_has_dependencies () const
	Return whether this object has dependencies computed. More...
bool	get_has_required_score_states () const
	Return whether score states are computed. More...
ModelObjectsTemp	get_inputs () const
ModelObjectsTemps	get_interactions () const
	Get the interacting sets induced by this ModelObject. More...
Model *	get_model () const
ModelObjectsTemp	get_outputs () const
const ScoreStatesTemp &	get_required_score_states () const
	Get the score states that are ancestors of this in the dependency graph. More...
void	set_has_dependencies (bool tf)
	Either invalidate the dependencies or ensure they are correct. More...
void	set_has_required_score_states (bool tf)
	Compute the required score states. More...
Public Member Functions inherited from IMP::Object
virtual void	clear_caches ()
CheckLevel	get_check_level () const
LogLevel	get_log_level () const
virtual VersionInfo	get_version_info () const
	Get information about the module and version of the object. More...
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)
virtual std::string	get_type_name () const

Protected Member Functions
virtual void	do_add_score_and_derivatives (ScoreAccumulator sa) const
	A restraint should override this to compute the score and derivatives. More...
virtual Restraints	do_create_current_decomposition () const
virtual Restraints	do_create_decomposition () const
ModelObjectsTemp	do_get_outputs () const
Protected Member Functions inherited from IMP::ModelObject
virtual ModelObjectsTemp	do_get_inputs () const =0
virtual ModelObjectsTemps	do_get_interactions () const
virtual void	handle_set_has_required_score_states (bool)
Protected Member Functions inherited from IMP::Object
	Object (std::string name)
	Construct an object with the given name. More...
virtual void	do_destroy ()

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 restraint 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 (or RestraintSet). 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)

Constructor & Destructor Documentation

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

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

Member Function Documentation

void IMP::Restraint::add_score_and_derivatives

(

ScoreAccumulator

sa

)

const

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::Restraint::create_current_decomposition

(

)

const

Decompose this restraint into constituent terms for the current conf.

Returns

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::Restraint::create_decomposition

(

)

const

Decompose this restraint into constituent terms.

Given the set of input particles, decompose the restraint into parts that are as simple 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::Restraint::create_scoring_function ( double  weight = 1.0, double  max = NO_MAX  ) const

virtual

Create a scoring function with only this restraint.

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::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, IMP::example::ExampleRestraint, and IMP::isd::LogWrapper.

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

protectedvirtual

A Restraint should override this if it wants to decompose itself for display and other purposes. The returned restraints will be made into a RestraintSet if needed, with suitable weight and maximum score.

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

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

Definition at line 235 of file Restraint.h.

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

protectedvirtual

A Restraint should override this if it wants to decompose itself for domino and other purposes. The returned restraints will be made into a RestraintSet if needed, with suitable weight and maximum score.

Reimplemented in IMP::core::ExcludedVolumeRestraint.

Definition at line 225 of file Restraint.h.

ModelObjectsTemp IMP::Restraint::do_get_outputs ( ) const

protectedvirtual

No outputs.

Implements IMP::ModelObject.

Definition at line 242 of file Restraint.h.

virtual RestraintInfo* IMP::Restraint::get_dynamic_info ( ) const

virtual

Returns

dynamic key:value information about this restraint, or null.

a set of key:value pairs that contain dynamic information about this restraint (i.e. information that changes during a sampling run, such as scores or cross correlations). If no such information is available, a null pointer is returned. This information is used when writing restraints to files, e.g. by the IMP.rmf module.

Reimplemented in IMP::bayesianem::GaussianEMRestraint, IMP::isd::GaussianEMRestraint, IMP::em2d::PCAFitRestraint, and IMP::isd::UniformPrior.

Definition at line 129 of file Restraint.h.

virtual double IMP::Restraint::get_last_score ( ) const

virtual

Return the (unweighted) score for this restraint last time it was evaluated.

Note

If some sort of special evaluation (eg Model::evaluate_if_good()) was the last call, the score, if larger than the max, is not accurate.

Reimplemented in IMP::RestraintSet.

Definition at line 212 of file Restraint.h.

double IMP::Restraint::get_score

(

)

const

Compute and return the current score for the restraint.

virtual RestraintInfo* IMP::Restraint::get_static_info ( ) const

virtual

Returns

static key:value information about this restraint, or null.

a set of key:value pairs that contain static information about this restraint (i.e. information that doesn't change during a sampling run, such as the type of restraint or filename from which information is read). Usually this includes a "type" key with the fully qualified classname (e.g. IMP.mymodule.MyRestraint). If no such information is available, a null pointer is returned. This information is used when writing restraints to files, e.g. by the IMP.rmf module.

Reimplemented in IMP::bayesianem::GaussianEMRestraint, IMP::isd::GaussianEMRestraint, IMP::em2d::PCAFitRestraint, IMP::saxs::Restraint, and IMP::isd::UniformPrior.

Definition at line 117 of file Restraint.h.

bool IMP::Restraint::get_was_good

(

)

const

Return whether this restraint violated its maximum last time it was evaluated.

Definition at line 216 of file Restraint.h.

---

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

• Restraint.h