%% LyX 1.5.6 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[english,preprint]{revtex4}
\usepackage[T1]{fontenc}
\usepackage[latin9]{inputenc}
\usepackage{babel}

\begin{document}

\title{MATLAB example: The Born-ion model}

\begin{abstract}
Let's consider the born-ion model at room temperature (T=298.15 C).
Inside the born radius (r=3A) the low dielectric coefficient representing
the molecule is set equal to $\epsilon^{x}=\epsilon^{y}=\epsilon^{z}=1.0$.
This ion is located at the origin of the reference system and it is
immersed in a solvent medium of dielectric coefficient that mimic
water, e.g., with $\epsilon^{x}=\epsilon^{y}=\epsilon^{z}=78.54$.
The bulk ionic strength is set equal to zero. The born ion charge
valence is set equal to $z=+1$. To solve the PB equation we will
use a cubic grid of 65 points and a box length of 12 A centered at
the ion position. We will use the linear B-spline to obtain the fractional
charge at the node points. 
\end{abstract}
\maketitle

\part{Using the MATLAB PB SOLVER}


\subsection*{Input files as generated by the APBS and pdb2pqr codes}

The {}``born-ion.pqr'' file corresponding to the model described
above reads

\begin{quotation}
ATOM 1 I ION 1 0.000 0.000 0.000 1.00 3.00
\end{quotation}
As an example, the {}``born.in'' input file used by the APBS reads

\begin{quotation}
\# READ IN MOLECULES

read 

mol pqr born-ion.pqr

end

\# COMPUTE POTENTIAL FOR SOLVATED STATE

elec name solvated

mg-auto 

dime 65 65 65

cglen 50 50 50

fglen 12 12 12

fgcent mol 1

cgcent mol 1

mol 1

lpbe

bcfl mdh

pdie 1.0

sdie 78.54

chgm spl0

srfm spl2

srad 1.4

swin 0.3

sdens 10.0

temp 298.15

calcenergy total

calcforce no

write pot dx APBS-born-pot

write charge dx born-charge

write dielx dx born-dielx

write diely dx born-diely

write dielz dx born-dielz

write kappa dx born-kappa

end

quit
\end{quotation}
For example, if you saved both files 'born-ion.pqr'' and 'born.in'
in the directory 'C:/Users/me/Documents/APBS\_PB\_solver/', you may
type in your command prompt window

\begin{quotation}
C:/Users/me/Documents/Matlab\_PB\_solver>apbs born.in
\end{quotation}
In this way we obtain the input files in dx format required by the
MATLAB version of the APBS to solve the PB equation. Specifically,
we obtain the shifted dielectric coefficients maps born-dielx.dx,
born-diely.dx, born-dielz.dx, and the ion accessibility map born-kappa.dx.
We also obtain the charge density born-charge.dx and the electrostatic
potential born-pot.dx maps which will be used later for testing purpose.


\subsection*{MATLAB input file}

Now we are ready to write the input file {}``born.inm'' as follows

\begin{quotation}
65 65 65

12 12 12

298.15

born-dielx.dx

born-diely.dx

born-dielz.dx

born-kappa.dx

born-ion.pqr

born\_ion\_model
\end{quotation}
The first line corresponds to the number of grid of points $[N_{x}N_{y}N_{z}]$;
the second line corresponds to the length in Anstrong of the boxsides
$[L_{x}L_{y}L_{z}]$; the next line corresponds to the temperature
in Celsius degree; next is the name of the dx file containing the
shifted dielectric coefficients along the x direction; next is for
the one corresponding to the y-direction and next the one in the z-direction.
The seventh line corresponds to the name of the ion accessibility
coefficient map. The next one corresponds to the name of the pqr file
generated by the pdb2pqr code and the last line corresponds to the
name of the folder that will be created into the current (working)
folder (for instances 'Matlab\_PB\_solver') where all the Matlab files
of our code are saved. In the folder {}``born\_ion\_model'' you
will find all the files generated by our Matlab code, namely electrostatic
potential and the charge maps in dx format, and the electrostatic
potential surface $u_{ij(N_{z}+1)/2}$ in both jpg and fig format. 


\subsection*{Before using our Matlab code}

Before running the {}``main.m'' file in the Matlab console you must
create a folder (for instances {}``Matlab\_Input\_Files'') in the
same directory (For instances 'C:/Users/me/Documents/Matlab\_PB\_solver/')
in which all the Matlab files of our code are saved. Then you must
save the input files born-ion.inm, born-ion.pqr, born-dielx.dx, born-diely.dx,
born-dielz.dx, and born-kappa.dx in the folder {}``Matlab\_Input\_Files''. 

Next, you must edit two lines in the {}``main.m'' file to know:

\begin{itemize}
\item The line number 57 contains the path to the folder {}``Matlab\_Input\_Files''.
In our example you have to set the path as follows
\end{itemize}
\begin{quotation}
MYPATH='C:/Users/me/Documents/Matlab\_PB\_solver/Matlab\_Input\_Files';
\end{quotation}
\begin{itemize}
\item The line number 65 contains the name of the inm input file. In our
example we termed it as {}``born-ion.inm'' such that we have to
set the name of the inputfile as follows
\end{itemize}
\begin{quotation}
inputfile='born-ion.inm';
\end{quotation}
Now we are ready to run the main.m file. In the command window of
Matlab you may type

\begin{quotation}
>\textcompwordmark{}>run C:/Users/me/Documents/Matlab\_PB\_solver/main
\end{quotation}
You are done. On the same command window you will see information
about the different steps that our code performs to get the required
solution. 


\subsection*{Matlab output files}

In this example you will find a created folder named 'born\_ion\_model'
in the directory 'C:/Users/me/Documents/Matlab\_PB\_solver/' containing
the following files

\begin{quotation}
born\_ion\_model\_MATLAB\_charge\_density.dx

born\_ion\_model\_MATLAB\_potential\_solution.dx

born\_ion\_model\_MATLAB\_potential\_solution.jpg

born\_ion\_model\_MATLAB\_potential\_solution.fig
\end{quotation}

\subsection*{Accuracy and efficiency of our Matlab code}

You may change same parameters of our code in order to make it faster
and more efficient. In particular, the default accuracy is set equal
to 10\textasciicircum{}-9. You may change it by editing the main.m
file and change the variable 'accuracy' for the required precision.
You may also change the tolerance in the inexact LU decompostion.
The default value for the variable 'tolerance' is set equal to 0.25. 

\newpage


\part{Testing our code}


\subsection*{Before using our Matlab code}

Before running the {}``comparison.m'' file in the Matlab console
you must create a folder (for instances {}``Potential'') in the
same directory (For instances 'C:/Users/me/Documents/Matlab\_PB\_solver/')
in which all the Matlab files of our code are saved. Then you must
save in that folder the APBS and MATLAB electrostatic potential solutions.
In our example they are APBS-born-pot.dx and born\_ion\_model\_MATLAB\_potential\_solution.dx. 

Next, you must edit three lines in the {}``comparison.m'' file to
know:

\begin{itemize}
\item The line number 19 contains the path to the folder {}``Potential''.
In our example you have to set the path as follows
\end{itemize}
\begin{quotation}
MYPATH='C:/Users/me/Documents/Matlab\_PB\_solver/Potential';
\end{quotation}
\begin{itemize}
\item The line number 27 contains the number of grid points in the format
$[N_{x}N_{y}N_{z}]$. In our example we have to set
\end{itemize}
\begin{quotation}
dime= {[}65 65 65];
\end{quotation}
\begin{itemize}
\item The line number 29 contains the length of the boxside in the format
$[L_{x}L_{y}L_{z}]$ in anstromgs. In our example we have to set
\end{itemize}
\begin{quotation}
glen= {[}12 12 12];
\end{quotation}
Now we are ready to run the comparison.m file. In the command window
of Matlab you may type

\begin{quotation}
>\textcompwordmark{}>run C:/Users/me/Documents/Matlab\_PB\_solver/comparison
\end{quotation}
You are done. On the same command window you will see information
about the different steps that our code performs to get the required
solution. 


\subsection*{Matlab output files}

In this example you will find a created folder named 'COMPARATIVE\_ANALYSIS'
in the directory 'C:/Users/me/Documents/Matlab\_PB\_solver/' containing
the following files

\begin{quotation}
Absolute Error between MATLAB and APBS solutions.dx

Absolute\_error.fig

Absolute\_error.tiff

APBS-born-pot\_and\_born\_ion\_model\_MATLAB\_potential\_solution.fig

APBS-born-pot\_and\_born\_ion\_model\_MATLAB\_potential\_solution.tiff
\end{quotation}

\end{document}