Introduction

Asunder is a Python package for constrained network structure detection on undirected graphs. In practice, that means it helps you take a graph whose nodes and edges are subject to constraints and generates a partition that respects those constraints.

The package is built around a simple idea: many parallel computing problems can be viewed through a graph, and the constrained community structure detection problem can be decomposed using a restricted master problem plus a pricing or heuristic subproblem. Asunder provides reusable tooling for that pattern and leaves room for application-specific logic where needed.

What Asunder Provides

Asunder gives you three things:

  • a reusable decomposition layer for graph-based constrained partitioning and column-generation style workflows

  • a built-in load balancing workflow for graph partitions with equal, near-equal, or explicitly bounded community sizes

  • packaged application logic for the current nonlinear branch-and-price workflow, plus supporting algorithms, utilities, and visualization helpers

The package is therefore useful in three different modes:

  • as a reusable toolkit for constrained partitioning and decomposition

  • as a complete load-balanced graph partitioning workflow

  • as a concrete application package for the built-in nonlinear branch-and-price workflow and its case studies

Package Layout

The public package is intentionally split into layers.

asunder

The top-level facade. Use this when you want the main convenience entry points such as run_csd_decomposition, solve_master_problem, solve_subproblem, run_evaluation, or the orchestration/config types.

asunder.base

The reusable layer. This contains algorithms, branch-and-price utilities, column-generation modules, evaluation metrics, legacy notebook shims, utilities, and visualization helpers.

asunder.load_balancing

The application layer for load-balanced graph partitioning. This contains the high-level LoadBalancer workflow, load-balancing master problem, initial feasible partition generators, and refinement logic.

asunder.nlbnp

The application layer for nonlinear branch-and-price workflows. This contains CorePeripheryPartition for component-level partitioning after core removal, the finer-grained NonlinearBranchAndPrice workflow, case studies, the built-in evaluation runner, and NLBNP-specific refinement.

If you are building a new application area, asunder.base is the starting point. If you want a complete balanced partitioning workflow, start with asunder.load_balancing. If you want to use the existing nonlinear branch-and-price workflow, asunder.nlbnp gives you the packaged application-specific pieces.

Mental Model

Most workflows in Asunder follow this rough sequence:

  1. Build or derive a graph whose nodes represent constraints, tasks, entities, or other units that should be grouped.

  2. Encode constraints through available and additional constraints. This could be pairwise structure through adjacency, weights, must-link, cannot-link, or worthy-edge style constraints.

  3. Generate one or more initial feasible partition matrices.

  4. Run a master problem and a pricing or heuristic subproblem in a loop.

  5. Optionally apply a refinement step or application-specific post-processing.

  6. Evaluate, inspect, or visualize the resulting partition.

You do not need every layer every time. Some users will call asunder.load_balancing.LoadBalancer directly, some will use the high-level top-level decomposition API, and others will work directly with asunder.base modules and plug in their own master, subproblem, and refinement routines.

When To Start High-Level vs Low-Level

Start with the top-level API if:

  • you want to run the default decomposition loop quickly

  • you are still validating whether your problem is a good fit

  • you mainly need orchestration and typed results

Use asunder.load_balancing if:

  • you want graph communities with balanced or bounded sizes

  • you have must-link or cannot-link constraints between graph nodes

  • you want a packaged workflow instead of custom master/subproblem wiring

Drop into asunder.base if:

  • you need a custom master problem

  • you need a custom pricing/subproblem routine

  • you want to mix and match reusable utilities and algorithms

  • you are building a new application package on top of the reusable layer

Use asunder.nlbnp if:

  • you expect core removal to expose connected components that are final communities

  • you already have a graph and want the generic nonlinear branch-and-price workflow

  • you want the built-in nonlinear branch-and-price case studies

  • you want the packaged evaluation runner

  • you need the NLBNP-specific refinement workflow

What Asunder Does Not Do For You

Asunder does not yet support general-purpose automatic decomposition from a raw Pyomo model. It expects you to supply either:

  • a graph representation of the problem, or

  • enough application logic to derive one

It is also not a guarantee that a default heuristic will be appropriate for every problem. The package is designed so that you can replace initial feasible column generation, master problem logic, subproblem logic, and refinement logic when the default pieces are not enough.

Next Steps