BALL  1.5.0
Classes | Public Member Functions | List of all members
BALL::EnergyMinimizer Class Reference

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

Inheritance diagram for BALL::EnergyMinimizer:
BALL::ConjugateGradientMinimizer BALL::ShiftedLVMMMinimizer BALL::SteepestDescentMinimizer BALL::StrangLBFGSMinimizer

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 EnergyMinimizeroperator= (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
 
GradientgetDirection ()
 
GradientgetGradient ()
 
GradientgetInitialGradient ()
 
double getEnergy () const
 
doublegetEnergy ()
 
double getInitialEnergy () const
 
doublegetInitialEnergy ()
 
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
 
ForceFieldgetForceField ()
 
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
 

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_
 
SnapShotManagersnapshot_
 
ForceFieldforce_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

◆ EnergyMinimizer() [1/4]

BALL::EnergyMinimizer::EnergyMinimizer ( )

Default constructor.

◆ EnergyMinimizer() [2/4]

BALL::EnergyMinimizer::EnergyMinimizer ( ForceField force_field)

Constructor.

◆ EnergyMinimizer() [3/4]

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

Constructor.

◆ EnergyMinimizer() [4/4]

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

Copy constructor

◆ ~EnergyMinimizer()

virtual BALL::EnergyMinimizer::~EnergyMinimizer ( )
virtual

Destructor.

Member Function Documentation

◆ enableEnergyAbortCondition()

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

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

◆ energyAbortConditionEnabled()

bool BALL::EnergyMinimizer::energyAbortConditionEnabled ( ) const

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

◆ findStep()

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.

◆ finishIteration()

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:

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

◆ getDirection()

Gradient& BALL::EnergyMinimizer::getDirection ( )

Return a reference to the current search direction

◆ getEnergy() [1/2]

double BALL::EnergyMinimizer::getEnergy ( ) const

Return the current energy

◆ getEnergy() [2/2]

double& BALL::EnergyMinimizer::getEnergy ( )

Return a reference to the current energy

◆ getEnergyDifferenceBound()

float BALL::EnergyMinimizer::getEnergyDifferenceBound ( ) const

Get the energy difference bound

◆ getEnergyOutputFrequency()

Size BALL::EnergyMinimizer::getEnergyOutputFrequency ( ) const

Get the energy ouput frequency

◆ getEnergyToAbort()

float BALL::EnergyMinimizer::getEnergyToAbort ( ) const

◆ getEnergyUpdateCounter()

Size BALL::EnergyMinimizer::getEnergyUpdateCounter ( ) const

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

◆ getForceField()

ForceField* BALL::EnergyMinimizer::getForceField ( )

Return the force field of the energy minimizer

◆ getForceUpdateCounter()

Size BALL::EnergyMinimizer::getForceUpdateCounter ( ) const

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

◆ getGradient()

Gradient& BALL::EnergyMinimizer::getGradient ( )

Return a reference to the current gradient

◆ getInitialEnergy() [1/2]

double BALL::EnergyMinimizer::getInitialEnergy ( ) const

Return the initial energy

◆ getInitialEnergy() [2/2]

double& BALL::EnergyMinimizer::getInitialEnergy ( )

Return a mutable reference to the initial energy

◆ getInitialGradient()

Gradient& BALL::EnergyMinimizer::getInitialGradient ( )

Return a reference to the initial gradient

◆ getMaxGradient()

float BALL::EnergyMinimizer::getMaxGradient ( ) const

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

◆ getMaximumDisplacement()

float BALL::EnergyMinimizer::getMaximumDisplacement ( ) const

Get the maximum displacement value

◆ getMaxNumberOfIterations()

Size BALL::EnergyMinimizer::getMaxNumberOfIterations ( ) const

Get the maximum number of iterations

◆ getMaxSameEnergy()

Size BALL::EnergyMinimizer::getMaxSameEnergy ( ) const

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

◆ getNumberOfIterations()

Size BALL::EnergyMinimizer::getNumberOfIterations ( ) const

Return the number of iterations performed.

◆ getSnapShotFrequency()

Size BALL::EnergyMinimizer::getSnapShotFrequency ( ) const

Get the snapshot output frequency

◆ isConverged()

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.

◆ isValid()

bool BALL::EnergyMinimizer::isValid ( ) const

Is the energy minimizer valid : did the setup work?

◆ minimize()

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
stepsmaximum number of steps to be taken
resumetrue 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.

◆ operator=()

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

Assignment operator

◆ operator==()

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

Equality operator

◆ printEnergy()

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

◆ setEnergyDifferenceBound()

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

Set the energy difference bound for convergence

◆ setEnergyOutputFrequency()

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

Set the energy output frequency

◆ setEnergyToAbort()

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.

◆ setMaxGradient()

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

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

◆ setMaximumDisplacement()

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.

◆ setMaxNumberOfIterations()

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

Set the maximum number of iterations

◆ setMaxSameEnergy()

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

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

◆ setNumberOfIterations()

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

Set the number of iterations performed so far.

◆ setSnapShotFrequency()

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

Set the snapshot frequency

◆ setup() [1/4]

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

Sets up the energy minimizer.

◆ setup() [2/4]

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

Sets up the energy minimizer.

◆ setup() [3/4]

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

Sets up the energy minimizer.

◆ setup() [4/4]

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

Sets up the energy minimizer.

◆ specificSetup()

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

◆ storeGradientEnergy()

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.

◆ takeSnapShot()

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

◆ updateDirection()

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.

◆ updateEnergy()

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

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

◆ updateForces()

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

◆ wasAborted()

bool BALL::EnergyMinimizer::wasAborted ( ) const

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

Member Data Documentation

◆ abort_by_energy_enabled_

bool BALL::EnergyMinimizer::abort_by_energy_enabled_
protected

Definition at line 545 of file energyMinimizer.h.

◆ abort_energy_

float BALL::EnergyMinimizer::abort_energy_
protected

Definition at line 548 of file energyMinimizer.h.

◆ aborted_

bool BALL::EnergyMinimizer::aborted_
protected

Definition at line 551 of file energyMinimizer.h.

◆ current_energy_

double BALL::EnergyMinimizer::current_energy_
protected

The current energy.

Definition at line 457 of file energyMinimizer.h.

◆ current_grad_

Gradient BALL::EnergyMinimizer::current_grad_
protected

The current gradient.

Definition at line 449 of file energyMinimizer.h.

◆ cutlo_

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.

◆ direction_

Gradient BALL::EnergyMinimizer::direction_
protected

The current search direction

Definition at line 469 of file energyMinimizer.h.

◆ energy_difference_bound_

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.

◆ energy_output_frequency_

Size BALL::EnergyMinimizer::energy_output_frequency_
protected

Frequency of energy output

Definition at line 495 of file energyMinimizer.h.

◆ energy_update_counter_

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.

◆ force_field_

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.

◆ force_update_counter_

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.

◆ initial_energy_

double BALL::EnergyMinimizer::initial_energy_
protected

The energy at the beginning of the current minimization step.

Definition at line 453 of file energyMinimizer.h.

◆ initial_grad_

Gradient BALL::EnergyMinimizer::initial_grad_
protected

The gradient at the beginning of the current minimization step.

Definition at line 445 of file energyMinimizer.h.

◆ max_gradient_

double BALL::EnergyMinimizer::max_gradient_
protected

The maximum RMS gradient tolerated (first convergence criterion)

Definition at line 508 of file energyMinimizer.h.

◆ max_same_energy_

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.

◆ maximal_number_of_iterations_

Size BALL::EnergyMinimizer::maximal_number_of_iterations_
protected

Maximum number of iterations

Definition at line 491 of file energyMinimizer.h.

◆ maximum_displacement_

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.

◆ number_of_iterations_

Size BALL::EnergyMinimizer::number_of_iterations_
protected

The current iteration number

Definition at line 487 of file energyMinimizer.h.

◆ old_energy_

double BALL::EnergyMinimizer::old_energy_
protected

The energy from the last step

Definition at line 465 of file energyMinimizer.h.

◆ old_grad_

Gradient BALL::EnergyMinimizer::old_grad_
protected

The gradient from the last step

Definition at line 461 of file energyMinimizer.h.

◆ options

Options BALL::EnergyMinimizer::options

Options

Definition at line 434 of file energyMinimizer.h.

◆ same_energy_counter_

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.

◆ snapshot_

SnapShotManager* BALL::EnergyMinimizer::snapshot_
protected

Pointer to a SnapShotManager for storing snapshots of the system

Definition at line 477 of file energyMinimizer.h.

◆ snapshot_frequency_

Size BALL::EnergyMinimizer::snapshot_frequency_
protected

Frequency of atom coordinate ouput

Definition at line 499 of file energyMinimizer.h.

◆ step_

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.

◆ valid_

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.