Boundary-element Poisson-Boltzmann calculations

This input file section documents boundary element method calculations with TABI-PB.

Parameters for a boundary-element polar solvation calculation.

class apbs.input_file.calculate.boundary_element.BoundaryElement(dict_=None, yaml=None, json=None)[source]

Bases: apbs.input_file.InputFile

Parameters for a boundary element linearized Poisson-Boltzmann polar solvation calculation.

Boundary element methods offer the ability to focus numerical effort on a much smaller region of the problem domain: the interface between the molecule and the solvent. In this method, two coupled integral equations defined on the solute-solvent boundary define a mathematical relationship between the electrostatic surface potential and its normal derivative with a set of integral kernels consisting of Coulomb and screened Coulomb potentials with their normal derivatives. The boundary element method requires a surface triangulation, generated by a program such as NanoShaper, on which to discretize the integral equations.

Objects can be initialized with dictionary/JSON/YAML data with the following keys:

calculate_energy

Indicate whether energy should be calculated.

Raises:TypeError – if not Boolean
calculate_forces

Indicate whether forces should be calculated.

Raises:TypeError – if not Boolean
error_tolerance

Relative error tolerance for iterative solver.

If not specified, the default value is ERROR_TOLERANCE.

Raises:
from_dict(input_)

Parse dictionary-format input into this object.

Parameters:input (dict) – input dictionary
Raises:KeyError – when input is missing
from_json(input_)

Parse JSON-format input string into this object.

Parameters:input (str) – JSON-format input string
from_yaml(input_)

Parse YAML-format input string into this object.

Parameters:input (str) – YAML-format input string
ions

Descriptions of mobile ion species.

Raises:TypeError – if not set to a Ions object
mesh

Parameters for the boundary mesh.

Raises:TypeError – if not set to Mesh object.
molecule

Specify which molecule to use for calculation.

Returns:alias for molecule read (see Data loading input file section (required))
Raises:TypeError – if not set to a string
solute_dielectric

Solute dielectric.

The dielectric value of a solute is often chosen using the following rules of thumb:

  • 1: only used to compare calculation results with non-polarizable molecular simulation
  • 2-4: “molecular” dielectric value; used when conformational degrees of freedom are modeled explicitly
  • 4-8: used to mimic sidechain libration and other small-scale conformational degrees of freedom
  • 8-12: used to model larger-scale sidechain rearrangement
  • 20-40: used to model larger-scale macromolecular conformational changes and/or water penetration into interior of molecule

Note

What does the continuum dielectric value of a non-continuum molecule mean? Hard to say – this approximation can be very difficult to interpret and can significant affect your results.

Returns:

a floating point number greater than or equal to one
Raises:
solvent_dielectric

Solvent dielectric.

78.5 is a good choice for water at 298 K.

Returns:

a floating point number greater than or equal to one
Raises:
solver

Boundary element solver.

Allowed values are one of the following:

  • tabi: the Treecode-Accelerated Boundary Integral (TABI) solver. For more information, see the Geng & Krasny 2013 J Comput Phys paper.

Each value must be accompanied by the corresponding solver parameters, set via solver_parameters().

Raises:
solver_parameters

Parameters for specified solver.

Returns:an object derived from InputFile based on the solver() property:
Raises:TypeError – if object is not derived from InputFile
temperature

Temperature for the calculation in Kelvin.

Raises:ValueError – if not a positive number (no violations of the 3rd Law!)
to_dict() → dict

Produce dictionary representation of self.

to_json() → str

Produce JSON representation of self.

to_yaml() → str

Produce YAML representation of self.

validate()[source]

Validate the object.

Raises:ValueError – if object is not valid
write_atom_potentials

Write out the electrostatic potential at each atom location.

Write out text file with potential at center of atom in units of \(k_b \, T \, e_c^{-1}\).

Note

These numbers are meaningless by themselves due to the presence of “self-energy” terms that are sensitive to grid spacing and position. These numbers should be evaluated with respect to a reference calculation: the potentials from that reference calculation should be subtracted from the target system. For example, one calculation might include a molecule with a heterogeneous dielectric coefficient and the reference system might be exactly the same system setup but with a homeogeneous dielectric coefficient. If the results from the reference calculation are substracted from the first calculation, then the result will be a physically meaningful reaction field potential. However, the results from the first and reference calculations are meaningless by themselves.

Returns:path to text file for writing atom potential values.
Raises:TypeError – if not set to string
class apbs.input_file.calculate.boundary_element.Mesh(dict_=None, yaml=None, json=None)[source]

Bases: apbs.input_file.InputFile

Boundary element mesh input.

Objects can be initialized with dictionary/JSON/YAML data with the following keys:

from_dict(input_)

Parse dictionary-format input into this object.

Parameters:input (dict) – input dictionary
Raises:KeyError – when input is missing
from_json(input_)

Parse JSON-format input string into this object.

Parameters:input (str) – JSON-format input string
from_yaml(input_)

Parse YAML-format input string into this object.

Parameters:input (str) – YAML-format input string
software

Software for generating mesh.

One of the following values:

  • nanoshaper: NanoShaper software <https://www.electrostaticszone.eu/downloads>

Note

The user is responsible for downloading the software and ensuring that it is available in their path.

Raises:
solvent_radius

Radius of the solvent molecules.

This parameter is used to define various solvent-related surfaces and volumes (see surface_method()). This value is usually set to 1.4 Å for a water-like molecular surface and set to 0 Å for a van der Waals surface.

Raises:ValueError – if value is not a non-negative number
surface_density

Number of points per area on surface.

Units are number per Å2 and are used in calculation of surface terms (e.g., molecular surface, solvent accessible surface). This keyword is ignored when surface_radius() is 0.0 (e.g., for van der Waals surfaces) or if surface method() refers to splines.

A typical value is 10.0.

Raises:ValueError – if value is not a positive number
surface_method

Method to compute molecular surface (boundary).

One of the following:

  • molecular surface: The problem domain is divided into two spaces with the boundary defined as the interface between these spaces. The “free volume” space is defined by the union of solvent-sized spheres (see solvent_radius()) which do not overlap with the solute atoms. This free volume is assigned bulk solvent dielectric values. The complement of this space is assigned solute dielectric values. When the solvent radius is set to zero, this method corresponds to a van der Waals surface definition. The ion-accessibility coefficient is defined by an “inflated” van der Waals model. Specifically, the radius of each biomolecular atom is increased by the radius of the ion species (as specified with the ion() property). The problem domain is then divided into two spaces. The space inside the union of these inflated atomic spheres is assigned an ion-accessibility value of 0; the complement space is assigned the bulk ion accessibility value. See Connolly ML, J Appl Crystallography 16 548-558, 1983 (10.1107/S0021889883010985).
  • skin: Edelsbrunner molecular skin as defined in Edelsbrunner, H.
    “Deformable Smooth Surface Design.” Discrete and Computational Geometry 21, no. 1 (January 1, 1999): 87–115. DOI:10.1007/PL00009412.
Raises:
to_dict() → dict

Produce dictionary representation of self.

to_json() → str

Produce JSON representation of self.

to_yaml() → str

Produce YAML representation of self.

validate()

Validate the object.

Raises:ValueError – if object is not valid
class apbs.input_file.calculate.boundary_element.TABIParameters(dict_=None, yaml=None, json=None)[source]

Bases: apbs.input_file.InputFile

Parameters for the TABI solver.

“TABI” is the the Treecode-Accelerated Boundary Integral (TABI) solver. For more information, see the Geng & Krasny 2013 J Comput Phys paper.

Objects can be initialized with dictionary/JSON/YAML data with the following keys:

from_dict(input_)

Parse dictionary-format input into this object.

Parameters:input (dict) – input dictionary
Raises:KeyError – when input is missing
from_json(input_)

Parse JSON-format input string into this object.

Parameters:input (str) – JSON-format input string
from_yaml(input_)

Parse YAML-format input string into this object.

Parameters:input (str) – YAML-format input string
maximum_particles

The maximum number of particles in the tree-code leaf.

This controls leaf size in the process of building the tree structure. A typical value for this parameter is 500.

Raises:
multipole_acceptance_criterion

The multipole acceptance criterion (MAC) controls the distance ratio at which the method uses direct summation or Taylor approximation (a particle-cluster interaction) to calculate the integral kernels.

The MAC is related to cluster characteristics by \(\frac{r_c}{R}\leqslant \theta\), where \(r_c\) is the cluster radius, \(R\) is the distance of the particle to the cluster center, and \(0 < \theta < 1\). If the this relationship is satisfied, then the Taylor approximation will be used instead of direct summation.

A typical value for this parameter is 0.8.

Raises:ValueError – if not a positive number less than 1.
to_dict() → dict

Produce dictionary representation of self.

to_json() → str

Produce JSON representation of self.

to_yaml() → str

Produce YAML representation of self.

tree_order

Specifies the order of the treecode multipole expansion.

This is an integer that indicates the Taylor expansion order. Users can adjust the order for different accuracy.

A typical choice for this parameter is 3.

Raises:
validate()

Validate the object.

Raises:ValueError – if object is not valid