# Installation and setup

It is recommended to setup a [Python virtual environment](https://docs.python.org/3/library/venv.html) first. All installation methods outlined below require the `pip` package. First make sure you have the most recent pip:

```bash
$ python -m pip install --upgrade pip 
```


## Installation from the pypi.org repository

This is the recommended way to install the latest release:

```bash
$ python -m pip install vre-middleware 
```


## Local installation from source

An installation from source requires to either clone the repository or to download a source archive file from [here](https://gitlab.kit.edu/kit/virtmat-tools/vre-middleware/-/releases). Here, we show how to use the first method and then to install VRE Middleware using `pip`:

```bash
$ git clone https://gitlab.kit.edu/kit/virtmat-tools/vre-middleware.git
$ cd vre-middleware
$ python -m pip install .
```

This command will install VRE mdiddleware and all dependency packages into your [Python virtual environment](https://docs.python.org/3/library/venv.html). 


## Development installation

You can install VRE Middleware in such a way that changes in the local repository source tree become immediately available without re-installation of the package:

```bash
$ cd vre-middleware
$ python -m pip install -e .
```

After installing the packages, the modules from VRE Middleware can be loaded, for example

```python
from virtmat.middleware.query.wfquery import WFQuery
```

**NOTE: Broken install due to an issue in FireWorks**

Fresh installations of VRE Middleware will currently *sometimes* not work. When running the API or the GUI this error may occur:

```
AttributeError:
"safe_load()" has been removed, use

  yaml = YAML(typ='safe', pure=True)
  yaml.load(...)

instead of file "jupyter-base-2024-05-14/lib64/python3.9/site-packages/fireworks/utilities/fw_serializers.py", line 256

            dct = yaml.safe_load(f_str)
```

This [issue](https://github.com/materialsproject/fireworks/issues/516) has been solved in FireWorks main branch but not yet released. See more discussions in this [issue](https://github.com/materialsproject/fireworks/issues/531).

As a work-around, VRE Middleware tries to downgrade `ruamel.yaml` automatically. If downgrade of `ruamel.yaml <0.18.0` is not possible, for example when the `ruamel.yaml` package is installed system-wide, then the error above occurs when running `texts`. In this case, another non-automatic workaround has to be performed by the user. A fresh virtual environment has to be created (without the packages fireworks, vre-language and vre-middleware). Then VRE Middleware is installed as in the instructions above after the following command:

```
python -m pip install git+https://github.com/materialsproject/fireworks.git
```