README.md 3.53 KB
Newer Older
1
2
[![Unitary Fund](https://img.shields.io/badge/Supported%20By-UNITARY%20FUND-brightgreen.svg?style=for-the-badge)](http://unitary.fund)

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
3
4
## pyALF

Jonas Schwab's avatar
Jonas Schwab committed
5
A Python package building on top of [ALF](https://git.physik.uni-wuerzburg.de/ALF/ALF), meant to simplify the different steps of working with ALF, including:
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
6

Jonas Schwab's avatar
Jonas Schwab committed
7
8
9
10
11
12
13
14
15
* Obtaining and compiling the ALF source code
* Preparing and running simulations
* Postprocessing and displaying the data obtained during the simulation

It introduces:
* The Python module `py_alf`, exposing all the packages utility to Python.
* A set of command line tools in the folder `py_alf/cli`, that make it easy to levarate pyALF from a Unix shell.
* Jupyter notebooks in the folder `Notebooks`, serving as an easy introduction to QMC and ALF
* Python Scripts in the folder `Scripts` that can be run to reproduce benchmark results for established models
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
16
17
18
19


## Prerequisites

Jonas Schwab's avatar
Jonas Schwab committed
20
* Python3
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
21
* Jupyter
22
* Prerequisites for analysis Python packages:
Jonas Schwab's avatar
Jonas Schwab committed
23
24
25
26
27
28
29
30
  - h5py
  - numpy
  - pandas
  - matplotlib
  - numba
  - scipy
  - tkinter
  - f90nml
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
31
32
33
* the libraries Lapack and Blas
* a Fortran compiler, such as gfortran or ifort,

34
where the last two are required by the main package [ALF](https://git.physik.uni-wuerzburg.de/ALF).
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
35

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
36
Also, add pyALF's path to your environment variable `PYTHONPATH`. In Linux, this can be achieved, e.g., by adding the following line to `.bashrc`:
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
37
38
39
40
41
42

```bash
export PYTHONPATH="/local/path/to/pyALF:$PYTHONPATH"
```


43
## Usage
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
44
45
46
47

Jupyter notebooks [are run](https://jupyter.readthedocs.io/en/latest/running.html) through a Jupyter server started, e.g., from the command line:

```bash
Jonas Schwab's avatar
Jonas Schwab committed
48
jupyter-notebook
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
49
50
51
```
or
```bash
Jonas Schwab's avatar
Jonas Schwab committed
52
jupyter-lab
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
53
54
55
```
which opens the "notebook dashboard" in your default browser, where you can navigate through your file structure to the pyALF directory. There you will find the interface's core module, `py_alf.py`, some auxiliary files, and a number of notebooks.

56
However, pyALF can also be used to start a simulation from the command line, without starting a Jupyter server. For instance, check the help message:
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
57
58

```bash
59
60
export PATH="/path/to/pyALF/py_alf/cli:$PATH"
alf_run.py -h
61
```
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
62

63

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
64
65
## Files and directories

66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
```
 pyALF/
    └── py_alf/
        └── __init__.py
        └── cli/
             └── What is currently in /Scripts
        ├── alf_source.py
        ├── simulation.py
        ├── lattice.py
        └── ...
    ├── doc/
    ├── Notebooks/
    └── Scripts/
```

* `py_alf/` - provides interfaces for compilig, running and postprocessing ALF in Python
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
* `default_variables.py` - defines dictionaries containing all ALF parameters with default values
* `Run.py` - helper script for compiling, running and testing ALF
* `Sims` - configuration for running directly from the command line
* `Notebooks` - directory containing Jupyter notebooks



## License
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 (see license.GPL and license.additional)
and took the liberty as per GPLv3 section 7 to include additional terms that deal with the attribution
of the original authors(see 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)
We mention that we link against parts of lapack which licensed under a BSD license(see license.BSD).