🛠️ Toolchain Roadmap#

The DIPY library relies on a set of primary dependencies, most notably Python, NumPy and Nibabel to function effectively. Additionally, a broader array of libraries and tools is necessary for both building the library and constructing its documentation.

It’s important to note that these tools and libraries are continuously evolving. This document aims to outline how DIPY will manage its usage of these dynamic dependencies over time.

DIPY strives to maintain compatibility across multiple releases of its dependent libraries and tools. Requiring users to switch to other components with every release would significantly reduce the value of DIPY. Nevertheless, retaining compatibility with older toolsets and libraries sets boundaries on incorporating newer functionalities and capabilities.

DIPY adopts a moderately conservative approach by ensuring compatibility with several major releases of Python and NumPy across major platforms. However, this stance may introduce further constraints, as illustrated in the C Compilers section.

  • First and foremost, DIPY is a Python project, hence it requires a Python environment.

  • Compilers for C code is needed, as well as for Cython.

  • The Python environment needs NumPy and Nibabel package to be installed.

  • Testing requires the pytest Python packages.

  • Building the documentation requires Sphinx packages along with sphinx_design, sphinxcontrib-bibtex, sphinx-gallery, PyData/GRG theme.

Building DIPY#

Python Versions#

DIPY is compatible with several versions of Python. When dropping support for older Python versions, DIPY takes guidance from :ref:`Scientific-Python SPECS<https://scientific-python.org/specs>`_. Python 2.7 support was dropped starting from DIPY 1.0.0

Date

Pythons supported

2018

Py2.7, Py3.4+ (DIPY 0.16.x is the last release to support Python 2.7)

2019

Py3.5+

mid-2020

Py3.6+

2022

Py3.7+

mid-2023

Py3.8+

2024

Py3.9+

NumPy#

While DIPY relies on NumPy, its releases are not bound to specific NumPy releases. Instead, DIPY strives for compatibility with at least the four preceding releases of NumPy. This approach necessitates writing DIPY using features common to all these versions, rather than relying solely on the latest NumPy features [1].

The table provided illustrates the compatible NumPy versions for each major Python release.

DIPY version

Python versions

NumPy versions

0.16.0

2.7, >=3.4, <=3.7

>=1.8.2, <= 1.16.x

1.0.0

>=3.5, <=3.7

>=1.13.3, <= 1.16.x

1.1.0/1

>=3.5, <=3.8

>=1.13.3, <= 1.17.3

1.2.0

>=3.6, <=3.8

>=1.14.5, <= 1.17.3

1.3.0

>=3.6, <=3.8

>=1.14.5, <1.17.3

1.4.0/1

>=3.6, <=3.9

>=1.14.5, <1.20.x

1.5.0

>=3.7, <=3.10

>=1.16.x, <1.23.0

1.6.0

>=3.7, <=3.11

>=1.16.x, <1.24.0

1.7.0

>=3.8, <=3.11

>=1.19.5, <1.24.0

1.8.0

>=3.8, <=3.12

>=1.19.5, <1.26.0

1.9.0

>=3.9, <3.12

>=1.21.6, <1.27.0

Note

The table above is not exhaustive. In specific cases, such as a particular architecture, these requirements could vary.

Compilers#

Building DIPY requires compilers for C as well as the python transpilers Cython.

To maintain compatibility with a large number of platforms & setups, especially where using the official wheels (or other distribution channels like Anaconda or conda-forge) is not possible, DIPY tries to keep compatibility with older compilers, on platforms that have not yet reached their official end-of-life.

As explained in more detail below, the current minimal compiler versions are:

Compiler

Default Platform (tested)

Secondary Platform (untested)

Minimal Version

GCC

Linux

AIX, Alpine Linux, OSX

GCC 8.x

LLVM

OSX

Linux, FreeBSD, Windows

LLVM 10.x

MSVC

Windows

Visual Studio 2019 (vc142)

Note that the lower bound for LLVM is not enforced. Older versions should work, but no version below LLVM 12 is tested regularly during development. Please file an issue if you encounter a problem during compilation.

Official Builds#

Currently, DIPY wheels are being built as follows:

Platform

CI Base Images [2] [3] [4]

Compilers

Comment

Linux x86

ubuntu-22.04

GCC 10.2.1

cibuildwheel

Linux arm

docker-builder-arm64

GCC 11.3.0

cibuildwheel

OSX x86

macOS-11

clang-13

cibuildwheel

OSX arm

macos-monterey-xcode:14

clang-13.1.6

cibuildwheel

Windows

windows-2019

Microsoft Visual 2019 (14.20)

cibuildwheel

Testing and Benchmarking#

Testing and benchmarking require recent versions of:

Tool

Version

URL

pytest

Recent

https://docs.pytest.org/en/latest/

asv (airspeed velocity)

Recent

https://asv.readthedocs.io/

Building the Documentation#

Tool

Version

Sphinx

Whatever recent versions work. >= 6.0.

GRG Sphinx theme

Whatever recent versions work. >= 0.3.1.

Sphinx-Design

Whatever recent versions work. >= 0.5.0.

numpydoc

Whatever recent versions work. >= 1.6.0.

Sphinx-Gallery

Whatever recent versions work. >= 0.15.0.

Sphinxcontrib-bibtex

Whatever recent versions work. >= 2.6.1

Note

Developer Note: The documentation build might require additional libraries based on the examples provided. Specifically, the versions of “numpy” and “nibabel” needed have implications for the Python docstring examples.

It’s essential for these examples to execute seamlessly in both the documentation build environment and any supported versions of “numpy/nibabel” that users might utilize with this DIPY release.

Packaging#

A Recent version of:

Tool

Version

URL

meson-python

Recent

https://meson-python.readthedocs.io/en/latest/

wheel

Recent

https://pythonwheels.com

cibuildwheel

Recent

https://cibuildwheel.readthedocs.io/en/stable/

A guide to making a DIPY release contain information on making and distributing a DIPY release.

References#