ArcTN Rust-native tensor-network contraction planning

ArcTN is a Rust tensor-network library for contraction-path optimization, slicing, and numerical execution, with Python integration for Quimb, opt_einsum, and other tools. ArcTN accepts tensor networks; it does not directly convert quantum-circuit tasks into networks. Build those networks with a frontend such as Quimb or supply them yourself.

Licensing and permitted use

Source code that the company is entitled to license is governed by the Arclight Non-Commercial Source-Available License 1.0, which prohibits commercial use and closed-source integration. This is not an OSI-approved open-source license. Commercial use requires separate authorization.

• Third-party dependencies retain their own licenses. Versions previously licensed under MIT / Apache retain the rights already granted; see third-party and historical licensing notices.
• Light / Heavy dynamic libraries are licensed separately. The source license for company code does not authorize their use or distribution. Their external distribution terms have not yet been determined, and neither the initial source release nor wheels built from that source include them.

See the ArcTN repository license section for full details. Commercial licensing and license inquiries: quill@arclightquantum.com.

Tensor networks and binary contraction trees

A tensor network describes how tensors connect through indices. With pairwise contraction, the computation can be represented by a binary contraction tree: leaves are input tensors, internal nodes are contractions, and the root is the final result.

One network can have different contraction trees. Consider the four-matrix product $ABCD$ below: both orders produce the same $2\times2$ result, but require different amounts of computation.

A contraction tree describes how tensors combine; a contraction path lists the actual computation steps. For example, the first tree permits either $AB$ or $CD$ to be computed first, followed by their combination. Contraction-path optimization searches different trees and selects a lower-cost order according to objectives such as computation and memory traffic. Light / Heavy use heuristic search and do not guarantee global optimality. See tensor networks and contraction trees.

Planning and execution

Describe a tensor network with inputs, output, and size_dict, and specify an objective to optimize its contraction path.

When intermediate tensors are too large, set target_size to split a large contraction into smaller sliced contractions. target_size bounds the element count of any single contraction result within each slice: for example, one million float64 elements occupy about 8 MB. It does not bound total program memory; input arrays and temporary computation space must be counted separately.

ArcTN supports both planning alone and numerical computation. Save a path and slicing scheme as an ArcTNExecutionPlan, an intermediate representation (IR) between planning and execution. With arrays supplied, arctn_contract can plan and execute directly. Existing Quimb networks can also use ArcTN plans through ArcTNOptimizer.

For quantum circuits, use the Quimb frontend: build the circuit in Quimb and pass optimize=ArcTNOptimizer(...) when computing amplitudes or expectation values. ArcTN then optimizes the path without requiring you to assemble inputs, output, and size_dict manually. Quimb converts the task into a network and may simplify it before search; Quimb / Cotengra perform numerical contraction.

VQE, QAOA, and quantum machine learning

In these algorithms, a circuit frontend builds the tensor network for an amplitude, probability, or expectation value from a parameterized circuit. ArcTN optimizes its contraction path, and an outer classical optimizer updates circuit parameters from the results. With Quimb, integrate through optimize=ArcTNOptimizer(...) and execute through Quimb / Cotengra; alternatively, pass the network and arrays directly to arctn_contract.

After parameter updates, reuse an existing path if tensor order, index correspondence, dimensions, and output order remain unchanged. ArcTN is not a complete quantum machine-learning training framework: the application or framework handles losses, parameter gradients, and training loops. See the VQE and QAOA examples and path reuse when parameters change.

From quantum circuit to contraction result

Two qubits start in $|00\rangle$ and undergo H, $R_y(\pi/3)$, CNOT, and $R_y(\pi/4)$ in sequence. To compute the final probability of measuring 11, first find the amplitude $A_{11}=\langle11|U|00\rangle$, then evaluate $P(11)=|A_{11}|^2$. The basis order here is $|q_0q_1\rangle$.

Inspecting contractions step by step

Express the initial state, quantum gates, and terminal $\langle1|$ as tensors, then ask ArcTN to search for a path. The diagram matches circuit gates to tensors; click the next-step button to inspect the generated path and intermediate results.

The NumPy run control computes the amplitude and probability along this path and compares them with ArcTN, a direct contraction, and an independent state-vector calculation.

{
  "ssa_path": [[4, 7], [0, 2], [8, 9], [1, 3], [5, 6], [10, 11], [12, 13]],
  "linear_path": [[4, 7], [0, 2], [4, 5], [0, 1], [0, 1], [0, 1], [0, 1]],
  "metrics": {
    "log10_flops": 1.6232492903979006,
    "log2_max_size": 3,
    "log2_max_contraction_size": 4.700439718141093,
    "log2_total_size": 4.392317422778761,
    "log2_read_write": 6.266786540694901,
    "log2_peak_size": 5.459431618637297,
    "log2_n_slices": null,
    "sliced_log10_flops_total": null,
    "sliced_log2_max_size": null,
    "sliced_log2_max_contraction_size": null,
    "sliced_log2_peak_size": null,
    "max_intermediate_log2_elements_per_slice": null
  }
}

tensors = store input arrays by SSA ID(arrays)
for left, right, out, axis_orders, matrix_shapes, output_shape in contractions:
    A = reorder axes and reshape as matrix(tensors[left], axis_orders.left, matrix_shapes.left)
    B = reorder axes and reshape as matrix(tensors[right], axis_orders.right, matrix_shapes.right)
    tensors[out] = reshape(A @ B, output_shape)
    del tensors[left], tensors[right]
amplitude = take final tensor(tensors)
probability = abs(amplitude) ** 2
compare amplitude(amplitude, ArcTN result, direct contraction result, state-vector result)
return amplitude, probability

• Quick start — Begin with a smaller Python example.

Numerical execution and integrations

Direct contraction execution

With numerical arrays supplied, arctn_contract performs planning, optional slicing, and execution in one call. It defaults to the native ArcTN CPU executor, with explicit external-array backends also available. return_info=True returns planning and execution reports alongside the result.

• Numerical execution — Array types, contraction steps, and returned information.
• Slicing example — Set target_size and choose Fixed or Dynamic slicing.

Using Quimb

Pass an ArcTNOptimizer to Quimb through optimize= to use ArcTN path search. ArcTNOptimizer.search() returns a ContractionTree with the path and slicing indices; Quimb / Cotengra perform subsequent numerical contraction.

• Quimb example

Saving and reusing paths

With the same structure and dimensions, changing array values does not require a new path search. Use arctn_plan to obtain the path and slicing information, and save it for later contractions.

• Saving and reusing paths

Core capabilities

Scope and boundaries

• The native executor uses CPUs; CuPy, PyTorch, and JAX arrays run through their explicitly selected external backends.

• Slicing does not perform low-rank truncation. Currently only internal indices are sliced: all values are enumerated and their results summed. Output indices remain intact and are not sliced.

• Light, Heavy, and most local-search methods are heuristic and do not guarantee global optimality. Dynamic programming is suitable for small subproblems; see its search scope.

• max_time is checked at algorithm checkpoints, not enforced as a process timeout. Use an external process or job scheduler for a strict limit.

• Compatibility and limitations

• Benchmark suite