README.md 8.66 KB
Newer Older
1
2
3
# ALF #
[![pipeline status](https://git.physik.uni-wuerzburg.de/fassaad/General_QMCT_code/badges/master/pipeline.svg)](https://git.physik.uni-wuerzburg.de/fassaad/General_QMCT_code/commits/master)
[![coverage report](https://git.physik.uni-wuerzburg.de/fassaad/General_QMCT_code/badges/master/coverage.svg)](https://git.physik.uni-wuerzburg.de/fassaad/General_QMCT_code/commits/master)
4
5
6
7


**Project website: https://alf.physik.uni-wuerzburg.de/.**

8
-> Interested contributors please check our [CONTRIBUTING.md](https://git.physik.uni-wuerzburg.de/ALF/ALF/-/blob/master/CONTRIBUTING.md) guidelines.
9
10
11
12

-> This is the **development** version of ALF, the latest stable version is [ALF 2.3](https://git.physik.uni-wuerzburg.de/ALF/ALF/-/tree/ALF-2.3/).

## Description ##
13
14

The **A**lgorithms for **L**attice **F**ermions package provides a general code for the finite temperature  and projective auxiliary field Quantum Monte Carlo algorithm.       The code  is engineered to  be able simulate any model that can be written in terms of  sums of single body operators, of squares of single body operators and single body operators coupled to an Ising field with  given dynamics. We  provide predefined types that allow  the user to specify the model, the  Bravais lattice  as well as equal time and time displaced observables.     The code supports an MPI implementation.   Examples such as the Hubbard model, the SU(N) Kondo lattice model, tV models,  models with long ranged interactions as well as Z2 lattice gauge theories coupled to fermions adn Z2 matter are discussed in the [documentation](https://git.physik.uni-wuerzburg.de/ALF/ALF/-/jobs/artifacts/master/raw/Documentation/doc.pdf?job=create_doc). Slides on the auxiliary field QMC can be found [here.](https://git.physik.uni-wuerzburg.de/ALF/ALF_Tutorial/-/blob/master/Presentations/ALF_2020_Assaad.pdf)
Fakher F. Assaad's avatar
Update    
Fakher F. Assaad committed
15

Florian Goth's avatar
Florian Goth committed
16
The Hamiltonians we can consider read:
Florian Goth's avatar
Florian Goth committed
17
![The Hamiltonian0](Images/Hamiltonian0.png "The Hamiltonian")
18
where
Florian Goth's avatar
Florian Goth committed
19
![The Hamiltonian1](Images/Hamiltonian1.png "Parts explanation")
Fakher F. Assaad's avatar
Fakher F. Assaad committed
20

21
Here Z denotes a scalar field (Ising or real continuous field) with predefined dynamics. If your model can be written in this form then it will be amenable to the ALF. 
Fakher F. Assaad's avatar
Fakher F. Assaad committed
22

23
24
25
26
## pyALF ##

For ease of use, the  [pyALF](https://git.physik.uni-wuerzburg.de/ALF/pyALF) repository  provides a python interface to run the ALF-code

27
## Doxygen ##
Fakher F. Assaad's avatar
Fakher F. Assaad committed
28

29
You can find here [Doxygen](https://gitpages.physik.uni-wuerzburg.de/ALF/ALF/) formatted documentation. (Work in progress)
Fakher F. Assaad's avatar
Fakher F. Assaad committed
30

31
32
33
34
35
## Installation ##

* Please check the latest documentation (Documentation/doc.pdf) for more details and Sec. 6.1, "Quick Start", to try ALF out straight away.

### PREREQUISITES ###
Fakher F. Assaad's avatar
Fakher F. Assaad committed
36

Jonas Schwab's avatar
Jonas Schwab committed
37
38
39
40
41
42
43
44
45
* Make
* A Fortran compiler, such as `gfortran` or `ifort`
* Blas+Lapack libraries
* Python3
* MPI libraries (optional)
* For HDF5 (optional)
	* C++ preprocessor (default: g++)
	* Curl
	* gzip development libraries
Fakher F. Assaad's avatar
Fakher F. Assaad committed
46

47
48
49

* **Linux**   
  To install the relevant packages.
Jonas Schwab's avatar
Jonas Schwab committed
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

  **Debian/Ubuntu/Linux Mint**: 
  ```
  sudo apt install make gfortran libblas-dev liblapack-dev \
            python3 libopenmpi-dev g++ curl libghc-zlib-dev git
  ```

  **Red Hat/Fedora/CentOS**:
  ```
  sudo yum install make gfortran libblas-devel liblapack-devel \
            python3 libopenmpi-dev g++ curl zlib git
  ```

  **OpenSuSE/SLES**:
  ```
  sudo zypper install make gcc-fortran lapack-devel \
               python3 libopenmpi-devel gcc-c++ curl zlib-devel git
  ```

  **Arch Linux**:
  ```
  sudo pacman -S make gcc-fortran lapack python3 openmpi curl zlib git
  ```
73
74
75
76
77
78
79
80

* **Other Unixes**   
  gfortran and the lapack implementation from netlib.org should be available for your system. Consult the documentation of your system on how to install the relevant packages. The package names from linux should give good starting points for your search.

* **MacOS**   
  gfortran for MacOS can be found at https://gcc.gnu.org/wiki/GFortranBinaries#MacOS. Detailed information on how to install the package  can be found at: https://gcc.gnu.org/wiki/GFortranBinariesMacOS. You will need to have Xcode as well as the  Apple developer tools installed. 

* **Windows**   
Jonas Schwab's avatar
Jonas Schwab committed
81
  The easiest way to compile ALF in Windows is trough the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL). It allows to run Linux within Windows. You can install the WSL and follow the instructions for Linux.
Fakher F. Assaad's avatar
Fakher F. Assaad committed
82
83


84
## CONFIGURATION FOR COMPILATION ##
85
<!--**setenv.sh**   sets the default set of envorinment variables.  Do not change  this since this default set of  environment variables is required for the tests to run adequaltely.-->
Fakher F. Assaad's avatar
Fakher F. Assaad committed
86

87
**configure.sh**  It is recommended to use this script to set the environment variables. Type ./configure.sh to  browse through a list of options. Notice that directory names containing **spaces are not supported**.
Fakher F. Assaad's avatar
Fakher F. Assaad committed
88

Fakher F. Assaad's avatar
Fakher F. Assaad committed
89
Once you have run the configuration script, change directory to Libraries, and to Analysis  and run the Makefiles there. In the Prog directory then type make examples.   The other programs are being updated to comply with the new version of the code.  
Fakher F. Assaad's avatar
Fakher F. Assaad committed
90

Fakher F. Assaad's avatar
Fakher F. Assaad committed
91
## FILES AND DIRECTORIES ##
Fakher F. Assaad's avatar
Update    
Fakher F. Assaad committed
92

93
**Libraries**    Libraries. Once that the environment is set in the file configure.sh  the Libraries can be compiled with the **make** command. 
Florian Goth's avatar
Florian Goth committed
94

Fakher F. Assaad's avatar
Fakher F. Assaad committed
95
**Prog**   Main program and subroutines.  
Florian Goth's avatar
Florian Goth committed
96

Fakher F. Assaad's avatar
Fakher F. Assaad committed
97
**Analysis** Analysis programs. 
Florian Goth's avatar
Florian Goth committed
98

99
**Scripts\_and\_Parameters\_files**  Helper scripts and the Start/ directory, which contains the files required to start a run. 
100

101
 
102
**Documentation**  We have included in the file  [doc.pdf](https://git.physik.uni-wuerzburg.de/ALF/ALF/-/jobs/artifacts/master/raw/Documentation/doc.pdf?job=create_doc) an extensive documentation.
103

104
105
**testsuite** An automatic test suite for various parts of the code

Florian Goth's avatar
Florian Goth committed
106

Fakher F. Assaad's avatar
Fakher F. Assaad committed
107
## TESTING ##
Fakher F. Assaad's avatar
Fakher F. Assaad committed
108

Florian Goth's avatar
Florian Goth committed
109
110
111
112
113
114
115
116
117
We have about 30 tests that test various parts of the program in the folder testsuite.
As testing framework we employ CTest.
From the subfolder testsuite the tests can be run as follows
- mkdir tests
- cd tests
- cmake ..
- make
- make test

118

Florian Goth's avatar
Florian Goth committed
119
## LICENSE ##
120
121
122
123
The various works that make up the ALF project are placed under licenses that put a strong emphasis on the attribution of the original authors and the sharing of the contained knowledge.
To that end we have placed the ALF source code under the GPL version 3 license and took the liberty as per GPLv3 section 7 to include additional terms that deal with the attribution
of the original authors (see license.GPL and license.additional).
The Documentation of the ALF project by the ALF contributors is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License (see Documentation/license.CCBYSA). Note that we link against parts of lapack, which is licensed under a BSD license (see license.lapack).
Florian Goth's avatar
Florian Goth committed
124

125
126
127
128
129
## KNOWN ISSUES ##

We have detected a bug in both 2017 versions of Intel's MPI implementation (mpi.intel/2017(default) 
and mpi.intel/2017.2) if used in combination with the parallel (threaded) MKL library. The advise is to 
use either the 2016 suite (intel/16.0 (compiler), mpi.intel/5.1 and mkl/11.3 ) or the new 2018 suite 
Florian Goth's avatar
Florian Goth committed
130
(intel/18.0 (compiler), mpi.intel/2018 and mkl/2018). We did not detect this issue in both environments. 
131
132
133
134
135
136
137
138
139
140
You should also be aware the by default, dynamic linking is used. Hence if you use the 2016 or 2018 modules 
at compilations, the bug can reenter if you still load the 2017 versions at runtime. So please adapt your
configureHPC.sh as well as your Jobfiles for the loadleveler accordingly.
Additional note: In the serial version, the bug also seems to be absent. 
If you want to use the 2017 suite, you have to use the serial version of MKL (mkl/2017_s), which means you 
cannot profit from openMP multi-threading. This library is linked statically, hence taking care of this at 
compile time is sufficient and there is no need to adapt the Jobfiles.
WARNING: Even if you do not use parallel tempering actively, we still strongly suggest to take care of 
the above bug as it is extremely hard to estimate hidden influences and correlations of this memory 
allocation bug in the rest of the program. It is possible the other parts of the algorithm might be 
Florian Goth's avatar
Florian Goth committed
141
142
affected apart from the tempering exchange step even so we have absolutely no hint of additionally 
affected sections in ALF.
143
144
145
146
147
148
149
150
151
152
153

Intel suite 2017: Apparently, there seems to be a bug in the Intel MPI threaded memory allocator if both Intel MPI 
implementation and the PARALLEL version of MKL is used. This bug corrupts the data transmission during tempering moves such 
that the Monte Carlo is broken. The current advise is to either use an earlier version (2016 and before) or a newer one
(2018 and later). It should also be OK to use the sequential MKL library if openMP multi-threading is not required. 
Setting the environment variable OMP_NUM_THREADS=1 however does not fix the bug as this still uses the threaded MKL 
library (Date: 1. June 2018)