Migrating from ODL 0.x to ODL 1.x

If you have a project built around ODL versions 0.6, 0.7, 0.8, or built the development version from the master branch until 2025 (“1.0-dev”), then you may need to make some changes to use your code together with the official 1.0 release. This guide explains how.

NumPy ufuncs

The most significant change in 1.0 is in the way pointwise / elementwise functions are applied to ODL objects (e.g. DiscretizedSpaceElement). ODL 0.x ultimately stored all data of such an object inside one or multiple NumPy arrays, and was thus able to hook into NumPy’s “ufunc” mechanism to allow code like:

>>> import odl # up to version 0.8.3
>>> import numpy as np
>>> space = odl.uniform_discr(0, np.pi, 7, nodes_on_bdry=True)
>>> xs = space.element(lambda x: x)
>>> np.cos(xs)
uniform_discr(0.0, 3.1415927, 7, nodes_on_bdry=True).element(
    [ 1.       ,  0.8660254,  0.5      , ..., -0.5      , -0.8660254,
     -1.       ]
)

If you run the same code with ODL 1.0, you will get an error message. The reason is that ODL can now use other backends like PyTorch for storing the data, on which NumPy ufuncs do not work. To offer a consistent way of performing pointwise operations on such objects regardless of the backend, ODL now offers versions of these functions in its own namespace:

>>> # import odl from version 1.0
>>> odl.cos(xs)
uniform_discr(0.0, 3.1415927, 7, nodes_on_bdry=True).element(
    [ 1.       ,  0.8660254,  0.5      , ..., -0.5      , -0.8660254,
     -1.       ]
)

Operator composition

Operators are a central feature of ODL. Typically, multiple primitive operators are composed to a whole pipeline. ODL 0.x used Python’s * for this purpose, which is intuitive from a mathematical perspective particular for linear operators as composition corresponds to matrix multiplication then.

Unfortunately it conflicted with another use of *, which most array libraries employ, namely pointwise multiplication (for matrices, this is the Hadamard product). To avoid mistakes from the different interpretations, from ODL 1.0 on the @ symbol should instead be used for composing operators (this is also used by NumPy and PyTorch for matrix multiplication). This also applies to the various ways ODL overloads “composition”; for example, to pre-compose an $L^2$ norm with a pointwise scaling, you could write:

>>> op = odl.functional.L2Norm(space) @ (1 + odl.sin(xs))
>>> op
FunctionalRightVectorMult(L2Norm(uniform_discr(0.0, 3.1415927, 7, nodes_on_bdry=True)), uniform_discr(0.0, 3.1415927, 7, nodes_on_bdry=True).element(
    [ 1.       ,  1.5      ,  1.8660254, ...,  1.8660254,  1.5      ,
      1.       ]
))
>>> op(space.one())
2.9360830109198384

In some cases, the old * syntax is still interpreted as composition when that is unambiguous, but this is deprecated and should be replaced with @. Only use * for multiplying odl objects pointwise, for example:

>>> odl.sqrt(xs) * odl.sqrt(xs) - xs
uniform_discr(0.0, 3.1415927, 7, nodes_on_bdry=True).element(
    [ 0.,  0.,  0., ...,  0.,  0., -0.]
)