BALL::EnergyMinimizer Class Reference
[Energy Minimizer]

#include <BALL/MOLMEC/MINIMIZATION/energyMinimizer.h>

Inheritance diagram for BALL::EnergyMinimizer:

Classes
struct	Default
struct	Option
Public Member Functions
bool	operator== (const EnergyMinimizer &energy_minimizer)
Constructors and Destructors

	EnergyMinimizer ()
	EnergyMinimizer (ForceField &force_field)
	EnergyMinimizer (ForceField &force_field, const Options &options)
	EnergyMinimizer (const EnergyMinimizer &energy_minimizer)
virtual	~EnergyMinimizer ()
Assignments

const EnergyMinimizer &	operator= (const EnergyMinimizer &energy_minimizer)
Debugging and Diagnostics

bool	isValid () const
Setup methods

bool	setup (ForceField &force_field)
bool	setup (ForceField &force_field, SnapShotManager *ssm)
bool	setup (ForceField &force_field, SnapShotManager *ssm, const Options &options)
bool	setup (ForceField &force_field, const Options &options)
virtual bool	specificSetup ()
Accessors

virtual bool	isConverged () const
virtual double	findStep ()
virtual void	updateDirection ()
virtual double	updateEnergy ()
virtual void	updateForces ()
void	storeGradientEnergy ()
virtual void	printEnergy () const
virtual void	takeSnapShot () const
virtual void	finishIteration ()
Size	getNumberOfIterations () const
Gradient &	getDirection ()
Gradient &	getGradient ()
Gradient &	getInitialGradient ()
double	getEnergy () const
double &	getEnergy ()
double	getInitialEnergy () const
double &	getInitialEnergy ()
void	setNumberOfIterations (Size number_of_iterations)
Size	getMaxNumberOfIterations () const
void	setMaxNumberOfIterations (Size number_of_iterations)
void	setMaxSameEnergy (Size number)
Size	getMaxSameEnergy () const
void	setEnergyOutputFrequency (Size energy_output_frequency)
Size	getEnergyOutputFrequency () const
void	setEnergyDifferenceBound (float energy_difference_bound)
float	getEnergyDifferenceBound () const
void	setMaxGradient (float max_gradient)
float	getMaxGradient () const
void	setMaximumDisplacement (float maximum_displacement)
float	getMaximumDisplacement () const
void	setSnapShotFrequency (Size snapshot_frequency)
Size	getSnapShotFrequency () const
ForceField *	getForceField ()
Size	getForceUpdateCounter () const
Size	getEnergyUpdateCounter () const
virtual bool	minimize (Size steps=0, bool resume=false)
void	enableEnergyAbortCondition (bool state)
bool	energyAbortConditionEnabled () const
	Query if the MDSimulation aborts if the Energy is greater than abort_energy_.
void	setEnergyToAbort (float value)
float	getEnergyToAbort () const
bool	wasAborted () const
Public Attributes
Public Attributes

Options	options
Protected Attributes
Protected Attributes

Gradient	initial_grad_
Gradient	current_grad_
double	initial_energy_
double	current_energy_
Gradient	old_grad_
double	old_energy_
Gradient	direction_
bool	valid_
SnapShotManager *	snapshot_
ForceField *	force_field_
Size	number_of_iterations_
Size	maximal_number_of_iterations_
Size	energy_output_frequency_
Size	snapshot_frequency_
double	energy_difference_bound_
double	max_gradient_
Size	max_same_energy_
Size	same_energy_counter_
float	maximum_displacement_
Size	force_update_counter_
Size	energy_update_counter_
float	cutlo_
double	step_
bool	abort_by_energy_enabled_
float	abort_energy_
bool	aborted_

Detailed Description

EnergyMinimizer. Base class for all minimizer for geometry optimization.

Definition at line 29 of file energyMinimizer.h.

Constructor & Destructor Documentation

BALL::EnergyMinimizer::EnergyMinimizer ( )

Default constructor.

BALL::EnergyMinimizer::EnergyMinimizer ( ForceField & force_field )

Constructor.

BALL::EnergyMinimizer::EnergyMinimizer	(	ForceField &	force_field,
		const Options &	options
	)

Constructor.

BALL::EnergyMinimizer::EnergyMinimizer ( const EnergyMinimizer & energy_minimizer )

Copy constructor

virtual BALL::EnergyMinimizer::~EnergyMinimizer ( ) [virtual]

Destructor.

Member Function Documentation

void BALL::EnergyMinimizer::enableEnergyAbortCondition ( bool state )

Specify if the MDSimulation aborts if the Energy is greater than abort_energy_

bool BALL::EnergyMinimizer::energyAbortConditionEnabled ( ) const

Query if the MDSimulation aborts if the Energy is greater than abort_energy_.

virtual double BALL::EnergyMinimizer::findStep ( ) [virtual]

Calculate the next step. This method is implemented in each minimizer class and tries to determine the next step to be taken. It typically performs a line search. The value returned is usually the step length with respect to the current direction.

Returns:: -1 to indicate failure

Reimplemented in BALL::ConjugateGradientMinimizer, BALL::ShiftedLVMMMinimizer, BALL::SteepestDescentMinimizer, and BALL::StrangLBFGSMinimizer.

virtual void BALL::EnergyMinimizer::finishIteration ( ) [virtual]

Finishing step for this iteration. This method should be called at the end of the main iteration loop implemented in minimize . It takes over some administrative stuff:

increment the iteration counter number_of_iterations_
call takeSnapShot if necessary
call printEnergy if necessary
call ForceField::update if necessary (to rebuild the pair lists!)
update the same_energy_counter_ tested in isConverged

This method should be overwritten only in rare cases. Even then, the programmer should make sure to call EnergyMinimizer::finishIteration or has to take care of the above items himself.

All derived classes should call this method at the end of the minimize main loop. Otherwise strange things might happen.

See also:: minimize

Gradient& BALL::EnergyMinimizer::getDirection ( )

Return a reference to the current search direction

double& BALL::EnergyMinimizer::getEnergy ( )

Return a reference to the current energy

double BALL::EnergyMinimizer::getEnergy ( ) const

Return the current energy

float BALL::EnergyMinimizer::getEnergyDifferenceBound ( ) const

Get the energy difference bound

Size BALL::EnergyMinimizer::getEnergyOutputFrequency ( ) const

Get the energy ouput frequency

float BALL::EnergyMinimizer::getEnergyToAbort ( ) const

Size BALL::EnergyMinimizer::getEnergyUpdateCounter ( ) const

Return the number of energy updates since the start of the minimization.

ForceField* BALL::EnergyMinimizer::getForceField ( )

Return the force field of the energy minimizer

Size BALL::EnergyMinimizer::getForceUpdateCounter ( ) const

Return the number of force updates since the start of the minimization.

Gradient& BALL::EnergyMinimizer::getGradient ( )

Return a reference to the current gradient

double& BALL::EnergyMinimizer::getInitialEnergy ( )

Return a mutable reference to the initial energy

double BALL::EnergyMinimizer::getInitialEnergy ( ) const

Return the initial energy

Gradient& BALL::EnergyMinimizer::getInitialGradient ( )

Return a reference to the initial gradient

float BALL::EnergyMinimizer::getMaxGradient ( ) const

Get the maximum RMS gradient (first convergence criterion). The gradient unit of the gradient is kJ/(mol ).

float BALL::EnergyMinimizer::getMaximumDisplacement ( ) const

Get the maximum displacement value

Size BALL::EnergyMinimizer::getMaxNumberOfIterations ( ) const

Get the maximum number of iterations

Size BALL::EnergyMinimizer::getMaxSameEnergy ( ) const

Get the maximum number of iterations allowed with equal energy (second convergence criterion)

Size BALL::EnergyMinimizer::getNumberOfIterations ( ) const

Return the number of iterations performed.

Size BALL::EnergyMinimizer::getSnapShotFrequency ( ) const

Get the snapshot output frequency

virtual bool BALL::EnergyMinimizer::isConverged ( ) const [virtual]

Implements the convergence criterion. If the convergence criterion is fulfilled, this method returns true. The convergence criterion is implemented as one of two conditions:

(1) {RMS gradient} is below max_rms_gradient_ (2) same_energy_counter_ is above max_same_energy_

If any of these conditions hold isConverged returns true. This method should be reimplemented in derived classes for a different convergence criterion.

bool BALL::EnergyMinimizer::isValid ( ) const

Is the energy minimizer valid : did the setup work?

virtual bool BALL::EnergyMinimizer::minimize	(	Size	steps = `0`,
		bool	resume = `false`
	)			`[virtual]`

Minimize the energy of the system bound to the force field. If a number of steps is given, the minimization is aborted after that number of steps, regardless of the number of steps given in the options (MAX_STEPS). Together with the resume option this feature is used to extract properties or visualize the results in the course of the minimization. If resume is set to true, the minimization continues with the former step width and settings.

Parameters:

	steps	maximum number of steps to be taken
	resume	true if the minimization is to be resumed with the previous settings

Returns:: bool - true if the minimization has converged

Reimplemented in BALL::ConjugateGradientMinimizer, BALL::ShiftedLVMMMinimizer, BALL::SteepestDescentMinimizer, and BALL::StrangLBFGSMinimizer.

const EnergyMinimizer& BALL::EnergyMinimizer::operator= ( const EnergyMinimizer & energy_minimizer )

Assignment operator

bool BALL::EnergyMinimizer::operator== ( const EnergyMinimizer & energy_minimizer )

Equality operator

virtual void BALL::EnergyMinimizer::printEnergy ( ) const [virtual]

Print the energy. This method is called by finishIteration after every energy_output_frequency_ steps. It prints the current RMS gradient and the current energy to Log .info().

See also:: setEnergyOutputFrequency; getEnergyOutputFrequency

void BALL::EnergyMinimizer::setEnergyDifferenceBound ( float energy_difference_bound )

Set the energy difference bound for convergence

void BALL::EnergyMinimizer::setEnergyOutputFrequency ( Size energy_output_frequency )

Set the energy output frequency

void BALL::EnergyMinimizer::setEnergyToAbort ( float value )

Set the value for the energy, that will result in aborting the minization, if it will be surpassed. Default value: 10^9.

void BALL::EnergyMinimizer::setMaxGradient ( float max_gradient )

Set the maximum RMS gradient (first convergence criterion). The gradient unit of the gradient is kJ/(mol ).

void BALL::EnergyMinimizer::setMaximumDisplacement ( float maximum_displacement )

Set the maximum displacement value. This is the maximum distance an atom may be moved by the minimizer in one iteration.

void BALL::EnergyMinimizer::setMaxNumberOfIterations ( Size number_of_iterations )

Set the maximum number of iterations

void BALL::EnergyMinimizer::setMaxSameEnergy ( Size number )

Set the maximum number of iterations allowed with equal energy (second convergence criterion)

void BALL::EnergyMinimizer::setNumberOfIterations ( Size number_of_iterations )

Set the number of iterations performed so far.

void BALL::EnergyMinimizer::setSnapShotFrequency ( Size snapshot_frequency )

Set the snapshot frequency

bool BALL::EnergyMinimizer::setup	(	ForceField &	force_field,
		const Options &	options
	)

Sets up the energy minimizer.

bool BALL::EnergyMinimizer::setup	(	ForceField &	force_field,
		SnapShotManager *	ssm,
		const Options &	options
	)

Sets up the energy minimizer.

bool BALL::EnergyMinimizer::setup	(	ForceField &	force_field,
		SnapShotManager *	ssm
	)

Sets up the energy minimizer.

bool BALL::EnergyMinimizer::setup ( ForceField & force_field )

Sets up the energy minimizer.

virtual bool BALL::EnergyMinimizer::specificSetup ( ) [virtual]

Specific setup

Reimplemented in BALL::ConjugateGradientMinimizer, BALL::ShiftedLVMMMinimizer, BALL::SteepestDescentMinimizer, and BALL::StrangLBFGSMinimizer.

void BALL::EnergyMinimizer::storeGradientEnergy ( )

Store the current energy and gradient. The current gradient and current energy is copied into initial energy and initial gradient. This is usually done at the start of an iteration.

virtual void BALL::EnergyMinimizer::takeSnapShot ( ) const [virtual]

Take a snapshot of the system. This method is called by finishIteration after every snapshot_frequency_ steps. It saves a SnapShot of the current atom coordinates to a SnapShotManager (if enabled).

See also:: setSnapShotFrequency; getSnapShotFrequency

virtual void BALL::EnergyMinimizer::updateDirection ( ) [virtual]

Update the search direction. This method is implemented by the derived classes to implement a method to determine a new search direction.

Reimplemented in BALL::ConjugateGradientMinimizer, BALL::ShiftedLVMMMinimizer, BALL::SteepestDescentMinimizer, and BALL::StrangLBFGSMinimizer.

virtual double BALL::EnergyMinimizer::updateEnergy ( ) [virtual]

Update energy. This method calls force_field_->updateEnergy() and stores the result in current_energy_.

virtual void BALL::EnergyMinimizer::updateForces ( ) [virtual]

Update forces and store them in current_grad_. This method calls force_field_->updateForces() and stores them in current_grad_ .

bool BALL::EnergyMinimizer::wasAborted ( ) const

Return true, if the minimization was aborted, e.g. because of strange energies or gradient.

Member Data Documentation

bool BALL::EnergyMinimizer::abort_by_energy_enabled_ [protected]

Definition at line 545 of file energyMinimizer.h.

float BALL::EnergyMinimizer::abort_energy_ [protected]

Definition at line 548 of file energyMinimizer.h.

bool BALL::EnergyMinimizer::aborted_ [protected]

Definition at line 551 of file energyMinimizer.h.

double BALL::EnergyMinimizer::current_energy_ [protected]

The current energy.

Definition at line 457 of file energyMinimizer.h.

Gradient BALL::EnergyMinimizer::current_grad_ [protected]

The current gradient.

Definition at line 449 of file energyMinimizer.h.

float BALL::EnergyMinimizer::cutlo_ [protected]

Numerical lower bound: we don't want to compute the reciprocal of a number which is lower than 'cutlo_'.

Definition at line 537 of file energyMinimizer.h.

Gradient BALL::EnergyMinimizer::direction_ [protected]

The current search direction

Definition at line 469 of file energyMinimizer.h.

double BALL::EnergyMinimizer::energy_difference_bound_ [protected]

If the energy difference (before and after an iteration) is smaller than this bound, the minimization procedure stops.

Definition at line 504 of file energyMinimizer.h.

Size BALL::EnergyMinimizer::energy_output_frequency_ [protected]

Frequency of energy output

Definition at line 495 of file energyMinimizer.h.

Size BALL::EnergyMinimizer::energy_update_counter_ [protected]

Internal counter: how often is an energy update done. Measure for the speed of minimization.

Definition at line 532 of file energyMinimizer.h.

ForceField* BALL::EnergyMinimizer::force_field_ [protected]

The force field bound to the energy minimizer. Among other data the force field contains the molecular system whose energy will be minimized by the energy minimizer.

Definition at line 483 of file energyMinimizer.h.

Size BALL::EnergyMinimizer::force_update_counter_ [protected]

Internal counter: how often is a force update done. Measure for the speed of minimization.

Definition at line 527 of file energyMinimizer.h.

double BALL::EnergyMinimizer::initial_energy_ [protected]

The energy at the beginning of the current minimization step.

Definition at line 453 of file energyMinimizer.h.

Gradient BALL::EnergyMinimizer::initial_grad_ [protected]

The gradient at the beginning of the current minimization step.

Definition at line 445 of file energyMinimizer.h.

double BALL::EnergyMinimizer::max_gradient_ [protected]

The maximum RMS gradient tolerated (first convergence criterion)