Python API

Look up functions, parameters, and return values for path optimization, persistence, numerical execution, and integrations.

On this page

Common parameters and API groups

Light / Heavy entry points require the full Python wheel or a separately configured compatible compiled library; see Installation. Executing an existing path and simplifying a network do not require Light / Heavy.

Category	API	Returns
Path optimization	`arctn_path`, `arctn_schedule`	A path, or a report with the path and metrics
Saving and loading	`arctn_plan`, `ArcTNExecutionPlan`	An object storing the network, path, and slicing information
Numerical contraction	`arctn_contract`	The result, optionally with an execution report
Compilation and reuse	`ArcTNCompiledContraction`	A reusable compiled object
Integrations	`arctn_tree`, `ArcTNOptimizer`	A Cotengra contraction tree or an `ArcTNOptimizer` object
Network simplification	`arctn_simplify`	A simplification prefix and reduced-network information

Common parameters

These parameters are available only where listed in the corresponding function signature. A * means that subsequent parameters must be passed by name. The signatures below list parameters and defaults; runnable calls appear in Quick start and the examples.

Parameter	Type	Meaning
`inputs`	`Sequence[Sequence[Hashable]]`	Index labels for each tensor; the inner order matches array axes
`output`	`Sequence[Hashable]`	Indices to retain, in result-axis order
`size_dict`	`Mapping[Hashable, int]`	Positive integer dimensions for all used indices, with no missing or extra entries
`preset`	`"light" \\| "heavy"`	Planning preset; defaults to Heavy
`seed`	`int`	Base random seed; seeds for additional independent Light and Heavy starts are derived from it; see Single-machine parallelism
`max_time`	`float \\| None`	Planning time limit in seconds; if provided, it must be finite and positive and takes effect at algorithm checkpoints
`flops_weight`	`float`	Finite, nonnegative FLOPs weight
`read_write_weight`	`float`	Finite, nonnegative read/write weight; the two weights cannot both be 0
`target_size`	`int \\| None`	Maximum element count of each binary contraction result per slice; for a single-tensor network, checks the final output
`slicing_mode`	`"fixed" \\| "dynamic"`	Fixed preserves the path; Dynamic permits path changes and requires `target_size`
`use_ssa`	`bool`	Return SSA encoding; otherwise return a linear path with stepwise renumbering
`rate_enabled`	`bool`	Enable rate-based early stopping; disabling it leaves other stopping conditions active
`backend`	`str`	`"native"` or an explicit array-backend name; `"auto"` is not accepted
`return_info`	`bool`	Also return an information dictionary

For network input rules, see Tensor-network input. target_size is measured in elements, not bytes, RSS, or GPU memory. For array backends and asynchronous timing, see Execution backends.

Path optimization

arctn_path

python

arctn_path(
    inputs,
    output,
    size_dict,
    *,
    preset="heavy",
    seed=0,
    use_ssa=False,
    max_time=None,
    flops_weight=1.0,
    read_write_weight=64.0,
)

Returns list[tuple[int, int]]. Searches for a path without executing arrays. Returns a linear path by default, or an SSA path with use_ssa=True. This function does not accept slicing parameters because a path list cannot also carry sliced indices.

arctn_schedule

python

arctn_schedule(
    inputs,
    output,
    size_dict,
    *,
    preset="heavy",
    seed=0,
    target_size=None,
    slicing_mode="fixed",
    max_time=None,
    use_ssa=False,
    flops_weight=1.0,
    read_write_weight=64.0,
    rate_enabled=True,
)

Returns a dict containing the path, objective weights, path metrics, search time wall_s recorded by the compiled library, and optional slicing information. It does not read or execute numerical arrays or return internal candidates and stage records. For fields and examples, see Using Heavy: reading the result.

Saving and loading

arctn_plan

python

arctn_plan(
    inputs,
    output,
    size_dict,
    *,
    preset="heavy",
    seed=0,
    target_size=None,
    slicing_mode="fixed",
    max_time=None,
    flops_weight=1.0,
    read_write_weight=64.0,
    rate_enabled=True,
)

Returns ArcTNExecutionPlan. Plans without executing arrays. The object stores the network, SSA path, and slicing information, but no numerical arrays, devices, or compiled kernels.

ArcTNExecutionPlan

An ArcTNExecutionPlan can be saved to a file and loaded in another process. It can also be converted to a contraction tree, or compiled for repeated execution when unsliced. For a complete example, see Saving and reusing paths.

Creating a plan from a report

python

ArcTNExecutionPlan.from_schedule(
    report,
    *,
    inputs,
    output,
    size_dict,
)

report must contain an SSA path, generated with arctn_schedule(..., use_ssa=True). All three network parameters are required. Returns ArcTNExecutionPlan without searching again.

Loading from a file

python

ArcTNExecutionPlan.load(path)

Reads and validates a version 2 JSON file containing the complete network and returns ArcTNExecutionPlan. Validation failures raise PlanValidationError; missing or unreadable files may still raise filesystem exceptions.

Loading from a dictionary

python

ArcTNExecutionPlan.from_dict(artifact)

Loads a parsed dictionary using the same validation rules as file loading.

Saving a file

python

plan.save(path)

Atomically writes the network, path, and slicing information as JSON. Arrays and in-process compilation state are not saved.

Exporting a dictionary

python

plan.to_dict()

Returns a serializable dictionary containing the network, path, and slicing information.

Validating a network or arrays

python

plan.validate(
    inputs=None,
    output=None,
    size_dict=None,
    *,
    arrays=None,
)

Either omit all three network parameters or provide all three together. Optionally pass arrays to check the array count, shapes, and data types. Returns None on success and raises PlanValidationError on failure.

Converting to a linear path

python

plan.to_linear_path()

Returns the linear path used by opt_einsum without replanning. The list itself carries no slicing information.

Converting to a contraction tree

python

plan.to_tree()

Returns a Cotengra ContractionTree containing the existing path and sliced indices. Requires Cotengra; does not search again.

Compiling a path

python

plan.compile(
    *,
    backend="native",
)

Returns ArcTNCompiledContraction. Available only when the actual slice set is empty; use plan.execute() for sliced plans.

Executing a saved path

python

plan.execute(
    arrays,
    *,
    backend="native",
    return_info=False,
)

Executes the saved path and slicing scheme without replanning. Returns the result array by default, or (result, info) with return_info=True. Information fields depend on the execution method; do not assume they exactly match the timing fields of arctn_contract.

Numerical contraction

arctn_contract

python

arctn_contract(
    inputs,
    output,
    size_dict,
    arrays,
    *,
    preset="heavy",
    seed=0,
    target_size=None,
    slicing_mode="fixed",
    max_time=None,
    backend="native",
    flops_weight=1.0,
    read_write_weight=64.0,
    return_info=False,
)

Returns the result array or (result, info). The native backend returns a NumPy array; external backends return objects from the corresponding array library. All inputs must share one supported data type: float32, float64, complex64, or complex128.

External backends may execute asynchronously. A host function returning does not imply device computation has finished; explicitly synchronize when measuring GPU time. execution_wall_s is provided only for native and numpy and is None for other backends. See Execution backends for all fields.

Compilation and reuse

ArcTNCompiledContraction

Prepares execution for a fixed network and SSA path: the native backend prepares axis transformations and matrix-multiplication parameters, while external backends compile an opt_einsum expression. The object is local to the current process and cannot be saved to a file.

Creating a compiled object

python

ArcTNCompiledContraction.compile(
    inputs,
    output,
    size_dict,
    *,
    ssa_path,
    backend="native",
)

ssa_path must be complete and valid. Compilation does not search for a path and does not support slice sets.

Execution and statistics

python

result = compiled.execute(arrays)
info = compiled.stats()

Calling compiled(arrays) is equivalent to execute. Repeated calls use the same network and path, with input validation on every call. See Compiling for repeated execution.

Integrations

arctn_tree

python

arctn_tree(
    inputs,
    output,
    size_dict,
    *,
    preset="heavy",
    seed=0,
    target_size=None,
    slicing_mode="fixed",
    max_time=None,
    flops_weight=1.0,
    read_write_weight=64.0,
    return_info=False,
)

Returns a Cotengra ContractionTree or (tree, info). Requires Cotengra and opt_einsum. The tree carries the contraction path and sliced indices for execution by Quimb / Cotengra.

ArcTNOptimizer

python

ArcTNOptimizer(
    *,
    preset="heavy",
    seed=0,
    max_time=None,
    flops_weight=1.0,
    read_write_weight=64.0,
    target_size=None,
    slicing_mode="fixed",
)

ArcTNOptimizer exposes ArcTN path optimization through two interfaces: the opt_einsum path interface and the Cotengra / Quimb contraction-tree interface. See Using ArcTN with Quimb for examples.

Returning a path

python

optimizer(inputs, output, size_dict, memory_limit=None)

Corresponds to ArcTNOptimizer.__call__ and returns a linear path. Because a list cannot represent a slice set, this call raises NotImplementedError if memory_limit is provided or target_size is configured in ArcTNOptimizer.

Returning a contraction tree

python

optimizer.search(inputs, output, size_dict)

Corresponds to ArcTNOptimizer.search and delegates to arctn_tree to return a ContractionTree with slicing information.

Path optimization and network simplification

Use ArcTNOptimizer for path optimization. If only simplified structural information is needed, use arctn_simplify below.

Network simplification

arctn_simplify

python

arctn_simplify(inputs, output, size_dict)

Returns simplification statistics, a prefix, and reduced-network information. Runs neither Light / Heavy search nor array computation. See Network simplification for the rules.

Error handling

Indices in output must be unique and present in the input network; this also applies to planning-only calls.
The same index may appear at most twice within a single input tensor.
The count and shapes of all input arrays must match the network, and all arrays in one execution must share a supported data type.
Weights must be finite, nonnegative, and not both zero.
target_size must be a positive integer. If no compliant plan is found, the interface reports an error without automatically relaxing the constraint.
backend defaults to native; it is neither inferred from the arrays nor changed after a failure.

Common exceptions include TypeError, ValueError, PlanValidationError, NotImplementedError, and ImportError for missing optional dependencies. See Validating inputs and handling errors for examples.

Download source Markdown ↓