Changelog

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)