Setup for development

Clone the repository

Clone the public repository:

git clone git@gitlab.com:scimba/scimba.git
cd scimba

Clone the private repository:

git clone git@gitlab.inria.fr:sciml/scimba.git
cd scimba
git checkout develop  # switch to the develop branch

Then create your own branch.

Create a virtual environment and install the package in editable mode

uv venv  # create a virtual environment
source .venv/bin/activate  # activate the virtual environment
uv sync  # default group: dev-cpu, all development tools, JAX CPU only

The development dependency groups are (see [dependency-groups] in pyproject.toml; default-groups is set to dev-cpu there, so a plain uv sync installs the CPU-only environment):

  • dev-cpu (default): all development tools, JAX CPU only — lighter install, no CUDA wheels;

  • dev: alias of dev-cuda12 — the same tools, JAX CUDA 12 on Linux x86_64 (JAX CPU on other platforms);

  • dev-cuda13: the same tools, JAX CUDA 13;

  • dev-cuda12-volta: the same tools, JAX CUDA 12 with torch capped below 2.11 (for Volta GPUs, e.g. V100 — see the note below).

# NB: `--group` is additive: the default group (`dev-cpu`) is always
# included, which is what makes these one-line variants work.
uv sync --group dev               # JAX CUDA 12 (alias of dev-cuda12)
uv sync --group dev-cuda12-volta  # JAX CUDA 12, Volta (V100)
uv sync --group dev-cuda13        # JAX CUDA 13

Warning

CUDA 13 requires a GPU with SM >= 7.5 (Turing or newer): Maxwell, Pascal and Volta architectures are no longer supported by CUDA 13. On a Volta GPU such as a V100 (SM 7.0), use a CUDA 12 environment (dev or dev-cuda12-volta).

On a Volta GPU, the cuda12-volta dependency group (see pyproject.toml; included by ci and by dev-cuda12-volta) caps torch below 2.11: the PyPI wheels of torch >= 2.11 depend on CUDA 13 packages, which land in the environment and break the CUDA 12 build on SM 7.0. Because uv.lock resolves every group, this cap applies to all the repository’s environments — the lockfile cannot move torch past 2.11 as long as the group exists.

python3 -m venv .venv  # create a virtual environment
source .venv/bin/activate  # activate the virtual environment
# upgrade pip to the latest version (at least 25.1) to install dependency
# groups (PEP 735, the [dependency-groups] table of pyproject.toml)
pip install --upgrade pip
# install the package in editable mode with the full development group
# (JAX CUDA 12 on Linux x86_64, JAX CPU on other platforms)
pip install -e . --group dev

For a JAX CPU-only or a JAX CUDA 13 environment, run instead:

pip install -e . --group dev-cpu
pip install -e . --group dev-cuda13

Install pre-commit hooks

Pre-commit hooks are used to ensure code quality before committing changes. The sequence of hooks is triggered automatically on git commit. Its configuration is in the .pre-commit-config.yaml file.

Warning

pre-commit may seem restrictive at first, but it is very useful for maintaining code quality and uniformity. If you don’t use it, you risk committing style errors or formatting issues that will cause failures in automated tests. Note that many style issues can be automatically fixed by ruff --fix triggered by pre-commit.

To install the pre-commit hooks, run:

pre-commit install

Except for the test suite and documentation builds, only files that have been indexed (using git add) will be checked by the hooks. To test it manually before committing, you can run:

pre-commit run

To test them on all files, you can run:

pre-commit run --all-files

To test only specific hooks, you can use, for example, for ruff:

pre-commit run ruff --all-files

To skip the pre-commit hooks for a specific commit, let’s say pytest, you can use:

SKIP=pytest git commit -m "Your commit message"

Tip

To execute the test suite pytest in parallel using all available CPU cores (see Run the test suite in parallel), you can use:

export PYTEST_ADDOPTS="$PYTEST_ADDOPTS -n auto"

To make this setting permanent in your VSCode terminal, you can add it to a file named .env in the project root of the repository (make sure to add this file to your .gitignore to avoid committing it).

PYTEST_ADDOPTS="-n auto"