Skip to content

Sparse

btorch.sparse

Sparse arrays for PyTorch with SciPy-like ergonomics.

btorch.sparse is a numerical sparse-array API that is independent of neuroscience connectivity:

import torch from btorch import sparse A = sparse.from_edges(torch.tensor([0, 1]), torch.tensor([2, 0]), ... torch.tensor([3.0, 5.0]), shape=(2, 3)) A @ torch.tensor([1.0, 0.0, 2.0]) tensor([6., 5.]) A.tocsr().indptr tensor([0, 1, 2])

Matrix products follow standard linear algebra (A.shape == (M, N) maps length-N vectors to length-M vectors) and conversions from PyTorch or SciPy never transpose. Connection semantics (source/destination orientation, synapses, receptors, delays) live in :mod:btorch.models.connection.

Attributes

__all__ = ['COO', 'CSC', 'CSR', 'CompositeOperator', 'ConstantOperator', 'DiagonalOperator', 'EdgeMap', 'Hints', 'ImplicitOperator', 'LinearOperator', 'LowRankOperator', 'ProductOperator', 'Properties', 'ScaledOperator', 'Sparse', 'StructuredOperator', 'SumOperator', 'TransposedOperator', 'as_sparse', 'asarray', 'coo', 'csc', 'csr', 'einsum', 'explain', 'from_dense', 'from_edges', 'from_scipy', 'from_torch', 'is_linear_operator', 'matmul', 'matvec', 'rmatvec', 'stack'] module-attribute

asarray = as_sparse module-attribute

Classes

COO

Bases: Sparse

Coordinate format: one index tuple and one value per stored entry.

COO supports any number of sparse dimensions. Entries may be unsorted and may contain duplicates; duplicates are summed by every operation, as in SciPy and PyTorch.

Two kinds of batch are supported and may be combined:

  • Shared pattern: values has leading batch dimensions, [*batch, nnz, *dense], and every batch member uses the same indices.
  • Different patterns: the first index rows are batch coordinates, so each batch member can have its own number of entries. Build these with :func:btorch.sparse.stack.

Parameters:

Name Type Description Default
indices Tensor

[n_index, nnz] integer coordinates. The rows are the batch coordinates (if any) followed by the sparse coordinates.

required
values Tensor

[*value_batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, *sparse, *dense).

required
batch_dim int | None

Total number of batch dimensions. Defaults to the number of leading value dimensions (a shared pattern).

None
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties of the given indices.

None
hints Hints | None

Performance expectations.

None
check bool

Validate index bounds.

True

Examples:

>>> import torch
>>> from btorch import sparse
>>> A = sparse.coo(torch.tensor([[0, 1], [2, 0]]),
...                torch.tensor([3.0, 5.0]), shape=(2, 3))
>>> A @ torch.tensor([1.0, 0.0, 2.0])
tensor([6., 5.])
Source code in btorch/sparse/coo.py
class COO(Sparse):
    """Coordinate format: one index tuple and one value per stored entry.

    COO supports any number of sparse dimensions. Entries may be unsorted and
    may contain duplicates; duplicates are summed by every operation, as in
    SciPy and PyTorch.

    Two kinds of batch are supported and may be combined:

    - *Shared pattern*: ``values`` has leading batch dimensions,
      ``[*batch, nnz, *dense]``, and every batch member uses the same indices.
    - *Different patterns*: the first index rows are batch coordinates, so each
      batch member can have its own number of entries. Build these with
      :func:`btorch.sparse.stack`.

    Args:
        indices: ``[n_index, nnz]`` integer coordinates. The rows are the
            batch coordinates (if any) followed by the sparse coordinates.
        values: ``[*value_batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, *sparse, *dense)``.
        batch_dim: Total number of batch dimensions. Defaults to the number
            of leading value dimensions (a shared pattern).
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties of the given indices.
        hints: Performance expectations.
        check: Validate index bounds.

    Examples:
        >>> import torch
        >>> from btorch import sparse
        >>> A = sparse.coo(torch.tensor([[0, 1], [2, 0]]),
        ...                torch.tensor([3.0, 5.0]), shape=(2, 3))
        >>> A @ torch.tensor([1.0, 0.0, 2.0])
        tensor([6., 5.])
    """

    format = "coo"

    def __init__(
        self,
        indices: Tensor,
        values: Tensor,
        shape: tuple[int, ...],
        *,
        batch_dim: int | None = None,
        dense_dim: int = 0,
        properties: Properties | None = None,
        hints: Hints | None = None,
        check: bool = True,
    ):
        values = _as_tensor(values)
        indices = _check_index("indices", _as_tensor(indices, device=values.device))
        shape = tuple(int(s) for s in shape)
        if indices.ndim != 2:
            raise ValueError(f"indices must be [n_index, nnz], got {indices.shape}.")
        n_index, nnz = indices.shape
        value_batch_dim = values.ndim - 1 - dense_dim
        if value_batch_dim < 0:
            raise ValueError(
                f"values with shape {tuple(values.shape)} cannot hold "
                f"{dense_dim} dense dimension(s) per entry."
            )
        if batch_dim is None:
            batch_dim = value_batch_dim
        index_batch_dim = batch_dim - value_batch_dim
        if index_batch_dim < 0:
            raise ValueError("batch_dim is smaller than the batch of `values`.")
        if len(shape) != value_batch_dim + n_index + dense_dim:
            raise ValueError(
                f"shape {shape} has {len(shape)} dimensions but indices/values "
                f"describe {value_batch_dim} value-batch + {n_index} indexed + "
                f"{dense_dim} dense."
            )
        if n_index - index_batch_dim < 1:
            raise ValueError("COO needs at least one sparse dimension.")
        if values.shape[value_batch_dim] != nnz:
            raise ValueError(
                f"values has {values.shape[value_batch_dim]} entries along its "
                f"entry axis but indices has {nnz}."
            )
        expected = (
            shape[:value_batch_dim] + (nnz,) + shape[len(shape) - dense_dim :]
            if dense_dim
            else shape[:value_batch_dim] + (nnz,)
        )
        if tuple(values.shape) != expected:
            raise ValueError(
                f"values has shape {tuple(values.shape)}, expected {expected}."
            )
        indexed = shape[value_batch_dim : value_batch_dim + n_index]
        if check and nnz > 0:
            lo = indices.amin(dim=1)
            hi = indices.amax(dim=1)
            for d, size in enumerate(indexed):
                if int(lo[d]) < 0 or int(hi[d]) >= size:
                    raise ValueError(
                        f"indices along indexed dimension {d} must be in "
                        f"[0, {size}), got range [{int(lo[d])}, {int(hi[d])}]."
                    )
        self._indices = indices
        self._values = values
        self._shape = shape
        self._batch_dim = batch_dim
        self._dense_dim = dense_dim
        self._value_batch_dim = value_batch_dim
        self.properties = properties or Properties()
        if self.properties.shared_pattern != bool(value_batch_dim):
            self.properties = self.properties.replace(
                shared_pattern=bool(value_batch_dim)
            )
        self.hints = hints or Hints()

    # ----------------------------------------------------------- accessors
    @property
    def nnz(self) -> int:
        return int(self._indices.shape[1])

    def indices(self) -> Tensor:
        """``[n_index, nnz]`` coordinates (PyTorch name)."""
        return self._indices

    def values(self) -> Tensor:
        """``[*value_batch, nnz, *dense]`` stored values (PyTorch name)."""
        return self._values

    @property
    def data(self) -> Tensor:
        """Stored values (SciPy name)."""
        return self._values

    @property
    def row(self) -> Tensor:
        """Row coordinate of each entry (two sparse dimensions only)."""
        self._require_matrix("row")
        return self._indices[-2]

    @property
    def col(self) -> Tensor:
        """Column coordinate of each entry (two sparse dimensions only)."""
        self._require_matrix("col")
        return self._indices[-1]

    def _require_matrix(self, what: str) -> None:
        if self.sparse_dim() != 2:
            raise ValueError(
                f"{what} needs exactly two sparse dimensions, this array has "
                f"{self.sparse_dim()}."
            )

    @property
    def _index_batch_dim(self) -> int:
        return self._batch_dim - self._value_batch_dim

    @property
    def _indexed_shape(self) -> tuple[int, ...]:
        """Sizes of the indexed (batch-coordinate + sparse) dimensions."""
        start = self._value_batch_dim
        return self._shape[start : start + self._indices.shape[0]]

    def _edge_index(self) -> tuple[Tensor | None, Tensor, Tensor]:
        """``(batch coordinates or None, row, col)`` for matrix products."""
        self._require_matrix("A matrix product")
        n_ib = self._index_batch_dim
        lead = self._indices[:n_ib] if n_ib else None
        return lead, self._indices[-2], self._indices[-1]

    # --------------------------------------------------------- construction
    def _like(self, indices: Tensor, values: Tensor, **changes) -> "COO":
        out = COO.__new__(COO)
        out.__dict__.update(self.__dict__)
        out._indices = indices
        out._values = values
        for key, value in changes.items():
            setattr(out, key, value)
        return out

    def with_values(self, values: Tensor) -> "COO":
        value_batch_dim = values.ndim - 1 - self._dense_dim
        tail = self._shape[self._value_batch_dim :]
        return COO(
            self._indices,
            values,
            tuple(values.shape[:value_batch_dim]) + tail,
            batch_dim=value_batch_dim + self._index_batch_dim,
            dense_dim=self._dense_dim,
            properties=self.properties,
            hints=self.hints,
            check=False,
        )

    def _map_tensors(self, index_fn, value_fn) -> "COO":
        return self._like(index_fn(self._indices), value_fn(self._values))

    # -------------------------------------------------------- canonical form
    def coalesce(self, return_map: bool = False) -> "COO" | tuple["COO", EdgeMap]:
        """Sort entries row-major and sum duplicates.

        Args:
            return_map: Also return the :class:`EdgeMap` from the old entries
                to the new ones, to move edge-aligned metadata consistently.

        Returns:
            The canonical COO, and the map if requested. The values of merged
            entries are summed, so gradients flow to every duplicate.
        """
        nnz = self.nnz
        if self.properties.canonical:
            edge_map = EdgeMap.identity(nnz, self._indices.device)
            return (self, edge_map) if return_map else self
        sizes = self._indexed_shape
        key = _ravel(self._indices, sizes)
        if self.properties.sorted:
            order = None
            sorted_key = key
        else:
            sorted_key, order = torch.sort(key, stable=True)
        unique_key, inverse = torch.unique_consecutive(sorted_key, return_inverse=True)
        if order is None:
            target = inverse
        else:
            target = torch.empty_like(inverse)
            target[order] = inverse
        edge_map = EdgeMap(target, int(unique_key.shape[0]))
        out = self._like(
            _unravel(unique_key, sizes),
            edge_map.sum(self._values, dim=self._value_batch_dim),
            properties=self.properties.replace(sorted=True, unique=True),
        )
        return (out, edge_map) if return_map else out

    def sum_duplicates(self) -> "COO":
        """SciPy-style alias of :meth:`coalesce` (returns a new array)."""
        return self.coalesce()

    # -------------------------------------------------------------- formats
    def tocoo(self) -> "COO":
        return self

    def _compressed(self, return_map: bool):
        """Canonical entries, their row pointers and the edge map."""
        self._require_matrix("CSR/CSC conversion")
        if self._index_batch_dim:
            raise NotImplementedError(
                "A batch of different sparsity patterns is stored as batched "
                "COO; compressed (CSR/CSC) storage for it is not implemented."
            )
        coo, edge_map = self.coalesce(return_map=True)
        n_rows = coo.sparse_shape[0]
        counts = torch.bincount(coo._indices[0], minlength=n_rows)
        pointer = torch.zeros(n_rows + 1, dtype=torch.long, device=counts.device)
        pointer[1:] = torch.cumsum(counts, 0)
        return coo, pointer, edge_map

    def tocsr(self, return_map: bool = False):
        """Convert to canonical CSR (sorted, duplicates summed).

        Args:
            return_map: Also return the :class:`EdgeMap` from the COO entries
                to the CSR entries.
        """
        from .csr import CSR

        coo, crow, edge_map = self._compressed(return_map)
        out = CSR(
            crow,
            coo._indices[1],
            coo._values,
            coo._shape,
            dense_dim=self._dense_dim,
            properties=coo.properties,
            hints=self.hints,
            check=False,
        )
        return (out, edge_map) if return_map else out

    def tocsc(self, return_map: bool = False):
        """Convert to canonical CSC (column-major, duplicates summed)."""
        result = self.transpose().tocsr(return_map)
        if return_map:
            return result[0].transpose(), result[1]
        return result.transpose()

    def transpose(self) -> "COO":
        self._require_matrix("transpose")
        idx = self._indices
        swapped = torch.cat([idx[:-2], idx[-1:], idx[-2:-1]])
        shape = list(self._shape)
        i = self._batch_dim
        shape[i], shape[i + 1] = shape[i + 1], shape[i]
        return self._like(
            swapped,
            self._values,
            _shape=tuple(shape),
            properties=self.properties.replace(sorted=False, triangular=None),
        )

    def to_dense(self) -> Tensor:
        n_vb = self._value_batch_dim
        sizes = self._indexed_shape
        dense = (
            self._shape[len(self._shape) - self._dense_dim :] if self._dense_dim else ()
        )
        key = _ravel(self._indices, sizes)
        flat = self._values.new_zeros(*self._shape[:n_vb], math.prod(sizes), *dense)
        flat = flat.index_add(n_vb, key, self._values)
        return flat.reshape(self._shape)
Attributes
col property

Column coordinate of each entry (two sparse dimensions only).

data property

Stored values (SciPy name).

row property

Row coordinate of each entry (two sparse dimensions only).

Methods:
coalesce(return_map=False)

Sort entries row-major and sum duplicates.

Parameters:

Name Type Description Default
return_map bool

Also return the :class:EdgeMap from the old entries to the new ones, to move edge-aligned metadata consistently.

False

Returns:

Type Description
'COO' | tuple['COO', EdgeMap]

The canonical COO, and the map if requested. The values of merged

'COO' | tuple['COO', EdgeMap]

entries are summed, so gradients flow to every duplicate.

Source code in btorch/sparse/coo.py
def coalesce(self, return_map: bool = False) -> "COO" | tuple["COO", EdgeMap]:
    """Sort entries row-major and sum duplicates.

    Args:
        return_map: Also return the :class:`EdgeMap` from the old entries
            to the new ones, to move edge-aligned metadata consistently.

    Returns:
        The canonical COO, and the map if requested. The values of merged
        entries are summed, so gradients flow to every duplicate.
    """
    nnz = self.nnz
    if self.properties.canonical:
        edge_map = EdgeMap.identity(nnz, self._indices.device)
        return (self, edge_map) if return_map else self
    sizes = self._indexed_shape
    key = _ravel(self._indices, sizes)
    if self.properties.sorted:
        order = None
        sorted_key = key
    else:
        sorted_key, order = torch.sort(key, stable=True)
    unique_key, inverse = torch.unique_consecutive(sorted_key, return_inverse=True)
    if order is None:
        target = inverse
    else:
        target = torch.empty_like(inverse)
        target[order] = inverse
    edge_map = EdgeMap(target, int(unique_key.shape[0]))
    out = self._like(
        _unravel(unique_key, sizes),
        edge_map.sum(self._values, dim=self._value_batch_dim),
        properties=self.properties.replace(sorted=True, unique=True),
    )
    return (out, edge_map) if return_map else out
indices()

[n_index, nnz] coordinates (PyTorch name).

Source code in btorch/sparse/coo.py
def indices(self) -> Tensor:
    """``[n_index, nnz]`` coordinates (PyTorch name)."""
    return self._indices
sum_duplicates()

SciPy-style alias of :meth:coalesce (returns a new array).

Source code in btorch/sparse/coo.py
def sum_duplicates(self) -> "COO":
    """SciPy-style alias of :meth:`coalesce` (returns a new array)."""
    return self.coalesce()
tocsc(return_map=False)

Convert to canonical CSC (column-major, duplicates summed).

Source code in btorch/sparse/coo.py
def tocsc(self, return_map: bool = False):
    """Convert to canonical CSC (column-major, duplicates summed)."""
    result = self.transpose().tocsr(return_map)
    if return_map:
        return result[0].transpose(), result[1]
    return result.transpose()
tocsr(return_map=False)

Convert to canonical CSR (sorted, duplicates summed).

Parameters:

Name Type Description Default
return_map bool

Also return the :class:EdgeMap from the COO entries to the CSR entries.

False
Source code in btorch/sparse/coo.py
def tocsr(self, return_map: bool = False):
    """Convert to canonical CSR (sorted, duplicates summed).

    Args:
        return_map: Also return the :class:`EdgeMap` from the COO entries
            to the CSR entries.
    """
    from .csr import CSR

    coo, crow, edge_map = self._compressed(return_map)
    out = CSR(
        crow,
        coo._indices[1],
        coo._values,
        coo._shape,
        dense_dim=self._dense_dim,
        properties=coo.properties,
        hints=self.hints,
        check=False,
    )
    return (out, edge_map) if return_map else out
values()

[*value_batch, nnz, *dense] stored values (PyTorch name).

Source code in btorch/sparse/coo.py
def values(self) -> Tensor:
    """``[*value_batch, nnz, *dense]`` stored values (PyTorch name)."""
    return self._values

CSC

Bases: _Compressed

Compressed sparse column format (exactly two sparse dimensions).

Parameters:

Name Type Description Default
pointer Tensor

[n_cols + 1] column pointers (ccol_indices).

required
minor Tensor

[nnz] row of each entry (row_indices).

required
values Tensor

[*batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, n_rows, n_cols, *dense).

required
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties (sorted refers to column-major order).

None
hints Hints | None

Performance expectations.

None
check bool

Validate the pointer and index ranges.

True
Source code in btorch/sparse/csr.py
class CSC(_Compressed):
    """Compressed sparse column format (exactly two sparse dimensions).

    Args:
        pointer: ``[n_cols + 1]`` column pointers (``ccol_indices``).
        minor: ``[nnz]`` row of each entry (``row_indices``).
        values: ``[*batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, n_rows, n_cols, *dense)``.
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties (``sorted`` refers to
            column-major order).
        hints: Performance expectations.
        check: Validate the pointer and index ranges.
    """

    format = "csc"
    _major_axis = 1

    def ccol_indices(self) -> Tensor:
        """``[n_cols + 1]`` column pointers (PyTorch name)."""
        return self._pointer

    def row_indices(self) -> Tensor:
        """``[nnz]`` row of each entry (PyTorch name)."""
        return self._minor

    def col_indices(self) -> Tensor:
        """``[nnz]`` column of each entry, expanded from the pointers."""
        return self._major_indices()

    def tocsr(self, return_map: bool = False):
        return self.tocoo().tocsr(return_map)

    def tocsc(self, return_map: bool = False):
        """Return ``self`` (already CSC; entries are left as stored).

        Use :meth:`coalesce` to sort rows and merge duplicates.
        """
        if return_map:
            return self, EdgeMap.identity(self.nnz, self._minor.device)
        return self

    def coalesce(self, return_map: bool = False):
        """Canonical CSC: sorted rows, duplicates summed."""
        return self.tocoo().tocsc(return_map)

    def transpose(self) -> CSR:
        """Transpose without copying: the same arrays read as CSR."""
        return self._like(
            CSR,
            _shape=self._swapped_shape(),
            properties=self.properties.replace(triangular=None),
        )
Methods:
ccol_indices()

[n_cols + 1] column pointers (PyTorch name).

Source code in btorch/sparse/csr.py
def ccol_indices(self) -> Tensor:
    """``[n_cols + 1]`` column pointers (PyTorch name)."""
    return self._pointer
coalesce(return_map=False)

Canonical CSC: sorted rows, duplicates summed.

Source code in btorch/sparse/csr.py
def coalesce(self, return_map: bool = False):
    """Canonical CSC: sorted rows, duplicates summed."""
    return self.tocoo().tocsc(return_map)
col_indices()

[nnz] column of each entry, expanded from the pointers.

Source code in btorch/sparse/csr.py
def col_indices(self) -> Tensor:
    """``[nnz]`` column of each entry, expanded from the pointers."""
    return self._major_indices()
row_indices()

[nnz] row of each entry (PyTorch name).

Source code in btorch/sparse/csr.py
def row_indices(self) -> Tensor:
    """``[nnz]`` row of each entry (PyTorch name)."""
    return self._minor
tocsc(return_map=False)

Return self (already CSC; entries are left as stored).

Use :meth:coalesce to sort rows and merge duplicates.

Source code in btorch/sparse/csr.py
def tocsc(self, return_map: bool = False):
    """Return ``self`` (already CSC; entries are left as stored).

    Use :meth:`coalesce` to sort rows and merge duplicates.
    """
    if return_map:
        return self, EdgeMap.identity(self.nnz, self._minor.device)
    return self
transpose()

Transpose without copying: the same arrays read as CSR.

Source code in btorch/sparse/csr.py
def transpose(self) -> CSR:
    """Transpose without copying: the same arrays read as CSR."""
    return self._like(
        CSR,
        _shape=self._swapped_shape(),
        properties=self.properties.replace(triangular=None),
    )

CSR

Bases: _Compressed

Compressed sparse row format (exactly two sparse dimensions).

Batch members share one sparsity pattern: crow_indices and col_indices are stored once and values is [*batch, nnz, *dense]. This is the natural layout for ensembles and parameter sweeps over a fixed topology.

Parameters:

Name Type Description Default
pointer Tensor

[n_rows + 1] row pointers (crow_indices).

required
minor Tensor

[nnz] column of each entry (col_indices).

required
values Tensor

[*batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, n_rows, n_cols, *dense).

required
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties.

None
hints Hints | None

Performance expectations.

None
check bool

Validate the pointer and index ranges.

True

Examples:

>>> import torch
>>> from btorch import sparse
>>> A = sparse.csr(torch.tensor([0, 1, 2]), torch.tensor([2, 0]),
...                torch.tensor([3.0, 5.0]), shape=(2, 3))
>>> A.indptr
tensor([0, 1, 2])
>>> A @ torch.tensor([1.0, 0.0, 2.0])
tensor([6., 5.])
Source code in btorch/sparse/csr.py
class CSR(_Compressed):
    """Compressed sparse row format (exactly two sparse dimensions).

    Batch members share one sparsity pattern: ``crow_indices`` and
    ``col_indices`` are stored once and ``values`` is ``[*batch, nnz,
    *dense]``. This is the natural layout for ensembles and parameter sweeps
    over a fixed topology.

    Args:
        pointer: ``[n_rows + 1]`` row pointers (``crow_indices``).
        minor: ``[nnz]`` column of each entry (``col_indices``).
        values: ``[*batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, n_rows, n_cols, *dense)``.
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties.
        hints: Performance expectations.
        check: Validate the pointer and index ranges.

    Examples:
        >>> import torch
        >>> from btorch import sparse
        >>> A = sparse.csr(torch.tensor([0, 1, 2]), torch.tensor([2, 0]),
        ...                torch.tensor([3.0, 5.0]), shape=(2, 3))
        >>> A.indptr
        tensor([0, 1, 2])
        >>> A @ torch.tensor([1.0, 0.0, 2.0])
        tensor([6., 5.])
    """

    format = "csr"
    _major_axis = 0

    def crow_indices(self) -> Tensor:
        """``[n_rows + 1]`` row pointers (PyTorch name)."""
        return self._pointer

    def col_indices(self) -> Tensor:
        """``[nnz]`` column of each entry (PyTorch name)."""
        return self._minor

    def row_indices(self) -> Tensor:
        """``[nnz]`` row of each entry, expanded from the pointers."""
        return self._major_indices()

    def tocsr(self, return_map: bool = False):
        """Return ``self`` (already CSR; entries are left as stored).

        Use :meth:`coalesce` to sort columns and merge duplicates.
        """
        if return_map:
            return self, EdgeMap.identity(self.nnz, self._minor.device)
        return self

    def coalesce(self, return_map: bool = False):
        """Canonical CSR: sorted columns, duplicates summed."""
        return self.tocoo().tocsr(return_map)

    def tocsc(self, return_map: bool = False):
        return self.tocoo().tocsc(return_map)

    def transpose(self) -> "CSC":
        """Transpose without copying: the same arrays read as CSC."""
        return self._like(
            CSC,
            _shape=self._swapped_shape(),
            properties=self.properties.replace(triangular=None),
        )
Methods:
coalesce(return_map=False)

Canonical CSR: sorted columns, duplicates summed.

Source code in btorch/sparse/csr.py
def coalesce(self, return_map: bool = False):
    """Canonical CSR: sorted columns, duplicates summed."""
    return self.tocoo().tocsr(return_map)
col_indices()

[nnz] column of each entry (PyTorch name).

Source code in btorch/sparse/csr.py
def col_indices(self) -> Tensor:
    """``[nnz]`` column of each entry (PyTorch name)."""
    return self._minor
crow_indices()

[n_rows + 1] row pointers (PyTorch name).

Source code in btorch/sparse/csr.py
def crow_indices(self) -> Tensor:
    """``[n_rows + 1]`` row pointers (PyTorch name)."""
    return self._pointer
row_indices()

[nnz] row of each entry, expanded from the pointers.

Source code in btorch/sparse/csr.py
def row_indices(self) -> Tensor:
    """``[nnz]`` row of each entry, expanded from the pointers."""
    return self._major_indices()
tocsr(return_map=False)

Return self (already CSR; entries are left as stored).

Use :meth:coalesce to sort columns and merge duplicates.

Source code in btorch/sparse/csr.py
def tocsr(self, return_map: bool = False):
    """Return ``self`` (already CSR; entries are left as stored).

    Use :meth:`coalesce` to sort columns and merge duplicates.
    """
    if return_map:
        return self, EdgeMap.identity(self.nnz, self._minor.device)
    return self
transpose()

Transpose without copying: the same arrays read as CSC.

Source code in btorch/sparse/csr.py
def transpose(self) -> "CSC":
    """Transpose without copying: the same arrays read as CSC."""
    return self._like(
        CSC,
        _shape=self._swapped_shape(),
        properties=self.properties.replace(triangular=None),
    )

CompositeOperator

Bases: LinearOperator

Operator built lazily from other operators and sparse matrices.

The concrete composites are :class:SumOperator, :class:ProductOperator, :class:ScaledOperator and :class:TransposedOperator; they are normally created with +, @, * and .T. A composite supports a capability only if all of its parts do (a Sparse part supports everything).

Attributes:

Name Type Description
parts tuple[Any, ...]

The operands, in order.

Source code in btorch/sparse/operator.py
class CompositeOperator(LinearOperator):
    """Operator built lazily from other operators and sparse matrices.

    The concrete composites are :class:`SumOperator`,
    :class:`ProductOperator`, :class:`ScaledOperator` and
    :class:`TransposedOperator`; they are normally created with ``+``, ``@``,
    ``*`` and ``.T``. A composite supports a capability only if all of its
    parts do (a ``Sparse`` part supports everything).

    Attributes:
        parts: The operands, in order.
    """

    parts: tuple[Any, ...]

    def _set_parts(self, parts: Sequence[Any]) -> None:
        self.parts = tuple(_as_part(p) for p in parts)
        if not self.parts:
            raise ValueError(f"{type(self).__name__} needs at least one operand.")
        self.dtype = _composite_dtype(self.parts)
        self.device = _composite_device(self.parts)

    def _common(self, allowed: frozenset[str] = _ALL) -> frozenset[str]:
        out = allowed
        for part in self.parts:
            out = out & _capabilities_of(part)
        return out

    def __repr__(self) -> str:
        inner = ", ".join(repr(p) for p in self.parts)
        return f"{type(self).__name__}(shape={self.shape}, parts=[{inner}])"

Connection

Bases: Module

Base class of all connection realisations.

Attributes:

Name Type Description
n_pre int

Number of pre-synaptic (source) neurons.

n_post int

Number of post-synaptic (target) neurons.

in_features int

Size of the last input dimension.

out_features int

Size of the last output dimension.

Source code in btorch/models/connection/base.py
class Connection(nn.Module):
    """Base class of all connection realisations.

    Attributes:
        n_pre: Number of pre-synaptic (source) neurons.
        n_post: Number of post-synaptic (target) neurons.
        in_features: Size of the last input dimension.
        out_features: Size of the last output dimension.
    """

    n_pre: int
    n_post: int

    @property
    def in_features(self) -> int:
        return self.n_pre

    @property
    def out_features(self) -> int:
        return self.n_post

    def forward(self, x: Tensor) -> Tensor:
        raise NotImplementedError

ConstantOperator

Bases: StructuredOperator

All-to-all operator with one shared weight: A[m, n] = value.

.. math:: y_{\ldots m} = \text{value} \cdot \sum_n x_{\ldots n}

The product costs O(M + N) instead of O(M N).

Parameters:

Name Type Description Default
shape tuple[int, int]

(M, N).

required
value Tensor | float

Scalar weight: a Python number or a 0-dim tensor (for example an nn.Parameter; gradients flow to it).

1.0
dtype dtype | None

Dtype used when value is a Python number.

None
device device | str | None

Device used when value is a Python number.

None

Examples:

>>> A = ConstantOperator((2, 3), 2.0)
>>> A @ torch.tensor([1.0, 2.0, 3.0])
tensor([12., 12.])
Source code in btorch/sparse/operator.py
class ConstantOperator(StructuredOperator):
    """All-to-all operator with one shared weight: ``A[m, n] = value``.

    .. math::
        y_{\\ldots m} = \\text{value} \\cdot \\sum_n x_{\\ldots n}

    The product costs ``O(M + N)`` instead of ``O(M N)``.

    Args:
        shape: ``(M, N)``.
        value: Scalar weight: a Python number or a 0-dim tensor (for example
            an ``nn.Parameter``; gradients flow to it).
        dtype: Dtype used when ``value`` is a Python number.
        device: Device used when ``value`` is a Python number.

    Examples:
        >>> A = ConstantOperator((2, 3), 2.0)
        >>> A @ torch.tensor([1.0, 2.0, 3.0])
        tensor([12., 12.])
    """

    def __init__(
        self,
        shape: tuple[int, int],
        value: Tensor | float = 1.0,
        *,
        dtype: torch.dtype | None = None,
        device: torch.device | str | None = None,
    ):
        self._shape = _check_shape(shape)
        if isinstance(value, Tensor):
            if value.ndim != 0:
                raise ValueError(
                    "ConstantOperator needs a scalar value, got shape "
                    f"{tuple(value.shape)}."
                )
            self.dtype, self.device = value.dtype, value.device
        else:
            self.dtype = dtype
            self.device = torch.device(device) if device is not None else None
        self.value = value

    def _matvec(self, x: Tensor) -> Tensor:
        total = x.sum(-1, keepdim=True) * self.value
        return total.expand(*x.shape[:-1], self._shape[0])

    def _rmatvec(self, x: Tensor) -> Tensor:
        total = x.sum(-1, keepdim=True) * self.value
        return total.expand(*x.shape[:-1], self._shape[1])

    def _value_tensor(self) -> Tensor:
        if isinstance(self.value, Tensor):
            return self.value
        return torch.tensor(self.value, dtype=self.dtype, device=self.device)

    def _enumerate_edges(self) -> Edges:
        m, n = self._shape
        value = self._value_tensor()
        rows = torch.arange(m, device=value.device).repeat_interleave(n)
        cols = torch.arange(n, device=value.device).repeat(m)
        return rows, cols, value.expand(m * n)

    def to_dense(self, *, dtype=None, device=None) -> Tensor:
        return self._value_tensor().to(dtype=dtype, device=device).expand(self._shape)

DiagonalOperator

Bases: StructuredOperator

One-to-one operator: A = diag(d), y = d * x.

Parameters:

Name Type Description Default
diag Tensor

[N] diagonal (may be an nn.Parameter).

required

Examples:

>>> DiagonalOperator(torch.tensor([1.0, 2.0])) @ torch.tensor([3.0, 4.0])
tensor([3., 8.])
Source code in btorch/sparse/operator.py
class DiagonalOperator(StructuredOperator):
    """One-to-one operator: ``A = diag(d)``, ``y = d * x``.

    Args:
        diag: ``[N]`` diagonal (may be an ``nn.Parameter``).

    Examples:
        >>> DiagonalOperator(torch.tensor([1.0, 2.0])) @ torch.tensor([3.0, 4.0])
        tensor([3., 8.])
    """

    def __init__(self, diag: Tensor):
        if not isinstance(diag, Tensor) or diag.ndim != 1:
            raise ValueError("DiagonalOperator needs a 1-D tensor.")
        self.diag = diag
        self._shape = (diag.shape[0], diag.shape[0])
        self.dtype, self.device = diag.dtype, diag.device

    def _matvec(self, x: Tensor) -> Tensor:
        return x * self.diag

    _rmatvec = _matvec

    def _enumerate_edges(self) -> Edges:
        index = torch.arange(self._shape[0], device=self.diag.device)
        return index, index, self.diag

    def to_dense(self, *, dtype=None, device=None) -> Tensor:
        return torch.diag(self.diag).to(dtype=dtype, device=device)

EdgeMap dataclass

Correspondence between the entries of two representations.

A representation change (sorting, duplicate reduction) maps every old entry e to a new entry target[e]. Every edge-aligned array (values, group ids, receptors, delays, plasticity state) must be moved with the same map, so the map is computed once and applied to each of them.

Parameters:

Name Type Description Default
target Tensor

[n_old] new position of every old entry.

required
n_new int

Number of entries after the change.

required
Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class EdgeMap:
    """Correspondence between the entries of two representations.

    A representation change (sorting, duplicate reduction) maps every old
    entry ``e`` to a new entry ``target[e]``. Every edge-aligned array (values,
    group ids, receptors, delays, plasticity state) must be moved with the same
    map, so the map is computed once and applied to each of them.

    Args:
        target: ``[n_old]`` new position of every old entry.
        n_new: Number of entries after the change.
    """

    target: Tensor
    n_new: int

    @property
    def n_old(self) -> int:
        return int(self.target.shape[0])

    @property
    def is_permutation(self) -> bool:
        """Whether no entries were merged."""
        return self.n_old == self.n_new

    def source(self) -> Tensor:
        """``[n_new]`` index of one old entry for every new entry.

        For merged duplicates this is the last old entry of the group.
        """
        old = torch.arange(self.n_old, device=self.target.device)
        if self.is_permutation:
            src = torch.empty_like(old)
            src[self.target] = old
            return src
        # Deterministic on every device (an indexed assignment with repeated
        # targets is not).
        src = self.target.new_zeros(self.n_new)
        return src.scatter_reduce(0, self.target, old, "amax", include_self=False)

    def sum(self, values: Tensor, dim: int = -1) -> Tensor:
        """Move additive data (weights); merged entries are summed.

        Differentiable: the gradient of a merged entry flows to every old
        entry that was merged into it.

        Args:
            values: Tensor whose axis ``dim`` has length ``n_old``.
            dim: Edge axis.
        """
        if self.is_permutation:
            return values.index_select(dim, self.source())
        shape = list(values.shape)
        shape[dim] = self.n_new
        return values.new_zeros(shape).index_add(dim, self.target, values)

    def take(self, meta: Tensor, dim: int = 0, check: bool = True) -> Tensor:
        """Move categorical metadata (group, receptor, delay ids).

        Args:
            meta: Tensor whose axis ``dim`` has length ``n_old``.
            dim: Edge axis.
            check: Raise if merged entries carry different metadata, because
                no single value can then represent the merged entry.

        Raises:
            ValueError: If ``check`` and merged duplicates disagree.
        """
        out = meta.index_select(dim, self.source())
        if check and not self.is_permutation:
            if not torch.equal(out.index_select(dim, self.target), meta):
                raise ValueError(
                    "Duplicate entries carry different metadata and cannot be "
                    "merged; split them into separate connections or make the "
                    "metadata equal first."
                )
        return out

    def compose(self, then: "EdgeMap") -> "EdgeMap":
        """Map equivalent to applying ``self`` and then ``then``."""
        return EdgeMap(then.target[self.target], then.n_new)

    @staticmethod
    def identity(n: int, device=None) -> "EdgeMap":
        return EdgeMap(torch.arange(n, device=device), n)
Attributes
is_permutation property

Whether no entries were merged.

Methods:
compose(then)

Map equivalent to applying self and then then.

Source code in btorch/sparse/properties.py
def compose(self, then: "EdgeMap") -> "EdgeMap":
    """Map equivalent to applying ``self`` and then ``then``."""
    return EdgeMap(then.target[self.target], then.n_new)
source()

[n_new] index of one old entry for every new entry.

For merged duplicates this is the last old entry of the group.

Source code in btorch/sparse/properties.py
def source(self) -> Tensor:
    """``[n_new]`` index of one old entry for every new entry.

    For merged duplicates this is the last old entry of the group.
    """
    old = torch.arange(self.n_old, device=self.target.device)
    if self.is_permutation:
        src = torch.empty_like(old)
        src[self.target] = old
        return src
    # Deterministic on every device (an indexed assignment with repeated
    # targets is not).
    src = self.target.new_zeros(self.n_new)
    return src.scatter_reduce(0, self.target, old, "amax", include_self=False)
sum(values, dim=-1)

Move additive data (weights); merged entries are summed.

Differentiable: the gradient of a merged entry flows to every old entry that was merged into it.

Parameters:

Name Type Description Default
values Tensor

Tensor whose axis dim has length n_old.

required
dim int

Edge axis.

-1
Source code in btorch/sparse/properties.py
def sum(self, values: Tensor, dim: int = -1) -> Tensor:
    """Move additive data (weights); merged entries are summed.

    Differentiable: the gradient of a merged entry flows to every old
    entry that was merged into it.

    Args:
        values: Tensor whose axis ``dim`` has length ``n_old``.
        dim: Edge axis.
    """
    if self.is_permutation:
        return values.index_select(dim, self.source())
    shape = list(values.shape)
    shape[dim] = self.n_new
    return values.new_zeros(shape).index_add(dim, self.target, values)
take(meta, dim=0, check=True)

Move categorical metadata (group, receptor, delay ids).

Parameters:

Name Type Description Default
meta Tensor

Tensor whose axis dim has length n_old.

required
dim int

Edge axis.

0
check bool

Raise if merged entries carry different metadata, because no single value can then represent the merged entry.

True

Raises:

Type Description
ValueError

If check and merged duplicates disagree.

Source code in btorch/sparse/properties.py
def take(self, meta: Tensor, dim: int = 0, check: bool = True) -> Tensor:
    """Move categorical metadata (group, receptor, delay ids).

    Args:
        meta: Tensor whose axis ``dim`` has length ``n_old``.
        dim: Edge axis.
        check: Raise if merged entries carry different metadata, because
            no single value can then represent the merged entry.

    Raises:
        ValueError: If ``check`` and merged duplicates disagree.
    """
    out = meta.index_select(dim, self.source())
    if check and not self.is_permutation:
        if not torch.equal(out.index_select(dim, self.target), meta):
            raise ValueError(
                "Duplicate entries carry different metadata and cannot be "
                "merged; split them into separate connections or make the "
                "metadata equal first."
            )
    return out

Hints dataclass

Performance expectations; advisory only.

Only expected_density is consulted by the planner today; the other two are accepted and reserved.

Parameters:

Name Type Description Default
expected_calls int | None

How many products the object will take part in (reserved).

None
expected_density float | None

Expected fraction of non-zero input entries, in [0, 1].

None
expected_batch int | None

Expected number of right-hand sides per call (reserved).

None

Raises:

Type Description
ValueError

If a value is out of range.

Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class Hints:
    """Performance expectations; advisory only.

    Only ``expected_density`` is consulted by the planner today; the other
    two are accepted and reserved.

    Args:
        expected_calls: How many products the object will take part in
            (reserved).
        expected_density: Expected fraction of non-zero input entries, in
            ``[0, 1]``.
        expected_batch: Expected number of right-hand sides per call
            (reserved).

    Raises:
        ValueError: If a value is out of range.
    """

    expected_calls: int | None = None
    expected_density: float | None = None
    expected_batch: int | None = None

    def __post_init__(self) -> None:
        density = self.expected_density
        if density is not None and not (
            isinstance(density, (int, float)) and 0.0 <= density <= 1.0
        ):
            raise ValueError(f"expected_density must be in [0, 1], got {density!r}.")
        for name in ("expected_calls", "expected_batch"):
            value = getattr(self, name)
            if value is not None and not (isinstance(value, int) and value > 0):
                raise ValueError(f"{name} must be a positive int, got {value!r}.")

    def replace(self, **changes) -> "Hints":
        """Return a copy with selected expectations changed."""
        return replace(self, **changes)
Methods:
replace(**changes)

Return a copy with selected expectations changed.

Source code in btorch/sparse/properties.py
def replace(self, **changes) -> "Hints":
    """Return a copy with selected expectations changed."""
    return replace(self, **changes)

ImplicitOperator

Bases: LinearOperator

Operator defined by user callables; nothing is stored or materialised.

Only matvec is required. Every other capability exists exactly when its callable was given, so an apply-only operator refuses .T, x @ A and tocsr() with a clear error, while an enumerable procedural operator can be materialised on request.

The callables are stored as given and called directly: the operator is differentiable when they are, and works under torch.compile when they do.

Parameters:

Name Type Description Default
shape tuple[int, int]

(M, N).

required
matvec Callable[[Tensor], Tensor]

x [..., N] -> y [..., M], applied along the last axis.

required
rmatvec Callable[[Tensor], Tensor] | None

Optional transpose apply x [..., M] -> y [..., N].

None
enumerate_edges Callable[[], Edges] | None

Optional callable without arguments returning (rows [E], cols [E], values [E]). Enables :meth:~LinearOperator.materialize, tocoo() and tocsr().

None
dtype dtype | None

Optional dtype, used by :meth:~LinearOperator.to_dense.

None
device device | str | None

Optional device, used by :meth:~LinearOperator.to_dense.

None
matmat Callable[[Tensor], Tensor] | None

Optional X [..., N, K] -> [..., M, K]. Defaults to matvec applied to the columns.

None

Examples:

A circular shift, never stored as a matrix:

>>> shift = ImplicitOperator(
...     (4, 4),
...     matvec=lambda x: x.roll(1, -1),
...     rmatvec=lambda x: x.roll(-1, -1),
... )
>>> shift @ torch.tensor([1.0, 2.0, 3.0, 4.0])
tensor([4., 1., 2., 3.])
Source code in btorch/sparse/operator.py
class ImplicitOperator(LinearOperator):
    """Operator defined by user callables; nothing is stored or materialised.

    Only ``matvec`` is required. Every other capability exists exactly when
    its callable was given, so an apply-only operator refuses ``.T``,
    ``x @ A`` and ``tocsr()`` with a clear error, while an enumerable
    procedural operator can be materialised on request.

    The callables are stored as given and called directly: the operator is
    differentiable when they are, and works under ``torch.compile`` when they
    do.

    Args:
        shape: ``(M, N)``.
        matvec: ``x [..., N] -> y [..., M]``, applied along the last axis.
        rmatvec: Optional transpose apply ``x [..., M] -> y [..., N]``.
        enumerate_edges: Optional callable without arguments returning
            ``(rows [E], cols [E], values [E])``. Enables
            :meth:`~LinearOperator.materialize`, ``tocoo()`` and ``tocsr()``.
        dtype: Optional dtype, used by :meth:`~LinearOperator.to_dense`.
        device: Optional device, used by :meth:`~LinearOperator.to_dense`.
        matmat: Optional ``X [..., N, K] -> [..., M, K]``. Defaults to
            ``matvec`` applied to the columns.

    Examples:
        A circular shift, never stored as a matrix:

        >>> shift = ImplicitOperator(
        ...     (4, 4),
        ...     matvec=lambda x: x.roll(1, -1),
        ...     rmatvec=lambda x: x.roll(-1, -1),
        ... )
        >>> shift @ torch.tensor([1.0, 2.0, 3.0, 4.0])
        tensor([4., 1., 2., 3.])
    """

    def __init__(
        self,
        shape: tuple[int, int],
        matvec: Callable[[Tensor], Tensor],
        rmatvec: Callable[[Tensor], Tensor] | None = None,
        enumerate_edges: Callable[[], Edges] | None = None,
        dtype: torch.dtype | None = None,
        device: torch.device | str | None = None,
        *,
        matmat: Callable[[Tensor], Tensor] | None = None,
    ):
        if not callable(matvec):
            raise TypeError("ImplicitOperator needs a callable matvec.")
        self._shape = _check_shape(shape)
        self._matvec_fn = matvec
        self._rmatvec_fn = rmatvec
        self._matmat_fn = matmat
        self._edges_fn = enumerate_edges
        self.dtype = dtype
        self.device = torch.device(device) if device is not None else None
        capabilities = {"matvec", "matmat"}
        if rmatvec is not None:
            capabilities.add("rmatvec")
        if enumerate_edges is not None:
            capabilities |= {"enumerate_edges", "materialize_sparse"}
        self._capabilities = frozenset(capabilities)

    def _matvec(self, x: Tensor) -> Tensor:
        return self._matvec_fn(x)

    def _rmatvec(self, x: Tensor) -> Tensor:
        return self._rmatvec_fn(x)

    def _matmat(self, x: Tensor) -> Tensor:
        if self._matmat_fn is not None:
            return self._matmat_fn(x)
        return self._matvec_fn(x.mT).mT

    def _enumerate_edges(self) -> Edges:
        rows, cols, values = self._edges_fn()
        return rows, cols, values

LinearOperator

Base class of everything that acts as a matrix of shape (M, N).

Subclasses implement the private hooks _matvec / _rmatvec (and optionally _matmat / _enumerate_edges) and list what they provide in _capabilities. The public methods validate shapes and capabilities and are shared by all operators.

Operators are plain Python objects holding tensors, like :class:~btorch.sparse.Sparse; they are not nn.Module. A learnable tensor used by an operator must be registered on the owning module, which passes it to the operator (see the examples of the concrete classes).

Operator algebra is lazy and never builds a matrix:

  • A + B, A - B: :class:SumOperator.
  • A @ B with another operator or a Sparse: :class:ProductOperator.
  • alpha * A, A * alpha, A / alpha, -A: :class:ScaledOperator.
  • A.T: :class:TransposedOperator.

The class is an ABC only so that explicit sparse arrays can be registered as virtual subclasses (LinearOperator.register(Sparse)); it has no abstract methods.

Source code in btorch/sparse/operator.py
class LinearOperator(metaclass=ABCMeta):
    """Base class of everything that acts as a matrix of shape ``(M, N)``.

    Subclasses implement the private hooks ``_matvec`` / ``_rmatvec`` (and
    optionally ``_matmat`` / ``_enumerate_edges``) and list what they provide
    in ``_capabilities``. The public methods validate shapes and capabilities
    and are shared by all operators.

    Operators are plain Python objects holding tensors, like
    :class:`~btorch.sparse.Sparse`; they are not ``nn.Module``. A learnable
    tensor used by an operator must be registered on the owning module, which
    passes it to the operator (see the examples of the concrete classes).

    Operator algebra is lazy and never builds a matrix:

    - ``A + B``, ``A - B``: :class:`SumOperator`.
    - ``A @ B`` with another operator or a ``Sparse``: :class:`ProductOperator`.
    - ``alpha * A``, ``A * alpha``, ``A / alpha``, ``-A``:
      :class:`ScaledOperator`.
    - ``A.T``: :class:`TransposedOperator`.

    The class is an ABC only so that explicit sparse arrays can be registered
    as virtual subclasses (``LinearOperator.register(Sparse)``); it has no
    abstract methods.
    """

    _capabilities: frozenset[str] = frozenset()
    _shape: tuple[int, int]
    dtype: torch.dtype | None = None
    device: torch.device | None = None

    # ----------------------------------------------------------------- shape
    @property
    def shape(self) -> tuple[int, int]:
        """``(M, N)``: the operator maps length-``N`` to length-``M``."""
        return self._shape

    @property
    def ndim(self) -> int:
        return 2

    # ---------------------------------------------------------- capabilities
    def supports(self, name: str) -> bool:
        """Whether the optional capability ``name`` is available.

        Args:
            name: One of :data:`CAPABILITIES`.

        Raises:
            ValueError: If ``name`` is not a known capability.
        """
        if name not in CAPABILITIES:
            raise ValueError(
                f"Unknown capability {name!r}; expected one of {sorted(CAPABILITIES)}."
            )
        return name in self._capabilities

    def _require(self, name: str) -> None:
        if name not in self._capabilities:
            raise NotImplementedError(
                f"{type(self).__name__} of shape {self.shape} does not support "
                f"the capability {name!r} (supported: "
                f"{sorted(self._capabilities)})."
            )

    # --------------------------------------------------------------- products
    def matvec(self, x: Tensor) -> Tensor:
        """Apply the operator along the last axis: ``[..., N] -> [..., M]``.

        .. math::
            y_{\\ldots m} = \\sum_n A_{m n}\\, x_{\\ldots n}

        All leading dimensions of ``x`` are independent samples.
        """
        self._require("matvec")
        if x.shape[-1] != self._shape[1]:
            raise ValueError(
                f"matvec: the last dimension of the input is {x.shape[-1]}, "
                f"expected {self._shape[1]} for an operator of shape {self.shape}."
            )
        return self._matvec(x)

    def rmatvec(self, x: Tensor) -> Tensor:
        """Apply the transpose along the last axis: ``[..., M] -> [..., N]``.

        Equals ``self.T.matvec(x)`` and, for 1-D ``x``, ``x @ self``.
        """
        self._require("rmatvec")
        if x.shape[-1] != self._shape[0]:
            raise ValueError(
                f"rmatvec: the last dimension of the input is {x.shape[-1]}, "
                f"expected {self._shape[0]} for an operator of shape {self.shape}."
            )
        return self._rmatvec(x)

    def matmat(self, x: Tensor) -> Tensor:
        """``A @ X`` for ``X [..., N, K]``, returning ``[..., M, K]``."""
        self._require("matmat")
        if x.ndim < 2 or x.shape[-2] != self._shape[1]:
            raise ValueError(
                f"matmat: the input needs shape [..., {self._shape[1]}, K] for "
                f"an operator of shape {self.shape}, got {tuple(x.shape)}."
            )
        return self._matmat(x)

    def _matvec(self, x: Tensor) -> Tensor:
        raise NotImplementedError

    def _rmatvec(self, x: Tensor) -> Tensor:
        raise NotImplementedError

    def _matmat(self, x: Tensor) -> Tensor:
        # Columns of X are vectors: move them to the last axis and back.
        return self.matvec(x.mT).mT

    def __matmul__(self, other):
        if isinstance(other, Tensor):
            if other.ndim == 0:
                raise ValueError("A @ x needs x with at least one dimension.")
            if other.ndim == 1:
                return self.matvec(other)
            return self.matmat(other)
        if is_linear_operator(other):
            return ProductOperator([self, other])
        return NotImplemented

    def __rmatmul__(self, other):
        if isinstance(other, Tensor):
            if other.ndim == 0:
                raise ValueError("x @ A needs x with at least one dimension.")
            # 1-D: x [M] -> [N]; matrix: X [..., K, M] -> [..., K, N]. In both
            # cases the transpose acts along the last axis.
            return self.rmatvec(other)
        if is_linear_operator(other):
            return ProductOperator([other, self])
        return NotImplemented

    # ---------------------------------------------------------- lazy algebra
    def __add__(self, other):
        if is_linear_operator(other):
            return SumOperator([self, other])
        return NotImplemented

    def __radd__(self, other):
        if is_linear_operator(other):
            return SumOperator([other, self])
        return NotImplemented

    def __sub__(self, other):
        if is_linear_operator(other):
            return SumOperator([self, ScaledOperator(other, -1.0)])
        return NotImplemented

    def __rsub__(self, other):
        if is_linear_operator(other):
            return SumOperator([other, ScaledOperator(self, -1.0)])
        return NotImplemented

    def __mul__(self, alpha):
        if _is_scalar(alpha):
            return ScaledOperator(self, alpha)
        return NotImplemented

    __rmul__ = __mul__

    def __truediv__(self, alpha):
        if _is_scalar(alpha):
            return ScaledOperator(self, 1.0 / alpha)
        return NotImplemented

    def __neg__(self):
        return ScaledOperator(self, -1.0)

    @property
    def T(self) -> "LinearOperator":
        """Lazy transpose; needs the ``"rmatvec"`` capability."""
        return TransposedOperator(self)

    def transpose(self) -> "LinearOperator":
        return self.T

    # -------------------------------------------------------- materialisation
    def enumerate_edges(self) -> Edges:
        """List the entries as ``(rows [E], cols [E], values [E])``.

        Entries may repeat; repeated coordinates are summed, as in
        :class:`~btorch.sparse.COO`. ``values`` keeps its autograd history.
        """
        self._require("enumerate_edges")
        return self._enumerate_edges()

    def _enumerate_edges(self) -> Edges:
        raise NotImplementedError

    def materialize(self, format: str | None = None):
        """Build an explicit :class:`~btorch.sparse.Sparse` with these entries.

        Args:
            format: Optional ``"coo"``, ``"csr"`` or ``"csc"``. Without it the
                result is format-agnostic.

        Raises:
            NotImplementedError: If the operator cannot list its entries
                (capability ``"materialize_sparse"``).
        """
        self._require("materialize_sparse")
        from . import from_edges

        rows, cols, values = self._enumerate_edges()
        out = from_edges(rows, cols, values, self.shape)
        if format is not None and out.format != format:
            out = getattr(out, f"to{format}")()
        return out

    def tocoo(self):
        """Materialise as COO (capability ``"materialize_sparse"``)."""
        return self.materialize("coo")

    def tocsr(self):
        """Materialise as CSR (capability ``"materialize_sparse"``)."""
        return self.materialize("csr")

    def tocsc(self):
        """Materialise as CSC (capability ``"materialize_sparse"``)."""
        return self.materialize("csc")

    def to_dense(
        self,
        *,
        dtype: torch.dtype | None = None,
        device: torch.device | str | None = None,
    ) -> Tensor:
        """Dense ``[M, N]`` matrix; an explicit request, never done implicitly.

        The default applies the operator to the identity (``N`` right-hand
        sides at once), so it only needs ``"matvec"`` and stays
        differentiable.

        Args:
            dtype: Dtype of the identity; defaults to the operator dtype if
                it has one.
            device: Device of the identity; defaults to the operator device.
        """
        eye = torch.eye(
            self._shape[1],
            dtype=dtype if dtype is not None else self.dtype,
            device=device if device is not None else self.device,
        )
        # Row n of matvec(eye) is A @ e_n, i.e. column n of A.
        return self.matvec(eye).mT

    def __repr__(self) -> str:
        return f"{type(self).__name__}(shape={self.shape})"
Attributes
T property

Lazy transpose; needs the "rmatvec" capability.

shape property

(M, N): the operator maps length-N to length-M.

Methods:
enumerate_edges()

List the entries as (rows [E], cols [E], values [E]).

Entries may repeat; repeated coordinates are summed, as in :class:~btorch.sparse.COO. values keeps its autograd history.

Source code in btorch/sparse/operator.py
def enumerate_edges(self) -> Edges:
    """List the entries as ``(rows [E], cols [E], values [E])``.

    Entries may repeat; repeated coordinates are summed, as in
    :class:`~btorch.sparse.COO`. ``values`` keeps its autograd history.
    """
    self._require("enumerate_edges")
    return self._enumerate_edges()
materialize(format=None)

Build an explicit :class:~btorch.sparse.Sparse with these entries.

Parameters:

Name Type Description Default
format str | None

Optional "coo", "csr" or "csc". Without it the result is format-agnostic.

None

Raises:

Type Description
NotImplementedError

If the operator cannot list its entries (capability "materialize_sparse").

Source code in btorch/sparse/operator.py
def materialize(self, format: str | None = None):
    """Build an explicit :class:`~btorch.sparse.Sparse` with these entries.

    Args:
        format: Optional ``"coo"``, ``"csr"`` or ``"csc"``. Without it the
            result is format-agnostic.

    Raises:
        NotImplementedError: If the operator cannot list its entries
            (capability ``"materialize_sparse"``).
    """
    self._require("materialize_sparse")
    from . import from_edges

    rows, cols, values = self._enumerate_edges()
    out = from_edges(rows, cols, values, self.shape)
    if format is not None and out.format != format:
        out = getattr(out, f"to{format}")()
    return out
matmat(x)

A @ X for X [..., N, K], returning [..., M, K].

Source code in btorch/sparse/operator.py
def matmat(self, x: Tensor) -> Tensor:
    """``A @ X`` for ``X [..., N, K]``, returning ``[..., M, K]``."""
    self._require("matmat")
    if x.ndim < 2 or x.shape[-2] != self._shape[1]:
        raise ValueError(
            f"matmat: the input needs shape [..., {self._shape[1]}, K] for "
            f"an operator of shape {self.shape}, got {tuple(x.shape)}."
        )
    return self._matmat(x)
matvec(x)

Apply the operator along the last axis: [..., N] -> [..., M].

.. math:: y_{\ldots m} = \sum_n A_{m n}\, x_{\ldots n}

All leading dimensions of x are independent samples.

Source code in btorch/sparse/operator.py
def matvec(self, x: Tensor) -> Tensor:
    """Apply the operator along the last axis: ``[..., N] -> [..., M]``.

    .. math::
        y_{\\ldots m} = \\sum_n A_{m n}\\, x_{\\ldots n}

    All leading dimensions of ``x`` are independent samples.
    """
    self._require("matvec")
    if x.shape[-1] != self._shape[1]:
        raise ValueError(
            f"matvec: the last dimension of the input is {x.shape[-1]}, "
            f"expected {self._shape[1]} for an operator of shape {self.shape}."
        )
    return self._matvec(x)
rmatvec(x)

Apply the transpose along the last axis: [..., M] -> [..., N].

Equals self.T.matvec(x) and, for 1-D x, x @ self.

Source code in btorch/sparse/operator.py
def rmatvec(self, x: Tensor) -> Tensor:
    """Apply the transpose along the last axis: ``[..., M] -> [..., N]``.

    Equals ``self.T.matvec(x)`` and, for 1-D ``x``, ``x @ self``.
    """
    self._require("rmatvec")
    if x.shape[-1] != self._shape[0]:
        raise ValueError(
            f"rmatvec: the last dimension of the input is {x.shape[-1]}, "
            f"expected {self._shape[0]} for an operator of shape {self.shape}."
        )
    return self._rmatvec(x)
supports(name)

Whether the optional capability name is available.

Parameters:

Name Type Description Default
name str

One of :data:CAPABILITIES.

required

Raises:

Type Description
ValueError

If name is not a known capability.

Source code in btorch/sparse/operator.py
def supports(self, name: str) -> bool:
    """Whether the optional capability ``name`` is available.

    Args:
        name: One of :data:`CAPABILITIES`.

    Raises:
        ValueError: If ``name`` is not a known capability.
    """
    if name not in CAPABILITIES:
        raise ValueError(
            f"Unknown capability {name!r}; expected one of {sorted(CAPABILITIES)}."
        )
    return name in self._capabilities
to_dense(*, dtype=None, device=None)

Dense [M, N] matrix; an explicit request, never done implicitly.

The default applies the operator to the identity (N right-hand sides at once), so it only needs "matvec" and stays differentiable.

Parameters:

Name Type Description Default
dtype dtype | None

Dtype of the identity; defaults to the operator dtype if it has one.

None
device device | str | None

Device of the identity; defaults to the operator device.

None
Source code in btorch/sparse/operator.py
def to_dense(
    self,
    *,
    dtype: torch.dtype | None = None,
    device: torch.device | str | None = None,
) -> Tensor:
    """Dense ``[M, N]`` matrix; an explicit request, never done implicitly.

    The default applies the operator to the identity (``N`` right-hand
    sides at once), so it only needs ``"matvec"`` and stays
    differentiable.

    Args:
        dtype: Dtype of the identity; defaults to the operator dtype if
            it has one.
        device: Device of the identity; defaults to the operator device.
    """
    eye = torch.eye(
        self._shape[1],
        dtype=dtype if dtype is not None else self.dtype,
        device=device if device is not None else self.device,
    )
    # Row n of matvec(eye) is A @ e_n, i.e. column n of A.
    return self.matvec(eye).mT
tocoo()

Materialise as COO (capability "materialize_sparse").

Source code in btorch/sparse/operator.py
def tocoo(self):
    """Materialise as COO (capability ``"materialize_sparse"``)."""
    return self.materialize("coo")
tocsc()

Materialise as CSC (capability "materialize_sparse").

Source code in btorch/sparse/operator.py
def tocsc(self):
    """Materialise as CSC (capability ``"materialize_sparse"``)."""
    return self.materialize("csc")
tocsr()

Materialise as CSR (capability "materialize_sparse").

Source code in btorch/sparse/operator.py
def tocsr(self):
    """Materialise as CSR (capability ``"materialize_sparse"``)."""
    return self.materialize("csr")

LowRankOperator

Bases: StructuredOperator

Low-rank operator A = U V^T applied as two thin products.

.. math:: y = U\,(V^\top x)

The product costs O((M + N) r). U V^T is dense, so listing its entries is not offered ("enumerate_edges" and "materialize_sparse" are unsupported); use :meth:to_dense for the explicit matrix.

Parameters:

Name Type Description Default
U Tensor

[M, r] left factor.

required
V Tensor

[N, r] right factor. Both may be nn.Parameter.

required
Source code in btorch/sparse/operator.py
class LowRankOperator(StructuredOperator):
    """Low-rank operator ``A = U V^T`` applied as two thin products.

    .. math::
        y = U\\,(V^\\top x)

    The product costs ``O((M + N) r)``. ``U V^T`` is dense, so listing its
    entries is not offered (``"enumerate_edges"`` and ``"materialize_sparse"``
    are unsupported); use :meth:`to_dense` for the explicit matrix.

    Args:
        U: ``[M, r]`` left factor.
        V: ``[N, r]`` right factor. Both may be ``nn.Parameter``.
    """

    _capabilities = _APPLY

    def __init__(self, U: Tensor, V: Tensor):
        if U.ndim != 2 or V.ndim != 2 or U.shape[1] != V.shape[1]:
            raise ValueError(
                "LowRankOperator needs U [M, r] and V [N, r] with the same "
                f"rank, got {tuple(U.shape)} and {tuple(V.shape)}."
            )
        self.U, self.V = U, V
        self._shape = (U.shape[0], V.shape[0])
        self.dtype, self.device = U.dtype, U.device

    @property
    def rank(self) -> int:
        return int(self.U.shape[1])

    def _matvec(self, x: Tensor) -> Tensor:
        return (x @ self.V) @ self.U.mT

    def _rmatvec(self, x: Tensor) -> Tensor:
        return (x @ self.U) @ self.V.mT

    def to_dense(self, *, dtype=None, device=None) -> Tensor:
        return (self.U @ self.V.mT).to(dtype=dtype, device=device)

ProductOperator

Bases: CompositeOperator

Lazy composition A_1 @ A_2 @ ... (the rightmost is applied first).

The product is never formed: matvec applies the parts right to left and rmatvec left to right. Its entries cannot be listed (that would be a sparse-sparse product), so "enumerate_edges" and "materialize_sparse" are unsupported.

Parameters:

Name Type Description Default
parts Sequence[Any]

Operators and/or sparse matrices with chained shapes (M, K_1), (K_1, K_2), ..., (K_j, N).

required
Source code in btorch/sparse/operator.py
class ProductOperator(CompositeOperator):
    """Lazy composition ``A_1 @ A_2 @ ...`` (the rightmost is applied first).

    The product is never formed: ``matvec`` applies the parts right to left
    and ``rmatvec`` left to right. Its entries cannot be listed (that would
    be a sparse-sparse product), so ``"enumerate_edges"`` and
    ``"materialize_sparse"`` are unsupported.

    Args:
        parts: Operators and/or sparse matrices with chained shapes
            ``(M, K_1), (K_1, K_2), ..., (K_j, N)``.
    """

    def __init__(self, parts: Sequence[Any]):
        flat: list[Any] = []
        for part in parts:
            flat.extend(part.parts if isinstance(part, ProductOperator) else [part])
        self._set_parts(flat)
        dtypes = {
            part_dtype
            for part in self.parts
            if (part_dtype := getattr(part, "dtype", None)) is not None
        }
        if len(dtypes) > 1:
            raise ValueError(
                "Product operators require every operand to use one dtype, got "
                f"{sorted(map(str, dtypes))}."
            )
        for left, right in zip(self.parts[:-1], self.parts[1:]):
            if left.shape[1] != right.shape[0]:
                raise ValueError(
                    "Cannot compose operators of shapes "
                    f"{tuple(left.shape)} and {tuple(right.shape)}: the inner "
                    "dimensions differ."
                )
        self._shape = (self.parts[0].shape[0], self.parts[-1].shape[1])
        self._capabilities = self._common(_APPLY)
        self._reversed = self.parts[::-1]

    def _matvec(self, x: Tensor) -> Tensor:
        for part in self._reversed:
            x = part.matvec(x)
        return x

    def _rmatvec(self, x: Tensor) -> Tensor:
        for part in self.parts:
            x = part.rmatvec(x)
        return x

Properties dataclass

Structural facts about a stored sparse representation.

A True value is a guarantee; False means "not known", never "known to be violated".

Parameters:

Name Type Description Default
sorted bool

Entries are in lexicographic (row-major) index order.

False
unique bool

No index tuple is stored twice.

False
symmetric bool

Stored values satisfy A == A.T.

False
structurally_symmetric bool

The sparsity pattern is symmetric.

False
triangular str | None

"lower", "upper" or None.

None
fixed_pattern bool

The pattern is never mutated (no rewiring).

False
shared_pattern bool

A batch of matrices shares one pattern.

False
Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class Properties:
    """Structural facts about a stored sparse representation.

    A ``True`` value is a guarantee; ``False`` means "not known", never
    "known to be violated".

    Args:
        sorted: Entries are in lexicographic (row-major) index order.
        unique: No index tuple is stored twice.
        symmetric: Stored values satisfy ``A == A.T``.
        structurally_symmetric: The sparsity pattern is symmetric.
        triangular: ``"lower"``, ``"upper"`` or ``None``.
        fixed_pattern: The pattern is never mutated (no rewiring).
        shared_pattern: A batch of matrices shares one pattern.
    """

    sorted: bool = False
    unique: bool = False
    symmetric: bool = False
    structurally_symmetric: bool = False
    triangular: str | None = None
    fixed_pattern: bool = False
    shared_pattern: bool = False

    @property
    def canonical(self) -> bool:
        """Whether entries are sorted and free of duplicates."""
        return self.sorted and self.unique

    def replace(self, **changes) -> "Properties":
        """Return a copy with some fields changed."""
        return replace(self, **changes)
Attributes
canonical property

Whether entries are sorted and free of duplicates.

Methods:
replace(**changes)

Return a copy with some fields changed.

Source code in btorch/sparse/properties.py
def replace(self, **changes) -> "Properties":
    """Return a copy with some fields changed."""
    return replace(self, **changes)

ScaledOperator

Bases: CompositeOperator

Lazy scalar multiple alpha * A.

Parameters:

Name Type Description Default
operator Any

Operator or sparse matrix.

required
alpha Tensor | float

Python number or 0-dim tensor (may be an nn.Parameter).

required
Source code in btorch/sparse/operator.py
class ScaledOperator(CompositeOperator):
    """Lazy scalar multiple ``alpha * A``.

    Args:
        operator: Operator or sparse matrix.
        alpha: Python number or 0-dim tensor (may be an ``nn.Parameter``).
    """

    def __init__(self, operator: Any, alpha: Tensor | float):
        if not _is_scalar(alpha):
            raise TypeError("ScaledOperator needs a scalar factor.")
        self._set_parts([operator])
        self.alpha = alpha
        if isinstance(alpha, Tensor):
            if self.device is not None and alpha.device != self.device:
                raise ValueError(
                    "Scaled operators require the factor and operand on one "
                    f"device, got {alpha.device} and {self.device}."
                )
            if self.dtype is not None:
                self.dtype = torch.promote_types(self.dtype, alpha.dtype)
            else:
                self.dtype = alpha.dtype
            self.device = alpha.device if self.device is None else self.device
        elif self.dtype is not None:
            alpha_dtype = torch.tensor(alpha).dtype
            self.dtype = torch.promote_types(self.dtype, alpha_dtype)
        self._shape = tuple(operator.shape)
        self._capabilities = self._common()

    def _matvec(self, x: Tensor) -> Tensor:
        return self.parts[0].matvec(x) * self.alpha

    def _rmatvec(self, x: Tensor) -> Tensor:
        return self.parts[0].rmatvec(x) * self.alpha

    def _enumerate_edges(self) -> Edges:
        rows, cols, values = _edges_of(self.parts[0])
        return rows, cols, values * self.alpha

Sparse

Sparse array with logical shape [*batch, *sparse, *dense].

Sparse is the format-agnostic interface. It describes what the array is (shape, dtype, device, number of stored entries) and offers the operations every format supports. Format-specific data such as indptr is only available on the concrete classes (:class:~btorch.sparse.COO, :class:~btorch.sparse.CSR, :class:~btorch.sparse.CSC), obtained with tocsr() / as_csr() and friends.

The three shape groups are:

  • batch_shape: independent sparse arrays (for example an ensemble of networks).
  • sparse_shape: the dimensions that are stored sparsely.
  • dense_shape: a dense payload attached to every stored entry.

Stored values have shape [*value_batch, nnz, *dense_shape]. A batch whose members share one sparsity pattern stores the pattern once and only the values per member.

Sparse is a plain Python object holding tensors; it is not a torch.Tensor subclass. Matrix products follow standard linear algebra: for A.shape == (M, N), A @ x maps a length-N vector to a length-M vector. Conversions never transpose.

Source code in btorch/sparse/base.py
class Sparse:
    """Sparse array with logical shape ``[*batch, *sparse, *dense]``.

    ``Sparse`` is the format-agnostic interface. It describes *what* the array
    is (shape, dtype, device, number of stored entries) and offers the
    operations every format supports. Format-specific data such as ``indptr``
    is only available on the concrete classes (:class:`~btorch.sparse.COO`,
    :class:`~btorch.sparse.CSR`, :class:`~btorch.sparse.CSC`), obtained with
    ``tocsr()`` / ``as_csr()`` and friends.

    The three shape groups are:

    - ``batch_shape``: independent sparse arrays (for example an ensemble of
      networks).
    - ``sparse_shape``: the dimensions that are stored sparsely.
    - ``dense_shape``: a dense payload attached to every stored entry.

    Stored values have shape ``[*value_batch, nnz, *dense_shape]``. A batch
    whose members share one sparsity pattern stores the pattern once and only
    the values per member.

    ``Sparse`` is a plain Python object holding tensors; it is not a
    ``torch.Tensor`` subclass. Matrix products follow standard linear algebra:
    for ``A.shape == (M, N)``, ``A @ x`` maps a length-``N`` vector to a
    length-``M`` vector. Conversions never transpose.
    """

    format: str = "sparse"
    # Let ``ndarray @ A`` reach ``__rmatmul__`` instead of NumPy treating the
    # sparse array as an object scalar.
    __array_ufunc__ = None

    _values: Tensor
    _shape: tuple[int, ...]
    _batch_dim: int
    _dense_dim: int
    properties: Properties
    hints: Hints

    # ------------------------------------------------------------------ shape
    @property
    def shape(self) -> tuple[int, ...]:
        """Logical shape ``(*batch, *sparse, *dense)``."""
        return self._shape

    @property
    def ndim(self) -> int:
        return len(self._shape)

    def batch_dim(self) -> int:
        """Number of batch dimensions."""
        return self._batch_dim

    def dense_dim(self) -> int:
        """Number of dense (per-entry payload) dimensions."""
        return self._dense_dim

    def sparse_dim(self) -> int:
        """Number of sparsely stored dimensions."""
        return self.ndim - self._batch_dim - self._dense_dim

    @property
    def batch_shape(self) -> tuple[int, ...]:
        return self._shape[: self._batch_dim]

    @property
    def sparse_shape(self) -> tuple[int, ...]:
        return self._shape[self._batch_dim : self.ndim - self._dense_dim]

    @property
    def dense_shape(self) -> tuple[int, ...]:
        return self._shape[self.ndim - self._dense_dim :]

    @property
    def dtype(self) -> torch.dtype:
        return self._values.dtype

    @property
    def device(self) -> torch.device:
        return self._values.device

    @property
    def nnz(self) -> int:
        """Number of stored entries (of one batch member for a shared pattern,
        of all members together otherwise)."""
        raise NotImplementedError

    @property
    def requires_grad(self) -> bool:
        return self._values.requires_grad

    # ------------------------------------------------------- format changes
    def tocoo(self) -> "COO":
        """Convert to COO (may allocate)."""
        raise NotImplementedError

    def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
        """Convert to CSR (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
        """Convert to CSC (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tobsr(self, blocksize: tuple[int, int]):
        """Convert to BSR; not implemented as a native format.

        Use ``to_torch(layout="bsr", blocksize=...)`` or
        ``to_scipy(format="bsr")`` to export block storage.
        """
        raise NotImplementedError(
            "BSR is not a native btorch format yet; export with "
            "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
        )

    def _as(self, fmt: str):
        if self.format != fmt:
            hint = (
                "BSR is not a native format; export with to_torch(layout='bsr')."
                if fmt == "bsr"
                else f"Call to{fmt}() to convert explicitly."
            )
            raise TypeError(
                f"This sparse array is stored as {self.format.upper()}, not "
                f"{fmt.upper()}; as_{fmt}() never converts. {hint}"
            )
        return self

    def as_coo(self) -> "COO":
        """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
        return self._as("coo")

    def as_csr(self) -> "CSR":
        """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
        return self._as("csr")

    def as_csc(self) -> "CSC":
        """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
        return self._as("csc")

    def as_bsr(self, blocksize: tuple[int, int] | None = None):
        """BSR is not a native format; always raises ``TypeError``."""
        return self._as("bsr")

    # -------------------------------------------------------------- interop
    @classmethod
    def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
        """Wrap a ``torch`` sparse tensor (see
        :func:`btorch.sparse.from_torch`)."""
        from .conversion import from_torch

        return from_torch(tensor, batch_dim=batch_dim)

    @classmethod
    def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
        """Convert a SciPy sparse array or matrix (see
        :func:`btorch.sparse.from_scipy`)."""
        from .conversion import from_scipy

        return from_scipy(array, device=device, dtype=dtype)

    def to_torch(
        self, layout: str | torch.layout | None = None, **kwargs: Any
    ) -> Tensor:
        """Export as a ``torch`` sparse tensor.

        Args:
            layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
                (or the ``torch.sparse_*`` layout). Defaults to the stored
                format.
            **kwargs: ``blocksize`` for the block layouts.
        """
        from .conversion import to_torch

        return to_torch(self, layout, **kwargs)

    def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
        """Export as a ``scipy.sparse`` array (CPU, detached).

        Args:
            format: Any SciPy format name; defaults to the stored format.
            **kwargs: ``blocksize`` for ``"bsr"``.
        """
        from .conversion import to_scipy

        return to_scipy(self, format, **kwargs)

    def to_dense(self) -> Tensor:
        """Materialise as a dense tensor of shape :attr:`shape`."""
        return self.tocoo().to_dense()

    # ------------------------------------------------------- tensor handling
    def with_values(self, values: Tensor) -> "Sparse":
        """Return an array with the same pattern and new values.

        ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
        shape creates a shared-pattern batch.
        """
        raise NotImplementedError

    def _map_tensors(self, index_fn, value_fn) -> "Sparse":
        """Apply ``index_fn`` to index tensors and ``value_fn`` to values."""
        raise NotImplementedError

    def to(self, *args, **kwargs) -> "Sparse":
        """Move to a device and/or cast the values (indices stay integer)."""
        device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

        return self._map_tensors(
            lambda index: index.to(device=device),
            lambda values: values.to(device=device, dtype=dtype),
        )

    def cpu(self) -> "Sparse":
        return self.to("cpu")

    def cuda(self, device=None) -> "Sparse":
        return self.to("cuda" if device is None else device)

    def float(self) -> "Sparse":
        return self.to(torch.float32)

    def double(self) -> "Sparse":
        return self.to(torch.float64)

    def detach(self) -> "Sparse":
        return self.with_values(self._values.detach())

    # ------------------------------------------------------------- products
    def matvec(self, x: Tensor) -> Tensor:
        """Apply the operator along the last axis of ``x``.

        See :func:`btorch.sparse.matvec`.
        """
        from .ops import matvec

        return matvec(self, x)

    def rmatvec(self, x: Tensor) -> Tensor:
        """Apply the transposed operator along the last axis of ``x``."""
        from .ops import rmatvec

        return rmatvec(self, x)

    def __matmul__(self, other):
        from .ops import matmul

        return matmul(self, other)

    def __rmatmul__(self, other):
        from .ops import matmul

        return matmul(other, self)

    @property
    def T(self) -> "Sparse":
        """Transpose of the two sparse dimensions."""
        return self.transpose()

    def transpose(self) -> "Sparse":
        raise NotImplementedError

    def __repr__(self) -> str:
        parts = [f"shape={self.shape}", f"nnz={self.nnz}", f"dtype={self.dtype}"]
        if self.batch_dim():
            parts.append(f"batch_shape={self.batch_shape}")
        if self.dense_dim():
            parts.append(f"dense_shape={self.dense_shape}")
        if self.device.type != "cpu":
            parts.append(f"device={self.device}")
        return f"{type(self).__name__}({', '.join(parts)})"
Attributes
T property

Transpose of the two sparse dimensions.

nnz property

Number of stored entries (of one batch member for a shared pattern, of all members together otherwise).

shape property

Logical shape (*batch, *sparse, *dense).

Methods:
as_bsr(blocksize=None)

BSR is not a native format; always raises TypeError.

Source code in btorch/sparse/base.py
def as_bsr(self, blocksize: tuple[int, int] | None = None):
    """BSR is not a native format; always raises ``TypeError``."""
    return self._as("bsr")
as_coo()

Return self if it is stored as COO, else raise TypeError.

Source code in btorch/sparse/base.py
def as_coo(self) -> "COO":
    """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
    return self._as("coo")
as_csc()

Return self if it is stored as CSC, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csc(self) -> "CSC":
    """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
    return self._as("csc")
as_csr()

Return self if it is stored as CSR, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csr(self) -> "CSR":
    """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
    return self._as("csr")
batch_dim()

Number of batch dimensions.

Source code in btorch/sparse/base.py
def batch_dim(self) -> int:
    """Number of batch dimensions."""
    return self._batch_dim
dense_dim()

Number of dense (per-entry payload) dimensions.

Source code in btorch/sparse/base.py
def dense_dim(self) -> int:
    """Number of dense (per-entry payload) dimensions."""
    return self._dense_dim
from_scipy(array, *, device=None, dtype=None) classmethod

Convert a SciPy sparse array or matrix (see :func:btorch.sparse.from_scipy).

Source code in btorch/sparse/base.py
@classmethod
def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
    """Convert a SciPy sparse array or matrix (see
    :func:`btorch.sparse.from_scipy`)."""
    from .conversion import from_scipy

    return from_scipy(array, device=device, dtype=dtype)
from_torch(tensor, *, batch_dim=0) classmethod

Wrap a torch sparse tensor (see :func:btorch.sparse.from_torch).

Source code in btorch/sparse/base.py
@classmethod
def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
    """Wrap a ``torch`` sparse tensor (see
    :func:`btorch.sparse.from_torch`)."""
    from .conversion import from_torch

    return from_torch(tensor, batch_dim=batch_dim)
matvec(x)

Apply the operator along the last axis of x.

See :func:btorch.sparse.matvec.

Source code in btorch/sparse/base.py
def matvec(self, x: Tensor) -> Tensor:
    """Apply the operator along the last axis of ``x``.

    See :func:`btorch.sparse.matvec`.
    """
    from .ops import matvec

    return matvec(self, x)
rmatvec(x)

Apply the transposed operator along the last axis of x.

Source code in btorch/sparse/base.py
def rmatvec(self, x: Tensor) -> Tensor:
    """Apply the transposed operator along the last axis of ``x``."""
    from .ops import rmatvec

    return rmatvec(self, x)
sparse_dim()

Number of sparsely stored dimensions.

Source code in btorch/sparse/base.py
def sparse_dim(self) -> int:
    """Number of sparsely stored dimensions."""
    return self.ndim - self._batch_dim - self._dense_dim
to(*args, **kwargs)

Move to a device and/or cast the values (indices stay integer).

Source code in btorch/sparse/base.py
def to(self, *args, **kwargs) -> "Sparse":
    """Move to a device and/or cast the values (indices stay integer)."""
    device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

    return self._map_tensors(
        lambda index: index.to(device=device),
        lambda values: values.to(device=device, dtype=dtype),
    )
to_dense()

Materialise as a dense tensor of shape :attr:shape.

Source code in btorch/sparse/base.py
def to_dense(self) -> Tensor:
    """Materialise as a dense tensor of shape :attr:`shape`."""
    return self.tocoo().to_dense()
to_scipy(format=None, **kwargs)

Export as a scipy.sparse array (CPU, detached).

Parameters:

Name Type Description Default
format str | None

Any SciPy format name; defaults to the stored format.

None
**kwargs Any

blocksize for "bsr".

{}
Source code in btorch/sparse/base.py
def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
    """Export as a ``scipy.sparse`` array (CPU, detached).

    Args:
        format: Any SciPy format name; defaults to the stored format.
        **kwargs: ``blocksize`` for ``"bsr"``.
    """
    from .conversion import to_scipy

    return to_scipy(self, format, **kwargs)
to_torch(layout=None, **kwargs)

Export as a torch sparse tensor.

Parameters:

Name Type Description Default
layout str | layout | None

"coo", "csr", "csc", "bsr" or "bsc" (or the torch.sparse_* layout). Defaults to the stored format.

None
**kwargs Any

blocksize for the block layouts.

{}
Source code in btorch/sparse/base.py
def to_torch(
    self, layout: str | torch.layout | None = None, **kwargs: Any
) -> Tensor:
    """Export as a ``torch`` sparse tensor.

    Args:
        layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
            (or the ``torch.sparse_*`` layout). Defaults to the stored
            format.
        **kwargs: ``blocksize`` for the block layouts.
    """
    from .conversion import to_torch

    return to_torch(self, layout, **kwargs)
tobsr(blocksize)

Convert to BSR; not implemented as a native format.

Use to_torch(layout="bsr", blocksize=...) or to_scipy(format="bsr") to export block storage.

Source code in btorch/sparse/base.py
def tobsr(self, blocksize: tuple[int, int]):
    """Convert to BSR; not implemented as a native format.

    Use ``to_torch(layout="bsr", blocksize=...)`` or
    ``to_scipy(format="bsr")`` to export block storage.
    """
    raise NotImplementedError(
        "BSR is not a native btorch format yet; export with "
        "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
    )
tocoo()

Convert to COO (may allocate).

Source code in btorch/sparse/base.py
def tocoo(self) -> "COO":
    """Convert to COO (may allocate)."""
    raise NotImplementedError
tocsc(return_map=False)

Convert to CSC (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
    """Convert to CSC (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
tocsr(return_map=False)

Convert to CSR (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
    """Convert to CSR (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
with_values(values)

Return an array with the same pattern and new values.

values is [*batch, nnz, *dense]; a different leading batch shape creates a shared-pattern batch.

Source code in btorch/sparse/base.py
def with_values(self, values: Tensor) -> "Sparse":
    """Return an array with the same pattern and new values.

    ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
    shape creates a shared-pattern batch.
    """
    raise NotImplementedError

StructuredOperator

Bases: LinearOperator

Operator with a closed-form product and no stored matrix.

Structured operators support every apply capability and can list their entries on request (:meth:enumerate_edges / :meth:materialize), which is the only time memory proportional to the number of entries is used.

Source code in btorch/sparse/operator.py
class StructuredOperator(LinearOperator):
    """Operator with a closed-form product and no stored matrix.

    Structured operators support every apply capability and can list their
    entries on request (:meth:`enumerate_edges` / :meth:`materialize`), which
    is the only time memory proportional to the number of entries is used.
    """

    _capabilities = _ALL

SumOperator

Bases: CompositeOperator

Lazy sum A_1 + A_2 + ... of operators with the same shape.

Listing the entries concatenates the entries of the parts (coordinates present in several parts are stored several times and summed by every sparse operation), so no sparse addition is run.

Parameters:

Name Type Description Default
parts Sequence[Any]

Operators and/or sparse matrices of one shape.

required
Source code in btorch/sparse/operator.py
class SumOperator(CompositeOperator):
    """Lazy sum ``A_1 + A_2 + ...`` of operators with the same shape.

    Listing the entries concatenates the entries of the parts (coordinates
    present in several parts are stored several times and summed by every
    sparse operation), so no sparse addition is run.

    Args:
        parts: Operators and/or sparse matrices of one shape.
    """

    def __init__(self, parts: Sequence[Any]):
        flat: list[Any] = []
        for part in parts:
            # Flatten nested sums so a long chain stays one level deep.
            flat.extend(part.parts if isinstance(part, SumOperator) else [part])
        self._set_parts(flat)
        shape = tuple(self.parts[0].shape)
        for part in self.parts:
            if tuple(part.shape) != shape:
                raise ValueError(
                    "Cannot add operators of different shapes: "
                    f"{shape} and {tuple(part.shape)}."
                )
        self._shape = shape
        self._capabilities = self._common()

    def _matvec(self, x: Tensor) -> Tensor:
        out = self.parts[0].matvec(x)
        for part in self.parts[1:]:
            out = out + part.matvec(x)
        return out

    def _rmatvec(self, x: Tensor) -> Tensor:
        out = self.parts[0].rmatvec(x)
        for part in self.parts[1:]:
            out = out + part.rmatvec(x)
        return out

    def _enumerate_edges(self) -> Edges:
        edges = [_edges_of(part) for part in self.parts]
        dtype = edges[0][2].dtype
        for _, _, values in edges[1:]:
            dtype = torch.promote_types(dtype, values.dtype)
        return (
            torch.cat([e[0] for e in edges]),
            torch.cat([e[1] for e in edges]),
            torch.cat([e[2].to(dtype) for e in edges]),
        )

TransposedOperator

Bases: CompositeOperator

Lazy transpose A^T; swaps matvec and rmatvec.

Created by :attr:LinearOperator.T. Building it fails immediately (not on first use) if the operator has no "rmatvec" capability.

Parameters:

Name Type Description Default
operator Any

Operator or sparse matrix.

required
Source code in btorch/sparse/operator.py
class TransposedOperator(CompositeOperator):
    """Lazy transpose ``A^T``; swaps ``matvec`` and ``rmatvec``.

    Created by :attr:`LinearOperator.T`. Building it fails immediately (not on
    first use) if the operator has no ``"rmatvec"`` capability.

    Args:
        operator: Operator or sparse matrix.
    """

    def __init__(self, operator: Any):
        self._set_parts([operator])
        if not _supports(operator, "rmatvec"):
            operator._require("rmatvec")  # raises, naming the capability
        inner = _capabilities_of(operator)
        capabilities = {"matvec", "matmat"} | (
            inner & {"enumerate_edges", "materialize_sparse"}
        )
        if "matvec" in inner:
            capabilities.add("rmatvec")
        self._capabilities = frozenset(capabilities)
        self._shape = (operator.shape[1], operator.shape[0])

    def _matvec(self, x: Tensor) -> Tensor:
        return self.parts[0].rmatvec(x)

    def _rmatvec(self, x: Tensor) -> Tensor:
        return self.parts[0].matvec(x)

    def _enumerate_edges(self) -> Edges:
        rows, cols, values = _edges_of(self.parts[0])
        return cols, rows, values

    @property
    def T(self):
        return self.parts[0]

Functions:

as_sparse(obj, *, format=None, device=None, dtype=None, batch_dim=0)

Interpret obj as a btorch sparse array.

This is the one conversion entry point: it accepts a btorch :class:Sparse, a PyTorch sparse tensor, or a SciPy sparse array/matrix. The orientation is never changed.

Parameters:

Name Type Description Default
obj Any

Sparse object of any supported library.

required
format str | None

Optional target format ("coo", "csr" or "csc").

None
device device | str | None

Optional target device.

None
dtype dtype | None

Optional value dtype.

None
batch_dim int

Leading batch dimensions of a PyTorch COO tensor (see :func:from_torch).

0

Returns:

Name Type Description
A Sparse

class:Sparse (the same object if nothing had to change).

Raises:

Type Description
TypeError

For dense tensors, arrays and unsupported types; dense data is never sparsified implicitly.

Source code in btorch/sparse/conversion.py
def as_sparse(
    obj: Any,
    *,
    format: str | None = None,
    device: torch.device | str | None = None,
    dtype: torch.dtype | None = None,
    batch_dim: int = 0,
) -> Sparse:
    """Interpret ``obj`` as a btorch sparse array.

    This is the one conversion entry point: it accepts a btorch
    :class:`Sparse`, a PyTorch sparse tensor, or a SciPy sparse array/matrix.
    The orientation is never changed.

    Args:
        obj: Sparse object of any supported library.
        format: Optional target format (``"coo"``, ``"csr"`` or ``"csc"``).
        device: Optional target device.
        dtype: Optional value dtype.
        batch_dim: Leading batch dimensions of a PyTorch COO tensor (see
            :func:`from_torch`).

    Returns:
        A :class:`Sparse` (the same object if nothing had to change).

    Raises:
        TypeError: For dense tensors, arrays and unsupported types; dense
            data is never sparsified implicitly.
    """
    if isinstance(obj, Sparse):
        out = obj
    elif isinstance(obj, Tensor):
        out = from_torch(obj, batch_dim=batch_dim)
    elif _is_scipy_sparse(obj):
        out = from_scipy(obj)
    else:
        raise TypeError(
            f"Cannot interpret {type(obj).__name__} as a sparse array. Expected "
            "a btorch Sparse, a torch sparse tensor or a SciPy sparse array."
        )
    if device is not None or dtype is not None:
        out = out.to(device=device, dtype=dtype)
    if format is not None and out.format != format:
        if format not in ("coo", "csr", "csc"):
            raise ValueError(
                f"Unknown or non-native sparse format {format!r}; native formats "
                "are 'coo', 'csr' and 'csc'."
            )
        out = getattr(out, f"to{format}")()
    return out

csc(ccol_indices, row_indices, values, shape, *, dense_dim=0)

Create a CSC array; see :class:CSC.

Source code in btorch/sparse/__init__.py
def csc(
    ccol_indices: Tensor,
    row_indices: Tensor,
    values: Tensor,
    shape: Sequence[int],
    *,
    dense_dim: int = 0,
) -> CSC:
    """Create a CSC array; see :class:`CSC`."""
    return CSC(ccol_indices, row_indices, values, tuple(shape), dense_dim=dense_dim)

explain(connection, x=None)

Describe how a connection is executed (debugging aid).

Reports the input representation, the canonical state, and the representation, algorithm and backend the runtime selected. Model code must not depend on the content.

Parameters:

Name Type Description Default
connection Connection

A connection module such as :class:~btorch.models.connection.SparseConnection.

required
x Tensor | None

Optional example input.

None
Source code in btorch/sparse/__init__.py
def explain(connection: "Connection", x: Tensor | None = None) -> str:
    """Describe how a connection is executed (debugging aid).

    Reports the input representation, the canonical state, and the
    representation, algorithm and backend the runtime selected. Model code
    must not depend on the content.

    Args:
        connection: A connection module such as
            :class:`~btorch.models.connection.SparseConnection`.
        x: Optional example input.
    """
    return connection.explain(x)

from_dense(tensor)

Build a COO array from the non-zero entries of a dense tensor.

Every dimension becomes a sparse dimension. Values stay connected to tensor for autograd.

Source code in btorch/sparse/conversion.py
def from_dense(tensor: Tensor) -> COO:
    """Build a COO array from the non-zero entries of a dense tensor.

    Every dimension becomes a sparse dimension. Values stay connected to
    ``tensor`` for autograd.
    """
    if tensor.layout != torch.strided:
        raise TypeError("from_dense expects a dense tensor.")
    indices = tensor.nonzero().T
    return COO(
        indices,
        tensor[tuple(indices)],
        tuple(tensor.shape),
        properties=Properties(sorted=True, unique=True),
        check=False,
    )

from_edges(rows, cols, values, shape, *, dense_dim=0)

Create a sparse matrix from row and column coordinates.

The result is format-agnostic: use tocsr() / tocoo() to request a specific format.

Parameters:

Name Type Description Default
rows Tensor

[nnz] row of each entry.

required
cols Tensor

[nnz] column of each entry.

required
values Tensor

[*batch, nnz, *dense] values.

required
shape Sequence[int]

(*batch, M, N, *dense).

required
dense_dim int

Number of trailing dense dimensions of each entry.

0
Source code in btorch/sparse/__init__.py
def from_edges(
    rows: Tensor,
    cols: Tensor,
    values: Tensor,
    shape: Sequence[int],
    *,
    dense_dim: int = 0,
) -> Sparse:
    """Create a sparse matrix from row and column coordinates.

    The result is format-agnostic: use ``tocsr()`` / ``tocoo()`` to request a
    specific format.

    Args:
        rows: ``[nnz]`` row of each entry.
        cols: ``[nnz]`` column of each entry.
        values: ``[*batch, nnz, *dense]`` values.
        shape: ``(*batch, M, N, *dense)``.
        dense_dim: Number of trailing dense dimensions of each entry.
    """
    import torch

    rows = torch.as_tensor(rows)
    cols = torch.as_tensor(cols, device=rows.device)
    return COO(torch.stack([rows, cols]), values, tuple(shape), dense_dim=dense_dim)

from_scipy(array, *, device=None, dtype=None)

Convert a SciPy sparse array or matrix.

Both scipy.sparse.sparray and the legacy spmatrix are accepted. COO, CSR and CSC keep their format (including unsorted indices and duplicate entries, exactly as stored); every other format (BSR, LIL, DOK, DIA) is converted through COO. The data is copied from CPU memory.

Parameters:

Name Type Description Default
array Any

SciPy sparse array or matrix.

required
device device | str | None

Target device (default CPU).

None
dtype dtype | None

Value dtype (default: the array's dtype).

None

Returns:

Type Description
Sparse

COO, CSR or CSC with shape == array.shape.

Raises:

Type Description
TypeError

If array is not a SciPy sparse object.

Source code in btorch/sparse/conversion.py
def from_scipy(
    array: Any,
    *,
    device: torch.device | str | None = None,
    dtype: torch.dtype | None = None,
) -> Sparse:
    """Convert a SciPy sparse array or matrix.

    Both ``scipy.sparse.sparray`` and the legacy ``spmatrix`` are accepted.
    COO, CSR and CSC keep their format (including unsorted indices and
    duplicate entries, exactly as stored); every other format (BSR, LIL, DOK,
    DIA) is converted through COO. The data is copied from CPU memory.

    Args:
        array: SciPy sparse array or matrix.
        device: Target device (default CPU).
        dtype: Value dtype (default: the array's dtype).

    Returns:
        ``COO``, ``CSR`` or ``CSC`` with ``shape == array.shape``.

    Raises:
        TypeError: If ``array`` is not a SciPy sparse object.
    """
    if not _is_scipy_sparse(array):
        raise TypeError(f"from_scipy expects a SciPy sparse array, got {type(array)}.")
    fmt = array.format
    if fmt not in ("coo", "csr", "csc"):
        array = array.tocoo()
        fmt = "coo"
    shape = tuple(int(s) for s in array.shape)
    if len(shape) != 2:
        raise NotImplementedError("Only 2-D SciPy sparse arrays are supported.")

    # Copies: the result must never alias (and later mutate) the caller's data.
    def index(a) -> Tensor:
        return torch.tensor(np.asarray(a, dtype=np.int64), device=device)

    values = torch.tensor(np.asarray(array.data), device=device)
    if dtype is not None:
        values = values.to(dtype)
    if fmt == "coo":
        indices = torch.stack([index(array.row), index(array.col)])
        # SciPy's ``has_canonical_format`` flag is not reliable (a DOK array
        # converted with ``tocoo()`` sets it for insertion-ordered entries),
        # so sortedness is verified here, once, in O(nnz).
        key = indices[0] * shape[1] + indices[1]
        canonical = bool((key[1:] > key[:-1]).all())
        return COO(
            indices,
            values,
            shape,
            properties=Properties(sorted=canonical, unique=canonical),
            check=False,
        )
    cls = CSR if fmt == "csr" else CSC
    unique = bool(array.has_canonical_format)
    return cls(
        index(array.indptr),
        index(array.indices),
        values,
        shape,
        properties=Properties(sorted=bool(array.has_sorted_indices), unique=unique),
        check=False,
    )

from_torch(tensor, *, batch_dim=0)

Wrap a PyTorch sparse tensor without copying or transposing.

COO, CSR and CSC keep their format. BSR and BSC are converted through COO, which is lossless. Values keep their autograd history, so gradients flow back to the tensor the sparse tensor was built from.

An uncoalesced COO tensor keeps its entries as stored (order and duplicates), unless it requires grad: PyTorch only exposes the values of an uncoalesced tensor to autograd after coalescing, so it is coalesced then. A batched CSR/CSC tensor whose members have different patterns becomes a batched COO.

Parameters:

Name Type Description Default
tensor Tensor

Tensor with a sparse layout.

required
batch_dim int

For a COO tensor, how many leading sparse dimensions are batch coordinates. PyTorch COO has no notion of a batch, so a tensor of shape (G, M, N) is read as a 3-D sparse array unless batch_dim=1 says it is G matrices.

0

Returns:

Type Description
Sparse

COO, CSR or CSC with shape == tensor.shape.

Raises:

Type Description
TypeError

If tensor is not sparse.

Source code in btorch/sparse/conversion.py
def from_torch(tensor: Tensor, *, batch_dim: int = 0) -> Sparse:
    """Wrap a PyTorch sparse tensor without copying or transposing.

    COO, CSR and CSC keep their format. BSR and BSC are converted through
    COO, which is lossless. Values keep their autograd history, so gradients
    flow back to the tensor the sparse tensor was built from.

    An uncoalesced COO tensor keeps its entries as stored (order and
    duplicates), unless it requires grad: PyTorch only exposes the values of
    an uncoalesced tensor to autograd after coalescing, so it is coalesced
    then. A batched CSR/CSC tensor whose members have different patterns
    becomes a batched COO.

    Args:
        tensor: Tensor with a sparse layout.
        batch_dim: For a COO tensor, how many leading sparse dimensions are
            batch coordinates. PyTorch COO has no notion of a batch, so a
            tensor of shape ``(G, M, N)`` is read as a 3-D sparse array
            unless ``batch_dim=1`` says it is ``G`` matrices.

    Returns:
        ``COO``, ``CSR`` or ``CSC`` with ``shape == tensor.shape``.

    Raises:
        TypeError: If ``tensor`` is not sparse.
    """
    if not isinstance(tensor, Tensor) or tensor.layout == torch.strided:
        raise TypeError(
            "from_torch expects a torch sparse tensor; dense tensors are never "
            "sparsified implicitly (use sparse.from_dense)."
        )
    shape = tuple(tensor.shape)
    layout = tensor.layout
    if layout in (torch.sparse_bsr, torch.sparse_bsc):
        tensor = tensor.to_sparse(layout=torch.sparse_coo)
        layout = torch.sparse_coo
    if layout == torch.sparse_coo:
        reordered = False
        if tensor.is_coalesced():
            indices, values = tensor.indices(), tensor.values()
            canonical = True
        elif tensor.requires_grad:
            # PyTorch only exposes the values of an uncoalesced tensor to
            # autograd after coalescing, which merges and reorders entries.
            tensor = tensor.coalesce()
            indices, values = tensor.indices(), tensor.values()
            canonical = reordered = True
        else:
            # Keep the entries exactly as stored (order and duplicates), so
            # arrays aligned with them stay aligned.
            indices, values = tensor._indices(), tensor._values()
            canonical = False
        out = COO(
            indices,
            values,
            shape,
            batch_dim=batch_dim,
            dense_dim=tensor.dense_dim(),
            properties=Properties(sorted=canonical, unique=canonical),
            check=False,
        )
        out._reordered = reordered
        return out
    if batch_dim:
        raise ValueError(
            "batch_dim applies to COO tensors; batched CSR/CSC tensors carry "
            "their batch dimensions themselves."
        )
    if layout == torch.sparse_csr:
        pointer, minor, cls = tensor.crow_indices(), tensor.col_indices(), CSR
    elif layout == torch.sparse_csc:
        pointer, minor, cls = tensor.ccol_indices(), tensor.row_indices(), CSC
    else:
        raise TypeError(f"Unsupported torch sparse layout {layout}.")
    if pointer.ndim > 1:
        # Batched compressed tensor: keep the compressed format when the
        # members share a pattern, otherwise fall back to batched COO.
        n_batch = pointer.ndim - 1
        flat_p = pointer.reshape(-1, pointer.shape[-1])
        flat_m = minor.reshape(-1, minor.shape[-1])
        if bool((flat_p == flat_p[0]).all()) and bool((flat_m == flat_m[0]).all()):
            pointer, minor = flat_p[0], flat_m[0]
        else:
            coo = tensor.to_sparse(layout=torch.sparse_coo).coalesce()
            return COO(
                coo.indices(),
                coo.values(),
                shape,
                batch_dim=n_batch,
                dense_dim=coo.dense_dim(),
                properties=Properties(sorted=True, unique=True),
                check=False,
            )
    # PyTorch does not guarantee sorted or unique indices within a row of a
    # compressed tensor, so nothing is claimed about them.
    return cls(
        pointer,
        minor,
        tensor.values(),
        shape,
        dense_dim=tensor.dense_dim(),
        check=False,
    )

is_linear_operator(obj)

Whether obj can be used as a linear operator here.

True for a :class:LinearOperator and for anything that looks like one (a 2-D shape with matvec and rmatvec), which is how a :class:~btorch.sparse.Sparse matrix is accepted without inheriting from :class:LinearOperator. Dense tensors are data, not operators.

Source code in btorch/sparse/operator.py
def is_linear_operator(obj: Any) -> bool:
    """Whether ``obj`` can be used as a linear operator here.

    True for a :class:`LinearOperator` and for anything that looks like one
    (a 2-D ``shape`` with ``matvec`` and ``rmatvec``), which is how a
    :class:`~btorch.sparse.Sparse` matrix is accepted without inheriting from
    :class:`LinearOperator`. Dense tensors are data, not operators.
    """
    if isinstance(obj, LinearOperator):
        return True
    if isinstance(obj, Tensor):
        return False
    return (
        callable(getattr(obj, "matvec", None))
        and callable(getattr(obj, "rmatvec", None))
        and hasattr(obj, "shape")
    )

matmul(a, b)

Matrix product with one sparse operand; the function behind @.

Shapes follow :func:torch.matmul:

  • A @ x with 1-D x of length N returns length M.
  • A @ X with X.shape == (..., N, K) returns (..., M, K).
  • x @ A with 1-D x of length M returns length N.
  • X @ A with X.shape == (..., K, M) returns (..., K, N).

Batch dimensions of the sparse operand broadcast with the leading dimensions of the dense operand as in torch.matmul. To apply a matrix to a stack of vectors [..., N] use :func:matvec.

Parameters:

Name Type Description Default
a Any

Left operand (sparse array or dense tensor).

required
b Any

Right operand (dense tensor or sparse array).

required

Returns:

Type Description
Tensor

Dense tensor.

Source code in btorch/sparse/ops.py
def matmul(a: Any, b: Any) -> Tensor:
    """Matrix product with one sparse operand; the function behind ``@``.

    Shapes follow :func:`torch.matmul`:

    - ``A @ x`` with 1-D ``x`` of length ``N`` returns length ``M``.
    - ``A @ X`` with ``X.shape == (..., N, K)`` returns ``(..., M, K)``.
    - ``x @ A`` with 1-D ``x`` of length ``M`` returns length ``N``.
    - ``X @ A`` with ``X.shape == (..., K, M)`` returns ``(..., K, N)``.

    Batch dimensions of the sparse operand broadcast with the leading
    dimensions of the dense operand as in ``torch.matmul``. To apply a matrix
    to a stack of vectors ``[..., N]`` use :func:`matvec`.

    Args:
        a: Left operand (sparse array or dense tensor).
        b: Right operand (dense tensor or sparse array).

    Returns:
        Dense tensor.
    """
    # Non-sparse linear operators implement the product themselves.
    for operand, method in ((a, "__matmul__"), (b, "__rmatmul__")):
        if not isinstance(operand, (Sparse, Tensor)) and hasattr(operand, "matvec"):
            other = b if operand is a else a
            return getattr(operand, method)(other)
    a_sparse, b_sparse = isinstance(a, Sparse), isinstance(b, Sparse)
    if a_sparse and b_sparse:
        raise NotImplementedError(
            "sparse @ sparse (operator composition / SpGEMM) is not implemented."
        )
    if a_sparse:
        if not isinstance(b, Tensor):
            return NotImplemented
        if a.dense_dim() and b.ndim > 1:
            raise NotImplementedError(
                "A @ X with a matrix right-hand side is not defined for arrays "
                "with dense entry dimensions; use matvec or sparse.einsum."
            )
        if b.ndim == 1:
            if a.batch_dim():
                b = b.reshape(*(1,) * a.batch_dim(), -1)
            return _matvec(a, b, transpose=False)
        return _matmat(a, b.mT, transpose=False).mT
    if b_sparse:
        if not isinstance(a, Tensor):
            return NotImplemented
        if b.dense_dim() and a.ndim > 1:
            raise NotImplementedError(
                "X @ A with a matrix left-hand side is not defined for arrays "
                "with dense entry dimensions; use rmatvec or sparse.einsum."
            )
        if a.ndim == 1:
            if b.batch_dim():
                a = a.reshape(*(1,) * b.batch_dim(), -1)
            return _matvec(b, a, transpose=True)
        return _matmat(b, a, transpose=True)
    return torch.matmul(a, b)

matvec(A, x)

Apply a sparse matrix along the last axis of a dense tensor.

For A.shape == (*batch, M, N, *dense) and x.shape == (*batch, ..., N) the result has shape (*batch, ..., M, *dense):

.. math:: y_{\ldots m} = \sum_n A_{m n}\, x_{\ldots n}

Any number of leading dimensions of x is treated as independent samples. If A has batch dimensions they align with the leading dimensions of x and broadcast (size 1 in x broadcasts); they are never combined with the sample dimensions implicitly.

Parameters:

Name Type Description Default
A Sparse

Sparse array with two sparse dimensions.

required
x Tensor

Dense tensor whose last dimension is N.

required

Returns:

Type Description
Tensor

Dense tensor.

Raises:

Type Description
ValueError

On a shape mismatch, or if x has fewer leading dimensions than A has batch dimensions.

Source code in btorch/sparse/ops.py
def matvec(A: Sparse, x: Tensor) -> Tensor:
    """Apply a sparse matrix along the last axis of a dense tensor.

    For ``A.shape == (*batch, M, N, *dense)`` and ``x.shape == (*batch, ...,
    N)`` the result has shape ``(*batch, ..., M, *dense)``:

    .. math::
        y_{\\ldots m} = \\sum_n A_{m n}\\, x_{\\ldots n}

    Any number of leading dimensions of ``x`` is treated as independent
    samples. If ``A`` has batch dimensions they align with the *leading*
    dimensions of ``x`` and broadcast (size 1 in ``x`` broadcasts); they are
    never combined with the sample dimensions implicitly.

    Args:
        A: Sparse array with two sparse dimensions.
        x: Dense tensor whose last dimension is ``N``.

    Returns:
        Dense tensor.

    Raises:
        ValueError: On a shape mismatch, or if ``x`` has fewer leading
            dimensions than ``A`` has batch dimensions.
    """
    if not isinstance(A, Sparse):
        return A.matvec(x)
    return _matvec(A, x, transpose=False)

rmatvec(A, x)

Apply the transpose of a sparse matrix along the last axis of x.

rmatvec(A, x) equals matvec(A.T, x) (and x @ A for 1-D x) without building the transpose. x has shape (*batch, ..., M) and the result (*batch, ..., N, *dense).

Source code in btorch/sparse/ops.py
def rmatvec(A: Sparse, x: Tensor) -> Tensor:
    """Apply the transpose of a sparse matrix along the last axis of ``x``.

    ``rmatvec(A, x)`` equals ``matvec(A.T, x)`` (and ``x @ A`` for 1-D ``x``)
    without building the transpose. ``x`` has shape ``(*batch, ..., M)`` and
    the result ``(*batch, ..., N, *dense)``.
    """
    if not isinstance(A, Sparse):
        return A.rmatvec(x)
    return _matvec(A, x, transpose=True)

stack(arrays)

Stack sparse arrays along a new leading batch dimension.

The members must have the same shape. If they all store the same sparsity pattern the result shares it (indices stored once, values [G, nnz]) and keeps the format of the first member. Otherwise the members may have different numbers of entries; the result is a batched COO that stores sum(nnz) entries without padding.

Parameters:

Name Type Description Default
arrays Sequence[Sparse]

Sparse arrays of identical shape.

required

Returns:

Type Description
Sparse

Sparse array of shape (len(arrays), *shape).

Examples:

>>> A = sparse.stack([A0, A1, A2])
>>> A.batch_shape
(3,)
>>> y = A.matvec(x)                      # x: [3, B, N] -> [3, B, M]
Source code in btorch/sparse/ops.py
def stack(arrays: Sequence[Sparse]) -> Sparse:
    """Stack sparse arrays along a new leading batch dimension.

    The members must have the same shape. If they all store the same sparsity
    pattern the result shares it (indices stored once, values ``[G, nnz]``)
    and keeps the format of the first member. Otherwise the members may have
    different numbers of entries; the result is a batched COO that stores
    ``sum(nnz)`` entries without padding.

    Args:
        arrays: Sparse arrays of identical shape.

    Returns:
        Sparse array of shape ``(len(arrays), *shape)``.

    Examples:
        >>> A = sparse.stack([A0, A1, A2])       # doctest: +SKIP
        >>> A.batch_shape
        (3,)
        >>> y = A.matvec(x)                      # x: [3, B, N] -> [3, B, M]
    """
    arrays = list(arrays)
    if not arrays:
        raise ValueError("stack needs at least one sparse array.")
    first = arrays[0]
    for a in arrays:
        if not isinstance(a, Sparse):
            raise TypeError(f"stack expects sparse arrays, got {type(a).__name__}.")
        if a.shape != first.shape or a.dense_dim() != first.dense_dim():
            raise ValueError(
                f"All stacked arrays need the same shape, got {a.shape} and "
                f"{first.shape}."
            )
        if a.batch_dim():
            raise NotImplementedError("Stacking already batched arrays.")

    same_pattern = all(a.format == first.format for a in arrays) and all(
        _same_pattern(first, a) for a in arrays[1:]
    )
    if same_pattern:
        return first.with_values(torch.stack([a._values for a in arrays]))

    coos = [a.tocoo() for a in arrays]
    indices = torch.cat(
        [
            torch.cat([torch.full_like(c._indices[:1], g), c._indices])
            for g, c in enumerate(coos)
        ],
        dim=1,
    )
    values = torch.cat([c._values for c in coos])
    canonical = all(c.properties.canonical for c in coos)
    return COO(
        indices,
        values,
        (len(coos), *first.shape),
        batch_dim=1,
        dense_dim=first.dense_dim(),
        properties=Properties(sorted=canonical, unique=canonical),
        check=False,
    )

btorch.sparse.base

Format-agnostic sparse array.

Classes

COO

Bases: Sparse

Coordinate format: one index tuple and one value per stored entry.

COO supports any number of sparse dimensions. Entries may be unsorted and may contain duplicates; duplicates are summed by every operation, as in SciPy and PyTorch.

Two kinds of batch are supported and may be combined:

  • Shared pattern: values has leading batch dimensions, [*batch, nnz, *dense], and every batch member uses the same indices.
  • Different patterns: the first index rows are batch coordinates, so each batch member can have its own number of entries. Build these with :func:btorch.sparse.stack.

Parameters:

Name Type Description Default
indices Tensor

[n_index, nnz] integer coordinates. The rows are the batch coordinates (if any) followed by the sparse coordinates.

required
values Tensor

[*value_batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, *sparse, *dense).

required
batch_dim int | None

Total number of batch dimensions. Defaults to the number of leading value dimensions (a shared pattern).

None
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties of the given indices.

None
hints Hints | None

Performance expectations.

None
check bool

Validate index bounds.

True

Examples:

>>> import torch
>>> from btorch import sparse
>>> A = sparse.coo(torch.tensor([[0, 1], [2, 0]]),
...                torch.tensor([3.0, 5.0]), shape=(2, 3))
>>> A @ torch.tensor([1.0, 0.0, 2.0])
tensor([6., 5.])
Source code in btorch/sparse/coo.py
class COO(Sparse):
    """Coordinate format: one index tuple and one value per stored entry.

    COO supports any number of sparse dimensions. Entries may be unsorted and
    may contain duplicates; duplicates are summed by every operation, as in
    SciPy and PyTorch.

    Two kinds of batch are supported and may be combined:

    - *Shared pattern*: ``values`` has leading batch dimensions,
      ``[*batch, nnz, *dense]``, and every batch member uses the same indices.
    - *Different patterns*: the first index rows are batch coordinates, so each
      batch member can have its own number of entries. Build these with
      :func:`btorch.sparse.stack`.

    Args:
        indices: ``[n_index, nnz]`` integer coordinates. The rows are the
            batch coordinates (if any) followed by the sparse coordinates.
        values: ``[*value_batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, *sparse, *dense)``.
        batch_dim: Total number of batch dimensions. Defaults to the number
            of leading value dimensions (a shared pattern).
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties of the given indices.
        hints: Performance expectations.
        check: Validate index bounds.

    Examples:
        >>> import torch
        >>> from btorch import sparse
        >>> A = sparse.coo(torch.tensor([[0, 1], [2, 0]]),
        ...                torch.tensor([3.0, 5.0]), shape=(2, 3))
        >>> A @ torch.tensor([1.0, 0.0, 2.0])
        tensor([6., 5.])
    """

    format = "coo"

    def __init__(
        self,
        indices: Tensor,
        values: Tensor,
        shape: tuple[int, ...],
        *,
        batch_dim: int | None = None,
        dense_dim: int = 0,
        properties: Properties | None = None,
        hints: Hints | None = None,
        check: bool = True,
    ):
        values = _as_tensor(values)
        indices = _check_index("indices", _as_tensor(indices, device=values.device))
        shape = tuple(int(s) for s in shape)
        if indices.ndim != 2:
            raise ValueError(f"indices must be [n_index, nnz], got {indices.shape}.")
        n_index, nnz = indices.shape
        value_batch_dim = values.ndim - 1 - dense_dim
        if value_batch_dim < 0:
            raise ValueError(
                f"values with shape {tuple(values.shape)} cannot hold "
                f"{dense_dim} dense dimension(s) per entry."
            )
        if batch_dim is None:
            batch_dim = value_batch_dim
        index_batch_dim = batch_dim - value_batch_dim
        if index_batch_dim < 0:
            raise ValueError("batch_dim is smaller than the batch of `values`.")
        if len(shape) != value_batch_dim + n_index + dense_dim:
            raise ValueError(
                f"shape {shape} has {len(shape)} dimensions but indices/values "
                f"describe {value_batch_dim} value-batch + {n_index} indexed + "
                f"{dense_dim} dense."
            )
        if n_index - index_batch_dim < 1:
            raise ValueError("COO needs at least one sparse dimension.")
        if values.shape[value_batch_dim] != nnz:
            raise ValueError(
                f"values has {values.shape[value_batch_dim]} entries along its "
                f"entry axis but indices has {nnz}."
            )
        expected = (
            shape[:value_batch_dim] + (nnz,) + shape[len(shape) - dense_dim :]
            if dense_dim
            else shape[:value_batch_dim] + (nnz,)
        )
        if tuple(values.shape) != expected:
            raise ValueError(
                f"values has shape {tuple(values.shape)}, expected {expected}."
            )
        indexed = shape[value_batch_dim : value_batch_dim + n_index]
        if check and nnz > 0:
            lo = indices.amin(dim=1)
            hi = indices.amax(dim=1)
            for d, size in enumerate(indexed):
                if int(lo[d]) < 0 or int(hi[d]) >= size:
                    raise ValueError(
                        f"indices along indexed dimension {d} must be in "
                        f"[0, {size}), got range [{int(lo[d])}, {int(hi[d])}]."
                    )
        self._indices = indices
        self._values = values
        self._shape = shape
        self._batch_dim = batch_dim
        self._dense_dim = dense_dim
        self._value_batch_dim = value_batch_dim
        self.properties = properties or Properties()
        if self.properties.shared_pattern != bool(value_batch_dim):
            self.properties = self.properties.replace(
                shared_pattern=bool(value_batch_dim)
            )
        self.hints = hints or Hints()

    # ----------------------------------------------------------- accessors
    @property
    def nnz(self) -> int:
        return int(self._indices.shape[1])

    def indices(self) -> Tensor:
        """``[n_index, nnz]`` coordinates (PyTorch name)."""
        return self._indices

    def values(self) -> Tensor:
        """``[*value_batch, nnz, *dense]`` stored values (PyTorch name)."""
        return self._values

    @property
    def data(self) -> Tensor:
        """Stored values (SciPy name)."""
        return self._values

    @property
    def row(self) -> Tensor:
        """Row coordinate of each entry (two sparse dimensions only)."""
        self._require_matrix("row")
        return self._indices[-2]

    @property
    def col(self) -> Tensor:
        """Column coordinate of each entry (two sparse dimensions only)."""
        self._require_matrix("col")
        return self._indices[-1]

    def _require_matrix(self, what: str) -> None:
        if self.sparse_dim() != 2:
            raise ValueError(
                f"{what} needs exactly two sparse dimensions, this array has "
                f"{self.sparse_dim()}."
            )

    @property
    def _index_batch_dim(self) -> int:
        return self._batch_dim - self._value_batch_dim

    @property
    def _indexed_shape(self) -> tuple[int, ...]:
        """Sizes of the indexed (batch-coordinate + sparse) dimensions."""
        start = self._value_batch_dim
        return self._shape[start : start + self._indices.shape[0]]

    def _edge_index(self) -> tuple[Tensor | None, Tensor, Tensor]:
        """``(batch coordinates or None, row, col)`` for matrix products."""
        self._require_matrix("A matrix product")
        n_ib = self._index_batch_dim
        lead = self._indices[:n_ib] if n_ib else None
        return lead, self._indices[-2], self._indices[-1]

    # --------------------------------------------------------- construction
    def _like(self, indices: Tensor, values: Tensor, **changes) -> "COO":
        out = COO.__new__(COO)
        out.__dict__.update(self.__dict__)
        out._indices = indices
        out._values = values
        for key, value in changes.items():
            setattr(out, key, value)
        return out

    def with_values(self, values: Tensor) -> "COO":
        value_batch_dim = values.ndim - 1 - self._dense_dim
        tail = self._shape[self._value_batch_dim :]
        return COO(
            self._indices,
            values,
            tuple(values.shape[:value_batch_dim]) + tail,
            batch_dim=value_batch_dim + self._index_batch_dim,
            dense_dim=self._dense_dim,
            properties=self.properties,
            hints=self.hints,
            check=False,
        )

    def _map_tensors(self, index_fn, value_fn) -> "COO":
        return self._like(index_fn(self._indices), value_fn(self._values))

    # -------------------------------------------------------- canonical form
    def coalesce(self, return_map: bool = False) -> "COO" | tuple["COO", EdgeMap]:
        """Sort entries row-major and sum duplicates.

        Args:
            return_map: Also return the :class:`EdgeMap` from the old entries
                to the new ones, to move edge-aligned metadata consistently.

        Returns:
            The canonical COO, and the map if requested. The values of merged
            entries are summed, so gradients flow to every duplicate.
        """
        nnz = self.nnz
        if self.properties.canonical:
            edge_map = EdgeMap.identity(nnz, self._indices.device)
            return (self, edge_map) if return_map else self
        sizes = self._indexed_shape
        key = _ravel(self._indices, sizes)
        if self.properties.sorted:
            order = None
            sorted_key = key
        else:
            sorted_key, order = torch.sort(key, stable=True)
        unique_key, inverse = torch.unique_consecutive(sorted_key, return_inverse=True)
        if order is None:
            target = inverse
        else:
            target = torch.empty_like(inverse)
            target[order] = inverse
        edge_map = EdgeMap(target, int(unique_key.shape[0]))
        out = self._like(
            _unravel(unique_key, sizes),
            edge_map.sum(self._values, dim=self._value_batch_dim),
            properties=self.properties.replace(sorted=True, unique=True),
        )
        return (out, edge_map) if return_map else out

    def sum_duplicates(self) -> "COO":
        """SciPy-style alias of :meth:`coalesce` (returns a new array)."""
        return self.coalesce()

    # -------------------------------------------------------------- formats
    def tocoo(self) -> "COO":
        return self

    def _compressed(self, return_map: bool):
        """Canonical entries, their row pointers and the edge map."""
        self._require_matrix("CSR/CSC conversion")
        if self._index_batch_dim:
            raise NotImplementedError(
                "A batch of different sparsity patterns is stored as batched "
                "COO; compressed (CSR/CSC) storage for it is not implemented."
            )
        coo, edge_map = self.coalesce(return_map=True)
        n_rows = coo.sparse_shape[0]
        counts = torch.bincount(coo._indices[0], minlength=n_rows)
        pointer = torch.zeros(n_rows + 1, dtype=torch.long, device=counts.device)
        pointer[1:] = torch.cumsum(counts, 0)
        return coo, pointer, edge_map

    def tocsr(self, return_map: bool = False):
        """Convert to canonical CSR (sorted, duplicates summed).

        Args:
            return_map: Also return the :class:`EdgeMap` from the COO entries
                to the CSR entries.
        """
        from .csr import CSR

        coo, crow, edge_map = self._compressed(return_map)
        out = CSR(
            crow,
            coo._indices[1],
            coo._values,
            coo._shape,
            dense_dim=self._dense_dim,
            properties=coo.properties,
            hints=self.hints,
            check=False,
        )
        return (out, edge_map) if return_map else out

    def tocsc(self, return_map: bool = False):
        """Convert to canonical CSC (column-major, duplicates summed)."""
        result = self.transpose().tocsr(return_map)
        if return_map:
            return result[0].transpose(), result[1]
        return result.transpose()

    def transpose(self) -> "COO":
        self._require_matrix("transpose")
        idx = self._indices
        swapped = torch.cat([idx[:-2], idx[-1:], idx[-2:-1]])
        shape = list(self._shape)
        i = self._batch_dim
        shape[i], shape[i + 1] = shape[i + 1], shape[i]
        return self._like(
            swapped,
            self._values,
            _shape=tuple(shape),
            properties=self.properties.replace(sorted=False, triangular=None),
        )

    def to_dense(self) -> Tensor:
        n_vb = self._value_batch_dim
        sizes = self._indexed_shape
        dense = (
            self._shape[len(self._shape) - self._dense_dim :] if self._dense_dim else ()
        )
        key = _ravel(self._indices, sizes)
        flat = self._values.new_zeros(*self._shape[:n_vb], math.prod(sizes), *dense)
        flat = flat.index_add(n_vb, key, self._values)
        return flat.reshape(self._shape)
Attributes
col property

Column coordinate of each entry (two sparse dimensions only).

data property

Stored values (SciPy name).

row property

Row coordinate of each entry (two sparse dimensions only).

Methods:
coalesce(return_map=False)

Sort entries row-major and sum duplicates.

Parameters:

Name Type Description Default
return_map bool

Also return the :class:EdgeMap from the old entries to the new ones, to move edge-aligned metadata consistently.

False

Returns:

Type Description
'COO' | tuple['COO', EdgeMap]

The canonical COO, and the map if requested. The values of merged

'COO' | tuple['COO', EdgeMap]

entries are summed, so gradients flow to every duplicate.

Source code in btorch/sparse/coo.py
def coalesce(self, return_map: bool = False) -> "COO" | tuple["COO", EdgeMap]:
    """Sort entries row-major and sum duplicates.

    Args:
        return_map: Also return the :class:`EdgeMap` from the old entries
            to the new ones, to move edge-aligned metadata consistently.

    Returns:
        The canonical COO, and the map if requested. The values of merged
        entries are summed, so gradients flow to every duplicate.
    """
    nnz = self.nnz
    if self.properties.canonical:
        edge_map = EdgeMap.identity(nnz, self._indices.device)
        return (self, edge_map) if return_map else self
    sizes = self._indexed_shape
    key = _ravel(self._indices, sizes)
    if self.properties.sorted:
        order = None
        sorted_key = key
    else:
        sorted_key, order = torch.sort(key, stable=True)
    unique_key, inverse = torch.unique_consecutive(sorted_key, return_inverse=True)
    if order is None:
        target = inverse
    else:
        target = torch.empty_like(inverse)
        target[order] = inverse
    edge_map = EdgeMap(target, int(unique_key.shape[0]))
    out = self._like(
        _unravel(unique_key, sizes),
        edge_map.sum(self._values, dim=self._value_batch_dim),
        properties=self.properties.replace(sorted=True, unique=True),
    )
    return (out, edge_map) if return_map else out
indices()

[n_index, nnz] coordinates (PyTorch name).

Source code in btorch/sparse/coo.py
def indices(self) -> Tensor:
    """``[n_index, nnz]`` coordinates (PyTorch name)."""
    return self._indices
sum_duplicates()

SciPy-style alias of :meth:coalesce (returns a new array).

Source code in btorch/sparse/coo.py
def sum_duplicates(self) -> "COO":
    """SciPy-style alias of :meth:`coalesce` (returns a new array)."""
    return self.coalesce()
tocsc(return_map=False)

Convert to canonical CSC (column-major, duplicates summed).

Source code in btorch/sparse/coo.py
def tocsc(self, return_map: bool = False):
    """Convert to canonical CSC (column-major, duplicates summed)."""
    result = self.transpose().tocsr(return_map)
    if return_map:
        return result[0].transpose(), result[1]
    return result.transpose()
tocsr(return_map=False)

Convert to canonical CSR (sorted, duplicates summed).

Parameters:

Name Type Description Default
return_map bool

Also return the :class:EdgeMap from the COO entries to the CSR entries.

False
Source code in btorch/sparse/coo.py
def tocsr(self, return_map: bool = False):
    """Convert to canonical CSR (sorted, duplicates summed).

    Args:
        return_map: Also return the :class:`EdgeMap` from the COO entries
            to the CSR entries.
    """
    from .csr import CSR

    coo, crow, edge_map = self._compressed(return_map)
    out = CSR(
        crow,
        coo._indices[1],
        coo._values,
        coo._shape,
        dense_dim=self._dense_dim,
        properties=coo.properties,
        hints=self.hints,
        check=False,
    )
    return (out, edge_map) if return_map else out
values()

[*value_batch, nnz, *dense] stored values (PyTorch name).

Source code in btorch/sparse/coo.py
def values(self) -> Tensor:
    """``[*value_batch, nnz, *dense]`` stored values (PyTorch name)."""
    return self._values

CSC

Bases: _Compressed

Compressed sparse column format (exactly two sparse dimensions).

Parameters:

Name Type Description Default
pointer Tensor

[n_cols + 1] column pointers (ccol_indices).

required
minor Tensor

[nnz] row of each entry (row_indices).

required
values Tensor

[*batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, n_rows, n_cols, *dense).

required
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties (sorted refers to column-major order).

None
hints Hints | None

Performance expectations.

None
check bool

Validate the pointer and index ranges.

True
Source code in btorch/sparse/csr.py
class CSC(_Compressed):
    """Compressed sparse column format (exactly two sparse dimensions).

    Args:
        pointer: ``[n_cols + 1]`` column pointers (``ccol_indices``).
        minor: ``[nnz]`` row of each entry (``row_indices``).
        values: ``[*batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, n_rows, n_cols, *dense)``.
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties (``sorted`` refers to
            column-major order).
        hints: Performance expectations.
        check: Validate the pointer and index ranges.
    """

    format = "csc"
    _major_axis = 1

    def ccol_indices(self) -> Tensor:
        """``[n_cols + 1]`` column pointers (PyTorch name)."""
        return self._pointer

    def row_indices(self) -> Tensor:
        """``[nnz]`` row of each entry (PyTorch name)."""
        return self._minor

    def col_indices(self) -> Tensor:
        """``[nnz]`` column of each entry, expanded from the pointers."""
        return self._major_indices()

    def tocsr(self, return_map: bool = False):
        return self.tocoo().tocsr(return_map)

    def tocsc(self, return_map: bool = False):
        """Return ``self`` (already CSC; entries are left as stored).

        Use :meth:`coalesce` to sort rows and merge duplicates.
        """
        if return_map:
            return self, EdgeMap.identity(self.nnz, self._minor.device)
        return self

    def coalesce(self, return_map: bool = False):
        """Canonical CSC: sorted rows, duplicates summed."""
        return self.tocoo().tocsc(return_map)

    def transpose(self) -> CSR:
        """Transpose without copying: the same arrays read as CSR."""
        return self._like(
            CSR,
            _shape=self._swapped_shape(),
            properties=self.properties.replace(triangular=None),
        )
Methods:
ccol_indices()

[n_cols + 1] column pointers (PyTorch name).

Source code in btorch/sparse/csr.py
def ccol_indices(self) -> Tensor:
    """``[n_cols + 1]`` column pointers (PyTorch name)."""
    return self._pointer
coalesce(return_map=False)

Canonical CSC: sorted rows, duplicates summed.

Source code in btorch/sparse/csr.py
def coalesce(self, return_map: bool = False):
    """Canonical CSC: sorted rows, duplicates summed."""
    return self.tocoo().tocsc(return_map)
col_indices()

[nnz] column of each entry, expanded from the pointers.

Source code in btorch/sparse/csr.py
def col_indices(self) -> Tensor:
    """``[nnz]`` column of each entry, expanded from the pointers."""
    return self._major_indices()
row_indices()

[nnz] row of each entry (PyTorch name).

Source code in btorch/sparse/csr.py
def row_indices(self) -> Tensor:
    """``[nnz]`` row of each entry (PyTorch name)."""
    return self._minor
tocsc(return_map=False)

Return self (already CSC; entries are left as stored).

Use :meth:coalesce to sort rows and merge duplicates.

Source code in btorch/sparse/csr.py
def tocsc(self, return_map: bool = False):
    """Return ``self`` (already CSC; entries are left as stored).

    Use :meth:`coalesce` to sort rows and merge duplicates.
    """
    if return_map:
        return self, EdgeMap.identity(self.nnz, self._minor.device)
    return self
transpose()

Transpose without copying: the same arrays read as CSR.

Source code in btorch/sparse/csr.py
def transpose(self) -> CSR:
    """Transpose without copying: the same arrays read as CSR."""
    return self._like(
        CSR,
        _shape=self._swapped_shape(),
        properties=self.properties.replace(triangular=None),
    )

CSR

Bases: _Compressed

Compressed sparse row format (exactly two sparse dimensions).

Batch members share one sparsity pattern: crow_indices and col_indices are stored once and values is [*batch, nnz, *dense]. This is the natural layout for ensembles and parameter sweeps over a fixed topology.

Parameters:

Name Type Description Default
pointer Tensor

[n_rows + 1] row pointers (crow_indices).

required
minor Tensor

[nnz] column of each entry (col_indices).

required
values Tensor

[*batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, n_rows, n_cols, *dense).

required
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties.

None
hints Hints | None

Performance expectations.

None
check bool

Validate the pointer and index ranges.

True

Examples:

>>> import torch
>>> from btorch import sparse
>>> A = sparse.csr(torch.tensor([0, 1, 2]), torch.tensor([2, 0]),
...                torch.tensor([3.0, 5.0]), shape=(2, 3))
>>> A.indptr
tensor([0, 1, 2])
>>> A @ torch.tensor([1.0, 0.0, 2.0])
tensor([6., 5.])
Source code in btorch/sparse/csr.py
class CSR(_Compressed):
    """Compressed sparse row format (exactly two sparse dimensions).

    Batch members share one sparsity pattern: ``crow_indices`` and
    ``col_indices`` are stored once and ``values`` is ``[*batch, nnz,
    *dense]``. This is the natural layout for ensembles and parameter sweeps
    over a fixed topology.

    Args:
        pointer: ``[n_rows + 1]`` row pointers (``crow_indices``).
        minor: ``[nnz]`` column of each entry (``col_indices``).
        values: ``[*batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, n_rows, n_cols, *dense)``.
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties.
        hints: Performance expectations.
        check: Validate the pointer and index ranges.

    Examples:
        >>> import torch
        >>> from btorch import sparse
        >>> A = sparse.csr(torch.tensor([0, 1, 2]), torch.tensor([2, 0]),
        ...                torch.tensor([3.0, 5.0]), shape=(2, 3))
        >>> A.indptr
        tensor([0, 1, 2])
        >>> A @ torch.tensor([1.0, 0.0, 2.0])
        tensor([6., 5.])
    """

    format = "csr"
    _major_axis = 0

    def crow_indices(self) -> Tensor:
        """``[n_rows + 1]`` row pointers (PyTorch name)."""
        return self._pointer

    def col_indices(self) -> Tensor:
        """``[nnz]`` column of each entry (PyTorch name)."""
        return self._minor

    def row_indices(self) -> Tensor:
        """``[nnz]`` row of each entry, expanded from the pointers."""
        return self._major_indices()

    def tocsr(self, return_map: bool = False):
        """Return ``self`` (already CSR; entries are left as stored).

        Use :meth:`coalesce` to sort columns and merge duplicates.
        """
        if return_map:
            return self, EdgeMap.identity(self.nnz, self._minor.device)
        return self

    def coalesce(self, return_map: bool = False):
        """Canonical CSR: sorted columns, duplicates summed."""
        return self.tocoo().tocsr(return_map)

    def tocsc(self, return_map: bool = False):
        return self.tocoo().tocsc(return_map)

    def transpose(self) -> "CSC":
        """Transpose without copying: the same arrays read as CSC."""
        return self._like(
            CSC,
            _shape=self._swapped_shape(),
            properties=self.properties.replace(triangular=None),
        )
Methods:
coalesce(return_map=False)

Canonical CSR: sorted columns, duplicates summed.

Source code in btorch/sparse/csr.py
def coalesce(self, return_map: bool = False):
    """Canonical CSR: sorted columns, duplicates summed."""
    return self.tocoo().tocsr(return_map)
col_indices()

[nnz] column of each entry (PyTorch name).

Source code in btorch/sparse/csr.py
def col_indices(self) -> Tensor:
    """``[nnz]`` column of each entry (PyTorch name)."""
    return self._minor
crow_indices()

[n_rows + 1] row pointers (PyTorch name).

Source code in btorch/sparse/csr.py
def crow_indices(self) -> Tensor:
    """``[n_rows + 1]`` row pointers (PyTorch name)."""
    return self._pointer
row_indices()

[nnz] row of each entry, expanded from the pointers.

Source code in btorch/sparse/csr.py
def row_indices(self) -> Tensor:
    """``[nnz]`` row of each entry, expanded from the pointers."""
    return self._major_indices()
tocsr(return_map=False)

Return self (already CSR; entries are left as stored).

Use :meth:coalesce to sort columns and merge duplicates.

Source code in btorch/sparse/csr.py
def tocsr(self, return_map: bool = False):
    """Return ``self`` (already CSR; entries are left as stored).

    Use :meth:`coalesce` to sort columns and merge duplicates.
    """
    if return_map:
        return self, EdgeMap.identity(self.nnz, self._minor.device)
    return self
transpose()

Transpose without copying: the same arrays read as CSC.

Source code in btorch/sparse/csr.py
def transpose(self) -> "CSC":
    """Transpose without copying: the same arrays read as CSC."""
    return self._like(
        CSC,
        _shape=self._swapped_shape(),
        properties=self.properties.replace(triangular=None),
    )

EdgeMap dataclass

Correspondence between the entries of two representations.

A representation change (sorting, duplicate reduction) maps every old entry e to a new entry target[e]. Every edge-aligned array (values, group ids, receptors, delays, plasticity state) must be moved with the same map, so the map is computed once and applied to each of them.

Parameters:

Name Type Description Default
target Tensor

[n_old] new position of every old entry.

required
n_new int

Number of entries after the change.

required
Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class EdgeMap:
    """Correspondence between the entries of two representations.

    A representation change (sorting, duplicate reduction) maps every old
    entry ``e`` to a new entry ``target[e]``. Every edge-aligned array (values,
    group ids, receptors, delays, plasticity state) must be moved with the same
    map, so the map is computed once and applied to each of them.

    Args:
        target: ``[n_old]`` new position of every old entry.
        n_new: Number of entries after the change.
    """

    target: Tensor
    n_new: int

    @property
    def n_old(self) -> int:
        return int(self.target.shape[0])

    @property
    def is_permutation(self) -> bool:
        """Whether no entries were merged."""
        return self.n_old == self.n_new

    def source(self) -> Tensor:
        """``[n_new]`` index of one old entry for every new entry.

        For merged duplicates this is the last old entry of the group.
        """
        old = torch.arange(self.n_old, device=self.target.device)
        if self.is_permutation:
            src = torch.empty_like(old)
            src[self.target] = old
            return src
        # Deterministic on every device (an indexed assignment with repeated
        # targets is not).
        src = self.target.new_zeros(self.n_new)
        return src.scatter_reduce(0, self.target, old, "amax", include_self=False)

    def sum(self, values: Tensor, dim: int = -1) -> Tensor:
        """Move additive data (weights); merged entries are summed.

        Differentiable: the gradient of a merged entry flows to every old
        entry that was merged into it.

        Args:
            values: Tensor whose axis ``dim`` has length ``n_old``.
            dim: Edge axis.
        """
        if self.is_permutation:
            return values.index_select(dim, self.source())
        shape = list(values.shape)
        shape[dim] = self.n_new
        return values.new_zeros(shape).index_add(dim, self.target, values)

    def take(self, meta: Tensor, dim: int = 0, check: bool = True) -> Tensor:
        """Move categorical metadata (group, receptor, delay ids).

        Args:
            meta: Tensor whose axis ``dim`` has length ``n_old``.
            dim: Edge axis.
            check: Raise if merged entries carry different metadata, because
                no single value can then represent the merged entry.

        Raises:
            ValueError: If ``check`` and merged duplicates disagree.
        """
        out = meta.index_select(dim, self.source())
        if check and not self.is_permutation:
            if not torch.equal(out.index_select(dim, self.target), meta):
                raise ValueError(
                    "Duplicate entries carry different metadata and cannot be "
                    "merged; split them into separate connections or make the "
                    "metadata equal first."
                )
        return out

    def compose(self, then: "EdgeMap") -> "EdgeMap":
        """Map equivalent to applying ``self`` and then ``then``."""
        return EdgeMap(then.target[self.target], then.n_new)

    @staticmethod
    def identity(n: int, device=None) -> "EdgeMap":
        return EdgeMap(torch.arange(n, device=device), n)
Attributes
is_permutation property

Whether no entries were merged.

Methods:
compose(then)

Map equivalent to applying self and then then.

Source code in btorch/sparse/properties.py
def compose(self, then: "EdgeMap") -> "EdgeMap":
    """Map equivalent to applying ``self`` and then ``then``."""
    return EdgeMap(then.target[self.target], then.n_new)
source()

[n_new] index of one old entry for every new entry.

For merged duplicates this is the last old entry of the group.

Source code in btorch/sparse/properties.py
def source(self) -> Tensor:
    """``[n_new]`` index of one old entry for every new entry.

    For merged duplicates this is the last old entry of the group.
    """
    old = torch.arange(self.n_old, device=self.target.device)
    if self.is_permutation:
        src = torch.empty_like(old)
        src[self.target] = old
        return src
    # Deterministic on every device (an indexed assignment with repeated
    # targets is not).
    src = self.target.new_zeros(self.n_new)
    return src.scatter_reduce(0, self.target, old, "amax", include_self=False)
sum(values, dim=-1)

Move additive data (weights); merged entries are summed.

Differentiable: the gradient of a merged entry flows to every old entry that was merged into it.

Parameters:

Name Type Description Default
values Tensor

Tensor whose axis dim has length n_old.

required
dim int

Edge axis.

-1
Source code in btorch/sparse/properties.py
def sum(self, values: Tensor, dim: int = -1) -> Tensor:
    """Move additive data (weights); merged entries are summed.

    Differentiable: the gradient of a merged entry flows to every old
    entry that was merged into it.

    Args:
        values: Tensor whose axis ``dim`` has length ``n_old``.
        dim: Edge axis.
    """
    if self.is_permutation:
        return values.index_select(dim, self.source())
    shape = list(values.shape)
    shape[dim] = self.n_new
    return values.new_zeros(shape).index_add(dim, self.target, values)
take(meta, dim=0, check=True)

Move categorical metadata (group, receptor, delay ids).

Parameters:

Name Type Description Default
meta Tensor

Tensor whose axis dim has length n_old.

required
dim int

Edge axis.

0
check bool

Raise if merged entries carry different metadata, because no single value can then represent the merged entry.

True

Raises:

Type Description
ValueError

If check and merged duplicates disagree.

Source code in btorch/sparse/properties.py
def take(self, meta: Tensor, dim: int = 0, check: bool = True) -> Tensor:
    """Move categorical metadata (group, receptor, delay ids).

    Args:
        meta: Tensor whose axis ``dim`` has length ``n_old``.
        dim: Edge axis.
        check: Raise if merged entries carry different metadata, because
            no single value can then represent the merged entry.

    Raises:
        ValueError: If ``check`` and merged duplicates disagree.
    """
    out = meta.index_select(dim, self.source())
    if check and not self.is_permutation:
        if not torch.equal(out.index_select(dim, self.target), meta):
            raise ValueError(
                "Duplicate entries carry different metadata and cannot be "
                "merged; split them into separate connections or make the "
                "metadata equal first."
            )
    return out

Hints dataclass

Performance expectations; advisory only.

Only expected_density is consulted by the planner today; the other two are accepted and reserved.

Parameters:

Name Type Description Default
expected_calls int | None

How many products the object will take part in (reserved).

None
expected_density float | None

Expected fraction of non-zero input entries, in [0, 1].

None
expected_batch int | None

Expected number of right-hand sides per call (reserved).

None

Raises:

Type Description
ValueError

If a value is out of range.

Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class Hints:
    """Performance expectations; advisory only.

    Only ``expected_density`` is consulted by the planner today; the other
    two are accepted and reserved.

    Args:
        expected_calls: How many products the object will take part in
            (reserved).
        expected_density: Expected fraction of non-zero input entries, in
            ``[0, 1]``.
        expected_batch: Expected number of right-hand sides per call
            (reserved).

    Raises:
        ValueError: If a value is out of range.
    """

    expected_calls: int | None = None
    expected_density: float | None = None
    expected_batch: int | None = None

    def __post_init__(self) -> None:
        density = self.expected_density
        if density is not None and not (
            isinstance(density, (int, float)) and 0.0 <= density <= 1.0
        ):
            raise ValueError(f"expected_density must be in [0, 1], got {density!r}.")
        for name in ("expected_calls", "expected_batch"):
            value = getattr(self, name)
            if value is not None and not (isinstance(value, int) and value > 0):
                raise ValueError(f"{name} must be a positive int, got {value!r}.")

    def replace(self, **changes) -> "Hints":
        """Return a copy with selected expectations changed."""
        return replace(self, **changes)
Methods:
replace(**changes)

Return a copy with selected expectations changed.

Source code in btorch/sparse/properties.py
def replace(self, **changes) -> "Hints":
    """Return a copy with selected expectations changed."""
    return replace(self, **changes)

LinearOperator

Base class of everything that acts as a matrix of shape (M, N).

Subclasses implement the private hooks _matvec / _rmatvec (and optionally _matmat / _enumerate_edges) and list what they provide in _capabilities. The public methods validate shapes and capabilities and are shared by all operators.

Operators are plain Python objects holding tensors, like :class:~btorch.sparse.Sparse; they are not nn.Module. A learnable tensor used by an operator must be registered on the owning module, which passes it to the operator (see the examples of the concrete classes).

Operator algebra is lazy and never builds a matrix:

  • A + B, A - B: :class:SumOperator.
  • A @ B with another operator or a Sparse: :class:ProductOperator.
  • alpha * A, A * alpha, A / alpha, -A: :class:ScaledOperator.
  • A.T: :class:TransposedOperator.

The class is an ABC only so that explicit sparse arrays can be registered as virtual subclasses (LinearOperator.register(Sparse)); it has no abstract methods.

Source code in btorch/sparse/operator.py
class LinearOperator(metaclass=ABCMeta):
    """Base class of everything that acts as a matrix of shape ``(M, N)``.

    Subclasses implement the private hooks ``_matvec`` / ``_rmatvec`` (and
    optionally ``_matmat`` / ``_enumerate_edges``) and list what they provide
    in ``_capabilities``. The public methods validate shapes and capabilities
    and are shared by all operators.

    Operators are plain Python objects holding tensors, like
    :class:`~btorch.sparse.Sparse`; they are not ``nn.Module``. A learnable
    tensor used by an operator must be registered on the owning module, which
    passes it to the operator (see the examples of the concrete classes).

    Operator algebra is lazy and never builds a matrix:

    - ``A + B``, ``A - B``: :class:`SumOperator`.
    - ``A @ B`` with another operator or a ``Sparse``: :class:`ProductOperator`.
    - ``alpha * A``, ``A * alpha``, ``A / alpha``, ``-A``:
      :class:`ScaledOperator`.
    - ``A.T``: :class:`TransposedOperator`.

    The class is an ABC only so that explicit sparse arrays can be registered
    as virtual subclasses (``LinearOperator.register(Sparse)``); it has no
    abstract methods.
    """

    _capabilities: frozenset[str] = frozenset()
    _shape: tuple[int, int]
    dtype: torch.dtype | None = None
    device: torch.device | None = None

    # ----------------------------------------------------------------- shape
    @property
    def shape(self) -> tuple[int, int]:
        """``(M, N)``: the operator maps length-``N`` to length-``M``."""
        return self._shape

    @property
    def ndim(self) -> int:
        return 2

    # ---------------------------------------------------------- capabilities
    def supports(self, name: str) -> bool:
        """Whether the optional capability ``name`` is available.

        Args:
            name: One of :data:`CAPABILITIES`.

        Raises:
            ValueError: If ``name`` is not a known capability.
        """
        if name not in CAPABILITIES:
            raise ValueError(
                f"Unknown capability {name!r}; expected one of {sorted(CAPABILITIES)}."
            )
        return name in self._capabilities

    def _require(self, name: str) -> None:
        if name not in self._capabilities:
            raise NotImplementedError(
                f"{type(self).__name__} of shape {self.shape} does not support "
                f"the capability {name!r} (supported: "
                f"{sorted(self._capabilities)})."
            )

    # --------------------------------------------------------------- products
    def matvec(self, x: Tensor) -> Tensor:
        """Apply the operator along the last axis: ``[..., N] -> [..., M]``.

        .. math::
            y_{\\ldots m} = \\sum_n A_{m n}\\, x_{\\ldots n}

        All leading dimensions of ``x`` are independent samples.
        """
        self._require("matvec")
        if x.shape[-1] != self._shape[1]:
            raise ValueError(
                f"matvec: the last dimension of the input is {x.shape[-1]}, "
                f"expected {self._shape[1]} for an operator of shape {self.shape}."
            )
        return self._matvec(x)

    def rmatvec(self, x: Tensor) -> Tensor:
        """Apply the transpose along the last axis: ``[..., M] -> [..., N]``.

        Equals ``self.T.matvec(x)`` and, for 1-D ``x``, ``x @ self``.
        """
        self._require("rmatvec")
        if x.shape[-1] != self._shape[0]:
            raise ValueError(
                f"rmatvec: the last dimension of the input is {x.shape[-1]}, "
                f"expected {self._shape[0]} for an operator of shape {self.shape}."
            )
        return self._rmatvec(x)

    def matmat(self, x: Tensor) -> Tensor:
        """``A @ X`` for ``X [..., N, K]``, returning ``[..., M, K]``."""
        self._require("matmat")
        if x.ndim < 2 or x.shape[-2] != self._shape[1]:
            raise ValueError(
                f"matmat: the input needs shape [..., {self._shape[1]}, K] for "
                f"an operator of shape {self.shape}, got {tuple(x.shape)}."
            )
        return self._matmat(x)

    def _matvec(self, x: Tensor) -> Tensor:
        raise NotImplementedError

    def _rmatvec(self, x: Tensor) -> Tensor:
        raise NotImplementedError

    def _matmat(self, x: Tensor) -> Tensor:
        # Columns of X are vectors: move them to the last axis and back.
        return self.matvec(x.mT).mT

    def __matmul__(self, other):
        if isinstance(other, Tensor):
            if other.ndim == 0:
                raise ValueError("A @ x needs x with at least one dimension.")
            if other.ndim == 1:
                return self.matvec(other)
            return self.matmat(other)
        if is_linear_operator(other):
            return ProductOperator([self, other])
        return NotImplemented

    def __rmatmul__(self, other):
        if isinstance(other, Tensor):
            if other.ndim == 0:
                raise ValueError("x @ A needs x with at least one dimension.")
            # 1-D: x [M] -> [N]; matrix: X [..., K, M] -> [..., K, N]. In both
            # cases the transpose acts along the last axis.
            return self.rmatvec(other)
        if is_linear_operator(other):
            return ProductOperator([other, self])
        return NotImplemented

    # ---------------------------------------------------------- lazy algebra
    def __add__(self, other):
        if is_linear_operator(other):
            return SumOperator([self, other])
        return NotImplemented

    def __radd__(self, other):
        if is_linear_operator(other):
            return SumOperator([other, self])
        return NotImplemented

    def __sub__(self, other):
        if is_linear_operator(other):
            return SumOperator([self, ScaledOperator(other, -1.0)])
        return NotImplemented

    def __rsub__(self, other):
        if is_linear_operator(other):
            return SumOperator([other, ScaledOperator(self, -1.0)])
        return NotImplemented

    def __mul__(self, alpha):
        if _is_scalar(alpha):
            return ScaledOperator(self, alpha)
        return NotImplemented

    __rmul__ = __mul__

    def __truediv__(self, alpha):
        if _is_scalar(alpha):
            return ScaledOperator(self, 1.0 / alpha)
        return NotImplemented

    def __neg__(self):
        return ScaledOperator(self, -1.0)

    @property
    def T(self) -> "LinearOperator":
        """Lazy transpose; needs the ``"rmatvec"`` capability."""
        return TransposedOperator(self)

    def transpose(self) -> "LinearOperator":
        return self.T

    # -------------------------------------------------------- materialisation
    def enumerate_edges(self) -> Edges:
        """List the entries as ``(rows [E], cols [E], values [E])``.

        Entries may repeat; repeated coordinates are summed, as in
        :class:`~btorch.sparse.COO`. ``values`` keeps its autograd history.
        """
        self._require("enumerate_edges")
        return self._enumerate_edges()

    def _enumerate_edges(self) -> Edges:
        raise NotImplementedError

    def materialize(self, format: str | None = None):
        """Build an explicit :class:`~btorch.sparse.Sparse` with these entries.

        Args:
            format: Optional ``"coo"``, ``"csr"`` or ``"csc"``. Without it the
                result is format-agnostic.

        Raises:
            NotImplementedError: If the operator cannot list its entries
                (capability ``"materialize_sparse"``).
        """
        self._require("materialize_sparse")
        from . import from_edges

        rows, cols, values = self._enumerate_edges()
        out = from_edges(rows, cols, values, self.shape)
        if format is not None and out.format != format:
            out = getattr(out, f"to{format}")()
        return out

    def tocoo(self):
        """Materialise as COO (capability ``"materialize_sparse"``)."""
        return self.materialize("coo")

    def tocsr(self):
        """Materialise as CSR (capability ``"materialize_sparse"``)."""
        return self.materialize("csr")

    def tocsc(self):
        """Materialise as CSC (capability ``"materialize_sparse"``)."""
        return self.materialize("csc")

    def to_dense(
        self,
        *,
        dtype: torch.dtype | None = None,
        device: torch.device | str | None = None,
    ) -> Tensor:
        """Dense ``[M, N]`` matrix; an explicit request, never done implicitly.

        The default applies the operator to the identity (``N`` right-hand
        sides at once), so it only needs ``"matvec"`` and stays
        differentiable.

        Args:
            dtype: Dtype of the identity; defaults to the operator dtype if
                it has one.
            device: Device of the identity; defaults to the operator device.
        """
        eye = torch.eye(
            self._shape[1],
            dtype=dtype if dtype is not None else self.dtype,
            device=device if device is not None else self.device,
        )
        # Row n of matvec(eye) is A @ e_n, i.e. column n of A.
        return self.matvec(eye).mT

    def __repr__(self) -> str:
        return f"{type(self).__name__}(shape={self.shape})"
Attributes
T property

Lazy transpose; needs the "rmatvec" capability.

shape property

(M, N): the operator maps length-N to length-M.

Methods:
enumerate_edges()

List the entries as (rows [E], cols [E], values [E]).

Entries may repeat; repeated coordinates are summed, as in :class:~btorch.sparse.COO. values keeps its autograd history.

Source code in btorch/sparse/operator.py
def enumerate_edges(self) -> Edges:
    """List the entries as ``(rows [E], cols [E], values [E])``.

    Entries may repeat; repeated coordinates are summed, as in
    :class:`~btorch.sparse.COO`. ``values`` keeps its autograd history.
    """
    self._require("enumerate_edges")
    return self._enumerate_edges()
materialize(format=None)

Build an explicit :class:~btorch.sparse.Sparse with these entries.

Parameters:

Name Type Description Default
format str | None

Optional "coo", "csr" or "csc". Without it the result is format-agnostic.

None

Raises:

Type Description
NotImplementedError

If the operator cannot list its entries (capability "materialize_sparse").

Source code in btorch/sparse/operator.py
def materialize(self, format: str | None = None):
    """Build an explicit :class:`~btorch.sparse.Sparse` with these entries.

    Args:
        format: Optional ``"coo"``, ``"csr"`` or ``"csc"``. Without it the
            result is format-agnostic.

    Raises:
        NotImplementedError: If the operator cannot list its entries
            (capability ``"materialize_sparse"``).
    """
    self._require("materialize_sparse")
    from . import from_edges

    rows, cols, values = self._enumerate_edges()
    out = from_edges(rows, cols, values, self.shape)
    if format is not None and out.format != format:
        out = getattr(out, f"to{format}")()
    return out
matmat(x)

A @ X for X [..., N, K], returning [..., M, K].

Source code in btorch/sparse/operator.py
def matmat(self, x: Tensor) -> Tensor:
    """``A @ X`` for ``X [..., N, K]``, returning ``[..., M, K]``."""
    self._require("matmat")
    if x.ndim < 2 or x.shape[-2] != self._shape[1]:
        raise ValueError(
            f"matmat: the input needs shape [..., {self._shape[1]}, K] for "
            f"an operator of shape {self.shape}, got {tuple(x.shape)}."
        )
    return self._matmat(x)
matvec(x)

Apply the operator along the last axis: [..., N] -> [..., M].

.. math:: y_{\ldots m} = \sum_n A_{m n}\, x_{\ldots n}

All leading dimensions of x are independent samples.

Source code in btorch/sparse/operator.py
def matvec(self, x: Tensor) -> Tensor:
    """Apply the operator along the last axis: ``[..., N] -> [..., M]``.

    .. math::
        y_{\\ldots m} = \\sum_n A_{m n}\\, x_{\\ldots n}

    All leading dimensions of ``x`` are independent samples.
    """
    self._require("matvec")
    if x.shape[-1] != self._shape[1]:
        raise ValueError(
            f"matvec: the last dimension of the input is {x.shape[-1]}, "
            f"expected {self._shape[1]} for an operator of shape {self.shape}."
        )
    return self._matvec(x)
rmatvec(x)

Apply the transpose along the last axis: [..., M] -> [..., N].

Equals self.T.matvec(x) and, for 1-D x, x @ self.

Source code in btorch/sparse/operator.py
def rmatvec(self, x: Tensor) -> Tensor:
    """Apply the transpose along the last axis: ``[..., M] -> [..., N]``.

    Equals ``self.T.matvec(x)`` and, for 1-D ``x``, ``x @ self``.
    """
    self._require("rmatvec")
    if x.shape[-1] != self._shape[0]:
        raise ValueError(
            f"rmatvec: the last dimension of the input is {x.shape[-1]}, "
            f"expected {self._shape[0]} for an operator of shape {self.shape}."
        )
    return self._rmatvec(x)
supports(name)

Whether the optional capability name is available.

Parameters:

Name Type Description Default
name str

One of :data:CAPABILITIES.

required

Raises:

Type Description
ValueError

If name is not a known capability.

Source code in btorch/sparse/operator.py
def supports(self, name: str) -> bool:
    """Whether the optional capability ``name`` is available.

    Args:
        name: One of :data:`CAPABILITIES`.

    Raises:
        ValueError: If ``name`` is not a known capability.
    """
    if name not in CAPABILITIES:
        raise ValueError(
            f"Unknown capability {name!r}; expected one of {sorted(CAPABILITIES)}."
        )
    return name in self._capabilities
to_dense(*, dtype=None, device=None)

Dense [M, N] matrix; an explicit request, never done implicitly.

The default applies the operator to the identity (N right-hand sides at once), so it only needs "matvec" and stays differentiable.

Parameters:

Name Type Description Default
dtype dtype | None

Dtype of the identity; defaults to the operator dtype if it has one.

None
device device | str | None

Device of the identity; defaults to the operator device.

None
Source code in btorch/sparse/operator.py
def to_dense(
    self,
    *,
    dtype: torch.dtype | None = None,
    device: torch.device | str | None = None,
) -> Tensor:
    """Dense ``[M, N]`` matrix; an explicit request, never done implicitly.

    The default applies the operator to the identity (``N`` right-hand
    sides at once), so it only needs ``"matvec"`` and stays
    differentiable.

    Args:
        dtype: Dtype of the identity; defaults to the operator dtype if
            it has one.
        device: Device of the identity; defaults to the operator device.
    """
    eye = torch.eye(
        self._shape[1],
        dtype=dtype if dtype is not None else self.dtype,
        device=device if device is not None else self.device,
    )
    # Row n of matvec(eye) is A @ e_n, i.e. column n of A.
    return self.matvec(eye).mT
tocoo()

Materialise as COO (capability "materialize_sparse").

Source code in btorch/sparse/operator.py
def tocoo(self):
    """Materialise as COO (capability ``"materialize_sparse"``)."""
    return self.materialize("coo")
tocsc()

Materialise as CSC (capability "materialize_sparse").

Source code in btorch/sparse/operator.py
def tocsc(self):
    """Materialise as CSC (capability ``"materialize_sparse"``)."""
    return self.materialize("csc")
tocsr()

Materialise as CSR (capability "materialize_sparse").

Source code in btorch/sparse/operator.py
def tocsr(self):
    """Materialise as CSR (capability ``"materialize_sparse"``)."""
    return self.materialize("csr")

Properties dataclass

Structural facts about a stored sparse representation.

A True value is a guarantee; False means "not known", never "known to be violated".

Parameters:

Name Type Description Default
sorted bool

Entries are in lexicographic (row-major) index order.

False
unique bool

No index tuple is stored twice.

False
symmetric bool

Stored values satisfy A == A.T.

False
structurally_symmetric bool

The sparsity pattern is symmetric.

False
triangular str | None

"lower", "upper" or None.

None
fixed_pattern bool

The pattern is never mutated (no rewiring).

False
shared_pattern bool

A batch of matrices shares one pattern.

False
Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class Properties:
    """Structural facts about a stored sparse representation.

    A ``True`` value is a guarantee; ``False`` means "not known", never
    "known to be violated".

    Args:
        sorted: Entries are in lexicographic (row-major) index order.
        unique: No index tuple is stored twice.
        symmetric: Stored values satisfy ``A == A.T``.
        structurally_symmetric: The sparsity pattern is symmetric.
        triangular: ``"lower"``, ``"upper"`` or ``None``.
        fixed_pattern: The pattern is never mutated (no rewiring).
        shared_pattern: A batch of matrices shares one pattern.
    """

    sorted: bool = False
    unique: bool = False
    symmetric: bool = False
    structurally_symmetric: bool = False
    triangular: str | None = None
    fixed_pattern: bool = False
    shared_pattern: bool = False

    @property
    def canonical(self) -> bool:
        """Whether entries are sorted and free of duplicates."""
        return self.sorted and self.unique

    def replace(self, **changes) -> "Properties":
        """Return a copy with some fields changed."""
        return replace(self, **changes)
Attributes
canonical property

Whether entries are sorted and free of duplicates.

Methods:
replace(**changes)

Return a copy with some fields changed.

Source code in btorch/sparse/properties.py
def replace(self, **changes) -> "Properties":
    """Return a copy with some fields changed."""
    return replace(self, **changes)

Sparse

Sparse array with logical shape [*batch, *sparse, *dense].

Sparse is the format-agnostic interface. It describes what the array is (shape, dtype, device, number of stored entries) and offers the operations every format supports. Format-specific data such as indptr is only available on the concrete classes (:class:~btorch.sparse.COO, :class:~btorch.sparse.CSR, :class:~btorch.sparse.CSC), obtained with tocsr() / as_csr() and friends.

The three shape groups are:

  • batch_shape: independent sparse arrays (for example an ensemble of networks).
  • sparse_shape: the dimensions that are stored sparsely.
  • dense_shape: a dense payload attached to every stored entry.

Stored values have shape [*value_batch, nnz, *dense_shape]. A batch whose members share one sparsity pattern stores the pattern once and only the values per member.

Sparse is a plain Python object holding tensors; it is not a torch.Tensor subclass. Matrix products follow standard linear algebra: for A.shape == (M, N), A @ x maps a length-N vector to a length-M vector. Conversions never transpose.

Source code in btorch/sparse/base.py
class Sparse:
    """Sparse array with logical shape ``[*batch, *sparse, *dense]``.

    ``Sparse`` is the format-agnostic interface. It describes *what* the array
    is (shape, dtype, device, number of stored entries) and offers the
    operations every format supports. Format-specific data such as ``indptr``
    is only available on the concrete classes (:class:`~btorch.sparse.COO`,
    :class:`~btorch.sparse.CSR`, :class:`~btorch.sparse.CSC`), obtained with
    ``tocsr()`` / ``as_csr()`` and friends.

    The three shape groups are:

    - ``batch_shape``: independent sparse arrays (for example an ensemble of
      networks).
    - ``sparse_shape``: the dimensions that are stored sparsely.
    - ``dense_shape``: a dense payload attached to every stored entry.

    Stored values have shape ``[*value_batch, nnz, *dense_shape]``. A batch
    whose members share one sparsity pattern stores the pattern once and only
    the values per member.

    ``Sparse`` is a plain Python object holding tensors; it is not a
    ``torch.Tensor`` subclass. Matrix products follow standard linear algebra:
    for ``A.shape == (M, N)``, ``A @ x`` maps a length-``N`` vector to a
    length-``M`` vector. Conversions never transpose.
    """

    format: str = "sparse"
    # Let ``ndarray @ A`` reach ``__rmatmul__`` instead of NumPy treating the
    # sparse array as an object scalar.
    __array_ufunc__ = None

    _values: Tensor
    _shape: tuple[int, ...]
    _batch_dim: int
    _dense_dim: int
    properties: Properties
    hints: Hints

    # ------------------------------------------------------------------ shape
    @property
    def shape(self) -> tuple[int, ...]:
        """Logical shape ``(*batch, *sparse, *dense)``."""
        return self._shape

    @property
    def ndim(self) -> int:
        return len(self._shape)

    def batch_dim(self) -> int:
        """Number of batch dimensions."""
        return self._batch_dim

    def dense_dim(self) -> int:
        """Number of dense (per-entry payload) dimensions."""
        return self._dense_dim

    def sparse_dim(self) -> int:
        """Number of sparsely stored dimensions."""
        return self.ndim - self._batch_dim - self._dense_dim

    @property
    def batch_shape(self) -> tuple[int, ...]:
        return self._shape[: self._batch_dim]

    @property
    def sparse_shape(self) -> tuple[int, ...]:
        return self._shape[self._batch_dim : self.ndim - self._dense_dim]

    @property
    def dense_shape(self) -> tuple[int, ...]:
        return self._shape[self.ndim - self._dense_dim :]

    @property
    def dtype(self) -> torch.dtype:
        return self._values.dtype

    @property
    def device(self) -> torch.device:
        return self._values.device

    @property
    def nnz(self) -> int:
        """Number of stored entries (of one batch member for a shared pattern,
        of all members together otherwise)."""
        raise NotImplementedError

    @property
    def requires_grad(self) -> bool:
        return self._values.requires_grad

    # ------------------------------------------------------- format changes
    def tocoo(self) -> "COO":
        """Convert to COO (may allocate)."""
        raise NotImplementedError

    def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
        """Convert to CSR (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
        """Convert to CSC (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tobsr(self, blocksize: tuple[int, int]):
        """Convert to BSR; not implemented as a native format.

        Use ``to_torch(layout="bsr", blocksize=...)`` or
        ``to_scipy(format="bsr")`` to export block storage.
        """
        raise NotImplementedError(
            "BSR is not a native btorch format yet; export with "
            "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
        )

    def _as(self, fmt: str):
        if self.format != fmt:
            hint = (
                "BSR is not a native format; export with to_torch(layout='bsr')."
                if fmt == "bsr"
                else f"Call to{fmt}() to convert explicitly."
            )
            raise TypeError(
                f"This sparse array is stored as {self.format.upper()}, not "
                f"{fmt.upper()}; as_{fmt}() never converts. {hint}"
            )
        return self

    def as_coo(self) -> "COO":
        """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
        return self._as("coo")

    def as_csr(self) -> "CSR":
        """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
        return self._as("csr")

    def as_csc(self) -> "CSC":
        """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
        return self._as("csc")

    def as_bsr(self, blocksize: tuple[int, int] | None = None):
        """BSR is not a native format; always raises ``TypeError``."""
        return self._as("bsr")

    # -------------------------------------------------------------- interop
    @classmethod
    def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
        """Wrap a ``torch`` sparse tensor (see
        :func:`btorch.sparse.from_torch`)."""
        from .conversion import from_torch

        return from_torch(tensor, batch_dim=batch_dim)

    @classmethod
    def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
        """Convert a SciPy sparse array or matrix (see
        :func:`btorch.sparse.from_scipy`)."""
        from .conversion import from_scipy

        return from_scipy(array, device=device, dtype=dtype)

    def to_torch(
        self, layout: str | torch.layout | None = None, **kwargs: Any
    ) -> Tensor:
        """Export as a ``torch`` sparse tensor.

        Args:
            layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
                (or the ``torch.sparse_*`` layout). Defaults to the stored
                format.
            **kwargs: ``blocksize`` for the block layouts.
        """
        from .conversion import to_torch

        return to_torch(self, layout, **kwargs)

    def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
        """Export as a ``scipy.sparse`` array (CPU, detached).

        Args:
            format: Any SciPy format name; defaults to the stored format.
            **kwargs: ``blocksize`` for ``"bsr"``.
        """
        from .conversion import to_scipy

        return to_scipy(self, format, **kwargs)

    def to_dense(self) -> Tensor:
        """Materialise as a dense tensor of shape :attr:`shape`."""
        return self.tocoo().to_dense()

    # ------------------------------------------------------- tensor handling
    def with_values(self, values: Tensor) -> "Sparse":
        """Return an array with the same pattern and new values.

        ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
        shape creates a shared-pattern batch.
        """
        raise NotImplementedError

    def _map_tensors(self, index_fn, value_fn) -> "Sparse":
        """Apply ``index_fn`` to index tensors and ``value_fn`` to values."""
        raise NotImplementedError

    def to(self, *args, **kwargs) -> "Sparse":
        """Move to a device and/or cast the values (indices stay integer)."""
        device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

        return self._map_tensors(
            lambda index: index.to(device=device),
            lambda values: values.to(device=device, dtype=dtype),
        )

    def cpu(self) -> "Sparse":
        return self.to("cpu")

    def cuda(self, device=None) -> "Sparse":
        return self.to("cuda" if device is None else device)

    def float(self) -> "Sparse":
        return self.to(torch.float32)

    def double(self) -> "Sparse":
        return self.to(torch.float64)

    def detach(self) -> "Sparse":
        return self.with_values(self._values.detach())

    # ------------------------------------------------------------- products
    def matvec(self, x: Tensor) -> Tensor:
        """Apply the operator along the last axis of ``x``.

        See :func:`btorch.sparse.matvec`.
        """
        from .ops import matvec

        return matvec(self, x)

    def rmatvec(self, x: Tensor) -> Tensor:
        """Apply the transposed operator along the last axis of ``x``."""
        from .ops import rmatvec

        return rmatvec(self, x)

    def __matmul__(self, other):
        from .ops import matmul

        return matmul(self, other)

    def __rmatmul__(self, other):
        from .ops import matmul

        return matmul(other, self)

    @property
    def T(self) -> "Sparse":
        """Transpose of the two sparse dimensions."""
        return self.transpose()

    def transpose(self) -> "Sparse":
        raise NotImplementedError

    def __repr__(self) -> str:
        parts = [f"shape={self.shape}", f"nnz={self.nnz}", f"dtype={self.dtype}"]
        if self.batch_dim():
            parts.append(f"batch_shape={self.batch_shape}")
        if self.dense_dim():
            parts.append(f"dense_shape={self.dense_shape}")
        if self.device.type != "cpu":
            parts.append(f"device={self.device}")
        return f"{type(self).__name__}({', '.join(parts)})"
Attributes
T property

Transpose of the two sparse dimensions.

nnz property

Number of stored entries (of one batch member for a shared pattern, of all members together otherwise).

shape property

Logical shape (*batch, *sparse, *dense).

Methods:
as_bsr(blocksize=None)

BSR is not a native format; always raises TypeError.

Source code in btorch/sparse/base.py
def as_bsr(self, blocksize: tuple[int, int] | None = None):
    """BSR is not a native format; always raises ``TypeError``."""
    return self._as("bsr")
as_coo()

Return self if it is stored as COO, else raise TypeError.

Source code in btorch/sparse/base.py
def as_coo(self) -> "COO":
    """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
    return self._as("coo")
as_csc()

Return self if it is stored as CSC, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csc(self) -> "CSC":
    """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
    return self._as("csc")
as_csr()

Return self if it is stored as CSR, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csr(self) -> "CSR":
    """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
    return self._as("csr")
batch_dim()

Number of batch dimensions.

Source code in btorch/sparse/base.py
def batch_dim(self) -> int:
    """Number of batch dimensions."""
    return self._batch_dim
dense_dim()

Number of dense (per-entry payload) dimensions.

Source code in btorch/sparse/base.py
def dense_dim(self) -> int:
    """Number of dense (per-entry payload) dimensions."""
    return self._dense_dim
from_scipy(array, *, device=None, dtype=None) classmethod

Convert a SciPy sparse array or matrix (see :func:btorch.sparse.from_scipy).

Source code in btorch/sparse/base.py
@classmethod
def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
    """Convert a SciPy sparse array or matrix (see
    :func:`btorch.sparse.from_scipy`)."""
    from .conversion import from_scipy

    return from_scipy(array, device=device, dtype=dtype)
from_torch(tensor, *, batch_dim=0) classmethod

Wrap a torch sparse tensor (see :func:btorch.sparse.from_torch).

Source code in btorch/sparse/base.py
@classmethod
def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
    """Wrap a ``torch`` sparse tensor (see
    :func:`btorch.sparse.from_torch`)."""
    from .conversion import from_torch

    return from_torch(tensor, batch_dim=batch_dim)
matvec(x)

Apply the operator along the last axis of x.

See :func:btorch.sparse.matvec.

Source code in btorch/sparse/base.py
def matvec(self, x: Tensor) -> Tensor:
    """Apply the operator along the last axis of ``x``.

    See :func:`btorch.sparse.matvec`.
    """
    from .ops import matvec

    return matvec(self, x)
rmatvec(x)

Apply the transposed operator along the last axis of x.

Source code in btorch/sparse/base.py
def rmatvec(self, x: Tensor) -> Tensor:
    """Apply the transposed operator along the last axis of ``x``."""
    from .ops import rmatvec

    return rmatvec(self, x)
sparse_dim()

Number of sparsely stored dimensions.

Source code in btorch/sparse/base.py
def sparse_dim(self) -> int:
    """Number of sparsely stored dimensions."""
    return self.ndim - self._batch_dim - self._dense_dim
to(*args, **kwargs)

Move to a device and/or cast the values (indices stay integer).

Source code in btorch/sparse/base.py
def to(self, *args, **kwargs) -> "Sparse":
    """Move to a device and/or cast the values (indices stay integer)."""
    device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

    return self._map_tensors(
        lambda index: index.to(device=device),
        lambda values: values.to(device=device, dtype=dtype),
    )
to_dense()

Materialise as a dense tensor of shape :attr:shape.

Source code in btorch/sparse/base.py
def to_dense(self) -> Tensor:
    """Materialise as a dense tensor of shape :attr:`shape`."""
    return self.tocoo().to_dense()
to_scipy(format=None, **kwargs)

Export as a scipy.sparse array (CPU, detached).

Parameters:

Name Type Description Default
format str | None

Any SciPy format name; defaults to the stored format.

None
**kwargs Any

blocksize for "bsr".

{}
Source code in btorch/sparse/base.py
def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
    """Export as a ``scipy.sparse`` array (CPU, detached).

    Args:
        format: Any SciPy format name; defaults to the stored format.
        **kwargs: ``blocksize`` for ``"bsr"``.
    """
    from .conversion import to_scipy

    return to_scipy(self, format, **kwargs)
to_torch(layout=None, **kwargs)

Export as a torch sparse tensor.

Parameters:

Name Type Description Default
layout str | layout | None

"coo", "csr", "csc", "bsr" or "bsc" (or the torch.sparse_* layout). Defaults to the stored format.

None
**kwargs Any

blocksize for the block layouts.

{}
Source code in btorch/sparse/base.py
def to_torch(
    self, layout: str | torch.layout | None = None, **kwargs: Any
) -> Tensor:
    """Export as a ``torch`` sparse tensor.

    Args:
        layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
            (or the ``torch.sparse_*`` layout). Defaults to the stored
            format.
        **kwargs: ``blocksize`` for the block layouts.
    """
    from .conversion import to_torch

    return to_torch(self, layout, **kwargs)
tobsr(blocksize)

Convert to BSR; not implemented as a native format.

Use to_torch(layout="bsr", blocksize=...) or to_scipy(format="bsr") to export block storage.

Source code in btorch/sparse/base.py
def tobsr(self, blocksize: tuple[int, int]):
    """Convert to BSR; not implemented as a native format.

    Use ``to_torch(layout="bsr", blocksize=...)`` or
    ``to_scipy(format="bsr")`` to export block storage.
    """
    raise NotImplementedError(
        "BSR is not a native btorch format yet; export with "
        "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
    )
tocoo()

Convert to COO (may allocate).

Source code in btorch/sparse/base.py
def tocoo(self) -> "COO":
    """Convert to COO (may allocate)."""
    raise NotImplementedError
tocsc(return_map=False)

Convert to CSC (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
    """Convert to CSC (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
tocsr(return_map=False)

Convert to CSR (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
    """Convert to CSR (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
with_values(values)

Return an array with the same pattern and new values.

values is [*batch, nnz, *dense]; a different leading batch shape creates a shared-pattern batch.

Source code in btorch/sparse/base.py
def with_values(self, values: Tensor) -> "Sparse":
    """Return an array with the same pattern and new values.

    ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
    shape creates a shared-pattern batch.
    """
    raise NotImplementedError

Functions:

_as_tensor(x, *, dtype=None, device=None)

Source code in btorch/sparse/base.py
def _as_tensor(x, *, dtype=None, device=None) -> Tensor:
    if isinstance(x, Tensor):
        return (
            x if dtype is None and device is None else x.to(device=device, dtype=dtype)
        )
    return torch.as_tensor(x, dtype=dtype, device=device)

_check_index(name, index)

Source code in btorch/sparse/base.py
def _check_index(name: str, index: Tensor) -> Tensor:
    if index.numel() == 0:
        # An empty Python list becomes a float tensor; it is still a valid
        # (empty) index.
        return index.to(torch.long)
    if index.is_floating_point() or index.dtype == torch.bool:
        raise TypeError(f"{name} must be an integer tensor, got {index.dtype}.")
    return index.to(torch.long)

btorch.sparse.conversion

Conversion between btorch sparse arrays, PyTorch and SciPy.

This module is the single place where foreign sparse objects are understood. Every higher-level API that accepts "a sparse matrix" calls :func:as_sparse, so all of them accept the same inputs and treat them the same way. Conversions never transpose and never densify.

Attributes

_LAYOUT_NAMES = {v: k for k, v in (_TORCH_LAYOUTS.items())} module-attribute

_TORCH_LAYOUTS = {'coo': torch.sparse_coo, 'csr': torch.sparse_csr, 'csc': torch.sparse_csc, 'bsr': torch.sparse_bsr, 'bsc': torch.sparse_bsc} module-attribute

Classes

COO

Bases: Sparse

Coordinate format: one index tuple and one value per stored entry.

COO supports any number of sparse dimensions. Entries may be unsorted and may contain duplicates; duplicates are summed by every operation, as in SciPy and PyTorch.

Two kinds of batch are supported and may be combined:

  • Shared pattern: values has leading batch dimensions, [*batch, nnz, *dense], and every batch member uses the same indices.
  • Different patterns: the first index rows are batch coordinates, so each batch member can have its own number of entries. Build these with :func:btorch.sparse.stack.

Parameters:

Name Type Description Default
indices Tensor

[n_index, nnz] integer coordinates. The rows are the batch coordinates (if any) followed by the sparse coordinates.

required
values Tensor

[*value_batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, *sparse, *dense).

required
batch_dim int | None

Total number of batch dimensions. Defaults to the number of leading value dimensions (a shared pattern).

None
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties of the given indices.

None
hints Hints | None

Performance expectations.

None
check bool

Validate index bounds.

True

Examples:

>>> import torch
>>> from btorch import sparse
>>> A = sparse.coo(torch.tensor([[0, 1], [2, 0]]),
...                torch.tensor([3.0, 5.0]), shape=(2, 3))
>>> A @ torch.tensor([1.0, 0.0, 2.0])
tensor([6., 5.])
Source code in btorch/sparse/coo.py
class COO(Sparse):
    """Coordinate format: one index tuple and one value per stored entry.

    COO supports any number of sparse dimensions. Entries may be unsorted and
    may contain duplicates; duplicates are summed by every operation, as in
    SciPy and PyTorch.

    Two kinds of batch are supported and may be combined:

    - *Shared pattern*: ``values`` has leading batch dimensions,
      ``[*batch, nnz, *dense]``, and every batch member uses the same indices.
    - *Different patterns*: the first index rows are batch coordinates, so each
      batch member can have its own number of entries. Build these with
      :func:`btorch.sparse.stack`.

    Args:
        indices: ``[n_index, nnz]`` integer coordinates. The rows are the
            batch coordinates (if any) followed by the sparse coordinates.
        values: ``[*value_batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, *sparse, *dense)``.
        batch_dim: Total number of batch dimensions. Defaults to the number
            of leading value dimensions (a shared pattern).
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties of the given indices.
        hints: Performance expectations.
        check: Validate index bounds.

    Examples:
        >>> import torch
        >>> from btorch import sparse
        >>> A = sparse.coo(torch.tensor([[0, 1], [2, 0]]),
        ...                torch.tensor([3.0, 5.0]), shape=(2, 3))
        >>> A @ torch.tensor([1.0, 0.0, 2.0])
        tensor([6., 5.])
    """

    format = "coo"

    def __init__(
        self,
        indices: Tensor,
        values: Tensor,
        shape: tuple[int, ...],
        *,
        batch_dim: int | None = None,
        dense_dim: int = 0,
        properties: Properties | None = None,
        hints: Hints | None = None,
        check: bool = True,
    ):
        values = _as_tensor(values)
        indices = _check_index("indices", _as_tensor(indices, device=values.device))
        shape = tuple(int(s) for s in shape)
        if indices.ndim != 2:
            raise ValueError(f"indices must be [n_index, nnz], got {indices.shape}.")
        n_index, nnz = indices.shape
        value_batch_dim = values.ndim - 1 - dense_dim
        if value_batch_dim < 0:
            raise ValueError(
                f"values with shape {tuple(values.shape)} cannot hold "
                f"{dense_dim} dense dimension(s) per entry."
            )
        if batch_dim is None:
            batch_dim = value_batch_dim
        index_batch_dim = batch_dim - value_batch_dim
        if index_batch_dim < 0:
            raise ValueError("batch_dim is smaller than the batch of `values`.")
        if len(shape) != value_batch_dim + n_index + dense_dim:
            raise ValueError(
                f"shape {shape} has {len(shape)} dimensions but indices/values "
                f"describe {value_batch_dim} value-batch + {n_index} indexed + "
                f"{dense_dim} dense."
            )
        if n_index - index_batch_dim < 1:
            raise ValueError("COO needs at least one sparse dimension.")
        if values.shape[value_batch_dim] != nnz:
            raise ValueError(
                f"values has {values.shape[value_batch_dim]} entries along its "
                f"entry axis but indices has {nnz}."
            )
        expected = (
            shape[:value_batch_dim] + (nnz,) + shape[len(shape) - dense_dim :]
            if dense_dim
            else shape[:value_batch_dim] + (nnz,)
        )
        if tuple(values.shape) != expected:
            raise ValueError(
                f"values has shape {tuple(values.shape)}, expected {expected}."
            )
        indexed = shape[value_batch_dim : value_batch_dim + n_index]
        if check and nnz > 0:
            lo = indices.amin(dim=1)
            hi = indices.amax(dim=1)
            for d, size in enumerate(indexed):
                if int(lo[d]) < 0 or int(hi[d]) >= size:
                    raise ValueError(
                        f"indices along indexed dimension {d} must be in "
                        f"[0, {size}), got range [{int(lo[d])}, {int(hi[d])}]."
                    )
        self._indices = indices
        self._values = values
        self._shape = shape
        self._batch_dim = batch_dim
        self._dense_dim = dense_dim
        self._value_batch_dim = value_batch_dim
        self.properties = properties or Properties()
        if self.properties.shared_pattern != bool(value_batch_dim):
            self.properties = self.properties.replace(
                shared_pattern=bool(value_batch_dim)
            )
        self.hints = hints or Hints()

    # ----------------------------------------------------------- accessors
    @property
    def nnz(self) -> int:
        return int(self._indices.shape[1])

    def indices(self) -> Tensor:
        """``[n_index, nnz]`` coordinates (PyTorch name)."""
        return self._indices

    def values(self) -> Tensor:
        """``[*value_batch, nnz, *dense]`` stored values (PyTorch name)."""
        return self._values

    @property
    def data(self) -> Tensor:
        """Stored values (SciPy name)."""
        return self._values

    @property
    def row(self) -> Tensor:
        """Row coordinate of each entry (two sparse dimensions only)."""
        self._require_matrix("row")
        return self._indices[-2]

    @property
    def col(self) -> Tensor:
        """Column coordinate of each entry (two sparse dimensions only)."""
        self._require_matrix("col")
        return self._indices[-1]

    def _require_matrix(self, what: str) -> None:
        if self.sparse_dim() != 2:
            raise ValueError(
                f"{what} needs exactly two sparse dimensions, this array has "
                f"{self.sparse_dim()}."
            )

    @property
    def _index_batch_dim(self) -> int:
        return self._batch_dim - self._value_batch_dim

    @property
    def _indexed_shape(self) -> tuple[int, ...]:
        """Sizes of the indexed (batch-coordinate + sparse) dimensions."""
        start = self._value_batch_dim
        return self._shape[start : start + self._indices.shape[0]]

    def _edge_index(self) -> tuple[Tensor | None, Tensor, Tensor]:
        """``(batch coordinates or None, row, col)`` for matrix products."""
        self._require_matrix("A matrix product")
        n_ib = self._index_batch_dim
        lead = self._indices[:n_ib] if n_ib else None
        return lead, self._indices[-2], self._indices[-1]

    # --------------------------------------------------------- construction
    def _like(self, indices: Tensor, values: Tensor, **changes) -> "COO":
        out = COO.__new__(COO)
        out.__dict__.update(self.__dict__)
        out._indices = indices
        out._values = values
        for key, value in changes.items():
            setattr(out, key, value)
        return out

    def with_values(self, values: Tensor) -> "COO":
        value_batch_dim = values.ndim - 1 - self._dense_dim
        tail = self._shape[self._value_batch_dim :]
        return COO(
            self._indices,
            values,
            tuple(values.shape[:value_batch_dim]) + tail,
            batch_dim=value_batch_dim + self._index_batch_dim,
            dense_dim=self._dense_dim,
            properties=self.properties,
            hints=self.hints,
            check=False,
        )

    def _map_tensors(self, index_fn, value_fn) -> "COO":
        return self._like(index_fn(self._indices), value_fn(self._values))

    # -------------------------------------------------------- canonical form
    def coalesce(self, return_map: bool = False) -> "COO" | tuple["COO", EdgeMap]:
        """Sort entries row-major and sum duplicates.

        Args:
            return_map: Also return the :class:`EdgeMap` from the old entries
                to the new ones, to move edge-aligned metadata consistently.

        Returns:
            The canonical COO, and the map if requested. The values of merged
            entries are summed, so gradients flow to every duplicate.
        """
        nnz = self.nnz
        if self.properties.canonical:
            edge_map = EdgeMap.identity(nnz, self._indices.device)
            return (self, edge_map) if return_map else self
        sizes = self._indexed_shape
        key = _ravel(self._indices, sizes)
        if self.properties.sorted:
            order = None
            sorted_key = key
        else:
            sorted_key, order = torch.sort(key, stable=True)
        unique_key, inverse = torch.unique_consecutive(sorted_key, return_inverse=True)
        if order is None:
            target = inverse
        else:
            target = torch.empty_like(inverse)
            target[order] = inverse
        edge_map = EdgeMap(target, int(unique_key.shape[0]))
        out = self._like(
            _unravel(unique_key, sizes),
            edge_map.sum(self._values, dim=self._value_batch_dim),
            properties=self.properties.replace(sorted=True, unique=True),
        )
        return (out, edge_map) if return_map else out

    def sum_duplicates(self) -> "COO":
        """SciPy-style alias of :meth:`coalesce` (returns a new array)."""
        return self.coalesce()

    # -------------------------------------------------------------- formats
    def tocoo(self) -> "COO":
        return self

    def _compressed(self, return_map: bool):
        """Canonical entries, their row pointers and the edge map."""
        self._require_matrix("CSR/CSC conversion")
        if self._index_batch_dim:
            raise NotImplementedError(
                "A batch of different sparsity patterns is stored as batched "
                "COO; compressed (CSR/CSC) storage for it is not implemented."
            )
        coo, edge_map = self.coalesce(return_map=True)
        n_rows = coo.sparse_shape[0]
        counts = torch.bincount(coo._indices[0], minlength=n_rows)
        pointer = torch.zeros(n_rows + 1, dtype=torch.long, device=counts.device)
        pointer[1:] = torch.cumsum(counts, 0)
        return coo, pointer, edge_map

    def tocsr(self, return_map: bool = False):
        """Convert to canonical CSR (sorted, duplicates summed).

        Args:
            return_map: Also return the :class:`EdgeMap` from the COO entries
                to the CSR entries.
        """
        from .csr import CSR

        coo, crow, edge_map = self._compressed(return_map)
        out = CSR(
            crow,
            coo._indices[1],
            coo._values,
            coo._shape,
            dense_dim=self._dense_dim,
            properties=coo.properties,
            hints=self.hints,
            check=False,
        )
        return (out, edge_map) if return_map else out

    def tocsc(self, return_map: bool = False):
        """Convert to canonical CSC (column-major, duplicates summed)."""
        result = self.transpose().tocsr(return_map)
        if return_map:
            return result[0].transpose(), result[1]
        return result.transpose()

    def transpose(self) -> "COO":
        self._require_matrix("transpose")
        idx = self._indices
        swapped = torch.cat([idx[:-2], idx[-1:], idx[-2:-1]])
        shape = list(self._shape)
        i = self._batch_dim
        shape[i], shape[i + 1] = shape[i + 1], shape[i]
        return self._like(
            swapped,
            self._values,
            _shape=tuple(shape),
            properties=self.properties.replace(sorted=False, triangular=None),
        )

    def to_dense(self) -> Tensor:
        n_vb = self._value_batch_dim
        sizes = self._indexed_shape
        dense = (
            self._shape[len(self._shape) - self._dense_dim :] if self._dense_dim else ()
        )
        key = _ravel(self._indices, sizes)
        flat = self._values.new_zeros(*self._shape[:n_vb], math.prod(sizes), *dense)
        flat = flat.index_add(n_vb, key, self._values)
        return flat.reshape(self._shape)
Attributes
col property

Column coordinate of each entry (two sparse dimensions only).

data property

Stored values (SciPy name).

row property

Row coordinate of each entry (two sparse dimensions only).

Methods:
coalesce(return_map=False)

Sort entries row-major and sum duplicates.

Parameters:

Name Type Description Default
return_map bool

Also return the :class:EdgeMap from the old entries to the new ones, to move edge-aligned metadata consistently.

False

Returns:

Type Description
'COO' | tuple['COO', EdgeMap]

The canonical COO, and the map if requested. The values of merged

'COO' | tuple['COO', EdgeMap]

entries are summed, so gradients flow to every duplicate.

Source code in btorch/sparse/coo.py
def coalesce(self, return_map: bool = False) -> "COO" | tuple["COO", EdgeMap]:
    """Sort entries row-major and sum duplicates.

    Args:
        return_map: Also return the :class:`EdgeMap` from the old entries
            to the new ones, to move edge-aligned metadata consistently.

    Returns:
        The canonical COO, and the map if requested. The values of merged
        entries are summed, so gradients flow to every duplicate.
    """
    nnz = self.nnz
    if self.properties.canonical:
        edge_map = EdgeMap.identity(nnz, self._indices.device)
        return (self, edge_map) if return_map else self
    sizes = self._indexed_shape
    key = _ravel(self._indices, sizes)
    if self.properties.sorted:
        order = None
        sorted_key = key
    else:
        sorted_key, order = torch.sort(key, stable=True)
    unique_key, inverse = torch.unique_consecutive(sorted_key, return_inverse=True)
    if order is None:
        target = inverse
    else:
        target = torch.empty_like(inverse)
        target[order] = inverse
    edge_map = EdgeMap(target, int(unique_key.shape[0]))
    out = self._like(
        _unravel(unique_key, sizes),
        edge_map.sum(self._values, dim=self._value_batch_dim),
        properties=self.properties.replace(sorted=True, unique=True),
    )
    return (out, edge_map) if return_map else out
indices()

[n_index, nnz] coordinates (PyTorch name).

Source code in btorch/sparse/coo.py
def indices(self) -> Tensor:
    """``[n_index, nnz]`` coordinates (PyTorch name)."""
    return self._indices
sum_duplicates()

SciPy-style alias of :meth:coalesce (returns a new array).

Source code in btorch/sparse/coo.py
def sum_duplicates(self) -> "COO":
    """SciPy-style alias of :meth:`coalesce` (returns a new array)."""
    return self.coalesce()
tocsc(return_map=False)

Convert to canonical CSC (column-major, duplicates summed).

Source code in btorch/sparse/coo.py
def tocsc(self, return_map: bool = False):
    """Convert to canonical CSC (column-major, duplicates summed)."""
    result = self.transpose().tocsr(return_map)
    if return_map:
        return result[0].transpose(), result[1]
    return result.transpose()
tocsr(return_map=False)

Convert to canonical CSR (sorted, duplicates summed).

Parameters:

Name Type Description Default
return_map bool

Also return the :class:EdgeMap from the COO entries to the CSR entries.

False
Source code in btorch/sparse/coo.py
def tocsr(self, return_map: bool = False):
    """Convert to canonical CSR (sorted, duplicates summed).

    Args:
        return_map: Also return the :class:`EdgeMap` from the COO entries
            to the CSR entries.
    """
    from .csr import CSR

    coo, crow, edge_map = self._compressed(return_map)
    out = CSR(
        crow,
        coo._indices[1],
        coo._values,
        coo._shape,
        dense_dim=self._dense_dim,
        properties=coo.properties,
        hints=self.hints,
        check=False,
    )
    return (out, edge_map) if return_map else out
values()

[*value_batch, nnz, *dense] stored values (PyTorch name).

Source code in btorch/sparse/coo.py
def values(self) -> Tensor:
    """``[*value_batch, nnz, *dense]`` stored values (PyTorch name)."""
    return self._values

CSC

Bases: _Compressed

Compressed sparse column format (exactly two sparse dimensions).

Parameters:

Name Type Description Default
pointer Tensor

[n_cols + 1] column pointers (ccol_indices).

required
minor Tensor

[nnz] row of each entry (row_indices).

required
values Tensor

[*batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, n_rows, n_cols, *dense).

required
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties (sorted refers to column-major order).

None
hints Hints | None

Performance expectations.

None
check bool

Validate the pointer and index ranges.

True
Source code in btorch/sparse/csr.py
class CSC(_Compressed):
    """Compressed sparse column format (exactly two sparse dimensions).

    Args:
        pointer: ``[n_cols + 1]`` column pointers (``ccol_indices``).
        minor: ``[nnz]`` row of each entry (``row_indices``).
        values: ``[*batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, n_rows, n_cols, *dense)``.
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties (``sorted`` refers to
            column-major order).
        hints: Performance expectations.
        check: Validate the pointer and index ranges.
    """

    format = "csc"
    _major_axis = 1

    def ccol_indices(self) -> Tensor:
        """``[n_cols + 1]`` column pointers (PyTorch name)."""
        return self._pointer

    def row_indices(self) -> Tensor:
        """``[nnz]`` row of each entry (PyTorch name)."""
        return self._minor

    def col_indices(self) -> Tensor:
        """``[nnz]`` column of each entry, expanded from the pointers."""
        return self._major_indices()

    def tocsr(self, return_map: bool = False):
        return self.tocoo().tocsr(return_map)

    def tocsc(self, return_map: bool = False):
        """Return ``self`` (already CSC; entries are left as stored).

        Use :meth:`coalesce` to sort rows and merge duplicates.
        """
        if return_map:
            return self, EdgeMap.identity(self.nnz, self._minor.device)
        return self

    def coalesce(self, return_map: bool = False):
        """Canonical CSC: sorted rows, duplicates summed."""
        return self.tocoo().tocsc(return_map)

    def transpose(self) -> CSR:
        """Transpose without copying: the same arrays read as CSR."""
        return self._like(
            CSR,
            _shape=self._swapped_shape(),
            properties=self.properties.replace(triangular=None),
        )
Methods:
ccol_indices()

[n_cols + 1] column pointers (PyTorch name).

Source code in btorch/sparse/csr.py
def ccol_indices(self) -> Tensor:
    """``[n_cols + 1]`` column pointers (PyTorch name)."""
    return self._pointer
coalesce(return_map=False)

Canonical CSC: sorted rows, duplicates summed.

Source code in btorch/sparse/csr.py
def coalesce(self, return_map: bool = False):
    """Canonical CSC: sorted rows, duplicates summed."""
    return self.tocoo().tocsc(return_map)
col_indices()

[nnz] column of each entry, expanded from the pointers.

Source code in btorch/sparse/csr.py
def col_indices(self) -> Tensor:
    """``[nnz]`` column of each entry, expanded from the pointers."""
    return self._major_indices()
row_indices()

[nnz] row of each entry (PyTorch name).

Source code in btorch/sparse/csr.py
def row_indices(self) -> Tensor:
    """``[nnz]`` row of each entry (PyTorch name)."""
    return self._minor
tocsc(return_map=False)

Return self (already CSC; entries are left as stored).

Use :meth:coalesce to sort rows and merge duplicates.

Source code in btorch/sparse/csr.py
def tocsc(self, return_map: bool = False):
    """Return ``self`` (already CSC; entries are left as stored).

    Use :meth:`coalesce` to sort rows and merge duplicates.
    """
    if return_map:
        return self, EdgeMap.identity(self.nnz, self._minor.device)
    return self
transpose()

Transpose without copying: the same arrays read as CSR.

Source code in btorch/sparse/csr.py
def transpose(self) -> CSR:
    """Transpose without copying: the same arrays read as CSR."""
    return self._like(
        CSR,
        _shape=self._swapped_shape(),
        properties=self.properties.replace(triangular=None),
    )

CSR

Bases: _Compressed

Compressed sparse row format (exactly two sparse dimensions).

Batch members share one sparsity pattern: crow_indices and col_indices are stored once and values is [*batch, nnz, *dense]. This is the natural layout for ensembles and parameter sweeps over a fixed topology.

Parameters:

Name Type Description Default
pointer Tensor

[n_rows + 1] row pointers (crow_indices).

required
minor Tensor

[nnz] column of each entry (col_indices).

required
values Tensor

[*batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, n_rows, n_cols, *dense).

required
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties.

None
hints Hints | None

Performance expectations.

None
check bool

Validate the pointer and index ranges.

True

Examples:

>>> import torch
>>> from btorch import sparse
>>> A = sparse.csr(torch.tensor([0, 1, 2]), torch.tensor([2, 0]),
...                torch.tensor([3.0, 5.0]), shape=(2, 3))
>>> A.indptr
tensor([0, 1, 2])
>>> A @ torch.tensor([1.0, 0.0, 2.0])
tensor([6., 5.])
Source code in btorch/sparse/csr.py
class CSR(_Compressed):
    """Compressed sparse row format (exactly two sparse dimensions).

    Batch members share one sparsity pattern: ``crow_indices`` and
    ``col_indices`` are stored once and ``values`` is ``[*batch, nnz,
    *dense]``. This is the natural layout for ensembles and parameter sweeps
    over a fixed topology.

    Args:
        pointer: ``[n_rows + 1]`` row pointers (``crow_indices``).
        minor: ``[nnz]`` column of each entry (``col_indices``).
        values: ``[*batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, n_rows, n_cols, *dense)``.
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties.
        hints: Performance expectations.
        check: Validate the pointer and index ranges.

    Examples:
        >>> import torch
        >>> from btorch import sparse
        >>> A = sparse.csr(torch.tensor([0, 1, 2]), torch.tensor([2, 0]),
        ...                torch.tensor([3.0, 5.0]), shape=(2, 3))
        >>> A.indptr
        tensor([0, 1, 2])
        >>> A @ torch.tensor([1.0, 0.0, 2.0])
        tensor([6., 5.])
    """

    format = "csr"
    _major_axis = 0

    def crow_indices(self) -> Tensor:
        """``[n_rows + 1]`` row pointers (PyTorch name)."""
        return self._pointer

    def col_indices(self) -> Tensor:
        """``[nnz]`` column of each entry (PyTorch name)."""
        return self._minor

    def row_indices(self) -> Tensor:
        """``[nnz]`` row of each entry, expanded from the pointers."""
        return self._major_indices()

    def tocsr(self, return_map: bool = False):
        """Return ``self`` (already CSR; entries are left as stored).

        Use :meth:`coalesce` to sort columns and merge duplicates.
        """
        if return_map:
            return self, EdgeMap.identity(self.nnz, self._minor.device)
        return self

    def coalesce(self, return_map: bool = False):
        """Canonical CSR: sorted columns, duplicates summed."""
        return self.tocoo().tocsr(return_map)

    def tocsc(self, return_map: bool = False):
        return self.tocoo().tocsc(return_map)

    def transpose(self) -> "CSC":
        """Transpose without copying: the same arrays read as CSC."""
        return self._like(
            CSC,
            _shape=self._swapped_shape(),
            properties=self.properties.replace(triangular=None),
        )
Methods:
coalesce(return_map=False)

Canonical CSR: sorted columns, duplicates summed.

Source code in btorch/sparse/csr.py
def coalesce(self, return_map: bool = False):
    """Canonical CSR: sorted columns, duplicates summed."""
    return self.tocoo().tocsr(return_map)
col_indices()

[nnz] column of each entry (PyTorch name).

Source code in btorch/sparse/csr.py
def col_indices(self) -> Tensor:
    """``[nnz]`` column of each entry (PyTorch name)."""
    return self._minor
crow_indices()

[n_rows + 1] row pointers (PyTorch name).

Source code in btorch/sparse/csr.py
def crow_indices(self) -> Tensor:
    """``[n_rows + 1]`` row pointers (PyTorch name)."""
    return self._pointer
row_indices()

[nnz] row of each entry, expanded from the pointers.

Source code in btorch/sparse/csr.py
def row_indices(self) -> Tensor:
    """``[nnz]`` row of each entry, expanded from the pointers."""
    return self._major_indices()
tocsr(return_map=False)

Return self (already CSR; entries are left as stored).

Use :meth:coalesce to sort columns and merge duplicates.

Source code in btorch/sparse/csr.py
def tocsr(self, return_map: bool = False):
    """Return ``self`` (already CSR; entries are left as stored).

    Use :meth:`coalesce` to sort columns and merge duplicates.
    """
    if return_map:
        return self, EdgeMap.identity(self.nnz, self._minor.device)
    return self
transpose()

Transpose without copying: the same arrays read as CSC.

Source code in btorch/sparse/csr.py
def transpose(self) -> "CSC":
    """Transpose without copying: the same arrays read as CSC."""
    return self._like(
        CSC,
        _shape=self._swapped_shape(),
        properties=self.properties.replace(triangular=None),
    )

Properties dataclass

Structural facts about a stored sparse representation.

A True value is a guarantee; False means "not known", never "known to be violated".

Parameters:

Name Type Description Default
sorted bool

Entries are in lexicographic (row-major) index order.

False
unique bool

No index tuple is stored twice.

False
symmetric bool

Stored values satisfy A == A.T.

False
structurally_symmetric bool

The sparsity pattern is symmetric.

False
triangular str | None

"lower", "upper" or None.

None
fixed_pattern bool

The pattern is never mutated (no rewiring).

False
shared_pattern bool

A batch of matrices shares one pattern.

False
Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class Properties:
    """Structural facts about a stored sparse representation.

    A ``True`` value is a guarantee; ``False`` means "not known", never
    "known to be violated".

    Args:
        sorted: Entries are in lexicographic (row-major) index order.
        unique: No index tuple is stored twice.
        symmetric: Stored values satisfy ``A == A.T``.
        structurally_symmetric: The sparsity pattern is symmetric.
        triangular: ``"lower"``, ``"upper"`` or ``None``.
        fixed_pattern: The pattern is never mutated (no rewiring).
        shared_pattern: A batch of matrices shares one pattern.
    """

    sorted: bool = False
    unique: bool = False
    symmetric: bool = False
    structurally_symmetric: bool = False
    triangular: str | None = None
    fixed_pattern: bool = False
    shared_pattern: bool = False

    @property
    def canonical(self) -> bool:
        """Whether entries are sorted and free of duplicates."""
        return self.sorted and self.unique

    def replace(self, **changes) -> "Properties":
        """Return a copy with some fields changed."""
        return replace(self, **changes)
Attributes
canonical property

Whether entries are sorted and free of duplicates.

Methods:
replace(**changes)

Return a copy with some fields changed.

Source code in btorch/sparse/properties.py
def replace(self, **changes) -> "Properties":
    """Return a copy with some fields changed."""
    return replace(self, **changes)

Sparse

Sparse array with logical shape [*batch, *sparse, *dense].

Sparse is the format-agnostic interface. It describes what the array is (shape, dtype, device, number of stored entries) and offers the operations every format supports. Format-specific data such as indptr is only available on the concrete classes (:class:~btorch.sparse.COO, :class:~btorch.sparse.CSR, :class:~btorch.sparse.CSC), obtained with tocsr() / as_csr() and friends.

The three shape groups are:

  • batch_shape: independent sparse arrays (for example an ensemble of networks).
  • sparse_shape: the dimensions that are stored sparsely.
  • dense_shape: a dense payload attached to every stored entry.

Stored values have shape [*value_batch, nnz, *dense_shape]. A batch whose members share one sparsity pattern stores the pattern once and only the values per member.

Sparse is a plain Python object holding tensors; it is not a torch.Tensor subclass. Matrix products follow standard linear algebra: for A.shape == (M, N), A @ x maps a length-N vector to a length-M vector. Conversions never transpose.

Source code in btorch/sparse/base.py
class Sparse:
    """Sparse array with logical shape ``[*batch, *sparse, *dense]``.

    ``Sparse`` is the format-agnostic interface. It describes *what* the array
    is (shape, dtype, device, number of stored entries) and offers the
    operations every format supports. Format-specific data such as ``indptr``
    is only available on the concrete classes (:class:`~btorch.sparse.COO`,
    :class:`~btorch.sparse.CSR`, :class:`~btorch.sparse.CSC`), obtained with
    ``tocsr()`` / ``as_csr()`` and friends.

    The three shape groups are:

    - ``batch_shape``: independent sparse arrays (for example an ensemble of
      networks).
    - ``sparse_shape``: the dimensions that are stored sparsely.
    - ``dense_shape``: a dense payload attached to every stored entry.

    Stored values have shape ``[*value_batch, nnz, *dense_shape]``. A batch
    whose members share one sparsity pattern stores the pattern once and only
    the values per member.

    ``Sparse`` is a plain Python object holding tensors; it is not a
    ``torch.Tensor`` subclass. Matrix products follow standard linear algebra:
    for ``A.shape == (M, N)``, ``A @ x`` maps a length-``N`` vector to a
    length-``M`` vector. Conversions never transpose.
    """

    format: str = "sparse"
    # Let ``ndarray @ A`` reach ``__rmatmul__`` instead of NumPy treating the
    # sparse array as an object scalar.
    __array_ufunc__ = None

    _values: Tensor
    _shape: tuple[int, ...]
    _batch_dim: int
    _dense_dim: int
    properties: Properties
    hints: Hints

    # ------------------------------------------------------------------ shape
    @property
    def shape(self) -> tuple[int, ...]:
        """Logical shape ``(*batch, *sparse, *dense)``."""
        return self._shape

    @property
    def ndim(self) -> int:
        return len(self._shape)

    def batch_dim(self) -> int:
        """Number of batch dimensions."""
        return self._batch_dim

    def dense_dim(self) -> int:
        """Number of dense (per-entry payload) dimensions."""
        return self._dense_dim

    def sparse_dim(self) -> int:
        """Number of sparsely stored dimensions."""
        return self.ndim - self._batch_dim - self._dense_dim

    @property
    def batch_shape(self) -> tuple[int, ...]:
        return self._shape[: self._batch_dim]

    @property
    def sparse_shape(self) -> tuple[int, ...]:
        return self._shape[self._batch_dim : self.ndim - self._dense_dim]

    @property
    def dense_shape(self) -> tuple[int, ...]:
        return self._shape[self.ndim - self._dense_dim :]

    @property
    def dtype(self) -> torch.dtype:
        return self._values.dtype

    @property
    def device(self) -> torch.device:
        return self._values.device

    @property
    def nnz(self) -> int:
        """Number of stored entries (of one batch member for a shared pattern,
        of all members together otherwise)."""
        raise NotImplementedError

    @property
    def requires_grad(self) -> bool:
        return self._values.requires_grad

    # ------------------------------------------------------- format changes
    def tocoo(self) -> "COO":
        """Convert to COO (may allocate)."""
        raise NotImplementedError

    def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
        """Convert to CSR (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
        """Convert to CSC (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tobsr(self, blocksize: tuple[int, int]):
        """Convert to BSR; not implemented as a native format.

        Use ``to_torch(layout="bsr", blocksize=...)`` or
        ``to_scipy(format="bsr")`` to export block storage.
        """
        raise NotImplementedError(
            "BSR is not a native btorch format yet; export with "
            "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
        )

    def _as(self, fmt: str):
        if self.format != fmt:
            hint = (
                "BSR is not a native format; export with to_torch(layout='bsr')."
                if fmt == "bsr"
                else f"Call to{fmt}() to convert explicitly."
            )
            raise TypeError(
                f"This sparse array is stored as {self.format.upper()}, not "
                f"{fmt.upper()}; as_{fmt}() never converts. {hint}"
            )
        return self

    def as_coo(self) -> "COO":
        """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
        return self._as("coo")

    def as_csr(self) -> "CSR":
        """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
        return self._as("csr")

    def as_csc(self) -> "CSC":
        """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
        return self._as("csc")

    def as_bsr(self, blocksize: tuple[int, int] | None = None):
        """BSR is not a native format; always raises ``TypeError``."""
        return self._as("bsr")

    # -------------------------------------------------------------- interop
    @classmethod
    def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
        """Wrap a ``torch`` sparse tensor (see
        :func:`btorch.sparse.from_torch`)."""
        from .conversion import from_torch

        return from_torch(tensor, batch_dim=batch_dim)

    @classmethod
    def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
        """Convert a SciPy sparse array or matrix (see
        :func:`btorch.sparse.from_scipy`)."""
        from .conversion import from_scipy

        return from_scipy(array, device=device, dtype=dtype)

    def to_torch(
        self, layout: str | torch.layout | None = None, **kwargs: Any
    ) -> Tensor:
        """Export as a ``torch`` sparse tensor.

        Args:
            layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
                (or the ``torch.sparse_*`` layout). Defaults to the stored
                format.
            **kwargs: ``blocksize`` for the block layouts.
        """
        from .conversion import to_torch

        return to_torch(self, layout, **kwargs)

    def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
        """Export as a ``scipy.sparse`` array (CPU, detached).

        Args:
            format: Any SciPy format name; defaults to the stored format.
            **kwargs: ``blocksize`` for ``"bsr"``.
        """
        from .conversion import to_scipy

        return to_scipy(self, format, **kwargs)

    def to_dense(self) -> Tensor:
        """Materialise as a dense tensor of shape :attr:`shape`."""
        return self.tocoo().to_dense()

    # ------------------------------------------------------- tensor handling
    def with_values(self, values: Tensor) -> "Sparse":
        """Return an array with the same pattern and new values.

        ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
        shape creates a shared-pattern batch.
        """
        raise NotImplementedError

    def _map_tensors(self, index_fn, value_fn) -> "Sparse":
        """Apply ``index_fn`` to index tensors and ``value_fn`` to values."""
        raise NotImplementedError

    def to(self, *args, **kwargs) -> "Sparse":
        """Move to a device and/or cast the values (indices stay integer)."""
        device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

        return self._map_tensors(
            lambda index: index.to(device=device),
            lambda values: values.to(device=device, dtype=dtype),
        )

    def cpu(self) -> "Sparse":
        return self.to("cpu")

    def cuda(self, device=None) -> "Sparse":
        return self.to("cuda" if device is None else device)

    def float(self) -> "Sparse":
        return self.to(torch.float32)

    def double(self) -> "Sparse":
        return self.to(torch.float64)

    def detach(self) -> "Sparse":
        return self.with_values(self._values.detach())

    # ------------------------------------------------------------- products
    def matvec(self, x: Tensor) -> Tensor:
        """Apply the operator along the last axis of ``x``.

        See :func:`btorch.sparse.matvec`.
        """
        from .ops import matvec

        return matvec(self, x)

    def rmatvec(self, x: Tensor) -> Tensor:
        """Apply the transposed operator along the last axis of ``x``."""
        from .ops import rmatvec

        return rmatvec(self, x)

    def __matmul__(self, other):
        from .ops import matmul

        return matmul(self, other)

    def __rmatmul__(self, other):
        from .ops import matmul

        return matmul(other, self)

    @property
    def T(self) -> "Sparse":
        """Transpose of the two sparse dimensions."""
        return self.transpose()

    def transpose(self) -> "Sparse":
        raise NotImplementedError

    def __repr__(self) -> str:
        parts = [f"shape={self.shape}", f"nnz={self.nnz}", f"dtype={self.dtype}"]
        if self.batch_dim():
            parts.append(f"batch_shape={self.batch_shape}")
        if self.dense_dim():
            parts.append(f"dense_shape={self.dense_shape}")
        if self.device.type != "cpu":
            parts.append(f"device={self.device}")
        return f"{type(self).__name__}({', '.join(parts)})"
Attributes
T property

Transpose of the two sparse dimensions.

nnz property

Number of stored entries (of one batch member for a shared pattern, of all members together otherwise).

shape property

Logical shape (*batch, *sparse, *dense).

Methods:
as_bsr(blocksize=None)

BSR is not a native format; always raises TypeError.

Source code in btorch/sparse/base.py
def as_bsr(self, blocksize: tuple[int, int] | None = None):
    """BSR is not a native format; always raises ``TypeError``."""
    return self._as("bsr")
as_coo()

Return self if it is stored as COO, else raise TypeError.

Source code in btorch/sparse/base.py
def as_coo(self) -> "COO":
    """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
    return self._as("coo")
as_csc()

Return self if it is stored as CSC, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csc(self) -> "CSC":
    """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
    return self._as("csc")
as_csr()

Return self if it is stored as CSR, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csr(self) -> "CSR":
    """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
    return self._as("csr")
batch_dim()

Number of batch dimensions.

Source code in btorch/sparse/base.py
def batch_dim(self) -> int:
    """Number of batch dimensions."""
    return self._batch_dim
dense_dim()

Number of dense (per-entry payload) dimensions.

Source code in btorch/sparse/base.py
def dense_dim(self) -> int:
    """Number of dense (per-entry payload) dimensions."""
    return self._dense_dim
from_scipy(array, *, device=None, dtype=None) classmethod

Convert a SciPy sparse array or matrix (see :func:btorch.sparse.from_scipy).

Source code in btorch/sparse/base.py
@classmethod
def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
    """Convert a SciPy sparse array or matrix (see
    :func:`btorch.sparse.from_scipy`)."""
    from .conversion import from_scipy

    return from_scipy(array, device=device, dtype=dtype)
from_torch(tensor, *, batch_dim=0) classmethod

Wrap a torch sparse tensor (see :func:btorch.sparse.from_torch).

Source code in btorch/sparse/base.py
@classmethod
def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
    """Wrap a ``torch`` sparse tensor (see
    :func:`btorch.sparse.from_torch`)."""
    from .conversion import from_torch

    return from_torch(tensor, batch_dim=batch_dim)
matvec(x)

Apply the operator along the last axis of x.

See :func:btorch.sparse.matvec.

Source code in btorch/sparse/base.py
def matvec(self, x: Tensor) -> Tensor:
    """Apply the operator along the last axis of ``x``.

    See :func:`btorch.sparse.matvec`.
    """
    from .ops import matvec

    return matvec(self, x)
rmatvec(x)

Apply the transposed operator along the last axis of x.

Source code in btorch/sparse/base.py
def rmatvec(self, x: Tensor) -> Tensor:
    """Apply the transposed operator along the last axis of ``x``."""
    from .ops import rmatvec

    return rmatvec(self, x)
sparse_dim()

Number of sparsely stored dimensions.

Source code in btorch/sparse/base.py
def sparse_dim(self) -> int:
    """Number of sparsely stored dimensions."""
    return self.ndim - self._batch_dim - self._dense_dim
to(*args, **kwargs)

Move to a device and/or cast the values (indices stay integer).

Source code in btorch/sparse/base.py
def to(self, *args, **kwargs) -> "Sparse":
    """Move to a device and/or cast the values (indices stay integer)."""
    device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

    return self._map_tensors(
        lambda index: index.to(device=device),
        lambda values: values.to(device=device, dtype=dtype),
    )
to_dense()

Materialise as a dense tensor of shape :attr:shape.

Source code in btorch/sparse/base.py
def to_dense(self) -> Tensor:
    """Materialise as a dense tensor of shape :attr:`shape`."""
    return self.tocoo().to_dense()
to_scipy(format=None, **kwargs)

Export as a scipy.sparse array (CPU, detached).

Parameters:

Name Type Description Default
format str | None

Any SciPy format name; defaults to the stored format.

None
**kwargs Any

blocksize for "bsr".

{}
Source code in btorch/sparse/base.py
def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
    """Export as a ``scipy.sparse`` array (CPU, detached).

    Args:
        format: Any SciPy format name; defaults to the stored format.
        **kwargs: ``blocksize`` for ``"bsr"``.
    """
    from .conversion import to_scipy

    return to_scipy(self, format, **kwargs)
to_torch(layout=None, **kwargs)

Export as a torch sparse tensor.

Parameters:

Name Type Description Default
layout str | layout | None

"coo", "csr", "csc", "bsr" or "bsc" (or the torch.sparse_* layout). Defaults to the stored format.

None
**kwargs Any

blocksize for the block layouts.

{}
Source code in btorch/sparse/base.py
def to_torch(
    self, layout: str | torch.layout | None = None, **kwargs: Any
) -> Tensor:
    """Export as a ``torch`` sparse tensor.

    Args:
        layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
            (or the ``torch.sparse_*`` layout). Defaults to the stored
            format.
        **kwargs: ``blocksize`` for the block layouts.
    """
    from .conversion import to_torch

    return to_torch(self, layout, **kwargs)
tobsr(blocksize)

Convert to BSR; not implemented as a native format.

Use to_torch(layout="bsr", blocksize=...) or to_scipy(format="bsr") to export block storage.

Source code in btorch/sparse/base.py
def tobsr(self, blocksize: tuple[int, int]):
    """Convert to BSR; not implemented as a native format.

    Use ``to_torch(layout="bsr", blocksize=...)`` or
    ``to_scipy(format="bsr")`` to export block storage.
    """
    raise NotImplementedError(
        "BSR is not a native btorch format yet; export with "
        "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
    )
tocoo()

Convert to COO (may allocate).

Source code in btorch/sparse/base.py
def tocoo(self) -> "COO":
    """Convert to COO (may allocate)."""
    raise NotImplementedError
tocsc(return_map=False)

Convert to CSC (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
    """Convert to CSC (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
tocsr(return_map=False)

Convert to CSR (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
    """Convert to CSR (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
with_values(values)

Return an array with the same pattern and new values.

values is [*batch, nnz, *dense]; a different leading batch shape creates a shared-pattern batch.

Source code in btorch/sparse/base.py
def with_values(self, values: Tensor) -> "Sparse":
    """Return an array with the same pattern and new values.

    ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
    shape creates a shared-pattern batch.
    """
    raise NotImplementedError

Functions:

_expand_batch_coo(A)

Indices/values of a torch COO tensor with explicit batch coordinates.

Source code in btorch/sparse/conversion.py
def _expand_batch_coo(A: COO) -> tuple[Tensor, Tensor, int]:
    """Indices/values of a torch COO tensor with explicit batch coordinates."""
    n_vb = A._value_batch_dim
    indices, values = A._indices, A._values
    if n_vb == 0:
        return indices, values, indices.shape[0]
    batch = A.shape[:n_vb]
    nnz = A.nnz
    grids = torch.meshgrid(
        *[torch.arange(b, device=indices.device) for b in batch], indexing="ij"
    )
    n_member = grids[0].numel()
    batch_idx = torch.stack([g.reshape(-1) for g in grids])  # [n_vb, G]
    batch_idx = batch_idx.repeat_interleave(nnz, dim=1)
    full = torch.cat([batch_idx, indices.repeat(1, n_member)])
    values = values.reshape(n_member * nnz, *values.shape[n_vb + 1 :])
    return full, values, full.shape[0]

_is_scipy_sparse(obj)

Source code in btorch/sparse/conversion.py
def _is_scipy_sparse(obj: Any) -> bool:
    # Cheap module check first so SciPy is only imported for SciPy objects.
    if not type(obj).__module__.startswith("scipy.sparse"):
        return False
    import scipy.sparse

    return scipy.sparse.issparse(obj)

as_sparse(obj, *, format=None, device=None, dtype=None, batch_dim=0)

Interpret obj as a btorch sparse array.

This is the one conversion entry point: it accepts a btorch :class:Sparse, a PyTorch sparse tensor, or a SciPy sparse array/matrix. The orientation is never changed.

Parameters:

Name Type Description Default
obj Any

Sparse object of any supported library.

required
format str | None

Optional target format ("coo", "csr" or "csc").

None
device device | str | None

Optional target device.

None
dtype dtype | None

Optional value dtype.

None
batch_dim int

Leading batch dimensions of a PyTorch COO tensor (see :func:from_torch).

0

Returns:

Name Type Description
A Sparse

class:Sparse (the same object if nothing had to change).

Raises:

Type Description
TypeError

For dense tensors, arrays and unsupported types; dense data is never sparsified implicitly.

Source code in btorch/sparse/conversion.py
def as_sparse(
    obj: Any,
    *,
    format: str | None = None,
    device: torch.device | str | None = None,
    dtype: torch.dtype | None = None,
    batch_dim: int = 0,
) -> Sparse:
    """Interpret ``obj`` as a btorch sparse array.

    This is the one conversion entry point: it accepts a btorch
    :class:`Sparse`, a PyTorch sparse tensor, or a SciPy sparse array/matrix.
    The orientation is never changed.

    Args:
        obj: Sparse object of any supported library.
        format: Optional target format (``"coo"``, ``"csr"`` or ``"csc"``).
        device: Optional target device.
        dtype: Optional value dtype.
        batch_dim: Leading batch dimensions of a PyTorch COO tensor (see
            :func:`from_torch`).

    Returns:
        A :class:`Sparse` (the same object if nothing had to change).

    Raises:
        TypeError: For dense tensors, arrays and unsupported types; dense
            data is never sparsified implicitly.
    """
    if isinstance(obj, Sparse):
        out = obj
    elif isinstance(obj, Tensor):
        out = from_torch(obj, batch_dim=batch_dim)
    elif _is_scipy_sparse(obj):
        out = from_scipy(obj)
    else:
        raise TypeError(
            f"Cannot interpret {type(obj).__name__} as a sparse array. Expected "
            "a btorch Sparse, a torch sparse tensor or a SciPy sparse array."
        )
    if device is not None or dtype is not None:
        out = out.to(device=device, dtype=dtype)
    if format is not None and out.format != format:
        if format not in ("coo", "csr", "csc"):
            raise ValueError(
                f"Unknown or non-native sparse format {format!r}; native formats "
                "are 'coo', 'csr' and 'csc'."
            )
        out = getattr(out, f"to{format}")()
    return out

from_dense(tensor)

Build a COO array from the non-zero entries of a dense tensor.

Every dimension becomes a sparse dimension. Values stay connected to tensor for autograd.

Source code in btorch/sparse/conversion.py
def from_dense(tensor: Tensor) -> COO:
    """Build a COO array from the non-zero entries of a dense tensor.

    Every dimension becomes a sparse dimension. Values stay connected to
    ``tensor`` for autograd.
    """
    if tensor.layout != torch.strided:
        raise TypeError("from_dense expects a dense tensor.")
    indices = tensor.nonzero().T
    return COO(
        indices,
        tensor[tuple(indices)],
        tuple(tensor.shape),
        properties=Properties(sorted=True, unique=True),
        check=False,
    )

from_scipy(array, *, device=None, dtype=None)

Convert a SciPy sparse array or matrix.

Both scipy.sparse.sparray and the legacy spmatrix are accepted. COO, CSR and CSC keep their format (including unsorted indices and duplicate entries, exactly as stored); every other format (BSR, LIL, DOK, DIA) is converted through COO. The data is copied from CPU memory.

Parameters:

Name Type Description Default
array Any

SciPy sparse array or matrix.

required
device device | str | None

Target device (default CPU).

None
dtype dtype | None

Value dtype (default: the array's dtype).

None

Returns:

Type Description
Sparse

COO, CSR or CSC with shape == array.shape.

Raises:

Type Description
TypeError

If array is not a SciPy sparse object.

Source code in btorch/sparse/conversion.py
def from_scipy(
    array: Any,
    *,
    device: torch.device | str | None = None,
    dtype: torch.dtype | None = None,
) -> Sparse:
    """Convert a SciPy sparse array or matrix.

    Both ``scipy.sparse.sparray`` and the legacy ``spmatrix`` are accepted.
    COO, CSR and CSC keep their format (including unsorted indices and
    duplicate entries, exactly as stored); every other format (BSR, LIL, DOK,
    DIA) is converted through COO. The data is copied from CPU memory.

    Args:
        array: SciPy sparse array or matrix.
        device: Target device (default CPU).
        dtype: Value dtype (default: the array's dtype).

    Returns:
        ``COO``, ``CSR`` or ``CSC`` with ``shape == array.shape``.

    Raises:
        TypeError: If ``array`` is not a SciPy sparse object.
    """
    if not _is_scipy_sparse(array):
        raise TypeError(f"from_scipy expects a SciPy sparse array, got {type(array)}.")
    fmt = array.format
    if fmt not in ("coo", "csr", "csc"):
        array = array.tocoo()
        fmt = "coo"
    shape = tuple(int(s) for s in array.shape)
    if len(shape) != 2:
        raise NotImplementedError("Only 2-D SciPy sparse arrays are supported.")

    # Copies: the result must never alias (and later mutate) the caller's data.
    def index(a) -> Tensor:
        return torch.tensor(np.asarray(a, dtype=np.int64), device=device)

    values = torch.tensor(np.asarray(array.data), device=device)
    if dtype is not None:
        values = values.to(dtype)
    if fmt == "coo":
        indices = torch.stack([index(array.row), index(array.col)])
        # SciPy's ``has_canonical_format`` flag is not reliable (a DOK array
        # converted with ``tocoo()`` sets it for insertion-ordered entries),
        # so sortedness is verified here, once, in O(nnz).
        key = indices[0] * shape[1] + indices[1]
        canonical = bool((key[1:] > key[:-1]).all())
        return COO(
            indices,
            values,
            shape,
            properties=Properties(sorted=canonical, unique=canonical),
            check=False,
        )
    cls = CSR if fmt == "csr" else CSC
    unique = bool(array.has_canonical_format)
    return cls(
        index(array.indptr),
        index(array.indices),
        values,
        shape,
        properties=Properties(sorted=bool(array.has_sorted_indices), unique=unique),
        check=False,
    )

from_torch(tensor, *, batch_dim=0)

Wrap a PyTorch sparse tensor without copying or transposing.

COO, CSR and CSC keep their format. BSR and BSC are converted through COO, which is lossless. Values keep their autograd history, so gradients flow back to the tensor the sparse tensor was built from.

An uncoalesced COO tensor keeps its entries as stored (order and duplicates), unless it requires grad: PyTorch only exposes the values of an uncoalesced tensor to autograd after coalescing, so it is coalesced then. A batched CSR/CSC tensor whose members have different patterns becomes a batched COO.

Parameters:

Name Type Description Default
tensor Tensor

Tensor with a sparse layout.

required
batch_dim int

For a COO tensor, how many leading sparse dimensions are batch coordinates. PyTorch COO has no notion of a batch, so a tensor of shape (G, M, N) is read as a 3-D sparse array unless batch_dim=1 says it is G matrices.

0

Returns:

Type Description
Sparse

COO, CSR or CSC with shape == tensor.shape.

Raises:

Type Description
TypeError

If tensor is not sparse.

Source code in btorch/sparse/conversion.py
def from_torch(tensor: Tensor, *, batch_dim: int = 0) -> Sparse:
    """Wrap a PyTorch sparse tensor without copying or transposing.

    COO, CSR and CSC keep their format. BSR and BSC are converted through
    COO, which is lossless. Values keep their autograd history, so gradients
    flow back to the tensor the sparse tensor was built from.

    An uncoalesced COO tensor keeps its entries as stored (order and
    duplicates), unless it requires grad: PyTorch only exposes the values of
    an uncoalesced tensor to autograd after coalescing, so it is coalesced
    then. A batched CSR/CSC tensor whose members have different patterns
    becomes a batched COO.

    Args:
        tensor: Tensor with a sparse layout.
        batch_dim: For a COO tensor, how many leading sparse dimensions are
            batch coordinates. PyTorch COO has no notion of a batch, so a
            tensor of shape ``(G, M, N)`` is read as a 3-D sparse array
            unless ``batch_dim=1`` says it is ``G`` matrices.

    Returns:
        ``COO``, ``CSR`` or ``CSC`` with ``shape == tensor.shape``.

    Raises:
        TypeError: If ``tensor`` is not sparse.
    """
    if not isinstance(tensor, Tensor) or tensor.layout == torch.strided:
        raise TypeError(
            "from_torch expects a torch sparse tensor; dense tensors are never "
            "sparsified implicitly (use sparse.from_dense)."
        )
    shape = tuple(tensor.shape)
    layout = tensor.layout
    if layout in (torch.sparse_bsr, torch.sparse_bsc):
        tensor = tensor.to_sparse(layout=torch.sparse_coo)
        layout = torch.sparse_coo
    if layout == torch.sparse_coo:
        reordered = False
        if tensor.is_coalesced():
            indices, values = tensor.indices(), tensor.values()
            canonical = True
        elif tensor.requires_grad:
            # PyTorch only exposes the values of an uncoalesced tensor to
            # autograd after coalescing, which merges and reorders entries.
            tensor = tensor.coalesce()
            indices, values = tensor.indices(), tensor.values()
            canonical = reordered = True
        else:
            # Keep the entries exactly as stored (order and duplicates), so
            # arrays aligned with them stay aligned.
            indices, values = tensor._indices(), tensor._values()
            canonical = False
        out = COO(
            indices,
            values,
            shape,
            batch_dim=batch_dim,
            dense_dim=tensor.dense_dim(),
            properties=Properties(sorted=canonical, unique=canonical),
            check=False,
        )
        out._reordered = reordered
        return out
    if batch_dim:
        raise ValueError(
            "batch_dim applies to COO tensors; batched CSR/CSC tensors carry "
            "their batch dimensions themselves."
        )
    if layout == torch.sparse_csr:
        pointer, minor, cls = tensor.crow_indices(), tensor.col_indices(), CSR
    elif layout == torch.sparse_csc:
        pointer, minor, cls = tensor.ccol_indices(), tensor.row_indices(), CSC
    else:
        raise TypeError(f"Unsupported torch sparse layout {layout}.")
    if pointer.ndim > 1:
        # Batched compressed tensor: keep the compressed format when the
        # members share a pattern, otherwise fall back to batched COO.
        n_batch = pointer.ndim - 1
        flat_p = pointer.reshape(-1, pointer.shape[-1])
        flat_m = minor.reshape(-1, minor.shape[-1])
        if bool((flat_p == flat_p[0]).all()) and bool((flat_m == flat_m[0]).all()):
            pointer, minor = flat_p[0], flat_m[0]
        else:
            coo = tensor.to_sparse(layout=torch.sparse_coo).coalesce()
            return COO(
                coo.indices(),
                coo.values(),
                shape,
                batch_dim=n_batch,
                dense_dim=coo.dense_dim(),
                properties=Properties(sorted=True, unique=True),
                check=False,
            )
    # PyTorch does not guarantee sorted or unique indices within a row of a
    # compressed tensor, so nothing is claimed about them.
    return cls(
        pointer,
        minor,
        tensor.values(),
        shape,
        dense_dim=tensor.dense_dim(),
        check=False,
    )

to_scipy(A, format=None, **kwargs)

Export a sparse matrix as a scipy.sparse array.

Values are detached and copied to CPU memory.

When converting to BSR, additional keyword arguments are forwarded to scipy.sparse.bsr_array, e.g., blocksize=(rows, columns). Other conversion paths do not consume these arguments.

Parameters:

Name Type Description Default
A Sparse

Unbatched sparse matrix without dense entry dimensions.

required
format str | None

SciPy format name. Defaults to the stored format.

None

Returns:

Name Type Description
result sparray

Sparse array with shape == A.shape.

Raises:

Type Description
ValueError

If A is batched, has dense entry dimensions, or does not have exactly two sparse dimensions.

Source code in btorch/sparse/conversion.py
def to_scipy(A: Sparse, format: str | None = None, **kwargs):
    """Export a sparse matrix as a ``scipy.sparse`` array.

    Values are detached and copied to CPU memory.

    When converting to BSR, additional keyword arguments are forwarded to
    ``scipy.sparse.bsr_array``, e.g., ``blocksize=(rows, columns)``. Other
    conversion paths do not consume these arguments.

    Args:
        A: Unbatched sparse matrix without dense entry dimensions.
        format: SciPy format name. Defaults to the stored format.

    Returns:
        result (scipy.sparse.sparray): Sparse array with ``shape == A.shape``.

    Raises:
        ValueError: If ``A`` is batched, has dense entry dimensions, or does
            not have exactly two sparse dimensions.
    """
    import scipy.sparse

    if A.batch_dim() or A.dense_dim() or A.sparse_dim() != 2:
        raise ValueError(
            "SciPy sparse arrays are 2-D: export one batch member at a time "
            f"(got batch_shape={A.batch_shape}, sparse_shape={A.sparse_shape}, "
            f"dense_shape={A.dense_shape})."
        )
    if format is None:
        format = A.format

    def np_(t: Tensor):
        return t.detach().cpu().numpy()

    if A.format == "coo":
        native = scipy.sparse.coo_array(
            (np_(A._values), (np_(A._indices[0]), np_(A._indices[1]))), shape=A.shape
        )
    else:
        cls = scipy.sparse.csr_array if A.format == "csr" else scipy.sparse.csc_array
        native = cls((np_(A._values), np_(A._minor), np_(A._pointer)), shape=A.shape)
    if format == A.format:
        return native
    if format == "bsr":
        return scipy.sparse.bsr_array(native.tocsr(), **kwargs)
    return native.asformat(format)

to_torch(A, layout=None, **kwargs)

Export a sparse array as a PyTorch sparse tensor.

A shared-pattern batch has no PyTorch equivalent, so its pattern is repeated for every batch member on export.

Additional keyword arguments are forwarded to :meth:torch.Tensor.to_sparse for layout conversion, e.g., blocksize=(rows, columns) for BSR or BSC.

Parameters:

Name Type Description Default
A Sparse

Sparse array.

required
layout str | layout | None

Target layout name or torch.sparse_* layout. Defaults to the stored format.

None

Returns:

Type Description
Tensor

Sparse tensor with shape == A.shape; values keep their autograd

Tensor

history.

Source code in btorch/sparse/conversion.py
def to_torch(A: Sparse, layout: str | torch.layout | None = None, **kwargs) -> Tensor:
    """Export a sparse array as a PyTorch sparse tensor.

    A shared-pattern batch has no PyTorch equivalent, so its pattern is
    repeated for every batch member on export.

    Additional keyword arguments are forwarded to :meth:`torch.Tensor.to_sparse`
    for layout conversion, e.g., ``blocksize=(rows, columns)`` for BSR or BSC.

    Args:
        A: Sparse array.
        layout: Target layout name or ``torch.sparse_*`` layout. Defaults to
            the stored format.

    Returns:
        Sparse tensor with ``shape == A.shape``; values keep their autograd
        history.
    """
    if layout is None:
        layout = A.format
    if not isinstance(layout, str):
        layout = _LAYOUT_NAMES[layout]
    if layout not in _TORCH_LAYOUTS:
        raise ValueError(f"Unknown torch sparse layout {layout!r}.")

    if layout in ("csr", "csc") and A.format == layout:
        bd = A.batch_dim()
        batch = A.shape[:bd]
        pointer = A._pointer.expand(*batch, -1)
        minor = A._minor.expand(*batch, -1)
        make = torch.sparse_csr_tensor if layout == "csr" else torch.sparse_csc_tensor
        return make(pointer, minor, A._values, size=A.shape)
    if layout in ("csr", "csc") and not getattr(A, "_index_batch_dim", 0):
        return to_torch(getattr(A, f"to{layout}")(), layout)

    coo = A.tocoo()
    indices, values, _ = _expand_batch_coo(coo)
    out = torch.sparse_coo_tensor(
        indices,
        values,
        size=coo.shape,
        is_coalesced=coo.properties.canonical or None,
    )
    if layout == "coo":
        return out
    if coo.batch_dim() or coo.sparse_dim() != 2:
        raise NotImplementedError(
            f"Export to the torch {layout} layout is implemented for "
            "unbatched matrices (and same-format shared-pattern batches)."
        )
    return out.coalesce().to_sparse(layout=_TORCH_LAYOUTS[layout], **kwargs)

btorch.sparse.coo

Coordinate (COO) sparse format.

Classes

COO

Bases: Sparse

Coordinate format: one index tuple and one value per stored entry.

COO supports any number of sparse dimensions. Entries may be unsorted and may contain duplicates; duplicates are summed by every operation, as in SciPy and PyTorch.

Two kinds of batch are supported and may be combined:

  • Shared pattern: values has leading batch dimensions, [*batch, nnz, *dense], and every batch member uses the same indices.
  • Different patterns: the first index rows are batch coordinates, so each batch member can have its own number of entries. Build these with :func:btorch.sparse.stack.

Parameters:

Name Type Description Default
indices Tensor

[n_index, nnz] integer coordinates. The rows are the batch coordinates (if any) followed by the sparse coordinates.

required
values Tensor

[*value_batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, *sparse, *dense).

required
batch_dim int | None

Total number of batch dimensions. Defaults to the number of leading value dimensions (a shared pattern).

None
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties of the given indices.

None
hints Hints | None

Performance expectations.

None
check bool

Validate index bounds.

True

Examples:

>>> import torch
>>> from btorch import sparse
>>> A = sparse.coo(torch.tensor([[0, 1], [2, 0]]),
...                torch.tensor([3.0, 5.0]), shape=(2, 3))
>>> A @ torch.tensor([1.0, 0.0, 2.0])
tensor([6., 5.])
Source code in btorch/sparse/coo.py
class COO(Sparse):
    """Coordinate format: one index tuple and one value per stored entry.

    COO supports any number of sparse dimensions. Entries may be unsorted and
    may contain duplicates; duplicates are summed by every operation, as in
    SciPy and PyTorch.

    Two kinds of batch are supported and may be combined:

    - *Shared pattern*: ``values`` has leading batch dimensions,
      ``[*batch, nnz, *dense]``, and every batch member uses the same indices.
    - *Different patterns*: the first index rows are batch coordinates, so each
      batch member can have its own number of entries. Build these with
      :func:`btorch.sparse.stack`.

    Args:
        indices: ``[n_index, nnz]`` integer coordinates. The rows are the
            batch coordinates (if any) followed by the sparse coordinates.
        values: ``[*value_batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, *sparse, *dense)``.
        batch_dim: Total number of batch dimensions. Defaults to the number
            of leading value dimensions (a shared pattern).
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties of the given indices.
        hints: Performance expectations.
        check: Validate index bounds.

    Examples:
        >>> import torch
        >>> from btorch import sparse
        >>> A = sparse.coo(torch.tensor([[0, 1], [2, 0]]),
        ...                torch.tensor([3.0, 5.0]), shape=(2, 3))
        >>> A @ torch.tensor([1.0, 0.0, 2.0])
        tensor([6., 5.])
    """

    format = "coo"

    def __init__(
        self,
        indices: Tensor,
        values: Tensor,
        shape: tuple[int, ...],
        *,
        batch_dim: int | None = None,
        dense_dim: int = 0,
        properties: Properties | None = None,
        hints: Hints | None = None,
        check: bool = True,
    ):
        values = _as_tensor(values)
        indices = _check_index("indices", _as_tensor(indices, device=values.device))
        shape = tuple(int(s) for s in shape)
        if indices.ndim != 2:
            raise ValueError(f"indices must be [n_index, nnz], got {indices.shape}.")
        n_index, nnz = indices.shape
        value_batch_dim = values.ndim - 1 - dense_dim
        if value_batch_dim < 0:
            raise ValueError(
                f"values with shape {tuple(values.shape)} cannot hold "
                f"{dense_dim} dense dimension(s) per entry."
            )
        if batch_dim is None:
            batch_dim = value_batch_dim
        index_batch_dim = batch_dim - value_batch_dim
        if index_batch_dim < 0:
            raise ValueError("batch_dim is smaller than the batch of `values`.")
        if len(shape) != value_batch_dim + n_index + dense_dim:
            raise ValueError(
                f"shape {shape} has {len(shape)} dimensions but indices/values "
                f"describe {value_batch_dim} value-batch + {n_index} indexed + "
                f"{dense_dim} dense."
            )
        if n_index - index_batch_dim < 1:
            raise ValueError("COO needs at least one sparse dimension.")
        if values.shape[value_batch_dim] != nnz:
            raise ValueError(
                f"values has {values.shape[value_batch_dim]} entries along its "
                f"entry axis but indices has {nnz}."
            )
        expected = (
            shape[:value_batch_dim] + (nnz,) + shape[len(shape) - dense_dim :]
            if dense_dim
            else shape[:value_batch_dim] + (nnz,)
        )
        if tuple(values.shape) != expected:
            raise ValueError(
                f"values has shape {tuple(values.shape)}, expected {expected}."
            )
        indexed = shape[value_batch_dim : value_batch_dim + n_index]
        if check and nnz > 0:
            lo = indices.amin(dim=1)
            hi = indices.amax(dim=1)
            for d, size in enumerate(indexed):
                if int(lo[d]) < 0 or int(hi[d]) >= size:
                    raise ValueError(
                        f"indices along indexed dimension {d} must be in "
                        f"[0, {size}), got range [{int(lo[d])}, {int(hi[d])}]."
                    )
        self._indices = indices
        self._values = values
        self._shape = shape
        self._batch_dim = batch_dim
        self._dense_dim = dense_dim
        self._value_batch_dim = value_batch_dim
        self.properties = properties or Properties()
        if self.properties.shared_pattern != bool(value_batch_dim):
            self.properties = self.properties.replace(
                shared_pattern=bool(value_batch_dim)
            )
        self.hints = hints or Hints()

    # ----------------------------------------------------------- accessors
    @property
    def nnz(self) -> int:
        return int(self._indices.shape[1])

    def indices(self) -> Tensor:
        """``[n_index, nnz]`` coordinates (PyTorch name)."""
        return self._indices

    def values(self) -> Tensor:
        """``[*value_batch, nnz, *dense]`` stored values (PyTorch name)."""
        return self._values

    @property
    def data(self) -> Tensor:
        """Stored values (SciPy name)."""
        return self._values

    @property
    def row(self) -> Tensor:
        """Row coordinate of each entry (two sparse dimensions only)."""
        self._require_matrix("row")
        return self._indices[-2]

    @property
    def col(self) -> Tensor:
        """Column coordinate of each entry (two sparse dimensions only)."""
        self._require_matrix("col")
        return self._indices[-1]

    def _require_matrix(self, what: str) -> None:
        if self.sparse_dim() != 2:
            raise ValueError(
                f"{what} needs exactly two sparse dimensions, this array has "
                f"{self.sparse_dim()}."
            )

    @property
    def _index_batch_dim(self) -> int:
        return self._batch_dim - self._value_batch_dim

    @property
    def _indexed_shape(self) -> tuple[int, ...]:
        """Sizes of the indexed (batch-coordinate + sparse) dimensions."""
        start = self._value_batch_dim
        return self._shape[start : start + self._indices.shape[0]]

    def _edge_index(self) -> tuple[Tensor | None, Tensor, Tensor]:
        """``(batch coordinates or None, row, col)`` for matrix products."""
        self._require_matrix("A matrix product")
        n_ib = self._index_batch_dim
        lead = self._indices[:n_ib] if n_ib else None
        return lead, self._indices[-2], self._indices[-1]

    # --------------------------------------------------------- construction
    def _like(self, indices: Tensor, values: Tensor, **changes) -> "COO":
        out = COO.__new__(COO)
        out.__dict__.update(self.__dict__)
        out._indices = indices
        out._values = values
        for key, value in changes.items():
            setattr(out, key, value)
        return out

    def with_values(self, values: Tensor) -> "COO":
        value_batch_dim = values.ndim - 1 - self._dense_dim
        tail = self._shape[self._value_batch_dim :]
        return COO(
            self._indices,
            values,
            tuple(values.shape[:value_batch_dim]) + tail,
            batch_dim=value_batch_dim + self._index_batch_dim,
            dense_dim=self._dense_dim,
            properties=self.properties,
            hints=self.hints,
            check=False,
        )

    def _map_tensors(self, index_fn, value_fn) -> "COO":
        return self._like(index_fn(self._indices), value_fn(self._values))

    # -------------------------------------------------------- canonical form
    def coalesce(self, return_map: bool = False) -> "COO" | tuple["COO", EdgeMap]:
        """Sort entries row-major and sum duplicates.

        Args:
            return_map: Also return the :class:`EdgeMap` from the old entries
                to the new ones, to move edge-aligned metadata consistently.

        Returns:
            The canonical COO, and the map if requested. The values of merged
            entries are summed, so gradients flow to every duplicate.
        """
        nnz = self.nnz
        if self.properties.canonical:
            edge_map = EdgeMap.identity(nnz, self._indices.device)
            return (self, edge_map) if return_map else self
        sizes = self._indexed_shape
        key = _ravel(self._indices, sizes)
        if self.properties.sorted:
            order = None
            sorted_key = key
        else:
            sorted_key, order = torch.sort(key, stable=True)
        unique_key, inverse = torch.unique_consecutive(sorted_key, return_inverse=True)
        if order is None:
            target = inverse
        else:
            target = torch.empty_like(inverse)
            target[order] = inverse
        edge_map = EdgeMap(target, int(unique_key.shape[0]))
        out = self._like(
            _unravel(unique_key, sizes),
            edge_map.sum(self._values, dim=self._value_batch_dim),
            properties=self.properties.replace(sorted=True, unique=True),
        )
        return (out, edge_map) if return_map else out

    def sum_duplicates(self) -> "COO":
        """SciPy-style alias of :meth:`coalesce` (returns a new array)."""
        return self.coalesce()

    # -------------------------------------------------------------- formats
    def tocoo(self) -> "COO":
        return self

    def _compressed(self, return_map: bool):
        """Canonical entries, their row pointers and the edge map."""
        self._require_matrix("CSR/CSC conversion")
        if self._index_batch_dim:
            raise NotImplementedError(
                "A batch of different sparsity patterns is stored as batched "
                "COO; compressed (CSR/CSC) storage for it is not implemented."
            )
        coo, edge_map = self.coalesce(return_map=True)
        n_rows = coo.sparse_shape[0]
        counts = torch.bincount(coo._indices[0], minlength=n_rows)
        pointer = torch.zeros(n_rows + 1, dtype=torch.long, device=counts.device)
        pointer[1:] = torch.cumsum(counts, 0)
        return coo, pointer, edge_map

    def tocsr(self, return_map: bool = False):
        """Convert to canonical CSR (sorted, duplicates summed).

        Args:
            return_map: Also return the :class:`EdgeMap` from the COO entries
                to the CSR entries.
        """
        from .csr import CSR

        coo, crow, edge_map = self._compressed(return_map)
        out = CSR(
            crow,
            coo._indices[1],
            coo._values,
            coo._shape,
            dense_dim=self._dense_dim,
            properties=coo.properties,
            hints=self.hints,
            check=False,
        )
        return (out, edge_map) if return_map else out

    def tocsc(self, return_map: bool = False):
        """Convert to canonical CSC (column-major, duplicates summed)."""
        result = self.transpose().tocsr(return_map)
        if return_map:
            return result[0].transpose(), result[1]
        return result.transpose()

    def transpose(self) -> "COO":
        self._require_matrix("transpose")
        idx = self._indices
        swapped = torch.cat([idx[:-2], idx[-1:], idx[-2:-1]])
        shape = list(self._shape)
        i = self._batch_dim
        shape[i], shape[i + 1] = shape[i + 1], shape[i]
        return self._like(
            swapped,
            self._values,
            _shape=tuple(shape),
            properties=self.properties.replace(sorted=False, triangular=None),
        )

    def to_dense(self) -> Tensor:
        n_vb = self._value_batch_dim
        sizes = self._indexed_shape
        dense = (
            self._shape[len(self._shape) - self._dense_dim :] if self._dense_dim else ()
        )
        key = _ravel(self._indices, sizes)
        flat = self._values.new_zeros(*self._shape[:n_vb], math.prod(sizes), *dense)
        flat = flat.index_add(n_vb, key, self._values)
        return flat.reshape(self._shape)
Attributes
col property

Column coordinate of each entry (two sparse dimensions only).

data property

Stored values (SciPy name).

row property

Row coordinate of each entry (two sparse dimensions only).

Methods:
coalesce(return_map=False)

Sort entries row-major and sum duplicates.

Parameters:

Name Type Description Default
return_map bool

Also return the :class:EdgeMap from the old entries to the new ones, to move edge-aligned metadata consistently.

False

Returns:

Type Description
'COO' | tuple['COO', EdgeMap]

The canonical COO, and the map if requested. The values of merged

'COO' | tuple['COO', EdgeMap]

entries are summed, so gradients flow to every duplicate.

Source code in btorch/sparse/coo.py
def coalesce(self, return_map: bool = False) -> "COO" | tuple["COO", EdgeMap]:
    """Sort entries row-major and sum duplicates.

    Args:
        return_map: Also return the :class:`EdgeMap` from the old entries
            to the new ones, to move edge-aligned metadata consistently.

    Returns:
        The canonical COO, and the map if requested. The values of merged
        entries are summed, so gradients flow to every duplicate.
    """
    nnz = self.nnz
    if self.properties.canonical:
        edge_map = EdgeMap.identity(nnz, self._indices.device)
        return (self, edge_map) if return_map else self
    sizes = self._indexed_shape
    key = _ravel(self._indices, sizes)
    if self.properties.sorted:
        order = None
        sorted_key = key
    else:
        sorted_key, order = torch.sort(key, stable=True)
    unique_key, inverse = torch.unique_consecutive(sorted_key, return_inverse=True)
    if order is None:
        target = inverse
    else:
        target = torch.empty_like(inverse)
        target[order] = inverse
    edge_map = EdgeMap(target, int(unique_key.shape[0]))
    out = self._like(
        _unravel(unique_key, sizes),
        edge_map.sum(self._values, dim=self._value_batch_dim),
        properties=self.properties.replace(sorted=True, unique=True),
    )
    return (out, edge_map) if return_map else out
indices()

[n_index, nnz] coordinates (PyTorch name).

Source code in btorch/sparse/coo.py
def indices(self) -> Tensor:
    """``[n_index, nnz]`` coordinates (PyTorch name)."""
    return self._indices
sum_duplicates()

SciPy-style alias of :meth:coalesce (returns a new array).

Source code in btorch/sparse/coo.py
def sum_duplicates(self) -> "COO":
    """SciPy-style alias of :meth:`coalesce` (returns a new array)."""
    return self.coalesce()
tocsc(return_map=False)

Convert to canonical CSC (column-major, duplicates summed).

Source code in btorch/sparse/coo.py
def tocsc(self, return_map: bool = False):
    """Convert to canonical CSC (column-major, duplicates summed)."""
    result = self.transpose().tocsr(return_map)
    if return_map:
        return result[0].transpose(), result[1]
    return result.transpose()
tocsr(return_map=False)

Convert to canonical CSR (sorted, duplicates summed).

Parameters:

Name Type Description Default
return_map bool

Also return the :class:EdgeMap from the COO entries to the CSR entries.

False
Source code in btorch/sparse/coo.py
def tocsr(self, return_map: bool = False):
    """Convert to canonical CSR (sorted, duplicates summed).

    Args:
        return_map: Also return the :class:`EdgeMap` from the COO entries
            to the CSR entries.
    """
    from .csr import CSR

    coo, crow, edge_map = self._compressed(return_map)
    out = CSR(
        crow,
        coo._indices[1],
        coo._values,
        coo._shape,
        dense_dim=self._dense_dim,
        properties=coo.properties,
        hints=self.hints,
        check=False,
    )
    return (out, edge_map) if return_map else out
values()

[*value_batch, nnz, *dense] stored values (PyTorch name).

Source code in btorch/sparse/coo.py
def values(self) -> Tensor:
    """``[*value_batch, nnz, *dense]`` stored values (PyTorch name)."""
    return self._values

EdgeMap dataclass

Correspondence between the entries of two representations.

A representation change (sorting, duplicate reduction) maps every old entry e to a new entry target[e]. Every edge-aligned array (values, group ids, receptors, delays, plasticity state) must be moved with the same map, so the map is computed once and applied to each of them.

Parameters:

Name Type Description Default
target Tensor

[n_old] new position of every old entry.

required
n_new int

Number of entries after the change.

required
Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class EdgeMap:
    """Correspondence between the entries of two representations.

    A representation change (sorting, duplicate reduction) maps every old
    entry ``e`` to a new entry ``target[e]``. Every edge-aligned array (values,
    group ids, receptors, delays, plasticity state) must be moved with the same
    map, so the map is computed once and applied to each of them.

    Args:
        target: ``[n_old]`` new position of every old entry.
        n_new: Number of entries after the change.
    """

    target: Tensor
    n_new: int

    @property
    def n_old(self) -> int:
        return int(self.target.shape[0])

    @property
    def is_permutation(self) -> bool:
        """Whether no entries were merged."""
        return self.n_old == self.n_new

    def source(self) -> Tensor:
        """``[n_new]`` index of one old entry for every new entry.

        For merged duplicates this is the last old entry of the group.
        """
        old = torch.arange(self.n_old, device=self.target.device)
        if self.is_permutation:
            src = torch.empty_like(old)
            src[self.target] = old
            return src
        # Deterministic on every device (an indexed assignment with repeated
        # targets is not).
        src = self.target.new_zeros(self.n_new)
        return src.scatter_reduce(0, self.target, old, "amax", include_self=False)

    def sum(self, values: Tensor, dim: int = -1) -> Tensor:
        """Move additive data (weights); merged entries are summed.

        Differentiable: the gradient of a merged entry flows to every old
        entry that was merged into it.

        Args:
            values: Tensor whose axis ``dim`` has length ``n_old``.
            dim: Edge axis.
        """
        if self.is_permutation:
            return values.index_select(dim, self.source())
        shape = list(values.shape)
        shape[dim] = self.n_new
        return values.new_zeros(shape).index_add(dim, self.target, values)

    def take(self, meta: Tensor, dim: int = 0, check: bool = True) -> Tensor:
        """Move categorical metadata (group, receptor, delay ids).

        Args:
            meta: Tensor whose axis ``dim`` has length ``n_old``.
            dim: Edge axis.
            check: Raise if merged entries carry different metadata, because
                no single value can then represent the merged entry.

        Raises:
            ValueError: If ``check`` and merged duplicates disagree.
        """
        out = meta.index_select(dim, self.source())
        if check and not self.is_permutation:
            if not torch.equal(out.index_select(dim, self.target), meta):
                raise ValueError(
                    "Duplicate entries carry different metadata and cannot be "
                    "merged; split them into separate connections or make the "
                    "metadata equal first."
                )
        return out

    def compose(self, then: "EdgeMap") -> "EdgeMap":
        """Map equivalent to applying ``self`` and then ``then``."""
        return EdgeMap(then.target[self.target], then.n_new)

    @staticmethod
    def identity(n: int, device=None) -> "EdgeMap":
        return EdgeMap(torch.arange(n, device=device), n)
Attributes
is_permutation property

Whether no entries were merged.

Methods:
compose(then)

Map equivalent to applying self and then then.

Source code in btorch/sparse/properties.py
def compose(self, then: "EdgeMap") -> "EdgeMap":
    """Map equivalent to applying ``self`` and then ``then``."""
    return EdgeMap(then.target[self.target], then.n_new)
source()

[n_new] index of one old entry for every new entry.

For merged duplicates this is the last old entry of the group.

Source code in btorch/sparse/properties.py
def source(self) -> Tensor:
    """``[n_new]`` index of one old entry for every new entry.

    For merged duplicates this is the last old entry of the group.
    """
    old = torch.arange(self.n_old, device=self.target.device)
    if self.is_permutation:
        src = torch.empty_like(old)
        src[self.target] = old
        return src
    # Deterministic on every device (an indexed assignment with repeated
    # targets is not).
    src = self.target.new_zeros(self.n_new)
    return src.scatter_reduce(0, self.target, old, "amax", include_self=False)
sum(values, dim=-1)

Move additive data (weights); merged entries are summed.

Differentiable: the gradient of a merged entry flows to every old entry that was merged into it.

Parameters:

Name Type Description Default
values Tensor

Tensor whose axis dim has length n_old.

required
dim int

Edge axis.

-1
Source code in btorch/sparse/properties.py
def sum(self, values: Tensor, dim: int = -1) -> Tensor:
    """Move additive data (weights); merged entries are summed.

    Differentiable: the gradient of a merged entry flows to every old
    entry that was merged into it.

    Args:
        values: Tensor whose axis ``dim`` has length ``n_old``.
        dim: Edge axis.
    """
    if self.is_permutation:
        return values.index_select(dim, self.source())
    shape = list(values.shape)
    shape[dim] = self.n_new
    return values.new_zeros(shape).index_add(dim, self.target, values)
take(meta, dim=0, check=True)

Move categorical metadata (group, receptor, delay ids).

Parameters:

Name Type Description Default
meta Tensor

Tensor whose axis dim has length n_old.

required
dim int

Edge axis.

0
check bool

Raise if merged entries carry different metadata, because no single value can then represent the merged entry.

True

Raises:

Type Description
ValueError

If check and merged duplicates disagree.

Source code in btorch/sparse/properties.py
def take(self, meta: Tensor, dim: int = 0, check: bool = True) -> Tensor:
    """Move categorical metadata (group, receptor, delay ids).

    Args:
        meta: Tensor whose axis ``dim`` has length ``n_old``.
        dim: Edge axis.
        check: Raise if merged entries carry different metadata, because
            no single value can then represent the merged entry.

    Raises:
        ValueError: If ``check`` and merged duplicates disagree.
    """
    out = meta.index_select(dim, self.source())
    if check and not self.is_permutation:
        if not torch.equal(out.index_select(dim, self.target), meta):
            raise ValueError(
                "Duplicate entries carry different metadata and cannot be "
                "merged; split them into separate connections or make the "
                "metadata equal first."
            )
    return out

Hints dataclass

Performance expectations; advisory only.

Only expected_density is consulted by the planner today; the other two are accepted and reserved.

Parameters:

Name Type Description Default
expected_calls int | None

How many products the object will take part in (reserved).

None
expected_density float | None

Expected fraction of non-zero input entries, in [0, 1].

None
expected_batch int | None

Expected number of right-hand sides per call (reserved).

None

Raises:

Type Description
ValueError

If a value is out of range.

Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class Hints:
    """Performance expectations; advisory only.

    Only ``expected_density`` is consulted by the planner today; the other
    two are accepted and reserved.

    Args:
        expected_calls: How many products the object will take part in
            (reserved).
        expected_density: Expected fraction of non-zero input entries, in
            ``[0, 1]``.
        expected_batch: Expected number of right-hand sides per call
            (reserved).

    Raises:
        ValueError: If a value is out of range.
    """

    expected_calls: int | None = None
    expected_density: float | None = None
    expected_batch: int | None = None

    def __post_init__(self) -> None:
        density = self.expected_density
        if density is not None and not (
            isinstance(density, (int, float)) and 0.0 <= density <= 1.0
        ):
            raise ValueError(f"expected_density must be in [0, 1], got {density!r}.")
        for name in ("expected_calls", "expected_batch"):
            value = getattr(self, name)
            if value is not None and not (isinstance(value, int) and value > 0):
                raise ValueError(f"{name} must be a positive int, got {value!r}.")

    def replace(self, **changes) -> "Hints":
        """Return a copy with selected expectations changed."""
        return replace(self, **changes)
Methods:
replace(**changes)

Return a copy with selected expectations changed.

Source code in btorch/sparse/properties.py
def replace(self, **changes) -> "Hints":
    """Return a copy with selected expectations changed."""
    return replace(self, **changes)

Properties dataclass

Structural facts about a stored sparse representation.

A True value is a guarantee; False means "not known", never "known to be violated".

Parameters:

Name Type Description Default
sorted bool

Entries are in lexicographic (row-major) index order.

False
unique bool

No index tuple is stored twice.

False
symmetric bool

Stored values satisfy A == A.T.

False
structurally_symmetric bool

The sparsity pattern is symmetric.

False
triangular str | None

"lower", "upper" or None.

None
fixed_pattern bool

The pattern is never mutated (no rewiring).

False
shared_pattern bool

A batch of matrices shares one pattern.

False
Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class Properties:
    """Structural facts about a stored sparse representation.

    A ``True`` value is a guarantee; ``False`` means "not known", never
    "known to be violated".

    Args:
        sorted: Entries are in lexicographic (row-major) index order.
        unique: No index tuple is stored twice.
        symmetric: Stored values satisfy ``A == A.T``.
        structurally_symmetric: The sparsity pattern is symmetric.
        triangular: ``"lower"``, ``"upper"`` or ``None``.
        fixed_pattern: The pattern is never mutated (no rewiring).
        shared_pattern: A batch of matrices shares one pattern.
    """

    sorted: bool = False
    unique: bool = False
    symmetric: bool = False
    structurally_symmetric: bool = False
    triangular: str | None = None
    fixed_pattern: bool = False
    shared_pattern: bool = False

    @property
    def canonical(self) -> bool:
        """Whether entries are sorted and free of duplicates."""
        return self.sorted and self.unique

    def replace(self, **changes) -> "Properties":
        """Return a copy with some fields changed."""
        return replace(self, **changes)
Attributes
canonical property

Whether entries are sorted and free of duplicates.

Methods:
replace(**changes)

Return a copy with some fields changed.

Source code in btorch/sparse/properties.py
def replace(self, **changes) -> "Properties":
    """Return a copy with some fields changed."""
    return replace(self, **changes)

Sparse

Sparse array with logical shape [*batch, *sparse, *dense].

Sparse is the format-agnostic interface. It describes what the array is (shape, dtype, device, number of stored entries) and offers the operations every format supports. Format-specific data such as indptr is only available on the concrete classes (:class:~btorch.sparse.COO, :class:~btorch.sparse.CSR, :class:~btorch.sparse.CSC), obtained with tocsr() / as_csr() and friends.

The three shape groups are:

  • batch_shape: independent sparse arrays (for example an ensemble of networks).
  • sparse_shape: the dimensions that are stored sparsely.
  • dense_shape: a dense payload attached to every stored entry.

Stored values have shape [*value_batch, nnz, *dense_shape]. A batch whose members share one sparsity pattern stores the pattern once and only the values per member.

Sparse is a plain Python object holding tensors; it is not a torch.Tensor subclass. Matrix products follow standard linear algebra: for A.shape == (M, N), A @ x maps a length-N vector to a length-M vector. Conversions never transpose.

Source code in btorch/sparse/base.py
class Sparse:
    """Sparse array with logical shape ``[*batch, *sparse, *dense]``.

    ``Sparse`` is the format-agnostic interface. It describes *what* the array
    is (shape, dtype, device, number of stored entries) and offers the
    operations every format supports. Format-specific data such as ``indptr``
    is only available on the concrete classes (:class:`~btorch.sparse.COO`,
    :class:`~btorch.sparse.CSR`, :class:`~btorch.sparse.CSC`), obtained with
    ``tocsr()`` / ``as_csr()`` and friends.

    The three shape groups are:

    - ``batch_shape``: independent sparse arrays (for example an ensemble of
      networks).
    - ``sparse_shape``: the dimensions that are stored sparsely.
    - ``dense_shape``: a dense payload attached to every stored entry.

    Stored values have shape ``[*value_batch, nnz, *dense_shape]``. A batch
    whose members share one sparsity pattern stores the pattern once and only
    the values per member.

    ``Sparse`` is a plain Python object holding tensors; it is not a
    ``torch.Tensor`` subclass. Matrix products follow standard linear algebra:
    for ``A.shape == (M, N)``, ``A @ x`` maps a length-``N`` vector to a
    length-``M`` vector. Conversions never transpose.
    """

    format: str = "sparse"
    # Let ``ndarray @ A`` reach ``__rmatmul__`` instead of NumPy treating the
    # sparse array as an object scalar.
    __array_ufunc__ = None

    _values: Tensor
    _shape: tuple[int, ...]
    _batch_dim: int
    _dense_dim: int
    properties: Properties
    hints: Hints

    # ------------------------------------------------------------------ shape
    @property
    def shape(self) -> tuple[int, ...]:
        """Logical shape ``(*batch, *sparse, *dense)``."""
        return self._shape

    @property
    def ndim(self) -> int:
        return len(self._shape)

    def batch_dim(self) -> int:
        """Number of batch dimensions."""
        return self._batch_dim

    def dense_dim(self) -> int:
        """Number of dense (per-entry payload) dimensions."""
        return self._dense_dim

    def sparse_dim(self) -> int:
        """Number of sparsely stored dimensions."""
        return self.ndim - self._batch_dim - self._dense_dim

    @property
    def batch_shape(self) -> tuple[int, ...]:
        return self._shape[: self._batch_dim]

    @property
    def sparse_shape(self) -> tuple[int, ...]:
        return self._shape[self._batch_dim : self.ndim - self._dense_dim]

    @property
    def dense_shape(self) -> tuple[int, ...]:
        return self._shape[self.ndim - self._dense_dim :]

    @property
    def dtype(self) -> torch.dtype:
        return self._values.dtype

    @property
    def device(self) -> torch.device:
        return self._values.device

    @property
    def nnz(self) -> int:
        """Number of stored entries (of one batch member for a shared pattern,
        of all members together otherwise)."""
        raise NotImplementedError

    @property
    def requires_grad(self) -> bool:
        return self._values.requires_grad

    # ------------------------------------------------------- format changes
    def tocoo(self) -> "COO":
        """Convert to COO (may allocate)."""
        raise NotImplementedError

    def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
        """Convert to CSR (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
        """Convert to CSC (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tobsr(self, blocksize: tuple[int, int]):
        """Convert to BSR; not implemented as a native format.

        Use ``to_torch(layout="bsr", blocksize=...)`` or
        ``to_scipy(format="bsr")`` to export block storage.
        """
        raise NotImplementedError(
            "BSR is not a native btorch format yet; export with "
            "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
        )

    def _as(self, fmt: str):
        if self.format != fmt:
            hint = (
                "BSR is not a native format; export with to_torch(layout='bsr')."
                if fmt == "bsr"
                else f"Call to{fmt}() to convert explicitly."
            )
            raise TypeError(
                f"This sparse array is stored as {self.format.upper()}, not "
                f"{fmt.upper()}; as_{fmt}() never converts. {hint}"
            )
        return self

    def as_coo(self) -> "COO":
        """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
        return self._as("coo")

    def as_csr(self) -> "CSR":
        """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
        return self._as("csr")

    def as_csc(self) -> "CSC":
        """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
        return self._as("csc")

    def as_bsr(self, blocksize: tuple[int, int] | None = None):
        """BSR is not a native format; always raises ``TypeError``."""
        return self._as("bsr")

    # -------------------------------------------------------------- interop
    @classmethod
    def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
        """Wrap a ``torch`` sparse tensor (see
        :func:`btorch.sparse.from_torch`)."""
        from .conversion import from_torch

        return from_torch(tensor, batch_dim=batch_dim)

    @classmethod
    def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
        """Convert a SciPy sparse array or matrix (see
        :func:`btorch.sparse.from_scipy`)."""
        from .conversion import from_scipy

        return from_scipy(array, device=device, dtype=dtype)

    def to_torch(
        self, layout: str | torch.layout | None = None, **kwargs: Any
    ) -> Tensor:
        """Export as a ``torch`` sparse tensor.

        Args:
            layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
                (or the ``torch.sparse_*`` layout). Defaults to the stored
                format.
            **kwargs: ``blocksize`` for the block layouts.
        """
        from .conversion import to_torch

        return to_torch(self, layout, **kwargs)

    def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
        """Export as a ``scipy.sparse`` array (CPU, detached).

        Args:
            format: Any SciPy format name; defaults to the stored format.
            **kwargs: ``blocksize`` for ``"bsr"``.
        """
        from .conversion import to_scipy

        return to_scipy(self, format, **kwargs)

    def to_dense(self) -> Tensor:
        """Materialise as a dense tensor of shape :attr:`shape`."""
        return self.tocoo().to_dense()

    # ------------------------------------------------------- tensor handling
    def with_values(self, values: Tensor) -> "Sparse":
        """Return an array with the same pattern and new values.

        ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
        shape creates a shared-pattern batch.
        """
        raise NotImplementedError

    def _map_tensors(self, index_fn, value_fn) -> "Sparse":
        """Apply ``index_fn`` to index tensors and ``value_fn`` to values."""
        raise NotImplementedError

    def to(self, *args, **kwargs) -> "Sparse":
        """Move to a device and/or cast the values (indices stay integer)."""
        device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

        return self._map_tensors(
            lambda index: index.to(device=device),
            lambda values: values.to(device=device, dtype=dtype),
        )

    def cpu(self) -> "Sparse":
        return self.to("cpu")

    def cuda(self, device=None) -> "Sparse":
        return self.to("cuda" if device is None else device)

    def float(self) -> "Sparse":
        return self.to(torch.float32)

    def double(self) -> "Sparse":
        return self.to(torch.float64)

    def detach(self) -> "Sparse":
        return self.with_values(self._values.detach())

    # ------------------------------------------------------------- products
    def matvec(self, x: Tensor) -> Tensor:
        """Apply the operator along the last axis of ``x``.

        See :func:`btorch.sparse.matvec`.
        """
        from .ops import matvec

        return matvec(self, x)

    def rmatvec(self, x: Tensor) -> Tensor:
        """Apply the transposed operator along the last axis of ``x``."""
        from .ops import rmatvec

        return rmatvec(self, x)

    def __matmul__(self, other):
        from .ops import matmul

        return matmul(self, other)

    def __rmatmul__(self, other):
        from .ops import matmul

        return matmul(other, self)

    @property
    def T(self) -> "Sparse":
        """Transpose of the two sparse dimensions."""
        return self.transpose()

    def transpose(self) -> "Sparse":
        raise NotImplementedError

    def __repr__(self) -> str:
        parts = [f"shape={self.shape}", f"nnz={self.nnz}", f"dtype={self.dtype}"]
        if self.batch_dim():
            parts.append(f"batch_shape={self.batch_shape}")
        if self.dense_dim():
            parts.append(f"dense_shape={self.dense_shape}")
        if self.device.type != "cpu":
            parts.append(f"device={self.device}")
        return f"{type(self).__name__}({', '.join(parts)})"
Attributes
T property

Transpose of the two sparse dimensions.

nnz property

Number of stored entries (of one batch member for a shared pattern, of all members together otherwise).

shape property

Logical shape (*batch, *sparse, *dense).

Methods:
as_bsr(blocksize=None)

BSR is not a native format; always raises TypeError.

Source code in btorch/sparse/base.py
def as_bsr(self, blocksize: tuple[int, int] | None = None):
    """BSR is not a native format; always raises ``TypeError``."""
    return self._as("bsr")
as_coo()

Return self if it is stored as COO, else raise TypeError.

Source code in btorch/sparse/base.py
def as_coo(self) -> "COO":
    """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
    return self._as("coo")
as_csc()

Return self if it is stored as CSC, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csc(self) -> "CSC":
    """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
    return self._as("csc")
as_csr()

Return self if it is stored as CSR, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csr(self) -> "CSR":
    """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
    return self._as("csr")
batch_dim()

Number of batch dimensions.

Source code in btorch/sparse/base.py
def batch_dim(self) -> int:
    """Number of batch dimensions."""
    return self._batch_dim
dense_dim()

Number of dense (per-entry payload) dimensions.

Source code in btorch/sparse/base.py
def dense_dim(self) -> int:
    """Number of dense (per-entry payload) dimensions."""
    return self._dense_dim
from_scipy(array, *, device=None, dtype=None) classmethod

Convert a SciPy sparse array or matrix (see :func:btorch.sparse.from_scipy).

Source code in btorch/sparse/base.py
@classmethod
def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
    """Convert a SciPy sparse array or matrix (see
    :func:`btorch.sparse.from_scipy`)."""
    from .conversion import from_scipy

    return from_scipy(array, device=device, dtype=dtype)
from_torch(tensor, *, batch_dim=0) classmethod

Wrap a torch sparse tensor (see :func:btorch.sparse.from_torch).

Source code in btorch/sparse/base.py
@classmethod
def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
    """Wrap a ``torch`` sparse tensor (see
    :func:`btorch.sparse.from_torch`)."""
    from .conversion import from_torch

    return from_torch(tensor, batch_dim=batch_dim)
matvec(x)

Apply the operator along the last axis of x.

See :func:btorch.sparse.matvec.

Source code in btorch/sparse/base.py
def matvec(self, x: Tensor) -> Tensor:
    """Apply the operator along the last axis of ``x``.

    See :func:`btorch.sparse.matvec`.
    """
    from .ops import matvec

    return matvec(self, x)
rmatvec(x)

Apply the transposed operator along the last axis of x.

Source code in btorch/sparse/base.py
def rmatvec(self, x: Tensor) -> Tensor:
    """Apply the transposed operator along the last axis of ``x``."""
    from .ops import rmatvec

    return rmatvec(self, x)
sparse_dim()

Number of sparsely stored dimensions.

Source code in btorch/sparse/base.py
def sparse_dim(self) -> int:
    """Number of sparsely stored dimensions."""
    return self.ndim - self._batch_dim - self._dense_dim
to(*args, **kwargs)

Move to a device and/or cast the values (indices stay integer).

Source code in btorch/sparse/base.py
def to(self, *args, **kwargs) -> "Sparse":
    """Move to a device and/or cast the values (indices stay integer)."""
    device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

    return self._map_tensors(
        lambda index: index.to(device=device),
        lambda values: values.to(device=device, dtype=dtype),
    )
to_dense()

Materialise as a dense tensor of shape :attr:shape.

Source code in btorch/sparse/base.py
def to_dense(self) -> Tensor:
    """Materialise as a dense tensor of shape :attr:`shape`."""
    return self.tocoo().to_dense()
to_scipy(format=None, **kwargs)

Export as a scipy.sparse array (CPU, detached).

Parameters:

Name Type Description Default
format str | None

Any SciPy format name; defaults to the stored format.

None
**kwargs Any

blocksize for "bsr".

{}
Source code in btorch/sparse/base.py
def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
    """Export as a ``scipy.sparse`` array (CPU, detached).

    Args:
        format: Any SciPy format name; defaults to the stored format.
        **kwargs: ``blocksize`` for ``"bsr"``.
    """
    from .conversion import to_scipy

    return to_scipy(self, format, **kwargs)
to_torch(layout=None, **kwargs)

Export as a torch sparse tensor.

Parameters:

Name Type Description Default
layout str | layout | None

"coo", "csr", "csc", "bsr" or "bsc" (or the torch.sparse_* layout). Defaults to the stored format.

None
**kwargs Any

blocksize for the block layouts.

{}
Source code in btorch/sparse/base.py
def to_torch(
    self, layout: str | torch.layout | None = None, **kwargs: Any
) -> Tensor:
    """Export as a ``torch`` sparse tensor.

    Args:
        layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
            (or the ``torch.sparse_*`` layout). Defaults to the stored
            format.
        **kwargs: ``blocksize`` for the block layouts.
    """
    from .conversion import to_torch

    return to_torch(self, layout, **kwargs)
tobsr(blocksize)

Convert to BSR; not implemented as a native format.

Use to_torch(layout="bsr", blocksize=...) or to_scipy(format="bsr") to export block storage.

Source code in btorch/sparse/base.py
def tobsr(self, blocksize: tuple[int, int]):
    """Convert to BSR; not implemented as a native format.

    Use ``to_torch(layout="bsr", blocksize=...)`` or
    ``to_scipy(format="bsr")`` to export block storage.
    """
    raise NotImplementedError(
        "BSR is not a native btorch format yet; export with "
        "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
    )
tocoo()

Convert to COO (may allocate).

Source code in btorch/sparse/base.py
def tocoo(self) -> "COO":
    """Convert to COO (may allocate)."""
    raise NotImplementedError
tocsc(return_map=False)

Convert to CSC (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
    """Convert to CSC (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
tocsr(return_map=False)

Convert to CSR (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
    """Convert to CSR (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
with_values(values)

Return an array with the same pattern and new values.

values is [*batch, nnz, *dense]; a different leading batch shape creates a shared-pattern batch.

Source code in btorch/sparse/base.py
def with_values(self, values: Tensor) -> "Sparse":
    """Return an array with the same pattern and new values.

    ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
    shape creates a shared-pattern batch.
    """
    raise NotImplementedError

Functions:

_as_tensor(x, *, dtype=None, device=None)

Source code in btorch/sparse/base.py
def _as_tensor(x, *, dtype=None, device=None) -> Tensor:
    if isinstance(x, Tensor):
        return (
            x if dtype is None and device is None else x.to(device=device, dtype=dtype)
        )
    return torch.as_tensor(x, dtype=dtype, device=device)

_check_index(name, index)

Source code in btorch/sparse/base.py
def _check_index(name: str, index: Tensor) -> Tensor:
    if index.numel() == 0:
        # An empty Python list becomes a float tensor; it is still a valid
        # (empty) index.
        return index.to(torch.long)
    if index.is_floating_point() or index.dtype == torch.bool:
        raise TypeError(f"{name} must be an integer tensor, got {index.dtype}.")
    return index.to(torch.long)

_ravel(indices, sizes)

Row-major linear index of indices [len(sizes), E].

Source code in btorch/sparse/coo.py
def _ravel(indices: Tensor, sizes: tuple[int, ...]) -> Tensor:
    """Row-major linear index of ``indices [len(sizes), E]``."""
    if math.prod(max(int(s), 1) for s in sizes) >= 2**63:
        raise OverflowError(
            f"The indexed shape {tuple(sizes)} has more than 2**63 positions; "
            "its entries cannot be linearised into int64 keys."
        )
    key = torch.zeros(indices.shape[1], dtype=torch.long, device=indices.device)
    for i, size in enumerate(sizes):
        key = key * size + indices[i]
    return key

_unravel(key, sizes)

Source code in btorch/sparse/coo.py
def _unravel(key: Tensor, sizes: tuple[int, ...]) -> Tensor:
    out = []
    for size in reversed(sizes):
        out.append(key % size if size > 0 else key)
        key = torch.div(key, max(size, 1), rounding_mode="floor")
    return torch.stack(out[::-1]) if out else key.new_empty((0, key.shape[0]))

btorch.sparse.csr

Compressed sparse row / column formats.

Classes

CSC

Bases: _Compressed

Compressed sparse column format (exactly two sparse dimensions).

Parameters:

Name Type Description Default
pointer Tensor

[n_cols + 1] column pointers (ccol_indices).

required
minor Tensor

[nnz] row of each entry (row_indices).

required
values Tensor

[*batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, n_rows, n_cols, *dense).

required
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties (sorted refers to column-major order).

None
hints Hints | None

Performance expectations.

None
check bool

Validate the pointer and index ranges.

True
Source code in btorch/sparse/csr.py
class CSC(_Compressed):
    """Compressed sparse column format (exactly two sparse dimensions).

    Args:
        pointer: ``[n_cols + 1]`` column pointers (``ccol_indices``).
        minor: ``[nnz]`` row of each entry (``row_indices``).
        values: ``[*batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, n_rows, n_cols, *dense)``.
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties (``sorted`` refers to
            column-major order).
        hints: Performance expectations.
        check: Validate the pointer and index ranges.
    """

    format = "csc"
    _major_axis = 1

    def ccol_indices(self) -> Tensor:
        """``[n_cols + 1]`` column pointers (PyTorch name)."""
        return self._pointer

    def row_indices(self) -> Tensor:
        """``[nnz]`` row of each entry (PyTorch name)."""
        return self._minor

    def col_indices(self) -> Tensor:
        """``[nnz]`` column of each entry, expanded from the pointers."""
        return self._major_indices()

    def tocsr(self, return_map: bool = False):
        return self.tocoo().tocsr(return_map)

    def tocsc(self, return_map: bool = False):
        """Return ``self`` (already CSC; entries are left as stored).

        Use :meth:`coalesce` to sort rows and merge duplicates.
        """
        if return_map:
            return self, EdgeMap.identity(self.nnz, self._minor.device)
        return self

    def coalesce(self, return_map: bool = False):
        """Canonical CSC: sorted rows, duplicates summed."""
        return self.tocoo().tocsc(return_map)

    def transpose(self) -> CSR:
        """Transpose without copying: the same arrays read as CSR."""
        return self._like(
            CSR,
            _shape=self._swapped_shape(),
            properties=self.properties.replace(triangular=None),
        )
Methods:
ccol_indices()

[n_cols + 1] column pointers (PyTorch name).

Source code in btorch/sparse/csr.py
def ccol_indices(self) -> Tensor:
    """``[n_cols + 1]`` column pointers (PyTorch name)."""
    return self._pointer
coalesce(return_map=False)

Canonical CSC: sorted rows, duplicates summed.

Source code in btorch/sparse/csr.py
def coalesce(self, return_map: bool = False):
    """Canonical CSC: sorted rows, duplicates summed."""
    return self.tocoo().tocsc(return_map)
col_indices()

[nnz] column of each entry, expanded from the pointers.

Source code in btorch/sparse/csr.py
def col_indices(self) -> Tensor:
    """``[nnz]`` column of each entry, expanded from the pointers."""
    return self._major_indices()
row_indices()

[nnz] row of each entry (PyTorch name).

Source code in btorch/sparse/csr.py
def row_indices(self) -> Tensor:
    """``[nnz]`` row of each entry (PyTorch name)."""
    return self._minor
tocsc(return_map=False)

Return self (already CSC; entries are left as stored).

Use :meth:coalesce to sort rows and merge duplicates.

Source code in btorch/sparse/csr.py
def tocsc(self, return_map: bool = False):
    """Return ``self`` (already CSC; entries are left as stored).

    Use :meth:`coalesce` to sort rows and merge duplicates.
    """
    if return_map:
        return self, EdgeMap.identity(self.nnz, self._minor.device)
    return self
transpose()

Transpose without copying: the same arrays read as CSR.

Source code in btorch/sparse/csr.py
def transpose(self) -> CSR:
    """Transpose without copying: the same arrays read as CSR."""
    return self._like(
        CSR,
        _shape=self._swapped_shape(),
        properties=self.properties.replace(triangular=None),
    )

CSR

Bases: _Compressed

Compressed sparse row format (exactly two sparse dimensions).

Batch members share one sparsity pattern: crow_indices and col_indices are stored once and values is [*batch, nnz, *dense]. This is the natural layout for ensembles and parameter sweeps over a fixed topology.

Parameters:

Name Type Description Default
pointer Tensor

[n_rows + 1] row pointers (crow_indices).

required
minor Tensor

[nnz] column of each entry (col_indices).

required
values Tensor

[*batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, n_rows, n_cols, *dense).

required
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties.

None
hints Hints | None

Performance expectations.

None
check bool

Validate the pointer and index ranges.

True

Examples:

>>> import torch
>>> from btorch import sparse
>>> A = sparse.csr(torch.tensor([0, 1, 2]), torch.tensor([2, 0]),
...                torch.tensor([3.0, 5.0]), shape=(2, 3))
>>> A.indptr
tensor([0, 1, 2])
>>> A @ torch.tensor([1.0, 0.0, 2.0])
tensor([6., 5.])
Source code in btorch/sparse/csr.py
class CSR(_Compressed):
    """Compressed sparse row format (exactly two sparse dimensions).

    Batch members share one sparsity pattern: ``crow_indices`` and
    ``col_indices`` are stored once and ``values`` is ``[*batch, nnz,
    *dense]``. This is the natural layout for ensembles and parameter sweeps
    over a fixed topology.

    Args:
        pointer: ``[n_rows + 1]`` row pointers (``crow_indices``).
        minor: ``[nnz]`` column of each entry (``col_indices``).
        values: ``[*batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, n_rows, n_cols, *dense)``.
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties.
        hints: Performance expectations.
        check: Validate the pointer and index ranges.

    Examples:
        >>> import torch
        >>> from btorch import sparse
        >>> A = sparse.csr(torch.tensor([0, 1, 2]), torch.tensor([2, 0]),
        ...                torch.tensor([3.0, 5.0]), shape=(2, 3))
        >>> A.indptr
        tensor([0, 1, 2])
        >>> A @ torch.tensor([1.0, 0.0, 2.0])
        tensor([6., 5.])
    """

    format = "csr"
    _major_axis = 0

    def crow_indices(self) -> Tensor:
        """``[n_rows + 1]`` row pointers (PyTorch name)."""
        return self._pointer

    def col_indices(self) -> Tensor:
        """``[nnz]`` column of each entry (PyTorch name)."""
        return self._minor

    def row_indices(self) -> Tensor:
        """``[nnz]`` row of each entry, expanded from the pointers."""
        return self._major_indices()

    def tocsr(self, return_map: bool = False):
        """Return ``self`` (already CSR; entries are left as stored).

        Use :meth:`coalesce` to sort columns and merge duplicates.
        """
        if return_map:
            return self, EdgeMap.identity(self.nnz, self._minor.device)
        return self

    def coalesce(self, return_map: bool = False):
        """Canonical CSR: sorted columns, duplicates summed."""
        return self.tocoo().tocsr(return_map)

    def tocsc(self, return_map: bool = False):
        return self.tocoo().tocsc(return_map)

    def transpose(self) -> "CSC":
        """Transpose without copying: the same arrays read as CSC."""
        return self._like(
            CSC,
            _shape=self._swapped_shape(),
            properties=self.properties.replace(triangular=None),
        )
Methods:
coalesce(return_map=False)

Canonical CSR: sorted columns, duplicates summed.

Source code in btorch/sparse/csr.py
def coalesce(self, return_map: bool = False):
    """Canonical CSR: sorted columns, duplicates summed."""
    return self.tocoo().tocsr(return_map)
col_indices()

[nnz] column of each entry (PyTorch name).

Source code in btorch/sparse/csr.py
def col_indices(self) -> Tensor:
    """``[nnz]`` column of each entry (PyTorch name)."""
    return self._minor
crow_indices()

[n_rows + 1] row pointers (PyTorch name).

Source code in btorch/sparse/csr.py
def crow_indices(self) -> Tensor:
    """``[n_rows + 1]`` row pointers (PyTorch name)."""
    return self._pointer
row_indices()

[nnz] row of each entry, expanded from the pointers.

Source code in btorch/sparse/csr.py
def row_indices(self) -> Tensor:
    """``[nnz]`` row of each entry, expanded from the pointers."""
    return self._major_indices()
tocsr(return_map=False)

Return self (already CSR; entries are left as stored).

Use :meth:coalesce to sort columns and merge duplicates.

Source code in btorch/sparse/csr.py
def tocsr(self, return_map: bool = False):
    """Return ``self`` (already CSR; entries are left as stored).

    Use :meth:`coalesce` to sort columns and merge duplicates.
    """
    if return_map:
        return self, EdgeMap.identity(self.nnz, self._minor.device)
    return self
transpose()

Transpose without copying: the same arrays read as CSC.

Source code in btorch/sparse/csr.py
def transpose(self) -> "CSC":
    """Transpose without copying: the same arrays read as CSC."""
    return self._like(
        CSC,
        _shape=self._swapped_shape(),
        properties=self.properties.replace(triangular=None),
    )

EdgeMap dataclass

Correspondence between the entries of two representations.

A representation change (sorting, duplicate reduction) maps every old entry e to a new entry target[e]. Every edge-aligned array (values, group ids, receptors, delays, plasticity state) must be moved with the same map, so the map is computed once and applied to each of them.

Parameters:

Name Type Description Default
target Tensor

[n_old] new position of every old entry.

required
n_new int

Number of entries after the change.

required
Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class EdgeMap:
    """Correspondence between the entries of two representations.

    A representation change (sorting, duplicate reduction) maps every old
    entry ``e`` to a new entry ``target[e]``. Every edge-aligned array (values,
    group ids, receptors, delays, plasticity state) must be moved with the same
    map, so the map is computed once and applied to each of them.

    Args:
        target: ``[n_old]`` new position of every old entry.
        n_new: Number of entries after the change.
    """

    target: Tensor
    n_new: int

    @property
    def n_old(self) -> int:
        return int(self.target.shape[0])

    @property
    def is_permutation(self) -> bool:
        """Whether no entries were merged."""
        return self.n_old == self.n_new

    def source(self) -> Tensor:
        """``[n_new]`` index of one old entry for every new entry.

        For merged duplicates this is the last old entry of the group.
        """
        old = torch.arange(self.n_old, device=self.target.device)
        if self.is_permutation:
            src = torch.empty_like(old)
            src[self.target] = old
            return src
        # Deterministic on every device (an indexed assignment with repeated
        # targets is not).
        src = self.target.new_zeros(self.n_new)
        return src.scatter_reduce(0, self.target, old, "amax", include_self=False)

    def sum(self, values: Tensor, dim: int = -1) -> Tensor:
        """Move additive data (weights); merged entries are summed.

        Differentiable: the gradient of a merged entry flows to every old
        entry that was merged into it.

        Args:
            values: Tensor whose axis ``dim`` has length ``n_old``.
            dim: Edge axis.
        """
        if self.is_permutation:
            return values.index_select(dim, self.source())
        shape = list(values.shape)
        shape[dim] = self.n_new
        return values.new_zeros(shape).index_add(dim, self.target, values)

    def take(self, meta: Tensor, dim: int = 0, check: bool = True) -> Tensor:
        """Move categorical metadata (group, receptor, delay ids).

        Args:
            meta: Tensor whose axis ``dim`` has length ``n_old``.
            dim: Edge axis.
            check: Raise if merged entries carry different metadata, because
                no single value can then represent the merged entry.

        Raises:
            ValueError: If ``check`` and merged duplicates disagree.
        """
        out = meta.index_select(dim, self.source())
        if check and not self.is_permutation:
            if not torch.equal(out.index_select(dim, self.target), meta):
                raise ValueError(
                    "Duplicate entries carry different metadata and cannot be "
                    "merged; split them into separate connections or make the "
                    "metadata equal first."
                )
        return out

    def compose(self, then: "EdgeMap") -> "EdgeMap":
        """Map equivalent to applying ``self`` and then ``then``."""
        return EdgeMap(then.target[self.target], then.n_new)

    @staticmethod
    def identity(n: int, device=None) -> "EdgeMap":
        return EdgeMap(torch.arange(n, device=device), n)
Attributes
is_permutation property

Whether no entries were merged.

Methods:
compose(then)

Map equivalent to applying self and then then.

Source code in btorch/sparse/properties.py
def compose(self, then: "EdgeMap") -> "EdgeMap":
    """Map equivalent to applying ``self`` and then ``then``."""
    return EdgeMap(then.target[self.target], then.n_new)
source()

[n_new] index of one old entry for every new entry.

For merged duplicates this is the last old entry of the group.

Source code in btorch/sparse/properties.py
def source(self) -> Tensor:
    """``[n_new]`` index of one old entry for every new entry.

    For merged duplicates this is the last old entry of the group.
    """
    old = torch.arange(self.n_old, device=self.target.device)
    if self.is_permutation:
        src = torch.empty_like(old)
        src[self.target] = old
        return src
    # Deterministic on every device (an indexed assignment with repeated
    # targets is not).
    src = self.target.new_zeros(self.n_new)
    return src.scatter_reduce(0, self.target, old, "amax", include_self=False)
sum(values, dim=-1)

Move additive data (weights); merged entries are summed.

Differentiable: the gradient of a merged entry flows to every old entry that was merged into it.

Parameters:

Name Type Description Default
values Tensor

Tensor whose axis dim has length n_old.

required
dim int

Edge axis.

-1
Source code in btorch/sparse/properties.py
def sum(self, values: Tensor, dim: int = -1) -> Tensor:
    """Move additive data (weights); merged entries are summed.

    Differentiable: the gradient of a merged entry flows to every old
    entry that was merged into it.

    Args:
        values: Tensor whose axis ``dim`` has length ``n_old``.
        dim: Edge axis.
    """
    if self.is_permutation:
        return values.index_select(dim, self.source())
    shape = list(values.shape)
    shape[dim] = self.n_new
    return values.new_zeros(shape).index_add(dim, self.target, values)
take(meta, dim=0, check=True)

Move categorical metadata (group, receptor, delay ids).

Parameters:

Name Type Description Default
meta Tensor

Tensor whose axis dim has length n_old.

required
dim int

Edge axis.

0
check bool

Raise if merged entries carry different metadata, because no single value can then represent the merged entry.

True

Raises:

Type Description
ValueError

If check and merged duplicates disagree.

Source code in btorch/sparse/properties.py
def take(self, meta: Tensor, dim: int = 0, check: bool = True) -> Tensor:
    """Move categorical metadata (group, receptor, delay ids).

    Args:
        meta: Tensor whose axis ``dim`` has length ``n_old``.
        dim: Edge axis.
        check: Raise if merged entries carry different metadata, because
            no single value can then represent the merged entry.

    Raises:
        ValueError: If ``check`` and merged duplicates disagree.
    """
    out = meta.index_select(dim, self.source())
    if check and not self.is_permutation:
        if not torch.equal(out.index_select(dim, self.target), meta):
            raise ValueError(
                "Duplicate entries carry different metadata and cannot be "
                "merged; split them into separate connections or make the "
                "metadata equal first."
            )
    return out

Hints dataclass

Performance expectations; advisory only.

Only expected_density is consulted by the planner today; the other two are accepted and reserved.

Parameters:

Name Type Description Default
expected_calls int | None

How many products the object will take part in (reserved).

None
expected_density float | None

Expected fraction of non-zero input entries, in [0, 1].

None
expected_batch int | None

Expected number of right-hand sides per call (reserved).

None

Raises:

Type Description
ValueError

If a value is out of range.

Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class Hints:
    """Performance expectations; advisory only.

    Only ``expected_density`` is consulted by the planner today; the other
    two are accepted and reserved.

    Args:
        expected_calls: How many products the object will take part in
            (reserved).
        expected_density: Expected fraction of non-zero input entries, in
            ``[0, 1]``.
        expected_batch: Expected number of right-hand sides per call
            (reserved).

    Raises:
        ValueError: If a value is out of range.
    """

    expected_calls: int | None = None
    expected_density: float | None = None
    expected_batch: int | None = None

    def __post_init__(self) -> None:
        density = self.expected_density
        if density is not None and not (
            isinstance(density, (int, float)) and 0.0 <= density <= 1.0
        ):
            raise ValueError(f"expected_density must be in [0, 1], got {density!r}.")
        for name in ("expected_calls", "expected_batch"):
            value = getattr(self, name)
            if value is not None and not (isinstance(value, int) and value > 0):
                raise ValueError(f"{name} must be a positive int, got {value!r}.")

    def replace(self, **changes) -> "Hints":
        """Return a copy with selected expectations changed."""
        return replace(self, **changes)
Methods:
replace(**changes)

Return a copy with selected expectations changed.

Source code in btorch/sparse/properties.py
def replace(self, **changes) -> "Hints":
    """Return a copy with selected expectations changed."""
    return replace(self, **changes)

Properties dataclass

Structural facts about a stored sparse representation.

A True value is a guarantee; False means "not known", never "known to be violated".

Parameters:

Name Type Description Default
sorted bool

Entries are in lexicographic (row-major) index order.

False
unique bool

No index tuple is stored twice.

False
symmetric bool

Stored values satisfy A == A.T.

False
structurally_symmetric bool

The sparsity pattern is symmetric.

False
triangular str | None

"lower", "upper" or None.

None
fixed_pattern bool

The pattern is never mutated (no rewiring).

False
shared_pattern bool

A batch of matrices shares one pattern.

False
Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class Properties:
    """Structural facts about a stored sparse representation.

    A ``True`` value is a guarantee; ``False`` means "not known", never
    "known to be violated".

    Args:
        sorted: Entries are in lexicographic (row-major) index order.
        unique: No index tuple is stored twice.
        symmetric: Stored values satisfy ``A == A.T``.
        structurally_symmetric: The sparsity pattern is symmetric.
        triangular: ``"lower"``, ``"upper"`` or ``None``.
        fixed_pattern: The pattern is never mutated (no rewiring).
        shared_pattern: A batch of matrices shares one pattern.
    """

    sorted: bool = False
    unique: bool = False
    symmetric: bool = False
    structurally_symmetric: bool = False
    triangular: str | None = None
    fixed_pattern: bool = False
    shared_pattern: bool = False

    @property
    def canonical(self) -> bool:
        """Whether entries are sorted and free of duplicates."""
        return self.sorted and self.unique

    def replace(self, **changes) -> "Properties":
        """Return a copy with some fields changed."""
        return replace(self, **changes)
Attributes
canonical property

Whether entries are sorted and free of duplicates.

Methods:
replace(**changes)

Return a copy with some fields changed.

Source code in btorch/sparse/properties.py
def replace(self, **changes) -> "Properties":
    """Return a copy with some fields changed."""
    return replace(self, **changes)

Sparse

Sparse array with logical shape [*batch, *sparse, *dense].

Sparse is the format-agnostic interface. It describes what the array is (shape, dtype, device, number of stored entries) and offers the operations every format supports. Format-specific data such as indptr is only available on the concrete classes (:class:~btorch.sparse.COO, :class:~btorch.sparse.CSR, :class:~btorch.sparse.CSC), obtained with tocsr() / as_csr() and friends.

The three shape groups are:

  • batch_shape: independent sparse arrays (for example an ensemble of networks).
  • sparse_shape: the dimensions that are stored sparsely.
  • dense_shape: a dense payload attached to every stored entry.

Stored values have shape [*value_batch, nnz, *dense_shape]. A batch whose members share one sparsity pattern stores the pattern once and only the values per member.

Sparse is a plain Python object holding tensors; it is not a torch.Tensor subclass. Matrix products follow standard linear algebra: for A.shape == (M, N), A @ x maps a length-N vector to a length-M vector. Conversions never transpose.

Source code in btorch/sparse/base.py
class Sparse:
    """Sparse array with logical shape ``[*batch, *sparse, *dense]``.

    ``Sparse`` is the format-agnostic interface. It describes *what* the array
    is (shape, dtype, device, number of stored entries) and offers the
    operations every format supports. Format-specific data such as ``indptr``
    is only available on the concrete classes (:class:`~btorch.sparse.COO`,
    :class:`~btorch.sparse.CSR`, :class:`~btorch.sparse.CSC`), obtained with
    ``tocsr()`` / ``as_csr()`` and friends.

    The three shape groups are:

    - ``batch_shape``: independent sparse arrays (for example an ensemble of
      networks).
    - ``sparse_shape``: the dimensions that are stored sparsely.
    - ``dense_shape``: a dense payload attached to every stored entry.

    Stored values have shape ``[*value_batch, nnz, *dense_shape]``. A batch
    whose members share one sparsity pattern stores the pattern once and only
    the values per member.

    ``Sparse`` is a plain Python object holding tensors; it is not a
    ``torch.Tensor`` subclass. Matrix products follow standard linear algebra:
    for ``A.shape == (M, N)``, ``A @ x`` maps a length-``N`` vector to a
    length-``M`` vector. Conversions never transpose.
    """

    format: str = "sparse"
    # Let ``ndarray @ A`` reach ``__rmatmul__`` instead of NumPy treating the
    # sparse array as an object scalar.
    __array_ufunc__ = None

    _values: Tensor
    _shape: tuple[int, ...]
    _batch_dim: int
    _dense_dim: int
    properties: Properties
    hints: Hints

    # ------------------------------------------------------------------ shape
    @property
    def shape(self) -> tuple[int, ...]:
        """Logical shape ``(*batch, *sparse, *dense)``."""
        return self._shape

    @property
    def ndim(self) -> int:
        return len(self._shape)

    def batch_dim(self) -> int:
        """Number of batch dimensions."""
        return self._batch_dim

    def dense_dim(self) -> int:
        """Number of dense (per-entry payload) dimensions."""
        return self._dense_dim

    def sparse_dim(self) -> int:
        """Number of sparsely stored dimensions."""
        return self.ndim - self._batch_dim - self._dense_dim

    @property
    def batch_shape(self) -> tuple[int, ...]:
        return self._shape[: self._batch_dim]

    @property
    def sparse_shape(self) -> tuple[int, ...]:
        return self._shape[self._batch_dim : self.ndim - self._dense_dim]

    @property
    def dense_shape(self) -> tuple[int, ...]:
        return self._shape[self.ndim - self._dense_dim :]

    @property
    def dtype(self) -> torch.dtype:
        return self._values.dtype

    @property
    def device(self) -> torch.device:
        return self._values.device

    @property
    def nnz(self) -> int:
        """Number of stored entries (of one batch member for a shared pattern,
        of all members together otherwise)."""
        raise NotImplementedError

    @property
    def requires_grad(self) -> bool:
        return self._values.requires_grad

    # ------------------------------------------------------- format changes
    def tocoo(self) -> "COO":
        """Convert to COO (may allocate)."""
        raise NotImplementedError

    def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
        """Convert to CSR (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
        """Convert to CSC (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tobsr(self, blocksize: tuple[int, int]):
        """Convert to BSR; not implemented as a native format.

        Use ``to_torch(layout="bsr", blocksize=...)`` or
        ``to_scipy(format="bsr")`` to export block storage.
        """
        raise NotImplementedError(
            "BSR is not a native btorch format yet; export with "
            "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
        )

    def _as(self, fmt: str):
        if self.format != fmt:
            hint = (
                "BSR is not a native format; export with to_torch(layout='bsr')."
                if fmt == "bsr"
                else f"Call to{fmt}() to convert explicitly."
            )
            raise TypeError(
                f"This sparse array is stored as {self.format.upper()}, not "
                f"{fmt.upper()}; as_{fmt}() never converts. {hint}"
            )
        return self

    def as_coo(self) -> "COO":
        """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
        return self._as("coo")

    def as_csr(self) -> "CSR":
        """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
        return self._as("csr")

    def as_csc(self) -> "CSC":
        """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
        return self._as("csc")

    def as_bsr(self, blocksize: tuple[int, int] | None = None):
        """BSR is not a native format; always raises ``TypeError``."""
        return self._as("bsr")

    # -------------------------------------------------------------- interop
    @classmethod
    def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
        """Wrap a ``torch`` sparse tensor (see
        :func:`btorch.sparse.from_torch`)."""
        from .conversion import from_torch

        return from_torch(tensor, batch_dim=batch_dim)

    @classmethod
    def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
        """Convert a SciPy sparse array or matrix (see
        :func:`btorch.sparse.from_scipy`)."""
        from .conversion import from_scipy

        return from_scipy(array, device=device, dtype=dtype)

    def to_torch(
        self, layout: str | torch.layout | None = None, **kwargs: Any
    ) -> Tensor:
        """Export as a ``torch`` sparse tensor.

        Args:
            layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
                (or the ``torch.sparse_*`` layout). Defaults to the stored
                format.
            **kwargs: ``blocksize`` for the block layouts.
        """
        from .conversion import to_torch

        return to_torch(self, layout, **kwargs)

    def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
        """Export as a ``scipy.sparse`` array (CPU, detached).

        Args:
            format: Any SciPy format name; defaults to the stored format.
            **kwargs: ``blocksize`` for ``"bsr"``.
        """
        from .conversion import to_scipy

        return to_scipy(self, format, **kwargs)

    def to_dense(self) -> Tensor:
        """Materialise as a dense tensor of shape :attr:`shape`."""
        return self.tocoo().to_dense()

    # ------------------------------------------------------- tensor handling
    def with_values(self, values: Tensor) -> "Sparse":
        """Return an array with the same pattern and new values.

        ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
        shape creates a shared-pattern batch.
        """
        raise NotImplementedError

    def _map_tensors(self, index_fn, value_fn) -> "Sparse":
        """Apply ``index_fn`` to index tensors and ``value_fn`` to values."""
        raise NotImplementedError

    def to(self, *args, **kwargs) -> "Sparse":
        """Move to a device and/or cast the values (indices stay integer)."""
        device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

        return self._map_tensors(
            lambda index: index.to(device=device),
            lambda values: values.to(device=device, dtype=dtype),
        )

    def cpu(self) -> "Sparse":
        return self.to("cpu")

    def cuda(self, device=None) -> "Sparse":
        return self.to("cuda" if device is None else device)

    def float(self) -> "Sparse":
        return self.to(torch.float32)

    def double(self) -> "Sparse":
        return self.to(torch.float64)

    def detach(self) -> "Sparse":
        return self.with_values(self._values.detach())

    # ------------------------------------------------------------- products
    def matvec(self, x: Tensor) -> Tensor:
        """Apply the operator along the last axis of ``x``.

        See :func:`btorch.sparse.matvec`.
        """
        from .ops import matvec

        return matvec(self, x)

    def rmatvec(self, x: Tensor) -> Tensor:
        """Apply the transposed operator along the last axis of ``x``."""
        from .ops import rmatvec

        return rmatvec(self, x)

    def __matmul__(self, other):
        from .ops import matmul

        return matmul(self, other)

    def __rmatmul__(self, other):
        from .ops import matmul

        return matmul(other, self)

    @property
    def T(self) -> "Sparse":
        """Transpose of the two sparse dimensions."""
        return self.transpose()

    def transpose(self) -> "Sparse":
        raise NotImplementedError

    def __repr__(self) -> str:
        parts = [f"shape={self.shape}", f"nnz={self.nnz}", f"dtype={self.dtype}"]
        if self.batch_dim():
            parts.append(f"batch_shape={self.batch_shape}")
        if self.dense_dim():
            parts.append(f"dense_shape={self.dense_shape}")
        if self.device.type != "cpu":
            parts.append(f"device={self.device}")
        return f"{type(self).__name__}({', '.join(parts)})"
Attributes
T property

Transpose of the two sparse dimensions.

nnz property

Number of stored entries (of one batch member for a shared pattern, of all members together otherwise).

shape property

Logical shape (*batch, *sparse, *dense).

Methods:
as_bsr(blocksize=None)

BSR is not a native format; always raises TypeError.

Source code in btorch/sparse/base.py
def as_bsr(self, blocksize: tuple[int, int] | None = None):
    """BSR is not a native format; always raises ``TypeError``."""
    return self._as("bsr")
as_coo()

Return self if it is stored as COO, else raise TypeError.

Source code in btorch/sparse/base.py
def as_coo(self) -> "COO":
    """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
    return self._as("coo")
as_csc()

Return self if it is stored as CSC, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csc(self) -> "CSC":
    """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
    return self._as("csc")
as_csr()

Return self if it is stored as CSR, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csr(self) -> "CSR":
    """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
    return self._as("csr")
batch_dim()

Number of batch dimensions.

Source code in btorch/sparse/base.py
def batch_dim(self) -> int:
    """Number of batch dimensions."""
    return self._batch_dim
dense_dim()

Number of dense (per-entry payload) dimensions.

Source code in btorch/sparse/base.py
def dense_dim(self) -> int:
    """Number of dense (per-entry payload) dimensions."""
    return self._dense_dim
from_scipy(array, *, device=None, dtype=None) classmethod

Convert a SciPy sparse array or matrix (see :func:btorch.sparse.from_scipy).

Source code in btorch/sparse/base.py
@classmethod
def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
    """Convert a SciPy sparse array or matrix (see
    :func:`btorch.sparse.from_scipy`)."""
    from .conversion import from_scipy

    return from_scipy(array, device=device, dtype=dtype)
from_torch(tensor, *, batch_dim=0) classmethod

Wrap a torch sparse tensor (see :func:btorch.sparse.from_torch).

Source code in btorch/sparse/base.py
@classmethod
def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
    """Wrap a ``torch`` sparse tensor (see
    :func:`btorch.sparse.from_torch`)."""
    from .conversion import from_torch

    return from_torch(tensor, batch_dim=batch_dim)
matvec(x)

Apply the operator along the last axis of x.

See :func:btorch.sparse.matvec.

Source code in btorch/sparse/base.py
def matvec(self, x: Tensor) -> Tensor:
    """Apply the operator along the last axis of ``x``.

    See :func:`btorch.sparse.matvec`.
    """
    from .ops import matvec

    return matvec(self, x)
rmatvec(x)

Apply the transposed operator along the last axis of x.

Source code in btorch/sparse/base.py
def rmatvec(self, x: Tensor) -> Tensor:
    """Apply the transposed operator along the last axis of ``x``."""
    from .ops import rmatvec

    return rmatvec(self, x)
sparse_dim()

Number of sparsely stored dimensions.

Source code in btorch/sparse/base.py
def sparse_dim(self) -> int:
    """Number of sparsely stored dimensions."""
    return self.ndim - self._batch_dim - self._dense_dim
to(*args, **kwargs)

Move to a device and/or cast the values (indices stay integer).

Source code in btorch/sparse/base.py
def to(self, *args, **kwargs) -> "Sparse":
    """Move to a device and/or cast the values (indices stay integer)."""
    device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

    return self._map_tensors(
        lambda index: index.to(device=device),
        lambda values: values.to(device=device, dtype=dtype),
    )
to_dense()

Materialise as a dense tensor of shape :attr:shape.

Source code in btorch/sparse/base.py
def to_dense(self) -> Tensor:
    """Materialise as a dense tensor of shape :attr:`shape`."""
    return self.tocoo().to_dense()
to_scipy(format=None, **kwargs)

Export as a scipy.sparse array (CPU, detached).

Parameters:

Name Type Description Default
format str | None

Any SciPy format name; defaults to the stored format.

None
**kwargs Any

blocksize for "bsr".

{}
Source code in btorch/sparse/base.py
def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
    """Export as a ``scipy.sparse`` array (CPU, detached).

    Args:
        format: Any SciPy format name; defaults to the stored format.
        **kwargs: ``blocksize`` for ``"bsr"``.
    """
    from .conversion import to_scipy

    return to_scipy(self, format, **kwargs)
to_torch(layout=None, **kwargs)

Export as a torch sparse tensor.

Parameters:

Name Type Description Default
layout str | layout | None

"coo", "csr", "csc", "bsr" or "bsc" (or the torch.sparse_* layout). Defaults to the stored format.

None
**kwargs Any

blocksize for the block layouts.

{}
Source code in btorch/sparse/base.py
def to_torch(
    self, layout: str | torch.layout | None = None, **kwargs: Any
) -> Tensor:
    """Export as a ``torch`` sparse tensor.

    Args:
        layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
            (or the ``torch.sparse_*`` layout). Defaults to the stored
            format.
        **kwargs: ``blocksize`` for the block layouts.
    """
    from .conversion import to_torch

    return to_torch(self, layout, **kwargs)
tobsr(blocksize)

Convert to BSR; not implemented as a native format.

Use to_torch(layout="bsr", blocksize=...) or to_scipy(format="bsr") to export block storage.

Source code in btorch/sparse/base.py
def tobsr(self, blocksize: tuple[int, int]):
    """Convert to BSR; not implemented as a native format.

    Use ``to_torch(layout="bsr", blocksize=...)`` or
    ``to_scipy(format="bsr")`` to export block storage.
    """
    raise NotImplementedError(
        "BSR is not a native btorch format yet; export with "
        "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
    )
tocoo()

Convert to COO (may allocate).

Source code in btorch/sparse/base.py
def tocoo(self) -> "COO":
    """Convert to COO (may allocate)."""
    raise NotImplementedError
tocsc(return_map=False)

Convert to CSC (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
    """Convert to CSC (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
tocsr(return_map=False)

Convert to CSR (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
    """Convert to CSR (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
with_values(values)

Return an array with the same pattern and new values.

values is [*batch, nnz, *dense]; a different leading batch shape creates a shared-pattern batch.

Source code in btorch/sparse/base.py
def with_values(self, values: Tensor) -> "Sparse":
    """Return an array with the same pattern and new values.

    ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
    shape creates a shared-pattern batch.
    """
    raise NotImplementedError

_Compressed

Bases: Sparse

Shared implementation of CSR and CSC.

pointer compresses the major axis (rows for CSR, columns for CSC) and minor holds the other coordinate of every entry.

Source code in btorch/sparse/csr.py
class _Compressed(Sparse):
    """Shared implementation of CSR and CSC.

    ``pointer`` compresses the *major* axis (rows for CSR, columns for CSC)
    and ``minor`` holds the other coordinate of every entry.
    """

    _major_axis: int  # 0 for CSR (rows), 1 for CSC (columns)

    def __init__(
        self,
        pointer: Tensor,
        minor: Tensor,
        values: Tensor,
        shape: tuple[int, ...],
        *,
        dense_dim: int = 0,
        properties: Properties | None = None,
        hints: Hints | None = None,
        check: bool = True,
    ):
        values = _as_tensor(values)
        pointer = _check_index("pointer", _as_tensor(pointer, device=values.device))
        minor = _check_index("indices", _as_tensor(minor, device=values.device))
        shape = tuple(int(s) for s in shape)
        name = type(self).__name__
        if pointer.ndim != 1 or minor.ndim != 1:
            raise ValueError(
                f"{name} stores one sparsity pattern: the pointer and index "
                "arrays must be 1-D. Batch members that share the pattern only "
                "differ in `values` ([*batch, nnz]); use sparse.stack() for "
                "different patterns."
            )
        batch_dim = values.ndim - 1 - dense_dim
        if batch_dim < 0 or len(shape) != batch_dim + 2 + dense_dim:
            raise ValueError(
                f"shape {shape} is inconsistent with values of shape "
                f"{tuple(values.shape)} and dense_dim={dense_dim}; {name} has "
                "exactly two sparse dimensions."
            )
        n_major = shape[batch_dim + self._major_axis]
        n_minor = shape[batch_dim + 1 - self._major_axis]
        nnz = int(minor.shape[0])
        if pointer.shape[0] != n_major + 1:
            raise ValueError(
                f"pointer has length {pointer.shape[0]}, expected {n_major + 1}."
            )
        expected = (
            shape[:batch_dim]
            + (nnz,)
            + shape[len(shape) - dense_dim :] * bool(dense_dim)
        )
        if tuple(values.shape) != expected:
            raise ValueError(
                f"values has shape {tuple(values.shape)}, expected {expected}."
            )
        if check:
            if int(pointer[0]) != 0 or int(pointer[-1]) != nnz:
                raise ValueError("pointer must start at 0 and end at nnz.")
            if bool((pointer[1:] < pointer[:-1]).any()):
                raise ValueError("pointer must be non-decreasing.")
            if nnz and (int(minor.min()) < 0 or int(minor.max()) >= n_minor):
                raise ValueError(f"indices must be in [0, {n_minor}).")
        self._pointer = pointer
        self._minor = minor
        self._values = values
        self._shape = shape
        self._batch_dim = batch_dim
        self._dense_dim = dense_dim
        self._value_batch_dim = batch_dim
        # Expanded major coordinate of each entry. Computed eagerly: filling
        # it lazily would change object state during a ``torch.compile``
        # trace and force a recompilation on the next call.
        counts = pointer[1:] - pointer[:-1]
        self._major = torch.repeat_interleave(
            torch.arange(counts.shape[0], device=counts.device), counts
        )
        self.properties = properties or Properties()
        if self.properties.shared_pattern != bool(batch_dim):
            self.properties = self.properties.replace(shared_pattern=bool(batch_dim))
        self.hints = hints or Hints()

    @property
    def nnz(self) -> int:
        return int(self._minor.shape[0])

    def values(self) -> Tensor:
        """``[*batch, nnz, *dense]`` stored values (PyTorch name)."""
        return self._values

    @property
    def data(self) -> Tensor:
        """Stored values (SciPy name)."""
        return self._values

    @property
    def indptr(self) -> Tensor:
        """Pointer array of the compressed axis (SciPy name)."""
        return self._pointer

    @property
    def indices(self) -> Tensor:
        """Coordinate of each entry along the uncompressed axis (SciPy
        name)."""
        return self._minor

    def _major_indices(self) -> Tensor:
        """Expanded coordinate of each entry along the compressed axis."""
        return self._major

    def _like(self, cls, **changes):
        out = cls.__new__(cls)
        out.__dict__.update(self.__dict__)
        for key, value in changes.items():
            setattr(out, key, value)
        return out

    def with_values(self, values: Tensor):
        batch_dim = values.ndim - 1 - self._dense_dim
        out = type(self)(
            self._pointer,
            self._minor,
            values,
            tuple(values.shape[:batch_dim]) + self._shape[self._batch_dim :],
            dense_dim=self._dense_dim,
            properties=self.properties,
            hints=self.hints,
            check=False,
        )
        out._major = self._major
        return out

    def _map_tensors(self, index_fn, value_fn):
        return self._like(
            type(self),
            _pointer=index_fn(self._pointer),
            _minor=index_fn(self._minor),
            _values=value_fn(self._values),
            _major=index_fn(self._major),
        )

    def _swapped_shape(self) -> tuple[int, ...]:
        shape = list(self._shape)
        i = self._batch_dim
        shape[i], shape[i + 1] = shape[i + 1], shape[i]
        return tuple(shape)

    def tocoo(self):
        from .coo import COO

        row, col = self._major_indices(), self._minor
        props = self.properties
        if self._major_axis == 1:
            row, col = col, row
            props = props.replace(sorted=False)
        return COO(
            torch.stack([row, col]),
            self._values,
            self._shape,
            dense_dim=self._dense_dim,
            properties=props,
            hints=self.hints,
            check=False,
        )

    def _edge_index(self) -> tuple[None, Tensor, Tensor]:
        if self._major_axis == 0:
            return None, self._major_indices(), self._minor
        return None, self._minor, self._major_indices()
Attributes
data property

Stored values (SciPy name).

indices property

Coordinate of each entry along the uncompressed axis (SciPy name).

indptr property

Pointer array of the compressed axis (SciPy name).

Methods:
values()

[*batch, nnz, *dense] stored values (PyTorch name).

Source code in btorch/sparse/csr.py
def values(self) -> Tensor:
    """``[*batch, nnz, *dense]`` stored values (PyTorch name)."""
    return self._values

Functions:

_as_tensor(x, *, dtype=None, device=None)

Source code in btorch/sparse/base.py
def _as_tensor(x, *, dtype=None, device=None) -> Tensor:
    if isinstance(x, Tensor):
        return (
            x if dtype is None and device is None else x.to(device=device, dtype=dtype)
        )
    return torch.as_tensor(x, dtype=dtype, device=device)

_check_index(name, index)

Source code in btorch/sparse/base.py
def _check_index(name: str, index: Tensor) -> Tensor:
    if index.numel() == 0:
        # An empty Python list becomes a float tensor; it is still a valid
        # (empty) index.
        return index.to(torch.long)
    if index.is_floating_point() or index.dtype == torch.bool:
        raise TypeError(f"{name} must be an integer tensor, got {index.dtype}.")
    return index.to(torch.long)

btorch.sparse.einsum

Experimental Einstein summation with one N-D sparse operand.

:func:einsum contracts one sparse array with dense tensors and returns a dense tensor. It is a gather / contract / scatter lowering over the COO entry list, not a sparse tensor compiler: see docs/en/docs/design/ sparse_einsum_notes.md for what the general problem needs.

Classes

Sparse

Sparse array with logical shape [*batch, *sparse, *dense].

Sparse is the format-agnostic interface. It describes what the array is (shape, dtype, device, number of stored entries) and offers the operations every format supports. Format-specific data such as indptr is only available on the concrete classes (:class:~btorch.sparse.COO, :class:~btorch.sparse.CSR, :class:~btorch.sparse.CSC), obtained with tocsr() / as_csr() and friends.

The three shape groups are:

  • batch_shape: independent sparse arrays (for example an ensemble of networks).
  • sparse_shape: the dimensions that are stored sparsely.
  • dense_shape: a dense payload attached to every stored entry.

Stored values have shape [*value_batch, nnz, *dense_shape]. A batch whose members share one sparsity pattern stores the pattern once and only the values per member.

Sparse is a plain Python object holding tensors; it is not a torch.Tensor subclass. Matrix products follow standard linear algebra: for A.shape == (M, N), A @ x maps a length-N vector to a length-M vector. Conversions never transpose.

Source code in btorch/sparse/base.py
class Sparse:
    """Sparse array with logical shape ``[*batch, *sparse, *dense]``.

    ``Sparse`` is the format-agnostic interface. It describes *what* the array
    is (shape, dtype, device, number of stored entries) and offers the
    operations every format supports. Format-specific data such as ``indptr``
    is only available on the concrete classes (:class:`~btorch.sparse.COO`,
    :class:`~btorch.sparse.CSR`, :class:`~btorch.sparse.CSC`), obtained with
    ``tocsr()`` / ``as_csr()`` and friends.

    The three shape groups are:

    - ``batch_shape``: independent sparse arrays (for example an ensemble of
      networks).
    - ``sparse_shape``: the dimensions that are stored sparsely.
    - ``dense_shape``: a dense payload attached to every stored entry.

    Stored values have shape ``[*value_batch, nnz, *dense_shape]``. A batch
    whose members share one sparsity pattern stores the pattern once and only
    the values per member.

    ``Sparse`` is a plain Python object holding tensors; it is not a
    ``torch.Tensor`` subclass. Matrix products follow standard linear algebra:
    for ``A.shape == (M, N)``, ``A @ x`` maps a length-``N`` vector to a
    length-``M`` vector. Conversions never transpose.
    """

    format: str = "sparse"
    # Let ``ndarray @ A`` reach ``__rmatmul__`` instead of NumPy treating the
    # sparse array as an object scalar.
    __array_ufunc__ = None

    _values: Tensor
    _shape: tuple[int, ...]
    _batch_dim: int
    _dense_dim: int
    properties: Properties
    hints: Hints

    # ------------------------------------------------------------------ shape
    @property
    def shape(self) -> tuple[int, ...]:
        """Logical shape ``(*batch, *sparse, *dense)``."""
        return self._shape

    @property
    def ndim(self) -> int:
        return len(self._shape)

    def batch_dim(self) -> int:
        """Number of batch dimensions."""
        return self._batch_dim

    def dense_dim(self) -> int:
        """Number of dense (per-entry payload) dimensions."""
        return self._dense_dim

    def sparse_dim(self) -> int:
        """Number of sparsely stored dimensions."""
        return self.ndim - self._batch_dim - self._dense_dim

    @property
    def batch_shape(self) -> tuple[int, ...]:
        return self._shape[: self._batch_dim]

    @property
    def sparse_shape(self) -> tuple[int, ...]:
        return self._shape[self._batch_dim : self.ndim - self._dense_dim]

    @property
    def dense_shape(self) -> tuple[int, ...]:
        return self._shape[self.ndim - self._dense_dim :]

    @property
    def dtype(self) -> torch.dtype:
        return self._values.dtype

    @property
    def device(self) -> torch.device:
        return self._values.device

    @property
    def nnz(self) -> int:
        """Number of stored entries (of one batch member for a shared pattern,
        of all members together otherwise)."""
        raise NotImplementedError

    @property
    def requires_grad(self) -> bool:
        return self._values.requires_grad

    # ------------------------------------------------------- format changes
    def tocoo(self) -> "COO":
        """Convert to COO (may allocate)."""
        raise NotImplementedError

    def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
        """Convert to CSR (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
        """Convert to CSC (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tobsr(self, blocksize: tuple[int, int]):
        """Convert to BSR; not implemented as a native format.

        Use ``to_torch(layout="bsr", blocksize=...)`` or
        ``to_scipy(format="bsr")`` to export block storage.
        """
        raise NotImplementedError(
            "BSR is not a native btorch format yet; export with "
            "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
        )

    def _as(self, fmt: str):
        if self.format != fmt:
            hint = (
                "BSR is not a native format; export with to_torch(layout='bsr')."
                if fmt == "bsr"
                else f"Call to{fmt}() to convert explicitly."
            )
            raise TypeError(
                f"This sparse array is stored as {self.format.upper()}, not "
                f"{fmt.upper()}; as_{fmt}() never converts. {hint}"
            )
        return self

    def as_coo(self) -> "COO":
        """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
        return self._as("coo")

    def as_csr(self) -> "CSR":
        """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
        return self._as("csr")

    def as_csc(self) -> "CSC":
        """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
        return self._as("csc")

    def as_bsr(self, blocksize: tuple[int, int] | None = None):
        """BSR is not a native format; always raises ``TypeError``."""
        return self._as("bsr")

    # -------------------------------------------------------------- interop
    @classmethod
    def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
        """Wrap a ``torch`` sparse tensor (see
        :func:`btorch.sparse.from_torch`)."""
        from .conversion import from_torch

        return from_torch(tensor, batch_dim=batch_dim)

    @classmethod
    def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
        """Convert a SciPy sparse array or matrix (see
        :func:`btorch.sparse.from_scipy`)."""
        from .conversion import from_scipy

        return from_scipy(array, device=device, dtype=dtype)

    def to_torch(
        self, layout: str | torch.layout | None = None, **kwargs: Any
    ) -> Tensor:
        """Export as a ``torch`` sparse tensor.

        Args:
            layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
                (or the ``torch.sparse_*`` layout). Defaults to the stored
                format.
            **kwargs: ``blocksize`` for the block layouts.
        """
        from .conversion import to_torch

        return to_torch(self, layout, **kwargs)

    def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
        """Export as a ``scipy.sparse`` array (CPU, detached).

        Args:
            format: Any SciPy format name; defaults to the stored format.
            **kwargs: ``blocksize`` for ``"bsr"``.
        """
        from .conversion import to_scipy

        return to_scipy(self, format, **kwargs)

    def to_dense(self) -> Tensor:
        """Materialise as a dense tensor of shape :attr:`shape`."""
        return self.tocoo().to_dense()

    # ------------------------------------------------------- tensor handling
    def with_values(self, values: Tensor) -> "Sparse":
        """Return an array with the same pattern and new values.

        ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
        shape creates a shared-pattern batch.
        """
        raise NotImplementedError

    def _map_tensors(self, index_fn, value_fn) -> "Sparse":
        """Apply ``index_fn`` to index tensors and ``value_fn`` to values."""
        raise NotImplementedError

    def to(self, *args, **kwargs) -> "Sparse":
        """Move to a device and/or cast the values (indices stay integer)."""
        device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

        return self._map_tensors(
            lambda index: index.to(device=device),
            lambda values: values.to(device=device, dtype=dtype),
        )

    def cpu(self) -> "Sparse":
        return self.to("cpu")

    def cuda(self, device=None) -> "Sparse":
        return self.to("cuda" if device is None else device)

    def float(self) -> "Sparse":
        return self.to(torch.float32)

    def double(self) -> "Sparse":
        return self.to(torch.float64)

    def detach(self) -> "Sparse":
        return self.with_values(self._values.detach())

    # ------------------------------------------------------------- products
    def matvec(self, x: Tensor) -> Tensor:
        """Apply the operator along the last axis of ``x``.

        See :func:`btorch.sparse.matvec`.
        """
        from .ops import matvec

        return matvec(self, x)

    def rmatvec(self, x: Tensor) -> Tensor:
        """Apply the transposed operator along the last axis of ``x``."""
        from .ops import rmatvec

        return rmatvec(self, x)

    def __matmul__(self, other):
        from .ops import matmul

        return matmul(self, other)

    def __rmatmul__(self, other):
        from .ops import matmul

        return matmul(other, self)

    @property
    def T(self) -> "Sparse":
        """Transpose of the two sparse dimensions."""
        return self.transpose()

    def transpose(self) -> "Sparse":
        raise NotImplementedError

    def __repr__(self) -> str:
        parts = [f"shape={self.shape}", f"nnz={self.nnz}", f"dtype={self.dtype}"]
        if self.batch_dim():
            parts.append(f"batch_shape={self.batch_shape}")
        if self.dense_dim():
            parts.append(f"dense_shape={self.dense_shape}")
        if self.device.type != "cpu":
            parts.append(f"device={self.device}")
        return f"{type(self).__name__}({', '.join(parts)})"
Attributes
T property

Transpose of the two sparse dimensions.

nnz property

Number of stored entries (of one batch member for a shared pattern, of all members together otherwise).

shape property

Logical shape (*batch, *sparse, *dense).

Methods:
as_bsr(blocksize=None)

BSR is not a native format; always raises TypeError.

Source code in btorch/sparse/base.py
def as_bsr(self, blocksize: tuple[int, int] | None = None):
    """BSR is not a native format; always raises ``TypeError``."""
    return self._as("bsr")
as_coo()

Return self if it is stored as COO, else raise TypeError.

Source code in btorch/sparse/base.py
def as_coo(self) -> "COO":
    """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
    return self._as("coo")
as_csc()

Return self if it is stored as CSC, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csc(self) -> "CSC":
    """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
    return self._as("csc")
as_csr()

Return self if it is stored as CSR, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csr(self) -> "CSR":
    """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
    return self._as("csr")
batch_dim()

Number of batch dimensions.

Source code in btorch/sparse/base.py
def batch_dim(self) -> int:
    """Number of batch dimensions."""
    return self._batch_dim
dense_dim()

Number of dense (per-entry payload) dimensions.

Source code in btorch/sparse/base.py
def dense_dim(self) -> int:
    """Number of dense (per-entry payload) dimensions."""
    return self._dense_dim
from_scipy(array, *, device=None, dtype=None) classmethod

Convert a SciPy sparse array or matrix (see :func:btorch.sparse.from_scipy).

Source code in btorch/sparse/base.py
@classmethod
def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
    """Convert a SciPy sparse array or matrix (see
    :func:`btorch.sparse.from_scipy`)."""
    from .conversion import from_scipy

    return from_scipy(array, device=device, dtype=dtype)
from_torch(tensor, *, batch_dim=0) classmethod

Wrap a torch sparse tensor (see :func:btorch.sparse.from_torch).

Source code in btorch/sparse/base.py
@classmethod
def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
    """Wrap a ``torch`` sparse tensor (see
    :func:`btorch.sparse.from_torch`)."""
    from .conversion import from_torch

    return from_torch(tensor, batch_dim=batch_dim)
matvec(x)

Apply the operator along the last axis of x.

See :func:btorch.sparse.matvec.

Source code in btorch/sparse/base.py
def matvec(self, x: Tensor) -> Tensor:
    """Apply the operator along the last axis of ``x``.

    See :func:`btorch.sparse.matvec`.
    """
    from .ops import matvec

    return matvec(self, x)
rmatvec(x)

Apply the transposed operator along the last axis of x.

Source code in btorch/sparse/base.py
def rmatvec(self, x: Tensor) -> Tensor:
    """Apply the transposed operator along the last axis of ``x``."""
    from .ops import rmatvec

    return rmatvec(self, x)
sparse_dim()

Number of sparsely stored dimensions.

Source code in btorch/sparse/base.py
def sparse_dim(self) -> int:
    """Number of sparsely stored dimensions."""
    return self.ndim - self._batch_dim - self._dense_dim
to(*args, **kwargs)

Move to a device and/or cast the values (indices stay integer).

Source code in btorch/sparse/base.py
def to(self, *args, **kwargs) -> "Sparse":
    """Move to a device and/or cast the values (indices stay integer)."""
    device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

    return self._map_tensors(
        lambda index: index.to(device=device),
        lambda values: values.to(device=device, dtype=dtype),
    )
to_dense()

Materialise as a dense tensor of shape :attr:shape.

Source code in btorch/sparse/base.py
def to_dense(self) -> Tensor:
    """Materialise as a dense tensor of shape :attr:`shape`."""
    return self.tocoo().to_dense()
to_scipy(format=None, **kwargs)

Export as a scipy.sparse array (CPU, detached).

Parameters:

Name Type Description Default
format str | None

Any SciPy format name; defaults to the stored format.

None
**kwargs Any

blocksize for "bsr".

{}
Source code in btorch/sparse/base.py
def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
    """Export as a ``scipy.sparse`` array (CPU, detached).

    Args:
        format: Any SciPy format name; defaults to the stored format.
        **kwargs: ``blocksize`` for ``"bsr"``.
    """
    from .conversion import to_scipy

    return to_scipy(self, format, **kwargs)
to_torch(layout=None, **kwargs)

Export as a torch sparse tensor.

Parameters:

Name Type Description Default
layout str | layout | None

"coo", "csr", "csc", "bsr" or "bsc" (or the torch.sparse_* layout). Defaults to the stored format.

None
**kwargs Any

blocksize for the block layouts.

{}
Source code in btorch/sparse/base.py
def to_torch(
    self, layout: str | torch.layout | None = None, **kwargs: Any
) -> Tensor:
    """Export as a ``torch`` sparse tensor.

    Args:
        layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
            (or the ``torch.sparse_*`` layout). Defaults to the stored
            format.
        **kwargs: ``blocksize`` for the block layouts.
    """
    from .conversion import to_torch

    return to_torch(self, layout, **kwargs)
tobsr(blocksize)

Convert to BSR; not implemented as a native format.

Use to_torch(layout="bsr", blocksize=...) or to_scipy(format="bsr") to export block storage.

Source code in btorch/sparse/base.py
def tobsr(self, blocksize: tuple[int, int]):
    """Convert to BSR; not implemented as a native format.

    Use ``to_torch(layout="bsr", blocksize=...)`` or
    ``to_scipy(format="bsr")`` to export block storage.
    """
    raise NotImplementedError(
        "BSR is not a native btorch format yet; export with "
        "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
    )
tocoo()

Convert to COO (may allocate).

Source code in btorch/sparse/base.py
def tocoo(self) -> "COO":
    """Convert to COO (may allocate)."""
    raise NotImplementedError
tocsc(return_map=False)

Convert to CSC (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
    """Convert to CSC (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
tocsr(return_map=False)

Convert to CSR (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
    """Convert to CSR (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
with_values(values)

Return an array with the same pattern and new values.

values is [*batch, nnz, *dense]; a different leading batch shape creates a shared-pattern batch.

Source code in btorch/sparse/base.py
def with_values(self, values: Tensor) -> "Sparse":
    """Return an array with the same pattern and new values.

    ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
    shape creates a shared-pattern batch.
    """
    raise NotImplementedError

Functions:

_parse(subscripts, n_operands)

Split subscripts into one term per operand and the output term.

Source code in btorch/sparse/einsum.py
def _parse(subscripts: str, n_operands: int) -> tuple[list[str], str]:
    """Split ``subscripts`` into one term per operand and the output term."""
    if not isinstance(subscripts, str):
        raise TypeError(
            "sparse.einsum needs the subscripts as a string, e.g. "
            f"einsum('ij,j->i', A, x); got {type(subscripts).__name__}."
        )
    spec = subscripts.replace(" ", "")
    if "." in spec:
        raise NotImplementedError(
            f"sparse.einsum does not support an ellipsis ('...') in {subscripts!r}; "
            "name every dimension explicitly."
        )
    lhs, arrow, out = spec.partition("->")
    if "->" in out:
        raise ValueError(f"{subscripts!r} contains more than one '->'.")
    terms = lhs.split(",")
    for term in [*terms, out]:
        if not all(c in string.ascii_letters for c in term):
            raise ValueError(
                f"Subscripts must be ASCII letters, got {term!r} in {subscripts!r}."
            )
    if len(terms) != n_operands:
        raise ValueError(
            f"{subscripts!r} has {len(terms)} input term(s) but {n_operands} "
            "operand(s) were given."
        )
    seen = "".join(terms)
    if not arrow:
        # Implicit mode (NumPy / PyTorch): every letter that appears exactly
        # once, in alphabetical order with upper case before lower case.
        return terms, "".join(sorted(c for c in set(seen) if seen.count(c) == 1))
    if len(set(out)) != len(out):
        raise ValueError(f"An output subscript appears more than once in {out!r}.")
    missing = sorted(set(out) - set(seen))
    if missing:
        raise ValueError(
            f"Output subscript(s) {missing} of {subscripts!r} do not appear in "
            "any input term."
        )
    return terms, out

_ravel(indices, sizes)

Row-major linear index of indices [len(sizes), E].

Source code in btorch/sparse/coo.py
def _ravel(indices: Tensor, sizes: tuple[int, ...]) -> Tensor:
    """Row-major linear index of ``indices [len(sizes), E]``."""
    if math.prod(max(int(s), 1) for s in sizes) >= 2**63:
        raise OverflowError(
            f"The indexed shape {tuple(sizes)} has more than 2**63 positions; "
            "its entries cannot be linearised into int64 keys."
        )
    key = torch.zeros(indices.shape[1], dtype=torch.long, device=indices.device)
    for i, size in enumerate(sizes):
        key = key * size + indices[i]
    return key

einsum(subscripts, A, *operands)

Contract one sparse array with dense tensors (experimental).

The result equals torch.einsum(subscripts, A.to_dense(), *operands) without ever building A.to_dense():

.. math:: Y_{\text{out}} = \sum_{\text{letters not in out}} A_{\text{sub}0} \prod_k X^{(k)}}_k

Scope. Exactly one sparse operand, which comes first; every other operand is a dense tensor (there may be none, e.g. "ii->i"); the output is always dense. Sparse times sparse and sparse outputs are not implemented. This function is experimental and may change.

Every subscript letter of A names one logical axis of A.shape == (*batch, *sparse, *dense). A letter is indexed if its axis is stored as coordinates in A.tocoo().indices() (the sparse dimensions and the batch dimensions of a different-pattern batch), and non-indexed if it is an axis of values (the batch dimensions of a shared-pattern batch and the dense dimensions).

Algorithm (E is the number of stored entries):

  1. Diagonal filter: if an indexed letter is repeated in A's subscript ("ii->i"), keep only the entries whose coordinates agree.
  2. Gather: index every dense operand with the coordinates of the indexed letters it shares with A; those axes collapse into one entry axis, giving [E, *other axes]. Operands sharing no indexed letter are left alone.
  3. Contract: one torch.einsum over the values, the gathered operands and the entry axis, producing per-entry contributions [E, *non-indexed output letters]. Indexed letters missing from the output are summed here together with the entry axis.
  4. Scatter: index_add the contributions at the linearised coordinates of the indexed letters that survive in the output, then reshape and permute to the requested order. Duplicate entries add up. If no indexed letter survives, step 3 already produces the result.

Cost. Time and memory are proportional to E and never to prod(sparse_shape), except for the dense output itself. The peak temporaries are the gathered operands and the per-entry contributions, each O(E * prod(sizes of the non-indexed letters it carries)); torch.einsum may hold pairwise intermediates of the same form, bounded by E times the sizes of all non-indexed letters of the expression.

Parameters:

Name Type Description Default
subscripts str

Einsum expression with single-letter subscripts, with or without -> (implicit output: the letters that appear once, sorted). An ellipsis is not supported.

required
A Sparse

Sparse array in any format; its term must have A.ndim letters.

required
*operands Tensor

Dense tensors, one per remaining term.

()

Returns:

Type Description
Tensor

Dense tensor with one axis per output letter. Its dtype is the

Tensor

promotion of all operand dtypes (torch.einsum would raise on

Tensor

mixed dtypes), so integer and bool operands may be passed directly.

Raises:

Type Description
NotImplementedError

For an ellipsis, a second sparse operand, or a letter repeated in A on both an indexed and a non-indexed axis.

ValueError

For malformed subscripts, a term whose length differs from the operand's number of dimensions, or a letter used with two different sizes. Size-1 axes do not broadcast.

TypeError

If A is not a sparse array.

Examples:

>>> import torch
>>> from btorch import sparse
>>> from btorch.sparse.einsum import einsum
>>> A = sparse.coo(torch.tensor([[0, 1], [2, 0]]),
...                torch.tensor([3.0, 5.0]), shape=(2, 3))
>>> einsum("mn,bn->bm", A, torch.tensor([[1.0, 0.0, 2.0]]))
tensor([[6., 5.]])
>>> einsum("mn->", A)
tensor(8.)

A batch of third-order sparse arrays with a vector per entry, contracted with one vector per batch member:

>>> Y = einsum("bijkd,bk->bijd", A5, x)
Source code in btorch/sparse/einsum.py
def einsum(subscripts: str, A: Sparse, *operands: Tensor) -> Tensor:
    """Contract one sparse array with dense tensors (experimental).

    The result equals ``torch.einsum(subscripts, A.to_dense(), *operands)``
    without ever building ``A.to_dense()``:

    .. math::
        Y_{\\text{out}} = \\sum_{\\text{letters not in out}}
            A_{\\text{sub}_0} \\prod_k X^{(k)}_{\\text{sub}_k}

    **Scope.** Exactly one sparse operand, which comes first; every other
    operand is a dense tensor (there may be none, e.g. ``"ii->i"``); the
    output is always dense. Sparse times sparse and sparse outputs are not
    implemented. This function is experimental and may change.

    Every subscript letter of ``A`` names one logical axis of
    ``A.shape == (*batch, *sparse, *dense)``. A letter is *indexed* if its
    axis is stored as coordinates in ``A.tocoo().indices()`` (the sparse
    dimensions and the batch dimensions of a different-pattern batch), and
    *non-indexed* if it is an axis of ``values`` (the batch dimensions of a
    shared-pattern batch and the dense dimensions).

    **Algorithm** (``E`` is the number of stored entries):

    1. *Diagonal filter*: if an indexed letter is repeated in ``A``'s
       subscript (``"ii->i"``), keep only the entries whose coordinates agree.
    2. *Gather*: index every dense operand with the coordinates of the indexed
       letters it shares with ``A``; those axes collapse into one entry axis,
       giving ``[E, *other axes]``. Operands sharing no indexed letter are
       left alone.
    3. *Contract*: one ``torch.einsum`` over the values, the gathered operands
       and the entry axis, producing per-entry contributions
       ``[E, *non-indexed output letters]``. Indexed letters missing from the
       output are summed here together with the entry axis.
    4. *Scatter*: ``index_add`` the contributions at the linearised
       coordinates of the indexed letters that survive in the output, then
       reshape and permute to the requested order. Duplicate entries add up.
       If no indexed letter survives, step 3 already produces the result.

    **Cost.** Time and memory are proportional to ``E`` and never to
    ``prod(sparse_shape)``, except for the dense output itself. The peak
    temporaries are the gathered operands and the per-entry contributions,
    each ``O(E * prod(sizes of the non-indexed letters it carries))``;
    ``torch.einsum`` may hold pairwise intermediates of the same form, bounded
    by ``E`` times the sizes of all non-indexed letters of the expression.

    Args:
        subscripts: Einsum expression with single-letter subscripts, with or
            without ``->`` (implicit output: the letters that appear once,
            sorted). An ellipsis is not supported.
        A: Sparse array in any format; its term must have ``A.ndim`` letters.
        *operands: Dense tensors, one per remaining term.

    Returns:
        Dense tensor with one axis per output letter. Its dtype is the
        promotion of all operand dtypes (``torch.einsum`` would raise on
        mixed dtypes), so integer and bool operands may be passed directly.

    Raises:
        NotImplementedError: For an ellipsis, a second sparse operand, or a
            letter repeated in ``A`` on both an indexed and a non-indexed axis.
        ValueError: For malformed subscripts, a term whose length differs
            from the operand's number of dimensions, or a letter used with
            two different sizes. Size-1 axes do **not** broadcast.
        TypeError: If ``A`` is not a sparse array.

    Examples:
        >>> import torch
        >>> from btorch import sparse
        >>> from btorch.sparse.einsum import einsum
        >>> A = sparse.coo(torch.tensor([[0, 1], [2, 0]]),
        ...                torch.tensor([3.0, 5.0]), shape=(2, 3))
        >>> einsum("mn,bn->bm", A, torch.tensor([[1.0, 0.0, 2.0]]))
        tensor([[6., 5.]])
        >>> einsum("mn->", A)
        tensor(8.)

        A batch of third-order sparse arrays with a vector per entry,
        contracted with one vector per batch member:

        >>> Y = einsum("bijkd,bk->bijd", A5, x)        # doctest: +SKIP
    """
    if not isinstance(A, Sparse):
        raise TypeError(
            "The first operand of sparse.einsum must be a sparse array, got "
            f"{type(A).__name__}."
        )
    for op in operands:
        if isinstance(op, Sparse):
            raise NotImplementedError(
                "sparse.einsum supports exactly one sparse operand (the first); "
                "sparse x sparse contraction is not implemented. Densify the "
                "other operands with to_dense() if they are small."
            )
        if not isinstance(op, Tensor):
            raise TypeError(f"Operands must be tensors, got {type(op).__name__}.")
    terms, out = _parse(subscripts, 1 + len(operands))
    sub_a, sub_ops = terms[0], terms[1:]

    coo = A.tocoo()
    indices, values = coo._indices, coo._values
    n_vb, n_index = coo._value_batch_dim, indices.shape[0]

    # ---- sizes: every occurrence of a letter must have the same size.
    if len(sub_a) != A.ndim:
        raise ValueError(
            f"The sparse term {sub_a!r} has {len(sub_a)} letter(s) but the "
            f"array has {A.ndim} dimensions, shape {A.shape} = (*batch "
            f"{A.batch_shape}, *sparse {A.sparse_shape}, *dense {A.dense_shape})."
        )
    size: dict[str, int] = {}

    def register(term: str, shape, what: str) -> None:
        for letter, n in zip(term, shape):
            if size.setdefault(letter, int(n)) != int(n):
                raise ValueError(
                    f"Subscript {letter!r} has size {int(n)} in {what} but "
                    f"size {size[letter]} elsewhere in {subscripts!r} "
                    "(size-1 axes do not broadcast)."
                )

    register(sub_a, A.shape, f"the sparse operand (shape {A.shape})")
    for k, (term, op) in enumerate(zip(sub_ops, operands), start=1):
        if len(term) != op.ndim:
            raise ValueError(
                f"Term {term!r} has {len(term)} letter(s) but operand {k} has "
                f"shape {tuple(op.shape)}."
            )
        register(term, op.shape, f"operand {k} (shape {tuple(op.shape)})")

    # ---- classify the letters of A by where their axis is stored.
    idx_letters = sub_a[n_vb : n_vb + n_index]
    val_letters = sub_a[:n_vb] + sub_a[n_vb + n_index :]
    mixed = sorted(set(idx_letters) & set(val_letters))
    if mixed:
        raise NotImplementedError(
            f"Subscript(s) {mixed} of {sub_a!r} repeat across a coordinate "
            "(sparse) axis and a batch/dense value axis of the sparse operand; "
            "this diagonal is not implemented."
        )

    # ---- 1. diagonal filter over repeated indexed letters.
    rows: dict[str, Tensor] = {}
    mask = None
    for r, letter in enumerate(idx_letters):
        if letter in rows:
            agree = indices[r] == rows[letter]
            mask = agree if mask is None else mask & agree
        else:
            rows[letter] = indices[r]
    if mask is not None:
        keep = mask.nonzero().squeeze(1)
        rows = {letter: row[keep] for letter, row in rows.items()}
        values = values.index_select(n_vb, keep)

    # ---- dtype: promote like a product of all operands would.
    dtype = functools.reduce(
        torch.promote_types, [op.dtype for op in operands], values.dtype
    )
    values = values.to(dtype)

    # ---- 2. gather the dense operands along the indexed letters.
    used = set("".join(terms)) | set(out)
    free = [c for c in string.ascii_letters if c not in used]
    if not free:
        raise NotImplementedError("sparse.einsum needs one unused subscript letter.")
    entry = free[0]
    inner_terms = [sub_a[:n_vb] + entry + sub_a[n_vb + n_index :]]
    inner_ops = [values]
    for term, op in zip(sub_ops, operands):
        op = op.to(dtype)
        hit = [d for d, letter in enumerate(term) if letter in rows]
        if hit:
            rest = [d for d in range(op.ndim) if d not in hit]
            # Indexed axes first, so the advanced index yields [E, *rest].
            op = op.permute(*hit, *rest)[tuple(rows[term[d]] for d in hit)]
            term = entry + "".join(term[d] for d in rest)
        inner_terms.append(term)
        inner_ops.append(op)

    # ---- 3. contract; 4. scatter into the surviving indexed letters.
    kept = [c for c in out if c in rows]
    if not kept:
        return torch.einsum(",".join(inner_terms) + "->" + out, *inner_ops)
    rest_out = [c for c in out if c not in rows]
    contrib = torch.einsum(
        ",".join(inner_terms) + "->" + entry + "".join(rest_out), *inner_ops
    )
    kept_sizes = tuple(size[c] for c in kept)
    key = _ravel(torch.stack([rows[c] for c in kept]), kept_sizes)
    flat = contrib.new_zeros(math.prod(kept_sizes), *contrib.shape[1:])
    result = flat.index_add(0, key, contrib).reshape(*kept_sizes, *contrib.shape[1:])
    current = kept + rest_out
    return result.permute(*[current.index(c) for c in out])

btorch.sparse.operator

Linear operators that are not explicit sparse arrays.

A :class:LinearOperator is anything that maps x [..., N] to y [..., M] linearly. A stored sparse array (:class:~btorch.sparse.Sparse) is one way to do that; this module holds the other ones:

  • :class:StructuredOperator: closed-form products with no stored matrix (:class:ConstantOperator, :class:DiagonalOperator, :class:LowRankOperator).
  • :class:ImplicitOperator: user callables; the matrix is never built unless the user provides an edge enumeration and asks for it.
  • :class:CompositeOperator: lazy sums, products, scalings and transposes of other operators (:class:SumOperator, :class:ProductOperator, :class:ScaledOperator, :class:TransposedOperator).

Procedural operators are deliberately not Sparse: they have no nnz, no format and no stored indices. What an operator can do is queried with :meth:LinearOperator.supports; asking for an unsupported capability raises NotImplementedError naming it.

Products follow the conventions of :func:btorch.sparse.matmul: for A.shape == (M, N), A @ x maps a length-N vector to a length-M vector, and A.matvec(x) applies A along the last axis of x.

A Sparse is accepted wherever an operator is expected (as a part of a sum or a product, on either side of @ and +).

Examples:

>>> import torch
>>> from btorch.sparse.operator import ConstantOperator, DiagonalOperator
>>> A = ConstantOperator((2, 3), 0.5) @ DiagonalOperator(torch.ones(3))
>>> A @ torch.tensor([1.0, 2.0, 3.0])
tensor([3., 3.])

Attributes

CAPABILITIES = frozenset({'matvec', 'matmat', 'rmatvec', 'enumerate_edges', 'materialize_sparse'}) module-attribute

Optional capabilities of a linear operator.

  • "matvec": A.matvec(x) and A @ x.
  • "matmat": A @ X with a matrix right-hand side.
  • "rmatvec": the transpose apply, A.rmatvec(x), x @ A and A.T.
  • "enumerate_edges": A.enumerate_edges() lists (rows, cols, values).
  • "materialize_sparse": A.materialize() / tocoo() / tocsr().

Edges = tuple[Tensor, Tensor, Tensor] module-attribute

_ALL = CAPABILITIES module-attribute

_APPLY = frozenset({'matvec', 'matmat', 'rmatvec'}) module-attribute

__all__ = ['CAPABILITIES', 'CompositeOperator', 'ConstantOperator', 'DiagonalOperator', 'ImplicitOperator', 'LinearOperator', 'LowRankOperator', 'ProductOperator', 'ScaledOperator', 'StructuredOperator', 'SumOperator', 'TransposedOperator', 'is_linear_operator'] module-attribute

Classes

CompositeOperator

Bases: LinearOperator

Operator built lazily from other operators and sparse matrices.

The concrete composites are :class:SumOperator, :class:ProductOperator, :class:ScaledOperator and :class:TransposedOperator; they are normally created with +, @, * and .T. A composite supports a capability only if all of its parts do (a Sparse part supports everything).

Attributes:

Name Type Description
parts tuple[Any, ...]

The operands, in order.

Source code in btorch/sparse/operator.py
class CompositeOperator(LinearOperator):
    """Operator built lazily from other operators and sparse matrices.

    The concrete composites are :class:`SumOperator`,
    :class:`ProductOperator`, :class:`ScaledOperator` and
    :class:`TransposedOperator`; they are normally created with ``+``, ``@``,
    ``*`` and ``.T``. A composite supports a capability only if all of its
    parts do (a ``Sparse`` part supports everything).

    Attributes:
        parts: The operands, in order.
    """

    parts: tuple[Any, ...]

    def _set_parts(self, parts: Sequence[Any]) -> None:
        self.parts = tuple(_as_part(p) for p in parts)
        if not self.parts:
            raise ValueError(f"{type(self).__name__} needs at least one operand.")
        self.dtype = _composite_dtype(self.parts)
        self.device = _composite_device(self.parts)

    def _common(self, allowed: frozenset[str] = _ALL) -> frozenset[str]:
        out = allowed
        for part in self.parts:
            out = out & _capabilities_of(part)
        return out

    def __repr__(self) -> str:
        inner = ", ".join(repr(p) for p in self.parts)
        return f"{type(self).__name__}(shape={self.shape}, parts=[{inner}])"

ConstantOperator

Bases: StructuredOperator

All-to-all operator with one shared weight: A[m, n] = value.

.. math:: y_{\ldots m} = \text{value} \cdot \sum_n x_{\ldots n}

The product costs O(M + N) instead of O(M N).

Parameters:

Name Type Description Default
shape tuple[int, int]

(M, N).

required
value Tensor | float

Scalar weight: a Python number or a 0-dim tensor (for example an nn.Parameter; gradients flow to it).

1.0
dtype dtype | None

Dtype used when value is a Python number.

None
device device | str | None

Device used when value is a Python number.

None

Examples:

>>> A = ConstantOperator((2, 3), 2.0)
>>> A @ torch.tensor([1.0, 2.0, 3.0])
tensor([12., 12.])
Source code in btorch/sparse/operator.py
class ConstantOperator(StructuredOperator):
    """All-to-all operator with one shared weight: ``A[m, n] = value``.

    .. math::
        y_{\\ldots m} = \\text{value} \\cdot \\sum_n x_{\\ldots n}

    The product costs ``O(M + N)`` instead of ``O(M N)``.

    Args:
        shape: ``(M, N)``.
        value: Scalar weight: a Python number or a 0-dim tensor (for example
            an ``nn.Parameter``; gradients flow to it).
        dtype: Dtype used when ``value`` is a Python number.
        device: Device used when ``value`` is a Python number.

    Examples:
        >>> A = ConstantOperator((2, 3), 2.0)
        >>> A @ torch.tensor([1.0, 2.0, 3.0])
        tensor([12., 12.])
    """

    def __init__(
        self,
        shape: tuple[int, int],
        value: Tensor | float = 1.0,
        *,
        dtype: torch.dtype | None = None,
        device: torch.device | str | None = None,
    ):
        self._shape = _check_shape(shape)
        if isinstance(value, Tensor):
            if value.ndim != 0:
                raise ValueError(
                    "ConstantOperator needs a scalar value, got shape "
                    f"{tuple(value.shape)}."
                )
            self.dtype, self.device = value.dtype, value.device
        else:
            self.dtype = dtype
            self.device = torch.device(device) if device is not None else None
        self.value = value

    def _matvec(self, x: Tensor) -> Tensor:
        total = x.sum(-1, keepdim=True) * self.value
        return total.expand(*x.shape[:-1], self._shape[0])

    def _rmatvec(self, x: Tensor) -> Tensor:
        total = x.sum(-1, keepdim=True) * self.value
        return total.expand(*x.shape[:-1], self._shape[1])

    def _value_tensor(self) -> Tensor:
        if isinstance(self.value, Tensor):
            return self.value
        return torch.tensor(self.value, dtype=self.dtype, device=self.device)

    def _enumerate_edges(self) -> Edges:
        m, n = self._shape
        value = self._value_tensor()
        rows = torch.arange(m, device=value.device).repeat_interleave(n)
        cols = torch.arange(n, device=value.device).repeat(m)
        return rows, cols, value.expand(m * n)

    def to_dense(self, *, dtype=None, device=None) -> Tensor:
        return self._value_tensor().to(dtype=dtype, device=device).expand(self._shape)

DiagonalOperator

Bases: StructuredOperator

One-to-one operator: A = diag(d), y = d * x.

Parameters:

Name Type Description Default
diag Tensor

[N] diagonal (may be an nn.Parameter).

required

Examples:

>>> DiagonalOperator(torch.tensor([1.0, 2.0])) @ torch.tensor([3.0, 4.0])
tensor([3., 8.])
Source code in btorch/sparse/operator.py
class DiagonalOperator(StructuredOperator):
    """One-to-one operator: ``A = diag(d)``, ``y = d * x``.

    Args:
        diag: ``[N]`` diagonal (may be an ``nn.Parameter``).

    Examples:
        >>> DiagonalOperator(torch.tensor([1.0, 2.0])) @ torch.tensor([3.0, 4.0])
        tensor([3., 8.])
    """

    def __init__(self, diag: Tensor):
        if not isinstance(diag, Tensor) or diag.ndim != 1:
            raise ValueError("DiagonalOperator needs a 1-D tensor.")
        self.diag = diag
        self._shape = (diag.shape[0], diag.shape[0])
        self.dtype, self.device = diag.dtype, diag.device

    def _matvec(self, x: Tensor) -> Tensor:
        return x * self.diag

    _rmatvec = _matvec

    def _enumerate_edges(self) -> Edges:
        index = torch.arange(self._shape[0], device=self.diag.device)
        return index, index, self.diag

    def to_dense(self, *, dtype=None, device=None) -> Tensor:
        return torch.diag(self.diag).to(dtype=dtype, device=device)

ImplicitOperator

Bases: LinearOperator

Operator defined by user callables; nothing is stored or materialised.

Only matvec is required. Every other capability exists exactly when its callable was given, so an apply-only operator refuses .T, x @ A and tocsr() with a clear error, while an enumerable procedural operator can be materialised on request.

The callables are stored as given and called directly: the operator is differentiable when they are, and works under torch.compile when they do.

Parameters:

Name Type Description Default
shape tuple[int, int]

(M, N).

required
matvec Callable[[Tensor], Tensor]

x [..., N] -> y [..., M], applied along the last axis.

required
rmatvec Callable[[Tensor], Tensor] | None

Optional transpose apply x [..., M] -> y [..., N].

None
enumerate_edges Callable[[], Edges] | None

Optional callable without arguments returning (rows [E], cols [E], values [E]). Enables :meth:~LinearOperator.materialize, tocoo() and tocsr().

None
dtype dtype | None

Optional dtype, used by :meth:~LinearOperator.to_dense.

None
device device | str | None

Optional device, used by :meth:~LinearOperator.to_dense.

None
matmat Callable[[Tensor], Tensor] | None

Optional X [..., N, K] -> [..., M, K]. Defaults to matvec applied to the columns.

None

Examples:

A circular shift, never stored as a matrix:

>>> shift = ImplicitOperator(
...     (4, 4),
...     matvec=lambda x: x.roll(1, -1),
...     rmatvec=lambda x: x.roll(-1, -1),
... )
>>> shift @ torch.tensor([1.0, 2.0, 3.0, 4.0])
tensor([4., 1., 2., 3.])
Source code in btorch/sparse/operator.py
class ImplicitOperator(LinearOperator):
    """Operator defined by user callables; nothing is stored or materialised.

    Only ``matvec`` is required. Every other capability exists exactly when
    its callable was given, so an apply-only operator refuses ``.T``,
    ``x @ A`` and ``tocsr()`` with a clear error, while an enumerable
    procedural operator can be materialised on request.

    The callables are stored as given and called directly: the operator is
    differentiable when they are, and works under ``torch.compile`` when they
    do.

    Args:
        shape: ``(M, N)``.
        matvec: ``x [..., N] -> y [..., M]``, applied along the last axis.
        rmatvec: Optional transpose apply ``x [..., M] -> y [..., N]``.
        enumerate_edges: Optional callable without arguments returning
            ``(rows [E], cols [E], values [E])``. Enables
            :meth:`~LinearOperator.materialize`, ``tocoo()`` and ``tocsr()``.
        dtype: Optional dtype, used by :meth:`~LinearOperator.to_dense`.
        device: Optional device, used by :meth:`~LinearOperator.to_dense`.
        matmat: Optional ``X [..., N, K] -> [..., M, K]``. Defaults to
            ``matvec`` applied to the columns.

    Examples:
        A circular shift, never stored as a matrix:

        >>> shift = ImplicitOperator(
        ...     (4, 4),
        ...     matvec=lambda x: x.roll(1, -1),
        ...     rmatvec=lambda x: x.roll(-1, -1),
        ... )
        >>> shift @ torch.tensor([1.0, 2.0, 3.0, 4.0])
        tensor([4., 1., 2., 3.])
    """

    def __init__(
        self,
        shape: tuple[int, int],
        matvec: Callable[[Tensor], Tensor],
        rmatvec: Callable[[Tensor], Tensor] | None = None,
        enumerate_edges: Callable[[], Edges] | None = None,
        dtype: torch.dtype | None = None,
        device: torch.device | str | None = None,
        *,
        matmat: Callable[[Tensor], Tensor] | None = None,
    ):
        if not callable(matvec):
            raise TypeError("ImplicitOperator needs a callable matvec.")
        self._shape = _check_shape(shape)
        self._matvec_fn = matvec
        self._rmatvec_fn = rmatvec
        self._matmat_fn = matmat
        self._edges_fn = enumerate_edges
        self.dtype = dtype
        self.device = torch.device(device) if device is not None else None
        capabilities = {"matvec", "matmat"}
        if rmatvec is not None:
            capabilities.add("rmatvec")
        if enumerate_edges is not None:
            capabilities |= {"enumerate_edges", "materialize_sparse"}
        self._capabilities = frozenset(capabilities)

    def _matvec(self, x: Tensor) -> Tensor:
        return self._matvec_fn(x)

    def _rmatvec(self, x: Tensor) -> Tensor:
        return self._rmatvec_fn(x)

    def _matmat(self, x: Tensor) -> Tensor:
        if self._matmat_fn is not None:
            return self._matmat_fn(x)
        return self._matvec_fn(x.mT).mT

    def _enumerate_edges(self) -> Edges:
        rows, cols, values = self._edges_fn()
        return rows, cols, values

LinearOperator

Base class of everything that acts as a matrix of shape (M, N).

Subclasses implement the private hooks _matvec / _rmatvec (and optionally _matmat / _enumerate_edges) and list what they provide in _capabilities. The public methods validate shapes and capabilities and are shared by all operators.

Operators are plain Python objects holding tensors, like :class:~btorch.sparse.Sparse; they are not nn.Module. A learnable tensor used by an operator must be registered on the owning module, which passes it to the operator (see the examples of the concrete classes).

Operator algebra is lazy and never builds a matrix:

  • A + B, A - B: :class:SumOperator.
  • A @ B with another operator or a Sparse: :class:ProductOperator.
  • alpha * A, A * alpha, A / alpha, -A: :class:ScaledOperator.
  • A.T: :class:TransposedOperator.

The class is an ABC only so that explicit sparse arrays can be registered as virtual subclasses (LinearOperator.register(Sparse)); it has no abstract methods.

Source code in btorch/sparse/operator.py
class LinearOperator(metaclass=ABCMeta):
    """Base class of everything that acts as a matrix of shape ``(M, N)``.

    Subclasses implement the private hooks ``_matvec`` / ``_rmatvec`` (and
    optionally ``_matmat`` / ``_enumerate_edges``) and list what they provide
    in ``_capabilities``. The public methods validate shapes and capabilities
    and are shared by all operators.

    Operators are plain Python objects holding tensors, like
    :class:`~btorch.sparse.Sparse`; they are not ``nn.Module``. A learnable
    tensor used by an operator must be registered on the owning module, which
    passes it to the operator (see the examples of the concrete classes).

    Operator algebra is lazy and never builds a matrix:

    - ``A + B``, ``A - B``: :class:`SumOperator`.
    - ``A @ B`` with another operator or a ``Sparse``: :class:`ProductOperator`.
    - ``alpha * A``, ``A * alpha``, ``A / alpha``, ``-A``:
      :class:`ScaledOperator`.
    - ``A.T``: :class:`TransposedOperator`.

    The class is an ABC only so that explicit sparse arrays can be registered
    as virtual subclasses (``LinearOperator.register(Sparse)``); it has no
    abstract methods.
    """

    _capabilities: frozenset[str] = frozenset()
    _shape: tuple[int, int]
    dtype: torch.dtype | None = None
    device: torch.device | None = None

    # ----------------------------------------------------------------- shape
    @property
    def shape(self) -> tuple[int, int]:
        """``(M, N)``: the operator maps length-``N`` to length-``M``."""
        return self._shape

    @property
    def ndim(self) -> int:
        return 2

    # ---------------------------------------------------------- capabilities
    def supports(self, name: str) -> bool:
        """Whether the optional capability ``name`` is available.

        Args:
            name: One of :data:`CAPABILITIES`.

        Raises:
            ValueError: If ``name`` is not a known capability.
        """
        if name not in CAPABILITIES:
            raise ValueError(
                f"Unknown capability {name!r}; expected one of {sorted(CAPABILITIES)}."
            )
        return name in self._capabilities

    def _require(self, name: str) -> None:
        if name not in self._capabilities:
            raise NotImplementedError(
                f"{type(self).__name__} of shape {self.shape} does not support "
                f"the capability {name!r} (supported: "
                f"{sorted(self._capabilities)})."
            )

    # --------------------------------------------------------------- products
    def matvec(self, x: Tensor) -> Tensor:
        """Apply the operator along the last axis: ``[..., N] -> [..., M]``.

        .. math::
            y_{\\ldots m} = \\sum_n A_{m n}\\, x_{\\ldots n}

        All leading dimensions of ``x`` are independent samples.
        """
        self._require("matvec")
        if x.shape[-1] != self._shape[1]:
            raise ValueError(
                f"matvec: the last dimension of the input is {x.shape[-1]}, "
                f"expected {self._shape[1]} for an operator of shape {self.shape}."
            )
        return self._matvec(x)

    def rmatvec(self, x: Tensor) -> Tensor:
        """Apply the transpose along the last axis: ``[..., M] -> [..., N]``.

        Equals ``self.T.matvec(x)`` and, for 1-D ``x``, ``x @ self``.
        """
        self._require("rmatvec")
        if x.shape[-1] != self._shape[0]:
            raise ValueError(
                f"rmatvec: the last dimension of the input is {x.shape[-1]}, "
                f"expected {self._shape[0]} for an operator of shape {self.shape}."
            )
        return self._rmatvec(x)

    def matmat(self, x: Tensor) -> Tensor:
        """``A @ X`` for ``X [..., N, K]``, returning ``[..., M, K]``."""
        self._require("matmat")
        if x.ndim < 2 or x.shape[-2] != self._shape[1]:
            raise ValueError(
                f"matmat: the input needs shape [..., {self._shape[1]}, K] for "
                f"an operator of shape {self.shape}, got {tuple(x.shape)}."
            )
        return self._matmat(x)

    def _matvec(self, x: Tensor) -> Tensor:
        raise NotImplementedError

    def _rmatvec(self, x: Tensor) -> Tensor:
        raise NotImplementedError

    def _matmat(self, x: Tensor) -> Tensor:
        # Columns of X are vectors: move them to the last axis and back.
        return self.matvec(x.mT).mT

    def __matmul__(self, other):
        if isinstance(other, Tensor):
            if other.ndim == 0:
                raise ValueError("A @ x needs x with at least one dimension.")
            if other.ndim == 1:
                return self.matvec(other)
            return self.matmat(other)
        if is_linear_operator(other):
            return ProductOperator([self, other])
        return NotImplemented

    def __rmatmul__(self, other):
        if isinstance(other, Tensor):
            if other.ndim == 0:
                raise ValueError("x @ A needs x with at least one dimension.")
            # 1-D: x [M] -> [N]; matrix: X [..., K, M] -> [..., K, N]. In both
            # cases the transpose acts along the last axis.
            return self.rmatvec(other)
        if is_linear_operator(other):
            return ProductOperator([other, self])
        return NotImplemented

    # ---------------------------------------------------------- lazy algebra
    def __add__(self, other):
        if is_linear_operator(other):
            return SumOperator([self, other])
        return NotImplemented

    def __radd__(self, other):
        if is_linear_operator(other):
            return SumOperator([other, self])
        return NotImplemented

    def __sub__(self, other):
        if is_linear_operator(other):
            return SumOperator([self, ScaledOperator(other, -1.0)])
        return NotImplemented

    def __rsub__(self, other):
        if is_linear_operator(other):
            return SumOperator([other, ScaledOperator(self, -1.0)])
        return NotImplemented

    def __mul__(self, alpha):
        if _is_scalar(alpha):
            return ScaledOperator(self, alpha)
        return NotImplemented

    __rmul__ = __mul__

    def __truediv__(self, alpha):
        if _is_scalar(alpha):
            return ScaledOperator(self, 1.0 / alpha)
        return NotImplemented

    def __neg__(self):
        return ScaledOperator(self, -1.0)

    @property
    def T(self) -> "LinearOperator":
        """Lazy transpose; needs the ``"rmatvec"`` capability."""
        return TransposedOperator(self)

    def transpose(self) -> "LinearOperator":
        return self.T

    # -------------------------------------------------------- materialisation
    def enumerate_edges(self) -> Edges:
        """List the entries as ``(rows [E], cols [E], values [E])``.

        Entries may repeat; repeated coordinates are summed, as in
        :class:`~btorch.sparse.COO`. ``values`` keeps its autograd history.
        """
        self._require("enumerate_edges")
        return self._enumerate_edges()

    def _enumerate_edges(self) -> Edges:
        raise NotImplementedError

    def materialize(self, format: str | None = None):
        """Build an explicit :class:`~btorch.sparse.Sparse` with these entries.

        Args:
            format: Optional ``"coo"``, ``"csr"`` or ``"csc"``. Without it the
                result is format-agnostic.

        Raises:
            NotImplementedError: If the operator cannot list its entries
                (capability ``"materialize_sparse"``).
        """
        self._require("materialize_sparse")
        from . import from_edges

        rows, cols, values = self._enumerate_edges()
        out = from_edges(rows, cols, values, self.shape)
        if format is not None and out.format != format:
            out = getattr(out, f"to{format}")()
        return out

    def tocoo(self):
        """Materialise as COO (capability ``"materialize_sparse"``)."""
        return self.materialize("coo")

    def tocsr(self):
        """Materialise as CSR (capability ``"materialize_sparse"``)."""
        return self.materialize("csr")

    def tocsc(self):
        """Materialise as CSC (capability ``"materialize_sparse"``)."""
        return self.materialize("csc")

    def to_dense(
        self,
        *,
        dtype: torch.dtype | None = None,
        device: torch.device | str | None = None,
    ) -> Tensor:
        """Dense ``[M, N]`` matrix; an explicit request, never done implicitly.

        The default applies the operator to the identity (``N`` right-hand
        sides at once), so it only needs ``"matvec"`` and stays
        differentiable.

        Args:
            dtype: Dtype of the identity; defaults to the operator dtype if
                it has one.
            device: Device of the identity; defaults to the operator device.
        """
        eye = torch.eye(
            self._shape[1],
            dtype=dtype if dtype is not None else self.dtype,
            device=device if device is not None else self.device,
        )
        # Row n of matvec(eye) is A @ e_n, i.e. column n of A.
        return self.matvec(eye).mT

    def __repr__(self) -> str:
        return f"{type(self).__name__}(shape={self.shape})"
Attributes
T property

Lazy transpose; needs the "rmatvec" capability.

shape property

(M, N): the operator maps length-N to length-M.

Methods:
enumerate_edges()

List the entries as (rows [E], cols [E], values [E]).

Entries may repeat; repeated coordinates are summed, as in :class:~btorch.sparse.COO. values keeps its autograd history.

Source code in btorch/sparse/operator.py
def enumerate_edges(self) -> Edges:
    """List the entries as ``(rows [E], cols [E], values [E])``.

    Entries may repeat; repeated coordinates are summed, as in
    :class:`~btorch.sparse.COO`. ``values`` keeps its autograd history.
    """
    self._require("enumerate_edges")
    return self._enumerate_edges()
materialize(format=None)

Build an explicit :class:~btorch.sparse.Sparse with these entries.

Parameters:

Name Type Description Default
format str | None

Optional "coo", "csr" or "csc". Without it the result is format-agnostic.

None

Raises:

Type Description
NotImplementedError

If the operator cannot list its entries (capability "materialize_sparse").

Source code in btorch/sparse/operator.py
def materialize(self, format: str | None = None):
    """Build an explicit :class:`~btorch.sparse.Sparse` with these entries.

    Args:
        format: Optional ``"coo"``, ``"csr"`` or ``"csc"``. Without it the
            result is format-agnostic.

    Raises:
        NotImplementedError: If the operator cannot list its entries
            (capability ``"materialize_sparse"``).
    """
    self._require("materialize_sparse")
    from . import from_edges

    rows, cols, values = self._enumerate_edges()
    out = from_edges(rows, cols, values, self.shape)
    if format is not None and out.format != format:
        out = getattr(out, f"to{format}")()
    return out
matmat(x)

A @ X for X [..., N, K], returning [..., M, K].

Source code in btorch/sparse/operator.py
def matmat(self, x: Tensor) -> Tensor:
    """``A @ X`` for ``X [..., N, K]``, returning ``[..., M, K]``."""
    self._require("matmat")
    if x.ndim < 2 or x.shape[-2] != self._shape[1]:
        raise ValueError(
            f"matmat: the input needs shape [..., {self._shape[1]}, K] for "
            f"an operator of shape {self.shape}, got {tuple(x.shape)}."
        )
    return self._matmat(x)
matvec(x)

Apply the operator along the last axis: [..., N] -> [..., M].

.. math:: y_{\ldots m} = \sum_n A_{m n}\, x_{\ldots n}

All leading dimensions of x are independent samples.

Source code in btorch/sparse/operator.py
def matvec(self, x: Tensor) -> Tensor:
    """Apply the operator along the last axis: ``[..., N] -> [..., M]``.

    .. math::
        y_{\\ldots m} = \\sum_n A_{m n}\\, x_{\\ldots n}

    All leading dimensions of ``x`` are independent samples.
    """
    self._require("matvec")
    if x.shape[-1] != self._shape[1]:
        raise ValueError(
            f"matvec: the last dimension of the input is {x.shape[-1]}, "
            f"expected {self._shape[1]} for an operator of shape {self.shape}."
        )
    return self._matvec(x)
rmatvec(x)

Apply the transpose along the last axis: [..., M] -> [..., N].

Equals self.T.matvec(x) and, for 1-D x, x @ self.

Source code in btorch/sparse/operator.py
def rmatvec(self, x: Tensor) -> Tensor:
    """Apply the transpose along the last axis: ``[..., M] -> [..., N]``.

    Equals ``self.T.matvec(x)`` and, for 1-D ``x``, ``x @ self``.
    """
    self._require("rmatvec")
    if x.shape[-1] != self._shape[0]:
        raise ValueError(
            f"rmatvec: the last dimension of the input is {x.shape[-1]}, "
            f"expected {self._shape[0]} for an operator of shape {self.shape}."
        )
    return self._rmatvec(x)
supports(name)

Whether the optional capability name is available.

Parameters:

Name Type Description Default
name str

One of :data:CAPABILITIES.

required

Raises:

Type Description
ValueError

If name is not a known capability.

Source code in btorch/sparse/operator.py
def supports(self, name: str) -> bool:
    """Whether the optional capability ``name`` is available.

    Args:
        name: One of :data:`CAPABILITIES`.

    Raises:
        ValueError: If ``name`` is not a known capability.
    """
    if name not in CAPABILITIES:
        raise ValueError(
            f"Unknown capability {name!r}; expected one of {sorted(CAPABILITIES)}."
        )
    return name in self._capabilities
to_dense(*, dtype=None, device=None)

Dense [M, N] matrix; an explicit request, never done implicitly.

The default applies the operator to the identity (N right-hand sides at once), so it only needs "matvec" and stays differentiable.

Parameters:

Name Type Description Default
dtype dtype | None

Dtype of the identity; defaults to the operator dtype if it has one.

None
device device | str | None

Device of the identity; defaults to the operator device.

None
Source code in btorch/sparse/operator.py
def to_dense(
    self,
    *,
    dtype: torch.dtype | None = None,
    device: torch.device | str | None = None,
) -> Tensor:
    """Dense ``[M, N]`` matrix; an explicit request, never done implicitly.

    The default applies the operator to the identity (``N`` right-hand
    sides at once), so it only needs ``"matvec"`` and stays
    differentiable.

    Args:
        dtype: Dtype of the identity; defaults to the operator dtype if
            it has one.
        device: Device of the identity; defaults to the operator device.
    """
    eye = torch.eye(
        self._shape[1],
        dtype=dtype if dtype is not None else self.dtype,
        device=device if device is not None else self.device,
    )
    # Row n of matvec(eye) is A @ e_n, i.e. column n of A.
    return self.matvec(eye).mT
tocoo()

Materialise as COO (capability "materialize_sparse").

Source code in btorch/sparse/operator.py
def tocoo(self):
    """Materialise as COO (capability ``"materialize_sparse"``)."""
    return self.materialize("coo")
tocsc()

Materialise as CSC (capability "materialize_sparse").

Source code in btorch/sparse/operator.py
def tocsc(self):
    """Materialise as CSC (capability ``"materialize_sparse"``)."""
    return self.materialize("csc")
tocsr()

Materialise as CSR (capability "materialize_sparse").

Source code in btorch/sparse/operator.py
def tocsr(self):
    """Materialise as CSR (capability ``"materialize_sparse"``)."""
    return self.materialize("csr")

LowRankOperator

Bases: StructuredOperator

Low-rank operator A = U V^T applied as two thin products.

.. math:: y = U\,(V^\top x)

The product costs O((M + N) r). U V^T is dense, so listing its entries is not offered ("enumerate_edges" and "materialize_sparse" are unsupported); use :meth:to_dense for the explicit matrix.

Parameters:

Name Type Description Default
U Tensor

[M, r] left factor.

required
V Tensor

[N, r] right factor. Both may be nn.Parameter.

required
Source code in btorch/sparse/operator.py
class LowRankOperator(StructuredOperator):
    """Low-rank operator ``A = U V^T`` applied as two thin products.

    .. math::
        y = U\\,(V^\\top x)

    The product costs ``O((M + N) r)``. ``U V^T`` is dense, so listing its
    entries is not offered (``"enumerate_edges"`` and ``"materialize_sparse"``
    are unsupported); use :meth:`to_dense` for the explicit matrix.

    Args:
        U: ``[M, r]`` left factor.
        V: ``[N, r]`` right factor. Both may be ``nn.Parameter``.
    """

    _capabilities = _APPLY

    def __init__(self, U: Tensor, V: Tensor):
        if U.ndim != 2 or V.ndim != 2 or U.shape[1] != V.shape[1]:
            raise ValueError(
                "LowRankOperator needs U [M, r] and V [N, r] with the same "
                f"rank, got {tuple(U.shape)} and {tuple(V.shape)}."
            )
        self.U, self.V = U, V
        self._shape = (U.shape[0], V.shape[0])
        self.dtype, self.device = U.dtype, U.device

    @property
    def rank(self) -> int:
        return int(self.U.shape[1])

    def _matvec(self, x: Tensor) -> Tensor:
        return (x @ self.V) @ self.U.mT

    def _rmatvec(self, x: Tensor) -> Tensor:
        return (x @ self.U) @ self.V.mT

    def to_dense(self, *, dtype=None, device=None) -> Tensor:
        return (self.U @ self.V.mT).to(dtype=dtype, device=device)

ProductOperator

Bases: CompositeOperator

Lazy composition A_1 @ A_2 @ ... (the rightmost is applied first).

The product is never formed: matvec applies the parts right to left and rmatvec left to right. Its entries cannot be listed (that would be a sparse-sparse product), so "enumerate_edges" and "materialize_sparse" are unsupported.

Parameters:

Name Type Description Default
parts Sequence[Any]

Operators and/or sparse matrices with chained shapes (M, K_1), (K_1, K_2), ..., (K_j, N).

required
Source code in btorch/sparse/operator.py
class ProductOperator(CompositeOperator):
    """Lazy composition ``A_1 @ A_2 @ ...`` (the rightmost is applied first).

    The product is never formed: ``matvec`` applies the parts right to left
    and ``rmatvec`` left to right. Its entries cannot be listed (that would
    be a sparse-sparse product), so ``"enumerate_edges"`` and
    ``"materialize_sparse"`` are unsupported.

    Args:
        parts: Operators and/or sparse matrices with chained shapes
            ``(M, K_1), (K_1, K_2), ..., (K_j, N)``.
    """

    def __init__(self, parts: Sequence[Any]):
        flat: list[Any] = []
        for part in parts:
            flat.extend(part.parts if isinstance(part, ProductOperator) else [part])
        self._set_parts(flat)
        dtypes = {
            part_dtype
            for part in self.parts
            if (part_dtype := getattr(part, "dtype", None)) is not None
        }
        if len(dtypes) > 1:
            raise ValueError(
                "Product operators require every operand to use one dtype, got "
                f"{sorted(map(str, dtypes))}."
            )
        for left, right in zip(self.parts[:-1], self.parts[1:]):
            if left.shape[1] != right.shape[0]:
                raise ValueError(
                    "Cannot compose operators of shapes "
                    f"{tuple(left.shape)} and {tuple(right.shape)}: the inner "
                    "dimensions differ."
                )
        self._shape = (self.parts[0].shape[0], self.parts[-1].shape[1])
        self._capabilities = self._common(_APPLY)
        self._reversed = self.parts[::-1]

    def _matvec(self, x: Tensor) -> Tensor:
        for part in self._reversed:
            x = part.matvec(x)
        return x

    def _rmatvec(self, x: Tensor) -> Tensor:
        for part in self.parts:
            x = part.rmatvec(x)
        return x

ScaledOperator

Bases: CompositeOperator

Lazy scalar multiple alpha * A.

Parameters:

Name Type Description Default
operator Any

Operator or sparse matrix.

required
alpha Tensor | float

Python number or 0-dim tensor (may be an nn.Parameter).

required
Source code in btorch/sparse/operator.py
class ScaledOperator(CompositeOperator):
    """Lazy scalar multiple ``alpha * A``.

    Args:
        operator: Operator or sparse matrix.
        alpha: Python number or 0-dim tensor (may be an ``nn.Parameter``).
    """

    def __init__(self, operator: Any, alpha: Tensor | float):
        if not _is_scalar(alpha):
            raise TypeError("ScaledOperator needs a scalar factor.")
        self._set_parts([operator])
        self.alpha = alpha
        if isinstance(alpha, Tensor):
            if self.device is not None and alpha.device != self.device:
                raise ValueError(
                    "Scaled operators require the factor and operand on one "
                    f"device, got {alpha.device} and {self.device}."
                )
            if self.dtype is not None:
                self.dtype = torch.promote_types(self.dtype, alpha.dtype)
            else:
                self.dtype = alpha.dtype
            self.device = alpha.device if self.device is None else self.device
        elif self.dtype is not None:
            alpha_dtype = torch.tensor(alpha).dtype
            self.dtype = torch.promote_types(self.dtype, alpha_dtype)
        self._shape = tuple(operator.shape)
        self._capabilities = self._common()

    def _matvec(self, x: Tensor) -> Tensor:
        return self.parts[0].matvec(x) * self.alpha

    def _rmatvec(self, x: Tensor) -> Tensor:
        return self.parts[0].rmatvec(x) * self.alpha

    def _enumerate_edges(self) -> Edges:
        rows, cols, values = _edges_of(self.parts[0])
        return rows, cols, values * self.alpha

StructuredOperator

Bases: LinearOperator

Operator with a closed-form product and no stored matrix.

Structured operators support every apply capability and can list their entries on request (:meth:enumerate_edges / :meth:materialize), which is the only time memory proportional to the number of entries is used.

Source code in btorch/sparse/operator.py
class StructuredOperator(LinearOperator):
    """Operator with a closed-form product and no stored matrix.

    Structured operators support every apply capability and can list their
    entries on request (:meth:`enumerate_edges` / :meth:`materialize`), which
    is the only time memory proportional to the number of entries is used.
    """

    _capabilities = _ALL

SumOperator

Bases: CompositeOperator

Lazy sum A_1 + A_2 + ... of operators with the same shape.

Listing the entries concatenates the entries of the parts (coordinates present in several parts are stored several times and summed by every sparse operation), so no sparse addition is run.

Parameters:

Name Type Description Default
parts Sequence[Any]

Operators and/or sparse matrices of one shape.

required
Source code in btorch/sparse/operator.py
class SumOperator(CompositeOperator):
    """Lazy sum ``A_1 + A_2 + ...`` of operators with the same shape.

    Listing the entries concatenates the entries of the parts (coordinates
    present in several parts are stored several times and summed by every
    sparse operation), so no sparse addition is run.

    Args:
        parts: Operators and/or sparse matrices of one shape.
    """

    def __init__(self, parts: Sequence[Any]):
        flat: list[Any] = []
        for part in parts:
            # Flatten nested sums so a long chain stays one level deep.
            flat.extend(part.parts if isinstance(part, SumOperator) else [part])
        self._set_parts(flat)
        shape = tuple(self.parts[0].shape)
        for part in self.parts:
            if tuple(part.shape) != shape:
                raise ValueError(
                    "Cannot add operators of different shapes: "
                    f"{shape} and {tuple(part.shape)}."
                )
        self._shape = shape
        self._capabilities = self._common()

    def _matvec(self, x: Tensor) -> Tensor:
        out = self.parts[0].matvec(x)
        for part in self.parts[1:]:
            out = out + part.matvec(x)
        return out

    def _rmatvec(self, x: Tensor) -> Tensor:
        out = self.parts[0].rmatvec(x)
        for part in self.parts[1:]:
            out = out + part.rmatvec(x)
        return out

    def _enumerate_edges(self) -> Edges:
        edges = [_edges_of(part) for part in self.parts]
        dtype = edges[0][2].dtype
        for _, _, values in edges[1:]:
            dtype = torch.promote_types(dtype, values.dtype)
        return (
            torch.cat([e[0] for e in edges]),
            torch.cat([e[1] for e in edges]),
            torch.cat([e[2].to(dtype) for e in edges]),
        )

TransposedOperator

Bases: CompositeOperator

Lazy transpose A^T; swaps matvec and rmatvec.

Created by :attr:LinearOperator.T. Building it fails immediately (not on first use) if the operator has no "rmatvec" capability.

Parameters:

Name Type Description Default
operator Any

Operator or sparse matrix.

required
Source code in btorch/sparse/operator.py
class TransposedOperator(CompositeOperator):
    """Lazy transpose ``A^T``; swaps ``matvec`` and ``rmatvec``.

    Created by :attr:`LinearOperator.T`. Building it fails immediately (not on
    first use) if the operator has no ``"rmatvec"`` capability.

    Args:
        operator: Operator or sparse matrix.
    """

    def __init__(self, operator: Any):
        self._set_parts([operator])
        if not _supports(operator, "rmatvec"):
            operator._require("rmatvec")  # raises, naming the capability
        inner = _capabilities_of(operator)
        capabilities = {"matvec", "matmat"} | (
            inner & {"enumerate_edges", "materialize_sparse"}
        )
        if "matvec" in inner:
            capabilities.add("rmatvec")
        self._capabilities = frozenset(capabilities)
        self._shape = (operator.shape[1], operator.shape[0])

    def _matvec(self, x: Tensor) -> Tensor:
        return self.parts[0].rmatvec(x)

    def _rmatvec(self, x: Tensor) -> Tensor:
        return self.parts[0].matvec(x)

    def _enumerate_edges(self) -> Edges:
        rows, cols, values = _edges_of(self.parts[0])
        return cols, rows, values

    @property
    def T(self):
        return self.parts[0]

Functions:

_as_part(obj)

Validate an operand of a composite (operator or plain 2-D Sparse).

Source code in btorch/sparse/operator.py
def _as_part(obj: Any) -> Any:
    """Validate an operand of a composite (operator or plain 2-D
    ``Sparse``)."""
    if not is_linear_operator(obj):
        raise TypeError(
            f"Expected a LinearOperator or a sparse matrix, got {type(obj).__name__}."
        )
    if len(obj.shape) != 2:
        raise ValueError(
            "Only plain matrices can be combined into an operator, got shape "
            f"{tuple(obj.shape)} (batch or dense entry dimensions are not "
            "supported in composites)."
        )
    return obj

_capabilities_of(part)

Source code in btorch/sparse/operator.py
def _capabilities_of(part: Any) -> frozenset[str]:
    # Operators defined here carry ``_capabilities``. Anything else is an
    # explicit sparse array (duck-typed or registered as a virtual subclass),
    # which supports every capability.
    return getattr(part, "_capabilities", _ALL)

_check_shape(shape)

Source code in btorch/sparse/operator.py
def _check_shape(shape: Sequence[int]) -> tuple[int, int]:
    shape = tuple(int(s) for s in shape)
    if len(shape) != 2 or min(shape) < 0:
        raise ValueError(f"An operator shape is (M, N) with M, N >= 0, got {shape}.")
    return shape

_composite_device(parts)

Source code in btorch/sparse/operator.py
def _composite_device(parts: Sequence[Any]) -> torch.device | None:
    devices = {
        torch.device(part_device)
        for part in parts
        if (part_device := getattr(part, "device", None)) is not None
    }
    if len(devices) > 1:
        raise ValueError(
            "Composite operators require every operand on one device, got "
            f"{sorted(map(str, devices))}."
        )
    return next(iter(devices), None)

_composite_dtype(parts)

Source code in btorch/sparse/operator.py
def _composite_dtype(parts: Sequence[Any]) -> torch.dtype | None:
    dtype = _first(parts, "dtype")
    if dtype is None:
        return None
    for part in parts:
        part_dtype = getattr(part, "dtype", None)
        if part_dtype is not None:
            dtype = torch.promote_types(dtype, part_dtype)
    return dtype

_edges_of(part)

Source code in btorch/sparse/operator.py
def _edges_of(part: Any) -> Edges:
    if hasattr(part, "_capabilities"):
        return part.enumerate_edges()
    coo = part.tocoo()
    return coo.row, coo.col, coo.values()

_first(parts, name)

Source code in btorch/sparse/operator.py
def _first(parts: Sequence[Any], name: str):
    for part in parts:
        value = getattr(part, name, None)
        if value is not None:
            return value
    return None

_is_scalar(alpha)

Source code in btorch/sparse/operator.py
def _is_scalar(alpha: Any) -> bool:
    if isinstance(alpha, Tensor):
        return alpha.ndim == 0
    return isinstance(alpha, int | float | complex) and not isinstance(alpha, bool)

_supports(part, name)

Source code in btorch/sparse/operator.py
def _supports(part: Any, name: str) -> bool:
    return name in _capabilities_of(part)

is_linear_operator(obj)

Whether obj can be used as a linear operator here.

True for a :class:LinearOperator and for anything that looks like one (a 2-D shape with matvec and rmatvec), which is how a :class:~btorch.sparse.Sparse matrix is accepted without inheriting from :class:LinearOperator. Dense tensors are data, not operators.

Source code in btorch/sparse/operator.py
def is_linear_operator(obj: Any) -> bool:
    """Whether ``obj`` can be used as a linear operator here.

    True for a :class:`LinearOperator` and for anything that looks like one
    (a 2-D ``shape`` with ``matvec`` and ``rmatvec``), which is how a
    :class:`~btorch.sparse.Sparse` matrix is accepted without inheriting from
    :class:`LinearOperator`. Dense tensors are data, not operators.
    """
    if isinstance(obj, LinearOperator):
        return True
    if isinstance(obj, Tensor):
        return False
    return (
        callable(getattr(obj, "matvec", None))
        and callable(getattr(obj, "rmatvec", None))
        and hasattr(obj, "shape")
    )

btorch.sparse.ops

Products with sparse arrays.

The public operations are :func:matmul (A @ x), :func:matvec, :func:rmatvec and :func:stack. How a product is executed (which representation, which algorithm, which backend) is not part of this API.

The implementation here is the reference one: a gather along the input index of every stored entry followed by an index_add along its output index. It uses only differentiable dense tensor operations, so autograd, torch.compile and every device work, and its backward never builds a dense matrix.

Classes

COO

Bases: Sparse

Coordinate format: one index tuple and one value per stored entry.

COO supports any number of sparse dimensions. Entries may be unsorted and may contain duplicates; duplicates are summed by every operation, as in SciPy and PyTorch.

Two kinds of batch are supported and may be combined:

  • Shared pattern: values has leading batch dimensions, [*batch, nnz, *dense], and every batch member uses the same indices.
  • Different patterns: the first index rows are batch coordinates, so each batch member can have its own number of entries. Build these with :func:btorch.sparse.stack.

Parameters:

Name Type Description Default
indices Tensor

[n_index, nnz] integer coordinates. The rows are the batch coordinates (if any) followed by the sparse coordinates.

required
values Tensor

[*value_batch, nnz, *dense] stored values.

required
shape tuple[int, ...]

Logical shape (*batch, *sparse, *dense).

required
batch_dim int | None

Total number of batch dimensions. Defaults to the number of leading value dimensions (a shared pattern).

None
dense_dim int

Number of trailing dense dimensions of each entry.

0
properties Properties | None

Known structural properties of the given indices.

None
hints Hints | None

Performance expectations.

None
check bool

Validate index bounds.

True

Examples:

>>> import torch
>>> from btorch import sparse
>>> A = sparse.coo(torch.tensor([[0, 1], [2, 0]]),
...                torch.tensor([3.0, 5.0]), shape=(2, 3))
>>> A @ torch.tensor([1.0, 0.0, 2.0])
tensor([6., 5.])
Source code in btorch/sparse/coo.py
class COO(Sparse):
    """Coordinate format: one index tuple and one value per stored entry.

    COO supports any number of sparse dimensions. Entries may be unsorted and
    may contain duplicates; duplicates are summed by every operation, as in
    SciPy and PyTorch.

    Two kinds of batch are supported and may be combined:

    - *Shared pattern*: ``values`` has leading batch dimensions,
      ``[*batch, nnz, *dense]``, and every batch member uses the same indices.
    - *Different patterns*: the first index rows are batch coordinates, so each
      batch member can have its own number of entries. Build these with
      :func:`btorch.sparse.stack`.

    Args:
        indices: ``[n_index, nnz]`` integer coordinates. The rows are the
            batch coordinates (if any) followed by the sparse coordinates.
        values: ``[*value_batch, nnz, *dense]`` stored values.
        shape: Logical shape ``(*batch, *sparse, *dense)``.
        batch_dim: Total number of batch dimensions. Defaults to the number
            of leading value dimensions (a shared pattern).
        dense_dim: Number of trailing dense dimensions of each entry.
        properties: Known structural properties of the given indices.
        hints: Performance expectations.
        check: Validate index bounds.

    Examples:
        >>> import torch
        >>> from btorch import sparse
        >>> A = sparse.coo(torch.tensor([[0, 1], [2, 0]]),
        ...                torch.tensor([3.0, 5.0]), shape=(2, 3))
        >>> A @ torch.tensor([1.0, 0.0, 2.0])
        tensor([6., 5.])
    """

    format = "coo"

    def __init__(
        self,
        indices: Tensor,
        values: Tensor,
        shape: tuple[int, ...],
        *,
        batch_dim: int | None = None,
        dense_dim: int = 0,
        properties: Properties | None = None,
        hints: Hints | None = None,
        check: bool = True,
    ):
        values = _as_tensor(values)
        indices = _check_index("indices", _as_tensor(indices, device=values.device))
        shape = tuple(int(s) for s in shape)
        if indices.ndim != 2:
            raise ValueError(f"indices must be [n_index, nnz], got {indices.shape}.")
        n_index, nnz = indices.shape
        value_batch_dim = values.ndim - 1 - dense_dim
        if value_batch_dim < 0:
            raise ValueError(
                f"values with shape {tuple(values.shape)} cannot hold "
                f"{dense_dim} dense dimension(s) per entry."
            )
        if batch_dim is None:
            batch_dim = value_batch_dim
        index_batch_dim = batch_dim - value_batch_dim
        if index_batch_dim < 0:
            raise ValueError("batch_dim is smaller than the batch of `values`.")
        if len(shape) != value_batch_dim + n_index + dense_dim:
            raise ValueError(
                f"shape {shape} has {len(shape)} dimensions but indices/values "
                f"describe {value_batch_dim} value-batch + {n_index} indexed + "
                f"{dense_dim} dense."
            )
        if n_index - index_batch_dim < 1:
            raise ValueError("COO needs at least one sparse dimension.")
        if values.shape[value_batch_dim] != nnz:
            raise ValueError(
                f"values has {values.shape[value_batch_dim]} entries along its "
                f"entry axis but indices has {nnz}."
            )
        expected = (
            shape[:value_batch_dim] + (nnz,) + shape[len(shape) - dense_dim :]
            if dense_dim
            else shape[:value_batch_dim] + (nnz,)
        )
        if tuple(values.shape) != expected:
            raise ValueError(
                f"values has shape {tuple(values.shape)}, expected {expected}."
            )
        indexed = shape[value_batch_dim : value_batch_dim + n_index]
        if check and nnz > 0:
            lo = indices.amin(dim=1)
            hi = indices.amax(dim=1)
            for d, size in enumerate(indexed):
                if int(lo[d]) < 0 or int(hi[d]) >= size:
                    raise ValueError(
                        f"indices along indexed dimension {d} must be in "
                        f"[0, {size}), got range [{int(lo[d])}, {int(hi[d])}]."
                    )
        self._indices = indices
        self._values = values
        self._shape = shape
        self._batch_dim = batch_dim
        self._dense_dim = dense_dim
        self._value_batch_dim = value_batch_dim
        self.properties = properties or Properties()
        if self.properties.shared_pattern != bool(value_batch_dim):
            self.properties = self.properties.replace(
                shared_pattern=bool(value_batch_dim)
            )
        self.hints = hints or Hints()

    # ----------------------------------------------------------- accessors
    @property
    def nnz(self) -> int:
        return int(self._indices.shape[1])

    def indices(self) -> Tensor:
        """``[n_index, nnz]`` coordinates (PyTorch name)."""
        return self._indices

    def values(self) -> Tensor:
        """``[*value_batch, nnz, *dense]`` stored values (PyTorch name)."""
        return self._values

    @property
    def data(self) -> Tensor:
        """Stored values (SciPy name)."""
        return self._values

    @property
    def row(self) -> Tensor:
        """Row coordinate of each entry (two sparse dimensions only)."""
        self._require_matrix("row")
        return self._indices[-2]

    @property
    def col(self) -> Tensor:
        """Column coordinate of each entry (two sparse dimensions only)."""
        self._require_matrix("col")
        return self._indices[-1]

    def _require_matrix(self, what: str) -> None:
        if self.sparse_dim() != 2:
            raise ValueError(
                f"{what} needs exactly two sparse dimensions, this array has "
                f"{self.sparse_dim()}."
            )

    @property
    def _index_batch_dim(self) -> int:
        return self._batch_dim - self._value_batch_dim

    @property
    def _indexed_shape(self) -> tuple[int, ...]:
        """Sizes of the indexed (batch-coordinate + sparse) dimensions."""
        start = self._value_batch_dim
        return self._shape[start : start + self._indices.shape[0]]

    def _edge_index(self) -> tuple[Tensor | None, Tensor, Tensor]:
        """``(batch coordinates or None, row, col)`` for matrix products."""
        self._require_matrix("A matrix product")
        n_ib = self._index_batch_dim
        lead = self._indices[:n_ib] if n_ib else None
        return lead, self._indices[-2], self._indices[-1]

    # --------------------------------------------------------- construction
    def _like(self, indices: Tensor, values: Tensor, **changes) -> "COO":
        out = COO.__new__(COO)
        out.__dict__.update(self.__dict__)
        out._indices = indices
        out._values = values
        for key, value in changes.items():
            setattr(out, key, value)
        return out

    def with_values(self, values: Tensor) -> "COO":
        value_batch_dim = values.ndim - 1 - self._dense_dim
        tail = self._shape[self._value_batch_dim :]
        return COO(
            self._indices,
            values,
            tuple(values.shape[:value_batch_dim]) + tail,
            batch_dim=value_batch_dim + self._index_batch_dim,
            dense_dim=self._dense_dim,
            properties=self.properties,
            hints=self.hints,
            check=False,
        )

    def _map_tensors(self, index_fn, value_fn) -> "COO":
        return self._like(index_fn(self._indices), value_fn(self._values))

    # -------------------------------------------------------- canonical form
    def coalesce(self, return_map: bool = False) -> "COO" | tuple["COO", EdgeMap]:
        """Sort entries row-major and sum duplicates.

        Args:
            return_map: Also return the :class:`EdgeMap` from the old entries
                to the new ones, to move edge-aligned metadata consistently.

        Returns:
            The canonical COO, and the map if requested. The values of merged
            entries are summed, so gradients flow to every duplicate.
        """
        nnz = self.nnz
        if self.properties.canonical:
            edge_map = EdgeMap.identity(nnz, self._indices.device)
            return (self, edge_map) if return_map else self
        sizes = self._indexed_shape
        key = _ravel(self._indices, sizes)
        if self.properties.sorted:
            order = None
            sorted_key = key
        else:
            sorted_key, order = torch.sort(key, stable=True)
        unique_key, inverse = torch.unique_consecutive(sorted_key, return_inverse=True)
        if order is None:
            target = inverse
        else:
            target = torch.empty_like(inverse)
            target[order] = inverse
        edge_map = EdgeMap(target, int(unique_key.shape[0]))
        out = self._like(
            _unravel(unique_key, sizes),
            edge_map.sum(self._values, dim=self._value_batch_dim),
            properties=self.properties.replace(sorted=True, unique=True),
        )
        return (out, edge_map) if return_map else out

    def sum_duplicates(self) -> "COO":
        """SciPy-style alias of :meth:`coalesce` (returns a new array)."""
        return self.coalesce()

    # -------------------------------------------------------------- formats
    def tocoo(self) -> "COO":
        return self

    def _compressed(self, return_map: bool):
        """Canonical entries, their row pointers and the edge map."""
        self._require_matrix("CSR/CSC conversion")
        if self._index_batch_dim:
            raise NotImplementedError(
                "A batch of different sparsity patterns is stored as batched "
                "COO; compressed (CSR/CSC) storage for it is not implemented."
            )
        coo, edge_map = self.coalesce(return_map=True)
        n_rows = coo.sparse_shape[0]
        counts = torch.bincount(coo._indices[0], minlength=n_rows)
        pointer = torch.zeros(n_rows + 1, dtype=torch.long, device=counts.device)
        pointer[1:] = torch.cumsum(counts, 0)
        return coo, pointer, edge_map

    def tocsr(self, return_map: bool = False):
        """Convert to canonical CSR (sorted, duplicates summed).

        Args:
            return_map: Also return the :class:`EdgeMap` from the COO entries
                to the CSR entries.
        """
        from .csr import CSR

        coo, crow, edge_map = self._compressed(return_map)
        out = CSR(
            crow,
            coo._indices[1],
            coo._values,
            coo._shape,
            dense_dim=self._dense_dim,
            properties=coo.properties,
            hints=self.hints,
            check=False,
        )
        return (out, edge_map) if return_map else out

    def tocsc(self, return_map: bool = False):
        """Convert to canonical CSC (column-major, duplicates summed)."""
        result = self.transpose().tocsr(return_map)
        if return_map:
            return result[0].transpose(), result[1]
        return result.transpose()

    def transpose(self) -> "COO":
        self._require_matrix("transpose")
        idx = self._indices
        swapped = torch.cat([idx[:-2], idx[-1:], idx[-2:-1]])
        shape = list(self._shape)
        i = self._batch_dim
        shape[i], shape[i + 1] = shape[i + 1], shape[i]
        return self._like(
            swapped,
            self._values,
            _shape=tuple(shape),
            properties=self.properties.replace(sorted=False, triangular=None),
        )

    def to_dense(self) -> Tensor:
        n_vb = self._value_batch_dim
        sizes = self._indexed_shape
        dense = (
            self._shape[len(self._shape) - self._dense_dim :] if self._dense_dim else ()
        )
        key = _ravel(self._indices, sizes)
        flat = self._values.new_zeros(*self._shape[:n_vb], math.prod(sizes), *dense)
        flat = flat.index_add(n_vb, key, self._values)
        return flat.reshape(self._shape)
Attributes
col property

Column coordinate of each entry (two sparse dimensions only).

data property

Stored values (SciPy name).

row property

Row coordinate of each entry (two sparse dimensions only).

Methods:
coalesce(return_map=False)

Sort entries row-major and sum duplicates.

Parameters:

Name Type Description Default
return_map bool

Also return the :class:EdgeMap from the old entries to the new ones, to move edge-aligned metadata consistently.

False

Returns:

Type Description
'COO' | tuple['COO', EdgeMap]

The canonical COO, and the map if requested. The values of merged

'COO' | tuple['COO', EdgeMap]

entries are summed, so gradients flow to every duplicate.

Source code in btorch/sparse/coo.py
def coalesce(self, return_map: bool = False) -> "COO" | tuple["COO", EdgeMap]:
    """Sort entries row-major and sum duplicates.

    Args:
        return_map: Also return the :class:`EdgeMap` from the old entries
            to the new ones, to move edge-aligned metadata consistently.

    Returns:
        The canonical COO, and the map if requested. The values of merged
        entries are summed, so gradients flow to every duplicate.
    """
    nnz = self.nnz
    if self.properties.canonical:
        edge_map = EdgeMap.identity(nnz, self._indices.device)
        return (self, edge_map) if return_map else self
    sizes = self._indexed_shape
    key = _ravel(self._indices, sizes)
    if self.properties.sorted:
        order = None
        sorted_key = key
    else:
        sorted_key, order = torch.sort(key, stable=True)
    unique_key, inverse = torch.unique_consecutive(sorted_key, return_inverse=True)
    if order is None:
        target = inverse
    else:
        target = torch.empty_like(inverse)
        target[order] = inverse
    edge_map = EdgeMap(target, int(unique_key.shape[0]))
    out = self._like(
        _unravel(unique_key, sizes),
        edge_map.sum(self._values, dim=self._value_batch_dim),
        properties=self.properties.replace(sorted=True, unique=True),
    )
    return (out, edge_map) if return_map else out
indices()

[n_index, nnz] coordinates (PyTorch name).

Source code in btorch/sparse/coo.py
def indices(self) -> Tensor:
    """``[n_index, nnz]`` coordinates (PyTorch name)."""
    return self._indices
sum_duplicates()

SciPy-style alias of :meth:coalesce (returns a new array).

Source code in btorch/sparse/coo.py
def sum_duplicates(self) -> "COO":
    """SciPy-style alias of :meth:`coalesce` (returns a new array)."""
    return self.coalesce()
tocsc(return_map=False)

Convert to canonical CSC (column-major, duplicates summed).

Source code in btorch/sparse/coo.py
def tocsc(self, return_map: bool = False):
    """Convert to canonical CSC (column-major, duplicates summed)."""
    result = self.transpose().tocsr(return_map)
    if return_map:
        return result[0].transpose(), result[1]
    return result.transpose()
tocsr(return_map=False)

Convert to canonical CSR (sorted, duplicates summed).

Parameters:

Name Type Description Default
return_map bool

Also return the :class:EdgeMap from the COO entries to the CSR entries.

False
Source code in btorch/sparse/coo.py
def tocsr(self, return_map: bool = False):
    """Convert to canonical CSR (sorted, duplicates summed).

    Args:
        return_map: Also return the :class:`EdgeMap` from the COO entries
            to the CSR entries.
    """
    from .csr import CSR

    coo, crow, edge_map = self._compressed(return_map)
    out = CSR(
        crow,
        coo._indices[1],
        coo._values,
        coo._shape,
        dense_dim=self._dense_dim,
        properties=coo.properties,
        hints=self.hints,
        check=False,
    )
    return (out, edge_map) if return_map else out
values()

[*value_batch, nnz, *dense] stored values (PyTorch name).

Source code in btorch/sparse/coo.py
def values(self) -> Tensor:
    """``[*value_batch, nnz, *dense]`` stored values (PyTorch name)."""
    return self._values

Properties dataclass

Structural facts about a stored sparse representation.

A True value is a guarantee; False means "not known", never "known to be violated".

Parameters:

Name Type Description Default
sorted bool

Entries are in lexicographic (row-major) index order.

False
unique bool

No index tuple is stored twice.

False
symmetric bool

Stored values satisfy A == A.T.

False
structurally_symmetric bool

The sparsity pattern is symmetric.

False
triangular str | None

"lower", "upper" or None.

None
fixed_pattern bool

The pattern is never mutated (no rewiring).

False
shared_pattern bool

A batch of matrices shares one pattern.

False
Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class Properties:
    """Structural facts about a stored sparse representation.

    A ``True`` value is a guarantee; ``False`` means "not known", never
    "known to be violated".

    Args:
        sorted: Entries are in lexicographic (row-major) index order.
        unique: No index tuple is stored twice.
        symmetric: Stored values satisfy ``A == A.T``.
        structurally_symmetric: The sparsity pattern is symmetric.
        triangular: ``"lower"``, ``"upper"`` or ``None``.
        fixed_pattern: The pattern is never mutated (no rewiring).
        shared_pattern: A batch of matrices shares one pattern.
    """

    sorted: bool = False
    unique: bool = False
    symmetric: bool = False
    structurally_symmetric: bool = False
    triangular: str | None = None
    fixed_pattern: bool = False
    shared_pattern: bool = False

    @property
    def canonical(self) -> bool:
        """Whether entries are sorted and free of duplicates."""
        return self.sorted and self.unique

    def replace(self, **changes) -> "Properties":
        """Return a copy with some fields changed."""
        return replace(self, **changes)
Attributes
canonical property

Whether entries are sorted and free of duplicates.

Methods:
replace(**changes)

Return a copy with some fields changed.

Source code in btorch/sparse/properties.py
def replace(self, **changes) -> "Properties":
    """Return a copy with some fields changed."""
    return replace(self, **changes)

Sparse

Sparse array with logical shape [*batch, *sparse, *dense].

Sparse is the format-agnostic interface. It describes what the array is (shape, dtype, device, number of stored entries) and offers the operations every format supports. Format-specific data such as indptr is only available on the concrete classes (:class:~btorch.sparse.COO, :class:~btorch.sparse.CSR, :class:~btorch.sparse.CSC), obtained with tocsr() / as_csr() and friends.

The three shape groups are:

  • batch_shape: independent sparse arrays (for example an ensemble of networks).
  • sparse_shape: the dimensions that are stored sparsely.
  • dense_shape: a dense payload attached to every stored entry.

Stored values have shape [*value_batch, nnz, *dense_shape]. A batch whose members share one sparsity pattern stores the pattern once and only the values per member.

Sparse is a plain Python object holding tensors; it is not a torch.Tensor subclass. Matrix products follow standard linear algebra: for A.shape == (M, N), A @ x maps a length-N vector to a length-M vector. Conversions never transpose.

Source code in btorch/sparse/base.py
class Sparse:
    """Sparse array with logical shape ``[*batch, *sparse, *dense]``.

    ``Sparse`` is the format-agnostic interface. It describes *what* the array
    is (shape, dtype, device, number of stored entries) and offers the
    operations every format supports. Format-specific data such as ``indptr``
    is only available on the concrete classes (:class:`~btorch.sparse.COO`,
    :class:`~btorch.sparse.CSR`, :class:`~btorch.sparse.CSC`), obtained with
    ``tocsr()`` / ``as_csr()`` and friends.

    The three shape groups are:

    - ``batch_shape``: independent sparse arrays (for example an ensemble of
      networks).
    - ``sparse_shape``: the dimensions that are stored sparsely.
    - ``dense_shape``: a dense payload attached to every stored entry.

    Stored values have shape ``[*value_batch, nnz, *dense_shape]``. A batch
    whose members share one sparsity pattern stores the pattern once and only
    the values per member.

    ``Sparse`` is a plain Python object holding tensors; it is not a
    ``torch.Tensor`` subclass. Matrix products follow standard linear algebra:
    for ``A.shape == (M, N)``, ``A @ x`` maps a length-``N`` vector to a
    length-``M`` vector. Conversions never transpose.
    """

    format: str = "sparse"
    # Let ``ndarray @ A`` reach ``__rmatmul__`` instead of NumPy treating the
    # sparse array as an object scalar.
    __array_ufunc__ = None

    _values: Tensor
    _shape: tuple[int, ...]
    _batch_dim: int
    _dense_dim: int
    properties: Properties
    hints: Hints

    # ------------------------------------------------------------------ shape
    @property
    def shape(self) -> tuple[int, ...]:
        """Logical shape ``(*batch, *sparse, *dense)``."""
        return self._shape

    @property
    def ndim(self) -> int:
        return len(self._shape)

    def batch_dim(self) -> int:
        """Number of batch dimensions."""
        return self._batch_dim

    def dense_dim(self) -> int:
        """Number of dense (per-entry payload) dimensions."""
        return self._dense_dim

    def sparse_dim(self) -> int:
        """Number of sparsely stored dimensions."""
        return self.ndim - self._batch_dim - self._dense_dim

    @property
    def batch_shape(self) -> tuple[int, ...]:
        return self._shape[: self._batch_dim]

    @property
    def sparse_shape(self) -> tuple[int, ...]:
        return self._shape[self._batch_dim : self.ndim - self._dense_dim]

    @property
    def dense_shape(self) -> tuple[int, ...]:
        return self._shape[self.ndim - self._dense_dim :]

    @property
    def dtype(self) -> torch.dtype:
        return self._values.dtype

    @property
    def device(self) -> torch.device:
        return self._values.device

    @property
    def nnz(self) -> int:
        """Number of stored entries (of one batch member for a shared pattern,
        of all members together otherwise)."""
        raise NotImplementedError

    @property
    def requires_grad(self) -> bool:
        return self._values.requires_grad

    # ------------------------------------------------------- format changes
    def tocoo(self) -> "COO":
        """Convert to COO (may allocate)."""
        raise NotImplementedError

    def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
        """Convert to CSR (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
        """Convert to CSC (may sort and merge duplicates).

        Args:
            return_map: Also return the mapping from stored entries to the
                converted entries.
        """
        raise NotImplementedError

    def tobsr(self, blocksize: tuple[int, int]):
        """Convert to BSR; not implemented as a native format.

        Use ``to_torch(layout="bsr", blocksize=...)`` or
        ``to_scipy(format="bsr")`` to export block storage.
        """
        raise NotImplementedError(
            "BSR is not a native btorch format yet; export with "
            "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
        )

    def _as(self, fmt: str):
        if self.format != fmt:
            hint = (
                "BSR is not a native format; export with to_torch(layout='bsr')."
                if fmt == "bsr"
                else f"Call to{fmt}() to convert explicitly."
            )
            raise TypeError(
                f"This sparse array is stored as {self.format.upper()}, not "
                f"{fmt.upper()}; as_{fmt}() never converts. {hint}"
            )
        return self

    def as_coo(self) -> "COO":
        """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
        return self._as("coo")

    def as_csr(self) -> "CSR":
        """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
        return self._as("csr")

    def as_csc(self) -> "CSC":
        """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
        return self._as("csc")

    def as_bsr(self, blocksize: tuple[int, int] | None = None):
        """BSR is not a native format; always raises ``TypeError``."""
        return self._as("bsr")

    # -------------------------------------------------------------- interop
    @classmethod
    def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
        """Wrap a ``torch`` sparse tensor (see
        :func:`btorch.sparse.from_torch`)."""
        from .conversion import from_torch

        return from_torch(tensor, batch_dim=batch_dim)

    @classmethod
    def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
        """Convert a SciPy sparse array or matrix (see
        :func:`btorch.sparse.from_scipy`)."""
        from .conversion import from_scipy

        return from_scipy(array, device=device, dtype=dtype)

    def to_torch(
        self, layout: str | torch.layout | None = None, **kwargs: Any
    ) -> Tensor:
        """Export as a ``torch`` sparse tensor.

        Args:
            layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
                (or the ``torch.sparse_*`` layout). Defaults to the stored
                format.
            **kwargs: ``blocksize`` for the block layouts.
        """
        from .conversion import to_torch

        return to_torch(self, layout, **kwargs)

    def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
        """Export as a ``scipy.sparse`` array (CPU, detached).

        Args:
            format: Any SciPy format name; defaults to the stored format.
            **kwargs: ``blocksize`` for ``"bsr"``.
        """
        from .conversion import to_scipy

        return to_scipy(self, format, **kwargs)

    def to_dense(self) -> Tensor:
        """Materialise as a dense tensor of shape :attr:`shape`."""
        return self.tocoo().to_dense()

    # ------------------------------------------------------- tensor handling
    def with_values(self, values: Tensor) -> "Sparse":
        """Return an array with the same pattern and new values.

        ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
        shape creates a shared-pattern batch.
        """
        raise NotImplementedError

    def _map_tensors(self, index_fn, value_fn) -> "Sparse":
        """Apply ``index_fn`` to index tensors and ``value_fn`` to values."""
        raise NotImplementedError

    def to(self, *args, **kwargs) -> "Sparse":
        """Move to a device and/or cast the values (indices stay integer)."""
        device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

        return self._map_tensors(
            lambda index: index.to(device=device),
            lambda values: values.to(device=device, dtype=dtype),
        )

    def cpu(self) -> "Sparse":
        return self.to("cpu")

    def cuda(self, device=None) -> "Sparse":
        return self.to("cuda" if device is None else device)

    def float(self) -> "Sparse":
        return self.to(torch.float32)

    def double(self) -> "Sparse":
        return self.to(torch.float64)

    def detach(self) -> "Sparse":
        return self.with_values(self._values.detach())

    # ------------------------------------------------------------- products
    def matvec(self, x: Tensor) -> Tensor:
        """Apply the operator along the last axis of ``x``.

        See :func:`btorch.sparse.matvec`.
        """
        from .ops import matvec

        return matvec(self, x)

    def rmatvec(self, x: Tensor) -> Tensor:
        """Apply the transposed operator along the last axis of ``x``."""
        from .ops import rmatvec

        return rmatvec(self, x)

    def __matmul__(self, other):
        from .ops import matmul

        return matmul(self, other)

    def __rmatmul__(self, other):
        from .ops import matmul

        return matmul(other, self)

    @property
    def T(self) -> "Sparse":
        """Transpose of the two sparse dimensions."""
        return self.transpose()

    def transpose(self) -> "Sparse":
        raise NotImplementedError

    def __repr__(self) -> str:
        parts = [f"shape={self.shape}", f"nnz={self.nnz}", f"dtype={self.dtype}"]
        if self.batch_dim():
            parts.append(f"batch_shape={self.batch_shape}")
        if self.dense_dim():
            parts.append(f"dense_shape={self.dense_shape}")
        if self.device.type != "cpu":
            parts.append(f"device={self.device}")
        return f"{type(self).__name__}({', '.join(parts)})"
Attributes
T property

Transpose of the two sparse dimensions.

nnz property

Number of stored entries (of one batch member for a shared pattern, of all members together otherwise).

shape property

Logical shape (*batch, *sparse, *dense).

Methods:
as_bsr(blocksize=None)

BSR is not a native format; always raises TypeError.

Source code in btorch/sparse/base.py
def as_bsr(self, blocksize: tuple[int, int] | None = None):
    """BSR is not a native format; always raises ``TypeError``."""
    return self._as("bsr")
as_coo()

Return self if it is stored as COO, else raise TypeError.

Source code in btorch/sparse/base.py
def as_coo(self) -> "COO":
    """Return ``self`` if it is stored as COO, else raise ``TypeError``."""
    return self._as("coo")
as_csc()

Return self if it is stored as CSC, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csc(self) -> "CSC":
    """Return ``self`` if it is stored as CSC, else raise ``TypeError``."""
    return self._as("csc")
as_csr()

Return self if it is stored as CSR, else raise TypeError.

Source code in btorch/sparse/base.py
def as_csr(self) -> "CSR":
    """Return ``self`` if it is stored as CSR, else raise ``TypeError``."""
    return self._as("csr")
batch_dim()

Number of batch dimensions.

Source code in btorch/sparse/base.py
def batch_dim(self) -> int:
    """Number of batch dimensions."""
    return self._batch_dim
dense_dim()

Number of dense (per-entry payload) dimensions.

Source code in btorch/sparse/base.py
def dense_dim(self) -> int:
    """Number of dense (per-entry payload) dimensions."""
    return self._dense_dim
from_scipy(array, *, device=None, dtype=None) classmethod

Convert a SciPy sparse array or matrix (see :func:btorch.sparse.from_scipy).

Source code in btorch/sparse/base.py
@classmethod
def from_scipy(cls, array: Any, *, device=None, dtype=None) -> "Sparse":
    """Convert a SciPy sparse array or matrix (see
    :func:`btorch.sparse.from_scipy`)."""
    from .conversion import from_scipy

    return from_scipy(array, device=device, dtype=dtype)
from_torch(tensor, *, batch_dim=0) classmethod

Wrap a torch sparse tensor (see :func:btorch.sparse.from_torch).

Source code in btorch/sparse/base.py
@classmethod
def from_torch(cls, tensor: Tensor, *, batch_dim: int = 0) -> "Sparse":
    """Wrap a ``torch`` sparse tensor (see
    :func:`btorch.sparse.from_torch`)."""
    from .conversion import from_torch

    return from_torch(tensor, batch_dim=batch_dim)
matvec(x)

Apply the operator along the last axis of x.

See :func:btorch.sparse.matvec.

Source code in btorch/sparse/base.py
def matvec(self, x: Tensor) -> Tensor:
    """Apply the operator along the last axis of ``x``.

    See :func:`btorch.sparse.matvec`.
    """
    from .ops import matvec

    return matvec(self, x)
rmatvec(x)

Apply the transposed operator along the last axis of x.

Source code in btorch/sparse/base.py
def rmatvec(self, x: Tensor) -> Tensor:
    """Apply the transposed operator along the last axis of ``x``."""
    from .ops import rmatvec

    return rmatvec(self, x)
sparse_dim()

Number of sparsely stored dimensions.

Source code in btorch/sparse/base.py
def sparse_dim(self) -> int:
    """Number of sparsely stored dimensions."""
    return self.ndim - self._batch_dim - self._dense_dim
to(*args, **kwargs)

Move to a device and/or cast the values (indices stay integer).

Source code in btorch/sparse/base.py
def to(self, *args, **kwargs) -> "Sparse":
    """Move to a device and/or cast the values (indices stay integer)."""
    device, dtype, _, _ = torch._C._nn._parse_to(*args, **kwargs)

    return self._map_tensors(
        lambda index: index.to(device=device),
        lambda values: values.to(device=device, dtype=dtype),
    )
to_dense()

Materialise as a dense tensor of shape :attr:shape.

Source code in btorch/sparse/base.py
def to_dense(self) -> Tensor:
    """Materialise as a dense tensor of shape :attr:`shape`."""
    return self.tocoo().to_dense()
to_scipy(format=None, **kwargs)

Export as a scipy.sparse array (CPU, detached).

Parameters:

Name Type Description Default
format str | None

Any SciPy format name; defaults to the stored format.

None
**kwargs Any

blocksize for "bsr".

{}
Source code in btorch/sparse/base.py
def to_scipy(self, format: str | None = None, **kwargs: Any) -> Any:
    """Export as a ``scipy.sparse`` array (CPU, detached).

    Args:
        format: Any SciPy format name; defaults to the stored format.
        **kwargs: ``blocksize`` for ``"bsr"``.
    """
    from .conversion import to_scipy

    return to_scipy(self, format, **kwargs)
to_torch(layout=None, **kwargs)

Export as a torch sparse tensor.

Parameters:

Name Type Description Default
layout str | layout | None

"coo", "csr", "csc", "bsr" or "bsc" (or the torch.sparse_* layout). Defaults to the stored format.

None
**kwargs Any

blocksize for the block layouts.

{}
Source code in btorch/sparse/base.py
def to_torch(
    self, layout: str | torch.layout | None = None, **kwargs: Any
) -> Tensor:
    """Export as a ``torch`` sparse tensor.

    Args:
        layout: ``"coo"``, ``"csr"``, ``"csc"``, ``"bsr"`` or ``"bsc"``
            (or the ``torch.sparse_*`` layout). Defaults to the stored
            format.
        **kwargs: ``blocksize`` for the block layouts.
    """
    from .conversion import to_torch

    return to_torch(self, layout, **kwargs)
tobsr(blocksize)

Convert to BSR; not implemented as a native format.

Use to_torch(layout="bsr", blocksize=...) or to_scipy(format="bsr") to export block storage.

Source code in btorch/sparse/base.py
def tobsr(self, blocksize: tuple[int, int]):
    """Convert to BSR; not implemented as a native format.

    Use ``to_torch(layout="bsr", blocksize=...)`` or
    ``to_scipy(format="bsr")`` to export block storage.
    """
    raise NotImplementedError(
        "BSR is not a native btorch format yet; export with "
        "to_torch(layout='bsr', blocksize=...) or to_scipy(format='bsr')."
    )
tocoo()

Convert to COO (may allocate).

Source code in btorch/sparse/base.py
def tocoo(self) -> "COO":
    """Convert to COO (may allocate)."""
    raise NotImplementedError
tocsc(return_map=False)

Convert to CSC (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsc(self, return_map: bool = False) -> "CSC | tuple[CSC, EdgeMap]":
    """Convert to CSC (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
tocsr(return_map=False)

Convert to CSR (may sort and merge duplicates).

Parameters:

Name Type Description Default
return_map bool

Also return the mapping from stored entries to the converted entries.

False
Source code in btorch/sparse/base.py
def tocsr(self, return_map: bool = False) -> "CSR | tuple[CSR, EdgeMap]":
    """Convert to CSR (may sort and merge duplicates).

    Args:
        return_map: Also return the mapping from stored entries to the
            converted entries.
    """
    raise NotImplementedError
with_values(values)

Return an array with the same pattern and new values.

values is [*batch, nnz, *dense]; a different leading batch shape creates a shared-pattern batch.

Source code in btorch/sparse/base.py
def with_values(self, values: Tensor) -> "Sparse":
    """Return an array with the same pattern and new values.

    ``values`` is ``[*batch, nnz, *dense]``; a different leading batch
    shape creates a shared-pattern batch.
    """
    raise NotImplementedError

Functions:

_apply(out_index, in_index, values, x, n_out, value_batch_dim, dense_dim)

y[..., out_index[e], :] += values[..., e, :] * x[..., in_index[e]].

Parameters:

Name Type Description Default
out_index Tensor

[E] output coordinate of each entry.

required
in_index Tensor

[E] input coordinate of each entry.

required
values Tensor

[*value_batch, E, *dense].

required
x Tensor

[*value_batch (broadcastable), *sample, n_in].

required
n_out int

Size of the output axis.

required
value_batch_dim int

Number of leading batch dimensions of values.

required
dense_dim int

Number of trailing dense dimensions of values.

required

Returns:

Type Description
Tensor

[*value_batch, *sample, n_out, *dense].

Source code in btorch/sparse/ops.py
def _apply(
    out_index: Tensor,
    in_index: Tensor,
    values: Tensor,
    x: Tensor,
    n_out: int,
    value_batch_dim: int,
    dense_dim: int,
) -> Tensor:
    """``y[..., out_index[e], :] += values[..., e, :] * x[..., in_index[e]]``.

    Args:
        out_index: ``[E]`` output coordinate of each entry.
        in_index: ``[E]`` input coordinate of each entry.
        values: ``[*value_batch, E, *dense]``.
        x: ``[*value_batch (broadcastable), *sample, n_in]``.
        n_out: Size of the output axis.
        value_batch_dim: Number of leading batch dimensions of ``values``.
        dense_dim: Number of trailing dense dimensions of ``values``.

    Returns:
        ``[*value_batch, *sample, n_out, *dense]``.
    """
    gathered = x.index_select(-1, in_index)
    n_sample = gathered.ndim - 1 - value_batch_dim
    values = values.reshape(
        *values.shape[:value_batch_dim],
        *(1,) * n_sample,
        *values.shape[value_batch_dim:],
    )
    gathered = gathered.reshape(*gathered.shape, *(1,) * dense_dim)
    contrib = gathered * values
    edge_axis = value_batch_dim + n_sample
    out = contrib.new_zeros(
        *contrib.shape[:edge_axis], n_out, *contrib.shape[edge_axis + 1 :]
    )
    return out.index_add(edge_axis, out_index, contrib)

_check_batch(A, x, n_in, what)

Source code in btorch/sparse/ops.py
def _check_batch(A: Sparse, x: Tensor, n_in: int, what: str) -> None:
    if x.shape[-1] != n_in:
        raise ValueError(
            f"{what}: the last dimension of the input is {x.shape[-1]}, "
            f"expected {n_in} for a sparse array of shape {A.shape}."
        )
    bd = A.batch_dim()
    if bd == 0:
        return
    if x.ndim - 1 < bd:
        raise ValueError(
            f"{what}: the sparse array has batch shape {A.batch_shape}, so the "
            f"input needs shape [*batch, ..., {n_in}], got {tuple(x.shape)}. "
            "Batch members are never combined implicitly with every input "
            "sample: add the batch dimensions explicitly, e.g. "
            "x.unsqueeze(0), and they will broadcast."
        )
    for a, b in zip(A.batch_shape, x.shape[:bd]):
        if b != 1 and a != 1 and b != a:
            raise ValueError(
                f"{what}: the leading dimensions {tuple(x.shape[:bd])} of the "
                f"input do not broadcast with the batch shape {A.batch_shape}."
            )

_matmat(A, x, transpose)

Batched product with torch.matmul (right-aligned) broadcasting.

x is [..., K, n] with the operator applied along the last axis; batch dimensions of A align with the dimensions right before K.

Source code in btorch/sparse/ops.py
def _matmat(A: Sparse, x: Tensor, transpose: bool) -> Tensor:
    """Batched product with ``torch.matmul`` (right-aligned) broadcasting.

    ``x`` is ``[..., K, n]`` with the operator applied along the last axis;
    batch dimensions of ``A`` align with the dimensions right before ``K``.
    """
    bd = A.batch_dim()
    if bd == 0:
        return _matvec(A, x, transpose)
    n_lead = x.ndim - 2
    if n_lead < bd:
        x = x.reshape(*(1,) * (bd - n_lead), *x.shape)
        n_lead = bd
    extra = n_lead - bd
    # [*extra, *batch, K, n] -> [*batch, *extra, K, n]
    order = list(range(extra, n_lead)) + list(range(extra)) + [n_lead, n_lead + 1]
    y = _matvec(A, x.permute(*order), transpose)
    back = list(range(bd, n_lead)) + list(range(bd)) + list(range(n_lead, y.ndim))
    return y.permute(*back)

_matvec(A, x, transpose)

Source code in btorch/sparse/ops.py
def _matvec(A: Sparse, x: Tensor, transpose: bool) -> Tensor:
    if A.sparse_dim() != 2:
        raise ValueError(
            f"Matrix products need two sparse dimensions, got {A.sparse_dim()}; "
            "use sparse.einsum for higher-order arrays."
        )
    lead, row, col = A._edge_index()
    n_row, n_col = A.sparse_shape
    if transpose:
        row, col, n_row, n_col = col, row, n_col, n_row
    _check_batch(A, x, n_col, "rmatvec" if transpose else "matvec")
    values = A._values
    if not (x.is_floating_point() or x.is_complex()) and values.is_floating_point():
        x = x.to(values.dtype)
    n_vb = A._value_batch_dim
    dd = A.dense_dim()
    if lead is None:
        return _apply(row, col, values, x, n_row, n_vb, dd)

    # Different patterns per batch member: fold the batch coordinate into the
    # row/column index and run one product over the block-diagonal operator.
    bd = A.batch_dim()
    ib_shape = A.batch_shape[n_vb:]
    n_member = math.prod(ib_shape)
    x = x.expand(*x.shape[:n_vb], *ib_shape, *x.shape[bd:])
    n_sample = x.ndim - 1 - bd
    vb_axes = list(range(n_vb))
    ib_axes = list(range(n_vb, bd))
    sample_axes = list(range(bd, bd + n_sample))
    x = x.permute(*vb_axes, *sample_axes, *ib_axes, x.ndim - 1)
    sample_shape = x.shape[n_vb : n_vb + n_sample]
    x = x.reshape(*x.shape[:n_vb], *sample_shape, n_member * n_col)
    member = _ravel(lead, ib_shape)
    y = _apply(
        member * n_row + row,
        member * n_col + col,
        values,
        x,
        n_member * n_row,
        n_vb,
        dd,
    )
    dense = y.shape[y.ndim - dd :] if dd else ()
    y = y.reshape(*y.shape[:n_vb], *sample_shape, *ib_shape, n_row, *dense)
    # [vb, sample, ib, n_row, dense] -> [vb, ib, sample, n_row, dense]
    n_ib = len(ib_shape)
    s0 = n_vb
    i0 = n_vb + n_sample
    order = (
        vb_axes
        + list(range(i0, i0 + n_ib))
        + list(range(s0, s0 + n_sample))
        + list(range(i0 + n_ib, y.ndim))
    )
    return y.permute(*order)

_ravel(indices, sizes)

Row-major linear index of indices [len(sizes), E].

Source code in btorch/sparse/coo.py
def _ravel(indices: Tensor, sizes: tuple[int, ...]) -> Tensor:
    """Row-major linear index of ``indices [len(sizes), E]``."""
    if math.prod(max(int(s), 1) for s in sizes) >= 2**63:
        raise OverflowError(
            f"The indexed shape {tuple(sizes)} has more than 2**63 positions; "
            "its entries cannot be linearised into int64 keys."
        )
    key = torch.zeros(indices.shape[1], dtype=torch.long, device=indices.device)
    for i, size in enumerate(sizes):
        key = key * size + indices[i]
    return key

_same_pattern(a, b)

Source code in btorch/sparse/ops.py
def _same_pattern(a: Sparse, b: Sparse) -> bool:
    if a.nnz != b.nnz:
        return False
    if a.format == "coo":
        return torch.equal(a._indices, b._indices)
    return torch.equal(a._pointer, b._pointer) and torch.equal(a._minor, b._minor)

matmul(a, b)

Matrix product with one sparse operand; the function behind @.

Shapes follow :func:torch.matmul:

  • A @ x with 1-D x of length N returns length M.
  • A @ X with X.shape == (..., N, K) returns (..., M, K).
  • x @ A with 1-D x of length M returns length N.
  • X @ A with X.shape == (..., K, M) returns (..., K, N).

Batch dimensions of the sparse operand broadcast with the leading dimensions of the dense operand as in torch.matmul. To apply a matrix to a stack of vectors [..., N] use :func:matvec.

Parameters:

Name Type Description Default
a Any

Left operand (sparse array or dense tensor).

required
b Any

Right operand (dense tensor or sparse array).

required

Returns:

Type Description
Tensor

Dense tensor.

Source code in btorch/sparse/ops.py
def matmul(a: Any, b: Any) -> Tensor:
    """Matrix product with one sparse operand; the function behind ``@``.

    Shapes follow :func:`torch.matmul`:

    - ``A @ x`` with 1-D ``x`` of length ``N`` returns length ``M``.
    - ``A @ X`` with ``X.shape == (..., N, K)`` returns ``(..., M, K)``.
    - ``x @ A`` with 1-D ``x`` of length ``M`` returns length ``N``.
    - ``X @ A`` with ``X.shape == (..., K, M)`` returns ``(..., K, N)``.

    Batch dimensions of the sparse operand broadcast with the leading
    dimensions of the dense operand as in ``torch.matmul``. To apply a matrix
    to a stack of vectors ``[..., N]`` use :func:`matvec`.

    Args:
        a: Left operand (sparse array or dense tensor).
        b: Right operand (dense tensor or sparse array).

    Returns:
        Dense tensor.
    """
    # Non-sparse linear operators implement the product themselves.
    for operand, method in ((a, "__matmul__"), (b, "__rmatmul__")):
        if not isinstance(operand, (Sparse, Tensor)) and hasattr(operand, "matvec"):
            other = b if operand is a else a
            return getattr(operand, method)(other)
    a_sparse, b_sparse = isinstance(a, Sparse), isinstance(b, Sparse)
    if a_sparse and b_sparse:
        raise NotImplementedError(
            "sparse @ sparse (operator composition / SpGEMM) is not implemented."
        )
    if a_sparse:
        if not isinstance(b, Tensor):
            return NotImplemented
        if a.dense_dim() and b.ndim > 1:
            raise NotImplementedError(
                "A @ X with a matrix right-hand side is not defined for arrays "
                "with dense entry dimensions; use matvec or sparse.einsum."
            )
        if b.ndim == 1:
            if a.batch_dim():
                b = b.reshape(*(1,) * a.batch_dim(), -1)
            return _matvec(a, b, transpose=False)
        return _matmat(a, b.mT, transpose=False).mT
    if b_sparse:
        if not isinstance(a, Tensor):
            return NotImplemented
        if b.dense_dim() and a.ndim > 1:
            raise NotImplementedError(
                "X @ A with a matrix left-hand side is not defined for arrays "
                "with dense entry dimensions; use rmatvec or sparse.einsum."
            )
        if a.ndim == 1:
            if b.batch_dim():
                a = a.reshape(*(1,) * b.batch_dim(), -1)
            return _matvec(b, a, transpose=True)
        return _matmat(b, a, transpose=True)
    return torch.matmul(a, b)

matvec(A, x)

Apply a sparse matrix along the last axis of a dense tensor.

For A.shape == (*batch, M, N, *dense) and x.shape == (*batch, ..., N) the result has shape (*batch, ..., M, *dense):

.. math:: y_{\ldots m} = \sum_n A_{m n}\, x_{\ldots n}

Any number of leading dimensions of x is treated as independent samples. If A has batch dimensions they align with the leading dimensions of x and broadcast (size 1 in x broadcasts); they are never combined with the sample dimensions implicitly.

Parameters:

Name Type Description Default
A Sparse

Sparse array with two sparse dimensions.

required
x Tensor

Dense tensor whose last dimension is N.

required

Returns:

Type Description
Tensor

Dense tensor.

Raises:

Type Description
ValueError

On a shape mismatch, or if x has fewer leading dimensions than A has batch dimensions.

Source code in btorch/sparse/ops.py
def matvec(A: Sparse, x: Tensor) -> Tensor:
    """Apply a sparse matrix along the last axis of a dense tensor.

    For ``A.shape == (*batch, M, N, *dense)`` and ``x.shape == (*batch, ...,
    N)`` the result has shape ``(*batch, ..., M, *dense)``:

    .. math::
        y_{\\ldots m} = \\sum_n A_{m n}\\, x_{\\ldots n}

    Any number of leading dimensions of ``x`` is treated as independent
    samples. If ``A`` has batch dimensions they align with the *leading*
    dimensions of ``x`` and broadcast (size 1 in ``x`` broadcasts); they are
    never combined with the sample dimensions implicitly.

    Args:
        A: Sparse array with two sparse dimensions.
        x: Dense tensor whose last dimension is ``N``.

    Returns:
        Dense tensor.

    Raises:
        ValueError: On a shape mismatch, or if ``x`` has fewer leading
            dimensions than ``A`` has batch dimensions.
    """
    if not isinstance(A, Sparse):
        return A.matvec(x)
    return _matvec(A, x, transpose=False)

rmatvec(A, x)

Apply the transpose of a sparse matrix along the last axis of x.

rmatvec(A, x) equals matvec(A.T, x) (and x @ A for 1-D x) without building the transpose. x has shape (*batch, ..., M) and the result (*batch, ..., N, *dense).

Source code in btorch/sparse/ops.py
def rmatvec(A: Sparse, x: Tensor) -> Tensor:
    """Apply the transpose of a sparse matrix along the last axis of ``x``.

    ``rmatvec(A, x)`` equals ``matvec(A.T, x)`` (and ``x @ A`` for 1-D ``x``)
    without building the transpose. ``x`` has shape ``(*batch, ..., M)`` and
    the result ``(*batch, ..., N, *dense)``.
    """
    if not isinstance(A, Sparse):
        return A.rmatvec(x)
    return _matvec(A, x, transpose=True)

stack(arrays)

Stack sparse arrays along a new leading batch dimension.

The members must have the same shape. If they all store the same sparsity pattern the result shares it (indices stored once, values [G, nnz]) and keeps the format of the first member. Otherwise the members may have different numbers of entries; the result is a batched COO that stores sum(nnz) entries without padding.

Parameters:

Name Type Description Default
arrays Sequence[Sparse]

Sparse arrays of identical shape.

required

Returns:

Type Description
Sparse

Sparse array of shape (len(arrays), *shape).

Examples:

>>> A = sparse.stack([A0, A1, A2])
>>> A.batch_shape
(3,)
>>> y = A.matvec(x)                      # x: [3, B, N] -> [3, B, M]
Source code in btorch/sparse/ops.py
def stack(arrays: Sequence[Sparse]) -> Sparse:
    """Stack sparse arrays along a new leading batch dimension.

    The members must have the same shape. If they all store the same sparsity
    pattern the result shares it (indices stored once, values ``[G, nnz]``)
    and keeps the format of the first member. Otherwise the members may have
    different numbers of entries; the result is a batched COO that stores
    ``sum(nnz)`` entries without padding.

    Args:
        arrays: Sparse arrays of identical shape.

    Returns:
        Sparse array of shape ``(len(arrays), *shape)``.

    Examples:
        >>> A = sparse.stack([A0, A1, A2])       # doctest: +SKIP
        >>> A.batch_shape
        (3,)
        >>> y = A.matvec(x)                      # x: [3, B, N] -> [3, B, M]
    """
    arrays = list(arrays)
    if not arrays:
        raise ValueError("stack needs at least one sparse array.")
    first = arrays[0]
    for a in arrays:
        if not isinstance(a, Sparse):
            raise TypeError(f"stack expects sparse arrays, got {type(a).__name__}.")
        if a.shape != first.shape or a.dense_dim() != first.dense_dim():
            raise ValueError(
                f"All stacked arrays need the same shape, got {a.shape} and "
                f"{first.shape}."
            )
        if a.batch_dim():
            raise NotImplementedError("Stacking already batched arrays.")

    same_pattern = all(a.format == first.format for a in arrays) and all(
        _same_pattern(first, a) for a in arrays[1:]
    )
    if same_pattern:
        return first.with_values(torch.stack([a._values for a in arrays]))

    coos = [a.tocoo() for a in arrays]
    indices = torch.cat(
        [
            torch.cat([torch.full_like(c._indices[:1], g), c._indices])
            for g, c in enumerate(coos)
        ],
        dim=1,
    )
    values = torch.cat([c._values for c in coos])
    canonical = all(c.properties.canonical for c in coos)
    return COO(
        indices,
        values,
        (len(coos), *first.shape),
        batch_dim=1,
        dense_dim=first.dense_dim(),
        properties=Properties(sorted=canonical, unique=canonical),
        check=False,
    )

btorch.sparse.properties

Structural properties, performance hints and edge maps of sparse objects.

Properties are facts about a stored representation that correctness may rely on (for example that indices are sorted). Hints are expectations about how the object will be used; they never change results.

Classes

EdgeMap dataclass

Correspondence between the entries of two representations.

A representation change (sorting, duplicate reduction) maps every old entry e to a new entry target[e]. Every edge-aligned array (values, group ids, receptors, delays, plasticity state) must be moved with the same map, so the map is computed once and applied to each of them.

Parameters:

Name Type Description Default
target Tensor

[n_old] new position of every old entry.

required
n_new int

Number of entries after the change.

required
Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class EdgeMap:
    """Correspondence between the entries of two representations.

    A representation change (sorting, duplicate reduction) maps every old
    entry ``e`` to a new entry ``target[e]``. Every edge-aligned array (values,
    group ids, receptors, delays, plasticity state) must be moved with the same
    map, so the map is computed once and applied to each of them.

    Args:
        target: ``[n_old]`` new position of every old entry.
        n_new: Number of entries after the change.
    """

    target: Tensor
    n_new: int

    @property
    def n_old(self) -> int:
        return int(self.target.shape[0])

    @property
    def is_permutation(self) -> bool:
        """Whether no entries were merged."""
        return self.n_old == self.n_new

    def source(self) -> Tensor:
        """``[n_new]`` index of one old entry for every new entry.

        For merged duplicates this is the last old entry of the group.
        """
        old = torch.arange(self.n_old, device=self.target.device)
        if self.is_permutation:
            src = torch.empty_like(old)
            src[self.target] = old
            return src
        # Deterministic on every device (an indexed assignment with repeated
        # targets is not).
        src = self.target.new_zeros(self.n_new)
        return src.scatter_reduce(0, self.target, old, "amax", include_self=False)

    def sum(self, values: Tensor, dim: int = -1) -> Tensor:
        """Move additive data (weights); merged entries are summed.

        Differentiable: the gradient of a merged entry flows to every old
        entry that was merged into it.

        Args:
            values: Tensor whose axis ``dim`` has length ``n_old``.
            dim: Edge axis.
        """
        if self.is_permutation:
            return values.index_select(dim, self.source())
        shape = list(values.shape)
        shape[dim] = self.n_new
        return values.new_zeros(shape).index_add(dim, self.target, values)

    def take(self, meta: Tensor, dim: int = 0, check: bool = True) -> Tensor:
        """Move categorical metadata (group, receptor, delay ids).

        Args:
            meta: Tensor whose axis ``dim`` has length ``n_old``.
            dim: Edge axis.
            check: Raise if merged entries carry different metadata, because
                no single value can then represent the merged entry.

        Raises:
            ValueError: If ``check`` and merged duplicates disagree.
        """
        out = meta.index_select(dim, self.source())
        if check and not self.is_permutation:
            if not torch.equal(out.index_select(dim, self.target), meta):
                raise ValueError(
                    "Duplicate entries carry different metadata and cannot be "
                    "merged; split them into separate connections or make the "
                    "metadata equal first."
                )
        return out

    def compose(self, then: "EdgeMap") -> "EdgeMap":
        """Map equivalent to applying ``self`` and then ``then``."""
        return EdgeMap(then.target[self.target], then.n_new)

    @staticmethod
    def identity(n: int, device=None) -> "EdgeMap":
        return EdgeMap(torch.arange(n, device=device), n)
Attributes
is_permutation property

Whether no entries were merged.

Methods:
compose(then)

Map equivalent to applying self and then then.

Source code in btorch/sparse/properties.py
def compose(self, then: "EdgeMap") -> "EdgeMap":
    """Map equivalent to applying ``self`` and then ``then``."""
    return EdgeMap(then.target[self.target], then.n_new)
source()

[n_new] index of one old entry for every new entry.

For merged duplicates this is the last old entry of the group.

Source code in btorch/sparse/properties.py
def source(self) -> Tensor:
    """``[n_new]`` index of one old entry for every new entry.

    For merged duplicates this is the last old entry of the group.
    """
    old = torch.arange(self.n_old, device=self.target.device)
    if self.is_permutation:
        src = torch.empty_like(old)
        src[self.target] = old
        return src
    # Deterministic on every device (an indexed assignment with repeated
    # targets is not).
    src = self.target.new_zeros(self.n_new)
    return src.scatter_reduce(0, self.target, old, "amax", include_self=False)
sum(values, dim=-1)

Move additive data (weights); merged entries are summed.

Differentiable: the gradient of a merged entry flows to every old entry that was merged into it.

Parameters:

Name Type Description Default
values Tensor

Tensor whose axis dim has length n_old.

required
dim int

Edge axis.

-1
Source code in btorch/sparse/properties.py
def sum(self, values: Tensor, dim: int = -1) -> Tensor:
    """Move additive data (weights); merged entries are summed.

    Differentiable: the gradient of a merged entry flows to every old
    entry that was merged into it.

    Args:
        values: Tensor whose axis ``dim`` has length ``n_old``.
        dim: Edge axis.
    """
    if self.is_permutation:
        return values.index_select(dim, self.source())
    shape = list(values.shape)
    shape[dim] = self.n_new
    return values.new_zeros(shape).index_add(dim, self.target, values)
take(meta, dim=0, check=True)

Move categorical metadata (group, receptor, delay ids).

Parameters:

Name Type Description Default
meta Tensor

Tensor whose axis dim has length n_old.

required
dim int

Edge axis.

0
check bool

Raise if merged entries carry different metadata, because no single value can then represent the merged entry.

True

Raises:

Type Description
ValueError

If check and merged duplicates disagree.

Source code in btorch/sparse/properties.py
def take(self, meta: Tensor, dim: int = 0, check: bool = True) -> Tensor:
    """Move categorical metadata (group, receptor, delay ids).

    Args:
        meta: Tensor whose axis ``dim`` has length ``n_old``.
        dim: Edge axis.
        check: Raise if merged entries carry different metadata, because
            no single value can then represent the merged entry.

    Raises:
        ValueError: If ``check`` and merged duplicates disagree.
    """
    out = meta.index_select(dim, self.source())
    if check and not self.is_permutation:
        if not torch.equal(out.index_select(dim, self.target), meta):
            raise ValueError(
                "Duplicate entries carry different metadata and cannot be "
                "merged; split them into separate connections or make the "
                "metadata equal first."
            )
    return out

Hints dataclass

Performance expectations; advisory only.

Only expected_density is consulted by the planner today; the other two are accepted and reserved.

Parameters:

Name Type Description Default
expected_calls int | None

How many products the object will take part in (reserved).

None
expected_density float | None

Expected fraction of non-zero input entries, in [0, 1].

None
expected_batch int | None

Expected number of right-hand sides per call (reserved).

None

Raises:

Type Description
ValueError

If a value is out of range.

Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class Hints:
    """Performance expectations; advisory only.

    Only ``expected_density`` is consulted by the planner today; the other
    two are accepted and reserved.

    Args:
        expected_calls: How many products the object will take part in
            (reserved).
        expected_density: Expected fraction of non-zero input entries, in
            ``[0, 1]``.
        expected_batch: Expected number of right-hand sides per call
            (reserved).

    Raises:
        ValueError: If a value is out of range.
    """

    expected_calls: int | None = None
    expected_density: float | None = None
    expected_batch: int | None = None

    def __post_init__(self) -> None:
        density = self.expected_density
        if density is not None and not (
            isinstance(density, (int, float)) and 0.0 <= density <= 1.0
        ):
            raise ValueError(f"expected_density must be in [0, 1], got {density!r}.")
        for name in ("expected_calls", "expected_batch"):
            value = getattr(self, name)
            if value is not None and not (isinstance(value, int) and value > 0):
                raise ValueError(f"{name} must be a positive int, got {value!r}.")

    def replace(self, **changes) -> "Hints":
        """Return a copy with selected expectations changed."""
        return replace(self, **changes)
Methods:
replace(**changes)

Return a copy with selected expectations changed.

Source code in btorch/sparse/properties.py
def replace(self, **changes) -> "Hints":
    """Return a copy with selected expectations changed."""
    return replace(self, **changes)

Properties dataclass

Structural facts about a stored sparse representation.

A True value is a guarantee; False means "not known", never "known to be violated".

Parameters:

Name Type Description Default
sorted bool

Entries are in lexicographic (row-major) index order.

False
unique bool

No index tuple is stored twice.

False
symmetric bool

Stored values satisfy A == A.T.

False
structurally_symmetric bool

The sparsity pattern is symmetric.

False
triangular str | None

"lower", "upper" or None.

None
fixed_pattern bool

The pattern is never mutated (no rewiring).

False
shared_pattern bool

A batch of matrices shares one pattern.

False
Source code in btorch/sparse/properties.py
@dataclass(frozen=True)
class Properties:
    """Structural facts about a stored sparse representation.

    A ``True`` value is a guarantee; ``False`` means "not known", never
    "known to be violated".

    Args:
        sorted: Entries are in lexicographic (row-major) index order.
        unique: No index tuple is stored twice.
        symmetric: Stored values satisfy ``A == A.T``.
        structurally_symmetric: The sparsity pattern is symmetric.
        triangular: ``"lower"``, ``"upper"`` or ``None``.
        fixed_pattern: The pattern is never mutated (no rewiring).
        shared_pattern: A batch of matrices shares one pattern.
    """

    sorted: bool = False
    unique: bool = False
    symmetric: bool = False
    structurally_symmetric: bool = False
    triangular: str | None = None
    fixed_pattern: bool = False
    shared_pattern: bool = False

    @property
    def canonical(self) -> bool:
        """Whether entries are sorted and free of duplicates."""
        return self.sorted and self.unique

    def replace(self, **changes) -> "Properties":
        """Return a copy with some fields changed."""
        return replace(self, **changes)
Attributes
canonical property

Whether entries are sorted and free of duplicates.

Methods:
replace(**changes)

Return a copy with some fields changed.

Source code in btorch/sparse/properties.py
def replace(self, **changes) -> "Properties":
    """Return a copy with some fields changed."""
    return replace(self, **changes)

btorch.sparse.runtime

Sparse execution runtime: planner, caches, backends and registered ops.

Nothing in this package is needed to define a model. It is the layer below :mod:btorch.models.connection that turns canonical tensor buffers into executed kernels, and the place where additional backends are registered.

Attributes

__all__ = ['BackendRegistry', 'KernelCache', 'Planner', 'RepresentationCache', 'csr_propagate', 'pack_spikes', 'planner', 'propagate', 'registry', 'spike_propagate', 'use_backend'] module-attribute

registry = BackendRegistry() module-attribute

Classes

BackendRegistry dataclass

Registry mapping (kernel, device type) to implementations.

The highest-priority available backend is used unless an override is active (see :func:use_backend). Backends are advanced runtime options; they do not appear in model constructors.

Source code in btorch/sparse/runtime/backend.py
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
@dataclass
class BackendRegistry:
    """Registry mapping ``(kernel, device type)`` to implementations.

    The highest-priority available backend is used unless an override is
    active (see :func:`use_backend`). Backends are advanced runtime options;
    they do not appear in model constructors.
    """

    _entries: dict[tuple[str, str], list[_Entry]] = field(default_factory=dict)
    _route_entries: dict[tuple[RouteKey, str], _RouteEntry] = field(
        default_factory=dict
    )
    _resolved: dict[tuple[str, str, str | None], _Entry] = field(default_factory=dict)
    _has: dict[tuple[str, str, str | None], bool] = field(default_factory=dict)
    _entry_revisions: dict[tuple[str, str, str], int] = field(default_factory=dict)
    _availability: dict[tuple[str, str, str, int], bool] = field(default_factory=dict)
    _route_revisions: dict[tuple[RouteKey, str], int] = field(default_factory=dict)
    _route_availability: dict[tuple[RouteKey, str, int], bool] = field(
        default_factory=dict
    )
    _registry_generation: int = 0
    _override_context: ContextVar[_OverrideState] = field(
        default_factory=lambda: ContextVar(
            "btorch_sparse_backend_override", default=_OverrideState(None, 0)
        ),
        repr=False,
    )
    kernels: KernelCache = field(default_factory=KernelCache)

    @property
    def _override(self) -> str | None:
        """Return the current context-local override.

        This private compatibility property is retained for older callers and
        tests. New code should use :attr:`override` or :meth:`snapshot`.
        """
        return self._override_state().name

    @_override.setter
    def _override(self, name: str | None) -> None:
        self.set_backend(name)

    @property
    def override(self) -> str | None:
        """Return the backend override active in the current context."""
        return self._override_state().name

    @property
    def override_revision(self) -> int:
        """Return the current context-local override revision."""
        return self._override_state().revision

    @property
    def registry_generation(self) -> int:
        """Return the process-wide registry generation."""
        return self._registry_generation

    @property
    def generation(self) -> int:
        """Alias for :attr:`registry_generation`."""
        return self._registry_generation

    def register(
        self,
        kernel: str,
        name: str,
        fn: Callable,
        *,
        device: str | tuple[str, ...] = ("cpu", "cuda"),
        priority: int = 0,
        available: Callable[[], bool] | None = None,
    ) -> None:
        """Register ``fn`` as backend ``name`` of ``kernel``.

        Args:
            kernel: Kernel name.
            name: Backend name (``"aten"``, ``"triton"``, ...).
            fn: Implementation.
            device: Device type(s) the implementation supports.
            priority: Higher wins when several backends are available.
            available: Optional lazy availability check.
        """
        devices = (device,) if isinstance(device, str) else device
        for dev in devices:
            entries = self._entries.setdefault((kernel, dev), [])
            entries[:] = [entry for entry in entries if entry.name != name]
            entry_key = (kernel, dev, name)
            revision = self._entry_revisions.get(entry_key, 0) + 1
            self._entry_revisions[entry_key] = revision
            self._availability = {
                key: value
                for key, value in self._availability.items()
                if key[:3] != entry_key
            }
            entries.append(
                _Entry(
                    name,
                    fn,
                    priority,
                    available or (lambda: True),
                    revision,
                )
            )
            entries.sort(key=lambda entry: -entry.priority)
        self._invalidate_resolution()
        self._registry_generation += 1

    def available(self, kernel: str, device: str) -> list[str]:
        """Names of the usable backends of ``kernel`` on ``device``, best
        first."""
        return [entry.name for entry in self._usable_entries(kernel, device)]

    def register_route(
        self,
        spec: RouteSpec,
        *,
        device: str | tuple[str, ...] = ("cpu", "cuda"),
        priority: int = 0,
        available: Callable[[], bool] | None = None,
        replace: bool = False,
    ) -> None:
        """Register one complete route candidate.

        A route is deliberately separate from legacy kernel registrations:
        the latter remain independently usable by the public low-level ops,
        while planning only sees complete route contracts.
        """
        devices = (device,) if isinstance(device, str) else device
        for dev in devices:
            key = (spec.key, dev)
            if key in self._route_entries and not replace:
                raise ValueError(
                    f"Route {spec.key!r} is already registered for {dev!r}; "
                    "use replace=True to replace it."
                )
            revision = self._route_revisions.get(key, 0) + 1
            self._route_revisions[key] = revision
            self._route_availability = {
                marker: value
                for marker, value in self._route_availability.items()
                if marker[:2] != key
            }
            self._route_entries[key] = _RouteEntry(
                spec=spec,
                device=dev,
                priority=priority,
                available=available or (lambda: True),
                revision=revision,
            )
        self._invalidate_resolution()
        self._registry_generation += 1

    def has_route(
        self,
        algorithm: str,
        device: str,
        context: PlanningContext | None = None,
    ) -> bool:
        """Return whether a complete route supports ``context``."""
        return bool(self._usable_routes(algorithm, device, context))

    def resolve_route(
        self,
        algorithm: str,
        device: str,
        context: PlanningContext | None = None,
    ) -> RouteResolutionSnapshot:
        """Select one complete route and return only its immutable identity."""
        candidates = self._usable_routes(algorithm, device, context)
        if not candidates:
            raise RuntimeError(f"No route for algorithm {algorithm!r} on {device!r}.")
        override = self.override
        if override is not None:
            forced = [entry for entry in candidates if entry.spec.backend == override]
            if forced:
                candidates = forced
        chosen = min(
            candidates,
            key=lambda entry: (
                -entry.priority,
                entry.spec.estimate_cost(context),
                entry.spec.key,
            ),
        )
        state = self._override_state()
        kernel_revisions = tuple(
            (kernel, backend, self.entry_revision(kernel, backend, device))
            for kernel, backend in chosen.spec.kernel_bindings
        )
        return RouteResolutionSnapshot(
            key=chosen.spec.key,
            algorithm=chosen.spec.algorithm,
            backend=chosen.spec.backend,
            device=device,
            revision=chosen.revision,
            registry_generation=self._registry_generation,
            override=state.name,
            override_revision=state.revision,
            kernel_revisions=kernel_revisions,
        )

    def bind_route(self, snapshot: RouteResolutionSnapshot) -> RouteBinding:
        """Bind exact callbacks for a previously selected route snapshot."""
        if snapshot.registry_generation != self._registry_generation:
            raise RuntimeError(
                "The selected sparse route is stale; replan before binding it."
            )
        entry = self._route_entries.get((snapshot.key, snapshot.device))
        if entry is None or entry.revision != snapshot.revision:
            raise RuntimeError(
                f"Sparse route {snapshot.key!r} changed before it was bound."
            )
        if not self._route_is_available(entry):
            raise RuntimeError(
                f"Sparse route {snapshot.key!r} is unavailable on "
                f"{snapshot.device!r}."
            )
        callbacks: dict[str, Callable] = {}
        for kernel, backend in entry.spec.kernel_bindings:
            current = self._resolve_exact(kernel, snapshot.device, backend)
            expected = next(
                revision
                for name, name_backend, revision in snapshot.kernel_revisions
                if name == kernel and name_backend == backend
            )
            if current.revision != expected:
                raise RuntimeError(
                    f"Sparse route {snapshot.key!r} changed its {kernel!r} "
                    "implementation before it was bound."
                )
            callbacks[kernel] = current.fn
        return RouteBinding(snapshot, entry.spec.build(callbacks))

    def route_revision(self, key: RouteKey, device: str) -> int:
        """Return the revision of a registered route."""
        try:
            return self._route_revisions[(key, device)]
        except KeyError as error:
            raise KeyError(f"No route {key!r} for device {device!r}.") from error

    def has(self, kernel: str, device: str) -> bool:
        """Whether a backend of ``kernel`` is usable on ``device``.

        With a forced backend (:func:`use_backend`) only that backend counts.
        """
        override = self.override
        key = (kernel, device, override)
        known = self._has.get(key)
        if known is None:
            entries = self._usable_entries(kernel, device)
            if override is not None:
                # A forced backend that lacks this (optional) kernel means "no".
                known = any(entry.name == override for entry in entries)
            else:
                known = bool(entries)
            self._has[key] = known
        return known

    def resolve(self, kernel: str, device: str) -> Callable:
        """Return the implementation to use for ``kernel`` on ``device``."""
        return self._resolve(kernel, device).fn

    def name(self, kernel: str, device: str) -> str:
        """Name of the backend :meth:`resolve` would pick."""
        return self._resolve(kernel, device).name

    def _resolve(self, kernel: str, device: str) -> _Entry:
        override = self.override
        key = (kernel, device, override)
        entries = self._usable_entries(kernel, device)
        if not entries:
            raise RuntimeError(f"No backend for kernel {kernel!r} on {device!r}.")
        hit = self._resolved.get(key)
        if hit is not None and any(entry is hit for entry in entries):
            return hit
        chosen = entries[0]
        if override is not None:
            # An override that does not implement this kernel falls back to
            # the default choice, so a partial backend can still be forced.
            chosen = next(
                (entry for entry in entries if entry.name == override), chosen
            )
        self._resolved[key] = chosen
        return chosen

    def _resolve_exact(self, kernel: str, device: str, name: str) -> _Entry:
        """Resolve one named implementation without consulting overrides."""
        entries = self._usable_entries(kernel, device)
        for entry in entries:
            if entry.name == name:
                return entry
        raise RuntimeError(
            f"No available backend {name!r} for kernel {kernel!r} on {device!r}."
        )

    def set_backend(self, name: str | None) -> None:
        """Force backend ``name`` in the current context (``None``: auto).

        Raises:
            ValueError: If no kernel has a backend called ``name``.
        """
        known = {entry.name for entries in self._entries.values() for entry in entries}
        if name is not None and name not in known:
            raise ValueError(
                f"Unknown backend {name!r}; registered backends: {sorted(known)}."
            )
        current = self._override_state()
        self._set_override_state(_OverrideState(name, current.revision + 1))
        self._invalidate_resolution()

    def entry_revision(self, kernel: str, name: str, device: str) -> int:
        """Return the monotonic revision of a registered implementation."""
        try:
            return self._entry_revisions[(kernel, device, name)]
        except KeyError as error:
            raise KeyError(
                f"No backend {name!r} for kernel {kernel!r} on {device!r}."
            ) from error

    revision = entry_revision

    def override_snapshot(self) -> BackendOverrideSnapshot:
        """Return the current context-local override identity."""
        state = self._override_state()
        return BackendOverrideSnapshot(state.name, state.revision)

    def snapshot(self) -> BackendRegistrySnapshot:
        """Return immutable registry state suitable for invalidation keys."""
        records: list[BackendEntrySnapshot] = []
        for (kernel, device), entries in sorted(self._entries.items()):
            statuses = self._observe_availability(kernel, device, entries)
            records.extend(
                BackendEntrySnapshot(
                    kernel=kernel,
                    device=device,
                    name=entry.name,
                    priority=entry.priority,
                    revision=entry.revision,
                    available=available,
                )
                for entry, available in zip(entries, statuses, strict=True)
            )
        state = self._override_state()
        return BackendRegistrySnapshot(
            registry_generation=self._registry_generation,
            override=state.name,
            override_revision=state.revision,
            entries=tuple(records),
        )

    def fingerprint(self) -> tuple:
        """Return a deterministic, hashable registry identity."""
        return self.snapshot().fingerprint

    def resolve_snapshot(self, kernel: str, device: str) -> BackendResolutionSnapshot:
        """Return immutable identity for the currently selected route."""
        entry = self._resolve(kernel, device)
        state = self._override_state()
        return BackendResolutionSnapshot(
            kernel=kernel,
            device=device,
            name=entry.name,
            revision=entry.revision,
            registry_generation=self._registry_generation,
            override=state.name,
            override_revision=state.revision,
        )

    def _override_state(self) -> _OverrideState:
        return self._override_context.get()

    def _set_override_state(self, state: _OverrideState) -> None:
        self._override_context.set(state)

    def _restore_override(self, state: _OverrideState) -> None:
        current = self._override_state()
        self._set_override_state(
            _OverrideState(state.name, max(current.revision, state.revision) + 1)
        )

    def _invalidate_resolution(self) -> None:
        self._resolved.clear()
        self._has.clear()

    def _observe_availability(
        self, kernel: str, device: str, entries: list[_Entry]
    ) -> tuple[bool, ...]:
        statuses: list[bool] = []
        changed = False
        for entry in entries:
            available = bool(entry.available())
            marker = (kernel, device, entry.name, entry.revision)
            previous = self._availability.get(marker)
            if previous is not None and previous != available:
                changed = True
            self._availability[marker] = available
            statuses.append(available)
        if changed:
            self._invalidate_resolution()
            self._registry_generation += 1
        return tuple(statuses)

    def _usable_entries(self, kernel: str, device: str) -> list[_Entry]:
        entries = self._entries.get((kernel, device), [])
        statuses = self._observe_availability(kernel, device, entries)
        return [
            entry
            for entry, available in zip(entries, statuses, strict=True)
            if available
        ]

    def _route_is_available(self, entry: _RouteEntry) -> bool:
        marker = (entry.spec.key, entry.device, entry.revision)
        available = bool(entry.available())
        previous = self._route_availability.get(marker)
        if previous is not None and previous != available:
            self._invalidate_resolution()
            self._registry_generation += 1
        self._route_availability[marker] = available
        return available

    def _usable_routes(
        self,
        algorithm: str,
        device: str,
        context: PlanningContext | None,
    ) -> list[_RouteEntry]:
        override = self.override
        candidates = [
            entry
            for entry in self._route_entries.values()
            if entry.device == device
            and entry.spec.algorithm == algorithm
            and (override is None or entry.spec.backend == override)
            and self._route_is_available(entry)
            and entry.spec.supports(context)
            and (
                not getattr(context, "requires_backward", False)
                or entry.spec.operator.supports_backward
            )
            and (
                not getattr(context, "compile", False)
                or entry.spec.operator.supports_compile
            )
            and (
                not getattr(context, "capture", False)
                or entry.spec.operator.supports_capture
            )
        ]
        return candidates
Attributes
generation property

Alias for :attr:registry_generation.

override property

Return the backend override active in the current context.

override_revision property

Return the current context-local override revision.

registry_generation property

Return the process-wide registry generation.

Methods:
available(kernel, device)

Names of the usable backends of kernel on device, best first.

Source code in btorch/sparse/runtime/backend.py
def available(self, kernel: str, device: str) -> list[str]:
    """Names of the usable backends of ``kernel`` on ``device``, best
    first."""
    return [entry.name for entry in self._usable_entries(kernel, device)]
bind_route(snapshot)

Bind exact callbacks for a previously selected route snapshot.

Source code in btorch/sparse/runtime/backend.py
def bind_route(self, snapshot: RouteResolutionSnapshot) -> RouteBinding:
    """Bind exact callbacks for a previously selected route snapshot."""
    if snapshot.registry_generation != self._registry_generation:
        raise RuntimeError(
            "The selected sparse route is stale; replan before binding it."
        )
    entry = self._route_entries.get((snapshot.key, snapshot.device))
    if entry is None or entry.revision != snapshot.revision:
        raise RuntimeError(
            f"Sparse route {snapshot.key!r} changed before it was bound."
        )
    if not self._route_is_available(entry):
        raise RuntimeError(
            f"Sparse route {snapshot.key!r} is unavailable on "
            f"{snapshot.device!r}."
        )
    callbacks: dict[str, Callable] = {}
    for kernel, backend in entry.spec.kernel_bindings:
        current = self._resolve_exact(kernel, snapshot.device, backend)
        expected = next(
            revision
            for name, name_backend, revision in snapshot.kernel_revisions
            if name == kernel and name_backend == backend
        )
        if current.revision != expected:
            raise RuntimeError(
                f"Sparse route {snapshot.key!r} changed its {kernel!r} "
                "implementation before it was bound."
            )
        callbacks[kernel] = current.fn
    return RouteBinding(snapshot, entry.spec.build(callbacks))
entry_revision(kernel, name, device)

Return the monotonic revision of a registered implementation.

Source code in btorch/sparse/runtime/backend.py
def entry_revision(self, kernel: str, name: str, device: str) -> int:
    """Return the monotonic revision of a registered implementation."""
    try:
        return self._entry_revisions[(kernel, device, name)]
    except KeyError as error:
        raise KeyError(
            f"No backend {name!r} for kernel {kernel!r} on {device!r}."
        ) from error
fingerprint()

Return a deterministic, hashable registry identity.

Source code in btorch/sparse/runtime/backend.py
def fingerprint(self) -> tuple:
    """Return a deterministic, hashable registry identity."""
    return self.snapshot().fingerprint
has(kernel, device)

Whether a backend of kernel is usable on device.

With a forced backend (:func:use_backend) only that backend counts.

Source code in btorch/sparse/runtime/backend.py
def has(self, kernel: str, device: str) -> bool:
    """Whether a backend of ``kernel`` is usable on ``device``.

    With a forced backend (:func:`use_backend`) only that backend counts.
    """
    override = self.override
    key = (kernel, device, override)
    known = self._has.get(key)
    if known is None:
        entries = self._usable_entries(kernel, device)
        if override is not None:
            # A forced backend that lacks this (optional) kernel means "no".
            known = any(entry.name == override for entry in entries)
        else:
            known = bool(entries)
        self._has[key] = known
    return known
has_route(algorithm, device, context=None)

Return whether a complete route supports context.

Source code in btorch/sparse/runtime/backend.py
def has_route(
    self,
    algorithm: str,
    device: str,
    context: PlanningContext | None = None,
) -> bool:
    """Return whether a complete route supports ``context``."""
    return bool(self._usable_routes(algorithm, device, context))
name(kernel, device)

Name of the backend :meth:resolve would pick.

Source code in btorch/sparse/runtime/backend.py
def name(self, kernel: str, device: str) -> str:
    """Name of the backend :meth:`resolve` would pick."""
    return self._resolve(kernel, device).name
override_snapshot()

Return the current context-local override identity.

Source code in btorch/sparse/runtime/backend.py
def override_snapshot(self) -> BackendOverrideSnapshot:
    """Return the current context-local override identity."""
    state = self._override_state()
    return BackendOverrideSnapshot(state.name, state.revision)
register(kernel, name, fn, *, device=('cpu', 'cuda'), priority=0, available=None)

Register fn as backend name of kernel.

Parameters:

Name Type Description Default
kernel str

Kernel name.

required
name str

Backend name ("aten", "triton", ...).

required
fn Callable

Implementation.

required
device str | tuple[str, ...]

Device type(s) the implementation supports.

('cpu', 'cuda')
priority int

Higher wins when several backends are available.

0
available Callable[[], bool] | None

Optional lazy availability check.

None
Source code in btorch/sparse/runtime/backend.py
def register(
    self,
    kernel: str,
    name: str,
    fn: Callable,
    *,
    device: str | tuple[str, ...] = ("cpu", "cuda"),
    priority: int = 0,
    available: Callable[[], bool] | None = None,
) -> None:
    """Register ``fn`` as backend ``name`` of ``kernel``.

    Args:
        kernel: Kernel name.
        name: Backend name (``"aten"``, ``"triton"``, ...).
        fn: Implementation.
        device: Device type(s) the implementation supports.
        priority: Higher wins when several backends are available.
        available: Optional lazy availability check.
    """
    devices = (device,) if isinstance(device, str) else device
    for dev in devices:
        entries = self._entries.setdefault((kernel, dev), [])
        entries[:] = [entry for entry in entries if entry.name != name]
        entry_key = (kernel, dev, name)
        revision = self._entry_revisions.get(entry_key, 0) + 1
        self._entry_revisions[entry_key] = revision
        self._availability = {
            key: value
            for key, value in self._availability.items()
            if key[:3] != entry_key
        }
        entries.append(
            _Entry(
                name,
                fn,
                priority,
                available or (lambda: True),
                revision,
            )
        )
        entries.sort(key=lambda entry: -entry.priority)
    self._invalidate_resolution()
    self._registry_generation += 1
register_route(spec, *, device=('cpu', 'cuda'), priority=0, available=None, replace=False)

Register one complete route candidate.

A route is deliberately separate from legacy kernel registrations: the latter remain independently usable by the public low-level ops, while planning only sees complete route contracts.

Source code in btorch/sparse/runtime/backend.py
def register_route(
    self,
    spec: RouteSpec,
    *,
    device: str | tuple[str, ...] = ("cpu", "cuda"),
    priority: int = 0,
    available: Callable[[], bool] | None = None,
    replace: bool = False,
) -> None:
    """Register one complete route candidate.

    A route is deliberately separate from legacy kernel registrations:
    the latter remain independently usable by the public low-level ops,
    while planning only sees complete route contracts.
    """
    devices = (device,) if isinstance(device, str) else device
    for dev in devices:
        key = (spec.key, dev)
        if key in self._route_entries and not replace:
            raise ValueError(
                f"Route {spec.key!r} is already registered for {dev!r}; "
                "use replace=True to replace it."
            )
        revision = self._route_revisions.get(key, 0) + 1
        self._route_revisions[key] = revision
        self._route_availability = {
            marker: value
            for marker, value in self._route_availability.items()
            if marker[:2] != key
        }
        self._route_entries[key] = _RouteEntry(
            spec=spec,
            device=dev,
            priority=priority,
            available=available or (lambda: True),
            revision=revision,
        )
    self._invalidate_resolution()
    self._registry_generation += 1
resolve(kernel, device)

Return the implementation to use for kernel on device.

Source code in btorch/sparse/runtime/backend.py
def resolve(self, kernel: str, device: str) -> Callable:
    """Return the implementation to use for ``kernel`` on ``device``."""
    return self._resolve(kernel, device).fn
resolve_route(algorithm, device, context=None)

Select one complete route and return only its immutable identity.

Source code in btorch/sparse/runtime/backend.py
def resolve_route(
    self,
    algorithm: str,
    device: str,
    context: PlanningContext | None = None,
) -> RouteResolutionSnapshot:
    """Select one complete route and return only its immutable identity."""
    candidates = self._usable_routes(algorithm, device, context)
    if not candidates:
        raise RuntimeError(f"No route for algorithm {algorithm!r} on {device!r}.")
    override = self.override
    if override is not None:
        forced = [entry for entry in candidates if entry.spec.backend == override]
        if forced:
            candidates = forced
    chosen = min(
        candidates,
        key=lambda entry: (
            -entry.priority,
            entry.spec.estimate_cost(context),
            entry.spec.key,
        ),
    )
    state = self._override_state()
    kernel_revisions = tuple(
        (kernel, backend, self.entry_revision(kernel, backend, device))
        for kernel, backend in chosen.spec.kernel_bindings
    )
    return RouteResolutionSnapshot(
        key=chosen.spec.key,
        algorithm=chosen.spec.algorithm,
        backend=chosen.spec.backend,
        device=device,
        revision=chosen.revision,
        registry_generation=self._registry_generation,
        override=state.name,
        override_revision=state.revision,
        kernel_revisions=kernel_revisions,
    )
resolve_snapshot(kernel, device)

Return immutable identity for the currently selected route.

Source code in btorch/sparse/runtime/backend.py
def resolve_snapshot(self, kernel: str, device: str) -> BackendResolutionSnapshot:
    """Return immutable identity for the currently selected route."""
    entry = self._resolve(kernel, device)
    state = self._override_state()
    return BackendResolutionSnapshot(
        kernel=kernel,
        device=device,
        name=entry.name,
        revision=entry.revision,
        registry_generation=self._registry_generation,
        override=state.name,
        override_revision=state.revision,
    )
route_revision(key, device)

Return the revision of a registered route.

Source code in btorch/sparse/runtime/backend.py
def route_revision(self, key: RouteKey, device: str) -> int:
    """Return the revision of a registered route."""
    try:
        return self._route_revisions[(key, device)]
    except KeyError as error:
        raise KeyError(f"No route {key!r} for device {device!r}.") from error
set_backend(name)

Force backend name in the current context (None: auto).

Raises:

Type Description
ValueError

If no kernel has a backend called name.

Source code in btorch/sparse/runtime/backend.py
def set_backend(self, name: str | None) -> None:
    """Force backend ``name`` in the current context (``None``: auto).

    Raises:
        ValueError: If no kernel has a backend called ``name``.
    """
    known = {entry.name for entries in self._entries.values() for entry in entries}
    if name is not None and name not in known:
        raise ValueError(
            f"Unknown backend {name!r}; registered backends: {sorted(known)}."
        )
    current = self._override_state()
    self._set_override_state(_OverrideState(name, current.revision + 1))
    self._invalidate_resolution()
snapshot()

Return immutable registry state suitable for invalidation keys.

Source code in btorch/sparse/runtime/backend.py
def snapshot(self) -> BackendRegistrySnapshot:
    """Return immutable registry state suitable for invalidation keys."""
    records: list[BackendEntrySnapshot] = []
    for (kernel, device), entries in sorted(self._entries.items()):
        statuses = self._observe_availability(kernel, device, entries)
        records.extend(
            BackendEntrySnapshot(
                kernel=kernel,
                device=device,
                name=entry.name,
                priority=entry.priority,
                revision=entry.revision,
                available=available,
            )
            for entry, available in zip(entries, statuses, strict=True)
        )
    state = self._override_state()
    return BackendRegistrySnapshot(
        registry_generation=self._registry_generation,
        override=state.name,
        override_revision=state.revision,
        entries=tuple(records),
    )

KernelCache

Memo for expensive backend artefacts (compiled kernels, workspaces).

Entries are keyed by an arbitrary hashable (kernel name, dtype, block size, ...). Nothing in here is model state; it is never serialised.

Source code in btorch/sparse/runtime/backend.py
class KernelCache:
    """Memo for expensive backend artefacts (compiled kernels, workspaces).

    Entries are keyed by an arbitrary hashable (kernel name, dtype, block
    size, ...). Nothing in here is model state; it is never serialised.
    """

    def __init__(self) -> None:
        self._store: dict = {}
        self._generation = 0

    @property
    def generation(self) -> int:
        """Return a counter advanced whenever all artefacts are discarded."""
        return self._generation

    def get(self, key, build: Callable):
        """Return the cached artefact for ``key``, building it on a miss."""
        try:
            return self._store[key]
        except KeyError:
            value = self._store[key] = build()
            return value

    def clear(self) -> None:
        self._store.clear()
        self._generation += 1

    def __len__(self) -> int:
        return len(self._store)
Attributes
generation property

Return a counter advanced whenever all artefacts are discarded.

Methods:
get(key, build)

Return the cached artefact for key, building it on a miss.

Source code in btorch/sparse/runtime/backend.py
def get(self, key, build: Callable):
    """Return the cached artefact for ``key``, building it on a miss."""
    try:
        return self._store[key]
    except KeyError:
        value = self._store[key] = build()
        return value

Planner

Choose representation, algorithm and backend for a propagation.

The planner only consults cheap, static information: device, batching and the user's :class:~btorch.sparse.Hints. Today it decides one thing, the algorithm:

  • "pull": destination-driven product (deterministic).
  • "push": source-driven with compaction on the device (Triton on CUDA). It is taken whenever the density hint is at or below the limit, whatever the density of an individual input turns out to be; it accumulates with floating-point atomics, so it is not bitwise reproducible and is not planned when deterministic algorithms are requested.
  • "adaptive-push": source-driven with host-side packing (reference backend); each call falls back to pull above the density limit.

Parameters:

Name Type Description Default
push_max_density dict[str, float] | None

Per device type, the largest expected input density for which source-driven propagation is planned. Above it (or without a density hint) the destination-driven product is used, which is deterministic and free of data-dependent control flow.

None
Source code in btorch/sparse/runtime/planner.py
class Planner:
    """Choose representation, algorithm and backend for a propagation.

    The planner only consults cheap, static information: device, batching and
    the user's :class:`~btorch.sparse.Hints`. Today it decides one thing, the
    algorithm:

    - ``"pull"``: destination-driven product (deterministic).
    - ``"push"``: source-driven with compaction on the device (Triton on
      CUDA). It is taken whenever the density hint is at or below the limit,
      whatever the density of an individual input turns out to be; it
      accumulates with floating-point atomics, so it is not bitwise
      reproducible and is not planned when deterministic algorithms are
      requested.
    - ``"adaptive-push"``: source-driven with host-side packing (reference
      backend); each call falls back to pull above the density limit.

    Args:
        push_max_density: Per device type, the largest expected input density
            for which source-driven propagation is planned. Above it (or
            without a density hint) the destination-driven product is used,
            which is deterministic and free of data-dependent control flow.
    """

    def __init__(self, push_max_density: dict[str, float] | None = None):
        # Measured crossovers (RTX 5090, heavy-tailed graphs of 4k-1M neurons,
        # batch 1-32): the device-compacting push beats the Triton pull below
        # 1.5-5% density once B * N is large, and never at ~4k neurons with
        # one sample. On CPU the ATen push only wins below ~0.2-0.5% density.
        self.push_max_density = push_max_density or {"cpu": 0.002, "cuda": 0.02}

    def plan(
        self,
        *,
        device: str,
        value_batched: bool,
        hints: Hints,
        dtype: torch.dtype,
    ) -> _Plan:
        limit = self.push_max_density.get(device, 0.0)
        density = hints.expected_density
        deterministic = torch.are_deterministic_algorithms_enabled()
        context = PlanningContext(
            device=device,
            value_batched=value_batched,
            expected_density=density,
            deterministic=deterministic,
            dtype=dtype,
        )
        if value_batched:
            algorithm, reason = "pull", "shared-pattern batch of values"
        elif density is None:
            algorithm, reason = "pull", "no expected_density hint"
        elif density > limit:
            algorithm, reason = "pull", f"expected_density {density:g} > {limit:g}"
        else:
            algorithm = "push"
            if not registry.has_route(algorithm, device, context):
                algorithm = (
                    "pull"
                    if device == "cuda" and registry.override is None
                    else "adaptive-push"
                )
                if not registry.has_route(algorithm, device, context):
                    algorithm = "pull"
            if device == "cuda" and algorithm != "pull" and deterministic:
                # CUDA source-driven routes accumulate with floating-point
                # atomics, including ATen's adaptive reference route.
                algorithm = "pull"
                reason = "deterministic algorithms requested"
            else:
                reason = f"expected_density {density:g} <= {limit:g}"
        if algorithm == "pull":
            context = PlanningContext(
                device=device,
                value_batched=value_batched,
                expected_density=density,
                deterministic=deterministic,
                dtype=dtype,
            )
        route = registry.resolve_route(algorithm, device, context)
        return _Plan(
            representation="destination CSR + source CSR",
            algorithm=algorithm,
            backend=route.backend,
            route=route,
            deterministic=deterministic,
            max_density=limit if algorithm != "pull" else 0.0,
            reason=reason,
        )

RepresentationCache

Bases: Module

Execution structures derived from canonical edge lists.

The canonical model state of a connection is its edge list in slot order. Kernels need compressed layouts, which this cache derives:

  • crow, col: destination-major CSR (pull / batched products).
  • perm: slot of every CSR entry (values_csr = values[perm]).
  • t_crow, t_col, t_perm: source-major CSR of the same edges (push, and the transposed product of the input gradient); t_perm is the CSR position of every source-major entry.

All of them are non-persistent buffers: they follow .to() with the owning module, never enter a state_dict, and are rebuilt from the canonical buffers whenever the topology changes. Rebuilding writes into the existing tensors when the number of edges is unchanged, so compiled graphs that captured them stay valid. A backend may keep derived copies of its own (the Triton pull kernels rebuild theirs when the pattern changes), so a CUDA graph captured before rewiring must be captured again. Rebuild at the optimizer boundary, never between a forward pass and its backward.

Source code in btorch/sparse/runtime/cache.py
class RepresentationCache(nn.Module):
    """Execution structures derived from canonical edge lists.

    The canonical model state of a connection is its edge list in *slot*
    order. Kernels need compressed layouts, which this cache derives:

    - ``crow``, ``col``: destination-major CSR (pull / batched products).
    - ``perm``: slot of every CSR entry (``values_csr = values[perm]``).
    - ``t_crow``, ``t_col``, ``t_perm``: source-major CSR of the same edges
      (push, and the transposed product of the input gradient); ``t_perm`` is
      the CSR position of every source-major entry.

    All of them are non-persistent buffers: they follow ``.to()`` with the
    owning module, never enter a ``state_dict``, and are rebuilt from the
    canonical buffers whenever the topology changes. Rebuilding writes into
    the existing tensors when the number of edges is unchanged, so compiled
    graphs that captured them stay valid. A backend may keep derived copies of
    its own (the Triton pull kernels rebuild theirs when the pattern
    changes), so a CUDA graph captured before rewiring must be captured
    again. Rebuild at the optimizer boundary, never between a forward pass
    and its backward.
    """

    crow: Tensor
    col: Tensor
    perm: Tensor
    t_crow: Tensor
    t_col: Tensor
    t_perm: Tensor

    _NAMES = ("crow", "col", "perm", "t_crow", "t_col", "t_perm")

    def __init__(self) -> None:
        super().__init__()
        for name in self._NAMES:
            self.register_buffer(name, torch.empty(0, dtype=torch.long), False)
        self.topology_version = -1
        self.identity_perm = True
        self.shape = (0, 0)

    @torch.no_grad()
    def build(self, row: Tensor, col: Tensor, shape: tuple[int, int], version: int):
        """(Re)build every representation.

        Args:
            row: ``[E]`` destination (output index) of each slot.
            col: ``[E]`` source (input index) of each slot.
            shape: ``(n_out, n_in)``.
            version: Topology version the structures correspond to.
        """
        n_out, n_in = shape
        # int64 so the linearised key cannot overflow for int32 inputs.
        row, col = row.long(), col.long()
        key = row * n_in + col
        if key.shape[0] > 1 and bool((key[1:] < key[:-1]).any()):
            perm = torch.argsort(key, stable=True)
            identity = False
        else:
            perm = torch.arange(key.shape[0], device=key.device)
            identity = True
        row_s, col_s = row[perm], col[perm]
        crow = self._pointer(row_s, n_out)
        t_perm = torch.argsort(col_s * n_out + row_s, stable=True)
        new = {
            "crow": crow,
            "col": col_s,
            "perm": perm,
            "t_crow": self._pointer(col_s[t_perm], n_in),
            "t_col": row_s[t_perm],
            "t_perm": t_perm,
        }
        for name, value in new.items():
            current = getattr(self, name)
            if current.shape == value.shape and current.device == value.device:
                current.copy_(value)
            else:
                setattr(self, name, value)
        self.identity_perm = identity
        self.shape = (n_out, n_in)
        self.topology_version = version

    def crow_rows(self) -> Tensor:
        """``[E]`` output index of every CSR entry (expanded ``crow``)."""
        counts = self.crow[1:] - self.crow[:-1]
        return torch.repeat_interleave(
            torch.arange(counts.shape[0], device=counts.device), counts
        )

    @staticmethod
    def _pointer(sorted_index: Tensor, n: int) -> Tensor:
        pointer = torch.zeros(n + 1, dtype=torch.long, device=sorted_index.device)
        pointer[1:] = torch.cumsum(torch.bincount(sorted_index, minlength=n), 0)
        return pointer

    def extra_repr(self) -> str:
        return (
            f"shape={self.shape}, nnz={self.col.shape[0]}, "
            f"topology_version={self.topology_version}"
        )
Methods:
build(row, col, shape, version)

(Re)build every representation.

Parameters:

Name Type Description Default
row Tensor

[E] destination (output index) of each slot.

required
col Tensor

[E] source (input index) of each slot.

required
shape tuple[int, int]

(n_out, n_in).

required
version int

Topology version the structures correspond to.

required
Source code in btorch/sparse/runtime/cache.py
@torch.no_grad()
def build(self, row: Tensor, col: Tensor, shape: tuple[int, int], version: int):
    """(Re)build every representation.

    Args:
        row: ``[E]`` destination (output index) of each slot.
        col: ``[E]`` source (input index) of each slot.
        shape: ``(n_out, n_in)``.
        version: Topology version the structures correspond to.
    """
    n_out, n_in = shape
    # int64 so the linearised key cannot overflow for int32 inputs.
    row, col = row.long(), col.long()
    key = row * n_in + col
    if key.shape[0] > 1 and bool((key[1:] < key[:-1]).any()):
        perm = torch.argsort(key, stable=True)
        identity = False
    else:
        perm = torch.arange(key.shape[0], device=key.device)
        identity = True
    row_s, col_s = row[perm], col[perm]
    crow = self._pointer(row_s, n_out)
    t_perm = torch.argsort(col_s * n_out + row_s, stable=True)
    new = {
        "crow": crow,
        "col": col_s,
        "perm": perm,
        "t_crow": self._pointer(col_s[t_perm], n_in),
        "t_col": row_s[t_perm],
        "t_perm": t_perm,
    }
    for name, value in new.items():
        current = getattr(self, name)
        if current.shape == value.shape and current.device == value.device:
            current.copy_(value)
        else:
            setattr(self, name, value)
    self.identity_perm = identity
    self.shape = (n_out, n_in)
    self.topology_version = version
crow_rows()

[E] output index of every CSR entry (expanded crow).

Source code in btorch/sparse/runtime/cache.py
def crow_rows(self) -> Tensor:
    """``[E]`` output index of every CSR entry (expanded ``crow``)."""
    counts = self.crow[1:] - self.crow[:-1]
    return torch.repeat_interleave(
        torch.arange(counts.shape[0], device=counts.device), counts
    )

Functions:

csr_propagate(crow, col, values, x, t_crow, t_col, t_perm)

Destination-driven sparse propagation y = A @ x along the last axis.

Parameters:

Name Type Description Default
crow Tensor

[M + 1] row pointers of the destination-major CSR.

required
col Tensor

[E] source index of each entry.

required
values Tensor

[*vb, E] entry values in CSR order (differentiable).

required
x Tensor

[*vb, *sample, N] dense input (differentiable).

required
t_crow Tensor

[N + 1] pointers of the source-major CSR.

required
t_col Tensor

[E] destination index of each source-major entry.

required
t_perm Tensor

[E] CSR position of each source-major entry.

required

Returns:

Type Description
Tensor

[*vb, *sample, M].

Source code in btorch/sparse/runtime/ops.py
@custom_op("btorch::csr_propagate", mutates_args=())
def csr_propagate(
    crow: Tensor,
    col: Tensor,
    values: Tensor,
    x: Tensor,
    t_crow: Tensor,
    t_col: Tensor,
    t_perm: Tensor,
) -> Tensor:
    """Destination-driven sparse propagation ``y = A @ x`` along the last axis.

    Args:
        crow: ``[M + 1]`` row pointers of the destination-major CSR.
        col: ``[E]`` source index of each entry.
        values: ``[*vb, E]`` entry values in CSR order (differentiable).
        x: ``[*vb, *sample, N]`` dense input (differentiable).
        t_crow: ``[N + 1]`` pointers of the source-major CSR.
        t_col: ``[E]`` destination index of each source-major entry.
        t_perm: ``[E]`` CSR position of each source-major entry.

    Returns:
        ``[*vb, *sample, M]``.
    """
    return _pull(crow, col, values, x)

pack_spikes(x)

Pack the non-zero entries of a dense spike tensor [B, N].

The packed indices are an execution aid only: the dense tensor remains the logical (and differentiable) spike representation.

Returns:

Type Description
Tensor

(active_idx, ptr); sample b owns

Tensor

active_idx[ptr[b]:ptr[b + 1]].

Source code in btorch/sparse/runtime/ops.py
def pack_spikes(x: Tensor) -> tuple[Tensor, Tensor]:
    """Pack the non-zero entries of a dense spike tensor ``[B, N]``.

    The packed indices are an execution aid only: the dense tensor remains
    the logical (and differentiable) spike representation.

    Returns:
        ``(active_idx, ptr)``; sample ``b`` owns
        ``active_idx[ptr[b]:ptr[b + 1]]``.
    """
    return kernels_aten.pack_spikes(x)

propagate(crow, col, values, x, t_crow, t_col, t_perm, max_density=None, task_values=None)

Sparse propagation y = A @ x; the entry point connections call.

Under torch.compile this is one registered operator (:func:csr_propagate, or :func:spike_propagate when max_density is given). In eager mode the same kernels run through a lighter autograd node. Results and gradients are identical on both routes.

Parameters:

Name Type Description Default
crow Tensor

[M + 1] row pointers of the destination-major CSR.

required
col Tensor

[E] source index of each entry.

required
values Tensor

[*vb, E] entry values in CSR order.

required
x Tensor

[*vb, *sample, N] dense input.

required
t_crow Tensor

[N + 1] pointers of the source-major CSR.

required
t_col Tensor

[E] destination index of each source-major entry.

required
t_perm Tensor

[E] CSR position of each source-major entry.

required
max_density float | None

None for destination-driven propagation; a density limit to use the source-driven path for sparse activity.

None

Returns:

Type Description
Tensor

[*vb, *sample, M].

Source code in btorch/sparse/runtime/ops.py
def propagate(
    crow: Tensor,
    col: Tensor,
    values: Tensor,
    x: Tensor,
    t_crow: Tensor,
    t_col: Tensor,
    t_perm: Tensor,
    max_density: float | None = None,
    task_values: Tensor | None = None,
) -> Tensor:
    """Sparse propagation ``y = A @ x``; the entry point connections call.

    Under ``torch.compile`` this is one registered operator
    (:func:`csr_propagate`, or :func:`spike_propagate` when ``max_density``
    is given). In eager mode the same kernels run through a lighter autograd
    node. Results and gradients are identical on both routes.

    Args:
        crow: ``[M + 1]`` row pointers of the destination-major CSR.
        col: ``[E]`` source index of each entry.
        values: ``[*vb, E]`` entry values in CSR order.
        x: ``[*vb, *sample, N]`` dense input.
        t_crow: ``[N + 1]`` pointers of the source-major CSR.
        t_col: ``[E]`` destination index of each source-major entry.
        t_perm: ``[E]`` CSR position of each source-major entry.
        max_density: ``None`` for destination-driven propagation; a density
            limit to use the source-driven path for sparse activity.

    Returns:
        ``[*vb, *sample, M]``.
    """
    if torch.compiler.is_compiling():
        if max_density is None:
            return csr_propagate(crow, col, values, x, t_crow, t_col, t_perm)
        prepared = values.new_empty(0) if task_values is None else task_values
        return spike_propagate(
            crow,
            col,
            values,
            x,
            t_crow,
            t_col,
            t_perm,
            max_density,
            prepared,
        )
    return _propagate_eager(
        crow, col, values, x, t_crow, t_col, t_perm, max_density, task_values
    )

spike_propagate(crow, col, values, x, t_crow, t_col, t_perm, max_density, task_values=None)

Sparse propagation that exploits sparse activity in x.

Mathematically identical to :func:csr_propagate. The forward visits only the out-edges of active sources. With a backend that compacts the input on the device (Triton on CUDA) this is a single launch without host synchronisation. The reference path packs the non-zero entries on the host side and falls back to the destination-driven product when the input density exceeds max_density. The backward is the same dense one, so gradients w.r.t. x are exact for every entry, including the silent ones.

Parameters:

Name Type Description Default
crow Tensor

[M + 1] row pointers of the destination-major CSR.

required
col Tensor

[E] source index of each entry.

required
values Tensor

[E] entry values in CSR order (differentiable).

required
x Tensor

[*sample, N] dense input (differentiable).

required
t_crow Tensor

[N + 1] pointers of the source-major CSR.

required
t_col Tensor

[E] destination index of each source-major entry.

required
t_perm Tensor

[E] CSR position of each source-major entry.

required
max_density float

Largest non-zero fraction of x handled by the host-packed source-driven path.

required

Returns:

Type Description
Tensor

[*sample, M].

Source code in btorch/sparse/runtime/ops.py
@custom_op("btorch::spike_propagate", mutates_args=())
def spike_propagate(
    crow: Tensor,
    col: Tensor,
    values: Tensor,
    x: Tensor,
    t_crow: Tensor,
    t_col: Tensor,
    t_perm: Tensor,
    max_density: float,
    task_values: Tensor | None = None,
) -> Tensor:
    """Sparse propagation that exploits sparse activity in ``x``.

    Mathematically identical to :func:`csr_propagate`. The forward visits
    only the out-edges of active sources. With a backend that compacts the
    input on the device (Triton on CUDA) this is a single launch without host
    synchronisation. The reference path packs the non-zero entries on the
    host side and falls back to the destination-driven product when the input
    density exceeds ``max_density``. The backward is the same dense one, so
    gradients w.r.t. ``x`` are exact for every entry, including the silent
    ones.

    Args:
        crow: ``[M + 1]`` row pointers of the destination-major CSR.
        col: ``[E]`` source index of each entry.
        values: ``[E]`` entry values in CSR order (differentiable).
        x: ``[*sample, N]`` dense input (differentiable).
        t_crow: ``[N + 1]`` pointers of the source-major CSR.
        t_col: ``[E]`` destination index of each source-major entry.
        t_perm: ``[E]`` CSR position of each source-major entry.
        max_density: Largest non-zero fraction of ``x`` handled by the
            host-packed source-driven path.

    Returns:
        ``[*sample, M]``.
    """
    prepared = None if task_values is None or task_values.numel() == 0 else task_values
    return _push_or_pull(
        crow, col, values, x, t_crow, t_col, t_perm, max_density, prepared
    )

use_backend(name)

Temporarily force a kernel backend in the current context.

Examples:

>>> from btorch.sparse import runtime
>>> with runtime.use_backend("aten"):
...     y = conn(x)
Source code in btorch/sparse/runtime/backend.py
@contextmanager
def use_backend(name: str | None) -> Iterator[None]:
    """Temporarily force a kernel backend in the current context.

    Examples:
        >>> from btorch.sparse import runtime
        >>> with runtime.use_backend("aten"):      # doctest: +SKIP
        ...     y = conn(x)
    """
    previous = registry._override_state()
    registry.set_backend(name)
    try:
        yield
    finally:
        registry._restore_override(previous)
        registry._invalidate_resolution()