.. _tabi:

tabi
==========

.. currentmodule::  apbs.input_file.calculate.boundary_element

.. note::
   
   This command has been ported to the *new APBS syntax* (see :ref:`new_input_format`); see :class:`BoundaryElement` and :class:`TABIParameters`.

This mode uses the TABI-PB integral equation software from Geng and Krasny to solve the linearized Poisson-Boltmzann equation. 
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 <https://www.electrostaticszone.eu/downloads>`_, on which to discretize the integral equations.

For more information, see the Geng & Krasny `2013 J Comput Phys paper <https://doi.org/10.1016/j.jcp.2013.03.056>`_.

.. toctree::
   :maxdepth: 1
   :caption: ELEC tabi keywords

   ion
   mac
   mesh
   ../generic/mol
   outdata
   pdie
   ../generic/sdens
   sdie
   ../generic/srad
   ../generic/temp
   tree_n0
   tree_order


======================
Background information
======================

The Treecode-Accelerated Boundary Integral Poisson-Boltzmann solver (TABI-PB; `Geng, 2013 <http://www.sciencedirect.com/science/article/pii/S0021999113002404>`_ calculates electrostatics of solvated biomolecules governed by the linearized Poisson-Boltzmann equation.
It uses a well-posed boundary integral Poisson-Boltzmann formulation to ensure rapid convergence.
In addition, a fast treecode algorithm for the screened Coulomb potential `(Li, 2009) <http://www.sciencedirect.com/science/article/pii/S0021999109000916>`_ is applied to speed up the matrix-vector products in each GMRES iteration.
The molecular surfaces, which divide the entire domain into solute region and solvent region, are generated by `NanoShaper <https://www.electrostaticszone.eu/downloads>`_.

-----------------
TABI-PB algorithm
-----------------

The coupled integral equations derived from the linearized Poisson-Boltzmann equation are

.. math::
   
   \frac{1}{2}(1+\epsilon)\phi({x})-\int_\Gamma(K_1({x},{y})\frac{\partial{\phi({y})}}{\partial{v}}+K_2({x},{y})\phi({y}))dS_{y} &=S_1({x}) \\
   \frac{1}{2}(1+\frac{1}{\epsilon})\frac{\partial{\phi({x})}}{\partial{v}}-\int_\Gamma(K_3({x},{y})\frac{\partial{\phi({y})}}{\partial{v}}+K_4({x},{y})\phi({y}))dS_{y} &=S_2({x}), {x}\in\Gamma

for the surface potential :math:`\phi`, and its normal derivative :math:`\frac{\partial\phi}{\partial v}` on the surface :math`\Gamma`.
The kernels :math:`K_{1,2,3,4}` are linear combinations of the Coulomb and screened Coulomb potentials:

.. math::
   
   G_0({x},{y}) &= \frac{1}{4\pi |{x}-{y}|} \\
   G_{\kappa}({x},{y}) &= \frac{e^{-\kappa|{x}-{y}|}}{4\pi |{x}-{y}|}

and their first and second derivatives.

The sums in the discretized form of the integral equations above have the form of *N*-body interactions,

.. math::
   
   V_i = \sum_{j=1,j \neq i}^{N} q_j G({x}_i,{x}_j), i=1,\ldots,N 

where :math:`G` is the screened Coulomb potential kernel, :math:`{x}_i, {x}_j` are the centroids of the triangles, and :math:`q_j` is the charge at :math:`{x}_j`.
The particles (centroids of the triangles) are divided into a hierarchy of clusters having a tree structure.
The treecode replaces the :math:`\mathcal{O}(N^2)` particle-particle interactions by :math:`\mathcal{O}(N \log N)` particle-cluster interactions and TABI-PB utilizes this feature efficiently.

======
Output
======

The TABI-PB code produces an output file called :file:`surface_potential.dat` containing:

* number of nodes, number of triangles
* node index, vertices, normal vector, surface potential (kJ mol\ :sup:`-1` e\ :sub:`c`\ :sup:`-1`), surface potential normal derivatives (kJ mol\ :sup:`-1` e\ :sub:`c`\ :sup:`-1` A\ :sup:`-1`)
* connectivity data for surface triangulation

The format is given below:

.. code-block:: bash
   
   num_node num_triangle
   node_index x y z norm_x norm_y norm_z phi norm_phi
   (et cetera)
   node_index1 node_index2 node_index3

The TABI-PB code prints the free energy of solvation and Coulombic free energy in kJ/mol, along with some other information such as CPU time and the GMRES residuals at each step.

Additionally, TABI-PB can optionally output a VTK polygonal data file containing color mappable potentials and normal derivatives of potentials on the faces and vertices of the mesh.
The VTK file can be visualized using `ParaView <https://www.paraview.org/>`_.

