mlx-lattice

mlx-lattice is a sparse point-cloud and sparse-voxel library built on top of MLX. It provides sparse tensor containers, coordinate management, sparse convolution and pooling operators, point/voxel conversion utilities, quantized inference helpers, and mlx.nn-style modules for Apple Silicon workflows.

The project is organized around sparse semantics rather than around individual kernels. A user creates a mlx_lattice.SparseTensor, applies operators such as mlx_lattice.ops.conv3d() or mlx_lattice.ops.pool3d(), and lets the implementation choose the appropriate CPU or Metal route. Backend details such as CSR traversal, sorted implicit-GEMM views, TensorOps availability, and quantized weight packing remain implementation details unless you are maintaining the native backend itself.

The most important contract is small:

• coordinates are integer rows ordered as (batch, x, y, z);

• features are MLX arrays whose rows are aligned with those coordinates;

• sparse relations describe how input coordinate rows contribute to output coordinate rows;

• public semantics are shared by the CPU and Metal backends even when their kernels use different implementation strategies.

Use the getting-started pages when learning the end-to-end workflow. Use the concept references when you need to reason about coordinate identity, relations, sparse algebra, or point/voxel conversion. Use the backend reference when diagnosing why a public operation selected a particular execution path.

Navigation map

Task	Read first	API reference
Build a sparse tensor	Sparse tensor model	Sparse tensor
Write a sparse model	Quickstart	Neural network modules
Use sparse convolution	Convolution routes	Convolution operations
Pool sparse features	Pooling routes	Pooling operations
Combine sparse branches	Coordinate-aligned sparse algebra	Sparse tensor algebra
Convert points and voxels	Point/voxel backend routes	Point/voxel operations
Quantize inference weights	Quantization routes	Quantized weights
Diagnose dispatch	Backend path selection	Diagnostics API
Check API stability	Stability contract	Caveats and stability notes

Note

The current package version is 0.2.0. Metal execution requires an MLX build with Metal support and a supported Apple Silicon device. CPU routes remain available for supported operators and are useful for correctness checks, development, and platforms without Metal.

Getting started

• Getting started

Reference

• Concepts
• Backend reference

API reference

• API reference

Project notes

• Stability contract
• Caveats and stability notes