Merge lp:~nickpapior/siesta/trunk-kovalp into lp:~kovalp/siesta/siesta

[Nick Papior]

Manual changes

[Petr Koval (kovalp)]

review: Approve

=== modified file 'Docs/siesta.tex'
--- Docs/siesta.tex	2016-10-20 11:53:53 +0000
+++ Docs/siesta.tex	2016-10-20 12:24:23 +0000
@@ -6775,139 +6775,132 @@
 \label{SolverPoisson}
 \index{Poisson solver}
 
-Poisson equation is solved within SIESTA 
-in order to compute a Hartree potential 
-
+Poisson equation is solved within SIESTA in order to compute a Hartree
+potential
 \begin{equation}
-\label{vh-def}
-V_{\mathrm{H}}(\mathbf{r}) = \iiint 
-\frac{\rho(\mathbf{r}')}{|\mathbf{r}-\mathbf{r}'|} d^3r'
+  \label{vh-def}
+  V_{\mathrm{H}}(\mathbf{r}) = \iiint 
+  \frac{\rho(\mathbf{r}')}{|\mathbf{r}-\mathbf{r}'|} d^3r'
 \end{equation}
 for a given electric charge density $\rho(\mathbf{r})$.
 
 In momentum space, the Hartree potential becomes diagonal 
 \begin{equation}
-\label{vh-g}
-V_{\mathrm{H}}(\mathbf{p}) = \frac{4\pi}{p^2}\, \rho(\mathbf{p}),
-\end{equation}
-and this is the computationally cheapest method of calculating 
-the potential. For instance, in case of periodic boundary
-conditions (PBC), the potential in real space is given by a 
-Fourier sum
-
-\begin{equation}
-\label{vh-r}
-V_{\mathrm{H}}(\mathbf{r}) = \sum_{\mathbf{G}} 
-\mathrm{e}^{\mathrm{i}\mathbf{Gr}} 4\pi G^{-2} \rho(\mathbf{G}),
-\end{equation}
-where $\rho(\mathbf{G})$ is the electric charge density in momentum space 
-\begin{equation}
-\label{rho-g}
-\rho(\mathbf{G}) = \frac{1}{(2 \pi)^3}\sum_{\mathbf{R}} 
-\mathrm{e}^{-\mathrm{i}\mathbf{GR}} \rho(\mathbf{R}).
-\end{equation}
-The summations in equations (\ref{vh-r}) and (\ref{rho-g})
-are going over the multiples of unit cell vectors in momentum- 
-$\mathbf{G}$ and coordinate- $\mathbf{R}$ space correspondingly.
-The Fourier transforms in equations (\ref{vh-r}) and (\ref{rho-g})
-can be accelerated by fast Fourier transforms (FFT), leading 
-to an low-complexity algorithm ($O(N)$, where $N$ is number of 
-points on the grid). In SIESTA, only this FFT-accelerated
-method is originally implemented. It is used also for 
-slabs, chains and molecules with success because, within 
-self-consistent field loop, the method
-is applied for (almost) neutral charge distributions, i.~e.
-for electric charge densities given by the density of 
-electrons $n_{\mathrm{e}}(\mathbf{r})$
-and the density of atomic cores $n_{\mathrm{a}}(\mathbf{r})$
-$$\rho(\mathbf{r}) = n_{\mathrm{e}}(\mathbf{r}) + n_{\mathrm{a}}(\mathbf{r}).$$
-
-However, this approach may fail to give sufficient accuracy 
-for systems with reduced dimensionality. There is a work around 
-in the form of some cutoffs in momentum space as summarized 
-nicely by Rozzi \textit{etal} \cite{Rozzi:2006}.
-For instance, for the case of molecules, i.e. for open boundary
-conditions (OBC), it is sufficient
-to modify the Hartree potential in momentum space (\ref{vh-g}) 
-
-\begin{equation}
-\label{vh-r-0d}
-V_{\mathrm{H}}(\mathbf{G}) = V_{\mathrm{C}}(G)\, \rho(\mathbf{G})
-[1-\cos(\alpha R G)],
-\end{equation}
-where $\alpha$ is a parameter 
-$R=(3 V_{\mathrm{box}}/(4\pi))^{1/3}$ and 
-\begin{equation}
-\label{vg-0d}
-V_{\mathrm{C}}(G) = 
-\begin{cases}
-4\pi G^{-2}, \text{ if } G\ne 0; \\
-2\pi\alpha R, \text{ if } G=0.
-\end{cases}
-\end{equation}
-
-The other approach to compute the Hartree potential (\ref{vh-def})
-directly on a real-space grid, but for the coordinates
-situated in the middle of the discretization cells and 
-subsequently to interpolate the potential to the input grid-points.
-This approach has an advantage of not introducing additional
-parameters. Moreover, if we notify that the potential 
-(\ref{vh-def}) is a (3-dimensional) convolution, then we can accelerate 
-this with FFT in such a way that there is no aliasing affects
-(i.e. we avoid cyclic convolutions by a suitable padding
-of data arrays).
+  \label{vh-g}
+  V_{\mathrm{H}}(\mathbf{p}) = \frac{4\pi}{p^2}\, \rho(\mathbf{p}),
+\end{equation}
+and this is the computationally cheapest method of calculating the
+potential. For instance, in case of periodic boundary conditions
+(PBC), the potential in real space is given by a Fourier sum
+
+\begin{equation}
+  \label{vh-r}
+  V_{\mathrm{H}}(\mathbf{r}) = \sum_{\mathbf{G}} 
+  \mathrm{e}^{\mathrm{i}\mathbf{Gr}} 4\pi G^{-2} \rho(\mathbf{G}),
+\end{equation}
+where $\rho(\mathbf{G})$ is the electric charge density in momentum
+space
+\begin{equation}
+  \label{rho-g}
+  \rho(\mathbf{G}) = \frac{1}{(2 \pi)^3}\sum_{\mathbf{R}} 
+  \mathrm{e}^{-\mathrm{i}\mathbf{GR}} \rho(\mathbf{R}).
+\end{equation}
+The summations in equations \eqref{vh-r} and \eqref{rho-g} are going
+over the multiples of unit cell vectors in momentum-$\mathbf{G}$ and
+coordinate-$\mathbf{R}$ space correspondingly.  The Fourier transforms
+in equations \eqref{vh-r} and \eqref{rho-g} can be accelerated by fast
+Fourier transforms (FFT), leading to an low-complexity algorithm
+($O(N)$, where $N$ is number of points on the grid). In SIESTA, only
+this FFT-accelerated method is originally implemented. It is used also
+for slabs, chains and molecules with success because, within
+self-consistent field loop, the method is applied for (almost) neutral
+charge distributions, i.e. for electric charge densities given by the
+density of electrons $n_{\mathrm{e}}(\mathbf{r})$ and the density of
+atomic cores $n_{\mathrm{a}}(\mathbf{r})$
+\begin{equation}
+  \rho(\mathbf{r}) = n_{\mathrm{e}}(\mathbf{r}) + n_{\mathrm{a}}(\mathbf{r}).
+\end{equation}
+
+However, this approach may fail to give sufficient accuracy for
+systems with reduced dimensionality. There is a work around in the
+form of some cutoffs in momentum space as summarized nicely by Rozzi
+\textit{etal} \cite{Rozzi:2006}.  For instance, for the case of
+molecules, i.e. for open boundary conditions (OBC), it is sufficient
+to modify the Hartree potential in momentum space \eqref{vh-g}
+\begin{equation}
+  \label{vh-r-0d}
+  V_{\mathrm{H}}(\mathbf{G}) = V_{\mathrm{C}}(G)\, \rho(\mathbf{G})
+  [1-\cos(\alpha R G)],
+\end{equation}
+where $\alpha$ is a parameter $R=(3 V_{\mathrm{box}}/(4\pi))^{1/3}$
+and
+\begin{equation}
+  \label{vg-0d}
+  V_{\mathrm{C}}(G) = 
+  \begin{cases}
+    4\pi G^{-2}, \text{ if } G\ne 0; \\
+    2\pi\alpha R, \text{ if } G=0.
+  \end{cases}
+\end{equation}
+
+The other approach to compute the Hartree potential \eqref{vh-def}
+directly on a real-space grid, but for the coordinates situated in the
+middle of the discretization cells and subsequently to interpolate the
+potential to the input grid-points.  This approach has an advantage of
+not introducing additional parameters. Moreover, if we notify that the
+potential \eqref{vh-def} is a (3-dimensional) convolution, then we can
+accelerate this with FFT in such a way that there is no aliasing
+affects (i.e. we avoid cyclic convolutions by a suitable padding of
+data arrays).
 
 In order to define a framework for using different Poisson solvers,
-there is an option \textbf{Poisson.Type} as described below
+there is an option \fdf{Poisson.Type} as described below
  
 \begin{fdfentry}{Poisson!Type}[string]<\fdfvalue{PBC}>
 
   Define the type of Poisson solver to use.
 
-\begin{itemize}
-\item \fdfvalue{PBC} (\textit{default})
-This is original SIESTA solver for periodic systems, i.e.
-for periodic boundary conditions in all three dimensions. 
-The solver realizes the equation (\ref{vh-r}).
-
-\item \fdfvalue{PBC.Cutoff0D}
-This is a realization of 0D cutoff in periodic systems, given 
-by equations (\ref{vh-r-0d}) and (\ref{vg-0d})
-(see Rozzi \textit{etal} \cite{Rozzi:2006}).
-
-\item \fdfvalue{OBC.6Loop}
-This is a reference calculation with a 6-folded loop,
-directly computing the Hartree potential (\ref{vh-def})
-for open boundary conditions (for atoms, molecules, clusters etc)
-in real space.
-The potential is computed in the middle of discretisation cells
-and is subsequently interpolated back to the points on which 
-the density is given. It is a slow algorithm and can be practically 
-used only for small systems.
-
-\item \fdfvalue{OBC.FastConv}
-FFT accelerated calculation of Hartree potential 
-in real space. The results of this option should be 
-equivalent to the option \fdfvalue{OBC.6Loop} 
-up to the machine precision.
-
-\item \fdfvalue{OBC.Check}
-This option is to realize a cross check of the 
-results delivered by options \fdfvalue{OBC.6Loop}
-and \fdfvalue{OBC.FastConv}. It invokes both algorithms
-and compares results.
-
-\end{itemize}
+  \begin{fdfoptions}
+
+    \option[PBC] %
+    This is original SIESTA solver for periodic systems, i.e.  for
+    periodic boundary conditions in all three dimensions. The solver
+    realizes the equation \eqref{vh-r}.
+
+    \option[PBC.Cutoff0D] %
+    This is a realization of 0D cutoff in periodic systems, given by
+    equations \eqref{vh-r-0d} and \eqref{vg-0d} (see Rozzi
+    \textit{etal} \cite{Rozzi:2006}).
+
+    \option[OBC.6Loop] %
+    This is a reference calculation with a 6-folded loop, directly
+    computing the Hartree potential \eqref{vh-def} for open boundary
+    conditions (for atoms, molecules, clusters etc.) in real space.
+    The potential is computed in the middle of discretisation cells
+    and is subsequently interpolated back to the points on which the
+    density is given. It is a slow algorithm and can be practically
+    used only for small systems.
+
+    \option[OBC.FastConv] %
+    FFT accelerated calculation of Hartree potential in real
+    space. The results of this option should be equivalent to the
+    option \fdfvalue{OBC.6Loop} up to the machine precision.
+
+    \option[OBC.Check] %
+    This option is to realize a cross check of the results delivered
+    by options \fdfvalue{OBC.6Loop} and \fdfvalue{OBC.FastConv}. It
+    invokes both algorithms and compares results.
+
+  \end{fdfoptions}
 
 \end{fdfentry}
 
 
 \begin{fdfentry}{Poisson!alpha}[real]<\fdfvalue{1.0}>
 
-This parameter defines the constant $\alpha$ in the 
-equations (\ref{vh-r-0d}) and (\ref{vg-0d}). It is 
-effective only if \fdfvalue{Poisson.Type = PBC.Cutoff0D}.
-
+  This parameter defines the constant $\alpha$ in the 
+  equations \eqref{vh-r-0d} and \eqref{vg-0d}. It is 
+  effective only if \fdf*{Poisson.Type PBC.Cutoff0D}.
 
 \end{fdfentry}
 

=== modified file 'version.info'
--- version.info	2016-10-11 19:50:15 +0000
+++ version.info	2016-10-20 12:24:23 +0000
@@ -1,1 +1,1 @@
-trunk-572
+trunk-572--kovalp-manual-1