Installation

cotengra is available on both pypi and conda-forge. While cotengra is pure python itself, the preferred way to install it is with pixi, which creates isolated and reproducible environments that can mix packages from conda-forge (the default) and also pypi.

Installing with pixi (preferred):

pixi init cotengra-project
cd cotengra-project
pixi add cotengra

Installing with pip:

pip install cotengra
# or
uv pip install cotengra

It is recommended to use uv to install and manage purely pypi based environments.

Installing with conda / mamba:

conda install -c conda-forge cotengra

miniforge is the recommended way to manage and install a conda-based environment.

Installing the latest version directly from github:

If you want to checkout the latest version of features and fixes, you can install directly from the github repository:

pip install -U git+https://github.com/jcmgray/cotengra.git

Installing a local, editable development version:

If you want to make changes to the source code and test them out, you can install a local editable version of the package:

git clone https://github.com/jcmgray/cotengra.git
pip install --no-deps -U -e cotengra/

Other than that, the optional dependencies are detailed below.

Hint

The recommended selection of optional dependencies from below covering most use-cases is:

autoray cmaes cotengrust cytoolz kahypar loky networkx opt_einsum optuna tqdm

Contraction

If you want to perform the contractions using cotengra itself you’ll need:

which supports at least numpy, cupy, torch, tensorflow, jax, and autograd among others.

Optimization

  • kahypar - Karlsruhe Hypergraph Partitioning for high quality divisive tree building (available via pip, unfortunately not yet via conda or for windows)

  • cotengrust - rust accelerated pathfinding primitives

  • tqdm - for showing live progress (available via pip or conda)

  • cytoolz - a couple of slightly faster utility functions

To perform the hyper-optimization (and not just randomly sample) one of the following libraries is needed:

  • optuna - Tree of Parzen Estimators used by default, high quality but only medium fast

  • cmaes - Covariance Matrix Adaptation Evolution Strategy, medium quality but very fast

  • nevergrad - various population and evolutionary algorithms (also fast & suitable for highly parallel path findings)

  • skopt - random forest as well as Gaussian process regressors (very high quality but very slow)

If you want to experiment with other algorithms then the following can be used:

  • python-igraph - various other community detection algorithms (though no hyperedge support and usually worse performance than kahypar).

  • QuickBB

  • FlowCutter

The latter two are both accessed simply using their command line interface and so the following executables should be placed on the path somewhere: [quickbb_64, flow_cutter_pace17].

Parallelization

The parallel functionality can requires any of the following:

Visualization

The following packages enable visualization: