Installation

Installation#

DiffeRT consists of two Python modules, differt and differt_core, where the latter is a direct dependency of the former, and both share the exact same version.

The main package, differt, uses Python-only code. The core package, differt_core, even though only containing a very limited set of utilities, is written in Rust to offer good performances, especially when reading large files or generating path candidates (see Generating path candidates).

Pre-built binaries are available for most platforms, and we recommend that users install DiffeRT from PyPI.

Pip Install#

The recommended installation procedure is with pip:

pip install differt

Important

If you encounter an error with installing from PyPI, e.g., because it is missing pre-built binaries for your platform, please report it as an issue in GitHub!

About JAX#

If you want to leverage the power of your GPU(s) or TPU(s), you may want to look at JAX’s installation guide, which provides the necessary information about how to install JAX with support for your target device.

DiffeRT works seamlessly with JAX regardless of the active devices (i.e., CPU, GPU, or TPU).

Optional dependencies#

By default, DiffeRT installs only a limited set of dependencies and does not include any plotting backend.

You may want to install those optional features by using extras[1]:

  • Plotting backends:

    • matplotlib: provide Matplotlib plotting backend;

    • plotly: provide Plotly plotting backend;

    • vispy: provide VisPy plotting backend;

  • VisPy-specific:

  • Jupyter support:

    • jupyter: provide support for Matplotlib and VisPy interactive plots inside notebooks;

  • Aliases:

    • all: alias to jupyter,matplotlib,plotly,vispy,vispy-backend;

Install from source#

If you consider contributing to DiffeRT (thanks!), or you want to work on your own local version, you will probably need to build the project from source.

This project is built using both Python and Rust code, to provide an easy-to-use but performant program. It also heavily uses the capabilities brought by JAX for numerical arrays.

Requirements#

To build this package locally, you need:

  • Rust* stable toolchain;

  • any modern C compiler*;

  • just>=1.38.0 to easily run commands listed in justfiles;

  • and uv>= 0.4.25 to manage this project.

This project contains justfiles with recipes[2] for most common use cases, so feel free to use them instead of the commands listed below.

Note

Requirements with an asterisk (*) are only needed if you want to build differt_core from source. If you don’t plan on making changes to the Rust code, see building without Rust.

Building#

Building (and installing) the packages is pretty simple thanks to uv:

uv sync

This will automatically download an appropriate Python version (if not available) and install the packages in a virtual environment.

Note

By default, uv sync will also install all the packages listed in the dev list of the [dependency-groups] section from the main pyproject.toml file.

You can opt out by specifying the --no-dev option.

Alternatively, you can install specific groups[3] with uv sync --group <GROUP>.

Building without Rust#

Rust (and the C compiler) are only needed if you want to build the differt_core package. However, as most features are written in the differt package, you might be interested to skip building the core package and, instead, download pre-built binaries from PyPI.

To do so, you need to edit two files: pyproject.toml and differt/pyproject.toml.

Listing 1 Adding one line to pyproject.toml#
[tool.uv.workspace]
members = ["differt", "differt-core"]
exclude = ["differt-core"]  # Add this line
Listing 2 Removing one line from differt/pyproject.toml#
[tool.uv.sources]
differt_core = {workspace = true}  # Remove (or comment) this line

After that, uv will know that it must download differt_core from PyPI and not look at the differt-core folder.

Contents