Changelog

v0.8.0 (2026-05-04)

Enhancements

  • "auto" and "auto-hq" presets now default to parallel="auto"

  • HyperOptimizer: now defaults to using subtree reconfiguration (turned off if any other refinement options are explitly given)

  • ContractionTree.subtree_reconfigure: add maxiter="auto" option, which defaults to min(tree.N, maxiter_auto_cap), where maxiter_auto_cap is a new argument to the preset constructors (default 128 for auto and 1024 for auto-hq).

  • Added a benchmarking example - Benchmarking and cotengra.

  • Default node type for ContractionTree changed to SSA-based representation, which is faster and uses less memory for big trees. Factored out node logic into a new nodeops module, with dynamic namespaces supporting both frozenset-based and SSA-based nodes.

  • ContractionTree: add get_peak_size, reorder_for_peak_size, and max_contraction_size.

  • ContractionTree: support single input “contractions” (trivial trees with a single tensor).

  • HyperOptimizer.search: support single terms (GH 77).

  • Change default finishing optimize step (e.g. for slicing/subtree reconfigure) to "auto".

  • Subtree reconfigure: add select="descend" mode.

  • PartitionTreeBuilder.build_divide: default to random-greedy-128 for super_optimize.

  • Greedy optimizers: add max_neighbors option to limit candidate pair generation, which helps for graphs with very large batch indices.

  • Allow hashing optimize when given as a list of lists (e.g. nested SSA paths).

  • Refactor the optlib interface for cleaner integration of multiple Bayesian / population-based optimizers; add sbplx, sses (steady-state evolutionary strategy), and neldermead / neldermead-adapt simple internal optimizers.

  • Add implementation="pytblis" for contraction via pytblis.

  • Update parallel logic for sub-workers, allowing nested parallelism without oversubscription.

  • DiskDict: add get, keys, values, items, __delitem__; enhance clear and cleanup methods.

  • Python optimal optimizer: accept float factors (GH 58).

  • Update schematic module with improvements pulled in from quimb.

  • einsum via bmm (implementation="cotengra"): update einsum-string parsing to follow more recent numpy behavior.

Bug fixes

Infrastructure

  • Move CI and developer workflow to Pixi (per-environment jobs, formatting tasks, readthedocs config). Add torch/jax/tensorflow test jobs. Various dependabot bumps.

v0.7.5 (2025-06-12)

Enhancements

  • ContractionTree.print_contractions: fix show_brackets option, show preprocessing steps with original inputs indices.

  • Only warn about missing recommended dependencies when they otherwise would be used, i.e. for hyper optimization only.

v0.7.4 (2025-05-13)

Bug fixes

  • Fix and add egde case test for optimize=() - GH 55

v0.7.3 (2025-05-12)

Enhancements

  • Allow manual path specification as edge path, e.g. optimize=['b', 'c', 'a']

  • Add optimize="edgesort" (aliased to optimize="ncon" too), which performs a contraction by contracting edges in sorted order, thus can be entirely specified by the graph labelling.

  • Add edge_path_to_ssa and edge_path_to_linear for converting edge paths to SSA and linear paths respectively.

  • ContractionTree.from_path: allow an edge_path argument. Deprecate ContractionTree.from_edge_path method in favor of this.

  • Speed up ContractionTree.get_path to ~ n log(n).

v0.7.2 (2025-04-01)

Breaking Changes

  • When contracting with slices and strip_exponent enabled, each slice result is returned with the exponent separately, rather than matching the first, these are are now combined in gather_slices.

  • If check_zero=True, strip_exponent=True, and a zero slice is encountered, the returned exponent will now be float('-inf') rather than 0.0 for compatbility with the above.

v0.7.1 (2025-02-24)

  • ReusableHyperOptimizer and DiskDict, allow splitting key into subdirectory structure (sharding) for better performance. Enabled for new caches by default.

  • High level interface functions accept the strip_exponent kwarg, which eagerly strips a scaling exponent (log10) as the contraction proceeds, avoiding issues to do with very large or very small numeric values.

  • add ReusableRandomGreedyOptimizer for reusing the same random greedy optimizer across multiple contractions, which is faster than creating a new one each time.

v0.7.0 (2025-01-07)

Enhancements

  • Add cmaes as an optlib method, use it by default for 'auto' preset if available since ih has less overhead than optuna.

  • Add HyperOptimizer.plot_parameters_parallel for plotting the sampled parameter space of a hyper optimizer method in parallel coordinates.

  • Add ncon interface.

  • Add utils.save_to_json and utils.load_from_json for saving and loading contractions to/from json.

  • Add examples/benchmarks with various json benchmark contractions

  • Add utils.networkx_graph_to_equation for converting a networkx graph to cotengra style inputs, output and size_dict.

  • Add "max" as a valid minimize option for optimize_optimal (also added to cotengrust), which minimizes the single most expensive contraction (i.e. the cost scaling)

  • Add RandomOptimizer, a fully random optimizer for testing and initialization purposes. It can be used with optimize="random" but is not recommended for actual optimization.

  • Add PathOptimizer to top-level namespace.

  • ContractTreeCompressed.from_path: add the autocomplete option

  • Add option overwrite="improved" to reusable hyper optimizers, which always searches but only overwrites if the new tree is better, allowing easy incremental refining of a collection of trees.

  • einsum via bmm (implementation="cotengra") avoids using einsum for transposing inputs.

  • add example Extract contraction to matmuls only doc

Bug fixes

v0.6.2 (2024-05-21)

Bug fixes

  • Fix final, output contractions being mistakenly marked as not tensordot-able.

  • When implementation="autoray" don’t require a backend to have both einsum and tensordot, instead fallback to cotengra’s own.

v0.6.1 (2024-05-15)

Breaking changes

  • The number of workers initialized (for non-distributed pools) is now set to, in order of preference, 1. the environment variable COTENGRA_NUM_WORKERS, 2. the environment variable OMP_NUM_THREADS, or 3. os.cpu_count().

Enhancements

  • add RandomGreedyOptimizer which is a lightweight and performant randomized greedy optimizer, eschewing both hyper parameter tuning and full contraction tree construction, making it suitable for very large contractions (10,000s of tensors+).

  • add optimize_random_greedy_track_flops which runs N trials of (random) greedy path optimization, whilst computing the FLOP count simultaneously. This or its accelerated rust counterpart in cotengrust is the driver for the above optimizer.

  • add parallel="threads" backend, and make it the default for RandomGreedyOptimizer when cotengrust is present, since its version of optimize_random_greedy_track_flops releases the GIL.

  • significantly improve both the speed and memory usage of SliceFinder

  • alias tree.total_cost() to tree.combo_cost()

v0.6.0 (2024-04-10)

Bug fixes

  • all input node legs and pre-processing steps are now calculated lazily, allowing slicing of indices including those ‘simplified’ away GH 31.

  • make tree.peak_size more accurate, by taking max assuming left, right and parent intermediate tensors are all present at the same time.

Enhancements

  • add simulated annealing tree refinement (in path_simulated_annealing.py), based on “Multi-Tensor Contraction for XEB Verification of Quantum Circuits” by Gleb Kalachev, Pavel Panteleev, Man-Hong Yung (arXiv:2108.05665), and the “treesa” implementation in OMEinsumContractionOrders.jl by Jin-Guo Liu and Pan Zhang. This can be accessed most easily by supplying opt = HyperOptimizer(simulated_annealing_opts={}).

  • add ContractionTree.plot_flat: a new method for plotting the contraction tree as a flat diagram showing all indices on every intermediate (without requiring any graph layouts), which is useful for visualizing and understanding small contractions.

  • HyperGraph.plot: support showing hyper outer indices, multi-edges, and automatic unique coloring of nodes and indices (to match plot_flat).

  • add `ContractionTree.plot_circuit for plotting the contraction tree as a circuit diagram, which is fast and useful for visualizing the traversal ordering for larger trees.

  • add ContractionTree.restore_ind for ‘unslicing’ or ‘unprojecting’ previously removed indices.

  • ContractionTree.from_path: add option complete to automatically complete the tree given an incomplete path (usually disconnected subgraphs - GH 29).

  • add ContractionTree.get_incomplete_nodes for finding all uncontracted childless-parentless node groups.

  • add ContractionTree.autocomplete for automatically completing a contraction tree, using above method.

  • tree.plot_flat: show any preprocessing steps and optionally list sliced indices

  • add get_rng as a single entry point for getting or propagating a random number generator, to help determinism.

  • set autojit="auto" for contractions, which by default turns on jit for backend="jax" only.

  • add tree.describe for a various levels of information about a tree, e.g. tree.describe("full") and tree.describe("concise").

  • add ctg.GreedyOptimizer and ctg.OptimalOptimizer to the top namespace.

  • add ContractionTree.benchmark for for automatically assessing hardware performance vs theoretical cost.

  • contraction trees now have a get_default_objective method to return the objective function they were optimized with, for simpler further refinement or scoring, where it is now picked up automatically.

  • change the default ‘sub’ optimizer on divisive partition building algorithms to be 'greedy' rather than 'auto'. This might make individual trials slightly worse but makes each cheaper, see discussion: (GH 27).

v0.5.6 (2023-12-07)

Bug fixes

  • fix a very rare but very infuriating bug related somehow to ReusableHyperOptimizer not being thread-safe and returning the wrong tree on github actions

v0.5.5 (2023-11-15)

Enhancements

  • HyperOptimizer: by default simply warn if an individual trial fails, rather than raising an exception. This is to ensure rare failures do not spoil an entire optimization run. The behavior can be controlled with the on_trial_error argument.

Bug fixes

  • fixed bug in greedy optimizer that produced negative scores and otherwise inaccurate scores.

  • fixed bug for contraction with many inputs and also preprocessing steps

v0.5.4 (2023-10-17)

Bug fixes

  • the auto and auto-hq optimizers are now safe to run under multi-threading.

v0.5.3 (2023-10-16)

  • einsum, einsum_tree and einsum_expression: add support for all numpy input formats, including interleaved indices and ellipses.

  • remove some hidden opt_einsum dependence (via a PathOptimizer method)

v0.5.2 (2023-10-13)

v0.5.1 (2023-10-3)

v0.5.0 (2023-09-26)