Index: Mini_help.tex
===================================================================
 Mini_help.tex (revision 8)
+++ Mini_help.tex (revision 9)
@@ 1,5 +1,4 @@
\documentclass[a4paper,11pt]{article}
\usepackage{a4wide}
%\usepackage{times}
\usepackage{graphicx}
\usepackage[body={16cm,24.5cm}]{geometry}
@@ 34,17 +33,17 @@
\lhead[]{}
\rhead[]{}
\cfoot{}
\title{OpenPath minihelp}
+\title{Opt'n Path minihelp}
\author{P. FleuratLessard, P. Dayal \\
Laboratoire de Chimie de l'ENS Lyon, 46 allée d'Italie, F69364 Lyon
+Laboratoire de Chimie de l'ENS Lyon, 46 all\'ee d'Italie, F69364 Lyon
Cedex 7}
\date{Feb. 2011}
+\date{March 2013}
\def\Path{\texttt{OpenPath}}
+\def\Path{\texttt{Opt'n Path}}
\begin{document}
\maketitle
\section{introduction}
+\section{Introduction}
\Path{} is a program that can optimize a reaction path between two
structures. The algorithm to optimize the path is close to the string
method. The originality of this program lies in the coordinate set it
@@ 52,21 +51,21 @@
This program is an independant program that calls standard electronic
structure codes to get the energies and forces it needs to optimize
 the reaction path. For now, it is coupled to Gaussian, MOPAC2009,
 Vasp and Turbomole.
+ the reaction path. For now, it is coupled to Gaussian, MOPAC,
+ Vasp, Turbomole and Siesta.
\section{Installation}
We suppose here that you will install \Path{} into a directory called
\texttt{OpenPath}. First, create the directory:
+\texttt{optnpath}. First, create the directory:
\begin{verbatim}
 mkdir OpenPath
 cd OpenPath
 mv ../OpenPath.tgz .
+ mkdir optnpath
+ cd optnpath
+ mv ../optnpath_x.yy.tgz .
\end{verbatim}
Uncompress the archive:
\begin{verbatim}
 gunzip OpenPath.tgz
 tar xvf OpenPath.tar
+ gunzip optnpath_x.yy.tgz
+ tar xvf Optnpath.tar
\end{verbatim}
You should now have this \texttt{Mini\_help.pdf} file and 4 directories (doc, src, utils, examples).
@@ 133,30 +132,37 @@
\end{verbatim}
 Compulsory variables are:
+\subsubsection{Compulsory variables are:}
\begin{description}
\item NGeomi: Number of geometries defining the Initial path
\item NGeomf: Number of geometries defining the Final path
\item Nat : Number of atoms
+\item[NGeomi:] Number of geometries defining the Initial path
+\item[NGeomf:] Number of geometries defining the Final path
+\item[Nat:] Number of atoms
\end{description}

 Other options
+
+
+\subsubsection{Other options:}
\begin{description}
\item Input: string that indicates the type of the input geometries.
 Accepted values are: Cart (or Xmol or Xyz) or Vasp
\item Prog: string that indicates the program that will be used for energy and gradient calculations.
 Accepted values are: Gaussian, Vasp or Ext. \\
 In case of a Gaussian calculations, input must be set to Cart.
+\item[Input:] String that indicates the type of the input geometries.
+ Accepted values are: Cart (or Xmol or Xyz), Vasp, Turbomole or Siesta.
+\item[Prog:] string that indicates the program that will be used for energy and gradient calculations.
+ Accepted values are: Gaussian, Mopac, Vasp, Turbomole, Siesta or Ext. \\
+\begin{itemize}
+\item In case of a Gaussian calculations, input must be set to Cart.
One example of a gaussian input should be added at the end of the
input file.See example file \texttt{Test\_HCN\_zmat\_g03.path}. \\
 In the case of a VASP calculation, if input is set to Cart, then
 the preamble of a VASP calculation should be added at the end of
+\item In the case of a VASP calculation, if input is set to Cart, then
+ the preamble of a VASP calculation s\item \texttt{Mopac}: Examples using sequential call
+ to MOPAC2009 to calculate the energies and forces along the path.
+hould be added at the end of
the input file. See example file \texttt{Test\_VASP\_cart.path}.
In the case of a VASP calculation, one should also give value of the
\texttt{RunMode} variable .
+\item In the case of a SIESTA calculation, an example of a Siesta input file
+ should be added at the end of the input file. See \texttt{Test\_Siesta.path}.
+\end{itemize}
\item RunMode: This indicates wether \Path{} should use VASP
 routine to calculate the energy and gradient of the whole path
+\item[RunMode:] When running on a multiprocessor machine, this indicates
+ wether \Path{} should calculate the energy and gradient of the whole path in parallel
or not. User has two options. One is to calculate the energy and
gradient of each point sequentially. This is usefull when
running on one (or two) processors. In this case,
@@ 164,87 +170,147 @@
in parallel with 8 or more processors, one can use VASP to
calculate simultaneously the energies and gradients for all
points, as in a normal NEB calculation. In this case,
 \texttt{RunMode} must be set to \texttt{PARA}.
\item ProgExe: Name (with full path) of the executable to be used to get
+ \texttt{RunMode} must be set to \texttt{PARA}.
+ \emph{For now, this is usefull only for VASP.} \\
+
+\item[ProgExe:] Name (with full path) of the executable to be used to get
energies and gradients. For example, if VASP is used in parallel, one might
have something like: \\
\verb!ProgExe='/usr/local/mpich/bin/mpirun machinefile machine np 8 ~/bin/VASP_46'!.
Another option that I use, is to put \verb!ProgExe='./run_vasp'! and I put every option needed to run VASP
into the \texttt{run\_vasp} file.
\item PathName: Prefix used to save the path. Default is Path
\item Poscar: string that will be used as the prefix for the different
+\item[EReac:] (REAL) By default, \Path{} does not compute the energy of the reactants
+ and products. This thus indicates the reactants energy to \Path{} to have better plots
+ at the end.
+\item[EProd:] (REAL) By default, \Path{} does not compute the energy of the reactants
+ and products. This thus indicates the products energy to \Path{} to have better plots.
+\item[PathName:] Prefix used to save the path. Default is Path
+\item[Poscar:] string that will be used as the prefix for the different
POSCAR files in a VASP calculations. Usefull only if PathOnly=.TRUE.,
not used for internal calculations.
\item IGeomRef: Index of the geometry used to construct the internal coordinates.
 Valid only for Coord=Zmat, Hybrid or Mixed
\item Fact: REAL used to define if two atoms are linked.
+\item[CalcName:] Prefix for the files used for the energy and gradient calculations
+\item[ISuffix:] Suffix for the input file used for energy and gradient calculations.
+The full inputfile name will thus be \textit{CalcName}.\textit{ISuffix}.
+\item[OSuffix:] Suffix for the output file used for energy and gradient calculations.
+ The full outputfile name will thus be \textit{CalcName}.\textit{OSuffix}.
+\item[IGeomRef:] Index of the geometry used to construct the internal coordinates.
+ Valid only for Coord=Zmat, Hybrid or Mixed.
+\item[Fact:] REAL used to define if two atoms are linked.
If $d(A,B) \leq fact*(rcov(A)+rcov(B))$, then A and B are considered Linked.
\item debugFile: Name of the file that indicates which subroutine should print debug info.
\item Coord: System of coordinates to use. Possible choices are:
  CART (or Xyz): works in cartesian
  Zmat: works in internal coordinates (Zmat)
  Mixed: frozen atoms, as well as atoms defined by the
+\item[debugFile:] Name of the file that indicates which subroutine should print debug info.
+\item[Coord:] System of coordinates to use. Possible choices are:
+\begin{itemize}
+\item CART (or Xyz): works in cartesian
+\item Zmat: works in internal coordinates (Zmat)
+\item Mixed: frozen atoms, as well as atoms defined by the
'cart' array(see below) are describe in CARTESIAN, whereas the
others are described in Zmat
  Baker: use of Baker coordinates, also called delocalized internal coordinates
  Hybrid: geometries are described in zmat, but the gradient are used in cartesian
\item Step\_method: method to compute the step for optimizing a geometry; choices are:
  RFO: Rational function optimization
  GDIIS: Geometry optimization using direct inversion in the iterative supspace
\item HUpdate: method to update the hessian. By default, it is MurtaghSargent
+\item Baker: use of Baker coordinates, also called delocalized internal coordinates
+\item Hybrid: geometries are described in zmat, but the gradient are used in cartesian
+\end{itemize}
+\item[Step\_method:] method to compute the step for optimizing a geometry; choices are:
+\begin{itemize}
+\item RFO: Rational function optimization
+\item GDIIS: Geometry optimization using direct inversion in the iterative supspace
+\end{itemize}
+\item[HUpdate:] method to update the hessian. By default, it is MurtaghSargent
Except for geometry optimization where it is BFGS.
\item MaxCyc: maximum number of iterations for the path optimization
\item Smax: Maximum length of a step during path optimization
\item SThresh: Step Threshold to consider that the path is stationary
\item GThresh: Gradient Threshold to consider that the path is stationary, only orthogonal part is taken
\item FTan: We moving the path, this gives the proportion of the displacement tangent to the path
+\item[MaxCyc:] maximum number of iterations for the path optimization
+\item[Smax:] Maximum length of a step during path optimization
+\item[SThresh:] Step Threshold to consider that the path is stationary
+\item[GThresh:] Gradient Threshold to consider that the path is stationary, only orthogonal part is taken
+\item[FTan:] We moving the path, this gives the proportion of the displacement tangent to the path
that is kept. FTan=1. corresponds to the full displacement,
whereas FTan=0. gives a displacement orthogonal to the path.
\item IReparam: The path is not reparameterised at each iteration. This gives the frequency of reparameterization.
\item ISpline: By default, a linear interpolation is used to generate the path.
+\item[IReparam:] The path is not reparameterised at each iteration. This gives the
+frequency of reparameterization.
+\item[IReparamT:] When the path is not reparameterised at each iteration, this gives the
+frequency of reparameterization of the \emph{tangents}.
+\item[ISpline:] By default, a linear interpolation is used to generate the path.
This option indicates the first step where spline interpolation is used.
+\item[BoxTol:] Real between 0. and 1. When doing periodic calculations,
+ it might happen that an atom moves out of the unit cell.
+ Path detects this by comparing the displacement to boxtol:
+ if an atom moves by more than Boxtol, then it is moved back into the unit cell. Default value: 0.5.
+\item[FrozTol:] (Real) This indicates the threshold to determine wether an atom moves between two images. Default is 1e4.
+\item[OptGeom:] This INTEGER indicates the index of the geometry you want to optimize.
+If \texttt{OptGeom} is set, then \Path{} performs a geometry optimization instead of a path interpolation.
+\item[GeomFile:] Name of the file to print the geometries and their energy
+ during a geometry optimization. If this variable is not given
+ then nothing is printed.
+\item[AnaFile:] Name of the file to print the values of the geometrical parameters
+that are monitored if \texttt{AnaGeom=.TRUE.}. Default is \textit{PathName}.dat
+\item[GplotFile:] Name of the \texttt{gnuplot} file to plot the evolution of the geometrical parameters that are monitored if \texttt{AnaGeom=.TRUE.}. Default is \textit{PathName}.gplot
+%% Not described here: NMaxPtPath, NGintMax (too technical ?)
\end{description}
 Arrays:
+\subsubsection{Arrays:}
\begin{description}
\item Rcov: Array containing the covalent radii of the first 80 elements.
+\item[Rcov:] Array containing the covalent radii of the first 86 elements.
You can modify it using, \verb!rcov(6)=0.8!.
\item Mass: Array containing the atomic mass of the first 80 elements.
\item AtTypes: Name of the different atoms used in a VASP calculations.
+\item[Mass:] Array containing the atomic mass of the first 86 elements.
+\item[AtTypes:] Name of the different atoms used in a VASP calculations.
If not given, Path will read the POTCAR file.
\end{description}
 Flags:
+\subsubsection{Flags:}
\begin{description}
\item MW: Flag. True if one wants to work in Mass Weighted coordinates. Default=.TRUE.
\item Renum: Flag. True if one wants to reoder the atoms in the
 initial order. default is .TRUE. most of the time.
\item OptProd: True if one wants to optimize the geometry of the products.
\item OptReac: True if one wants to optimize the geometry of the reactants.
\item CalcEProd: if TRUE the product energy will be
 computed. Default is FALSE. Not Compatible with RunMode=Para".
\item CalcEReac: if TRUE the reactants energy will be
 computed. Default is FALSE. Not Compatible with RunMode=Para".
\item PathOnly:TRUE if one wants to generate the initial path, and stops.
\item Hinv: if True, then Hessian inversed is used.
\item IniHup: if True, then Hessian inverse is extrapolated
+\item[MW:] Flag. True if one wants to work in Mass Weighted coordinates. Default=.TRUE.
+\item[Renum:] Flag. True if one wants to reoder the atoms in the
+ initial order. default is .TRUE. unless for \texttt{Coord} equals \texttt{CART}.
+\item[OptProd:] True if one wants to optimize the geometry of the products.
+\item[OptReac:] True if one wants to optimize the geometry of the reactants.
+\item[CalcEProd:] if TRUE the product energy will be
+ computed. Default is FALSE. Not Compatible with \texttt{RunMode=Para}.
+\item[CalcEReac:] if TRUE the reactants energy will be
+ computed. Default is FALSE. Not Compatible with \texttt{RunMode=Para}.
+\item[PathOnly:] TRUE if one wants to generate the initial path, and stops.
+\item[Align:] If .FALSE., successive geometries along the path are not aligned on each other before path interpolation. Default is .TRUE. if there are 4 atoms or more.
+\item[Hinv:] if True, then Hessian inversed is used.
+\item[IniHup:] if True, then Hessian inverse is extrapolated
using the initial path calculations.
\item HupNeighbour: if True, then Hessian inverse is
+\item[HupNeighbour:] if True, then Hessian inverse is
extrapolated using the neighbouring points of the path.
\item FFrozen: True if one wants to freeze the positions of some atoms.
+\item[FFrozen:] True if one wants to freeze the positions of some atoms.
If True, a \verb!&frozenlist! namelist containing the
list of frozen atoms must be given.
If VASP is used, and frozen is not given
here, the program will use the F flags of the input geometry
\item FCart: True if one wants to describe some atoms using cartesian coordinates.
+\item[FCart:] True if one wants to describe some atoms using cartesian coordinates.
*** Only used in 'mixed' calculations. ***
If True, a \verb!&cartlist! namelist containing the list of cart atoms must be given.
By default, only frozen atoms are described in cartesian coordinates.
\item Autocart: True if you want to let the program choosing the cartesian atoms.
\item VMD: TRUE if you want to use VMD to look at the Path. Used only for VASP for now
+\item[Autocart:] True if you want to let the program choosing the cartesian atoms.
+\item[VMD:] TRUE if you want to use VMD to look at the Path. Used only for VASP for now.
+\item[WriteVASP:] TRUE if you want to print the images coordinates in POSCAR files.
+See also the POSCAR option. This can be used only if prog or input=VASP.
+\item[AnaGeom:] If TRUE, Opt'n Path will create a file .dat for geometries analysis.
+ If True, Opt'n Path will look for the AnaList namelist after the Path Namelist.
+\item[DynMaxStep:] if TRUE, the maximum allowed step is updated at each step, for each geometry.
+ If energy goes up, $Smax=Smax*0.8$, if not $Smax=Smax*1.2$.
+ It is ensured that the dynamical Smax is within $[0.5*SMax_0,2*Smax_0]$.
\end{description}
+\subsubsection{Additional namelists:}
+\begin{description}
+\item[\&cartlist list= \ldots{} \&end] This gives the list of atoms that are described using cartesian coordinates. Read only if \texttt{FCart=.TRUE.}. To indicate an atom range, from 1 to 5 for example, one can put 1 5 in the list. For example: \\
+\texttt{\&cartlist list = 1 2 6 12 20 \&end} \\
+will described atoms 1, 2, 6, 12, 13, 14, 15, 16, 17, 18, 19 and 20 in cartesian.
+\item[\&Frozenlist list= \ldots{} \&end] This gives the list of atoms that are frozen during optimization. Read only if \texttt{FFrozen=.TRUE.}. To indicate an atom range, from 1 to 5 for example, one can put 1 5 in the list.
+\item[\&Analist nb= \ldots{} \&end] list of variables for geometry analysis. If present and if AnaGeom=T then
+ Opt'n Path will read it and print the values of the variable in a .dat file
+ If AnaGeom is T but Analist is not given, then Path.dat just contains the energy.
+Analist contains the number of variables to monitor: Nb, and is followed by the description
+of the variables among:
+b(ond) At1 At2
+a(ngle) At1 At2 At3
+d(ihedral) At1 At2 At3 At4
+c NbAt At1 At2 At3 At4 At5... to create a center of mass. The centers of mass are added
+at the end of the real atoms of the system.
+\end{description}
+
+\subsection{Examples}
More to come... have a look at the files provided in the
\texttt{examples} directory. In particular, you will find there three
directories containing easytouse examples. That is, each directory contains
@@ 289,7 +355,9 @@
\end{itemize}
\end{itemize}
\item \texttt{Mopac}: Examples using sequential call
 to MOPAC2009 to calculate the energies and forces along the path.
+ to MOPAC to calculate the energies and forces along the path.
+\item \texttt{Siesta}: Examples using sequential call
+ to Siesta to calculate the energies and forces along the path.
\item \texttt{Test}: Examples using the analytical HCN potential
energy surface to calculate the energies and forces along the path.
As this is fast, we also provide other Analysis tools.