FDPB Class Reference
[Solvation methods]

Finite Difference Poisson Boltzmann Solver. More...

#include <poissonBoltzmann.h>

List of all members.

Debugging

Index getErrorCode () const

Return the last error code.

String getErrorMessage (Index error_code)

Return the last error message.

Public Types

typedef FastAtomStruct FastAtom

enum ErrorCode {
  ERROR__NONE = -1, ERROR__UNKNOWN = 0, ERROR__NOT_IMPLEMENTED = 1, ERROR__CANNOT_CREATE_ATOM_ARRAY,
  ERROR__CANNOT_CREATE_SAS_GRID, ERROR__CANNOT_CREATE_EPSILON_GRID, ERROR__CANNOT_CREATE_KAPPA_GRID, ERROR__CANNOT_CREATE_CHARGE_GRID,
  ERROR__CANNOT_CREATE_PHI_GRID, ERROR__SAS_GRID_REQUIRED, ERROR__EPSILON_GRID_REQUIRED, ERROR__ATOM_ARRAY_REQUIRED,
  ERROR__PHI_GRID_REQUIRED, ERROR__OUT_OF_MEMORY, ERROR__UNKNOWN_DIELECTRIC_SMOOTHING_METHOD, ERROR__UNKNOWN_CHARGE_DISTRIBUTION_METHOD,
  ERROR__UNKNOWN_BOUNDARY_CONDITION_TYPE, ERROR__NOT_A_VECTOR_IN_UPPER_LOWER, ERROR__ILLEGAL_VALUE_FOR_LOWER_UPPER, ERROR__SETUP_REQUIRED,
  NUMBER_OF_ERRORS
}

Error codes: these are the possible error codes that can be produced by FDPB. More...

Public Member Functions

Constructors and Destructors

FDPB ()

Default constructor.

FDPB (const FDPB &fdpb)

Copy constructor.

FDPB (System &system)

Constructor.

FDPB (Options &new_options)

Constructor.

FDPB (System &system, Options &new_options)

Constructor.

virtual ~FDPB ()

Destructor.

void destroy ()

Frees all allocated memory and destroys the options and results.

void destroyGrids ()

Destroys all allocated grids and the atom array.

Setup methods

Using these methods, a FDPB object can be prepared for a calculation.

bool setup (System &system)

General setup method.

bool setup (System &system, Options &options)

Setup with assignment of options.

bool setupEpsGrid (System &system)

Setup the dielectric grid.

bool setupSASGrid (System &system)

Setup the ion accessible grid.

bool setupAtomArray (System &system)

Setup an compact datastructure containing all charged atoms.

bool setupKappaGrid ()

Setup the Debye Hueckel parameter grid.

bool setupQGrid ()

Setup charge grid.

bool setupPhiGrid ()

Setup electrostatic potential grid.

bool setupBoundary ()

Setup boundary conditions for the electrostatic potential.

Executing the calculation and retrieving the results

bool solve ()

Solves the linearized Poisson-Boltzmann equation.

double getEnergy () const

Returns the energy of the last calculation.

double getReactionFieldEnergy () const

Return the reaction field energy.

double calculateReactionFieldEnergy () const

Calculate the reaction field energy.

Size getNumberOfIterations () const

Returns the number of iterations needed to converge.

Public Attributes

Options and results of the calculation

Options options

The options for the FDPB calculation.

Options results

The results of the last calculation.

Grids and arrays

TRegularData3D< Vector3 > * eps_grid

The grid containing the spatial dependent dielectric constant.

TRegularData3D< float > * kappa_grid

The grid containing the modified Debye Hueckel parameter.

TRegularData3D< float > * q_grid

The grid containing the atom charges (distributed).

TRegularData3D< float > * phi_grid

The grid containing the electrostatic potential.

TRegularData3D< char > * SAS_grid

The grid describing the solvent accessible surface of the system.

vector< FDPB::FastAtom > * atom_array

An array containing a fast representation of all atoms in the system.

Protected Attributes

Vector3 lower_

Vector3 upper_

Vector3 offset_

bool use_offset_

float spacing_

double energy_

double reaction_field_energy_

vector< Position > boundary_points_

Size number_of_iterations_

int error_code_

Static Protected Attributes

const char * error_message_ []

Detailed Description

Finite Difference Poisson Boltzmann Solver.

Member Enumeration Documentation

enum FDPB::ErrorCode

Error codes: these are the possible error codes that can be produced by FDPB.

See also:
FDPB::getErrorCode()
FDPB::getErrorMessage()

Enumeration values:

ERROR__NONE No error.

ERROR__UNKNOWN Unknown error.

ERROR__NOT_IMPLEMENTED Not implemented error.
Someone has been too lazy to implement the this method. Wait for the next release...

ERROR__CANNOT_CREATE_ATOM_ARRAY Unable to create the atom array/out of memory.
FDPB internally creates a dynamic array containing the atoms of the system. If FDPB::setupAtomArray() cannot create this array you normally ran out of virtual memory.

ERROR__CANNOT_CREATE_SAS_GRID Unable to create SAS grid/out of memory.
FDPB uses a TRegularData3D<char> (FDPB::SAS_grid) to describe whether a point in space is inside the ion exclusion layer. This grid is created by FDPB::setupSASGrid(). On failure this error code is set. It usually indicates a lack of virtual memory.

ERROR__CANNOT_CREATE_EPSILON_GRID Unable to create dielectric grid/out of memory.
FDPB uses a TRegularData3D<float> ( FDPB::eps_grid ) to describe the dielectric constant $\varepsilon$ as a function of space. This grid is created by calling FDPB::setupEpsGrid(). It contains the relative dielectric constant between neighbouring grid points.
If virtual memory is exhausted and the grid could not be created this error is set.

ERROR__CANNOT_CREATE_KAPPA_GRID Unable to create grid for the modified Debye Hueckel parameter/out of memory.
The modified Debye Hueckel parameter $\bar{\kappa}$ is also a function of space and therefore represented by a TRegularData3D<float> (FDPB::kappa_grid). The grid is created by FDPB::setupKappaGrid().
If the creation of this grid fails due to a alack of virtual memory this error code is set.

ERROR__CANNOT_CREATE_CHARGE_GRID Unable to create charge grid/out of memory.
FDPB::setupQGrid() distributes the charge of the atoms in a grid. This grid is named FDPB::q_grid.
If the creation of this grid fails due to a lack of virtual memory, this error code is set.

ERROR__CANNOT_CREATE_PHI_GRID Unable to create electrostatic potential grid/out of memory.
FDPB::setupPhiGrid() creates a TRegularData3D<float> (FDPB::phi_grid) containing the electrostatic potential as a function of space. If the creation of this grid fails due to a lack of virtual memory, this error code is set.

ERROR__SAS_GRID_REQUIRED Create solvent accessible surface grid first.
This error code is set by FDPB::setupKappGrid() if it is called but the ion excluded surface has not been set (usually by calling FDPB::setupSASGrid).
Solution: call FDPB::setupKappaGrid after calling FDPB::setupSASGrid.

ERROR__EPSILON_GRID_REQUIRED Create dielectric constant grid first.
This error code is set by FDPB::setupQGrid(), FDPB::setupKappaGrid(), or FDPB::setupPhiGrid() if it was called, but FDPB::eps_grid was not defined yet (this is usually done by calling FDPB::setupEpsGrid ).
Solution: call FDPB::setupEpsGrid first

ERROR__ATOM_ARRAY_REQUIRED Create atom array first.
This error code is set by FDPB::setupQGrid() or FDPB::setupBoundary() if it was called but FDPB::atom_array was not yet defined (this is usually done by calling FDPB::setupAtomArray()).
Solution: call FDPB::setupAtomArray() first

ERROR__PHI_GRID_REQUIRED Create electrostatic potential grid first.
FDPB::phi_grid contains the electrostatic potential at each point in space. FDPB::setupBoundary() sets this error code if it is called but FDPB::phi_grid has not been set yet. Solution: call FDPB::setupPhiGrid() before calling FDPB::setupBoundary()

ERROR__OUT_OF_MEMORY Not enough virtual memory.
This error code is set if FDPB::solve() ran out of virtual memory while creating some internal datastructures. Solution: reduce grid dimensions or increase grid spacing.

ERROR__UNKNOWN_DIELECTRIC_SMOOTHING_METHOD The specified method to smooth the dielectric constant grid is not allowed.
FDPB::setupEpsGrid sets this error code, if it cannot identify the method given in FDPB::Option::dielectric_smoothing.
Solution: specify a valid smoothing method in FDPB::options

See also:
FDPB::Option::dielectric_smoothing
FDPB::DielectricSmoothing

ERROR__UNKNOWN_CHARGE_DISTRIBUTION_METHOD The specified charge distribution is not allowed.
FDPB::setupQGrid() sets this error code, if it cannot identify the method given in FDPB::Option::charge_distribution.
Solution: specify a valid charge distribution method in FDPB::options

See also:
FDPB::Option::charge_distribution
FDPB::ChargeDistribution

ERROR__UNKNOWN_BOUNDARY_CONDITION_TYPE The specified boundary condition type is not allowed.
FDPB::setupBoundary() sets this error code, if it cannot identify the boundary condition given in FDPB::Option::boundary.
Solution: specify a valid boundary condition in FDPB::options

See also:
FDPB::Option::boundary
FDPB::Boundary

ERROR__NOT_A_VECTOR_IN_UPPER_LOWER Upper or lower grid coordinates were specified in an incorrect format.
This error code is set by FDPB::setupEpsGrid if the string given in FDPB::options (key FDPB::Option::LOWER or FDPB::Option::UPPER) were not in vector format.
Solution: specify upper/lower coordinates in the correct format

See also:
Options::isVector

ERROR__ILLEGAL_VALUE_FOR_LOWER_UPPER Lower and upper corner of the grid were set to wrong values.
Lower and upper corners of the grid given in FDPB::options (key FDPB::Option::LOWER and FDPB::Option::UPPER) must fulfill just one condition: every coordinate of lower hast to be less (not equal!) to the corresponding coordinate of upper.
Solution: specify a reasonable non-degenerate grid

ERROR__SETUP_REQUIRED Call setup first.
This error code is set by FDPB::solve() if FDPB::q_grid or FDPB::phi_grid or FDPB::eps_grid are undefined.
Solution: define each of the above mentioned grids or call FDPB::setup()

NUMBER_OF_ERRORS Total number of errors defined.

Constructor & Destructor Documentation

FDPB::FDPB ( )

Default constructor.
Creates an empty FDPB object.

FDPB::FDPB ( const FDPB & fdpb )

Copy constructor.
Copies an existing FDPB object.

FDPB::FDPB ( System & system )

Constructor.
Creates an instance of FDPB and calls setup(system). The options used are the default options.
See also:
setup(system)

FDPB::FDPB ( Options & new_options )

Constructor.
Creates an instance of FDPB and assigns the given options to the FDPB object's options.
See also:
options
Options

FDPB::FDPB ( System & system,

Options & new_options

)

Constructor.
Creates an instance of FDPB and calls setup(system, options)
See also:
setup(system, options)
options
Options

virtual FDPB::~FDPB ( ) [virtual]

Destructor.

Member Function Documentation

double FDPB::calculateReactionFieldEnergy ( ) const

Calculate the reaction field energy.

Returns:
reaction field energy in kJ/mol

void FDPB::destroy ( )

Frees all allocated memory and destroys the options and results.

void FDPB::destroyGrids ( )

Destroys all allocated grids and the atom array.
This method reverts the FDPB object to the state it had prior to a call to setup. Especially it frees all memory intensive datastructures.
destroyGrids deletes eps_grid, kappa_grid, q_grid, phi_grid, and SAS_grid. Contrary to destroy, it doesnt't clear options and results.

See also:
destroy
setup

double FDPB::getEnergy ( ) const

Returns the energy of the last calculation.
The total electrostatic energy of the FDPB object after the last iteration (even if no convergence was reached!) is returned in units of kJ/mol.
See also:
getNumberOfIterations

Returns:
energy in kJ/mol

Index FDPB::getErrorCode ( ) const

Return the last error code.
If a method fails, an internal error code is set in FDPB. This error code can be queried by calling this method. If no error occured it should return FDPB::ERROR__NONE.
See also:
getErrorMessage
ErrorCodes

String FDPB::getErrorMessage ( Index error_code ) [static]

Return the last error message.

See also:
getErrorCode
ErrorCodes

Size FDPB::getNumberOfIterations ( ) const

Returns the number of iterations needed to converge.
Returns the number of iterations taken in the last call to FDPB::solve(). If convergence could not be reached (i.e., the convergence criterions defined in options could not be met), -1 is returned.
Returns:
int number of iterations

See also:
Option::max_iterations
Default::max_iterations

double FDPB::getReactionFieldEnergy ( ) const

Return the reaction field energy.

Returns:
reaction field energy in kJ/mol

bool FDPB::setup ( System & system,

Options & options

)

Setup with assignment of options.
This method copies the options given by options into the options variable of the FDPB object and invokes setup(system) afterwards.
See also:
setup(System& system)

Parameters:

options the new options

system the molecular system to be evaluated

Returns:
bool true on success, call getErrorCode otherwise

bool FDPB::setup ( System & system )

General setup method.
Setup calls (in this order!)

setupAtomArray
setupEpsGrid
setupSASGrid
setupKappaGrid
setupPhiGrid
setupQGrid
setupBoundary

If any of theses method invocations fail, it terminates at this point and returns false.
On successful execution it returns true and the FDPB object is ready to solve the Poisson Boltzmann equation by calling solve().

See also:
setup(System& system, Options& options)

Parameters:

system the molecular system to be examined.

Returns:
bool true on success, call getErrorCode otherwise

bool FDPB::setupAtomArray ( System & system )

Setup an compact datastructure containing all charged atoms.
This method creates a dynamic array containing all charged atoms.
The method may set the error code to ERROR__CANNOT_CREATE_ATOM_ARRAY and terminate with false if insufficient virtual memory is available to create the array.

Parameters:

system the system to be evaluated

Returns:
bool true on success, call getErrorCode otherwise

See also:
atom_array
FastAtom

bool FDPB::setupBoundary ( )

Setup boundary conditions for the electrostatic potential.

bool FDPB::setupEpsGrid ( System & system )

Setup the dielectric grid.
The Finite Difference Poisson Boltzmann Method is based on the assumption that one can determine which points on a given grid are inside a given solute (with low dielectric constant) and which points are outside (i.e., they are in the high dielectric constant solvent).
setupEpsGrid creates a grid containing the dielectric constant between any two neighbouring grid points (i.e., it contains 3 N values). Points inside the molecule (i.i, inside the radius of any atom) are set to the solute dielectric constant, all other points are set to the solvent dielectric constant.

This method also sets the coordinates and dimensions of the grid (extracted from either options or system) and the grid spacing.

Normally this method is not called by the user, but automatically by setup. If you consider to call it by yourself, be sure to call the single setup methods in the correct order (as described for setup).

This method may set one of the following error codes and return false afterwards:

ERROR__NOT_A_VECTOR_IN_UPPER_LOWER
ERROR__ILLEGAL_VALUE_FOR_LOWER_UPPER

Parameters:

system the system to be evaluated

Returns:
true on success, call getErrorCode otherwise

bool FDPB::setupKappaGrid ( )

Setup the Debye Hueckel parameter grid.

bool FDPB::setupQGrid ( )

Setup charge grid.

bool FDPB::setupSASGrid ( System & system )

Setup the ion accessible grid.
Not yet implemented!

bool FDPB::solve ( )

Solves the linearized Poisson-Boltzmann equation.

Member Data Documentation

vector<FDPB::FastAtom>* FDPB::atom_array

An array containing a fast representation of all atoms in the system.

See also:
FastAtom

TRegularData3D<Vector3>* FDPB::eps_grid

The grid containing the spatial dependent dielectric constant.
The (relative) dielectric constant is unitless.
See also:
setupEpsGrid

TRegularData3D<float>* FDPB::kappa_grid

The grid containing the modified Debye Hueckel parameter.

See also:
setupKappaGrid

Options FDPB::options

The options for the FDPB calculation.

TRegularData3D<float>* FDPB::phi_grid

The grid containing the electrostatic potential.
Before a calculation this is grid is initialized with the boundary condition. After the calculation (i.e. after a call to solve()) it contains the electrostatic potential in units of J/C resulting from the Poisson-Boltzmann equation).
See also:
setupPhiGrid()
setupBoundary()
solve()

TRegularData3D<float>* FDPB::q_grid

The grid containing the atom charges (distributed).
Each atom's charge is distributed on the grid by setupQGrid, according to the charge distribution method specified in options.
q_grid contains these partial charges. Units are elementary charges, if the atom charges were given in multiples of the elementary charge (Atom::setCharge).

See also:
BALL_ELEMENTARY_CHARGE
setupQGrid

Options FDPB::results

The results of the last calculation.

TRegularData3D<char>* FDPB::SAS_grid

The grid describing the solvent accessible surface of the system.


Debugging
Index	getErrorCode () const
	Return the last error code.
String	getErrorMessage (Index error_code)
	Return the last error message.
Public Types
typedef FastAtomStruct	FastAtom
enum	ErrorCode { ERROR__NONE = -1, ERROR__UNKNOWN = 0, ERROR__NOT_IMPLEMENTED = 1, ERROR__CANNOT_CREATE_ATOM_ARRAY, ERROR__CANNOT_CREATE_SAS_GRID, ERROR__CANNOT_CREATE_EPSILON_GRID, ERROR__CANNOT_CREATE_KAPPA_GRID, ERROR__CANNOT_CREATE_CHARGE_GRID, ERROR__CANNOT_CREATE_PHI_GRID, ERROR__SAS_GRID_REQUIRED, ERROR__EPSILON_GRID_REQUIRED, ERROR__ATOM_ARRAY_REQUIRED, ERROR__PHI_GRID_REQUIRED, ERROR__OUT_OF_MEMORY, ERROR__UNKNOWN_DIELECTRIC_SMOOTHING_METHOD, ERROR__UNKNOWN_CHARGE_DISTRIBUTION_METHOD, ERROR__UNKNOWN_BOUNDARY_CONDITION_TYPE, ERROR__NOT_A_VECTOR_IN_UPPER_LOWER, ERROR__ILLEGAL_VALUE_FOR_LOWER_UPPER, ERROR__SETUP_REQUIRED, NUMBER_OF_ERRORS }
	Error codes: these are the possible error codes that can be produced by FDPB. More...
Public Member Functions
Constructors and Destructors
	FDPB ()
	Default constructor.
	FDPB (const FDPB &fdpb)
	Copy constructor.
	FDPB (System &system)
	Constructor.
	FDPB (Options &new_options)
	Constructor.
	FDPB (System &system, Options &new_options)
	Constructor.
virtual	~FDPB ()
	Destructor.
void	destroy ()
	Frees all allocated memory and destroys the options and results.
void	destroyGrids ()
	Destroys all allocated grids and the atom array.
Setup methods
Using these methods, a FDPB object can be prepared for a calculation.
bool	setup (System &system)
	General setup method.
bool	setup (System &system, Options &options)
	Setup with assignment of options.
bool	setupEpsGrid (System &system)
	Setup the dielectric grid.
bool	setupSASGrid (System &system)
	Setup the ion accessible grid.
bool	setupAtomArray (System &system)
	Setup an compact datastructure containing all charged atoms.
bool	setupKappaGrid ()
	Setup the Debye Hueckel parameter grid.
bool	setupQGrid ()
	Setup charge grid.
bool	setupPhiGrid ()
	Setup electrostatic potential grid.
bool	setupBoundary ()
	Setup boundary conditions for the electrostatic potential.
Executing the calculation and retrieving the results
bool	solve ()
	Solves the linearized Poisson-Boltzmann equation.
double	getEnergy () const
	Returns the energy of the last calculation.
double	getReactionFieldEnergy () const
	Return the reaction field energy.
double	calculateReactionFieldEnergy () const
	Calculate the reaction field energy.
Size	getNumberOfIterations () const
	Returns the number of iterations needed to converge.
Public Attributes
Options and results of the calculation
Options	options
	The options for the FDPB calculation.
Options	results
	The results of the last calculation.
Grids and arrays
TRegularData3D< Vector3 > *	eps_grid
	The grid containing the spatial dependent dielectric constant.
TRegularData3D< float > *	kappa_grid
	The grid containing the modified Debye Hueckel parameter.
TRegularData3D< float > *	q_grid
	The grid containing the atom charges (distributed).
TRegularData3D< float > *	phi_grid
	The grid containing the electrostatic potential.
TRegularData3D< char > *	SAS_grid
	The grid describing the solvent accessible surface of the system.
vector< FDPB::FastAtom > *	atom_array
	An array containing a fast representation of all atoms in the system.
Protected Attributes
Vector3	lower_
Vector3	upper_
Vector3	offset_
bool	use_offset_
float	spacing_
double	energy_
double	reaction_field_energy_
vector< Position >	boundary_points_
Size	number_of_iterations_
int	error_code_
Static Protected Attributes
const char *	error_message_ []

FDPB Class Reference [Solvation methods]

Debugging

Public Types

Public Member Functions

Public Attributes