IMP logo
IMP Reference Guide  develop.714915d50b,2024/12/07
The Integrative Modeling Platform
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::bff::AVNetworkRestraint, 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::ParticlesDummyRestraint, IMP::em2d::PCAFitRestraint, IMP::em2d::RigidBodiesImageFitRestraint, IMP::em::DensityFillingRestraint, IMP::em::EnvelopeFitRestraint, IMP::em::EnvelopePenetrationRestraint, IMP::em::FitRestraint, IMP::em::FitRestraintBayesEM3D, 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::ResidueProteinProximityRestraint, 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::OverallPositionRestraint, IMP::npc::PerinuclearVolumeLocationRestraint, IMP::npc::PoreSideVolumeLocationRestraint, IMP::npc::ProteinChainRestraint, IMP::npc::ProteinContactRestraint, IMP::npc::ProteinProximityRestraint, IMP::npc::XAxialPositionLowerRestraint, IMP::npc::XAxialPositionRestraint, IMP::npc::XAxialPositionUpperRestraint, 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::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:

Note
When logging is VERBOSE, restraints should print enough information in evaluate to reproduce 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 56 of file Restraint.h.

Public Member Functions

 Restraint (Model *m, std::string name)
 Create a restraint and register it with the model. More...
 
 Restraint ()
 Default constructor. More...
 
Restraintcreate_current_decomposition () const
 Decompose this restraint into constituent terms for the current conf. More...
 
Restraintcreate_decomposition () const
 Decompose this restraint into constituent terms. More...
 
virtual ScoringFunctioncreate_scoring_function (double weight=1.0, double max=NO_MAX) const
 Create a scoring function with only this restraint. More...
 
virtual RestraintInfoget_dynamic_info () const
 
bool get_is_aggregate () const
 Return whether this restraint wraps a number of other restraints. More...
 
double get_last_last_score () const
 Get the unweighted score from the last-but-one time it was evaluated. More...
 
virtual double get_last_score () const
 
double get_score () const
 
virtual RestraintInfoget_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...
 
Modelget_model () const
 
ModelObjectsTemp get_outputs () const
 
const ScoreStatesTempget_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
 
virtual void do_add_score_and_derivatives_moved (ScoreAccumulator sa, const ParticleIndexes &moved_pis, const ParticleIndexes &reset_pis) const
 
virtual Restraints do_create_current_decomposition () const
 
virtual Restraints do_create_decomposition () const
 
ModelObjectsTemp do_get_outputs () const override
 
- 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 ()
 

Protected Attributes

bool is_aggregate_
 

Evaluation convenience methods

These are convenience methods to get the score of just this restraint; each just calls the equivalent method in the ScoringFunction class.

double evaluate (bool calc_derivs) const
 
double evaluate_moved (bool calc_derivs, const ParticleIndexes &moved_pis, const ParticleIndexes &reset_pis) const
 
double evaluate_moved_if_below (bool calc_derivatives, const ParticleIndexes &moved_pis, const ParticleIndexes &reset_pis, double max) const
 
double evaluate_moved_if_good (bool calc_derivatives, const ParticleIndexes &moved_pis, const ParticleIndexes &reset_pis) const
 
double evaluate_if_good (bool calc_derivatives) const
 
double evaluate_if_below (bool calc_derivatives, double max) const
 

Evaluation implementation

These methods are 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.

Note
These functions probably should be called do_evaluate, but were grandfathered in.
Although the returned score is unweighted, the DerivativeAccumulator passed in should be properly weighted.
virtual double unprotected_evaluate (DerivativeAccumulator *da) const
 Return the unweighted score for the restraint. More...
 
virtual double unprotected_evaluate_moved (DerivativeAccumulator *da, const ParticleIndexes &moved_pis, const ParticleIndexes &reset_pis) const
 Return the unweighted score, taking moving particles into account. More...
 
virtual double unprotected_evaluate_if_good (DerivativeAccumulator *da, double max) const
 
virtual double unprotected_evaluate_if_below (DerivativeAccumulator *da, double max) const
 The function calling this will treat any score >= max as bad. More...
 
virtual double unprotected_evaluate_moved_if_below (DerivativeAccumulator *da, const ParticleIndexes &moved_pis, const ParticleIndexes &reset_pis, double max) const
 
virtual double unprotected_evaluate_moved_if_good (DerivativeAccumulator *da, const ParticleIndexes &moved_pis, const ParticleIndexes &reset_pis, double max) const
 

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.

IMP::Restraint::Restraint ( )

Default constructor.

Default-constructed restraints cannot be evaluated.

Member Function Documentation

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 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 315 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 305 of file Restraint.h.

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

No outputs.

Implements IMP::ModelObject.

Definition at line 326 of file Restraint.h.

double IMP::Restraint::evaluate ( bool  calc_derivs) const
double IMP::Restraint::evaluate_if_below ( bool  calc_derivatives,
double  max 
) const
See Also
ScoringFunction::evaluate_if_below
double IMP::Restraint::evaluate_if_good ( bool  calc_derivatives) const
See Also
ScoringFunction::evaluate_if_good
double IMP::Restraint::evaluate_moved ( bool  calc_derivs,
const ParticleIndexes moved_pis,
const ParticleIndexes reset_pis 
) const
double IMP::Restraint::evaluate_moved_if_below ( bool  calc_derivatives,
const ParticleIndexes moved_pis,
const ParticleIndexes reset_pis,
double  max 
) const
See Also
ScoringFunction::evaluate_moved_if_below
double IMP::Restraint::evaluate_moved_if_good ( bool  calc_derivatives,
const ParticleIndexes moved_pis,
const ParticleIndexes reset_pis 
) const
See Also
ScoringFunction::evaluate_moved_if_good
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 190 of file Restraint.h.

bool IMP::Restraint::get_is_aggregate ( ) const

Return whether this restraint wraps a number of other restraints.

Definition at line 291 of file Restraint.h.

double IMP::Restraint::get_last_last_score ( ) const

Get the unweighted score from the last-but-one time it was evaluated.

See Also
get_last_score

Definition at line 288 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 283 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::npc::OverallPositionRestraint, IMP::npc::XAxialPositionUpperRestraint, IMP::npc::XAxialPositionLowerRestraint, IMP::npc::XAxialPositionRestraint, IMP::npc::MembraneExclusionRestraint, IMP::npc::MembraneSurfaceLocationConditionalRestraint, IMP::npc::MembraneSurfaceLocationRestraint, IMP::npc::XYRadialPositionUpperRestraint, IMP::npc::XYRadialPositionLowerRestraint, IMP::npc::XYRadialPositionRestraint, IMP::npc::YAxialPositionUpperRestraint, IMP::npc::YAxialPositionLowerRestraint, IMP::npc::YAxialPositionRestraint, IMP::isd::CrossLinkMSRestraint, IMP::npc::ZAxialPositionUpperRestraint, IMP::bayesianem::GaussianEMRestraint, IMP::isd::GaussianEMRestraint, IMP::npc::ZAxialPositionLowerRestraint, IMP::em2d::PCAFitRestraint, IMP::saxs::Restraint, IMP::npc::ZAxialPositionRestraint, IMP::pmi::CrossLinkRestraintSet, and IMP::isd::UniformPrior.

Definition at line 178 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 296 of file Restraint.h.

virtual double IMP::Restraint::unprotected_evaluate ( DerivativeAccumulator da) const
virtual

Return the unweighted score for the restraint.

Reimplemented in IMP::npc::OverallPositionRestraint, IMP::npc::XAxialPositionUpperRestraint, IMP::npc::XAxialPositionLowerRestraint, IMP::npc::XAxialPositionRestraint, IMP::npc::ProteinProximityRestraint, IMP::npc::AssemblySymmetryByDihedralRestraint, IMP::npc::AssemblySymmetryByDistanceRestraint, IMP::npc::PerinuclearVolumeLocationRestraint, IMP::npc::PoreSideVolumeLocationRestraint, IMP::npc::MembraneExclusionRestraint, IMP::npc::MembraneSurfaceLocationConditionalRestraint, IMP::npc::MembraneSurfaceLocationRestraint, IMP::npc::ProteinChainRestraint, IMP::npc::ProteinContactRestraint, IMP::npc::XYRadialPositionUpperRestraint, IMP::npc::XYRadialPositionLowerRestraint, IMP::npc::XYRadialPositionRestraint, IMP::npc::YAxialPositionUpperRestraint, IMP::npc::YAxialPositionLowerRestraint, IMP::npc::YAxialPositionRestraint, IMP::bff::AVNetworkRestraint, IMP::isd::CrossLinkMSRestraint, IMP::isd::GaussianAnchorEMRestraint, IMP::npc::ZAxialPositionUpperRestraint, IMP::bayesianem::GaussianEMRestraint, IMP::em2d::Em2DRestraint, IMP::isd::CysteineCrossLinkRestraint, IMP::isd::FretRestraint, IMP::isd::GaussianEMRestraint, IMP::npc::ZAxialPositionLowerRestraint, IMP::core::ExcludedVolumeRestraint, IMP::core::MSConnectivityRestraint, IMP::core::RigidBodyUmbrella, IMP::pmi::CompositeRestraint, IMP::isd::TALOSRestraint, IMP::em2d::ParticlesDummyRestraint, IMP::multifit::ComplementarityRestraint, IMP::isd::LognormalAmbiguousRestraint, IMP::isd::StudentTRestraint, IMP::npc::CompositeRestraint, IMP::isd::GaussianProcessInterpolationRestraint, IMP::spb::EM2DRestraint, IMP::atom::CHARMMStereochemistryRestraint, IMP::em::FitRestraint, IMP::container::PairsRestraint, IMP::container::QuadsRestraint, IMP::container::SingletonsRestraint, IMP::container::TripletsRestraint, IMP::RestraintSet, IMP::isd::AtomicCrossLinkMSRestraint, IMP::isd::ResidueProteinProximityRestraint, IMP::isd::MarginalNOERestraint, IMP::isd::NormalSigmaPCRestraint, IMP::saxs::Restraint, IMP::core::ConnectivityRestraint, IMP::em2d::PCAFitRestraint, IMP::isd::GaussianRestraint, IMP::isd::LognormalRestraint, IMP::core::PairRestraint, IMP::core::QuadRestraint, IMP::core::SingletonRestraint, IMP::core::TripletRestraint, IMP::em2d::DummyRestraint, IMP::isd::MarginalHBondRestraint, IMP::npc::ZAxialPositionRestraint, IMP::atom::CADihedralRestraint, IMP::isd::AmbiguousNOERestraint, IMP::isd::AmbiguousRestraint, IMP::em::PCAFitRestraint, IMP::core::MultipleBinormalRestraint, IMP::em::FitRestraintBayesEM3D, IMP::example::ExampleComplexRestraint, IMP::multifit::DummyRestraint, IMP::pmi::MembraneRestraint, IMP::em::EnvelopeFitRestraint, IMP::core::DiameterRestraint, IMP::atom::CAAngleRestraint, IMP::em::EnvelopePenetrationRestraint, IMP::isd::LogWrapper, IMP::isd::NOERestraint, IMP::multifit::WeightedExcludedVolumeRestraint, IMP::em::DensityFillingRestraint, IMP::isd::UniformPrior, IMP::spb::UniformBoundedRestraint, IMP::core::ConstantRestraint, IMP::container::MinimumPairRestraint, IMP::container::MinimumQuadRestraint, IMP::container::MinimumSingletonRestraint, IMP::container::MinimumTripletRestraint, IMP::spb::DistanceTerminiRestraint, IMP::saxs::RadiusOfGyrationRestraint, IMP::core::DihedralRestraint, IMP::isd::JeffreysRestraint, IMP::multifit::RadiusOfGyrationRestraint, IMP::atom::HelixRestraint, IMP::spb::TwoStateGoModelRestraint, IMP::core::MinimumRestraint, IMP::isd::vonMisesKappaJeffreysRestraint, IMP::isd::vonMisesKappaConjugateRestraint, IMP::spb::DiameterRgyrRestraint, IMP::atom::EzRestraint, IMP::isd::GammaPrior, IMP::core::VolumeRestraint, IMP::isd::ISDRestraint, and IMP::isd::WeightRestraint.

virtual double IMP::Restraint::unprotected_evaluate_if_below ( DerivativeAccumulator da,
double  max 
) const
virtual

The function calling this will treat any score >= max as bad.

Definition at line 146 of file Restraint.h.

virtual double IMP::Restraint::unprotected_evaluate_if_good ( DerivativeAccumulator da,
double  max 
) const
virtual

The function calling this will treat any score >= get_maximum_score as bad and so can return early as soon as such a situation is found.

Definition at line 139 of file Restraint.h.

virtual double IMP::Restraint::unprotected_evaluate_moved ( DerivativeAccumulator da,
const ParticleIndexes moved_pis,
const ParticleIndexes reset_pis 
) const
virtual

Return the unweighted score, taking moving particles into account.

By default this just calls regular unprotected_evaluate(), but may be overridden by restraints to be more efficient, e.g. by skipping terms that involve unchanged particles.

Parameters
daObject to accumulate derivatives, or nullptr.
moved_pisParticles that have moved since the last scoring function evaluation.
reset_pisParticles that have moved, but back to the positions they had at the last-but-one evaluation (e.g. due to a rejected Monte Carlo move).
Returns
Current score.

Reimplemented in IMP::isd::LogWrapper.

Definition at line 129 of file Restraint.h.


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