/*! @file 
@brief README file for pseudo2.5. Notice the file README.first.

@details

@section PSEUDO_WAVELETS   Wavelet transformation parameters


pseudo.2.5 uses the transformation of the Gaussian KS orbitals into a cartesian basis of Daubechie
wavelets (and the resulting deviation in the kinetic energy) as a measure for the softness of the
atomic pseudofunction to generate 'softer' pseudo potentials. This wavelet transformation is done
for several values of hgrid - the grid spacing of the wavelet basis - and the deviations in Ekin are
added according to a power law. In order to request the calculation of these deviations, some 
keywords must be present in the file input.dat to specify related parameters - setting a nonzero
weight for these terms in the file weights.par is not sufficient. 
<pre>
  Keyword     default value       description
  
  -nh         0                   The number of sample values for the grid spacing. 
  -hmin       0.3                 The finest grid spacing to be used for the hgrid samples
  -hmax       0.5                 The coarsest grid spacing
  -crmult     8.0                 Length scale for grid points that hold scaling functions
  -frmult     8.0                 and for grid points that hold scaling functions and wavelets
  -nhpow      14                  The power law for adding up deviations per sample - optional
  -offset     0.0                 Offset btw origin and grid - optional
 </pre>

While most of these may work fine with the default values, -nh 0 obviously turns off the treatment
of the wavelet part. The default for -nhpow simply means that contributions from different grid
spacings are weighted by a factor that is one for the finest grid, and scales with the 14th power
of the nr of grid points per dimension - an empirical choice that seems to work fine for fitting.
crmult and frmult define the coarse and fine radii for the computational volumes around the origin,
with only scaling functions, or wavelets and scaling functions on the cartesian grid points,
respectively.  A typical choice is three to ten times the atomic charge integration radius rcov.
Finer values for hgrid and larger radii lead to higher computational times.
It is important to choose the radii large enough that the resulting plot from the file dEkin.orb.dat
is suitably converged. To small radii lead to large errors especially for fine grids, which may be
identified by bumps and wiggles in said plot. Below is an example of dEkin.orb.dat.

<pre>
# hgrid            dE_kin(gauss-wvlt) weighted by hgrid orbital  1        orbital  2        
  0.3500000000E+00  0.2522785193E-05  0.2118849652E-05  0.7295995581E-06  0.2414980251E-05
  0.4000000000E+00  0.1032687898E-04  0.1337524352E-05  0.3134552417E-05  0.9839665165E-05
  0.4500000000E+00  0.3250003817E-04  0.8092471288E-06  0.1035457110E-04  0.3080641717E-04
  0.5000000000E+00  0.8250287634E-04  0.4699606742E-06  0.2756106726E-04  0.7776318008E-04
</pre> 


determines the power law for adding up the contributions resulting from different hgrid samples. 
In this case, the penalty term for each hgrid is weighted by (0.3/hgrid)**14.



@section PSEUDO_MPI   About the usage of MPI processes 

Each process reads its own atom.##.ae file generated by atom, where ## is a two digit number. Every
process then calculates the penalty contribitions due to its configuration and the excitation energy
from the ground state (atom.00.ae) to that configuration. Thus one can treat at most as many
configurations as there are processes available in the MPI run. If a reference file is missing or a
reading error occurs, pseudo will give a notification and use atom.00.ae for that process instead.

If there is some weight on softness, the wavelet transformations of the orbitals of the ground state
are computed for the given range of samples for the grid spacing hgrid. If the number of processes
equals the number of occupied orbitals with distinct (n,l and s) quantum numbers, the different hgrid
samples are treated one after the other, each transformation efficiently parallelized over the
orbitals. Otherwise, each sample is assigned a number of processes between one and the number of
orbitals. Small hgrid values are treated with as many processes as possible, giving priority to finer
grid spacings which are computationally more expensive. When there are not enough or to many MPI
processes to do so, the number of samples is adjusted automatically. Be sure to test your setup
before running longer fitting cycles. Some minimal time profiling information is provided at the end
of each run. Notice that the time displayed for communication includes the time spent waiting for
other processes, which can be a dominant term when the workload for the wavelet transformations
is balanced poorly.



@section PSEUDO_CUDA    About the usage of CUDA acceleration

This version of pseudo comes with a cudafortran implementation of the convolution kernels that are
used to calculate the kinetic energy in the Daubechie wavelet basis. When softness properties are
taken into account during the fit, this part of the program will take most of the computational
resources, allowing for a significant overall speedup with the GPU version. The corresponding
sources and an example Makefile are found in the ekin.cublas subdirectory of pseudos sources.
The MPI functionality of pseudo as described above should remain, as each process will treat
its set of orbitals and request the convolutions from the GPU attached to its host.
The cudafortran kernels have been implemented by Raffael Widmer.



@section PSEUDO_MIXED   How to set up mixed atomic reference data

Another new feature is the -mixref option which replaces the -ignore flag. The idea of this is to
perform a parallel fit for different values for the integration radius rcov, the shallowness of
the confining potential rprb, the Gaussian basis parameters ng and rij or even the XC functionals
to be used. This can be done along with fitting of softness and excitation energies, for instance if
you need more processes for the parallel treatment of the wavelet transformations than the number of
configurations considered.  
If you want to fit for several values of rcov, rprb, nr, rij or iXC, run the needed AE calculations
first, one at a time. Be sure to copy the atom.00.ae output files accordingly before treating the
next reference system. After you are done with this, run atom once more for the reference system and
all configurations to be used for the fitting of excitation energies. To do so, use the keyword line
'NEXT CONFIGURATION' as explained in README.atom. Finally, adjust the overall weights of each
configuration on the first line of each atom.##.ae file and be sure to include the keyword -mixref
on the first line of input.dat

*/
