Rust API

Look up interfaces for automatic path optimization, path generation, tree search, network simplification, slicing, and file I/O.

Automatic path optimization

Before calling Light / Heavy from Rust, set ARCTN_ENGINE_LIBRARY to a compatible compiled library; see Installation configuration. The standalone algorithms and numerical execution functions below do not depend on this library.

use arctn::{
    auto_path_preset_with_objective, AutoPreset,
    PlannerObjective, TensorNetwork,
};

let objective = PlannerObjective::new(1.0, 64.0)?;
let plan = auto_path_preset_with_objective(
    &net, AutoPreset::Heavy, 0, None, objective,
)?;

Core types and modules

Low-level modules

Low-level functions can be called independently. Their parameters are separate from the Python Light / Heavy interfaces.

Path generation

The signatures below omit pub and use short type names. Except for single-pass deterministic greedy search, functions without an objective parameter use PlannerObjective::FIXED, namely $F+64R$.

greedy

fn greedy(
    net: &TensorNetwork,
) -> Result<(SsaPath, PathStats), String>;

Import arctn::greedy. Runs one deterministic greedy pass with no additional objective parameter.

random_greedy

fn random_greedy(
    net: &TensorNetwork,
    ntrials: usize,
    seed: u64,
) -> Result<(SsaPath, PathStats), String>;

Import arctn::random_greedy. ntrials must be greater than zero. For a custom objective, use arctn::paths::greedy::random_greedy_with_objective, adding objective: PlannerObjective after the parameters above.

random_greedy_simplified

fn random_greedy_simplified(
    net: &TensorNetwork,
    ntrials: usize,
    seed: u64,
) -> Result<(SsaPath, PathStats), String>;

Import arctn::random_greedy_simplified. Searches the reduced network and returns a complete path for the original network.

optimal_dp

fn optimal_dp(
    net: &TensorNetwork,
    max_n: usize,
) -> Result<(SsaPath, PathStats), String>;

Import arctn::optimal_dp. max_n limits the tensor count of the complete input network. arctn::paths::optimal::optimal_dp_with_objective adds an objective parameter at the end; see Dynamic programming for its exactness scope.

bisect

fn bisect(
    net: &TensorNetwork,
    ntrials: usize,
    seed: u64,
    cutoff: usize,
) -> Result<(SsaPath, PathStats), String>;

Import arctn::paths::bisect::bisect. cutoff is restricted to 2–20. In the same module, bisect_with_objective adds an objective parameter at the end to compare complete candidates; DP within small subproblems still uses the default objective.

order_dp

fn order_dp(
    net: &TensorNetwork,
    order: &[usize],
) -> Result<(SsaPath, PathStats), String>;

Import arctn::paths::ordertree::order_dp. order must contain every input ID exactly once; only parenthesizations preserving that leaf order are optimized. The same module provides order_dp_with_objective with an objective parameter at the end.

Tree search and reconfiguration

The following functions are in arctn::tree. All except treesa_path are also exported from the arctn root module. Each has a *_with_objective variant in the same module with a final objective: PlannerObjective parameter; versions without it use the default objective $F+64R$.

reconfigure_path

fn reconfigure_path(
    net: &TensorNetwork,
    path: &SsaPath,
    subtree_size: usize,
    max_sweeps: usize,
) -> Result<(SsaPath, PathStats), String>;

subtree_size limits the number of input nodes in the local subnetwork, which need not equal the number of original tensors.

anneal_path

fn anneal_path(
    net: &TensorNetwork,
    path: &SsaPath,
    niters: usize,
    seed: u64,
    t0_rel: f64,
    t1_rel: f64,
) -> Result<(SsaPath, PathStats), String>;

Runs one simulated annealing chain, with relative temperature changing from t0_rel to t1_rel.

anneal_paths

fn anneal_paths(
    net: &TensorNetwork,
    path: &SsaPath,
    chains: usize,
    niters: usize,
    seed: u64,
) -> (SsaPath, PathStats);

Runs multiple independent annealing chains and returns one best path. chains=0 is treated as at least one chain. This function does not return Result; an invalid initial path may panic. Validate the network and path before calling.

treesa_path

fn treesa_path(
    net: &TensorNetwork,
    path: &SsaPath,
    chains: usize,
    beta0: f64,
    beta1: f64,
    beta_steps: usize,
    sweeps_per_beta: usize,
    reconf_interval: usize,
    reconf_size: usize,
    seed: u64,
) -> Result<(SsaPath, PathStats), String>;

Advances through inverse temperatures, repeatedly sweeping the tree. reconf_interval=0 disables periodic subtree reconfiguration.

temper_path

fn temper_path(
    net: &TensorNetwork,
    path: &SsaPath,
    n_replicas: usize,
    rounds: usize,
    moves_per_round: usize,
    t_min: f64,
    t_max: f64,
    reconf_interval: usize,
    reconf_size: usize,
    seed: u64,
) -> Result<(SsaPath, PathStats), String>;

All replicas start from the same path; local updates alternate with exchanges between adjacent temperatures.

temper_paths

fn temper_paths(
    net: &TensorNetwork,
    init_paths: &[SsaPath],
    n_replicas: usize,
    rounds: usize,
    moves_per_round: usize,
    t_min: f64,
    t_max: f64,
    reconf_interval: usize,
    reconf_size: usize,
    seed: u64,
    patience: usize,
) -> Result<(SsaPath, PathStats), String>;

Initializes from a nonempty set of starting paths. patience=0 disables stopping after consecutive rounds without improvement; the best path retained during the run is still returned.

Network simplification and path validation

The following functions are all exported from the arctn root module. Structural simplification does not execute numerical arrays.

simplify

fn simplify(
    net: &TensorNetwork,
) -> Simplified;

Returns prefix, reduced, and map. This function does not report input errors through Result; validate the network before calling.

stitch

fn stitch(
    n_orig: usize,
    prefix: &SsaPath,
    map: &[usize],
    reduced_path: &SsaPath,
) -> SsaPath;

The prefix and mapping must come from the same simplification, and the reduced path must match that reduced network. Check the stitched path with simulate_path.

simulate_path

fn simulate_path(
    net: &TensorNetwork,
    path: &SsaPath,
) -> Result<PathStats, String>;

Checks SSA references and the final result and recomputes path metrics without executing tensor arrays.

Slice selection

Fixed-path slice selection leaves the supplied path unchanged. For execution, see Fixed-path slicing and execution.

find_slices_to_size

fn find_slices_to_size(
    net: &TensorNetwork,
    path: &SsaPath,
    target_size: usize,
) -> Option<SliceResult>;

Import arctn::find_slices_to_size. The target is an element count. Returns None if the target is zero or no valid scheme satisfying the limit is found.

Numerical execution

contract_network

fn contract_network<T: Scalar>(
    net: &TensorNetwork,
    tensors: Vec<DenseTensor<T>>,
    path: &SsaPath,
) -> Result<DenseTensor<T>, String>;

Import arctn::contract_network. Executes the supplied SSA path without searching again or selecting slices. Input array order and dimensions must match the network; output axes follow net.output. tensors is passed by value, transferring ownership into the function. Invalid inputs or paths return Err(String).

For repeated execution with a fixed network and path, use CompiledContraction; see Compilation and reuse.

Sliced execution

use arctn::{
    auto_path_preset_to_size, contract_network_sliced,
    AutoPreset,
};

let plan = auto_path_preset_to_size(
    &net, AutoPreset::Heavy, 0, None, 1 << 24,
)?;
let slice = plan.slice.as_ref().ok_or("missing slice plan")?;
let out = contract_network_sliced(
    &net, &tensors, &plan.path, &slice.legs,
)?;

Reading and writing path files

Version 1 files store only an identifier for checking the network, not its structure, so the network must be supplied when loading. Version 2 files also contain the normalized network structure. Legacy files without a format identifier still require explicit permission to load.