base class for the energy method hierarchy More...

#include <EnergyMethod.hh>

Inheritance diagram for core::scoring::methods::EnergyMethod:

Public Types
typedef utility::VirtualBase	parent

Public Member Functions
	EnergyMethod (EnergyMethodCreatorOP creator)
	Constructor with EnergyMethodCreator, which lists the score types that this energy method is responsible for. More...

virtual EnergyMethodOP	clone () const =0

virtual void	setup_for_packing (pose::Pose &, utility::vector1< bool > const &, utility::vector1< bool > const &) const
	if an energy method needs to cache data in the Energies object, before packing begins, then it does so during this function. The packer must ensure this function is called. The default behavior is to do nothing. More...

virtual void	setup_for_packing_with_rotsets (pose::Pose &pose, pack_basic::RotamerSetsBaseOP const &rotsets, ScoreFunction const &sfxn) const
	if an energy method needs to cache data in the Energies object, before packing begins and requires access to the RotamerSets object, then it does so during this function. The default behavior is to do nothing. More...

virtual void	prepare_rotamers_for_packing (pose::Pose const &, conformation::RotamerSetBase &) const
	If an energy method needs to cache data in a packing::RotamerSet object before rotamer energies are calculated, it does so during this function. The packer must ensure this function is called. The default behavior is to do nothing. More...

virtual void	update_residue_for_packing (pose::Pose &, Size resid) const
	If the pose changes in the middle of a packing (as happens in rotamer trials) and if an energy method needs to cache data in the pose that corresponds to its current state, then the method must update that data when this function is called. The packer must ensure this function gets called. The default behavior is to do nothing. More...

virtual void	setup_for_scoring (pose::Pose &, ScoreFunction const &) const
	if an energy method needs to cache something in the pose (e.g. in pose.energies()), before scoring begins, it must do so in this method. All long range energy functions must initialize their LREnergyContainers before scoring begins. The default is to do nothing. More...

virtual bool	requires_a_setup_for_scoring_for_residue_opportunity_during_regular_scoring (pose::Pose const &pose) const
	Does this EnergyMethod require the opportunity to examine the residue before (regular) scoring begins? Not all energy methods would. The ScoreFunction will not ask energy methods to examine residues that are uninterested in doing so. The default implmentation of this function returns false. More...

virtual void	setup_for_scoring_for_residue (conformation::Residue const &rsd, pose::Pose const &pose, ScoreFunction const &sfxn, basic::datacache::BasicDataCache &residue_data_cache) const
	Do any setup work before scoring, caching any slow-to-compute data that will be used during energy evaluation inside of the input Residue object's data cache. (The Residue on the whole is given as a constant reference, but non-constant access to its data cache is granted.) More...

virtual void	setup_for_minimizing (pose::Pose &, ScoreFunction const &, kinematics::MinimizerMapBase const &) const
	Called at the beginning of atom tree minimization, this method allows the derived class the opportunity to initialize pertinent data that will be used during minimization. During minimzation, the chemical structure of the pose is constant, so assumptions on the number of atoms per residue and their identities are safe so long as the pose's Energies object's "use_nblist()" method returns true. More...

virtual void	finalize_after_minimizing (pose::Pose &pose) const
	Called after minimization, allowing a derived class to do some teardown steps. More...

virtual void	setup_for_derivatives (pose::Pose &pose, ScoreFunction const &sfxn) const
	Called immediately before atom- and DOF-derivatives are calculated allowing the derived class a chance to prepare for future calls. More...

virtual void	finalize_after_derivatives (pose::Pose &, ScoreFunction const &) const
	called at the end of derivatives evaluation More...

virtual bool	minimize_in_whole_structure_context (pose::Pose const &) const
	Should this EnergyMethod have score and derivative evaluation evaluated only in the context of the whole Pose, or can it be included in a decomposed manner for a residue or a set of residue-pairs that are not part of the Pose that's serving as their context? The default method implemented in the base class returns true in order to grandfather in EnergyMethods that have not had their derivatives changed to take advantage of the new derivative-evaluation machinery. Methods that return "true" will not have their residue-energy(-ext) / residue-pair-energy(-ext) methods invoked by the ScoreFunction during its traversal of the MinimizationGraph, and instead will be asked to perform all their work during finalize_total_energies(). Similarly, they will be expected to perform all their work during eval_atom_deriv() instead of during the ScoreFunction's traversal of the MinimizationGraph for derivative evaluation. IMPORTANT: Methods that return "true" cannot be included in RTMin. More...

virtual bool	defines_high_order_terms (pose::Pose const &) const
	Should this EnergyMethod have score and derivative evaluation evaluated both in the context of the whole Pose and in the context of residue or residue-pairs? This covers scoring terms like env-smooth wherein the CBeta's get derivatives for increasing the neighbor counts for surrounding residues, and terms like constraints, which are definable on arbitrary number of residues (e.g. more than 2); both of these terms could be used in RTMin, and both should use the residue and residue-pair evaluation scheme with the MinimizationGraph for the majority of the work they do. (Now, high-order constraints (3-body or above) will not be properly evaluated within RTMin.). The default implementation returns "false". More...

virtual void	eval_atom_derivative (id::AtomID const &id, pose::Pose const &pose, kinematics::DomainMap const &domain_map, ScoreFunction const &sfxn, EnergyMap const &emap, Vector &F1, Vector &F2) const
	Evaluate the XYZ derivative for an atom in the pose. Called during the atomtree derivative calculation, atom_tree_minimize.cc, through the ScoreFunction::eval_atom_derivative intermediary. F1 and F2 should not zeroed, rather, this class should accumulate its contribution from this atom's XYZ derivative. More...

virtual void	finalize_total_energy (pose::Pose &pose, ScoreFunction const &sfxn, EnergyMap &total_energy) const
	called by the ScoreFunction at the end of energy evaluation. The derived class has the opportunity to accumulate a score into the pose's total_energy EnergyMap. WholeStructure energies operate within this method; any method using a NeighborList during minimization would also operate within this function call. More...

ScoreTypes const &	score_types () const
	Returns the score types that this energy method computes. More...

virtual EnergyMethodType	method_type () const =0
	Return one of the 7 kinds of energy methods that exist: e.g. context-dependent-one-body vs whole-structure. More...

virtual void	indicate_required_context_graphs (utility::vector1< bool > &context_graphs_required) const =0
	Indicate in the context-graphs-required list which context-graphs this energy method requires that the Pose maintain when doing neighbor evaluation. Context graphs are allowed. More...

virtual core::Size	version () const =0
	Return the version of the energy method. More...

virtual void	show_additional_info (std::ostream &, pose::Pose &, bool) const
	show additional information of the energy method More...

virtual bool	energy_method_provides_citation_info () const
	Does this energy method provide information about how to cite it? More...

virtual utility::vector1 < basic::citation_manager::CitationCollectionCOP >	provide_citation_info () const
	Provide the citation. More...

virtual bool	energy_method_is_unpublished () const
	Does this energy method indicate that it is unpublished (and, by extension, that the author should be included in publications resulting from it)? More...

virtual utility::vector1 < basic::citation_manager::UnpublishedModuleInfoCOP >	provide_authorship_info_for_unpublished () const
	Provide a list of authors and their e-mail addresses, as strings. More...

Protected Member Functions
void	set_score_types (EnergyMethodCreatorOP creator)
	Override the entirety of the score types list if they were initialized incorrectly in a parent's constructor. More...

Private Attributes
ScoreTypes	score_types_

Detailed Description

base class for the energy method hierarchy

Member Typedef Documentation

typedef utility::VirtualBase core::scoring::methods::EnergyMethod::parent

Constructor & Destructor Documentation

core::scoring::methods::EnergyMethod::EnergyMethod ( EnergyMethodCreatorOP creator )

Constructor with EnergyMethodCreator, which lists the score types that this energy method is responsible for.

Member Function Documentation

virtual EnergyMethodOP core::scoring::methods::EnergyMethod::clone ( ) const

pure virtual

Referenced by core::scoring::ScoreFunction::add_extra_method().

bool core::scoring::methods::EnergyMethod::defines_high_order_terms ( pose::Pose const & ) const

virtual

Should this EnergyMethod have score and derivative evaluation evaluated both in the context of the whole Pose and in the context of residue or residue-pairs? This covers scoring terms like env-smooth wherein the CBeta's get derivatives for increasing the neighbor counts for surrounding residues, and terms like constraints, which are definable on arbitrary number of residues (e.g. more than 2); both of these terms could be used in RTMin, and both should use the residue and residue-pair evaluation scheme with the MinimizationGraph for the majority of the work they do. (Now, high-order constraints (3-body or above) will not be properly evaluated within RTMin.). The default implementation returns "false".

Reimplemented in core::scoring::constraints::ConstraintsEnergy.

bool core::scoring::methods::EnergyMethod::energy_method_is_unpublished ( ) const

virtual

Does this energy method indicate that it is unpublished (and, by extension, that the author should be included in publications resulting from it)?

Defaults to false. Derived classes may override this to provide authorship info. If set to true, the provide_authorship_info_for_unpublished() override should also be provided.

Author: Vikram K. Mulligan (vmull.nosp@m.igan.nosp@m.@flat.nosp@m.iron.nosp@m.insti.nosp@m.tute.nosp@m..org)

Reimplemented in core::pack::guidance_scoreterms::approximate_buried_unsat_penalty::ApproximateBuriedUnsatPenalty, core::pack::guidance_scoreterms::buried_unsat_penalty::BuriedUnsatPenalty, core::pack::guidance_scoreterms::hbnet_energy::HBNetEnergy, core::pack::guidance_scoreterms::voids_penalty_energy::VoidsPenaltyEnergy, and core::scoring::netcharge_energy::NetChargeEnergy.

bool core::scoring::methods::EnergyMethod::energy_method_provides_citation_info ( ) const

virtual

Does this energy method provide information about how to cite it?

Defaults to false. Derived classes may override this to provide citation info. If set to true, the provide_citation_info() override should also be provided.

Author: Vikram K. Mulligan (vmull.nosp@m.igan.nosp@m.@flat.nosp@m.iron.nosp@m.insti.nosp@m.tute.nosp@m..org)

Reimplemented in core::scoring::aa_composition_energy::AACompositionEnergy.

void core::scoring::methods::EnergyMethod::eval_atom_derivative	(	id::AtomID const &	id,
		pose::Pose const &	pose,
		kinematics::DomainMap const &	domain_map,
		ScoreFunction const &	sfxn,
		EnergyMap const &	emap,
		Vector &	F1,
		Vector &	F2
	)		const

virtual

Evaluate the XYZ derivative for an atom in the pose. Called during the atomtree derivative calculation, atom_tree_minimize.cc, through the ScoreFunction::eval_atom_derivative intermediary. F1 and F2 should not zeroed, rather, this class should accumulate its contribution from this atom's XYZ derivative.

The derivative scheme is based on that of Abe, Braun, Noguti and Go (1984) "Rapid Calculation of First and Second Derivatives of Conformational Energy with Respect to Dihedral Angles for Proteins. General Recurrent Equations" Computers & Chemistry 8(4) pp. 239-247. F1 and F2 correspond roughly to Fa and Ga, respectively, of equations 7a & 7b in that paper.

default implementation does not alter either the F1 or F2 vectors.

void core::scoring::methods::EnergyMethod::finalize_after_derivatives	(	pose::Pose &	,
		ScoreFunction const &
	)		const

virtual

called at the end of derivatives evaluation

default implementation noop

Reimplemented in core::scoring::dna::DNATorsionEnergy, and core::scoring::orbitals::OrbitalsScore.

void core::scoring::methods::EnergyMethod::finalize_after_minimizing ( pose::Pose & pose ) const

virtual

Called after minimization, allowing a derived class to do some teardown steps.

Base class function does nothing. Derived classes may override.

Author: Vikram K. Mulligan (vmull.nosp@m.ig@u.nosp@m.w.edu).

Reimplemented in core::pack::guidance_scoreterms::buried_unsat_penalty::BuriedUnsatPenalty, core::scoring::mhc_epitope_energy::MHCEpitopeEnergy, core::pack::guidance_scoreterms::approximate_buried_unsat_penalty::ApproximateBuriedUnsatPenalty, core::pack::guidance_scoreterms::hbnet_energy::HBNetEnergy, core::scoring::aa_composition_energy::AACompositionEnergy, core::pack::guidance_scoreterms::voids_penalty_energy::VoidsPenaltyEnergy, and core::scoring::util_methods::DumpTrajectoryEnergy.

void core::scoring::methods::EnergyMethod::finalize_total_energy	(	pose::Pose &	pose,
		ScoreFunction const &	sfxn,
		EnergyMap &	total_energy
	)		const

virtual

called by the ScoreFunction at the end of energy evaluation. The derived class has the opportunity to accumulate a score into the pose's total_energy EnergyMap. WholeStructure energies operate within this method; any method using a NeighborList during minimization would also operate within this function call.

called at the end of energy evaluation

virtual void core::scoring::methods::EnergyMethod::indicate_required_context_graphs ( utility::vector1< bool > & context_graphs_required ) const

pure virtual

Indicate in the context-graphs-required list which context-graphs this energy method requires that the Pose maintain when doing neighbor evaluation. Context graphs are allowed.

virtual EnergyMethodType core::scoring::methods::EnergyMethod::method_type ( ) const

pure virtual

Return one of the 7 kinds of energy methods that exist: e.g. context-dependent-one-body vs whole-structure.

Implemented in core::scoring::methods::ContextDependentTwoBodyEnergy, core::scoring::methods::ContextDependentOneBodyEnergy, core::scoring::methods::WholeStructureEnergy, core::scoring::methods::ContextIndependentOneBodyEnergy, core::scoring::methods::ContextIndependentTwoBodyEnergy, core::scoring::methods::ContextDependentLRTwoBodyEnergy, and core::scoring::methods::ContextIndependentLRTwoBodyEnergy.

bool core::scoring::methods::EnergyMethod::minimize_in_whole_structure_context ( pose::Pose const & ) const

virtual

Should this EnergyMethod have score and derivative evaluation evaluated only in the context of the whole Pose, or can it be included in a decomposed manner for a residue or a set of residue-pairs that are not part of the Pose that's serving as their context? The default method implemented in the base class returns true in order to grandfather in EnergyMethods that have not had their derivatives changed to take advantage of the new derivative-evaluation machinery. Methods that return "true" will not have their residue-energy(-ext) / residue-pair-energy(-ext) methods invoked by the ScoreFunction during its traversal of the MinimizationGraph, and instead will be asked to perform all their work during finalize_total_energies(). Similarly, they will be expected to perform all their work during eval_atom_deriv() instead of during the ScoreFunction's traversal of the MinimizationGraph for derivative evaluation. IMPORTANT: Methods that return "true" cannot be included in RTMin.

void core::scoring::methods::EnergyMethod::prepare_rotamers_for_packing	(	pose::Pose const &	,
		conformation::RotamerSetBase &
	)		const

virtual

If an energy method needs to cache data in a packing::RotamerSet object before rotamer energies are calculated, it does so during this function. The packer must ensure this function is called. The default behavior is to do nothing.

default implementation noop

utility::vector1< basic::citation_manager::UnpublishedModuleInfoCOP > core::scoring::methods::EnergyMethod::provide_authorship_info_for_unpublished ( ) const

virtual

Provide a list of authors and their e-mail addresses, as strings.

Returns: A list of pairs of (author, e-mail address). Empty list if not unpublished.

Author: Vikram K. Mulligan (vmull.nosp@m.igan.nosp@m.@flat.nosp@m.iron.nosp@m.insti.nosp@m.tute.nosp@m..org)

Reimplemented in core::pack::guidance_scoreterms::approximate_buried_unsat_penalty::ApproximateBuriedUnsatPenalty, core::pack::guidance_scoreterms::buried_unsat_penalty::BuriedUnsatPenalty, core::pack::guidance_scoreterms::hbnet_energy::HBNetEnergy, core::pack::guidance_scoreterms::voids_penalty_energy::VoidsPenaltyEnergy, and core::scoring::netcharge_energy::NetChargeEnergy.

utility::vector1< basic::citation_manager::CitationCollectionCOP > core::scoring::methods::EnergyMethod::provide_citation_info ( ) const

virtual

Provide the citation.

Returns: A vector of citation collections. This allows the energy method to provide citations for itself and for any modules that it invokes.

The default implementation of this function provides an empty vector. It may be overriden by energy methods wishing to provide citation information.

Author: Vikram K. Mulligan (vmull.nosp@m.igan.nosp@m.@flat.nosp@m.iron.nosp@m.insti.nosp@m.tute.nosp@m..org)

Reimplemented in core::scoring::aa_composition_energy::AACompositionEnergy.

bool core::scoring::methods::EnergyMethod::requires_a_setup_for_scoring_for_residue_opportunity_during_regular_scoring ( pose::Pose const & pose ) const

virtual

Does this EnergyMethod require the opportunity to examine the residue before (regular) scoring begins? Not all energy methods would. The ScoreFunction will not ask energy methods to examine residues that are uninterested in doing so. The default implmentation of this function returns false.

Reimplemented in core::scoring::lkball::LK_BallEnergy.

ScoreTypes const& core::scoring::methods::EnergyMethod::score_types ( ) const

inline

Returns the score types that this energy method computes.

References score_types_.

Referenced by core::scoring::ScoreFunction::add_extra_method(), core::scoring::methods::ShortRangeTwoBodyEnergy::evaluate_rotamer_background_energies(), core::scoring::methods::ShortRangeTwoBodyEnergy::evaluate_rotamer_pair_energies(), core::scoring::methods::OneBodyEnergy::setup_for_derivatives_for_residue(), and core::scoring::methods::TwoBodyEnergy::setup_for_derivatives_for_residue().

void core::scoring::methods::EnergyMethod::set_score_types ( EnergyMethodCreatorOP creator )

protected

Override the entirety of the score types list if they were initialized incorrectly in a parent's constructor.

References score_types_.

Referenced by core::scoring::elec::FA_ElecEnergyAroAll::FA_ElecEnergyAroAll(), core::scoring::elec::FA_ElecEnergyAroAro::FA_ElecEnergyAroAro(), and core::scoring::elec::RNA_FA_ElecEnergy::RNA_FA_ElecEnergy().

void core::scoring::methods::EnergyMethod::setup_for_derivatives	(	pose::Pose &	pose,
		ScoreFunction const &	sfxn
	)		const

virtual

Called immediately before atom- and DOF-derivatives are calculated allowing the derived class a chance to prepare for future calls.

default implementation noop

void core::scoring::methods::EnergyMethod::setup_for_minimizing	(	pose::Pose &	,
		ScoreFunction const &	,
		kinematics::MinimizerMapBase const &
	)		const

virtual

Called at the beginning of atom tree minimization, this method allows the derived class the opportunity to initialize pertinent data that will be used during minimization. During minimzation, the chemical structure of the pose is constant, so assumptions on the number of atoms per residue and their identities are safe so long as the pose's Energies object's "use_nblist()" method returns true.

default implementation noop

void core::scoring::methods::EnergyMethod::setup_for_packing	(	pose::Pose &	,
		utility::vector1< bool > const &	,
		utility::vector1< bool > const &
	)		const

virtual

if an energy method needs to cache data in the Energies object, before packing begins, then it does so during this function. The packer must ensure this function is called. The default behavior is to do nothing.

default implementation noop

void core::scoring::methods::EnergyMethod::setup_for_packing_with_rotsets	(	pose::Pose &	pose,
		pack_basic::RotamerSetsBaseOP const &	rotsets,
		ScoreFunction const &	sfxn
	)		const

virtual

if an energy method needs to cache data in the Energies object, before packing begins and requires access to the RotamerSets object, then it does so during this function. The default behavior is to do nothing.

The exact order of events when setting up for packing are as follows:

setup_for_packing() is called for all energy methods
rotamers are built
setup_for_packing_with_rotsets() is called for all energy methods
prepare_rotamers_for_packing() is called for all energy methods
The energy methods are asked to score all rotamers and rotamer pairs
Annealing
Remarks
The pose is specifically non-const here so that energy methods can store data in it

Note
: Used in ApproximateBuriedUnsatPenalty to pre-compute compatible rotamers

Reimplemented in core::pack::guidance_scoreterms::approximate_buried_unsat_penalty::ApproximateBuriedUnsatPenalty.

void core::scoring::methods::EnergyMethod::setup_for_scoring	(	pose::Pose &	,
		ScoreFunction const &
	)		const

virtual

if an energy method needs to cache something in the pose (e.g. in pose.energies()), before scoring begins, it must do so in this method. All long range energy functions must initialize their LREnergyContainers before scoring begins. The default is to do nothing.

void core::scoring::methods::EnergyMethod::setup_for_scoring_for_residue	(	conformation::Residue const &	rsd,
		pose::Pose const &	pose,
		ScoreFunction const &	sfxn,
		basic::datacache::BasicDataCache &	residue_data_cache
	)		const

virtual

Do any setup work before scoring, caching any slow-to-compute data that will be used during energy evaluation inside of the input Residue object's data cache. (The Residue on the whole is given as a constant reference, but non-constant access to its data cache is granted.)

Reimplemented in core::scoring::lkball::LK_BallEnergy.

void core::scoring::methods::EnergyMethod::show_additional_info	(	std::ostream &	,
		pose::Pose &	,
		bool
	)		const

virtual

show additional information of the energy method

Reimplemented in protocols::nmr::pre::PREEnergy, protocols::nmr::pcs::PCSEnergy, protocols::nmr::rdc::RDCEnergy, protocols::scoring::methods::pcs::PCS_Energy, protocols::scoring::methods::pcsTs1::PCS_Energy_Ts1, protocols::scoring::methods::pcsTs2::PCS_Energy_Ts2, protocols::scoring::methods::pcsTs3::PCS_Energy_Ts3, and protocols::scoring::methods::pcsTs4::PCS_Energy_Ts4.

void core::scoring::methods::EnergyMethod::update_residue_for_packing	(	pose::Pose &	,
		Size	resid
	)		const

virtual

If the pose changes in the middle of a packing (as happens in rotamer trials) and if an energy method needs to cache data in the pose that corresponds to its current state, then the method must update that data when this function is called. The packer must ensure this function gets called. The default behavior is to do nothing.

default implementation noop

Reimplemented in core::scoring::methods::MultipoleElecEnergy, core::scoring::methods::SASAEnergy, core::scoring::methods::VdWTinkerEnergy, core::scoring::methods::GenBornEnergy, core::scoring::methods::MMLJEnergyInter, core::scoring::methods::FACTSEnergy, core::scoring::methods::PairEnergy, and core::scoring::methods::CustomAtomPairEnergy.

virtual core::Size core::scoring::methods::EnergyMethod::version ( ) const

pure virtual

Return the version of the energy method.

Member Data Documentation

ScoreTypes core::scoring::methods::EnergyMethod::score_types_

private

Referenced by score_types(), and set_score_types().

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

src/core/scoring/methods/EnergyMethod.hh
src/core/scoring/methods/EnergyMethod.cc

Public Types

Public Member Functions

Protected Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation