specular.backends.use_backend

Copy

use_backend(name)

Temporarily select a backend, restoring the previous selection when the scope ends, including when an exception is raised.

Parameters

Name	Type	Description
name	str	One of "numpy", "numba", or "jax". Names are case-sensitive.

Returns

Context manager and function decorator — Entering the context selects the requested backend. In with use_backend(name) as selected:, selected is the validated BackendName. Exiting restores the previous backend.

Notes

Validation and backend loading occur when entering the context or calling a decorated function, rather than when constructing the context manager. Invalid names and missing dependencies raise the same errors as set_backend. Optional backends must be installed first.

An object returned by use_backend can be reused after its context exits, but re-entering the same object while it is active raises RuntimeError. Nested overrides are supported by creating a separate context manager for each scope.

The decorator supports ordinary synchronous and asynchronous functions. Decorating a generator or async-generator function raises TypeError. In a generator, put a with block inside the body and leave it before yielding; otherwise the caller also observes the temporary backend while the generator is suspended.

This function is also available as specular.use_backend.

Examples

Copy

import specular

previous = specular.get_backend()
with specular.use_backend("numpy") as selected:
    print(selected)  # numpy
    value = specular.derivative(lambda x: x * x, 2.0)
assert specular.get_backend() == previous

The decorator applies the temporary selection to each invocation:

Copy

@specular.use_backend("numpy")
def square_derivative(x):
    return specular.derivative(lambda t: t * t, x)

print(square_derivative(2.0))

See the backend user guide for optional backend examples and callback requirements.

Source code in specular/backends/_registry.py

Copy

def use_backend(name: str) -> _BackendContext:
    """Temporarily select a backend, restoring the previous choice afterward.

    The returned object is both a context manager and a function decorator.
    It can be reused after its context exits, but cannot be re-entered while
    active. Generator and async-generator functions cannot be decorated.
    """

    return _BackendContext(name)