Generic NLBNP Workflow

Generic high-level nonlinear branch-and-price workflow.

asunder.nlbnp.workflow.run_nonlinear_branch_and_price(graph, *, worthy_edges=None, worthy_edge_attr=None, worthy_edge_value=None, must_link=None, cannot_link=None, algorithm='louvain', package='networkx', seed=42, ifc_params=None, refine=True, refine_params=None, prob_method='threshold', use_refined_column=True, final_master_solve=False, extract_dual=True, max_iterations=None, tolerance=1e-08, disable_tqdm=False, verbose=-1, additional_constraints=None, config=None, master_fn=<function solve_master_problem>, subproblem_fn=None, **overrides)

Run a generic nonlinear branch-and-price decomposition workflow.

Parameters:

  • graph (networkx.Graph or ndarray) – Input graph or square adjacency matrix.

  • worthy_edges (sequence of tuple, optional) – Edge pairs that should be treated as worthy edges. For networkx inputs, pairs use graph node labels. For adjacency inputs, pairs use integer node indices.

  • worthy_edge_attr (str, optional) – Edge attribute used to derive worthy edges from a networkx.Graph. When worthy_edge_value is None, truthy attribute values are selected. Otherwise, the attribute must equal worthy_edge_value.

  • worthy_edge_value (Any, optional) – Attribute value selected by worthy_edge_attr.

  • must_link (sequence of tuple, optional) – Pairwise constraints using graph node labels or adjacency indices.

  • cannot_link (sequence of tuple, optional) – Pairwise constraints using graph node labels or adjacency indices.

  • algorithm (str) – Heuristic pricing algorithm name.

  • package (str or None) – Third-party package namespace used by package-backed heuristic pricing.

  • seed (int or None) – Random seed.

  • ifc_params (dict or None) – Initial feasible column generator configuration. Defaults to make_simple_partition.

  • refine (bool) – Whether to configure the default linear-group refinement hook.

  • refine_params (dict or None) – Explicit refinement configuration. Overrides the default refinement configuration when supplied.

  • prob_method (str) – Probability-to-label method passed to the default linear-group refinement function.

  • use_refined_column (bool) – Whether refined columns should be added to the column pool.

  • final_master_solve (bool) – Whether to run a final integer master solve.

  • extract_dual (bool) – Whether to solve the relaxed master with dual extraction.

  • max_iterations (int or None) – Maximum column-generation iterations.

  • tolerance (float) – Reduced-cost stopping tolerance.

  • disable_tqdm (bool) – Disable the progress bar.

  • verbose (int or bool) – Verbosity passed to the decomposition loop.

  • additional_constraints (dict or None) – Additional constraints passed through to the master problem.

  • config (CSDDecompositionConfig or None) – Base decomposition configuration. Explicit wrapper arguments override matching fields.

  • master_fn (callable) – Master problem callable.

  • subproblem_fn (callable or None) – Pricing/subproblem callable. Defaults to the appropriate built-in heuristic callable for algorithm.

  • **overrides (Any) – Additional configuration overrides passed to run_csd_decomposition.

Returns:

Structured decomposition result with label-aware metadata.

Return type:

DecompositionResult

asunder.nlbnp.workflow.CorePeripheryPartition(graph, *, unworthy_edges=None, unworthy_edge_attr=None, unworthy_edge_value=None, nonlinear_nodes=None, nonlinear_node_attr=None, nonlinear_node_value=None, cp_algorithm='SPEC', prob_method='gaussian_mixture', threshold=0.8, seed=42, verbose=False)

Solve NLBNP by separating a core and partitioning periphery components.

This path is appropriate when removing the detected core naturally leaves each connected periphery component as a complete final community. Use run_nonlinear_branch_and_price() when those components need further subdivision.

Parameters:

  • graph (networkx.Graph or ndarray) – Input graph or square adjacency matrix.

  • unworthy_edges (sequence of tuple, optional) – Edge pairs that cannot connect separate communities.

  • unworthy_edge_attr (str, optional) – Edge attribute used to derive unworthy edges from a networkx.Graph.

  • unworthy_edge_value (Any, optional) – Attribute value selected by unworthy_edge_attr.

  • nonlinear_nodes (sequence, optional) – Nodes that represent nonlinear constraints and should remain together.

  • nonlinear_node_attr (str, optional) – Node attribute used to derive nonlinear nodes from a networkx.Graph.

  • nonlinear_node_value (Any, optional) – Attribute value selected by nonlinear_node_attr.

  • cp_algorithm ({"SPEC", "GA", "KL"}) – Core-periphery detection algorithm.

  • prob_method ({"threshold", "gaussian_mixture", "DBSCAN"}) – Method used to convert continuous coreness values to discrete labels.

  • threshold (float) – Threshold used when prob_method="threshold".

  • seed (int or None) – Random seed.

  • verbose (bool) – Controls probability conversion output.

Return type:

tuple[ndarray, dict[str, Any]]

Returns:

  • community_labels (ndarray of int, shape (N,)) – Community labels where the core is community 0 and connected periphery components are communities 1..K.

  • metadata (dict) – Core-periphery detection, component, and graph-label metadata.

asunder.nlbnp.workflow.NonlinearBranchAndPrice(graph, *, worthy_edges=None, worthy_edge_attr=None, worthy_edge_value=None, must_link=None, cannot_link=None, algorithm='louvain', package='networkx', seed=42, ifc_params=None, refine=True, refine_params=None, prob_method='threshold', use_refined_column=True, final_master_solve=False, extract_dual=True, max_iterations=None, tolerance=1e-08, disable_tqdm=False, verbose=-1, additional_constraints=None, config=None, master_fn=<function solve_master_problem>, subproblem_fn=None, **overrides)

LoadBalancer-style alias for run_nonlinear_branch_and_price().

Return type:

DecompositionResult

Parameters:

  • graph (nx.Graph | np.ndarray)

  • worthy_edges (Sequence[tuple[Hashable, Hashable]] | None)

  • worthy_edge_attr (str | None)

  • worthy_edge_value (Any)

  • must_link (Sequence[tuple[Hashable, Hashable]] | None)

  • cannot_link (Sequence[tuple[Hashable, Hashable]] | None)

  • algorithm (str)

  • package (str | None)

  • seed (int | None)

  • ifc_params (dict[str, Any] | None)

  • refine (bool)

  • refine_params (dict[str, Any] | None)

  • prob_method (str)

  • use_refined_column (bool)

  • final_master_solve (bool)

  • extract_dual (bool)

  • max_iterations (int | None)

  • tolerance (float)

  • disable_tqdm (bool)

  • verbose (int | bool)

  • additional_constraints (dict[str, Any] | None)

  • config (CSDDecompositionConfig | None)

  • master_fn (MasterProblemFn)

  • subproblem_fn (SubproblemFn | None)

  • overrides (Any)