BALL  1.4.79
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Classes | Public Types | Protected Attributes | Static Protected Attributes | List of all members
BALL::FDPB Class Reference

#include <BALL/SOLVATION/poissonBoltzmann.h>

Classes

struct  Boundary
 
struct  ChargeDistribution
 
struct  Default
 
struct  DielectricSmoothing
 
struct  FastAtomStruct
 
struct  Option
 

Public Types

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
}
 
typedef struct FastAtomStruct FastAtom
 

Public Member Functions

Constructors and Destructors
 FDPB ()
 
 FDPB (const FDPB &fdpb)
 
 FDPB (System &system)
 
 FDPB (Options &new_options)
 
 FDPB (System &system, Options &new_options)
 
virtual ~FDPB ()
 
void destroy ()
 
void destroyGrids ()
 
Setup methods

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

bool setup (System &system)
 
bool setup (System &system, Options &options)
 
bool setupEpsGrid (System &system)
 
bool setupSASGrid (System &system)
 
bool setupAtomArray (System &system)
 
bool setupKappaGrid ()
 
bool setupQGrid ()
 
bool setupPhiGrid ()
 
bool setupBoundary ()
 
Executing the calculation and retrieving the results
bool solve ()
 
double getEnergy () const
 
double getReactionFieldEnergy () const
 
double calculateReactionFieldEnergy () const
 
Size getNumberOfIterations () const
 

Public Attributes

Options and results of the calculation
Options options
 
Options results
 
Grids and arrays
TRegularData3D< Vector3 > * eps_grid
 
TRegularData3D< float > * kappa_grid
 
TRegularData3D< float > * q_grid
 
TRegularData3D< float > * phi_grid
 
TRegularData3D< char > * SAS_grid
 
vector< FDPB::FastAtom > * atom_array
 

Protected Attributes

Vector3 lower_
 
Vector3 upper_
 
Vector3 offset_
 
bool use_offset_
 
float spacing_
 
double energy_
 
double reaction_field_energy_
 
vector< Positionboundary_points_
 
Size number_of_iterations_
 
int error_code_
 

Static Protected Attributes

static const char * error_message_ []
 

Debugging

Index getErrorCode () const
 
static String getErrorMessage (Index error_code)
 

Detailed Description

Finite Difference Poisson Boltzmann Solver.

Definition at line 36 of file poissonBoltzmann.h.

Member Typedef Documentation

Definition at line 635 of file poissonBoltzmann.h.

Constructor & Destructor Documentation

BALL::FDPB::FDPB ( )

Default constructor. Creates an empty FDPB object.

BALL::FDPB::FDPB ( const FDPB fdpb)

Copy constructor. Copies an existing FDPB object.

BALL::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)
BALL::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
BALL::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 BALL::FDPB::~FDPB ( )
virtual

Destructor.

Member Function Documentation

double BALL::FDPB::calculateReactionFieldEnergy ( ) const

Calculate the reaction field energy.

Returns
reaction field energy in kJ/mol
void BALL::FDPB::destroy ( )

Frees all allocated memory and destroys the options and results.

void BALL::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 BALL::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 BALL::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
static String BALL::FDPB::getErrorMessage ( Index  error_code)
static

Return the last error message.

See also
getErrorCode
ErrorCodes
Size BALL::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 BALL::FDPB::getReactionFieldEnergy ( ) const

Return the reaction field energy.

Returns
reaction field energy in kJ/mol
bool BALL::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
systemthe molecular system to be examined.
Returns
bool true on success, call getErrorCode otherwise
bool BALL::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
optionsthe new options
systemthe molecular system to be evaluated
Returns
bool true on success, call getErrorCode otherwise
bool BALL::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
systemthe system to be evaluated
Returns
bool true on success, call getErrorCode otherwise
See also
atom_array
FastAtom
bool BALL::FDPB::setupBoundary ( )

Setup boundary conditions for the electrostatic potential.

bool BALL::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
systemthe system to be evaluated
Returns
true on success, call getErrorCode otherwise
bool BALL::FDPB::setupKappaGrid ( )

Setup the Debye Hueckel parameter grid.

bool BALL::FDPB::setupPhiGrid ( )

Setup electrostatic potential grid

bool BALL::FDPB::setupQGrid ( )

Setup charge grid.

bool BALL::FDPB::setupSASGrid ( System system)

Setup the ion accessible grid. Not yet implemented!

bool BALL::FDPB::solve ( )

Solves the linearized Poisson-Boltzmann equation.

Member Data Documentation

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

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

See also
FastAtom

Definition at line 911 of file poissonBoltzmann.h.

vector<Position> BALL::FDPB::boundary_points_
protected

Definition at line 934 of file poissonBoltzmann.h.

double BALL::FDPB::energy_
protected

Definition at line 926 of file poissonBoltzmann.h.

TRegularData3D<Vector3>* BALL::FDPB::eps_grid

The grid containing the spatial dependent dielectric constant. The (relative) dielectric constant is unitless.

See also
setupEpsGrid

Definition at line 876 of file poissonBoltzmann.h.

int BALL::FDPB::error_code_
protected

Definition at line 941 of file poissonBoltzmann.h.

const char* BALL::FDPB::error_message_[]
staticprotected

Definition at line 943 of file poissonBoltzmann.h.

TRegularData3D<float>* BALL::FDPB::kappa_grid

The grid containing the modified Debye Hueckel parameter.

See also
setupKappaGrid

Definition at line 881 of file poissonBoltzmann.h.

Vector3 BALL::FDPB::lower_
protected

Definition at line 917 of file poissonBoltzmann.h.

Size BALL::FDPB::number_of_iterations_
protected

Definition at line 937 of file poissonBoltzmann.h.

Vector3 BALL::FDPB::offset_
protected

Definition at line 919 of file poissonBoltzmann.h.

Options BALL::FDPB::options

The options for the FDPB calculation.

Definition at line 861 of file poissonBoltzmann.h.

TRegularData3D<float>* BALL::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()

Definition at line 902 of file poissonBoltzmann.h.

TRegularData3D<float>* BALL::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

Definition at line 891 of file poissonBoltzmann.h.

double BALL::FDPB::reaction_field_energy_
protected

Definition at line 929 of file poissonBoltzmann.h.

Options BALL::FDPB::results

The results of the last calculation.

Definition at line 865 of file poissonBoltzmann.h.

TRegularData3D<char>* BALL::FDPB::SAS_grid

The grid describing the solvent accessible surface of the system.

Definition at line 906 of file poissonBoltzmann.h.

float BALL::FDPB::spacing_
protected

Definition at line 923 of file poissonBoltzmann.h.

Vector3 BALL::FDPB::upper_
protected

Definition at line 918 of file poissonBoltzmann.h.

bool BALL::FDPB::use_offset_
protected

Definition at line 921 of file poissonBoltzmann.h.