Skip to content

lmlib.statespace.backend

Selection tool to switch between Python interpreter (default) and JIT (Just-in-Time) compilation execution for time-critical routines in the statespace package.

Functions:

  • set_backend –

    Selects one out of multiple available backends (to optimize execution performance).

  • set_gpu_dtype –

    Set the on-device compute precision of the cupy GPU backend.

  • get_gpu_dtype –

    Return the active cupy-backend device compute dtype (numpy scalar type).

  • is_backend_available –

    Checks if the backend backend is available on this system.

  • get_backend –

    Returns the name of the currently selected backend.

Attributes:

  • BACKEND_TYPES –

    tuple of str : All backend names known to lmlib ('jit', 'numpy', 'lfilter', 'cupy'), whether or not they are installed on this system.

  • available_backends –

    tuple of str : Backend names actually available on this system. 'jit' is appended at import time when the optional numba package is installed; 'cupy' is appended when the optional cupy package is installed and a CUDA device is visible.

Attributes

BACKEND_TYPES module-attribute 

BACKEND_TYPES = ('jit', 'numpy', 'lfilter', 'cupy')

tuple of str : All backend names known to lmlib ('jit', 'numpy', 'lfilter', 'cupy'), whether or not they are installed on this system.

available_backends module-attribute 

available_backends = ('numpy', 'lfilter')

tuple of str : Backend names actually available on this system. 'jit' is appended at import time when the optional numba package is installed; 'cupy' is appended when the optional cupy package is installed and a CUDA device is visible.

Functions

set_backend 

set_backend(backend)

Selects one out of multiple available backends (to optimize execution performance).

Parameters:

  • backend (str(jit, py, python, numpy, lfilter)) –
    • "numpy" : for State Space Backend in Python (default)
    • "lfilter" : for Transfer Function Backend in Python
    • "jit": Just-in-Time compilation (if available)
    • "cupy": GPU Transfer Function Backend using CuPy / cupyx (if available)
    • "python" or "py" : Deprecated. (same as numpy)
  • If –
  • Use –
Source code in lmlib/statespace/backend.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def set_backend(backend):
    r"""
    Selects one out of multiple available backends (to optimize execution performance).

    Parameters
    ----------
    backend : str ("jit", "py", "python", "numpy", "lfilter")

          - "numpy" : for State Space Backend in Python (default)
          - "lfilter" : for Transfer Function Backend in Python
          - "jit": Just-in-Time compilation (if available)
          - "cupy": GPU Transfer Function Backend using CuPy / cupyx (if available)
          - "python" or "py" : Deprecated. (same as numpy)


    If the selected backend is not available, an assert is risen. 
    Use [`is_backend_available`][lmlib.statespace.backend.is_backend_available] to check availability first. 
    """
    backend = backend.lower()
    global _backend
    assert backend in BACKEND_TYPES, "Unknown backend name."
    if backend == 'jit':
        assert backend in available_backends, "jit backend not available. Check that numba package is installed!"
        _backend = 'jit'
    if backend == 'cupy':
        assert backend in available_backends, "cupy backend not available. Check that the cupy package is installed and a CUDA device is visible!"
        _backend = 'cupy'
    if backend in ('py', 'python'):
        DeprecationWarning("backend name 'py' and 'python' is deprecated and will be removed. Use 'numpy' instead.")
        _backend = 'numpy'
    if backend == 'numpy':
        _backend = 'numpy'
    if backend == 'lfilter':
        _backend = 'lfilter'

set_gpu_dtype 

set_gpu_dtype(dtype)

Set the on-device compute precision of the cupy GPU backend.

Parameters:

  • dtype ((float32, float64), default: 'float32' ) –

    'float64' (default) gives ~1e-13 parity with the lfilter backend. 'float32' is much faster on GPUs with reduced FP64 throughput (most consumer / laptop cards) at ~1e-6 relative accuracy (the error grows with ALSSM order).

Notes

Host buffers (xi / kappa / W) stay float64; only device math changes. The steady-state W is computed on the host and is unaffected. Requires the cupy backend to be available.

Source code in lmlib/statespace/backend.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def set_gpu_dtype(dtype):
    r"""
    Set the on-device compute precision of the ``cupy`` GPU backend.

    Parameters
    ----------
    dtype : {'float32', 'float64'} or numpy dtype
        ``'float64'`` (default) gives ~1e-13 parity with the ``lfilter`` backend.
        ``'float32'`` is much faster on GPUs with reduced FP64 throughput
        (most consumer / laptop cards) at ~1e-6 relative accuracy (the error
        grows with ALSSM order).

    Notes
    -----
    Host buffers (``xi`` / ``kappa`` / ``W``) stay float64; only device math
    changes. The steady-state ``W`` is computed on the host and is unaffected.
    Requires the ``cupy`` backend to be available.
    """
    assert 'cupy' in available_backends, \
        "cupy backend not available; cannot set GPU precision."
    from lmlib.statespace.backends.rec_cupy import set_gpu_dtype as _set
    return _set(dtype)

get_gpu_dtype 

get_gpu_dtype()

Return the active cupy-backend device compute dtype (numpy scalar type).

Source code in lmlib/statespace/backend.py 
77
78
79
80
81
def get_gpu_dtype():
    r"""Return the active ``cupy``-backend device compute dtype (numpy scalar type)."""
    assert 'cupy' in available_backends, "cupy backend not available."
    from lmlib.statespace.backends.rec_cupy import get_gpu_dtype as _get
    return _get()

is_backend_available 

is_backend_available(backend)

Checks if the backend backend is available on this system.

Parameters:

  • backend (str) – 
      or a list of valid backends, see [`set_backend`][lmlib.statespace.backend.set_backend]

Returns:

  • output ( bool ) –

    True or False

Source code in lmlib/statespace/backend.py 
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def is_backend_available(backend):
    r"""
    Checks if the backend `backend` is available on this system. 

    Parameters
    ----------
    backend : str 
              or a list of valid backends, see [`set_backend`][lmlib.statespace.backend.set_backend]

    Returns
    ----------
    output : bool
             `True` or `False`
    """

    return backend in available_backends

get_backend 

get_backend(cost_term)

Returns the name of the currently selected backend.

Returns:

Source code in lmlib/statespace/backend.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
def get_backend(cost_term):
    r"""
    Returns the name of the currently selected backend.


    Returns
    ----------
    output : str
             for a list of valid backends, see [`set_backend`][lmlib.statespace.backend.set_backend]
    """

    global _backend
    return _backend