Skip to content

Extending GaNDLF


Before starting to work on the code-level on GaNDLF, please follow the instructions to install GaNDLF from sources. Once that's done, please verify the installation using the following command:

# continue from previous shell
(venv_gandlf) $> 
# you should be in the "GaNDLF" git repo
(venv_gandlf) $> python ./gandlf_verifyInstall

Submodule flowcharts

  • The following flowcharts are intended to provide a high-level overview of the different submodules in GaNDLF.
  • Navigate to the file in each submodule folder for details.

Overall Architecture

Dependency Management

To update/change/add a dependency in setup, please ensure at least the following conditions are met:

  • The package is being actively maintained.
  • The new dependency is being testing against the minimum python version supported by GaNDLF (see the python_requires variable in setup).
  • It does not clash with any existing dependencies.

Adding Models

Adding Augmentation Transformations

Adding Preprocessing functionality

Adding Training Functionality

Adding Inference Functionality

Update parameters

For any new feature, please ensure the corresponding option in the sample configuration is added, so that others can review/use/extend it as needed.

Update Tests

Once you have made changes to functionality, it is imperative that the unit tests be updated to cover the new code. Please see the full testing suite for details and examples.

Run Tests


There are two types of tests: unit tests for GaNDLF code, which tests the functionality, and integration tests for deploying and running mlcubes. Some additional steps are required for running tests:

  1. Ensure that the install optional dependencies [ref] have been installed.
  2. Tests are using sample data, which gets downloaded and prepared automatically when you run unit tests. Prepared data is stored at ${GaNDLF_root_dir}/testing/data/ folder. However, you may want to download & explore data by yourself.

Unit tests

Once you have the virtual environment set up, tests can be run using the following command:

# continue from previous shell
(venv_gandlf) $> pytest --device cuda # can be cuda or cpu, defaults to cpu

Any failures will be reported in the file ${GaNDLF_HOME}/testing/failures.log.

Integration tests

All integration tests are combined to one shell script:

# it's assumed you are in `GaNDLF/` repo root directory
cd testing/

Code coverage

The code coverage for the unit tests can be obtained by the following command:

# continue from previous shell
(venv_gandlf) $> coverage run -m pytest --device cuda; coverage report -m