Skip to content

Latest commit

 

History

History
130 lines (86 loc) · 4.7 KB

quick_start.md

File metadata and controls

130 lines (86 loc) · 4.7 KB
Raw

Heat Quick Start

No-frills instructions for new users and new contributors.

New Users (conda, pip, HPC, Docker)

conda

The Heat conda build includes all dependencies including OpenMPI.

conda create --name heat_env
conda activate heat_env
conda -c conda-forge heat

Test your installation.

pip

Pre-requisite: MPI installation. We test with OpenMPI

Virtual environment and installation:

python -m venv heat_env
source heat_env/bin/activate
pip install heat[hdf5,netcdf]

Test your installation.

HPC

Work in progress.

Docker

Get the docker image from our package repository

docker pull ghcr.io/helmholtz-analytics/heat:<version-tag>

or build it from our Dockerfile

git clone https://github.com/helmholtz-analytics/heat.git
cd heat/docker
docker build --build-args HEAT_VERSION=X.Y.Z --PYTORCH_IMG=<nvcr-tag> -t heat:latest .

<nvcr-tag> should be replaced with an existing version of the official Nvidia pytorch container image. Information and existing tags can be found on the here

See our docker README for other details.

Test

In your terminal, test your setup with the heat_test.py script:

mpirun -n 2 python heat_test.py

It should print something like this:

x is distributed:  True
Global DNDarray x:  DNDarray([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=ht.int32, device=cpu:0, split=0)
Global DNDarray x:
Local torch tensor on rank  0 :  tensor([0, 1, 2, 3, 4], dtype=torch.int32)
Local torch tensor on rank  1 :  tensor([5, 6, 7, 8, 9], dtype=torch.int32)

New Contributors

  1. Pick an Issue you'd like to work on. Check out Good First Issues, start from the most recent. Get in touch and ask to be assigned to the issue.

  2. IMPORTANT: As soon as an issue is assigned, a new branch will be created (a comment will be posted under the relevant issue). Do use this branch to make your changes, it has been checked out from the correct source branch (i.e. main for new features, release/* for bug fixes).

  3. Fork or, if you have write access, clone the Heat repository.

  4. Create a virtual environment heat_dev with all dependencies via heat_dev.yml. Note that heat_dev.yml does not install Heat.

    conda env create -f heat_dev.yml
conda activate heat_dev

  5. In the /heat directory of your local repo, install the pre-commit hooks:

    cd $MY_REPO_DIR/heat/
pre-commit install

  6. Write and run (locally) unit tests for any change you introduce. Here's a sample of our test modules.

    Running all unit tests locally, e.g. on 3 processes:

    mpirun -n 3 python -m unittest

    Testing one module only, e.g. manipulations:

    mpirun -n 3 python -m unittest heat/core/tests/test_manipulations.py

    Testing one function within a module, e.g. manipulations.concatenate:

    mpirun -n 3 python -m unittest heat.core.tests.test_manipulations.TestManipulations.test_concatenate

    Testing with CUDA (if available):

    export HEAT_TEST_USE_DEVICE=gpu
mpirun -n 3 python -m unittest

    Helpful options for debugging:

    mpirun --tag-output -n 3 python -m unittest -vf

  7. After making and pushing your changes, go ahead and create a Pull Request. Make sure you go through the Due Diligence checklist (part of our PR template). Consider allowing us to edit your branch for a smoother review process.

    Thank you so much for your time!