Improved documentation

doc/eplf.texi

@@ -46,12 +46,18 @@ Localization Function.@refill
 @end menu
 
 @node Introduction
-@chapter Introduction
+@chapter What is EPLF?
 @include intro.texi
 
-@node Using EPLF
+@node Structure of the EPLF code
+@chapter Structure of the EPLF code
+@include programming.texi
+
+@node Using the EPLF code
 @chapter Using the @exe program
 @include wf.texi
 @include ezfio.texi
+@include interface.texi
+@include running.texi
 
 @bye

doc/ezfio.texi

@@ -2,22 +2,26 @@
 {@acronym{EZFIO} }
 @end macro
 
-@section Preparing the @ezfio file
+@section Building the @ezfio database
+An @ezfio database is a directory which contains all the needed input/output data
+needed by the code. 
 
-The @exe program uses the @ezfio (Easy Fortran Input/Output) library
+@subsection Using the provided wrapper
-generator@footnote{@url{http://ezfio.sourceforge.net}} to handle data persistence.
-An @ezfio ``file'' is a directory which contains all the needed input/output data
-needed by the code. These files are accessible via a simple @acronym{API} both
-in Fortran and Python.
 
-The output file containing the computed wave function has to be transformed
+The output file from Molpro, @gamess or Gaussian has to be transformed
-into an @ezfio file in order to be used by @exe. This step is realized by
+into an @ezfio database in order to be used by @exe. This step is realized by
-calling the @command{to_ezfio.py} Python script followed by the name of the
+calling the @command{to_ezfio.exe} command, followed by the name of the
 file containing the wave function:
 @example
-to_ezfio.py test.out
+to_ezfio.exe test.out
 @end example
-An @ezfio file is produced, named @file{test.out.ezfio}.
+An @ezfio database is then produced, named @file{test.out.ezfio}.
 
 
+@subsection Using your own code
+Refer to the @ezfio web site@footnote{http://ezfio.sourceforge.net}
+to learn how to use the @ezfio @acronym{API} to collect your data into an
+@ezfio database.  The @ezfio definition file is the @file{eplf.config} file,
+located at the root of the EPLF package.
+
 

doc/interface.texi

@@ -0,0 +1,82 @@
+The @exe code is able to compute the following functions on a regular three-dimensional
+grid:
+@itemize
+@item The electron pair localization function (EPLF)
+@item The electron localization function (ELF)
+@item The electron density
+@end itemize
+The gradients, the norm of the gradient and the laplacian of any of these
+three functions can also be requested. Note that the EPLF can only be calculated
+for a single Slater determinant.
+
+@section Using the provided interface
+The @file{eplf_edit.py} script allows to modify easily the conditions of the calculation:
+the choice of the functions to compute, the dimension of the grid, etc.
+Running the following command
+@example
+eplf_edit.py test.out.ezfio
+@end example
+opens an input file in your default editor (defined by the @code{$EDITOR}
+environment variable). Lines starting with a @code{#} character are commented.
+The input file is separated in three sections.
+
+@subsection The Computation section
+If you are in a parallel environment, the first line of this section is
+@example
+nproc = 0
+@end example
+which defines the number of processors to use. If nproc is chosen equal to 0,
+then the batch queuing system may choose itself the proper number of processors.
+Otherwise, specify the number of processors you want to use.
+
+Then, all the computable functions appear, preceded by empty parentheses. Put an
+@code{X} between the parentheses for the functions you want to compute, for example
+@example
+(X) elf
+( ) density
+(X) eplf
+@end example
+
+@subsection The Edit section
+
+You can edit the nuclear coordinates and/or the parameters of the grid by
+un-commenting the @code{edit(geometry)} or @code{edit(grid_parameters)}
+statements.
+
+When you save and quit the current input file, a new file will be open containing
+the parameters to edit. In the case of the grid parameters, as there is some redundance
+between the possible inputs quantities, the @code{Default} keyword can be used to
+replace the (x,y,z) specification.
+@example
+###########################
+# Grid : test.out.ezfio
+###########################
+
+# Number of points along x, y, z
+40 40 40
+
+# Coordinates of the origin (x,y,z)
+-3.000000 -4.744648 -5.322027
+
+# Coordinates of the opposite point (x,y,z)
+Default
+
+# Step sizes (x,y,z)
+Default
+@end example
+
+@subsection The Clear section
+All the previously calculated grids are saved in the @ezfio database.
+If the grid parameters are changed, these grids are inconsistent.
+Therefore, it may be necessary to clear the previously calculated grids.
+This can be realized by un-commenting the @code{clear(*)} statements.
+The @code{clear(all)} statement clears all the grids, and also the grid
+parameters.
+
+@subsection Saving the input data
+When the editor is closed, after saving the file, all the input data is
+saved into the EZFIO database. It can be modified later by running again
+the @file{eplf_edit.py} script. A shell script @file{run_test.out.ezfio.sh}
+is automatically created to launch the calculation.
+
+

doc/programming.texi

@@ -0,0 +1,25 @@
+@macro irp
+{@acronym{IRPF90} }
+@end macro
+
+@macro eplf
+{@acronym{EPLF} }
+@end macro
+
+@macro ezfio
+{@acronym{EZFIO} }
+@end macro
+
+The @eplf code is written using the @irp environment
+@footnote{``IRPF90: a programming environment for high performance computing''
+A. Scemama, arXiv:0909.5012v1 [cs.SE] (2009)}, which needs Python>2.3.
+@irp can be downloaded from @url{http://irpf90.ups-tlse.fr}
+
+The input/output data are handled by the Eazy Fortran I/O library generator (EZFIO),
+which can be downloaded from @url{http://ezfio.sourceforge.net}. In this way, the
+data needed by the Fortran code is accessible both by Fortran an Python using the
+same API. The computational part of @eplf is written in @irp and the user
+interfaces are written in Python.
+
+
+

doc/running.texi

@@ -0,0 +1,16 @@
+@section Running the calculation
+
+To run the calculation, run the @command{./run_test.out.ezfio.sh} command,
+or place it in a submission script of a batch queuing system.
+
+Once the calculation is done, the grid is saved into the @ezfio database.
+It can be converted to a cube file using the @command{to_cube} tool,
+specifying as a first argument the @ezfio database, and which grid to convert
+as a second argument. For example:
+@example
+to_cube test.out.ezfio eplf
+@end example
+produces the file @file{test.out.ezfio_eplf.cube}
+
+
+

doc/wf.texi

@@ -1,3 +1,9 @@
+In theory, the @eplf can be computed from any kind of wave function (but note
+that the present code is written in the Restricted Hartree-Fock framework).
+The first step is to calculate a wave function using a quantum
+chemistry code. Then, the parameters of the wave function need to be saved in
+the @ezfio database in order to be communicated to the @exe fortran program.
+
 @section Wave function preparation
 
 @macro gamess
@@ -24,14 +30,22 @@
 {@acronym{CI} } 
 @end macro
 
-Output files of Gaussian, Molpro and @gamess can be read to build the wave function files.
+Wave functions calculated using Gaussian, Molpro and @gamess can be read from
-A major constraint is to realize @emph{single point} a calculation.
+the output files.  A major constraint is to realize a @emph{single point} 
+calculation, all the following quantities appearing in the output file:
+@itemize
+@item The basis set
+@item The full set of MOs
+@item The coefficients of the Slater determinant expansion for @ci wave functions.
+@end itemize
 
 @subsection Using Gaussian
 
 In the Gaussian input file, use the keywords @code{GFPRINT} and @code{pop=Full}.
 In the case of @cas wave functions, use the @code{#p} keyword and the @code{SlaterDet}
 attribute of the @code{CAS} keyword.
+When doing a @cas with Gaussian, first do the Hartree-Fock calculation saving the checkpoint
+file and then do the @cas in a second step.
 
 @subsection Using Molpro
 
@@ -43,22 +57,31 @@ Use the following options in the Molpro input file:
 @item @code{gthresh,printci=0.;} for @mcscf calculations
 @end itemize
 
-An @rhf calculation is mandatory before any @mcscf calculation. Be sure to
+An @rhf calculation is mandatory before any @mcscf calculation, since some
-print @emph{all} molecular orbitals using the @code{orbprint} keyword.
+information is printed only the @rhf part. Be sure to print @emph{all} molecular
+orbitals using the @code{orbprint} keyword, and to use the same spin multiplicity
+and charge between the @rhf and the @cas.
 
 @subsection Using @gamess
 
 For @mcscf calculations, first compute the @mcscf single-point wave function
-with the @acronym{GUGA} algorithm. Then, put the the @mcscf orbitals in the
+with the @acronym{GUGA} algorithm. Then, put the the @mcscf orbitals (of the
-@gamess input file, and run a single-point @acronym{GUGA} @ci calculation with
+@code{.dat} file) in the @gamess input file, and run a single-point
+@acronym{GUGA} @ci calculation with
 the following keywords:
 @itemize @bullet
 @item
-@code{PRTTOL=0.0} in the @code{$GUGDIA} group
+@code{PRTTOL=0.0001} in the @code{$GUGDIA} group to use a threshold of @math{10^{-4}} on
+the @ci coefficients
 @item
-@code{NPRT=2} in the @code{$CIDRT} group
+@code{NPRT=2} in the @code{$CIDRT} group to print the CSF expansions in terms of Slater determinants
 @item
-@code{PRTMO=.T.} in the @code{$GUESS} group
+@code{PRTMO=.T.} in the @code{$GUESS} group to print the molecular orbitals
 @end itemize
 
 
+@subsection Using your own code
+Any other code producing a wave function can be used, as long as you are able to gather all
+the needed data.
+
+

scripts/eplf_edit.py

@@ -263,6 +263,12 @@ def edit_temp_file(input_file,write_file,read_file,saved_file=None):
 
 def build_script(inp):
   run_script = "run_"+inp.name
+# try:
+#   file = open(run_script,'r')
+#   file.close()
+#   return
+# except:
+#   pass
   file = open(run_script,'w')
   buffer = """
   #!/bin/bash
@@ -271,6 +277,9 @@ $RUNCOMMAND
 """.lstrip()
   command = "${EPLF_PATH}/bin/eplf %s"%(inp.name)
   if inp.has_mpi:
+    if inp.nproc <= 0:
+      command = "${EPLF_MPIRUN} "+command
+    else:
       command = "${EPLF_MPIRUN} -np %d "%(inp.nproc)+command
   buffer = buffer.replace("$RUNCOMMAND",command)
   print >>file, buffer

scripts/to_ezfio.py

@@ -146,17 +146,17 @@ def write_ezfioFile(res,filename):
 # Determinants
   det_thr = 1.e-6
   closed_mos = res.closed_mos
-  nactive = ezfio.get_mo_basis_mo_active_num()
+  virtual_mos = res.virtual_mos
   dets_a = []
   dets_b = []
   for d in res.determinants:
     dnew_a = []
     dnew_b = []
     for x in d['alpha']:
-      if x not in closed_mos:
+      if x not in closed_mos+virtual_mos:
         dnew_a.append(x+1)
     for x in d['beta']:
-      if x not in closed_mos:
+      if x not in closed_mos+virtual_mos:
         dnew_b.append(x+1)
     for x in range(res.num_alpha-len(dnew_a)-len(closed_mos)):
       dnew_a.append(0)