model

AirFoldedVariable()

A resource variable a transform replaced with the constant it provably always holds.

Provisional: importable, but outside the compatibility promise; a minor release can change or remove it.

variable: str

The resource tensor that held the variable.

constants: list[str]

The former read outputs, now constants holding the initial value.

nbytes: int

Persistent bytes the variable occupied.

assignment: str

none when the main graph never assigned it, clip when every assignment stored a MAXIMUM/MINIMUM chain of its own read that leaves the initial value unchanged.

reads: int

READ_VARIABLE operators removed.

assigns: int

ASSIGN_VARIABLE operators removed.

AirModel()

In-memory graph IR for AOT codegen.

name: str = Field(default='Model', description='Name of the model')

Name of the model.

version: str = Field(default='1.0.0', description='Version of the model')

Version of the model.

description: str = Field(default='', description='Description of the model')

Description of the model.

tensors: dict[str, AirTensor] = Field(default_factory=dict, description='Mapping from tensor ID to its AirTensor metadata')

Mapping from tensor ID to its AirTensor metadata.

operators: list[AirOperator] = Field(default_factory=list, description='Topologically ordered list of operators (nodes) in the graph')

Topologically ordered list of operators (nodes) in the graph.

input_ids: list[str] = Field(default_factory=list, description='IDs of tensors that serve as model inputs')

IDs of tensors that serve as model inputs.

output_ids: list[str] = Field(default_factory=list, description='IDs of tensors that serve as model outputs')

IDs of tensors that serve as model outputs.

folded_variables: list[AirFoldedVariable] = Field(default_factory=list, description='Resource variables folded into constants, in folding order')

Resource variables folded into constants.

inputs: list[AirTensor]

List of AirTensor objects corresponding to model inputs.

outputs: list[AirTensor]

List of AirTensor objects corresponding to model outputs.

add_tensor(tensor: AirTensor) -> None

Raises

Errors raised by add_tensor
Type	Description
`ValueError`	If a tensor with the same ID already exists.

remove_tensor(tid: TensorId) -> None

Remove a tensor from the model by its ID.

Raises

Errors raised by remove_tensor
Type	Description
`KeyError`	If the tensor ID is not found.

add_operator(op: AirOperator) -> None

Append a new operator to the execution list.

Raises

Errors raised by add_operator
Type	Description
`ValueError`	If an operator with the same ID already exists.

has_tensor(tid: TensorId) -> bool

Check if a tensor exists in the model by its ID.

get_tensor(tid: TensorId) -> AirTensor

Lookup a tensor by its ID.

Raises

Errors raised by get_tensor
Type	Description
`KeyError`	If the tensor ID is not found.

alias_root(tid: TensorId) -> TensorId

The tensor whose storage tid reads: the end of its alias chain, or tid itself.

tensor_owns_storage(tid: TensorId, *, model_inputs: bool = True) -> str | None

Why tensor tid’s bytes may not be moved or shared, or None when they may.

A tensor owns its storage when it is persistent (state a kernel may write through an input or a named tensor, which no producer count sees), pinned to an arena offset by an external compiler, named by an ETHOS_U operator (whose command stream addresses the arena rather than the pointer table), or a model input (the caller’s buffer). This is the one list of owners; structure_violations, substitution_blockers and identity pruning all consult it.

Parameters

Parameters of tensor_owns_storage
Name	Type	Default	Description
`tid`	`TensorId`	Required	The tensor to check.
`model_inputs`	`bool`	True	Whether being a model input counts. A model input's bytes may be viewed through an alias but not replaced, so a caller asking about the root of a view passes ``False``.

Returns

Returns of tensor_owns_storage
Type	Description
`str \| None`	str \| None: The reason, or ``None`` when nothing owns the storage.

storage_owners(*, model_inputs: bool = True) -> dict[TensorId, str]

The reason of every tensor that owns its storage, by the rules of :meth:tensor_owns_storage.

One pass over the operators indexes the ETHOS_U-addressed tensors, so asking about every tensor costs the model’s size, not its square.

Parameters

Parameters of storage_owners
Name	Type	Default	Description
`model_inputs`	`bool`	True	Whether being a model input counts.

Returns

Returns of storage_owners
Type	Description
`dict[TensorId, str]`	dict[TensorId, str]: The reason per owning tensor; a tensor that owns nothing is absent.

substitution_blockers(tid: TensorId) -> list[str]

Why the consumers of tid cannot be given another tensor, nor its storage another role.

A transform that replaces reads of a run-time tensor, or turns one into a constant in place, may do so only when this is empty. rewrite_constant owns the matching rule for constants.

Parameters

Parameters of substitution_blockers
Name	Type	Default	Description
`tid`	`TensorId`	Required	The tensor whose consumers would be rebound.

Returns

Returns of substitution_blockers
Type	Description
`list[str]`	list[str]: One reason per blocker, empty when the substitution is safe.

structure_violations() -> list[str]

Describe every way the model’s tensors and aliases are ill-formed.

Every tensor an operator or the model names exists; no tensor has two producers and no operator produces a constant (read-only storage has no writer); alias chains end at an existing root without a cycle; a tensor that owns its storage (tensor_owns_storage) has no alias; a constant alias has a constant root; nothing aliases into persistent, pinned or NPU-addressed storage; a model output’s alias root is scratch. The transform pipeline runs this on the loaded model and after each transform.

Returns

Returns of structure_violations
Type	Description
`list[str]`	list[str]: One description per violation; empty when the model is well-formed.

tensor_is_shared(tid: TensorId, reader: AirOperator | None = None) -> bool

Whether anything other than reader uses tensor tid.

Uses are other operators, aliases in either direction (following alias chains transitively), and the model’s inputs and outputs. Rewriting a tensor in place is safe only when this is False.

Parameters

Parameters of tensor_is_shared
Name	Type	Default	Description
`tid`	`TensorId`	Required	The tensor to check.
`reader`	`AirOperator \| None`	None	The operator asking; its own references do not count.

Returns

Returns of tensor_is_shared
Value	Type	Description
`bool`	`bool`	``True`` when some other use exists.

rewrite_constant(reader: AirOperator, name: str | int, data) -> AirTensor

Bind reader’s tensor name to data, rewriting it only where that is safe.

The tensor is rewritten in place when nothing else uses it and reader itself references it once. Otherwise reader’s name is rebound to a copy under <id>_rewritten (or the first free <id>_rewritten_N) whose _packed_from names the source, so memory.tensors rules on the source id still place it, and every other reference keeps the original.

Parameters

Parameters of rewrite_constant
Name	Type	Default	Description
`reader`	`AirOperator`	Required	The operator that owns the rewrite.
`name`	`str \| int`	Required	Its local name for the tensor, or the tensor's position in its inputs.
`data`		Required	The rewritten data.

Returns

Returns of rewrite_constant
Value	Type	Description
`AirTensor`	`AirTensor`	The tensor ``reader`` now reads.

topo_sort() -> list[AirOperator]

Return operators in execution order.

Assumes operators was populated in valid topological order.

order_violations() -> list[str]

Describe every read of a tensor that a later operator produces.

operators is the execution order the planner and the emitted schedule follow, so an operator may not reference, through its inputs or named tensors, a tensor that only a later operator writes. Constant and persistent tensors and model inputs hold a value before any operator runs and are exempt. A read through an alias is checked against every tensor on its alias chain down to the root, because an operator that writes an alias writes the root’s storage.

Returns

Returns of order_violations
Type	Description
`list[str]`	list[str]: One description per violation; empty when the order is valid.

prune_unused_tensors() -> list[TensorId]

Remove dangling tensors that are not referenced by any operator or model input/output.