Installation

Local Install

First, make sure that the libraries and packages listed in Dependencies within README.md are installed. Installation might differ per operating system. Most of the Python packages should be available from PyPI.

Afterwards, to install REHEATFUNQ locally, run the following command in the REHEATFUNQ source code root directory

pip install --user .

Alternatively, if you have not downloaded the source yet, you can run the following command:

pip install 'reheatfunq @ git+https://github.com/mjziebarth/REHEATFUNQ'

Container/Docker Images

REHEATFUNQ can also be used within the provided Docker images. The images contain a Jupyter notebook server running as user reheatfunq, and all required packages are installed.

Two container images are supplied: Dockerfile and Dockerfile-stable. The former builds on the python:slim-bookworm image and pulls up-to-date dependencies from the web. It is more lightweight, uses considerably less compile time, and can utilize new features of the updated software. On the flip side, this image might not be able to (exactly) reproduce the simulations from the paper if any of the important packages introduces changes to the numerics.

For this reason, Dockerfile-stable is provided which uses vendored sources and should stay reproducible in the long term. It builds upon a snapshot of the Debian slim image for basic functionality and vendors the relevant source code of the REHEATFUNQ model and its foundations to build a reproducible model.

Dockerfile

Two container services are covered in this documentation, Podman and Docker. To build the Dockerfile container, run either

podman build --format docker -t reheatfunq .

or

sudo docker build -t 'reheatfunq' .

within the repository’s root directory (sudo may or may not be required depending on the Docker setup).

The Jupyter notebook server is exposed at the container’s 8888 port. This port may or may not be free on your system. To run REHEATFUNQ in the container, first identify a free port XXXX on your machine. Then, run

podman run -p XXXX:8888 reheatfunq

or

sudo docker run -p XXXX:8888 reheatfunq

The container image does not contain all required data to run the analysis of the REHEATFUNQ paper. Most prominently, that includes the NGHF.csv of Lucazeau [L2019]. A convenient method to copy this (or other files you wish to copy) to the running container is the Jupyter server file up- and download dialog.

You can shut down the container image by quitting the Jupyter server via the web interface.

Dockerfile-stable

This container image requires the sources of the software upon which REHEATFUNQ is built. The combined source code archive of this software is large (the Dockerfile-stable starts by bootstrapping the GNU Compiler Collection and successively compiles the Python ecosystem and numeric software) and it is split off this git repository. The archives vendor-1.3.3.tar.xz and vendor-2.0.1.tar.xz from GFZ Data Services contains the required software.

There are two ways to build the Dockerfile-stable image. Since version 2.0.1, the shell script build-Dockerfile-stable.sh is available to facilitate the build process. Using this script, the build process should be as simple as

bash build-Dockerfile-stable.sh

A second way is to build the image manually. This first requires downloading vendor-1.3.3.tar.xz and vendor-2.0.1.tar.xz. Following the instructions presented therein, extract the compile and wheels subfolders into the vendor directory of this repository.

Then, you can build and run the Docker image as below (you might want to rename the container according to the REHEATFUNQ version you are using—unless stated otherwise, the following versions are compatible with vendor-1.3.3.tar.xz and vendor-2.0.1.tar.xz):

podman build --format docker -f Dockerfile-stable -t reheatfunq-2.0.1-stable
podman run -p XXXX:8888 reheatfunq-2.0.1-stable

or

sudo docker build -f Dockerfile-stable -t 'reheatfunq-2.0.1-stable' .
sudo docker run -p XXXX:8888 reheatfunq-2.0.1-stable

Nearly all of the dependencies of this container are contained in vendor-1.3.3.tar.xz and vendor-2.0.1.tar.xz so that this image should build reproducibly in the long-term. Nevertheless, the Debian snapshot used as a base image might be unavailable at some point in the future of this writing. In this case, it should be possible to swap the base image to another linux without great impact. For the purpose of base image agnosticism, the container image rebuilds gcc and installs libraries to the /sci directory.

In case that swapping the base image is neccessary but does not work out of the box, it is likely that the initial user setup or the installation of build tools to bootstrap gcc has to be adjusted.

Known Issues

Cython 3.0.4 compile failure (REHEATFUNQ v1.4.0)

With Cython version 3.0.4 (potentially also other versions), REHEATFUNQ v1.4.0 may fail to install locally with a (fairly extensive) error message that boils down to the following error:

reheatfunq/coverings/rdisks.pyx:235:27: Cannot assign type 'iterator' to 'const_iterator'

On Cython 3.0.4, this issue can be fixed by editing line 213 of the file reheatfunq/coverings/rdisks.pyx from

cdef unordered_map[vector[cbool],size_t].iterator it

to

cdef unordered_map[vector[cbool],size_t].const_iterator it

Local install should now proceed normally.