Installation¶

Asunder is distributed on PyPI as put-asunder. The base install is enough for the main package, the load balancing workflow, the default decomposition APIs, NetworkX-based algorithms, scikit-network algorithms, Pyomo modeling, and the standard evaluation utilities.

Base Install¶

Install the released package with:

python -m pip install put-asunder

QMETIS Platform Support¶

The released Windows x86-64, Linux x86-64, and macOS universal2 wheels bundle the pinned qmetis-v5.2.1-modularity.1 native library with an idx64-real32 ABI. Pip selects the compatible platform wheel automatically. Each wheel includes only qmetis.dll, libqmetis.so, or libqmetis.dylib as appropriate; generic metis-named native libraries are deliberately excluded.

Use the bundled load-balancing pricing heuristic with:

result = LoadBalancer(G, K=4, R=2, algorithm="qmetis")

The high-level interface intentionally has no QMETIS-specific parameters. Asunder derives QMETIS’s search envelope from the load-balancing bounds and recalculates reduced cost with the original floating-point graph and duals. Because QMETIS does not reliably support adjacency self-loops, its candidate generator drops nonzero diagonal values, including internal-edge mass created by graph contraction, and emits QMETISApproximationWarning. This is an explicit search approximation only; exact reduced-cost rescoring continues to use the original diagonal values.

The source distribution does not contain native libraries. A source install can use the rest of Asunder normally, but selecting algorithm="qmetis" requires a compatible QMETIS library to be staged during a platform-wheel build.

Optional Extras¶

Optional extras add dependencies for workflows that are useful but not required for every installation. Extras can be installed one at a time or combined in a comma-separated list.

graph

Installs python-igraph and leidenalg.

Use this extra when you want the igraph- or leidenalg-backed community detection paths, such as calling decomposition routines with package="igraph" or package="leidenalg". These backends are especially useful for larger graph instances where compiled graph routines can be faster than pure Python alternatives. python-igraph is also used by some graph automorphism and symmetry-detection helpers.

python -m pip install "put-asunder[graph]"

viz

Installs matplotlib and seaborn.

Use this extra when you want plotting helpers under asunder.base.visualization for graph, partition, and matrix inspection. It is independent of the graph extra, but commonly installed with it for exploratory analysis.

python -m pip install "put-asunder[viz]"

legacy

Installs cpnet.

Use this extra only when you need legacy core-periphery heuristics that rely on cpnet. The core package and current high-level workflows do not require it. The legacy extra is best-effort on Python 3.13 and 3.14 because it depends on compatibility from the upstream legacy package.

python -m pip install "put-asunder[legacy]"

docs

Installs the Sphinx documentation toolchain: sphinx, furo, myst-parser, and sphinx-autodoc-typehints.

Use this extra from a local clone when you want to build the documentation.

python -m pip install -e ".[docs]"

dev

Installs development tools: build, pytest, pytest-cov, ruff, mypy, and pre-commit.

Use this extra from a local clone when you want to run tests, linting, type checks, or contribution hooks.

python -m pip install -e ".[dev]"

Common Install Recipes¶

Install graph algorithms plus visualization support from PyPI:

python -m pip install "put-asunder[graph,viz]"

Install the common contributor environment from a local clone:

python -m pip install -e ".[dev,graph,viz,docs]"

Build the documentation after installing the documentation dependencies:

sphinx-build -b html docs docs/_build/html

Python Support¶

The core package supports Python 3.10, 3.11, 3.12, 3.13, and 3.14. The mainstream graph and viz extras are also expected to work across those versions. The legacy extra is maintained on a best-effort basis on Python 3.13 and 3.14 because it depends on upstream legacy dependencies.

Notes¶

Solver-backed workflows require an available Pyomo-compatible solver in your local environment. Asunder includes the Python modeling interfaces needed by the package, but solver executables, licenses, and solver-specific environment configuration remain local setup concerns rather than dedicated Asunder extras.

For Gurobi-backed runs, configure your environment as required by Gurobi. In many setups that includes setting GRB_LICENSE_FILE before calling create_solver("gurobi_direct") or another Gurobi solver name.