Getting started

The getting-started section explains how to install mlx-lattice and how to think about a sparse pipeline before reading individual API entries. The API is compact, but sparse tensor code has a few concepts that are easier to learn in order: coordinate rows, feature rows, coordinate identity, relations, and backend path selection.

Most user code follows the same shape:

1. build or receive a set of batched integer coordinates;

2. attach feature rows to those coordinates with mlx_lattice.SparseTensor;

3. apply sparse operators or mlx_lattice.nn modules;

4. optionally pool, voxelize, devoxelize, quantize weights, or align multiple sparse tensors.

The public API does not require choosing CPU kernels, Metal kernels, TensorOps kernels, or implicit-GEMM kernels by hand. Those are internal execution choices. The user-facing responsibility is to keep the sparse tensor contract valid: coordinates must be integer (N, 4) rows, features must have N rows, and operators that combine tensors must either share coordinate identity or ask for a value-aligned join.

• Installation
  • Installing from a checkout
  • Verifying the install
  • Choosing CPU or Metal during development
  • Development checks
  • Platform notes
  • Troubleshooting checklist
• Quickstart
  • Walkthrough map
  • Create a sparse tensor
  • Functional convolution
  • Target coordinates
  • mlx_lattice.nn modules
  • Pooling
  • Feature operations
  • Sparse tensor algebra
  • Point/voxel conversion
  • Quantized inference
  • Relation builders and neighbor queries
  • Recommended next reads
• End-to-end sparse workflow
  • Workflow cross-reference
  • Stage 1: choose the sparse support
  • Stage 2: build tensors with metadata
  • Stage 3: compose feature-preserving blocks
  • Stage 4: insert relation-changing blocks
  • Stage 5: align branches before combining
  • Stage 6: bridge point and voxel domains
  • Stage 7: quantize after the floating contract is correct
  • Stage 8: benchmark by public shape

Recommended reading order

Start with Installation if you are setting up a checkout or a development environment. Then read Quickstart for a small executable walkthrough. End-to-end sparse workflow is more conceptual: it explains how individual building blocks connect in a real model or data-processing pipeline.

After that, the reference sections become more useful:

• Sparse tensor model describes the sparse tensor value model and the coordinate manager.

• Coordinates and relations describes relation objects, kernel geometry, and neighbor views.

• Coordinate-aligned sparse algebra describes value-aligned sparse algebra.

• Backend path selection explains how the backend dispatch chooses CPU, classic Metal, TensorOps, and quantized routes.

Development expectations

mlx-lattice contains Python code, MLX integration code, and native CPU/Metal extensions. A source checkout is therefore more involved than a pure Python package. When contributing, keep three checks separate in your head:

ty

Verifies Python typing and catches API-level inconsistencies.

pytest

Verifies semantic behavior and backend parity where the local environment can execute the requested backend.

prek

Runs the repository’s configured formatting, linting, and native static checks. This is the broadest local hygiene gate and is the closest match for CI style checks.

Documentation describes public semantics and stable maintainer contracts. Temporary environment variables, internal kernel names, and benchmark switches are not presented as user APIs.