==================================================================================================
************************************   Welcome to FreeWilly  *************************************
==================================================================================================

Willy is an electron of course!

This program requires libmesh with some non-standard functions. These are, among some options in the
configuration preinstalled the libraries petsc and slepc.
To make sure it will work for you as well, please install it using the 'install.sh' script.
Check your configuration of libmesh comparing with the 'configs.conf' file.

==================================================================================================
*****************************  TIPPS AND TRICKS FOR INSTALLATION  ********************************
==================================================================================================

== Installing required libraries ==
FreeWilly is based on several external libraries which are libmesh and libraries it is based on again.
Installing petsc:
   As PETSc has no support for long double types, libmesh may not be installed with '--enable-tripleprecision'
   as long as your compiler does not support respective type conversions. However, installation with complex 
   numbers and mpi-support (which is needed for the libmesh-interface as it seems) can be done using the 
   configure-options:
    ./configure --with-scalar-type=complex --with-precision=double 
   And use mpi in the configuration!
   
   The second library that is needed is SLEPC which is build on top of PETSc and copies most of its options
   from the PETSc installation. Therefore, the variables $SLEPC_DIR, $PETSC_DIR and $PETSC_ARCH need to be set.
   Moreover, it can be compiled with further libraries as well as described on the respective home page.

Having these libraries (and optionally some others) one can install libmesh finally. With the above 
configurations, this should be possible using the './install.sh' script.

To compile the application (FreeWilly) in debug-mode, type 'export METHOD=dbg' before 'make'. 
This method must be enabled by the libmesh-installation (as it is by default).
For installing FreeWilly finally, first change the first line in the makefile such that it 
points to your libmesh installation.

Good luck!

==================================================================================================
******************************  Description of the Program  **************************************
==================================================================================================

All quantities specified are in atomic units here.

==================================================================================================
********************************  Running of the Program  ****************************************
==================================================================================================
FreeWilly is called with all options concerning ... being set in an input file as a first argument.
Here, the following options are available:

 _________________________________________________________________________________________________________________
|OPTION NAME=          DEFAULT       POSSIBLE VALUES         EXPLANATION                                              |
 --------------------------------------------------------------------------------------------------------------------
| nev               |    15     |        integers > 0     |  number of eigenvalues (and eigenvectors) requested.      |
|                   |           |                         |     The number of actually computed EVs may differ.       |
| pot               |     -     |       string            |  has no meaning for computation, but is used to setup     |
|                   |           |                         |     name for the output-files.                            |
| Energy            |     -     |      any real number    |  photon energy in atomic units.                           |
| infinite          |    false  |      true , false       |  Switch between infinite elements and Dirichlet boundaries|
|                   |           |                         |                                                           |
 -------------------- ----------- ------------------------- ----------------------------------------------------------- 
|print_quadrature   |   false   |      true , false       |  whether quadrature points should be printed or not       |
|pictorious         |   false   |      true , false       |  if DO and ESP should be computed explicitly              |
|spherical_analysis |    -1     |      (positive) integer |  if positive, states the maximum quantum number l for     |
|                   |           |                         |     which <solution | Spher. Wave> should be computed     |
|cubes              |   false   |      true , false       |  whether cube files should be produced or not.            |
|guessed l          |    -1     |    (positive) integer   | quantum numbers l, m for the spherical wave used as       |
|guessed m          | guessed l |      integer            |     initial guess. If l<0: use dyson orbital instead      |
 ------------------- ----------- ------------------------- ----------------------------------------------------------- 
| cap               |    false  |      true, false        |  turns complex absorbing boundaries on/off. NOT TESTED    |
| gamma             |     -     |       Real              |  the parameter governing the steapness of CAP             |
|                   |           |                         |                                                           |
|                   |           |  fibonacci, spiral,     |                                                           |
|                   |           |  archimedes, lebedev,   |  Algorithm used to obtain the spherical point distribution|
| angular           |     -     |   womMD, fliME, womMN,  |                                                           | 
|                   |           |    womEV,  Sdesign      |                                                           |
| scheme            |     -     |        son, tm          |                                                           |
| p                 |     ?     |     any real number     |                                                           |
|                   |           |                         |     ONLY VALID FOR scheme=tm                              |
 ------------------- ----------- ------------------------- ----------------------------------------------------------- 
| radius            |     ?     |Any positive real number |   max. radius of the spheres around the nuclei            |
| order             |     1     |      1, 2               |  order p of the FEM                                       |
| maxVol            |           |                         |   maximum volume of the                                   |
|                   |           |                         |      finite elements                                      |
| bending           |     ?     | any positive real number| parameter (in thesis called l) determining the radial 
|                   |           |                         |     distribution of spheres                               |
| circles           |           |                         | number of spheres placed around the atoms                 |
| r_0               |    12     | any positive real number| parameter for the RBF-interpolation for electr. pot.      |
|                   |           |                         |     You should provide a good grid; this procedure is bad |
| maxiter           |   700     | any positive integer    | maximum number of iterations used                         |
|                   |           |                         |                                                           |
| refine            | false     |         false           |     mesh refinement is possible only without infinite el. |
| transform         |    -      |   cayley, sinv; any     | which spectral transf. should be applied                  |
|                   |           |                         |     if not given or with typo: use shift                  |
| solver            |    -      |lapack, arnoldi,lanczos  | which algorithm for solving should be used                |
|                   |           |                         |     if not given or with typo: use Krylov-Schur           |
 ------------------- ----------- ------------------------- ----------------------------------------------------------- 
| mesh_file         | -         | name of file            | file containing the ESP.                                  |
| mol_file          | -         | name of file            | File containing the DO, geometry and basis set            |
 _____________________________________________________________________________________________________________________

Further options:
------------------------------------------
|  --n-threads            | #threads -> no parallelisation possible at the moment.
|  --disable-mpi          |
|  --disable-petsc        |
|  --handle-mpi-errors    |  (default/ other options)
|  --sync-with-stdio      |
|  --separate-libmeshout  |
|  --redirect-stdout      |
------------------------------------------
  
  Some further options for more special purpuses can be found in the libmesh documentation.

==================================================================================================
*****************************  Functions to use in the future  ***********************************
==================================================================================================

Please use at least libMesh-version > 1.0. If no newer version is available, use the current development
tree at https://github.com/libMesh/libmesh . 
Older versions will fail to run this program.