IR API

lattice_contract is now MLIR-first. Its public surface contains the annotation-backed lattice dialect schema plus a generated textual MLIR builder. It does not import MLX, Torch, native kernels, or sparse runtime objects.

For the conceptual model, read Sparse model IR.

Annotated dialect schema

The dialect schema is executable metadata: decorators register types, attributes, operations, operands, results, and operation attributes once. The builder consumes this schema directly, so exporter code can call the generated operation surface instead of carrying a parallel op-name registry.

The current dialect surface is intentionally small but semantic: sparse ABI construction/decomposition, symbolic weight binding, the sparse convolution family (forward, submanifold, target, transpose, and generative transpose), local/global sparse pooling, point/voxel conversion, dense feature projection, dense feature activation, dense feature normalization, sparse feature replacement, and coordinate-aligned sparse binary algebra. Backend execution routes such as TensorOps, CSR views, point-to-voxel cache maps, or rulebook layouts are not encoded in the dialect.

class lattice_contract.schema.TypeParameter(name, kind)

Bases: object

One MLIR dialect type parameter.

Parameters:

• name (str)

• kind (str)

name: str

kind: str

class lattice_contract.schema.TypeDef(name, mnemonic, parameters=(), summary='')

Bases: object

Annotated MLIR type declaration.

Parameters:

• name (str)

• mnemonic (str)

• parameters (tuple[TypeParameter, ...])

• summary (str)

name: str

mnemonic: str

parameters: tuple[TypeParameter, ...]

summary: str

class lattice_contract.schema.AttrParameter(name, kind)

Bases: object

One MLIR dialect attribute parameter.

Parameters:

• name (str)

• kind (str)

name: str

kind: str

class lattice_contract.schema.AttrDef(name, mnemonic, parameters=(), values=(), summary='')

Bases: object

Annotated MLIR attribute declaration.

Parameters:

• name (str)

• mnemonic (str)

• parameters (tuple[AttrParameter, ...])

• values (tuple[str, ...])

• summary (str)

name: str

mnemonic: str

parameters: tuple[AttrParameter, ...]

values: tuple[str, ...]

summary: str

class lattice_contract.schema.OperandDef(name, type, kind='ssa', optional=False)

Bases: object

One operation operand declaration.

Parameters:

• name (str)

• type (str)

• kind (Literal['ssa', 'symbol'])

• optional (bool)

name: str

type: str

kind: Literal['ssa', 'symbol']

optional: bool

class lattice_contract.schema.ResultDef(name, type)

Bases: object

One operation result declaration.

Parameters:

• name (str)

• type (str)

name: str

type: str

class lattice_contract.schema.OpAttributeDef(name, kind, required=True)

Bases: object

One operation attribute declaration.

Parameters:

• name (str)

• kind (Literal['coord', 'feature_layout', 'weight_layout', 'packing', 'activation', 'gelu_approx', 'join', 'binary_op', 'pool_mode', 'voxel_reduction', 'point_interpolation', 'i64_triple', 'f64_triple', 'i64', 'f32', 'str'])

• required (bool)

name: str

kind: Literal['coord', 'feature_layout', 'weight_layout', 'packing', 'activation', 'gelu_approx', 'join', 'binary_op', 'pool_mode', 'voxel_reduction', 'point_interpolation', 'i64_triple', 'f64_triple', 'i64', 'f32', 'str']

required: bool

class lattice_contract.schema.OpDef(name, python_name, operands=(), results=(), attributes=(), assembly='functional', summary='')

Bases: object

Annotated MLIR operation declaration.

Parameters:

• name (str)

• python_name (str)

• operands (tuple[OperandDef, ...])

• results (tuple[ResultDef, ...])

• attributes (tuple[OpAttributeDef, ...])

• assembly (str)

• summary (str)

name: str

python_name: str

operands: tuple[OperandDef, ...]

results: tuple[ResultDef, ...]

attributes: tuple[OpAttributeDef, ...]

assembly: str

summary: str

class lattice_contract.schema.DialectSchema(namespace, types=<factory>, attrs=<factory>, ops=<factory>, _ops_by_python_name=<factory>)

Bases: object

Annotation-backed dialect schema.

The schema is intentionally executable: decorators register MLIR declarations once, and downstream builders/importers consume the registry instead of maintaining hand-written op-name maps.

Parameters:

• namespace (str)

• types (dict[str, TypeDef])

• attrs (dict[str, AttrDef])

• ops (dict[str, OpDef])

• _ops_by_python_name (dict[str, OpDef])

namespace: str

types: dict[str, TypeDef]

attrs: dict[str, AttrDef]

ops: dict[str, OpDef]

type(name, mnemonic, *, parameters=(), summary='')

Register a dialect type declaration.

Return type:

Callable[[TypeVar(DeclarationT, bound= Callable | type)], TypeVar(DeclarationT, bound= Callable | type)]

Parameters:

• name (str)

• mnemonic (str)

• parameters (Iterable[TypeParameter])

• summary (str)

attr(name, mnemonic, *, parameters=(), values=(), summary='')

Register a dialect attribute declaration.

Return type:

Callable[[TypeVar(DeclarationT, bound= Callable | type)], TypeVar(DeclarationT, bound= Callable | type)]

Parameters:

• name (str)

• mnemonic (str)

• parameters (Iterable[AttrParameter])

• values (Iterable[str])

• summary (str)

op(name, *, python_name=None, operands=(), results=(), attributes=(), assembly='functional', summary='')

Register a dialect operation declaration.

Return type:

Callable[[TypeVar(DeclarationT, bound= Callable | type)], TypeVar(DeclarationT, bound= Callable | type)]

Parameters:

• name (str)

• python_name (str | None)

• operands (Iterable[OperandDef])

• results (Iterable[ResultDef])

• attributes (Iterable[OpAttributeDef])

• assembly (str)

• summary (str)

add_type(definition)

Return type:

Self

Parameters:

definition (TypeDef)

add_attr(definition)

Return type:

Self

Parameters:

definition (AttrDef)

add_op(definition)

Return type:

Self

Parameters:

definition (OpDef)

op_by_python_name(name)

Return type:

OpDef

Parameters:

name (str)

qualified_op_name(definition)

Return the fully-qualified MLIR operation name.

Return type:

str

Parameters:

definition (str | OpDef)

resolve_qualified_op(name)

Resolve a fully-qualified MLIR operation name.

Return type:

OpDef

Parameters:

name (str)

resolve_op(value)

Resolve an op handle to its schema definition.

Decorated functions/classes carry __lattice_op__ metadata. This is the preferred path because it lets framework code bind to the API object instead of repeating dialect strings.

Return type:

OpDef

Parameters:

value (str | OpDef | Callable[[...], Any])

iter_ops()

Return type:

Iterator[OpDef]

lattice_contract.schema.type_param(name, kind)

Declare one dialect type parameter.

Return type:

TypeParameter

Parameters:

• name (str)

• kind (str)

lattice_contract.schema.attr_param(name, kind)

Declare one dialect attribute parameter.

Return type:

AttrParameter

Parameters:

• name (str)

• kind (str)

lattice_contract.schema.operand(name, type, *, kind='ssa', optional=False)

Declare one operation operand.

Return type:

OperandDef

Parameters:

• name (str)

• type (str)

• kind (Literal['ssa', 'symbol'])

• optional (bool)

lattice_contract.schema.result(name, type)

Declare one operation result.

Return type:

ResultDef

Parameters:

• name (str)

• type (str)

lattice_contract.schema.op_attr(name, kind, *, required=True)

Declare one operation attribute.

Return type:

OpAttributeDef

Parameters:

• name (str)

• kind (Literal['coord', 'feature_layout', 'weight_layout', 'packing', 'activation', 'gelu_approx', 'join', 'binary_op', 'pool_mode', 'voxel_reduction', 'point_interpolation', 'i64_triple', 'f64_triple', 'i64', 'f32', 'str'])

• required (bool)

lattice_contract.schema.schema_digest(schema)

Return a compact stable digest useful for drift tests.

Return type:

Mapping[str, tuple[str, ...]]

Parameters:

schema (DialectSchema)

lattice_contract.schema.canonical_schema(schema)

Return the canonical public schema used for artifact compatibility.

Return type:

Mapping[str, Any]

Parameters:

schema (DialectSchema)

lattice_contract.schema.schema_fingerprint(schema)

Return a deterministic SHA-256 fingerprint for a dialect schema.

Return type:

str

Parameters:

schema (DialectSchema)

class lattice_contract.dialect.SparseTensorType

Bases: object

Annotated sparse tensor type declaration.

class lattice_contract.dialect.WeightType

Bases: object

Annotated symbolic weight type declaration.

class lattice_contract.dialect.CoordAttr

Bases: object

Annotated coordinate convention attribute.

class lattice_contract.dialect.FeatureLayoutAttr

Bases: object

Annotated feature layout attribute.

class lattice_contract.dialect.WeightLayoutAttr

Bases: object

Annotated weight layout attribute.

class lattice_contract.dialect.PackingAttr

Bases: object

Annotated weight packing attribute.

class lattice_contract.dialect.ActivationAttr

Bases: object

Annotated dense feature activation attribute.

class lattice_contract.dialect.GeluApproxAttr

Bases: object

Annotated GELU approximation attribute.

class lattice_contract.dialect.JoinAttr

Bases: object

Annotated sparse algebra join attribute.

class lattice_contract.dialect.BinaryOpAttr

Bases: object

Annotated sparse binary operation attribute.

class lattice_contract.dialect.PoolModeAttr

Bases: object

Annotated sparse pooling reduction mode attribute.

class lattice_contract.dialect.VoxelReductionAttr

Bases: object

Annotated point-to-voxel feature aggregation reduction.

class lattice_contract.dialect.PointInterpolationAttr

Bases: object

Annotated voxel-to-point interpolation mode.

lattice_contract.dialect.weight()

Register lattice.weight.

Return type:

None

lattice_contract.dialect.sparse_make()

Register lattice.sparse.make.

Return type:

None

lattice_contract.dialect.sparse_decompose()

Register lattice.sparse.decompose.

Return type:

None

lattice_contract.dialect.sparse_with_features()

Register lattice.sparse.with_features.

Return type:

None

lattice_contract.dialect.sparse_reindex()

Register lattice.sparse.reindex.

Return type:

None

lattice_contract.dialect.conv3d()

Register lattice.conv3d.

Return type:

None

lattice_contract.dialect.subm_conv3d()

Register lattice.subm_conv3d.

Return type:

None

lattice_contract.dialect.normalized_subm_conv3d()

Register lattice.normalized_subm_conv3d.

Return type:

None

lattice_contract.dialect.target_conv3d()

Register lattice.target_conv3d.

Return type:

None

lattice_contract.dialect.conv_transpose3d()

Register lattice.conv_transpose3d.

Return type:

None

lattice_contract.dialect.target_conv_transpose3d()

Register lattice.target_conv_transpose3d.

Return type:

None

lattice_contract.dialect.normalized_conv_transpose3d()

Register lattice.normalized_conv_transpose3d.

Return type:

None

lattice_contract.dialect.target_normalized_conv_transpose3d()

Register lattice.target_normalized_conv_transpose3d.

Return type:

None

lattice_contract.dialect.generative_conv_transpose3d()

Register lattice.generative_conv_transpose3d.

Return type:

None

lattice_contract.dialect.normalized_generative_conv_transpose3d()

Register lattice.normalized_generative_conv_transpose3d.

Return type:

None

lattice_contract.dialect.pool3d()

Register lattice.pool3d.

Return type:

None

lattice_contract.dialect.pool_transpose3d()

Register lattice.pool_transpose3d.

Return type:

None

lattice_contract.dialect.trilinear_upsample3d()

Register lattice.trilinear_upsample3d.

Return type:

None

lattice_contract.dialect.global_pool()

Register lattice.global_pool.

Return type:

None

lattice_contract.dialect.voxelize()

Register lattice.voxelize.

Return type:

None

lattice_contract.dialect.devoxelize()

Register lattice.devoxelize.

Return type:

None

lattice_contract.dialect.linear()

Register lattice.linear.

Return type:

None

lattice_contract.dialect.embedding_lookup()

Register lattice.embedding_lookup.

Return type:

None

lattice_contract.dialect.elementwise()

Register lattice.elementwise.

Return type:

None

lattice_contract.dialect.softmax()

Register lattice.softmax.

Return type:

None

lattice_contract.dialect.activation()

Register lattice.activation.

Return type:

None

lattice_contract.dialect.batch_norm()

Register lattice.batch_norm.

Return type:

None

lattice_contract.dialect.layer_norm()

Register lattice.layer_norm.

Return type:

None

lattice_contract.dialect.rms_norm()

Register lattice.rms_norm.

Return type:

None

lattice_contract.dialect.sparse_binary()

Register lattice.sparse.binary.

Return type:

None

lattice_contract.dialect.sparse_cat()

Register lattice.sparse.cat.

Return type:

None

MLIR builder

The builder emits textual lattice MLIR from the annotated schema. It is intended for exporters and tests; semantic verification remains the job of lattice-opt and the MLIR dialect verifier.

Generated modules include the required artifact ABI metadata: lattice.ir_version = 2 and lattice.weight_file = "weights.safetensors". These attributes are part of the stable exchange contract, not optional documentation. The corresponding Python constants are exported as CURRENT_DIALECT_VERSION, ARTIFACT_GRAPH_FILE, and ARTIFACT_WEIGHT_FILE.

class lattice_contract.mlir.builder.TensorType(text)

Bases: object

Raw MLIR tensor type used at graph ABI boundaries.

Parameters:

text (str)

text: str

mlir()

Return type:

str

class lattice_contract.mlir.builder.SparseTensorType(dtype='f16', rank=3, coord='batch_x_y_z', feature='row_channel')

Bases: object

Lattice sparse tensor type.

Parameters:

• dtype (str)

• rank (int)

• coord (str)

• feature (str)

dtype: str

rank: int

coord: str

feature: str

mlir()

Return type:

str

class lattice_contract.mlir.builder.WeightType(family, dtype='f16')

Bases: object

Lattice symbolic weight type.

Parameters:

• family (str)

• dtype (str)

family: str

dtype: str

mlir()

Return type:

str

class lattice_contract.mlir.builder.Packing(kind='dense', group_size=0, scale_dtype='', mode='')

Bases: object

Lattice weight packing attribute.

Parameters:

• kind (str)

• group_size (int)

• scale_dtype (str)

• mode (str)

kind: str

group_size: int

scale_dtype: str

mode: str

mlir()

Return type:

str

class lattice_contract.mlir.builder.SSAValue(name, type)

Bases: object

Named SSA value plus its MLIR type.

Parameters:

• name (str)

• type (TensorType | SparseTensorType | WeightType)

name: str

type: TensorType | SparseTensorType | WeightType

ref()

Return type:

str

lattice_contract.mlir.builder.dense_packing()

Return dense weight packing.

Return type:

Packing

lattice_contract.mlir.builder.quantized_packing(kind, *, group_size, scale_dtype='f16', mode='affine')

Return affine int4/int8 weight packing.

Return type:

Packing

Parameters:

• kind (str)

• group_size (int)

• scale_dtype (str)

• mode (str)

type lattice_contract.mlir.builder.EmitResult = SSAValue | tuple[SSAValue, ...]

type lattice_contract.mlir.builder.OpHandle = str | OpDef | Callable[[...], Any]

class lattice_contract.mlir.builder.EmitFn(*args, **kwargs)

Bases: Protocol

Textual MLIR emitter callable with a stable function name.

class lattice_contract.mlir.builder.EmitRegistry(functions, default)

Bases: object

Annotation-backed textual assembly emitter registry.

Parameters:

• functions (dict[str, EmitFn])

• default (EmitFn)

functions: dict[str, EmitFn]

default: EmitFn

register(op, fn)

Register a specialized emitter for a dialect operation.

Return type:

EmitFn

Parameters:

• op (OpHandle)

• fn (EmitFn)

emit(builder, op, kwargs)

Emit op through a specialized or default emitter.

Return type:

SSAValue | tuple[SSAValue, ...]

Parameters:

• builder (MLIRModuleBuilder)

• op (OpDef)

• kwargs (Mapping[str, Any])

lattice_contract.mlir.builder.mlir_emitter(*, op)

Bind a textual assembly hook to a dialect declaration.

Return type:

Callable[[EmitFn], EmitFn]

Parameters:

op (OpHandle)

class lattice_contract.mlir.builder.MLIRModuleBuilder(name='forward')

Bases: object

Annotation-driven textual MLIR module builder.

Operation methods are generated dynamically from lattice_contract.dialect.LATTICE_DIALECT. The builder is therefore a convenience layer over the annotated schema, not a second op registry.

Parameters:

name (str)

argument(name, type, *, role='tensor')

Append a function argument and return its SSA value.

Return type:

SSAValue

Parameters:

• name (str)

• type (str | TensorType | SparseTensorType)

• role (Literal['tensor', 'sparse_coords', 'sparse_features', 'sparse_active'])

return_(*values, names=None, roles=None)

Set function return values.

Return type:

None

Parameters:

• values (SSAValue)

• names (Sequence[str] | None)

• roles (Sequence[Literal['tensor', 'sparse_tensor']] | None)

to_mlir()

Render the module as textual MLIR.

Return type:

str

emit(definition, **kwargs)

Emit an operation declared by the annotated schema.

Return type:

SSAValue | tuple[SSAValue, ...]

Parameters:

• definition (OpDef)

• kwargs (Any)

lattice_contract.mlir.builder.functional_emitter(builder, op, kwargs)

Return type:

SSAValue

Parameters:

• builder (MLIRModuleBuilder)

• op (OpDef)

• kwargs (Mapping[str, Any])

lattice_contract.mlir.builder.weight_emitter(builder, op, kwargs)

Return type:

SSAValue

Parameters:

• builder (MLIRModuleBuilder)

• op (OpDef)

• kwargs (Mapping[str, Any])

lattice_contract.mlir.builder.sparse_decompose_emitter(builder, op, kwargs)

Return type:

tuple[SSAValue, ...]

Parameters:

• builder (MLIRModuleBuilder)

• op (OpDef)

• kwargs (Mapping[str, Any])