Coordinate management

Coordinate managers make sparse support identity explicit. A CoordinateMapKey belongs to exactly one CoordinateManager; relations are cached by source key, target key, kernel geometry, semantic operation, and execution policy. This prevents tensors with equal stride but different rows from sharing a kernel map.

Feature-only operations preserve the input key. Support-changing operations insert a new map into the same manager so later inverse convolution and branch alignment can refer to the precise execution graph.

class torch_lattice.core.coords.CoordinateMapKey(manager_id, id, stride)

Bases: object

Identity of one coordinate support owned by a coordinate manager.

Parameters:

• manager_id (int)

• id (int)

• stride (tuple[int, int, int])

manager_id: int

id: int

stride: tuple[int, int, int]

class torch_lattice.core.coords.RelationKey(source, target, operation, kernel_size, stride, padding, dilation, execution)

Bases: object

Identity of a cached sparse relation and its execution representation.

Parameters:

• source (CoordinateMapKey)

• target (CoordinateMapKey)

• operation (str)

• kernel_size (tuple[int, int, int])

• stride (tuple[int, int, int])

• padding (tuple[int, int, int])

• dilation (tuple[int, int, int])

• execution (tuple[Any, ...])

source: CoordinateMapKey

target: CoordinateMapKey

operation: str

kernel_size: tuple[int, int, int]

stride: tuple[int, int, int]

padding: tuple[int, int, int]

dilation: tuple[int, int, int]

execution: tuple[Any, ...]

class torch_lattice.core.coords.CoordinateMap(coords, spatial_range, batch_counts)

Bases: object

Parameters:

• coords (Tensor)

• spatial_range (tuple[int, int, int, int] | None)

• batch_counts (tuple[int, ...] | None)

coords: Tensor

spatial_range: tuple[int, int, int, int] | None

batch_counts: tuple[int, ...] | None

class torch_lattice.core.coords.CoordinateManager

Bases: object

Own coordinate supports and relations for one sparse execution graph.

insert(coords, stride, *, spatial_range, batch_counts)

Return type:

CoordinateMapKey

Parameters:

• coords (Tensor)

• stride (tuple[int, int, int])

• spatial_range (tuple[int, int, int, int] | None)

• batch_counts (tuple[int, ...] | None)

get(key)

Return type:

CoordinateMap

Parameters:

key (CoordinateMapKey)

relation(key)

Return type:

Any | None

Parameters:

key (RelationKey)

set_relation(key, relation)

Return type:

None

Parameters:

• key (RelationKey)

• relation (Any)

forward_relation(source, *, operation, kernel_size, stride, padding, dilation, execution)

Return type:

tuple[CoordinateMapKey, Any] | None

Parameters:

• source (CoordinateMapKey)

• operation (str)

• kernel_size (tuple[int, int, int])

• stride (tuple[int, int, int])

• padding (tuple[int, int, int])

• dilation (tuple[int, int, int])

• execution (tuple[Any, ...])

set_forward_relation(key, relation)

Return type:

None

Parameters:

• key (RelationKey)

• relation (Any)

set_inverse_relation(key, relation)

Return type:

None

Parameters:

• key (RelationKey)

• relation (Any)

inverse_relation(source, *, operation, kernel_size, stride, padding, dilation, execution)

Return type:

tuple[CoordinateMapKey, Any] | None

Parameters:

• source (CoordinateMapKey)

• operation (str)

• kernel_size (tuple[int, int, int])

• stride (tuple[int, int, int])

• padding (tuple[int, int, int])

• dilation (tuple[int, int, int])

• execution (tuple[Any, ...])

generated_target(source, *, operation, kernel_size, stride, padding, dilation)

Return cached support generated by a coordinate-only operation.

Return type:

CoordinateMapKey | None

Parameters:

• source (CoordinateMapKey)

• operation (str)

• kernel_size (tuple[int, int, int])

• stride (tuple[int, int, int])

• padding (tuple[int, int, int])

• dilation (tuple[int, int, int])

set_generated_target(source, target, *, operation, kernel_size, stride, padding, dilation)

Cache one generated coordinate support by its exact geometry.

Return type:

None

Parameters:

• source (CoordinateMapKey)

• target (CoordinateMapKey)

• operation (str)

• kernel_size (tuple[int, int, int])

• stride (tuple[int, int, int])

• padding (tuple[int, int, int])

• dilation (tuple[int, int, int])

hashmap(key, execution)

Return type:

tuple[Any, Any] | None

Parameters:

• key (CoordinateMapKey)

• execution (tuple[Any, ...])

set_hashmap(key, execution, value)

Return type:

None

Parameters:

• key (CoordinateMapKey)

• execution (tuple[Any, ...])

• value (tuple[Any, Any])

clear_relations()

Return type:

None

property relation_count: int

property cached_relations: tuple[Any, ...]

Read-only snapshot of cached relation payloads for diagnostics.

property cached_hashmaps: tuple[tuple[Any, Any], ...]

Read-only snapshot of native hash maps for diagnostics.