Compilation and reuse

Prepare a fixed network and contraction path once, then execute them on multiple sets of numerical arrays.

Compile once, execute repeatedly

When network structure, dimensions, and contraction path stay fixed and only array values change, compile once and execute on multiple array sets. This avoids both replanning and repeatedly preparing the same contraction expression.

Path search decides which two tensors to contract next. Compilation determines the axis permutations and matrix multiplications for each step; execution applies those steps to actual arrays. Reusing a compiled object saves preparation work, but every new array set still requires the corresponding numerical computation.

Compilation here prepares contraction steps for execution; it does not regenerate machine code for each input. The compiled object does not store input values.

What the native backend prepares

Rust CompiledContraction stores axes for unary processing, input-axis permutations for each step, batched-matrix-multiplication shapes, and the final output-axis order. Subsequent execute calls use this information directly.

Every execution still validates input count, shapes, and DenseTensor layout.

steps = prepare axis orders, matrix shapes, and output order from network and path
For each input array set arrays:
    Check whether the arrays match the network
    result = execute numerical contraction using steps

Reusing an object in Python

Assume ssa_path is available and arrays0 and arrays1 contain different numerical values. Both sets follow inputs order and retain the same shape and axis meanings for each array:

from arctn import ArcTNCompiledContraction

compiled = ArcTNCompiledContraction.compile(
    inputs, output, size_dict,
    ssa_path=ssa_path,
    backend="numpy",
)
y0 = compiled.execute(arrays0)
y1 = compiled.execute(arrays1)
print(compiled.stats())

y0 and y1 are the contraction results for the two array sets; the second execute reuses the same compiled object. For example, gate parameters can change in a fixed quantum-circuit structure while reusing the compiled contraction, provided the gate-tensor connectivity and dimensions remain unchanged.

The default is backend="native". Other backends must be selected explicitly; "auto" is not accepted. Install external backends and their dependencies separately.

ssa_path= requires SSA format, not an opt_einsum linear path. SSA uses fixed tensor IDs; a linear path uses positions in the current tensor list, which change after each contraction.

Reuse requirements

ArcTNCompiledContraction is used within the current process. Recompile after changing the network structure, dimensions, or SSA path.

Persist the network, contraction path, and slicing information, not the compiled object. Save and load these through ArcTNExecutionPlan; for an unsliced plan, call plan.compile() once and reuse its result. Repeated unsliced plan.execute() calls also avoid replanning, but create a new compiled object on every call.

The Python compilation interface does not support a nonempty slicing set. Execute a saved sliced plan with ArcTNExecutionPlan.execute(), or pass it to Cotengra through to_tree().

Rust also provides execute_stripped: after each matrix multiplication, if the maximum magnitude is positive and finite, it normalizes by that magnitude and accumulates a separate base-10 scaling exponent. This prevents numerical scales from becoming too large or too small, without truncation or approximation.