#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_. More...

void	setEnergyToAbort (float value)

float	getEnergyToAbort () const

bool	wasAborted () const

Public Attributes
Public Attributes
Options	options

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::ShiftedLVMMMinimizer, BALL::ConjugateGradientMinimizer, BALL::StrangLBFGSMinimizer, and BALL::SteepestDescentMinimizer.

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 ( ) const

Return the current energy

double& BALL::EnergyMinimizer::getEnergy ( )

Return a reference to 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 ( ) const

Return the initial energy

double& BALL::EnergyMinimizer::getInitialEnergy ( )

Return a mutable reference to 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::ShiftedLVMMMinimizer, BALL::ConjugateGradientMinimizer, BALL::StrangLBFGSMinimizer, and BALL::SteepestDescentMinimizer.

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 )

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,
		SnapShotManager *	ssm,
		const Options &	options
	)

Sets up the energy minimizer.

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

Sets up the energy minimizer.

virtual bool BALL::EnergyMinimizer::specificSetup ( )

virtual

Specific setup

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

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::ShiftedLVMMMinimizer, BALL::ConjugateGradientMinimizer, BALL::StrangLBFGSMinimizer, and BALL::SteepestDescentMinimizer.

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)

Definition at line 508 of file energyMinimizer.h.

Size BALL::EnergyMinimizer::max_same_energy_

protected

The maximum number of iterations with same energy. When this number is reached, we assume the system to have converged (second convergence criterion)

Definition at line 514 of file energyMinimizer.h.

Size BALL::EnergyMinimizer::maximal_number_of_iterations_

protected

Maximum number of iterations

Definition at line 491 of file energyMinimizer.h.

float BALL::EnergyMinimizer::maximum_displacement_

protected

The maximal shift of an atom per iteration step (in Angstrom).

Definition at line 522 of file energyMinimizer.h.

Size BALL::EnergyMinimizer::number_of_iterations_

protected

The current iteration number

Definition at line 487 of file energyMinimizer.h.

double BALL::EnergyMinimizer::old_energy_

protected

The energy from the last step

Definition at line 465 of file energyMinimizer.h.

Gradient BALL::EnergyMinimizer::old_grad_

protected

The gradient from the last step

Definition at line 461 of file energyMinimizer.h.

Options BALL::EnergyMinimizer::options

Options

Definition at line 434 of file energyMinimizer.h.

Size BALL::EnergyMinimizer::same_energy_counter_

protected

A counter for the number of steps with a similar energy.

Definition at line 518 of file energyMinimizer.h.

SnapShotManager* BALL::EnergyMinimizer::snapshot_

protected

Pointer to a SnapShotManager for storing snapshots of the system

Definition at line 477 of file energyMinimizer.h.

Size BALL::EnergyMinimizer::snapshot_frequency_

protected

Frequency of atom coordinate ouput

Definition at line 499 of file energyMinimizer.h.

double BALL::EnergyMinimizer::step_

protected

The last step size (in respect of the length of the computed direction vector), so the length of the last step was $step\cdot|direction|$ .

Definition at line 542 of file energyMinimizer.h.

bool BALL::EnergyMinimizer::valid_

protected

The boolean variable indicates if the setup of the energy minimizer was successful

Definition at line 473 of file energyMinimizer.h.

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_

Classes

Public Member Functions

Public Attributes

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation