Finite-element Poisson-Boltzmann calculations
Parameters for a finite-element polar solvation calculation.
- class apbs.input_file.calculate.finite_element.FiniteElement(dict_=None, yaml=None, json=None)[source]
Bases:
apbs.input_file.InputFile
Parameters for a finite-difference polar solvation Poisson-Boltzmann calculation.
Objects can be initialized with dictionary/JSON/YAML data with the following keys:
a priori refinement
: a priori mesh refinement strategy; seea_priori_refinement()
boundary condition
:boundary_condition()
calculate energy
: seecalculate_energy()
calculate forces
: seecalculate_forces()
charge discretization
: method used to map charges onto the grid; seecharge_discretization()
domain length
: seedomain_length()
error estimation
: how error is calculated for driving refinement; seeerror_estimation()
error-based refinement
: method for choosing which simplices to refine based on error; seeerror_based_refinement()
equation
: what version of the Poisson-Boltzmann equation to solve; seeequation()
ions
: information about mobile ion species; seeions()
initial mesh resolution
: target resolution of initial mesh; seeinitial_mesh_resolution()
initial mesh vertices
: target number of vertices in the initial finite element mesh; seeinitial_mesh_vertices()
maximum refinement iterations
: number of times to perform the solve-estimate-refine iteration of the finite element solver; seemaximum_refinement_iterations()
maximum vertices
: target for maximum number of vertices in mesh; seemaximum_vertices()
molecule
: alias to molecule for calculation; seemolecule()
no-op
: determine whether the solver should be run; seenoop()
solute dielectric
: seesolute_dielectric()
solvent dielectric
: seesolvent_dielectric()
solvent radius
: seesolvent_radius()
surface method
: seesurface_method()
surface spline window
: seesurface_spline_window()
temperature
: seetemperature()
use maps
: use input map for one or more properties of the system; seeuse_maps()
write atom potentials
: write out atom potentials; seewrite_atom_potentials()
write maps
: write out one or more properties of the system to a map; seewrite_maps()
- property a_priori_refinement: str
Strategy for refining the initial very coarse 8-tetrahedron initial finite element to a resolution suitable for the main solve-estimate-refine iteration.
Allowed values include:
geometric
: geometry-based refinement at molecular surface and chargesuniform
: uniform refinement of the mesh
- Raises
ValueError – if not set to allowed value
TypeError – if not set to string
- property boundary_condition: str
Boundary condition for Poisson-Boltzmann equation.
This property can have one of the following values:
zero
: Dirichlet condition where the potential at the boundary is set to zero. This condition is not commonly used and can result in large errors if used inappropriately.single sphere
: Dirichlet condition where the potential at the boundary is set to the values prescribed by a Debye-Hückel model for a single sphere with a point charge, dipole, and quadrupole. The sphere radius in this model is set to the radius of the biomolecule and the sphere charge, dipole, and quadrupole are set to the total moments of the protein. This condition works best when the boundary is sufficiently far (multiple Debye lengths) from the biomolecule.multiple sphere
: Dirichlet condition where the potential at the boundary is set to the values prescribed by a Debye-Hückel model for multiple, non-interacting spheres with a point charges. The radii of the non-interacting spheres are set to the atomic radii of and the sphere charges are set to the atomic charges. This condition works better thansingle sphere
for closer boundaries but can be very slow for large biomolecules.focus
alias
: Dirichlet condition where the potential at the boundary is set to the values computed by a previous (usually lower-resolution) PB calculation with aliasalias
. All of the boundary points should lie within the domain of the previous calculation for best accuracy; if any boundary points lie outside, their values are computed using thesingle sphere
Debye-Hückel boundary condition (see above).
- Raises
ValueError – if set to an invalid boundary type
IndexError – if an insufficient number of words are present
- 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 charge_discretization: str
The method by which the biomolecular point charges (i.e., Dirac delta functions) by which charges are mapped to the grid used for the finite difference calculation.
As we are attempting to model delta functions, the support (domain) of these discretized charge distributions is always strongly dependent on the grid spacing.
The following types of discretization are supported:
linear
: Traditional trilinear interpolation (linear splines). The charge is mapped onto the nearest-neighbor grid points. Resulting potentials are very sensitive to grid spacing, length, and position.cubic
: Cubic B-spline discretization. The charge is mapped onto the nearest- and next-nearest-neighbor grid points. Resulting potentials are somewhat less sensitive (thanlinear
) to grid spacing, length, and position.quintic
: Quintic B-spline discretization. Similar tocubic
, except the charge/multipole is additionally mapped to include next-next-nearest neighbors (125 grid points receive charge density).
- Raises
TypeError – if not set to string
ValueError – if not one of the allowed values above
- property domain_length: list
Length of rectangular prism domain.
- Returns
list of non-zero lengths for x, y, and z directions.
- Raises
TypeError – if not list of positive definite numbers.
IndexError – if list not length 3
- property equation: str
Specifies which version of the Poisson-Boltzmann equation (PBE) to solve:
Most users should use one of these:
linearized pbe
nonlinear pbe
These versions are experimental and unstable:
linearized regularized pbe
nonlinear regularized pbe
- Raises
TypeError – if not set to a string.
ValueError – if set to an invalid value
- property error_based_refinement: str
Specify error-based refinement strategy for simplices.
Can be assigned one of the following values:
global
: this refines simplices until the global error is less than the amount specified byerror_tolerance()
.simplex
: this refines simplices until the per-simplex error is less than the amount specified byerror_tolerance()
.fraction
: this refines the specified fraction of simplices with the largest per-simplex error. The fraction is specified byerror_tolerance()
.
- Raises
TypeError – if not set to string
ValueError – if not set to allowed value
- property error_tolerance: float
Error tolerance for error-based refinement of simplices.
The meaning of this property changes based on the setting of
error_based_refinement()
.raises TypeError: if not a positive number.
- from_dict(input_)[source]
Populate object from dictionary.
- Parameters
input (dict) – dictionary with input data.
- Raises
KeyError – if dictionary missing keys.
- 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 initial_mesh_resolution: float
Target spacing (in Å) of initial mesh.
Initial refinement will continue until this target spacing is met or until
initial_mesh_vertices()
is exceeded.- Raises
TypeError – if not set to a positive number
- property initial_mesh_vertices: int
Target number of vertices in initial mesh.
Initial refinement will continue until this number of vertices is exceeded or
initial_mesh_resolution()
is reached.- Raises
TypeError – if not set to a positive integer
- property ions: apbs.input_file.calculate.generic.MobileIons
Descriptions of mobile ion species.
- Raises
TypeError – if not set to a
Ions
object
- property maximum_refinement_iterations: int
Maximum number of solve-estimate-refine iterations.
The solve-estimate-refine loop will continue until this number of iterations is reached or the mesh has more than
maximum_vertices()
vertices.- Raises
TypeError – if not sent to positive integer
- property maximum_vertices: int
Maximum number of vertices produced in solve-estimate-refine iterations.
The solve-estimate-refine loop will continue until the mesh has more than this number of vertices or
maximum_refinement_iterations()
has been reached.- Raises
TypeError – if not sent to positive integer
- 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 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_method: str
Method used to defined solute-solvent interface.
One of the following values:
molecular surface
: The dielectric coefficient is defined based on a molecular surface definition. The problem domain is divided into two 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).smoothed molecular surface
: The dielectric and ion-accessibility coefficients are defined as for themolecular surface
(see above). However, they are then “smoothed” by a 9-point harmonic averaging to somewhat reduce sensitivity to the grid setup. See Bruccoleri et al. J Comput Chem 18 268-276, 1997 (10.1007/s00214-007-0397-0).cubic spline
: The dielectric and ion-accessibility coefficients are defined by a cubic-spline surface as described by Im et al, Comp Phys Commun 111 (1-3) 59-75, 1998 (10.1016/S0010-4655(98)00016-2). The width of the dielectric interface is controlled by thespline_window()
property. These spline-based surface definitions are very stable with respect to grid parameters and therefore ideal for calculating forces. However, they require substantial reparameterization of the force field; interested users should consult Nina et al, Biophys Chem 78 (1-2) 89-96, 1999 (10.1016/S0301-4622(98)00236-1). Additionally, these surfaces can generate unphysical results with non-zero ionic strengths.septic spline
: The dielectric and ion-accessibility coefficients are defined by a 7th order polynomial. This surface definition has characteristics similar to the cubic spline, but provides higher order continuity necessary for stable force calculations with atomic multipole force fields (up to quadrupole).
- Raises
TypeError – if not set to a string
ValueError – if set to invalid value
- property surface_spline_window: float
Window for spline-based surface definitions (not needed otherwise).
This is the distance (in Å) over which the spline transitions from the solvent dielectric value to the solute dielectric value. A typical value is 0.3 Å.
- Returns
positive number
- Raises
TypeError – if not a positive number
- property temperature: float
Temperature for the calculation in Kelvin.
- Raises
ValueError – if not a positive number (no violations of the 3rd Law!)
- to_json() str
Produce JSON representation of self.
- to_yaml() str
Produce YAML representation of self.
- property use_maps: list
Information for (optionally) using maps read into APBS.
- Returns
list of
UseMap
objects- Raises
TypeError – if not a list of
UseMap
objects
- validate()[source]
Validate this object.
Assumes that all attributes have been set via setters.
- Raises
ValueError – if object is invalid.
- 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
- property write_maps: list
Write out maps related to computed properties.
See
WriteMap
for more information.- Raises
TypeError – if set to wrong type