Updated documentation

README.md

@@ -13,19 +13,12 @@ This updated version, aims to solve single-site, multi-orbital models, in either
 See [j.cpc.2021.108261](https://doi.org/10.1016/j.cpc.2021.108261) for further information about the underlying algorithms. Yet, suitable modifications have been developed to address the Superconducting and non-SU(2) channels.  
 
 ### Documentation
-The documentation for the EDIpack2 library and the its Python API (EDIpy2) is available at [https://aamaricci.github.io/EDIpack2.0/](https://aamaricci.github.io/EDIpack2.0/)  
+The documentation for the EDIpack2 library and its Python API (EDIpy2) is available at [https://aamaricci.github.io/EDIpack2.0/](https://aamaricci.github.io/EDIpack2.0/)  
 
 The documentation is under construction:  
 - [x] Setup the general structure  
 - [x] Merge with the EDIpy2 documentation (from L.Crippa)  
-- [] Draft the main index of the documentation  
-- [] Write documentation for the global initial part  
-- [] Write documentation for the bath part  
-- [] Write documentation for the I/O part  
-- [] Write documentation for the NORMAL part  
-- [] Write documentation for the SUPERC part  
-- [] Write documentation for the NONSU2 part  
-- [] Write documentation for the global final part  
+- [ ] Draft the main index of the documentation  
 
 
 ### Dependencies
@@ -41,7 +34,7 @@ The code is based on:
 
 ### Installation
 
-Installation is available using CMake. In the current v0.0.1 API are only provided in Fortran. In a future release Python and C/C++ API will be included.  
+Installation is available using CMake. In the current version API are only provided in Fortran and Python.  
 The software gives acces to the static library `libedipack2.a` and the related modules `EDIPACK2`
 
 Clone the repo:
@@ -50,12 +43,11 @@ Clone the repo:
 
 And from the repository directory (`cd EDIpack2`) make a standard out-of-source CMake compilation:
 
-`mkdir build`
-`cd build`
-`cmake ..`     
+`mkdir build`  
+`cd build`  
+`cmake ..`      
 `make`     
 `make install`   
-`make post-install`    
 
 Please follow the instructions on the screen to complete installation on your environment.  
 The library can be loaded using one of the following, automatically generated, files :  

doc/conf.py

@@ -31,7 +31,7 @@
 # The short X.Y version
 version = u''
 # The full version, including alpha/beta/rc tags
-release = u''
+release = u'beta 0.0.1'
 
 
 # -- General configuration ---------------------------------------------------
@@ -88,17 +88,14 @@
 exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = None
+pygments_style = 'sphinx'
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-#html_theme = 'sphinxdoc'
-#html_theme = 'classic'
-#html_theme = 'alabaster'    
 html_theme = 'sphinx_rtd_theme'
 html_css_files = [
     'css/custom.css',

doc/fortran_src/01_dependencies.rst

@@ -0,0 +1,13 @@
+Dependencies
+============
+
+The EDIpack2.0 code relies on:
+
+* `SciFortran <https://github.com/aamaricci/SciFortran>`_ : an
+  external library  providing a simple and generic environment for
+  scientific software development, *in a way* just like ``scipy`` for
+  ``python``.  
+
+* `MPI <https://github.com/open-mpi/ompi>`_ : a distributed memory
+  parallel communication layer including Fortran compiler. 
+

doc/fortran_src/02_installation.rst

@@ -0,0 +1,102 @@
+Installation
+#####################
+
+EDIpack2.0 is available in the form of a static Fortran library
+`libedipack2.a` and the related Fortran module `EDIPACK2`.
+Installation is available using CMake. In the current release the
+library enables standard Fortran API and Python API `EDIpy2`. 
+
+
+Installing EDIpack2.0
+======================
+We assume that `SciFortran` and `MPI` have been correctly installed
+and are available in the system. See related documentation. Note that
+the installation of `EDIpack2.0` closely follows the `SciFortran`
+template.
+
+
+Clone the repo:
+
+.. code-block:: bash
+		
+   git clone https://github.com/aamaricci/EDIpack2.0 EDIpack2
+
+
+
+Optionally define the fortran compiler:
+
+.. code-block:: bash
+		
+   export FC=mpif90/gfortran/ifort
+
+
+From the repository directory (`cd EDIpack2`) make a standard
+out-of-source CMake compilation:
+
+GNU Make
+------------
+Using GNU `make` is the default CMake workflow, with widest version
+support (CMake > 3.0). Note that parallel `make` execution is tested
+and working.
+
+.. code-block:: bash
+		
+   mkdir build 
+   cd build  
+   cmake .. 
+   make -j
+
+
+
+Ninja
+------------
+Using `ninja` if a fortran-capable version of `ninja <https://ninja-build.org>`_ is available in your system (and CMake can take advantage of it), you can use it to build the library at lightning, multi-threaded, speed. 
+
+.. code-block:: bash
+		
+   mkdir build    
+   cd build  
+   cmake -GNinja ..  
+   ninja
+
+
+
+
+The `CMake` compilation can be customized using the following
+additional variables (default values between `< >`):   
+
+* `-DPREFIX=prefix directory <~/opt/EDIpack2/VERSION/PLATFORM/[GIT_BRANCH]>` 
+
+* `-DUSE_MPI=<yes>/no`  
+
+* `-DVERBOSE=yes/<no>`  
+
+* `-DBUILD_TYPE=<RELEASE>/TESTING/DEBUG/AGGRESSIVE`  
+
+
+Please follow the instructions on the screen to complete installation on your environment.  
+The library can be loaded using one of the following, automatically generated, files :  
+
+* pkg-config file in `~/.pkg-config.d/EDIpack2.pc`  
+* environment module file `~/.modules.d/EDIpack2/<PLAT>`  
+* homebrew `bash` script `<PREFIX>/bin/configvars.sh`
+
+
+Python API: EDIpy2 
+======================
+The `edipy2` python module is installable from this folder via:
+o R
+.. code-block:: bash
+		
+   pip install .
+
+on some systems such as Debian >= 11 and Mac Os, if a virtual environment is not in use, the flag `--break-system-packages` has to be set. This creates no issue since no distro is packaging this library.
+To remove the module, run:
+
+.. code-block:: bash
+		
+   pip uninstall -y edipy2
+
+with same caveat for the `--break-system-packages` flag.
+
+See `EDIpy2` documentation for more information. 

doc/fortran_src/edipack2.rst

@@ -1,18 +1,12 @@
 EDIpack 2.0
 =============
 
-EDIpack2.0: a massively parallel Lanczos Exact Diagonalization based
-solver for generic quantum impurity problems. 
-
-For the time being we  traverse the documentation following the
-compilation structure in CMake.
-
 .. toctree::
    :maxdepth: 1
    :glob:
    :caption: Contents:
 
-   init
-
-
+   01_dependencies
+   02_installation
+   
 

doc/index.rst

@@ -1,21 +1,46 @@
-EDIpack 2.0: A massively parallel Exact Diagonalization solver for quantum Impurity problems
-============================================================================================================
+EDIpack2.0
+################
+
+A massively parallel Exact Diagonalization solver for quantum Impurity problems.
+***************************************************************************************************************
 
 (under construction)
 
-EDIpack2.0 is a suitable extension of `EDIpack
-<https://github.com/aamaricci/EDIpack>`_ : a  Lanczos based method 
+Introduction
+===============
+
+EDIpack2.0 is a Lanczos based method 
 for the solution of generic Quantum Impurity problems,  exploiting distributed memory MPI parallelisation.
-This 2.0 version, aims to solve single-site, multi-orbital models, in either  *normal*, *superconducting* (s-wave) or *Spin-non-conserving* (e.g. with Spin-Orbit Coupling or in-plane magnetization) phases, including electron-phonons coupling. The code works at zero and low temperatures.   
+The 2.0 version extends the `EDIpack <https://github.com/aamaricci/EDIpack>`_ by enabling the solution of
+single-site, multi-orbital models with different conserved
+quantum numbers :math:`\vec{Q}` corresponding to separate operational modes:
+
+* :math:`\vec{Q}=[\vec{N}_\uparrow,\vec{N}_\downarrow]` for which
+  either the number of total or orbital spin up and down electrons is
+  conserved: **normal**: 
+* :math:`\vec{Q}=S_z`  with *s*-wave pairing with conserved total
+  magnetization:  **superconducting**  
+* :math:`\vec{Q}=N_{\rm tot}`  where spin degrees
+  freedom is not fully conserved:  **non-SU(2)**
+  (used, for instance, in presence of local Spin-Orbit coupling, in-plane magnetization or in-plane triplet excitonic condensation)
+
+All modes include electron-phonon coupling (local or Holstein
+phonons). EDIpack2.0  is designed to obtain the lowest part of the
+spectrum of the problem, thus it naturally works at zero temperature
+but can also be used to explore low temperature properties.  
 
-See
-`j.cpc.2021.108261 <https://doi.org/10.1016/j.cpc.2021.108261>`_
-for further information about the underlying algorithm in the *normal*
-channel. 
-Substantial modifications have been developed to address the Superconducting and non-SU(2) channels.  
+The EDIpack2.0 diagonalization algorithm is based on a massively
+parallel execution of matrix-vector products, required in the context
+of Lanczos-Arnoldi linear procedures.  See `j.cpc.2021.108261
+<https://doi.org/10.1016/j.cpc.2021.108261>`_ for a detailed
+descriptions of these algorithms.
+However, substantial modifications have been introduced in the 2.0
+version to address the *Superconducting* and *non-SU(2)* channels.  
 An updated manuscript will be released soon. 
 
 
+
+
 .. toctree::
    :maxdepth: 2