%% 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 two Born-ions model}

\begin{abstract}
Let's consider the two-ions complex model at room temperature (T=298.15
C). Inside the radius (r=1A) the low dielectric coefficient representing
the (solute) molecule is set equal to $\epsilon^{x}=\epsilon^{y}=\epsilon^{z}=2.0$.
The positive ion (with valence equal to $z=+1)$ is located at the
position $(1,1,1)$ in amstrongs and the negative ion (with valence
equal to $z=-1)$ is located at the position $(-1,-1,-1)$. Both ions
are immersed in a solvent medium of dielectric coefficient that mimic
water, e.g., with $\epsilon^{x}=\epsilon^{y}=\epsilon^{z}=78.54$
(solvated state). The bulk ionic strength is set equal to zero. To
solve the PB equation we will use a cubic grid of 65 points and a
box length of 12 A centered at the origin of the reference system
$(0,0,0)$. 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 {}``twoions.pqr'' file corresponding to the model described
above reads

\begin{quotation}
ATOM 1 I1 ION 1 1.000 1.000 1.000 1.000 1.000

ATOM 2 I2 ION 1 -1.000 -1.000 -1.000 -1.000 1.000
\end{quotation}
As an example, the {}``twoions.in'' input file used by the APBS
reads

\begin{quotation}
read 

mol pqr twoions.pqr \# Two-ion complex

end

elec name comp\_solv \# Solvated complex

mg-manual

dime 65 65 65 \# Grid dimensions

nlev 4 \# Multigrid levels

glen 12 12 12 \# Grid lengths

gcent mol 1 \# Grid center 

mol 1 

lpbe \# Linearized PB

bcfl mdh \# Full multipole boundary condition

ion 1 0.000 2.0 \# Zero ionic strength

ion -1 0.000 2.0 \# Zero ionic strength

pdie 2.0 \# Solute dielectric

sdie 78.54 \# Solvent dielectric

chgm spl2 \# Cubic spline charge discretization

srfm mol \# Molecular surface

srad 1.4 \# Solvent probe radius

swin 0.3 \# Surface spline window

sdens 10.0 \# Sphere density

temp 298.15 \# Temperature

write pot dx twoions-pot

write charge dx twoions-charge

write dielx dx twoions-dielx

write diely dx twoions-diely

write dielz dx twoions-dielz

write kappa dx twoions-kappa

calcenergy total \# Total energy

calcforce no \# No forces

end

quit
\end{quotation}
For example, if you saved both files 'twoions.pqr'' and 'twoions.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 twoions.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 twoions-dielx.dx,
twoions-diely.dx, twoions-dielz.dx, and the ion accessibility map
twoions-kappa.dx. We also obtain the charge density twoions-charge.dx
and the electrostatic potential twoions-pot.dx maps which will be
used later for testing purpose.


\subsection*{MATLAB input file}

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

\begin{quotation}
65 65 65

12 12 12

298.15

0.0 78.54

twoions-dielx.dx

twoions-diely.dx

twoions-dielz.dx

twoions-kappa.dx

twoions.pqr

twoions\_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 line contains the bulk properties (ionic strenght
$I_{s}=\sum c_{i}z_{i}^{2}$ and the solvent dielectric coeffcient
for the solvated states or the molecular dielectric coefficient for
the reference state); 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 {}``twoions\_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 twoions.inm, twoions-ion.pqr, twoions-dielx.dx,
twoions-diely.dx, twoions-dielz.dx, and twoions-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 {}``twoions.inm'' such that we have to set
the name of the inputfile as follows
\end{itemize}
\begin{quotation}
inputfile='twoions.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 'twoions\_model'
in the directory 'C:/Users/me/Documents/Matlab\_PB\_solver/' containing
the following files

\begin{quotation}
twoions\_model\_MATLAB\_charge\_density.dx

twoions\_model\_MATLAB\_potential\_solution.dx

twoions\_model\_MATLAB\_potential\_solution.jpg

twoions\_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-twoions-pot.dx and twoions\_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-twoions-pot\_and\_twoions\_model\_MATLAB\_potential\_solution.fig

APBS-twoions-pot\_and\_twoions\_model\_MATLAB\_potential\_solution.tiff
\end{quotation}

\end{document}