Solvers API

The graphcalc.solvers module contains solver-backed functionality used in optimization-oriented workflows across the library.

graphcalc.solvers.doctor() → str

Return a multi-line diagnostic string describing which solver GraphCalc would use right now, including how it was found.

Examples

>>> out = doctor()
>>> isinstance(out, str)
True
>>> out.startswith("GraphCalc Solver Doctor")
True
>>> "Selected" in out and "Path trial(s)" in out
True

graphcalc.solvers.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.solvers.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.solvers.solve_or_raise(prob: LpProblem, solver: LpSolver) → None

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

graphcalc.solvers.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.