Utilities API

The graphcalc.utils module contains general-purpose helper functionality used across GraphCalc workflows.

General utilities for GraphCalc.

This module intentionally avoids solver resolution/selection logic; that all lives in graphcalc.solvers.

Exports

GraphLike

Union of networkx.Graph and graphcalc.core.SimpleGraph.

enforce_type

Decorator factory to enforce the type of a positional argument.

require_graph_like

Decorator ensuring the first argument is a graph-like object.

_extract_and_report

Helper to read solution status/objective/variables from a solved PuLP model.

Convenience re-exports from graphcalc.solvers

get_default_solver, resolve_solver, with_solver, solve_or_raise, SolverSpec

graphcalc.utils.GraphLike

Type alias for objects accepted as graphs in GraphCalc.

graphcalc.utils.enforce_type(arg_index: int, expected_types)

Decorator factory to enforce the type of a specific positional argument.

Parameters:

• arg_index (int) – Index of the positional argument in *args to check.

• expected_types (type or tuple[type, ...]) – The expected type(s) for the argument at arg_index.

Raises:

TypeError – When the argument at arg_index is not of type expected_types.

graphcalc.utils.get_default_solver(msg: bool = False) → LpSolver_CMD

Return the first available LP solver backend, honoring environment overrides.

Order of preference:

1. HiGHS

2. CBC

3. GLPK

Environment overrides

• GRAPHCALC_SOLVER:

  Friendly name ("highs", "cbc", "glpsol") or PuLP key ("HiGHS_CMD", "PULP_CBC_CMD", "GLPK_CMD"), or "auto".

• GRAPHCALC_SOLVER_PATH:

  Full path to an executable (e.g., C:\miniconda3\envs\gc\Library\bin\highs.exe).

returns:

Configured with msg according to the argument.

rtype:

pulp.apis.core.LpSolver_CMD

graphcalc.utils.require_graph_like(func)

Decorator that enforces the first argument to be graph-like.

Checks that the wrapped function’s first positional argument is an instance of networkx.Graph.

Raises:

TypeError – If the first argument is not a supported graph type.

graphcalc.utils.resolve_solver(solver: str | Dict[str, Any] | LpSolver | LpSolver_CMD | Callable[[], LpSolver | LpSolver_CMD] | Type[LpSolver] | Type[LpSolver_CMD] | None, *, msg: bool = False, solver_options: Dict[str, Any] | None = None) → LpSolver

Resolve a flexible solver spec into a PuLP solver instance.

Accepts

• None

  Use get_default_solver().

• str

  PuLP registry name (e.g., “HiGHS_CMD”, “GUROBI_CMD”) or friendly alias (“auto”, “highs”, “cbc”, “glpsol”).

• dict

  {“name”: <str>, “options”: {…}} forwarded to pulp.getSolver().

• class

  Subclass of PuLP solver; will be instantiated with solver_options.

• callable

  Zero-argument factory returning a PuLP solver instance.

• instance

  An already-constructed PuLP solver object.

Notes

• msg is propagated when we construct the solver (string/dict/class). If the caller provides an instance, we do not override its settings.

graphcalc.utils.solve_or_raise(prob: LpProblem, solver: LpSolver) → None

Solve a PuLP problem and raise ValueError if the status is not Optimal.

graphcalc.utils.with_solver(fn)

Decorator that adds a uniform (verbose=False, *, solver=None, solver_options=None) interface to solver-backed functions without repeating boilerplate.

The wrapped function must accept parameters (verbose: bool = False, solve=None, **kwargs). The decorator injects a solve(prob) closure that resolves the solver with resolve_solver and calls solve_or_raise.