cotengra

library0.8.1pypypi✓ verified 86d ago

cotengra is a Python library designed for the hyper-optimized contraction of large tensor networks and einsums. It provides advanced pathfinding algorithms, including those based on hyper-optimization, to minimize computational cost (FLOPs, memory). The current version is 0.7.5, and it is actively maintained with regular releases focusing on performance enhancements, new optimization strategies, and bug fixes.

data ai-ml

pip install cotengra

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · COTENGRA

cotengra

datapythonv0.8.1

Install

1.8s avg

Import

173ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.8.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.180s · 21.5MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.8s · import 0.166s · 22MB

20MB installed

● package 20MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ContractionTree

✓ from cotengra import ContractionTree

HyperOptimizer

✓ from cotengra import HyperOptimizer

contract_path

✓ from cotengra import contract_path

This quickstart demonstrates how to define a tensor network using an einsum expression and array shapes, initialize a `ContractionTree`, tune its contraction path using cotengra's hyper-optimization, and then perform the contraction. It also shows how to get the resulting shape and the optimized path.

import cotengra as ctg import numpy as np import opt_einsum as oe # Define an einsum expression and corresponding tensor shapes expr = 'ijkl,klmn,mnop->ijop' shapes = [(2,3,4,5), (4,5,6,7), (6,7,8,9)] arrays = [np.random.rand(*s) for s in shapes] # Initialize a ContractionTree with the expression and shapes tree = ctg.ContractionTree(expr, shapes) # Tune the contraction path using cotengra's hyper-optimizer # For real use, consider increasing max_time and max_repeats tree.tune(max_time=5, max_repeats=16) # Perform the contraction result = tree.contract(arrays) print("Contraction result shape:", result.shape) print("Optimized path:", tree.path)

Debug

Known issues

breakingThe method for determining the number of workers for non-distributed pools changed significantly. It now prioritizes `COTENGRA_NUM_WORKERS` environment variable, then `OMP_NUM_THREADS`, then `os.cpu_count()`.

fix

Explicitly set `n_workers` in `HyperOptimizer` or `ContractionTree` methods, or manage the `COTENGRA_NUM_WORKERS` environment variable for consistent parallel execution behavior.

affects: >=0.6.1

gotchaThe default hyper-optimizer used by the `'auto'` preset changed from `optuna` to `cmaes` (if available), potentially altering performance characteristics for existing code.

fix

To explicitly use `optuna` or `cmaes`, specify `optimizer_options={'optlib': 'optuna'}` or `{'optlib': 'cmaes'}` when initializing `HyperOptimizer` or calling `tree.tune()`.

affects: >=0.7.0

gotchaBehavior of `strip_exponent` with `gather_slices` and `check_zero` changed. Slices with zero value will now return `float('-inf')` as exponent, and `gather_slices` combines exponents.

fix

Review code that relies on the exact numerical representation of exponents when using `strip_exponent` with slicing, especially for zero-value slices. Adapt expectations for `float('-inf')` and combined exponents.

affects: >=0.7.2

gotchaWarnings about missing recommended dependencies (e.g., `optuna`, `cmaes`) are now only issued when those dependencies would actually be used (e.g., during hyper-optimization calls).

fix

Ensure `optuna` or `cmaes` are installed (e.g., `pip install cotengra[optuna,cmaes]`) if you intend to use advanced hyper-optimization features to avoid runtime warnings and ensure full functionality.

affects: >=0.7.5

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'optuna'

Attempting to use `HyperOptimizer` or `ContractionTree.tune()` with an optimization method that requires `optuna` or `cmaes` without having the respective library installed.

fix

Install the required optional dependency: `pip install cotengra[optuna]` or `pip install cotengra[cmaes]` (or both with `pip install cotengra[optuna,cmaes]`).

ValueError: input '...' has shape '(D1,D2,...)' but need '(...)' for index 'x'

The dimensions implied by the einsum expression for a given index do not match the actual dimension of the corresponding array.

fix

Carefully check the `expr` string and ensure that the `shapes` provided in the list match the order and dimensions of the indices for each tensor.

TypeError: 'NoneType' object is not callable (often related to multiprocessing in notebooks)

Multiprocessing pools (used for optimization) can fail to initialize correctly in interactive environments like Jupyter notebooks or on Windows without proper guards.

fix

When using `HyperOptimizer` or `ContractionTree.tune()` in an interactive environment, consider setting `n_workers=1` explicitly. If using a script with custom multiprocessing, ensure code that creates child processes is guarded by `if __name__ == '__main__':`.

Upgrade

Version history

0.8.1latest on PyPI · released Jun 8, 2026

Audit

Dependencies

optunaoptionalProvides the 'optuna' hyper-optimization backend for pathfinding. Recommended for optimal performance.

cmaesoptionalProvides the 'cmaes' hyper-optimization backend. Used by default for the 'auto' preset from v0.7.0 if available.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jcmgray/cotengra ↗

packagehttps://pypi.org/project/cotengra/ ↗

docshttps://cotengra.readthedocs.io/ ↗

changeloghttps://cotengra.readthedocs.io/en/latest/changelog.html ↗