IMP Reference Guide
develop.714915d50b,2024/12/07
The Integrative Modeling Platform
|
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.
A restraint is a term in an IMP
ScoringFunction.
To implement a new restraint, just implement the two methods:
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... | |
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 |
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 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 |
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.
| |
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.
| |
double | get_maximum_score () const |
void | set_maximum_score (double s) |
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.
Restraint* IMP::Restraint::create_current_decomposition | ( | ) | const |
Decompose this restraint into constituent terms for the current conf.
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 |
Create a scoring function with only this restraint.
|
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.
|
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.
|
overrideprotectedvirtual |
double IMP::Restraint::evaluate | ( | bool | calc_derivs | ) | const |
double IMP::Restraint::evaluate_if_below | ( | bool | calc_derivatives, |
double | max | ||
) | const |
double IMP::Restraint::evaluate_if_good | ( | bool | calc_derivatives | ) | const |
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 |
double IMP::Restraint::evaluate_moved_if_good | ( | bool | calc_derivatives, |
const ParticleIndexes & | moved_pis, | ||
const ParticleIndexes & | reset_pis | ||
) | const |
|
virtual |
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.
Definition at line 288 of file Restraint.h.
|
virtual |
Return the (unweighted) score for this restraint last time it was evaluated.
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 |
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 |
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 |
The function calling this will treat any score >= max as bad.
Definition at line 146 of file Restraint.h.
|
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 |
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.
da | Object to accumulate derivatives, or nullptr. |
moved_pis | Particles that have moved since the last scoring function evaluation. |
reset_pis | Particles 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). |
Reimplemented in IMP::isd::LogWrapper.
Definition at line 129 of file Restraint.h.