README.md 3.65 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

Jonas Schwab's avatar
Jonas Schwab committed
18
The **documentation** can be found [here](http://gitpages.physik.uni-wuerzburg.de/Jonas_schwab/pyalf-docu).
19

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
Jonas Schwab's avatar
Jonas Schwab committed
35
36
* The libraries Lapack and Blas
* A Fortran compiler, such as gfortran or ifort,
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
37

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

Jonas Schwab's avatar
Jonas Schwab 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` if the used shell if bash or `~/.zshrc`, if the shell is zsh:
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

Jonas Schwab's avatar
Jonas Schwab committed
48
49
50
51
52
53
54
55
There are multiple ways to use pyALF, which roughly breaks down into three approaches:
* Using Jupyter notebooks
* Using the command line interface
* Use the module `py_alf` in custom scripts

### Jupyter notebooks

A convenient way to use pyALF is through Jupyter notebooks. They [are run](https://jupyter.readthedocs.io/en/latest/running.html) through a Jupyter server started, e.g., from the command line:
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
56
57

```bash
Jonas Schwab's avatar
Jonas Schwab committed
58
jupyter-notebook
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
59
```
Jonas Schwab's avatar
Jonas Schwab committed
60

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
61
or
Jonas Schwab's avatar
Jonas Schwab committed
62

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
63
```bash
Jonas Schwab's avatar
Jonas Schwab committed
64
jupyter-lab
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
65
```
Jonas Schwab's avatar
Jonas Schwab committed
66

Jonas Schwab's avatar
Jonas Schwab committed
67
68
69
which opens the "notebook dashboard" in your default browser, from where one can open the sample notebooks in `Notebooks/` and create new notebooks.

### Command line interface
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
70

Jonas Schwab's avatar
Jonas Schwab committed
71
pyALF also delivers a set of command line scripts, located in the folder `/py_alf/cli/`, to be use from a UNIX shell. For convenient access, it makes sense to add the folder to the environment variable `PATH`:
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
72
73

```bash
74
export PATH="/path/to/pyALF/py_alf/cli:$PATH"
Jonas Schwab's avatar
Jonas Schwab committed
75
76
77
78
79
```

Then the scripts can simply be called by their names, try e.g. 

```bash
80
alf_run.py -h
81
```
Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
82

Jonas Schwab's avatar
Jonas Schwab committed
83
For a full list of command line scripts see [here](gitpages.physik.uni-wuerzburg.de/Jonas_schwab/pyalf-docu/source/reference/cli.html).
Jonas Schwab's avatar
Jonas Schwab committed
84
85
86
87
88

### Use module `py_alf` in custom scripts

Finally, one can also use the module module `py_alf` in custon Python scripts, which is analogous to the usage in Jupyter notebooks minus some interactivity.

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
89
## License
Jonas Schwab's avatar
Jonas Schwab committed
90

Jefferson Stafusa E. Portela's avatar
Jefferson Stafusa E. Portela committed
91
92
93
94
95
96
97
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).