README.md 2.95 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
* Obtaining and compiling the ALF source code
* Preparing and running simulations
* Postprocessing and displaying the data obtained during the simulation

It introduces:
Jonas Schwab's avatar
Jonas Schwab committed
12

Jonas Schwab's avatar
Jonas Schwab committed
13
* The Python module `py_alf`, exposing all the package's utility to Python.
Jonas Schwab's avatar
Jonas Schwab committed
14
* A set of command line tools in the folder `py_alf/cli`, that make it easy to leverage pyALF from a Unix shell.
Jonas Schwab's avatar
Jonas Schwab committed
15
16
* 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
17

18
19
The **preliminary documentation** can be found [here](http://gitpages.physik.uni-wuerzburg.de/Jonas_schwab/pyalf-docu).

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
20
21
## Prerequisites

Jonas Schwab's avatar
Jonas Schwab committed
22
* Python3
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
23
* Jupyter
Jonas Schwab's avatar
Jonas Schwab committed
24
* The following Python packages:
Jonas Schwab's avatar
Jonas Schwab committed
25
26
27
28
29
30
31
  * h5py
  * numpy
  * pandas
  * matplotlib
  * numba
  * scipy
  * tkinter
Jonas Schwab's avatar
Jonas Schwab committed
32
  * ipywidgets
Jonas Schwab's avatar
Jonas Schwab committed
33
  * ipympl
Jonas Schwab's avatar
Jonas Schwab committed
34
  * f90nml
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
35
36
37
* the libraries Lapack and Blas
* a Fortran compiler, such as gfortran or ifort,

38
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
39

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
40
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
41
42
43
44
45

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

46
## Usage
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
47
48
49
50

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
51
jupyter-notebook
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
52
```
Jonas Schwab's avatar
Jonas Schwab committed
53

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
54
or
Jonas Schwab's avatar
Jonas Schwab committed
55

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
56
```bash
Jonas Schwab's avatar
Jonas Schwab committed
57
jupyter-lab
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
58
```
Jonas Schwab's avatar
Jonas Schwab committed
59

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
60
61
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.

62
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
63
64

```bash
65
66
export PATH="/path/to/pyALF/py_alf/cli:$PATH"
alf_run.py -h
67
```
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
68
69

## License
Jonas Schwab's avatar
Jonas Schwab committed
70

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
71
72
73
74
75
76
77
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).