Builder

Fluent API for building block/scope sparsity hierarchies.

Example:

builder = (
    SparsityBuilder()
    .add_block(param_u, (2, 2, 2, 2), name="U")
    .add_block(param_v, (2, 2, 2, 2), name="V")
    .add_scope("U", scope_shape=(1, 1), name="gU")
    .add_scope("V", scope_shape=(1, 4), name="gV")
    .couple_scopes(
        ["gU", "gV"],
        orders=[(0,1,2,3), (1,0,2,3)],
        name="UV",
    )
)
coupling = builder.get_scope("UV")

class sparsekit.builder.SparsityBuilder

Bases: object

Fluent builder for constructing BlockSpec/ScopeSpec hierarchies.

All mutating methods return self for method chaining.

add_block(param, block_shape, name)

Register a single parameter with its block decomposition.

Parameters:

• param (Parameter)

• block_shape (Tuple[int, ...])

• name (str)

couple_blocks(block_names, orders, name)

Create a BlockCoupling from previously added blocks.

Parameters:

• block_names (List[str])

• orders (List[Tuple[int, ...]])

• name (str)

get_block(name)

Retrieve a BlockSpec or BlockCoupling by name.

Parameters:

name (str)

Return type:

BlockCoupling | BlockSpec

add_scope(block_name, scope_shape, name)

Add a ScopeSpec over an existing block or coupling.

Parameters:

• block_name (str)

• scope_shape (Tuple[int, ...])

• name (str)

couple_scopes(scope_names, orders, name)

Create a ScopeCoupling from previously added scopes.

Scopes are consumed (popped) from the builder when coupled.

Parameters:

• scope_names (List[str])

• orders (List[Tuple[int, ...]])

• name (str)

get_scope(name)

Retrieve a ScopeSpec or ScopeCoupling by name.

Parameters:

name (str)

Return type:

ScopeSpec | ScopeCoupling

get_all_scopes()

Return all uncoupled scopes and scope couplings.

Return type:

Iterable[ScopeSpec | ScopeCoupling]