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:
valueshas 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
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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: |
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
indices()
¶
sum_duplicates()
¶
tocsc(return_map=False)
¶
Convert to canonical CSC (column-major, duplicates summed).
tocsr(return_map=False)
¶
Convert to canonical CSR (sorted, duplicates summed).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
return_map
|
bool
|
Also return the :class: |
False
|
Source code in btorch/sparse/coo.py
CSC
¶
Bases: _Compressed
Compressed sparse column format (exactly two sparse dimensions).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pointer
|
Tensor
|
|
required |
minor
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
|
Source code in btorch/sparse/csr.py
Methods:¶
ccol_indices()
¶
coalesce(return_map=False)
¶
col_indices()
¶
row_indices()
¶
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
transpose()
¶
Transpose without copying: the same arrays read as CSR.
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
|
|
required |
minor
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
Methods:¶
coalesce(return_map=False)
¶
col_indices()
¶
crow_indices()
¶
row_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
transpose()
¶
Transpose without copying: the same arrays read as CSC.
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
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
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]
|
|
required |
value
|
Tensor | float
|
Scalar weight: a Python number or a 0-dim tensor (for example
an |
1.0
|
dtype
|
dtype | None
|
Dtype used when |
None
|
device
|
device | str | None
|
Device used when |
None
|
Examples:
Source code in btorch/sparse/operator.py
DiagonalOperator
¶
Bases: StructuredOperator
One-to-one operator: A = diag(d), y = d * x.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
diag
|
Tensor
|
|
required |
Examples:
Source code in btorch/sparse/operator.py
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
|
|
required |
n_new
|
int
|
Number of entries after the change. |
required |
Source code in btorch/sparse/properties.py
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 | |
Attributes¶
is_permutation
property
¶
Whether no entries were merged.
Methods:¶
compose(then)
¶
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
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 |
required |
dim
|
int
|
Edge axis. |
-1
|
Source code in btorch/sparse/properties.py
take(meta, dim=0, check=True)
¶
Move categorical metadata (group, receptor, delay ids).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
meta
|
Tensor
|
Tensor whose axis |
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 |
Source code in btorch/sparse/properties.py
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
|
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
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]
|
|
required |
matvec
|
Callable[[Tensor], Tensor]
|
|
required |
rmatvec
|
Callable[[Tensor], Tensor] | None
|
Optional transpose apply |
None
|
enumerate_edges
|
Callable[[], Edges] | None
|
Optional callable without arguments returning
|
None
|
dtype
|
dtype | None
|
Optional dtype, used by :meth: |
None
|
device
|
device | str | None
|
Optional device, used by :meth: |
None
|
matmat
|
Callable[[Tensor], Tensor] | None
|
Optional |
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
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 | |
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 @ Bwith another operator or aSparse: :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
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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
materialize(format=None)
¶
Build an explicit :class:~btorch.sparse.Sparse with these entries.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
format
|
str | None
|
Optional |
None
|
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
If the operator cannot list its entries
(capability |
Source code in btorch/sparse/operator.py
matmat(x)
¶
A @ X for X [..., N, K], returning [..., M, K].
Source code in btorch/sparse/operator.py
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
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
supports(name)
¶
Whether the optional capability name is available.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
One of :data: |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in btorch/sparse/operator.py
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
tocoo()
¶
tocsc()
¶
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
|
|
required |
V
|
Tensor
|
|
required |
Source code in btorch/sparse/operator.py
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
|
required |
Source code in btorch/sparse/operator.py
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 |
False
|
structurally_symmetric
|
bool
|
The sparsity pattern is symmetric. |
False
|
triangular
|
str | 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
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 |
required |
Source code in btorch/sparse/operator.py
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
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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)
¶
as_coo()
¶
as_csc()
¶
as_csr()
¶
batch_dim()
¶
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
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
matvec(x)
¶
Apply the operator along the last axis of x.
See :func:btorch.sparse.matvec.
rmatvec(x)
¶
sparse_dim()
¶
to(*args, **kwargs)
¶
Move to a device and/or cast the values (indices stay integer).
Source code in btorch/sparse/base.py
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
|
|
{}
|
Source code in btorch/sparse/base.py
to_torch(layout=None, **kwargs)
¶
Export as a torch sparse tensor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
layout
|
str | layout | None
|
|
None
|
**kwargs
|
Any
|
|
{}
|
Source code in btorch/sparse/base.py
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
tocoo()
¶
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
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
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
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
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
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
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 ( |
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: |
0
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Sparse
|
class: |
Raises:
| Type | Description |
|---|---|
TypeError
|
For dense tensors, arrays and unsupported types; dense data is never sparsified implicitly. |
Source code in btorch/sparse/conversion.py
csc(ccol_indices, row_indices, values, shape, *, dense_dim=0)
¶
Create a CSC array; see :class:CSC.
Source code in btorch/sparse/__init__.py
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: |
required |
x
|
Tensor | None
|
Optional example input. |
None
|
Source code in btorch/sparse/__init__.py
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
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
|
|
required |
cols
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
shape
|
Sequence[int]
|
|
required |
dense_dim
|
int
|
Number of trailing dense dimensions of each entry. |
0
|
Source code in btorch/sparse/__init__.py
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
|
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
Source code in btorch/sparse/conversion.py
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 |
0
|
Returns:
| Type | Description |
|---|---|
Sparse
|
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
Source code in btorch/sparse/conversion.py
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | |
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
matmul(a, b)
¶
Matrix product with one sparse operand; the function behind @.
Shapes follow :func:torch.matmul:
A @ xwith 1-Dxof lengthNreturns lengthM.A @ XwithX.shape == (..., N, K)returns(..., M, K).x @ Awith 1-Dxof lengthMreturns lengthN.X @ AwithX.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
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 |
required |
Returns:
| Type | Description |
|---|---|
Tensor
|
Dense tensor. |
Raises:
| Type | Description |
|---|---|
ValueError
|
On a shape mismatch, or if |
Source code in btorch/sparse/ops.py
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
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 |
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
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:
valueshas 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
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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: |
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
indices()
¶
sum_duplicates()
¶
tocsc(return_map=False)
¶
Convert to canonical CSC (column-major, duplicates summed).
tocsr(return_map=False)
¶
Convert to canonical CSR (sorted, duplicates summed).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
return_map
|
bool
|
Also return the :class: |
False
|
Source code in btorch/sparse/coo.py
CSC
¶
Bases: _Compressed
Compressed sparse column format (exactly two sparse dimensions).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pointer
|
Tensor
|
|
required |
minor
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
|
Source code in btorch/sparse/csr.py
Methods:¶
ccol_indices()
¶
coalesce(return_map=False)
¶
col_indices()
¶
row_indices()
¶
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
transpose()
¶
Transpose without copying: the same arrays read as CSR.
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
|
|
required |
minor
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
Methods:¶
coalesce(return_map=False)
¶
col_indices()
¶
crow_indices()
¶
row_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
transpose()
¶
Transpose without copying: the same arrays read as CSC.
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
|
|
required |
n_new
|
int
|
Number of entries after the change. |
required |
Source code in btorch/sparse/properties.py
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 | |
Attributes¶
is_permutation
property
¶
Whether no entries were merged.
Methods:¶
compose(then)
¶
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
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 |
required |
dim
|
int
|
Edge axis. |
-1
|
Source code in btorch/sparse/properties.py
take(meta, dim=0, check=True)
¶
Move categorical metadata (group, receptor, delay ids).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
meta
|
Tensor
|
Tensor whose axis |
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 |
Source code in btorch/sparse/properties.py
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
|
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
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 @ Bwith another operator or aSparse: :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
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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
materialize(format=None)
¶
Build an explicit :class:~btorch.sparse.Sparse with these entries.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
format
|
str | None
|
Optional |
None
|
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
If the operator cannot list its entries
(capability |
Source code in btorch/sparse/operator.py
matmat(x)
¶
A @ X for X [..., N, K], returning [..., M, K].
Source code in btorch/sparse/operator.py
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
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
supports(name)
¶
Whether the optional capability name is available.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
One of :data: |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in btorch/sparse/operator.py
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
tocoo()
¶
tocsc()
¶
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 |
False
|
structurally_symmetric
|
bool
|
The sparsity pattern is symmetric. |
False
|
triangular
|
str | 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
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
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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)
¶
as_coo()
¶
as_csc()
¶
as_csr()
¶
batch_dim()
¶
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
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
matvec(x)
¶
Apply the operator along the last axis of x.
See :func:btorch.sparse.matvec.
rmatvec(x)
¶
sparse_dim()
¶
to(*args, **kwargs)
¶
Move to a device and/or cast the values (indices stay integer).
Source code in btorch/sparse/base.py
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
|
|
{}
|
Source code in btorch/sparse/base.py
to_torch(layout=None, **kwargs)
¶
Export as a torch sparse tensor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
layout
|
str | layout | None
|
|
None
|
**kwargs
|
Any
|
|
{}
|
Source code in btorch/sparse/base.py
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
tocoo()
¶
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
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
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
Functions:¶
_as_tensor(x, *, dtype=None, device=None)
¶
_check_index(name, index)
¶
Source code in btorch/sparse/base.py
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:
valueshas 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
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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: |
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
indices()
¶
sum_duplicates()
¶
tocsc(return_map=False)
¶
Convert to canonical CSC (column-major, duplicates summed).
tocsr(return_map=False)
¶
Convert to canonical CSR (sorted, duplicates summed).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
return_map
|
bool
|
Also return the :class: |
False
|
Source code in btorch/sparse/coo.py
CSC
¶
Bases: _Compressed
Compressed sparse column format (exactly two sparse dimensions).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pointer
|
Tensor
|
|
required |
minor
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
|
Source code in btorch/sparse/csr.py
Methods:¶
ccol_indices()
¶
coalesce(return_map=False)
¶
col_indices()
¶
row_indices()
¶
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
transpose()
¶
Transpose without copying: the same arrays read as CSR.
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
|
|
required |
minor
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
Methods:¶
coalesce(return_map=False)
¶
col_indices()
¶
crow_indices()
¶
row_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
transpose()
¶
Transpose without copying: the same arrays read as CSC.
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 |
False
|
structurally_symmetric
|
bool
|
The sparsity pattern is symmetric. |
False
|
triangular
|
str | 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
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
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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)
¶
as_coo()
¶
as_csc()
¶
as_csr()
¶
batch_dim()
¶
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
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
matvec(x)
¶
Apply the operator along the last axis of x.
See :func:btorch.sparse.matvec.
rmatvec(x)
¶
sparse_dim()
¶
to(*args, **kwargs)
¶
Move to a device and/or cast the values (indices stay integer).
Source code in btorch/sparse/base.py
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
|
|
{}
|
Source code in btorch/sparse/base.py
to_torch(layout=None, **kwargs)
¶
Export as a torch sparse tensor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
layout
|
str | layout | None
|
|
None
|
**kwargs
|
Any
|
|
{}
|
Source code in btorch/sparse/base.py
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
tocoo()
¶
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
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
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
Functions:¶
_expand_batch_coo(A)
¶
Indices/values of a torch COO tensor with explicit batch coordinates.
Source code in btorch/sparse/conversion.py
_is_scipy_sparse(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 ( |
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: |
0
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Sparse
|
class: |
Raises:
| Type | Description |
|---|---|
TypeError
|
For dense tensors, arrays and unsupported types; dense data is never sparsified implicitly. |
Source code in btorch/sparse/conversion.py
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
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
|
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
Source code in btorch/sparse/conversion.py
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 |
0
|
Returns:
| Type | Description |
|---|---|
Sparse
|
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
Source code in btorch/sparse/conversion.py
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | |
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 |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in btorch/sparse/conversion.py
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 |
None
|
Returns:
| Type | Description |
|---|---|
Tensor
|
Sparse tensor with |
Tensor
|
history. |
Source code in btorch/sparse/conversion.py
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:
valueshas 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
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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: |
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
indices()
¶
sum_duplicates()
¶
tocsc(return_map=False)
¶
Convert to canonical CSC (column-major, duplicates summed).
tocsr(return_map=False)
¶
Convert to canonical CSR (sorted, duplicates summed).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
return_map
|
bool
|
Also return the :class: |
False
|
Source code in btorch/sparse/coo.py
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
|
|
required |
n_new
|
int
|
Number of entries after the change. |
required |
Source code in btorch/sparse/properties.py
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 | |
Attributes¶
is_permutation
property
¶
Whether no entries were merged.
Methods:¶
compose(then)
¶
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
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 |
required |
dim
|
int
|
Edge axis. |
-1
|
Source code in btorch/sparse/properties.py
take(meta, dim=0, check=True)
¶
Move categorical metadata (group, receptor, delay ids).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
meta
|
Tensor
|
Tensor whose axis |
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 |
Source code in btorch/sparse/properties.py
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
|
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
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 |
False
|
structurally_symmetric
|
bool
|
The sparsity pattern is symmetric. |
False
|
triangular
|
str | 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
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
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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)
¶
as_coo()
¶
as_csc()
¶
as_csr()
¶
batch_dim()
¶
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
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
matvec(x)
¶
Apply the operator along the last axis of x.
See :func:btorch.sparse.matvec.
rmatvec(x)
¶
sparse_dim()
¶
to(*args, **kwargs)
¶
Move to a device and/or cast the values (indices stay integer).
Source code in btorch/sparse/base.py
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
|
|
{}
|
Source code in btorch/sparse/base.py
to_torch(layout=None, **kwargs)
¶
Export as a torch sparse tensor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
layout
|
str | layout | None
|
|
None
|
**kwargs
|
Any
|
|
{}
|
Source code in btorch/sparse/base.py
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
tocoo()
¶
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
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
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
Functions:¶
_as_tensor(x, *, dtype=None, device=None)
¶
_check_index(name, index)
¶
Source code in btorch/sparse/base.py
_ravel(indices, sizes)
¶
Row-major linear index of indices [len(sizes), E].
Source code in btorch/sparse/coo.py
_unravel(key, sizes)
¶
Source code in btorch/sparse/coo.py
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
|
|
required |
minor
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
|
Source code in btorch/sparse/csr.py
Methods:¶
ccol_indices()
¶
coalesce(return_map=False)
¶
col_indices()
¶
row_indices()
¶
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
transpose()
¶
Transpose without copying: the same arrays read as CSR.
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
|
|
required |
minor
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
Methods:¶
coalesce(return_map=False)
¶
col_indices()
¶
crow_indices()
¶
row_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
transpose()
¶
Transpose without copying: the same arrays read as CSC.
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
|
|
required |
n_new
|
int
|
Number of entries after the change. |
required |
Source code in btorch/sparse/properties.py
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 | |
Attributes¶
is_permutation
property
¶
Whether no entries were merged.
Methods:¶
compose(then)
¶
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
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 |
required |
dim
|
int
|
Edge axis. |
-1
|
Source code in btorch/sparse/properties.py
take(meta, dim=0, check=True)
¶
Move categorical metadata (group, receptor, delay ids).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
meta
|
Tensor
|
Tensor whose axis |
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 |
Source code in btorch/sparse/properties.py
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
|
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
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 |
False
|
structurally_symmetric
|
bool
|
The sparsity pattern is symmetric. |
False
|
triangular
|
str | 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
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
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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)
¶
as_coo()
¶
as_csc()
¶
as_csr()
¶
batch_dim()
¶
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
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
matvec(x)
¶
Apply the operator along the last axis of x.
See :func:btorch.sparse.matvec.
rmatvec(x)
¶
sparse_dim()
¶
to(*args, **kwargs)
¶
Move to a device and/or cast the values (indices stay integer).
Source code in btorch/sparse/base.py
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
|
|
{}
|
Source code in btorch/sparse/base.py
to_torch(layout=None, **kwargs)
¶
Export as a torch sparse tensor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
layout
|
str | layout | None
|
|
None
|
**kwargs
|
Any
|
|
{}
|
Source code in btorch/sparse/base.py
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
tocoo()
¶
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
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
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
_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
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 | |
Functions:¶
_as_tensor(x, *, dtype=None, device=None)
¶
_check_index(name, index)
¶
Source code in btorch/sparse/base.py
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
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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)
¶
as_coo()
¶
as_csc()
¶
as_csr()
¶
batch_dim()
¶
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
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
matvec(x)
¶
Apply the operator along the last axis of x.
See :func:btorch.sparse.matvec.
rmatvec(x)
¶
sparse_dim()
¶
to(*args, **kwargs)
¶
Move to a device and/or cast the values (indices stay integer).
Source code in btorch/sparse/base.py
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
|
|
{}
|
Source code in btorch/sparse/base.py
to_torch(layout=None, **kwargs)
¶
Export as a torch sparse tensor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
layout
|
str | layout | None
|
|
None
|
**kwargs
|
Any
|
|
{}
|
Source code in btorch/sparse/base.py
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
tocoo()
¶
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
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
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
Functions:¶
_parse(subscripts, n_operands)
¶
Split subscripts into one term per operand and the output term.
Source code in btorch/sparse/einsum.py
_ravel(indices, sizes)
¶
Row-major linear index of indices [len(sizes), E].
Source code in btorch/sparse/coo.py
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):
- Diagonal filter: if an indexed letter is repeated in
A's subscript ("ii->i"), keep only the entries whose coordinates agree. - 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. - Contract: one
torch.einsumover 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. - Scatter:
index_addthe 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 |
required |
A
|
Sparse
|
Sparse array in any format; its term must have |
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 ( |
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 |
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 |
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:
Source code in btorch/sparse/einsum.py
65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 | |
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)andA @ x."matmat":A @ Xwith a matrix right-hand side."rmatvec": the transpose apply,A.rmatvec(x),x @ AandA.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
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]
|
|
required |
value
|
Tensor | float
|
Scalar weight: a Python number or a 0-dim tensor (for example
an |
1.0
|
dtype
|
dtype | None
|
Dtype used when |
None
|
device
|
device | str | None
|
Device used when |
None
|
Examples:
Source code in btorch/sparse/operator.py
DiagonalOperator
¶
Bases: StructuredOperator
One-to-one operator: A = diag(d), y = d * x.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
diag
|
Tensor
|
|
required |
Examples:
Source code in btorch/sparse/operator.py
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]
|
|
required |
matvec
|
Callable[[Tensor], Tensor]
|
|
required |
rmatvec
|
Callable[[Tensor], Tensor] | None
|
Optional transpose apply |
None
|
enumerate_edges
|
Callable[[], Edges] | None
|
Optional callable without arguments returning
|
None
|
dtype
|
dtype | None
|
Optional dtype, used by :meth: |
None
|
device
|
device | str | None
|
Optional device, used by :meth: |
None
|
matmat
|
Callable[[Tensor], Tensor] | None
|
Optional |
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
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 | |
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 @ Bwith another operator or aSparse: :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
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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
materialize(format=None)
¶
Build an explicit :class:~btorch.sparse.Sparse with these entries.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
format
|
str | None
|
Optional |
None
|
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
If the operator cannot list its entries
(capability |
Source code in btorch/sparse/operator.py
matmat(x)
¶
A @ X for X [..., N, K], returning [..., M, K].
Source code in btorch/sparse/operator.py
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
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
supports(name)
¶
Whether the optional capability name is available.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
One of :data: |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in btorch/sparse/operator.py
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
tocoo()
¶
tocsc()
¶
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
|
|
required |
V
|
Tensor
|
|
required |
Source code in btorch/sparse/operator.py
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
|
required |
Source code in btorch/sparse/operator.py
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 |
required |
Source code in btorch/sparse/operator.py
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
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
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
Functions:¶
_as_part(obj)
¶
Validate an operand of a composite (operator or plain 2-D
Sparse).
Source code in btorch/sparse/operator.py
_capabilities_of(part)
¶
Source code in btorch/sparse/operator.py
_check_shape(shape)
¶
_composite_device(parts)
¶
Source code in btorch/sparse/operator.py
_composite_dtype(parts)
¶
Source code in btorch/sparse/operator.py
_edges_of(part)
¶
_first(parts, name)
¶
_is_scalar(alpha)
¶
_supports(part, name)
¶
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
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:
valueshas 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
|
|
required |
values
|
Tensor
|
|
required |
shape
|
tuple[int, ...]
|
Logical shape |
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
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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: |
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
indices()
¶
sum_duplicates()
¶
tocsc(return_map=False)
¶
Convert to canonical CSC (column-major, duplicates summed).
tocsr(return_map=False)
¶
Convert to canonical CSR (sorted, duplicates summed).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
return_map
|
bool
|
Also return the :class: |
False
|
Source code in btorch/sparse/coo.py
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 |
False
|
structurally_symmetric
|
bool
|
The sparsity pattern is symmetric. |
False
|
triangular
|
str | 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
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
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 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 | |
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)
¶
as_coo()
¶
as_csc()
¶
as_csr()
¶
batch_dim()
¶
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
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
matvec(x)
¶
Apply the operator along the last axis of x.
See :func:btorch.sparse.matvec.
rmatvec(x)
¶
sparse_dim()
¶
to(*args, **kwargs)
¶
Move to a device and/or cast the values (indices stay integer).
Source code in btorch/sparse/base.py
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
|
|
{}
|
Source code in btorch/sparse/base.py
to_torch(layout=None, **kwargs)
¶
Export as a torch sparse tensor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
layout
|
str | layout | None
|
|
None
|
**kwargs
|
Any
|
|
{}
|
Source code in btorch/sparse/base.py
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
tocoo()
¶
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
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
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
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
|
|
required |
in_index
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
x
|
Tensor
|
|
required |
n_out
|
int
|
Size of the output axis. |
required |
value_batch_dim
|
int
|
Number of leading batch dimensions of |
required |
dense_dim
|
int
|
Number of trailing dense dimensions of |
required |
Returns:
| Type | Description |
|---|---|
Tensor
|
|
Source code in btorch/sparse/ops.py
_check_batch(A, x, n_in, what)
¶
Source code in btorch/sparse/ops.py
_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
_matvec(A, x, transpose)
¶
Source code in btorch/sparse/ops.py
_ravel(indices, sizes)
¶
Row-major linear index of indices [len(sizes), E].
Source code in btorch/sparse/coo.py
_same_pattern(a, b)
¶
matmul(a, b)
¶
Matrix product with one sparse operand; the function behind @.
Shapes follow :func:torch.matmul:
A @ xwith 1-Dxof lengthNreturns lengthM.A @ XwithX.shape == (..., N, K)returns(..., M, K).x @ Awith 1-Dxof lengthMreturns lengthN.X @ AwithX.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
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 |
required |
Returns:
| Type | Description |
|---|---|
Tensor
|
Dense tensor. |
Raises:
| Type | Description |
|---|---|
ValueError
|
On a shape mismatch, or if |
Source code in btorch/sparse/ops.py
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
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 |
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
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
|
|
required |
n_new
|
int
|
Number of entries after the change. |
required |
Source code in btorch/sparse/properties.py
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 | |
Attributes¶
is_permutation
property
¶
Whether no entries were merged.
Methods:¶
compose(then)
¶
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
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 |
required |
dim
|
int
|
Edge axis. |
-1
|
Source code in btorch/sparse/properties.py
take(meta, dim=0, check=True)
¶
Move categorical metadata (group, receptor, delay ids).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
meta
|
Tensor
|
Tensor whose axis |
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 |
Source code in btorch/sparse/properties.py
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
|
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
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 |
False
|
structurally_symmetric
|
bool
|
The sparsity pattern is symmetric. |
False
|
triangular
|
str | 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
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 | |
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.
bind_route(snapshot)
¶
Bind exact callbacks for a previously selected route snapshot.
Source code in btorch/sparse/runtime/backend.py
entry_revision(kernel, name, device)
¶
Return the monotonic revision of a registered implementation.
Source code in btorch/sparse/runtime/backend.py
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
has_route(algorithm, device, context=None)
¶
Return whether a complete route supports context.
Source code in btorch/sparse/runtime/backend.py
name(kernel, device)
¶
override_snapshot()
¶
Return the current context-local override identity.
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 ( |
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
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
resolve(kernel, device)
¶
resolve_route(algorithm, device, context=None)
¶
Select one complete route and return only its immutable identity.
Source code in btorch/sparse/runtime/backend.py
resolve_snapshot(kernel, device)
¶
Return immutable identity for the currently selected route.
Source code in btorch/sparse/runtime/backend.py
route_revision(key, device)
¶
Return the revision of a registered route.
Source code in btorch/sparse/runtime/backend.py
set_backend(name)
¶
Force backend name in the current context (None: auto).
Raises:
| Type | Description |
|---|---|
ValueError
|
If no kernel has a backend called |
Source code in btorch/sparse/runtime/backend.py
snapshot()
¶
Return immutable registry state suitable for invalidation keys.
Source code in btorch/sparse/runtime/backend.py
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
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
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 | |
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_permis 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
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 | |
Methods:¶
build(row, col, shape, version)
¶
(Re)build every representation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
row
|
Tensor
|
|
required |
col
|
Tensor
|
|
required |
shape
|
tuple[int, int]
|
|
required |
version
|
int
|
Topology version the structures correspond to. |
required |
Source code in btorch/sparse/runtime/cache.py
crow_rows()
¶
[E] output index of every CSR entry (expanded crow).
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
|
|
required |
col
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
x
|
Tensor
|
|
required |
t_crow
|
Tensor
|
|
required |
t_col
|
Tensor
|
|
required |
t_perm
|
Tensor
|
|
required |
Returns:
| Type | Description |
|---|---|
Tensor
|
|
Source code in btorch/sparse/runtime/ops.py
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
|
|
Tensor
|
|
Source code in btorch/sparse/runtime/ops.py
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
|
|
required |
col
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
x
|
Tensor
|
|
required |
t_crow
|
Tensor
|
|
required |
t_col
|
Tensor
|
|
required |
t_perm
|
Tensor
|
|
required |
max_density
|
float | None
|
|
None
|
Returns:
| Type | Description |
|---|---|
Tensor
|
|
Source code in btorch/sparse/runtime/ops.py
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
|
|
required |
col
|
Tensor
|
|
required |
values
|
Tensor
|
|
required |
x
|
Tensor
|
|
required |
t_crow
|
Tensor
|
|
required |
t_col
|
Tensor
|
|
required |
t_perm
|
Tensor
|
|
required |
max_density
|
float
|
Largest non-zero fraction of |
required |
Returns:
| Type | Description |
|---|---|
Tensor
|
|
Source code in btorch/sparse/runtime/ops.py
use_backend(name)
¶
Temporarily force a kernel backend in the current context.
Examples: