Relation operations¶
Relation operations expose the same relation builders used internally by convolution, pooling, and neighbor queries. They are useful when an application needs to inspect sparse connectivity, reuse relation metadata, or gather neighbor features explicitly.
Kernel relations are lattice relations over integer coordinates. Neighbor relations are geometric query/source relations over sparse rows and carry distances in edge order.
Submanifold relations are explicit relation objects. They fix output support
to the input coordinate identity while still exposing the same edge arrays, CSR
views, and implicit-GEMM views as compatible forward relations. This keeps
subm_conv3d semantically distinct from generic forward convolution without
duplicating backend kernels.
Related pages¶
Concept reference: Coordinates and relations
Core relation classes: Relations
Coordinate manager cache API: Coordinate management
Convolution route consumers: Convolution routes
- mlx_lattice.ops.relations.build_generative_relation(coords, active_rows=None, kernel_size=2, stride=2)[source]¶
Build a generative transpose-convolution relation.
- mlx_lattice.ops.relations.build_kernel_relation(coords, active_rows=None, kernel_size=3, stride=1, padding=0, dilation=1)[source]¶
Build a forward sparse convolution/pooling relation.
- mlx_lattice.ops.relations.build_knn_relation(source_coords, query_coords=None, *, source_active_rows=None, query_active_rows=None, k)[source]¶
Build a k-nearest-neighbor relation between source and query coords.
- Return type:
- Parameters:
source_coords (array)
query_coords (array | None)
source_active_rows (array | None)
query_active_rows (array | None)
k (int)
- mlx_lattice.ops.relations.build_radius_relation(source_coords, query_coords=None, *, source_active_rows=None, query_active_rows=None, radius, max_neighbors=None)[source]¶
Build a radius-neighborhood relation between source and query coords.
- Return type:
- Parameters:
- mlx_lattice.ops.relations.build_submanifold_kernel_relation(coords, active_rows=None, kernel_size=3, dilation=1)[source]¶
Build a submanifold relation whose output support is
coords.
- mlx_lattice.ops.relations.build_target_kernel_relation(coords, target_coords, *, active_rows=None, target_active_rows=None, kernel_size=3, stride=1, padding=0, dilation=1)[source]¶
Build a sparse kernel relation from source coords to target coords.
- mlx_lattice.ops.relations.build_transposed_kernel_relation(coords, active_rows=None, kernel_size=2, stride=2, padding=0, dilation=1)[source]¶
Build a sparse transpose-convolution relation.
- mlx_lattice.ops.relations.gather_neighbor_features(source, relation)[source]¶
Gather source features in neighbor-edge order.
The result has shape
(E, C)whereEis the neighbor edge capacity andCissource.channels.- Return type:
array- Parameters:
source (SparseTensor)
relation (NeighborRelation)
- mlx_lattice.ops.relations.generative_kernel_relation(x, *, kernel_size=2, stride=2)[source]¶
Build the generative transpose-convolution relation for a tensor.
- Return type:
- Parameters:
- mlx_lattice.ops.relations.kernel_offsets(kernel_size, dilation=1)[source]¶
Enumerate spatial offsets for a dense 3D kernel footprint.
- mlx_lattice.ops.relations.kernel_relation(x, *, kernel_size=3, stride=1, padding=0, dilation=1)[source]¶
Build the forward kernel relation for a sparse tensor.
This is the functional wrapper around
x.coord_manager.kernel_relation. The returned relation can be inspected or passed to lower-level execution helpers.
- mlx_lattice.ops.relations.knn_relation(source, query=None, *, k)[source]¶
Build a k-nearest-neighbor relation for sparse tensors.
sourcesupplies candidate rows andquerysupplies query rows. Whenqueryis omitted, the relation is built withinsource. Both tensors must use the same sparse stride.- Return type:
- Parameters:
source (SparseTensor)
query (SparseTensor | None)
k (int)
- mlx_lattice.ops.relations.radius_relation(source, query=None, *, radius, max_neighbors=None)[source]¶
Build a radius-neighborhood relation for sparse tensors.
max_neighborsoptionally caps the number of source rows associated with each query row. Distances are stored in the returned relation in edge order.- Return type:
- Parameters:
source (SparseTensor)
query (SparseTensor | None)
radius (float)
max_neighbors (int | None)
- mlx_lattice.ops.relations.submanifold_kernel_relation(x, *, kernel_size=3, dilation=1)[source]¶
Build the submanifold kernel relation for a sparse tensor.
The returned relation fixes output support to
x’s coordinate identity. It is the relation semantic used bysubm_conv3d().- Return type:
- Parameters:
- mlx_lattice.ops.relations.target_kernel_relation(x, target, *, kernel_size=3, stride=1, padding=0, dilation=1)[source]¶
Build a relation from
xto an explicit target sparse tensor.Target coordinates fix the output support. If
targetbelongs to a different coordinate manager, its coordinate array is inserted intox’s manager before the relation is cached.- Return type:
- Parameters: