Metadata-Version: 2.4
Name: put-asunder
Version: 0.1.0
Summary: Asunder: Constrained Structure Detection on Undirected Graphs.
Author-email: Fortune Adekogbe <fortunea@umich.edu>, Allman Group <allmanaa@umich.edu>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/allman-group/asunder
Project-URL: Documentation, https://put-asunder.readthedocs.io
Project-URL: Repository, https://github.com/allman-group/asunder
Keywords: graph,constrained-clustering,graph-clustering,community-detection,core-periphery,column-generation,constrained-network-structure-detection,branch-and-price
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Science/Research
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.13
Requires-Dist: networkx>=3.2
Requires-Dist: scikit-learn>=1.5
Requires-Dist: scikit-network>=0.33
Requires-Dist: tqdm>=4.66
Requires-Dist: pyomo>=6.8
Requires-Dist: gurobipy>=11.0
Provides-Extra: graph
Requires-Dist: python-igraph>=0.11; extra == "graph"
Requires-Dist: leidenalg>=0.10; extra == "graph"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == "viz"
Requires-Dist: seaborn>=0.13; extra == "viz"
Provides-Extra: legacy
Requires-Dist: cpnet; extra == "legacy"
Provides-Extra: docs
Requires-Dist: sphinx>=7.4; extra == "docs"
Requires-Dist: furo>=2024.8.6; extra == "docs"
Requires-Dist: myst-parser>=3.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2.3; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.7; extra == "dev"
Requires-Dist: mypy>=1.12; extra == "dev"
Requires-Dist: pre-commit>=3.8; extra == "dev"
Dynamic: license-file

# Asunder

Asunder is a Python package for constrained structure detection on undirected graphs, with workflows centered on column generation and customizable master/subproblem pipelines.

Development of Asunder is led by the Allman Group at the University of Michigan.

## Install

Base install:

```bash
pip install put-asunder
```

Optional extras:

```bash
pip install "put-asunder[graph,viz]"
```

Legacy heuristics (best-effort on Python 3.13):

```bash
pip install "put-asunder[legacy]"
```

## Python Support

- Guaranteed: Python 3.10, 3.11, 3.12, 3.13 for core package.
- Guaranteed: mainstream extras (`graph`, `viz`) on Python 3.10–3.13.
- Best-effort: `legacy` extra on Python 3.13.

## Quickstart

```python
import numpy as np
from asunder import CSDDecomposition, CSDDecompositionConfig

A = np.array([
    [0, 1, 1, 0],
    [1, 0, 1, 0],
    [1, 1, 0, 0],
    [0, 0, 0, 0],
], dtype=float)

cfg = CSDDecompositionConfig(
    ifc_params={"generator": lambda N, **_: [np.ones((N, N))], "num": 1, "args": {"N": A.shape[0]}},
    extract_dual=False,
    final_master_solve=False,
)

result = CSDDecomposition(config=cfg).run(A)
print(result.metadata)
```

## Solver Setup

Asunder accepts user-provided solver objects. For Gurobi, `GRB_LICENSE_FILE` is used by your environment. Example:

```python
from asunder import create_solver

solver = create_solver("gurobi_direct")
```

## Problem Fit

Asunder works well out of the box for optimization problems where coordination or operations are coupled across time and those interactions can be represented as a graph over constraints.

Asunder also supports general constrained partitioning beyond these domain examples when requirements can be expressed as must-link and cannot-link constraints.

Typical fit signals:

- coupling across time periods, units, or resources
- mixed discrete-continuous structure with meaningful constraint interactions
- a useful interpretation of must-link/cannot-link or worthy-edge constraints
- value from multilevel partitioning or core-periphery structure detection

Representative domains:

- stochastic design and dispatch in energy systems
- scheduling and resource allocation in healthcare systems
- planning, routing, and location in supply chain and logistics
- network configuration and resource management in telecommunications

For a fuller guide on where default workflows are sufficient vs where customization helps, see `docs/problem_fit.rst`.

## Constraint Graph Compatibility

For the built-in case-study evaluation workflows (`run_evaluation`), Asunder expects a constraint-graph pattern consistent with the provided case studies.

Required structure for `run_evaluation`-style workflows:

- undirected graph (typically `networkx.Graph`)
- node attribute `constraint` (string tag used for ground-truth and role grouping)
- edge attribute `var_type` with values `"integer"` or `"continuous"`

Commonly present (recommended) attributes:

- node attribute `type` (for example `"constraint"`)
- node attribute `details` (metadata dict)
- edge attributes `weight`, `variables`, `var_types`

How these are used:

- `constraint` identifies core/nonlinear tags in built-in case studies
- `var_type` determines candidate edge sets for CP and CD_Refine paths

If you are not using `run_evaluation` and instead calling decomposition APIs directly, you can work from an adjacency matrix plus explicit `must_link`, `cannot_link`, and optional `worthy_edges`.

## Customization Points

For custom problems, typical extension points are:

1. Initial feasible partition generator.
2. `solve_master_problem` replacement.
3. Heuristic or ILP subproblem replacement.
4. Optional partition refinement stage.

## Examples

- Nonlinear B&P-style decomposition: `examples/nonlinear_bp.py`
- Custom subproblem wiring: `examples/custom_subproblem.py`

## Documentation

Sphinx docs are scaffolded in `docs/` and intended for Read the Docs deployment.

## References

Asunder integrates or wraps methods from:

- python-igraph / leidenalg
- scikit-network
- signed-louvain style algorithms
