Consistency-based Sheaf Diffusion

Getting started

Basic requirements

The code have been tested on a cluster of Linux nodes using SLURM.
We cannot guarantee the functioning of the code if the following requirements are not met:

Installation

To properly install and run our code we recommend using a virtual environment (e.g., created via pyenv-virtualenv or conda).

The entire installation process consists of 3(+1) steps. You can skip step 0 at you own "risk".

(Optional) Step 0: create a virtual environment

In the following we show how to create the environment via pyenv and pyenv-virtualenv. The steps are the following:

• install pyenv (if you don't have it yet) by following the original guidelines;
• install the correct Python version:

  pyenv install 3.10.4

• create a virtual environment with the correct version of Python:

  pyenv virtualenv 3.10.4 <PROJECT_NAME>

Step 1: clone the repository, change into it and (optional) activate the environment

This step allows you to download the code in your machine, move into the correct directory and (optional) activate the correct environment. The steps are the following:

• clone the repository:

  git clone <PROJECT_URL>

• change into the repository:

  cd <PROJECT_NAME>

• (optional) activate the environment (everytime you'll enter the folder, the environment will be automatically activated)

  pyenv local <PROJECT_NAME> 

Step 2: install PyTorch and PyTorch Geometric

Depending on your CPU/GPU setup you might need to install PyTorch and PyTorch Geometric in different ways.
We provide a detailed explanation on how to install these packages here. Please also consider to refer to the original documentation (PyTorch, PyG) in case of any doubts.

Make sure the environment is active, in case you created it.

Step 3: install the code as a local package

All the required packages (beside Pytorch/Pytorch Geometric) are defined in the pyproject.toml file and can be easily installed via pip as following:

pip install --editable .

or equivalently:

pip install -e .

Running Experiments

1. Set up the sweeper's parameters in the config/exp/<YOUR_EXP>.yaml file according to the experiments you want to run.
2. Run python exec.py --multirun +exp=YOUR_EXP hydra/launcher/qos=YOUR_QOS to automatically run experiments on the SLURM cluster, or python exec.py --multirun +exp=YOUR_EXP hydra/launcher=local to run them locally.

Reading Results

An example how to load and read results is given in notebooks/VisualizeResults.ipynb

Support

If you have any questions regarding the code and its reproducibility, feel free to contact the reference author.

Authors

• David Reifferscheidt*:

  Master's student at the Technical University of Munich (TUM)

  • Email: david.reifferscheidt@tum.de * Reference author
• Filippo Guerranti*:

  PhD student at the DAML group, Technical University of Munich (TUM)

  • Email: f.guerranti@tum.de * Reference author

Citation

If you build upon this work, please cite our paper as follows: TBD

@inproceedings{CITATION_KEY,
    title = {{PAPER_TITLE}},
    author = {}
    booktitle = {{BOOK_TITLE}},
    year = {YEAR}
}