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

@details

@section Input     Input files, introduction and version changes   

The following input files must be present to invoke 'pseudo'. All of these files are generated by
the all electron program 'atom'. 

If a file is missing, a reading error occurs or proofreading indicates a mistake, 'pseudo' will give
some error message with additional information.


 weights.par     The fitting procedure of 'pseudo' uses a simple downhill method to minimize an
                 empirical penalty function. The various contributions to that function are defined
                 by the weights in this file. The first line is used for comments and the second 
                 line contains a list of weights independent of the all electron reference data.
                 From line three on, the file is backwards compatible with previous versions.
                 All weights and corresponding properties are explained in the next section.

 atom.00.ae      This file contains the reference data from the all electron calculation. Notice
                 the first line contains an overall weight factor to be taken into account for
                 all penalty contributions that depend on the following data. In a parallel run,
                 one file per MPI process is needed, atom.00.ae, atom.01.ae, atom.02.ae and so on.

 input.dat       This is an input file with options that have been read as command line arguments
                 in previous versions and some additional parameters the user can specify. If this
                 file is absent, pseudo will print a notification with a list of recognized options:

                   -cy      N number of fitting cycles (-1< N< 10000)
                   -fit       equivalent to -cy 1
                   -maxiter N number of iterations per simplex
                   -ng      N number of Gaussians
                   -rij     F max length scale of Gaussians/rloc 
                   -fullacc   use max. number of gaussians
                   -orth      orthogonalisation of the projectors
                   -lith      transformation of the projectors as in lit.
                   -denbas    use dense gaussian basis    
                   -mixref    allow contradictions in AE ref data
                   -info      write gaussian coefficients of final
                              wavefunctions to gauss.par
                   -plot      plot wfs after each iteration
                   -lNso      avg nonlocal potential =0 for l=N  
                              (only for the highest projector)
                   -inwidth F initial width of the simplex
                   -stuck   N max steps to consider simplex stuck
                   -cvg     F convergence crit for simplex spread

                 Notice that the entire file is parsed for keywords, of which some need to be followed
                 with numeric values. If the same option is specified several times, the previous 
                 settings will be overridden with its latest occurrence. 

 psppar          This is the pseudopotential in ABINIT's GTH, HGH or HGH-K format (code 2,3 or 10).
                 The file serves as an initial guess for and output of resulting PSP parameters.
                 Previous versions used psp.par files of a different format. If you want to convert
                 such a psp.par file to the ABINIT format, you can invoke the program psp.import.f.
                 Notice the comment on line one may contain some optional input parameters. 
                 If present, these will be compared with the current settings for proofreading.
                 The same holds for a list of NLCC parameters possibly located on line 5. 

 FITPAR          This file specifies which parameters of psppar shall be free during the fit.
                 In previous versions, a logical array was read in some fixed format. This version 
                 will parse the file for keywords instead. If no matches are found, pseudo will print
                 some more instructions. The keyword "auto" will free most params from psppar.

 ae.orbitals.plt This file contains a list of all electron wavefunctions and is needed when plots
                 are requested from pseudo with the -plot option. Comparing the pseudowavefunctions
                 with the AE wavefunctions is indeed needful to check the outcome of any fit.
                 Plotting utilities are provided for the use with gnuplot.



___________________________

   weights.par in detail
___________________________


Below is an example input file. The first line is a comment and the second line holds some new
weights absent in previous versions of pseudo.

 weights file for nonrelativistic carbon
 0d0 1d5 1d0 1d0 1d0 1d3      psi(0), dEkin_wvlt, radii, hij, locality E_exct
   n   l  so    eigval  chrg    dchrg  ddchrg  res    rnode dnode ddnode
   2   0 0.00   1.0e3   1.0e3   0.0e0  0.0e0   0.0e0  1.0e0 0.0e0 0.0e0
   3   0 0.00   1.0e0   1.0e0   0.0e0  0.0e0   0.0e0  0.0e0 0.0e0 0.0e0
   4   0 0.00   1.0e0   1.0e0   0.0e0  0.0e0   0.0e0  0.0e0 0.0e0 0.0e0
   2   1 0.00   1.0e3   1.0e3   0.0e0  0.0e0   0.0e0  1.0e0 0.0e0 0.0e0
   3   1 0.00   1.0e0   1.0e0   0.0e0  0.0e0   0.0e0  0.0e0 0.0e0 0.0e0
   4   1 0.00   1.0e0   1.0e0   0.0e0  0.0e0   0.0e0  0.0e0 0.0e0 0.0e0
   3   2 0.00   1.0e0   1.0e0   0.0e0  0.0e0   0.0e0  0.0e0 0.0e0 0.0e0
   4   2 0.00   1.0e0   1.0e0   0.0e0  0.0e0   0.0e0  0.0e0 0.0e0 0.0e0
   4   3 0.00   1.0e0   1.0e0   0.0e0  0.0e0   0.0e0  0.0e0 0.0e0 0.0e0


The weights on the second line are defined as follows.

 psi(0)        Puts weight on the density of the lowest s orbital at r=0, where it should vanish.
               This is not always useful and may actually compete with softness.

 dEkin_wvlt    This is the weight factor for the change in kinetic energy when transforming the
               valence orbitals to a wavelet basis. This Weight is typically > 1d4. Notice that
               calculations without this softness term run much faster, especially when serial.

 radii         Very small length scales of the projectors r_l make them hard to resolve in a wavelet
               basis. This penalizes small r_l according to a power law that approximates the
               deviation of the transformed projectors norm.   1-|projector|  ~ 1d-6 (hgrid/r)**12

 hij           Large matrix elements of the projectors may lead to numerical instabilities. This
               weight applies to the empirical term                        sum( (hij/10.0)**12 )

 locality      A common problem when searching for soft pseudopotentials are wide extensions
               of the local Gaussian potential. This weight is used to make sure V_loc is
               sufficiently small beyond a distance to the origin of rcov. 

 E_exct        This is the overall weight for all excitation energies. Deviations in the mHa
               range will give contributions around 1 with this weight.

The following lines give weights for eigenvalues, integrals, residues and nodes of each KS orbital,
or rather how the difference of these quantities to the all electron counterparts are summed up. 
Notice that the overall weighting factor on the first line of each atom.##.ae file is taken into
account to scale these weights for each atomic configuration. The default is one for the ground
state and 1E-3 for excited configurations. 

n l so         quantum numbers of the orbital for the weights of this line

eigval         Kohn Sham eigenvalues

chrg           int_0^rcov psi^2 r^2 dr         (Notice rcov is defined in atom.dat and psppar.)
dhrg           int_0^infinity psi^2 r^4 dr     
ddchrg         int_0^infinity psi^2 r^6 dr     (Allows a different radial weighting.)

res            residue = H*psi(i) - ev(i)*psi(i) (Obviously, this depends on the Gaussian basis.)

rnode          integral of the wavefunction between false nodes in the core-region caused by unwanted
               oszilations of the pseudowfn in this region (the lowest orbitals of each angular
               momentum must have zero nodes, the next higher orbitals must have one node, etc) 
dnode          the same as rnode but now for the first derivative of the wavefunction ...
ddnode         ... and for the second derivative of the wavefunction


During the fit, some major contributions of the penalty function are written out whenever the
lowest value of the simplex improves. Notice the penalty uses square weighting, i.e.

                penalty = sqrt( sum( (weight(i)*penalty(i) )**2 ) ) ). 

Therefore, small penalty terms have little impact, and weights should be adjusted such that all
properties that need to be improved give similar contributions to the overall penalty.



***************************************************************************************************

Further information on input files related to parallel computations, wavelet transformations
and nonlinear core corrections is found in the files README.pseudo.parallel and README.NLCC.

*/
