Abstract Base Classes
These abstract classes define the interface shared by all block and scope
types. You do not instantiate them directly — use BlockSpec,
BlockCoupling, ScopeSpec,
or ScopeCoupling instead.
SparseBlock
-
class sparsekit.block.SparseBlock[source]
Bases: ABC
Abstract base class for block-structured sparse tensors.
Provides interface for viewing tensors as block grids, computing block
statistics, and applying soft/hard thresholding operations.
-
norms(values=None, p=2)[source]
Compute Lp norm for each block.
- Parameters:
-
- Return type:
Tensor
-
min(values=None)[source]
Compute minimum value for each block.
- Parameters:
values (Tensor | Mapping[Any, Tensor] | None)
- Return type:
Tensor
-
max(values=None)[source]
Compute maximum value for each block.
- Parameters:
values (Tensor | Mapping[Any, Tensor] | None)
- Return type:
Tensor
-
property grid_ndim: int
Number of dimensions in the block grid.
-
property grid_shape: Tuple[int, ...]
Shape of the block grid (number of blocks per dimension).
-
abstractmethod parameters()[source]
Iterable of Parameter objects managed by this node.
- Return type:
Iterable[View]
-
abstract property data: Mapping[BlockSpec, Tensor] | Tensor
Raw tensor data of the underlying parameter(s).
-
abstractmethod nnz(eps=1e-08)[source]
Count non-zero elements with absolute value > eps.
- Return type:
int
-
numblk()[source]
Total number of blocks in the grid.
- Return type:
int
-
numel()[source]
Total number of elements across all blocks.
- Return type:
int
-
abstractmethod numel_per_block()[source]
Number of elements per block.
- Return type:
int
-
abstractmethod apply_mask(mask)[source]
Zero out blocks where mask is True.
- Parameters:
mask (Tensor)
- Return type:
None
-
abstractmethod apply_multiplier(multiplier)[source]
Multiply each block by corresponding scalar in multiplier.
- Parameters:
multiplier (Tensor)
-
abstractmethod block_view(values, reorder=True, merge=False)[source]
Return a block-structured view of values.
- Parameters:
values (Tensor | Mapping[Any, Tensor] | None)
- Return type:
Tensor
-
abstractmethod reduce(values, reduce_fn)[source]
Apply reduce_fn over each block and return grid-shaped result.
- Parameters:
-
- Return type:
Tensor
-
soft_threshold(block_thresholds, conditioners=None, max_iter=20, atol=1e-08, eps=None)[source]
Apply soft thresholding to shrink block norms.
- Parameters:
block_thresholds (Tensor) – Per-block threshold values.
conditioners (Tensor | Mapping[Any, Tensor] | None) – Optional diagonal conditioner for Adam variant.
max_iter (int) – Maximum iterations for Adam variant.
eps (float | None) – Small constant for numerical stability.
atol (float) – Absolute tolerance for convergence.
- Return type:
None
-
hard_threshold(thresholds, values)[source]
Zero out blocks with values-based norm below threshold.
- Parameters:
thresholds (Tensor) – Per-block threshold values.
values (Tensor | Mapping[Any, Tensor] | None) – Values to compare to; use None to use self norm.
-
abstractmethod get_masks(block_masks)[source]
Convert block-level mask to element-level masks per BlockSpec.
- Parameters:
block_masks (Tensor)
- Return type:
Mapping[SparseBlock, Tensor]
SparseScope
-
class sparsekit.scope.SparseScope[source]
Bases: ABC
Abstract base class for scope-level sparsity specifications.
-
abstractmethod numblk_per_scope()[source]
Number of blocks per scope.
- Return type:
int
-
abstractmethod numel_per_scope()[source]
Number of elements per scope.
- Return type:
int
-
property grid_shape: Tuple[int, ...]
Shape of the scope grid (number of scopes per dimension).
-
abstractmethod hard_threshold(thresholds=None, nnz=None, values=None)[source]
Zeros out blocks in-place based on scope-level thresholds.
- Parameters:
-
-
sparsity_to_nnz(sparsity)[source]
Convert a sparsity ratio to number of non-zero blocks per scope.
- Parameters:
sparsity (float) – Fraction of blocks to prune (0.0 = keep all,
1.0 = prune all).
- Returns:
Number of blocks to keep per scope.
- Return type:
int