Planning pipeline
Combine path generation and local improvement through the Light and Heavy contraction-planning presets.
On this page
Search in a single call
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 for the differences.
Candidate-tree diagrams and selection principles are covered in tensor networks and contraction paths; the objective is defined in path metrics and objectives.
Public Python interface
| 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 for runnable examples and the Python API for full signatures.
Common parameters
| 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 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
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 |
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 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.
Slicing limits
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 for usage.