---
title: "Python API"
description: "Look up functions, parameters, and return values for path optimization, persistence, numerical execution, and integrations."
eyebrow: "API reference"
---

## Common parameters and API groups {#exports}

Light / Heavy entry points require the full Python wheel or a separately configured compatible compiled library; see [Installation](/docs/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 {#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](/docs/quick-start) and the [examples](/docs/tutorial-heavy).

| 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](/docs/parallelism#auto-starts) |
| `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](/docs/tensor-network#validation). `target_size` is measured in elements, not bytes, RSS, or GPU memory. For array backends and asynchronous timing, see [Execution backends](/docs/execution-backends).

## Path optimization {#search-apis}

### arctn_path {#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 {#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](/docs/tutorial-heavy#read).

## Saving and loading {#saved-paths}

### arctn_plan {#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 {#execution-plan}

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](/docs/tutorial-reuse).

#### Creating a plan from a report {#plan-from-schedule}

```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 {#plan-load}

```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 {#plan-from-dict}

```python
ArcTNExecutionPlan.from_dict(artifact)
```

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

#### Saving a file {#plan-save}

```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 {#plan-to-dict}

```python
plan.to_dict()
```

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

#### Validating a network or arrays {#plan-validate}

```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 {#plan-to-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 {#plan-to-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 {#plan-compile}

```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 {#plan-execute}

```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 {#execution-apis}

### arctn_contract {#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](/docs/execution-backends) for all fields.

## Compilation and reuse {#compiled-apis}

### ArcTNCompiledContraction {#compiled}

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 {#compiled-compile}

```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 {#compiled-execute}

```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](/docs/tutorial-reuse#compile).

## Integrations {#integration-apis}

### arctn_tree {#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 {#optimizer}

```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](/docs/tutorial-quimb) for examples.

#### Returning a path {#optimizer-call}

```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 {#optimizer-search}

```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 {#optimizer-simplify}

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

## Network simplification {#simplification-api}

### arctn_simplify {#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](/docs/simplification) for the rules.

## Error handling {#errors}

- 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](/docs/validation) for examples.