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
: seecalculate_energy()
calculate forces
: seecalculate_forces()
error tolerance
: solver error tolerance; seeerror_tolerance()
ions
: information about mobile ion species; seeions()
molecule
: alias to molecule for calculation; seemolecule()
solute dielectric
: seesolute_dielectric()
solvent dielectric
: seesolvent_dielectric()
solver
: seesolver()
solver parameters
: see func:solver_parameterstemperature
: seetemperature()
mesh
: specify how the mesh is obtained; seemesh()
write atom potentials
: write out atom potentials; see
- property calculate_energy: bool
Indicate whether energy should be calculated.
- Raises
TypeError – if not Boolean
- property calculate_forces: bool
Indicate whether forces should be calculated.
- Raises
TypeError – if not Boolean
- property error_tolerance: float
Relative error tolerance for iterative solver.
If not specified, the default value is
ERROR_TOLERANCE
.- Raises
TypeError – if not set to positive number
ValueError – if not set to number less than 1
- abstract 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
- property ions: apbs.input_file.calculate.generic.MobileIons
Descriptions of mobile ion species.
- Raises
TypeError – if not set to a
Ions
object
- property mesh: apbs.input_file.calculate.boundary_element.Mesh
Parameters for the boundary mesh.
- Raises
TypeError – if not set to
Mesh
object.
- property molecule: str
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
- property solute_dielectric: float
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
TypeError – if not a number
ValueError – if not greater than or equal to 1
- property solvent_dielectric: float
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
TypeError – if not a number
ValueError – if not greater than or equal to 1
- property solver: str
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
TypeError – if not set to string.
ValueError – if set to invalid string.
- property solver_parameters: apbs.input_file.InputFile
Parameters for specified solver.
- Returns
an object derived from
InputFile
based on thesolver()
property:tabi
: returns object of typeTABIParameters
- Raises
TypeError – if object is not derived from
InputFile
- property temperature: float
Temperature for the calculation in Kelvin.
- Raises
ValueError – if not a positive number (no violations of the 3rd Law!)
- abstract to_dict() dict
Produce dictionary representation of self.
- to_json() str
Produce JSON representation of self.
- to_yaml() str
Produce YAML representation of self.
- property write_atom_potentials: str
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:
software
: software to use when generating the mesh; seesoftware()
solvent radius
: seesolvent_radius()
.surface density
: seesurface_density()
.surface method
: seesurface_method()
.
- abstract 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
- property software: str
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
TypeError – if not set to a string
ValueError – if set to an invalid value
- property solvent_radius: float
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
- property surface_density: float
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 ifsurface method()
refers to splines.A typical value is 10.0.
- Raises
ValueError – if value is not a positive number
- property surface_method: str
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 (seesolvent_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 theion()
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
TypeError – if not set to string.
ValueError – if not set to valid value.
- abstract to_dict() dict
Produce dictionary representation of self.
- to_json() str
Produce JSON representation of self.
- to_yaml() str
Produce YAML representation of self.
- abstract 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:
maximum particles
: the maximum number of particles in a tree leaf; seemaximum_particles()
.multipole acceptance criterion
: seemultipole_acceptance_criterion()
.tree order
: seetree_order()
.
- abstract 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
- property maximum_particles: int
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
ValueError – if not set to a positive number
TypeError – if not set to an integer
- property multipole_acceptance_criterion: float
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.
- abstract to_dict() dict
Produce dictionary representation of self.
- to_json() str
Produce JSON representation of self.
- to_yaml() str
Produce YAML representation of self.
- property tree_order: int
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
TypeError – if not an integer
ValueError – if not a positive number.
- abstract validate()
Validate the object.
- Raises
ValueError – if object is not valid