Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

Vpmg class

A wrapper for Mike Holst's PMG multigrid code. More...


Files

file  vpmg.h
 Contains declarations for class Vpmg.


Data Structures

struct  sVpmg
 Contains public data members for Vpmg class/module. More...


Defines

#define VPMGMAXPART   2000

Typedefs

typedef sVpmg Vpmg
 Declaration of the Vpmg class as the Vpmg structure.


Functions

int Vpmg_memChk (Vpmg *thee)
 Return the memory used by this structure (and its contents) in bytes.

Vpmg * Vpmg_ctor (Vpmgp *parms, Vpbe *pbe)
 Constructor for the Vpmg class (no focusing).

int Vpmg_ctor2 (Vpmg *thee, Vpmgp *parms, Vpbe *pbe)
 FORTRAN stub constructor for the Vpmg class (no focusing).

Vpmg * Vpmg_ctorFocus (Vpmgp *parms, Vpbe *pbe, Vpmg *pmgOLD, int energyFlag)
 Constructor for the Vpmg class (with focusing).

int Vpmg_ctor2Focus (Vpmg *thee, Vpmgp *parms, Vpbe *pbe, Vpmg *pmgOLD, int energyFlag)
 FORTRAN stub bonstructor for the Vpmg class (with focusing).

void Vpmg_dtor (Vpmg **thee)
 Object destructor.

void Vpmg_dtor2 (Vpmg *thee)
 FORTRAN stub object destructor.

void Vpmg_fillco (Vpmg *thee, Vsurf_Meth surfMeth, double splineWin, Vchrg_Meth chargeMeth, int useDielXMap, Vgrid *dielXMap, int useDielYMap, Vgrid *dielYMap, int useDielZMap, Vgrid *dielZMap, int useKappaMap, Vgrid *kappaMap, int useChargeMap, Vgrid *chargeMap)
 Fill the coefficient arrays prior to solving the equation.

void Vpmg_solve (Vpmg *thee)
 Solve the PBE using PMG.

double Vpmg_energy (Vpmg *thee, int extFlag)
 Get the total electrostatic energy.

double Vpmg_qfEnergy (Vpmg *thee, int extFlag)
 Get the "fixed charge" contribution to the electrostatic energy.

double Vpmg_qfAtomEnergy (Vpmg *thee, Vatom *atom)
 Get the per-atom "fixed charge" contribution to the electrostatic energy.

double Vpmg_qmEnergy (Vpmg *thee, int extFlag)
 Get the "mobile charge" contribution to the electrostatic energy.

double Vpmg_dielEnergy (Vpmg *thee, int extFlag)
 Get the "polarization" contribution to the electrostatic energy.

double Vpmg_npEnergy (Vpmg *thee, int extFlag)
 Get the "apolar" energy.

double Vpmg_dielGradNorm (Vpmg *thee)
 Get the integral of the gradient of the dielectric function.

void Vpmg_force (Vpmg *thee, double *force, int atomID, Vsurf_Meth srfm, Vchrg_Meth chgm)
 Calculate the total force on the specified atom in units of .

void Vpmg_qfForce (Vpmg *thee, double *force, int atomID, Vchrg_Meth chgm)
 Calculate the "charge-field" force on the specified atom in units of .

void Vpmg_dbnpForce (Vpmg *thee, double *dbForce, double *npForce, int atomID, Vsurf_Meth srfm)
 Calculate the dielectric boundary and apolar forces on the specified atom in units of .

void Vpmg_ibForce (Vpmg *thee, double *force, int atomID, Vsurf_Meth srfm)
 Calculate the osmotic pressure on the specified atom in units of .

void Vpmg_setPart (Vpmg *thee, double lowerCorner[3], double upperCorner[3], int bflags[6])
 Set partition information which restricts the calculation of observables to a (rectangular) subset of the problem domain.

void Vpmg_unsetPart (Vpmg *thee)
 Remove partition restrictions.

void Vpmg_fillArray (Vpmg *thee, double *vec, Vdata_Type type, double parm)
 Fill the specified array with accessibility values.

void Vpmg_printColComp (Vpmg *thee, char path[72], char title[72], char mxtype[3], int flag)
 Print out a column-compressed sparse matrix in Harwell-Boeing format.


Detailed Description

A wrapper for Mike Holst's PMG multigrid code.

Note:
Many of the routines and macros are borrowed from the main.c driver (written by Mike Holst) provided with the PMG code.

Define Documentation

#define VPMGMAXPART   2000
 

The maximum number of partitions the mesh can be divided into


Function Documentation

Vpmg* Vpmg_ctor Vpmgp   parms,
Vpbe   pbe
 

Constructor for the Vpmg class (no focusing).

Author:
Nathan Baker
Parameters:
parms  PMG parameter object
pbe  Object containing PBE-specific variables
Returns:
Pointer to newly allocated Vpmg object

int Vpmg_ctor2 Vpmg   thee,
Vpmgp   parms,
Vpbe   pbe
 

FORTRAN stub constructor for the Vpmg class (no focusing).

Author:
Nathan Baker
Parameters:
thee  Pointer to newly-allocated Vpmg object
parms  PMG parameter object
pbe  Object containing PBE-specific variables
Returns:
1 if successful, 0 otherwise

int Vpmg_ctor2Focus Vpmg   thee,
Vpmgp   parms,
Vpbe   pbe,
Vpmg   pmgOLD,
int    energyFlag
 

FORTRAN stub bonstructor for the Vpmg class (with focusing).

Note:
Construct the PMG object by focusing. In other words, use the solution from the passed Vpmg object to set the boundary conditions for the new Vpmg object. IN THE PROCESS, THE OLD VPMG OBJECT IS DESTROYED. The solver parameters specifed by the passed Vpmgp object and the equation data from the Vpbe object are also used.
Author:
Nathan Baker
Parameters:
thee  Pointer to newly allocated Vpmg object
parms  PMG parameter object for new mesh
pbe  PBE parameter object
pmgOLD  Old Vpmg object to use for setting boundary conditions
energyFlag 
  • 0: Don't calculate any energy contribution from outside focusing area
  • 1: Calculate total energy contribution from outside focusing area
  • 2: Calculate energy component contributions
Returns:
1 if successful, 0 otherwise

Vpmg* Vpmg_ctorFocus Vpmgp   parms,
Vpbe   pbe,
Vpmg   pmgOLD,
int    energyFlag
 

Constructor for the Vpmg class (with focusing).

Note:
Construct the PMG object by focusing. In other words, use the solution from the passed Vpmg object to set the boundary conditions for the new Vpmg object. IN THE PROCESS, THE OLD VPMG OBJECT IS DESTROYED. The solver parameters specifed by the passed Vpmgp object and the equation data from the Vpbe object are also used.
Author:
Nathan Baker
Parameters:
parms  PMG parameter object for new mesh
pbe  PBE parameter object
pmgOLD  Old Vpmg object to use for setting boundary conditions
energyFlag 
  • 0: Don't calculate any energy contribution from outside focusing area
  • 1: Calculate total energy contribution from outside focusing area
  • 2: Calculate energy component contributions
Returns:
Pointer to the newly allocated Vpmg object

void Vpmg_dbnpForce Vpmg   thee,
double *    dbForce,
double *    npForce,
int    atomID,
Vsurf_Meth    srfm
 

Calculate the dielectric boundary and apolar forces on the specified atom in units of .

Author:
Nathan Baker
Note:
  • Using the force evaluation methods of Im et al (Roux group), Comput Phys Commun, 111, 59--75 (1998). However, this gives the whole (self-interactions included) force -- reaction field forces will have to be calculated at higher level.
  • No contributions are made from higher levels of focusing.
  • This is currently implemented in a very inefficient fashion becuase I'm not sure which of the PMG coefficient arrays can be re-used and which are overwritten by PMG.
Parameters:
thee  Vpmg object
dbForce  3*double space to hold the dielectric boudnary force in units of
npForce  3*double space to hold the apolar boudnary force in units of
atomID  Valist ID of desired atom
srfm  Surface definition method

double Vpmg_dielEnergy Vpmg   thee,
int    extFlag
 

Get the "polarization" contribution to the electrostatic energy.

Using the solution at the finest mesh level, get the electrostatic energy due to the interaction of the mobile charges with the potential:

where is the dielectric parameter and is the dimensionless electrostatic potential. The energy is scaled to units of .

Author:
Nathan Baker
Note:
The value of this observable may be modified by setting restrictions on the subdomain over which it is calculated. Such limits can be set via Vpmg_setPart and are generally useful for parallel runs.
Parameters:
thee  Vpmg object
extFlag  If this was a focused calculation, then it is possible to include the energy contributions from the outside the focused domain. This should be on (=1) for sequential focusing calculations and off (=0) for parallel calculations.
Returns:
The polarization electrostatic energy in units of .

double Vpmg_dielGradNorm Vpmg   thee
 

Get the integral of the gradient of the dielectric function.

Using the dielectric map at the finest mesh level, calculate the integral of the norm of the dielectric function gradient routines of Im et al (see Vpmg_dbnpForce for reference):

where is the dielectric parameter. The integral is returned in units of A^2.

Author:
Nathan Baker restrictions on the subdomain over which it is calculated. Such limits can be set via Vpmg_setPart and are generally useful for parallel runs.
Parameters:
thee  Vpmg object
Returns:
The integral in units of A^2.

void Vpmg_dtor Vpmg **    thee
 

Object destructor.

Author:
Nathan Baker
Parameters:
thee  Pointer to memory location of object to be destroyed

void Vpmg_dtor2 Vpmg   thee
 

FORTRAN stub object destructor.

Author:
Nathan Baker
Parameters:
thee  Pointer to object to be destroyed

double Vpmg_energy Vpmg   thee,
int    extFlag
 

Get the total electrostatic energy.

Author:
Nathan Baker
Note:
The value of this observable may be modified by setting restrictions on the subdomain over which it is calculated. Such limits can be set via Vpmg_setPart and are generally useful for parallel runs.
Parameters:
thee  Vpmg object
extFlag  If this was a focused calculation, then it is possible to include the energy contributions from the outside the focused domain. This should be on (=1) for sequential focusing calculations and off (=0) for parallel calculations.
Returns:
The electrostatic energy in units of .

void Vpmg_fillArray Vpmg   thee,
double *    vec,
Vdata_Type    type,
double    parm
 

Fill the specified array with accessibility values.

Author:
Nathan Baker
Parameters:
thee  Vpmg object
vec  An array nx*ny*nz in length to contain the accessibility values (where nx, ny, nz are the numbers of grid points)
type  Which data to write
parm  Parameter for data definition (if needed)

void Vpmg_fillco Vpmg   thee,
Vsurf_Meth    surfMeth,
double    splineWin,
Vchrg_Meth    chargeMeth,
int    useDielXMap,
Vgrid   dielXMap,
int    useDielYMap,
Vgrid   dielYMap,
int    useDielZMap,
Vgrid   dielZMap,
int    useKappaMap,
Vgrid   kappaMap,
int    useChargeMap,
Vgrid   chargeMap
 

Fill the coefficient arrays prior to solving the equation.

Author:
Nathan Baker
Parameters:
thee  Vpmg object
surfMeth  Surface discretization method
splineWin  Spline window (for surfMeth = VSM_SPLINE)
chargeMeth  Charge discretization method
useDielXMap  Specifies whether to use (1) or ignore (0) the dielXMap arguement
dielXMap  Pointer to a Vgrid object containing an external x-shifted dielectric map. Can be VNULL if useDielMap is 0.
useDielYMap  Specifies whether to use (1) or ignore (0) the dielYMap arguement
dielYMap  Pointer to a Vgrid object containing an external y-shifted dielectric map. Can be VNULL if useDielMap is 0.
useDielZMap  Specifies whether to use (1) or ignore (0) the dielZMap arguement
dielZMap  Pointer to a Vgrid object containing an external z-shifted dielectric map. Can be VNULL if useDielMap is 0.
useKappaMap  Specifies whether to use (1) or ignore (0) the kappaMap arguement
kappaMap  Pointer to a Vgrid object containing an external kappa map. Can be VNULL if useKappaMap is 0.
useChargeMap  Specifies whether to use (1) or ignore (0) the chargeMap arguement
chargeMap  Pointer to a Vgrid object containing an external charge distribution map. Can be VNULL if useChargeMap is 0.

void Vpmg_force Vpmg   thee,
double *    force,
int    atomID,
Vsurf_Meth    srfm,
Vchrg_Meth    chgm
 

Calculate the total force on the specified atom in units of .

Author:
Nathan Baker
Note:
  • Using the force evaluation methods of Im et al (Roux group), Comput Phys Commun, 111, 59--75 (1998). However, this gives the whole (self-interactions included) force -- reaction field forces will have to be calculated at higher level.
  • No contributions are made from higher levels of focusing.
  • This is currently implemented in a very inefficient fashion becuase I'm not sure which of the PMG coefficient arrays can be re-used and which are overwritten by PMG.
Parameters:
thee  Vpmg object
force  3*double space to hold the force in units of
atomID  Valist ID of desired atom
srfm  Surface definition method
chgm  Charge discretization method

void Vpmg_ibForce Vpmg   thee,
double *    force,
int    atomID,
Vsurf_Meth    srfm
 

Calculate the osmotic pressure on the specified atom in units of .

Author:
Nathan Baker
Note:
  • Using the force evaluation methods of Im et al (Roux group), Comput Phys Commun, 111, 59--75 (1998). However, this gives the whole (self-interactions included) force -- reaction field forces will have to be calculated at higher level.
  • No contributions are made from higher levels of focusing.
  • This is currently implemented in a very inefficient fashion becuase I'm not sure which of the PMG coefficient arrays can be re-used and which are overwritten by PMG.
Parameters:
thee  Vpmg object
force  3*double space to hold the force in units of
atomID  Valist ID of desired atom
srfm  Surface definition method

int Vpmg_memChk Vpmg   thee
 

Return the memory used by this structure (and its contents) in bytes.

Author:
Nathan Baker
Parameters:
thee  Vpmg object
Returns:
The memory used by this structure and its contents in bytes

double Vpmg_npEnergy Vpmg   thee,
int    extFlag
 

Get the "apolar" energy.

Using the dielectric map at the finest mesh level, calculate the surface area in a manner consistent with the force evaluation routines of Im et al (see Vpmg_dbnpForce and Vpmg_dielGradNorm):

where is the dielectric parameter, is the dielectric constant for the solvent and is the dielectric constant for the protein. The apolar energy is then,

where is the apolar coefficient set in Vpbe (see Vpbe_ctor). The energy is returned in units of .

Author:
Nathan Baker
Note:
I personally feel that this routine should not find its way into the main APBS driver. In this case, the apolar energy is calculated in a manner consistent with the force evaluation, but it is not the only possible apolar energy definition... The value of this observable may be modified by setting restrictions on the subdomain over which it is calculated. Such limits can be set via Vpmg_setPart and are generally useful for parallel runs.
Parameters:
thee  Vpmg object
extFlag  If this was a focused calculation, then it is possible to include the energy contributions from the outside the focused domain. This should be on (=1) for sequential focusing calculations and off (=0) for parallel calculations.
Returns:
The apolar energy in units of .

void Vpmg_printColComp Vpmg   thee,
char    path[72],
char    title[72],
char    mxtype[3],
int    flag
 

Print out a column-compressed sparse matrix in Harwell-Boeing format.

Author:
Nathan Baker
Parameters:
thee  Vpmg object
path  The file to which the matrix is to be written
title  The title of the matrix
mxtype  The type of REAL-valued matrix, a 3-character string of the form "R_A", where the blank can contain:
  • S: Symmetric matrix
  • U: Unsymmetric matrix
  • H: Hermitian matrix
  • Z: Skew symmetric matrix
  • R: Rectangular
flag  The operator to compress:
  • 0: Just the Poisson operator
  • 1: The linearization of the full Poisson-Boltzmann operator around the current solution

double Vpmg_qfAtomEnergy Vpmg   thee,
Vatom   atom
 

Get the per-atom "fixed charge" contribution to the electrostatic energy.

Using the solution at the finest mesh level, get the electrostatic energy due to the interaction of the fixed charges with the potential:

where is the charge and is the location of the atom of interest. The result is returned in units of . Clearly, no self-interaction terms are removed. A factor a 1/2 has to be included to convert this to a real energy.

Author:
Nathan Baker
Note:
The value of this observable may be modified by setting restrictions on the subdomain over which it is calculated. Such limits can be set via Vpmg_setPart and are generally useful for parallel runs.
Parameters:
thee  Vpmg object
atom  The atom for which to calculate the energy.
Returns:
The fixed charge electrostatic energy in units of .

double Vpmg_qfEnergy Vpmg   thee,
int    extFlag
 

Get the "fixed charge" contribution to the electrostatic energy.

Using the solution at the finest mesh level, get the electrostatic energy due to the interaction of the fixed charges with the potential:

and return the result in units of . Clearly, no self-interaction terms are removed. A factor a 1/2 has to be included to convert this to a real energy.

Author:
Nathan Baker
Note:
The value of this observable may be modified by setting restrictions on the subdomain over which it is calculated. Such limits can be set via Vpmg_setPart and are generally useful for parallel runs.
Parameters:
thee  Vpmg object
extFlag  If this was a focused calculation, then it is possible to include the energy contributions from the outside the focused domain. This should be on (=1) for sequential focusing calculations and off (=0) for parallel calculations.
Returns:
The fixed charge electrostatic energy in units of .

void Vpmg_qfForce Vpmg   thee,
double *    force,
int    atomID,
Vchrg_Meth    chgm
 

Calculate the "charge-field" force on the specified atom in units of .

Author:
Nathan Baker
Note:
  • Using the force evaluation methods of Im et al (Roux group), Comput Phys Commun, 111, 59--75 (1998). However, this gives the whole (self-interactions included) force -- reaction field forces will have to be calculated at higher level.
  • No contributions are made from higher levels of focusing.
  • This is currently implemented in a very inefficient fashion becuase I'm not sure which of the PMG coefficient arrays can be re-used and which are overwritten by PMG.
Parameters:
thee  Vpmg object
force  3*double space to hold the force in units of
atomID  Valist ID of desired atom
chgm  Charge discretization method

double Vpmg_qmEnergy Vpmg   thee,
int    extFlag
 

Get the "mobile charge" contribution to the electrostatic energy.

Using the solution at the finest mesh level, get the electrostatic energy due to the interaction of the mobile charges with the potential:

for the NPBE and

for the LPBE. Here denotes the counterion species, is the bulk ionic strength, is the modified Debye-Huckel parameter, is the concentration of species , is the charge of species , and is the dimensionless electrostatic potential. The energy is scaled to units of .

Author:
Nathan Baker
Note:
The value of this observable may be modified by setting restrictions on the subdomain over which it is calculated. Such limits can be set via Vpmg_setPart and are generally useful for parallel runs.
Parameters:
thee  Vpmg object
extFlag  If this was a focused calculation, then it is possible to include the energy contributions from the outside the focused domain. This should be on (=1) for sequential focusing calculations and off (=0) for parallel calculations.
Returns:
The mobile charge electrostatic energy in units of .

void Vpmg_setPart Vpmg   thee,
double    lowerCorner[3],
double    upperCorner[3],
int    bflags[6]
 

Set partition information which restricts the calculation of observables to a (rectangular) subset of the problem domain.

Author:
Nathan Baker
Parameters:
thee  Vpmg object
lowerCorner  Partition lower corner
upperCorner  Partition upper corner
bflags  Whether or not a particular processor owns a face of it's partition. This keeps things disjoint. 0 if the face is not owned by this partition and 1 otherwise.

void Vpmg_solve Vpmg   thee
 

Solve the PBE using PMG.

Author:
Nathan Baker
Parameters:
thee  Vpmg object

void Vpmg_unsetPart Vpmg   thee
 

Remove partition restrictions.

Author:
Nathan Baker
Parameters:
thee  Vpmg object


Generated on Tue Feb 17 09:27:30 2004 for APBS by doxygen1.2.18