---
title: "Planning pipeline"
description: "Combine path generation and local improvement through the Light and Heavy contraction-planning presets."
eyebrow: "Automatic contraction planning"
---

## Search in a single call {#scope}

ArcTN offers Light and Heavy search modes, combining path generation, local improvement, and result selection in one call. Provide a tensor network and optimization objective, then choose `preset="light"` or `preset="heavy"` without invoking individual low-level search methods.

A candidate here is a complete contraction path: it specifies every pairwise contraction from the input tensors to the final result, rather than just the two tensors selected for one step. The planning pipeline schedules the generation and improvement of these paths and compares them using the objective for the current call.

| Stage | Work performed |
| --- | --- |
| Generate candidates | Apply methods such as randomized greedy search and hypergraph bisection to the original and simplified networks, as selected by the preset |
| Improve paths | Apply local searches such as subtree reconfiguration and tempering, according to the preset and stopping conditions |
| Return a result | Select a path using the current objective; handle slicing constraints if `target_size` is requested |

Simplification fixes some contraction steps, then searches the smaller remaining network. Joining the two parts still gives a complete path on the original input network, so it can be compared with paths generated directly on that network. The preset determines the generation and improvement methods; stopping conditions may cause some stages to be skipped. See [Light / Heavy interfaces](/docs/auto-light-heavy#comparison) for the differences.

Candidate-tree diagrams and selection principles are covered in [tensor networks and contraction paths](/docs/tensor-network#candidate-set); the objective is defined in [path metrics and objectives](/docs/path-metrics#definition).

## Public Python interface {#basic-usage}

| Entry point | When to use it | Result |
| --- | --- | --- |
| arctn\_path | Plan a path with Light or Heavy | An SSA or linear path |
| arctn\_schedule | Inspect the path, work estimates, and slicing information | A dictionary containing the path, objective, metrics, and optional slicing results |
| arctn\_plan | Plan and retain network and slicing information | A persistable ArcTNExecutionPlan |
| arctn\_tree | Convert a plan to a Cotengra ContractionTree | A tree usable by Cotengra / Quimb |
| arctn\_contract | Execute numerical contraction immediately after planning | The numerical result and optional final information |

See the [quick start](/docs/quick-start) for runnable examples and the [Python API](/docs/python-api) for full signatures.

## Common parameters {#public-controls}

| Parameter | Purpose | Notes |
| --- | --- | --- |
| preset | Select `light` or `heavy` | Defaults to `heavy` |
| seed | Set the base seed for this search | Controls random search choices, not input-array values |
| max\_time | Search time limit in seconds | Checked at algorithm checkpoints; the call may return slightly later |
| flops\_weight / read\_write\_weight | Fix the complete-path objective for this call | Must be finite, nonnegative, and not both zero |
| target\_size | Bound the largest intermediate tensor in each slice, in elements | Not an RSS, device-memory, or total concurrent-slice memory limit |
| slicing\_mode | Select `fixed` or `dynamic` | `dynamic` also requires `target_size` |
| rate\_enabled | Enable early stopping based on estimated contraction work | Applies to `arctn_schedule` and `arctn_plan`; defaults to `True` |

`target_size` and `slicing_mode` apply to `arctn_schedule`, `arctn_plan`, `arctn_tree`, and `arctn_contract`. `arctn_path`, which returns only a path, does not accept them.

The weights determine what matters most when comparing paths. For example, `flops_weight=1` and `read_write_weight=0` select solely by FLOPs; the default `(1, 64)` considers both FLOPs and logical memory traffic. See the [objective definition](/docs/path-metrics#definition) for definitions and numerical examples.

`rate_enabled=False` disables only this early-stopping criterion, not the search algorithms' own convergence checks or `max_time`. A fixed random seed does not imply identical timing on every run. If the entire process must terminate immediately at a deadline, enforce a timeout outside the call, for example with a job scheduler.

## Returned results {#guarantees}

`arctn_schedule` returns a path and structured report. `arctn_plan` returns an `ArcTNExecutionPlan` containing the network, path, and slicing information for subsequent execution.

| Content | Meaning |
| --- | --- |
| `path` | Complete contraction path on the original input network |
| `log10_flops`, `log2_read_write`, etc. | Structural counts for the returned path; see [path metrics](/docs/path-metrics) |
| `planner_objective` and weights | Objective used for this search |
| `sliced_legs` and `sliced_*` fields | Optional slicing-index set and post-slicing metrics |

The report lets you inspect the returned path and its metrics, but the final report alone cannot reconstruct all unpublished search candidates. See [Using Heavy: reading the result](/docs/tutorial-heavy#read) for field definitions.

Light and Heavy use heuristic search. Neither guarantees a globally optimal result, and early stopping does not prove local optimality. See [what the best candidate means](/docs/tensor-network#optimality).

## Slicing limits {#slicing}

When `target_size` is supplied, a successful result respects the element-count bound for every pairwise contraction result within each slice; single-tensor networks also check the final output. The interface returns an error if it cannot meet the bound. `target_size` is not a limit on process RSS, device memory, or the combined memory of concurrent slices.

See [controlling intermediate tensors](/docs/tutorial-slicing) for usage.