Loading...
Searching...
No Matches
BALL::EnergyMinimizer Class Reference
Molecular Modeling » Molecular Mechanics » Energy Minimizer

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

Inheritance diagram for BALL::EnergyMinimizer:

## Classes

struct | Option
struct | Default

## Public Member Functions

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)
bool | 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

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

## 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:

- 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

## getDirection()

Gradient & BALL::EnergyMinimizer::getDirection | ( |  | ) |

Return a reference to the current search direction

## getEnergy() [1/2]

double & BALL::EnergyMinimizer::getEnergy | ( |  | ) |

Return a reference to the current energy

## getEnergy() [2/2]

double BALL::EnergyMinimizer::getEnergy | ( |  | ) | const

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

Return a mutable reference to the initial energy

## getInitialEnergy() [2/2]

double BALL::EnergyMinimizer::getInitialEnergy | ( |  | ) | const

Return 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 \AA).

## 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

  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.

## 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 \AA).

## 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,
|  | const Options & | options )

Sets up the energy minimizer.

## setup() [3/4]

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

Sets up the energy minimizer.

## setup() [4/4]

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

Sets up the energy minimizer.

## specificSetup()

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

virtual

Specific setup

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

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

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

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.