For the complete documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /get-started.md).

Python class

EagerRealizationContext

EagerRealizationContext

class max.experimental.realization_context.EagerRealizationContext(executor=None, *, use_interpreter=None)

source

Bases: RealizationContext

Computation graph for managing tensor operations.

This class manages the directed acyclic graph (DAG) of tensor operations for lazy evaluation and optimization. It tracks both realized tensors (with concrete data in memory) and unrealized tensors (pending computations) to enable efficient batch compilation and execution.

Initializes the context.

Parameters:

• executor (Executor | None) – Executor used to run the finalized graph. None resolves to default_executor() at construction time.
• use_interpreter (bool | None) – Deprecated. Selects an executor for backward compatibility when executor is not given: True forces the interpreter for any graph the interpreter accepts (runtime errors propagate), False forces compilation, and None uses the default executor.

add_mutable_source()

add_mutable_source(tensor)

source

Adds a realized tensor as a mutable graph input.

Like add_source() but creates a BufferType (mutable) input so the tensor can be mutated in-place by buffer_store.

Parameters:

tensor (Tensor)

Return type:

RealizationState

add_source()

add_source(tensor)

source

Adds a realized tensor as an input source to the computation graph.

Registers a realized tensor as a graph input, allowing it to be used in subsequent graph operations. The tensor’s data will be passed to the compiled graph during execution. This operation is idempotent; adding the same tensor multiple times returns the same state.

Parameters:

tensor (Tensor) – A realized tensor to add as a graph input source.

Returns:

The state associating the tensor with its graph value and this context.

Return type:

RealizationState

Raises:

TypeError – If the tensor is not realized (has no concrete data).

create_unrealized()

create_unrealized(values, *, mapping=None)

source

Creates an unrealized tensor backed by graph value(s).

Parameters:

• values (tuple[GraphValue, ...])
• mapping (DeviceMapping | None)

Return type:

Tensor

ensure_signal_buffers()

ensure_signal_buffers(mesh)

source

Lazily creates signal buffers for multi-device collectives on mesh.

Called by collective ops when they detect a multi-GPU mesh. On the first call, this adds BufferType graph inputs and caches the resulting BufferValue list so subsequent collectives in the same graph reuse the same buffers.

The runtime driver.Buffer objects (1025 MB each) are allocated once per device set via _cached_signal_buffers() and shared across all eager contexts to avoid repeated allocation.

Returns None for single-device or CPU-only meshes.

Parameters:

mesh (DeviceMesh)

Return type:

list[BufferValue] | None

finalize_graph()

finalize_graph()

source

Finalizes the computation graph for execution.

Prepares the graph for execution by setting outputs, lowering RMO ops, and removing dead code and unused arguments.

Returns:

A tuple containing the list of output tensors (including the seed) and the finalized graph.

Return type:

tuple[list[Tensor], Graph]

graph

graph: Graph

source

The graph used by the realization context.

realize_all()

async realize_all()

source

Compiles and executes the computation graph, realizing all tensors.

Finalizes the computation graph, passes it to the bound Executor, and applies the results to produce concrete values for all pending (unrealized) tensors. After execution, all tensors tracked by this context will have their data in memory.

Returns:

The list of realized output tensors (excluding the internal seed tensor).

Return type:

list[Tensor]

Raises:

TypeError – If called while still inside this realization context.

signal_buffers

signal_buffers: list[BufferValue] | None

source

Signal buffer graph values for multi-device collectives (lazily created).

source_values

source_values: dict[int, Value[Any]]

source

Reverse map of sources (TensorValue for read-only, BufferValue for mutable)

sources

sources: dict[Value[Any], Tensor]

source

Keeps a strong reference to tensor data that we need to compute graph values

unrealized

unrealized: list[ReferenceType[Tensor]]

source

Unrealized values