Main Page | Class List | Directories | File List | Class Members | File Members
mgrid

mgrid.h File Reference

Multilevel summation (a.k.a. multiple grid). More...

#include "mdapi/mdtypes.h"
#include "mgrid/lattice.h"

Go to the source code of this file.

Classes

struct  MgridCell_tag
 (For internal use only.) More...
struct  MgridParam_tag
 Helper class to configure Mgrid_tag class. More...
struct  MgridSystem_tag
 Helper class to provide and return results from Mgrid_tag class. More...
struct  Mgrid_tag
 Multilevel summation (a.k.a. multiple grid) solver. More...

Typedefs

typedef MgridCell_tag MgridCell
 (For internal use only.)
typedef MgridParam_tag MgridParam
 Helper class to configure Mgrid_tag class.
typedef MgridSystem_tag MgridSystem
 Helper class to provide and return results from Mgrid_tag class.
typedef Mgrid_tag Mgrid
 Multilevel summation (a.k.a. multiple grid) solver.

Enumerations

enum  { MGRID_FAIL = -1 }
enum  MgridBoundary_tag { MGRID_BOUNDARY_BEGIN = 0, MGRID_PERIODIC, MGRID_NONPERIODIC, MGRID_BOUNDARY_END }
 Boundary conditions. More...
enum  MgridApprox_tag {
  MGRID_APPROX_BEGIN = 0, MGRID_CUBIC, MGRID_BSPLINE, MGRID_QUINTIC1,
  MGRID_QUINTIC2, MGRID_HEPTIC1, MGRID_HEPTIC3, MGRID_NONIC1,
  MGRID_NONIC4, MGRID_HERMITE, MGRID_APPROX_END
}
 Approximation. More...
enum  MgridSplit_tag {
  MGRID_SPLIT_BEGIN = 0, MGRID_TAYLOR1, MGRID_TAYLOR2, MGRID_TAYLOR3,
  MGRID_TAYLOR4, MGRID_TAYLOR5, MGRID_TAYLOR6, MGRID_TAYLOR7,
  MGRID_TAYLOR8, MGRID_ERRMIN3, MGRID_EXSELF1, MGRID_EXSELF2,
  MGRID_EXSELF3, MGRID_EXSELF7, MGRID_ODDPR1, MGRID_ODDPR2,
  MGRID_ODDPR3, MGRID_ODDPR4, MGRID_ODDPR5, MGRID_ODDPR6,
  MGRID_ODDPR7, MGRID_ODDPR8, MGRID_SPLIT_END
}
 Splitting. More...

Functions

int mgrid_param_config (MgridParam *p)
 Chooses suitable MgridParam_tag parameters.
int mgrid_string_to_boundary (const char *)
 Convert string to boundary option.
const char * mgrid_boundary_to_string (int)
 Convert boundary option to string.
int mgrid_string_to_approx (const char *)
 Convert string to approximation option.
const char * mgrid_approx_to_string (int)
 Convert approximation option to string.
int mgrid_string_to_split (const char *)
 Convert string to splitting option.
const char * mgrid_split_to_string (int)
 Convert splitting option to string.
int mgrid_init (Mgrid *)
 Constructor.
int mgrid_setup (Mgrid *, const MgridSystem *s, const MgridParam *p)
 Setup the Mgrid_tag object.
int mgrid_force (Mgrid *, MgridSystem *s)
 Compute electrostatic forces and potential energy.
void mgrid_done (Mgrid *)
 Destructor.
int mgrid_system_validate (const Mgrid *, const MgridSystem *s)
 Validate atomic positions.
int mgrid_exact_smooth (Mgrid *, MgridSystem *s)
 Compute exact smoothed part.
int mgrid_short_setup (Mgrid *)
int mgrid_ncubic_setup (Mgrid *, const MgridSystem *)
int mgrid_pcubic_setup (Mgrid *, const MgridSystem *)
int mgrid_nbspline_setup (Mgrid *, const MgridSystem *)
int mgrid_pbspline_setup (Mgrid *, const MgridSystem *)
int mgrid_nquintic1_setup (Mgrid *, const MgridSystem *)
int mgrid_pquintic1_setup (Mgrid *, const MgridSystem *)
int mgrid_nquintic2_setup (Mgrid *, const MgridSystem *)
int mgrid_pquintic2_setup (Mgrid *, const MgridSystem *)
int mgrid_nheptic1_setup (Mgrid *, const MgridSystem *)
int mgrid_pheptic1_setup (Mgrid *, const MgridSystem *)
int mgrid_nheptic3_setup (Mgrid *, const MgridSystem *)
int mgrid_pheptic3_setup (Mgrid *, const MgridSystem *)
int mgrid_nnonic1_setup (Mgrid *, const MgridSystem *)
int mgrid_pnonic1_setup (Mgrid *, const MgridSystem *)
int mgrid_nnonic4_setup (Mgrid *, const MgridSystem *)
int mgrid_pnonic4_setup (Mgrid *, const MgridSystem *)
int mgrid_nhermite_setup (Mgrid *, const MgridSystem *)
int mgrid_phermite_setup (Mgrid *, const MgridSystem *)
int mgrid_setup_longrange (Mgrid *, const MgridSystem *)

Detailed Description

Multilevel summation (a.k.a. multiple grid).

Author:
David J. Hardy
Date:
2003-2005
The Mgrid_tag class provides a fast method for computing electrostatics. This multilevel summation method produces smooth potential energy and continuous forces for both nonperiodic and periodic boundary conditions. The approximation utilizes a repeated smooth splitting of the interaction potential into a short-range part evaluated directly and a slowly varying long-range part which is interpolated to a lattice. Repeated use of this idea gives rise to a hierarchical method for which, under reasonable assumptions, the computational cost is linear in the number of atoms.

The original paper detailing this method for nonperiodic systems is

Further analysis, improvements, and the extension of the method to periodic boundaries are presented in my dissertation, which should be available shortly.

Caveats:

See the notes for MgridParam_tag for recommended parameter selection.

Typedef Documentation

typedef struct Mgrid_tag Mgrid
 

Multilevel summation (a.k.a. multiple grid) solver.

Members should be treated as private.

typedef struct MgridParam_tag MgridParam
 

Helper class to configure Mgrid_tag class.

User sets the internal fields of this class in order to configure the parameters needed by Mgrid_tag class. The MgridParam_tag class is intended to be setup once and used to initialize the Mgrid_tag class.

The recommended parameters depend on the accuracy desired:

  • for low accuracy choose: $ 3 \leq $ spacing $ \leq 4 $ , cutoff $ \approx 8 $ , approx $ = $ MGRID_CUBIC, split $ = $ MGRID_TAYLOR2.
  • for medium accuracy choose: spacing $ \approx 3 $ , $ 8 \leq $ cutoff $ \leq 12 $ , approx $ = $ MGRID_QUINTIC1, split $ = $ MGRID_TAYLOR3.
  • for high accuracy choose: $ 2 \leq $ spacing $ \leq 3 $ , cutoff $ \approx 12 $ , approx $ = $ MGRID_HEPTIC1, split $ = $ MGRID_TAYLOR4 (or perhaps MGRID_NONIC1 and MGRID_TAYLOR5).

typedef struct MgridSystem_tag MgridSystem
 

Helper class to provide and return results from Mgrid_tag class.

User sets the internal fields of this class in order to provide data to Mgrid_tag class and receive its results. The user retains ownership of the arrays. The arrays are of length MgridParam_tag::natoms.

Input:
The pos and charge arrays must be provided. The atomic positions in pos must map into the cubic domain defined by MgridParam_tag. For periodic simulations, this means that they might have to be "wrapped" back into the box. Depending on the desired units, the atomic charges supplied to the charge array will need to be weighted by the square root of the conversion constant.

Optional input:
The excl_list and scaled14_list are jagged arrays as defined by the force library. These are supplied if the user wishes the mgrid library to compute electrostatic exclusions, along with scaling14 multiplicative constant if applicable. All things considered, there is no discernible numerical advantage to having electrostatic exclusions subtracted out sooner rather later, so it is probably best to just have the force library deal with it.

Output:
The electrostatic potential energy is returned in u_elec, the sum of the short-range part u_short and the long-range part u_long. The array f_elec designated to receive the electrostatic forces must be provided. The arrays f_short and f_long provide, respectively, the short-range and long-range parts of the force for each atom, intended for diagnostic purposes.

Enumeration Type Documentation

anonymous enum
 

Enumerator:
MGRID_FAIL  Return value from failed function call.

enum MgridApprox_tag
 

Approximation.

Set MgridParam_tag::approx to indicate choice of the approximation scheme.

Enumerator:
MGRID_CUBIC  Cubic numerical Hermite interpolation, $\mathrm{C}^1 $ continuous.
MGRID_BSPLINE  B-spline approximation, $\mathrm{C}^2 $ continuous.
MGRID_QUINTIC1  Quintic polynomial interpolation, $\mathrm{C}^1 $ continuous.
MGRID_QUINTIC2  Quintic polynomial interpolation, $\mathrm{C}^2 $ continuous.
MGRID_HEPTIC1  Heptic (7th degree) polynomial interpolation, $\mathrm{C}^1 $ continuous.
MGRID_HEPTIC3  Heptic (7th degree) polynomial interpolation, $\mathrm{C}^3 $ continuous.
MGRID_NONIC1  Nonic (9th degree) polynomial interpolation, $\mathrm{C}^1 $ continuous.
MGRID_NONIC4  Nonic (9th degree) polynomial interpolation, $\mathrm{C}^4 $ continuous.
MGRID_HERMITE  Hermite interpolation, $\mathrm{C}^1 $ continuous.

enum MgridBoundary_tag
 

Boundary conditions.

Set MgridParam_tag::boundary to indicate boundary conditions.

Enumerator:
MGRID_PERIODIC  Periodic boundary conditions.
MGRID_NONPERIODIC  Nonperiodic boundary conditions.

enum MgridSplit_tag
 

Splitting.

Set MgridParam_tag::split to indicate choice of splitting. This selects the function that will be approximated.

Enumerator:
MGRID_TAYLOR1  1st order Taylor polynomial in $ r^2 $ , $\mathrm{C}^1 $ continuous.
MGRID_TAYLOR2  2nd order Taylor polynomial in $ r^2 $ , $\mathrm{C}^2 $ continuous.
MGRID_TAYLOR3  3rd order Taylor polynomial in $ r^2 $ , $\mathrm{C}^3 $ continuous.
MGRID_TAYLOR4  4th order Taylor polynomial in $ r^2 $ , $\mathrm{C}^4 $ continuous.
MGRID_TAYLOR5  5th order Taylor polynomial in $ r^2 $ , $\mathrm{C}^5 $ continuous.
MGRID_TAYLOR6  6th order Taylor polynomial in $ r^2 $ , $\mathrm{C}^6 $ continuous.
MGRID_TAYLOR7  7th order Taylor polynomial in $ r^2 $ , $\mathrm{C}^7 $ continuous.
MGRID_TAYLOR8  8th order Taylor polynomial in $ r^2 $ , $\mathrm{C}^8 $ continuous.
MGRID_ERRMIN3  Degree 3 polynomial in $ r^2 $ , $\mathrm{C}^2 $ continuous, that minimizes the maximum error bound for cubic numerical Hermite interpolation.
MGRID_EXSELF1  Smoothed part is piecewise-defined degree 3 to degree 1 polynomial in $ r^2 $ , $\mathrm{C}^2 $ continuous, computes exact self-forces within $ \frac{1}{2} a $ .
MGRID_EXSELF2  Smoothed part is piecewise-defined degree 3 to degree 1 polynomial in $ r^2 $ , $\mathrm{C}^2 $ continuous, computes exact self-forces within $ \frac{1}{3} a $ .
MGRID_EXSELF3  Smoothed part is piecewise-defined degree 3 to degree 1 polynomial in $ r^2 $ , $\mathrm{C}^2 $ continuous, computes exact self-forces within $ \frac{1}{4} a $ .
MGRID_EXSELF7  Smoothed part is piecewise-defined degree 3 polynomial in $ r $ to degree 1 polynomial in $ r^2 $ , $\mathrm{C}^2 $ continuous, computes exact self-forces within $ \frac{1}{2} a $ .
MGRID_ODDPR1  Smoothed part contains some odd powers of $ r $ , $\mathrm{C}^1 $ continuous.
MGRID_ODDPR2  Smoothed part contains some odd powers of $ r $ , $\mathrm{C}^2 $ continuous.
MGRID_ODDPR3  Smoothed part contains some odd powers of $ r $ , $\mathrm{C}^3 $ continuous.
MGRID_ODDPR4  Smoothed part contains some odd powers of $ r $ , $\mathrm{C}^4 $ continuous.
MGRID_ODDPR5  Smoothed part contains some odd powers of $ r $ , $\mathrm{C}^5 $ continuous.
MGRID_ODDPR6  Smoothed part contains some odd powers of $ r $ , $\mathrm{C}^6 $ continuous.
MGRID_ODDPR7  Smoothed part contains some odd powers of $ r $ , $\mathrm{C}^7 $ continuous.
MGRID_ODDPR8  Smoothed part contains some odd powers of $ r $ , $\mathrm{C}^8 $ continuous.

Function Documentation

const char* mgrid_approx_to_string (  int   ) 
 

Convert approximation option to string.

Provide diagnostic information by converting MgridParam_tag::approx to a meaningful string form.

Returns:
Corresponding string form or "unknown" if value is out of range.

const char* mgrid_boundary_to_string (  int   ) 
 

Convert boundary option to string.

Provide diagnostic information by converting MgridParam_tag::boundary to a meaningful string form.

Returns:
Corresponding string form or "unknown" if value is out of range.

void mgrid_done (  Mgrid *   ) 
 

Destructor.

Frees memory allocations made internally during mgrid_setup(). Call when finished using Mgrid_tag object.

int mgrid_exact_smooth (  Mgrid *  ,
MgridSystem *  s
) 
 

Compute exact smoothed part.

Parameters:
[in,out] s Provides input data and receives results.
For nonperiodic boundaries, this routine computes the all pairs solution for the smoothed (long-range) part. This is a quadratic computation, provided solely for the purpose of analysis.

int mgrid_force (  Mgrid *  ,
MgridSystem *  s
) 
 

Compute electrostatic forces and potential energy.

Parameters:
[in,out] s Provides input data and receives results.
This routine performs the multilevel summation computation. The MgridSystem_tag object s must provide the atomic positions (wrapped into the cubic domain) and the (possibly weighted) charges. The updated force array(s) and potential energy values are returned. It is intended that this routine may be called successively during a simulation with updated positions provided.

Returns:
0 for success or MGRID_FAIL on failure.

int mgrid_init (  Mgrid *   ) 
 

Constructor.

Initializes a Mgrid_tag object. Must call this routine first.

Returns:
0 for success or MGRID_FAIL on failure.

int mgrid_param_config (  MgridParam *  p  ) 
 

Chooses suitable MgridParam_tag parameters.

Parameters:
[in,out] p Partially initialized MgridParam_tag object.
Given some number of parameters, this function tries to determine the rest of the parameters. The following parameters must be set: If periodic boundaries are employed, then MgridParam_tag::length must also be set.

The method of filling in the remaining parameters differs depending on the selected boundary conditions.

For periodic boundaries, the number of spacings MgridParam_tag::nspacings is chosen to be a power of 2 such that MgridParam_tag::spacing is no smaller than that provided. If MgridParam_tag::nspacings is set but not MgridParam_tag::spacing, then MgridParam_tag::nspacings is changed to be a power of 2 no larger than the amount given. MgridParam_tag::nlevels is set to its maximum amount.

For nonperiodic boundaries, any of MgridParam_tag::length, MgridParam_tag::spacing, MgridParam_tag::nspacings can be determined if two are provided. MgridParam_tag::nlevels is set to its maximum amount.

Returns:
0 for success or MGRID_FAIL on failure.

int mgrid_setup (  Mgrid *  ,
const MgridSystem *  s,
const MgridParam *  p
) 
 

Setup the Mgrid_tag object.

Parameters:
[in] s The charges are needed for the system.
[in] p The completely filled in MgridParam_tag object.
This routine performs memory allocation and computes tables of constants needed for efficient force evaluation. It is intended that this routine is called once before a simulation begins.

The only thing needed from s are the charges, which should not change between calls to the force evaluation function.

The MgridParam_tag object p must be completely filled in, presumably from a successful call to mgrid_param_config().

Returns:
0 on success or MGRID_FAIL on failure.

const char* mgrid_split_to_string (  int   ) 
 

Convert splitting option to string.

Provide diagnostic information by converting MgridParam_tag::split to a meaningful string form.

Returns:
Corresponding string form or "unknown" if value is out of range.

int mgrid_string_to_approx (  const char *   ) 
 

Convert string to approximation option.

Assist in configuring MgridParam_tag by converting strings into their MgridApprox_tag values. Leave off the "MGRID_" prefix; string matching is not case sensitive.

Returns:
Nonzero approximation value or 0 if string is not recognized.

int mgrid_string_to_boundary (  const char *   ) 
 

Convert string to boundary option.

Assist in configuring MgridParam_tag by converting the strings "periodic" and "nonperiodic" into their MgridBoundary_tag values.

Returns:
Nonzero boundary value or 0 if string is not recognized.

int mgrid_string_to_split (  const char *   ) 
 

Convert string to splitting option.

Assist in configuring MgridParam_tag by converting strings into their MgridSplit_tag values. Leave off the "MGRID_" prefix; string matching is not case sensitive.

Returns:
Nonzero splitting value or 0 if string is not recognized.

int mgrid_system_validate (  const Mgrid *  ,
const MgridSystem *  s
) 
 

Validate atomic positions.

Parameters:
[in] s Provides atomic positions.
Given that Mgrid_tag has been setup by mgrid_setup(), this routine verifies that all positions are within the cubic domain.

Returns:
The number of atoms MgridParam_tag::natoms is returned on success. Otherwise, the index of the first atom found outside the domain is returned.

Generated on Mon Sep 26 10:55:19 2005 for MDX by  doxygen 1.4.4