neofoam.framework.graph

Shared graph utilities for DAG validation, ordering, and visualization.

Solvers and models in NeoFOAM declare their work as Operation objects with depends_on / before constraints. Before those operations can run, the framework needs to:

  1. Validate the dependency graph (no duplicates, no missing dependencies, no cycles) — see validation.

  2. Resolve a topological order, respecting loop scopes and using operation_number as a tie-breaker — see resolver.

  3. Optionally render the resulting graph for diagnostics — see visualization.

The package exposes ten public symbols across four modules:

  • DAGResolver — the main entry point; merges and orders operations across loop scopes.

  • TopologicalSorter (Protocol) and NetworkxTopologicalSorter (default impl) — the injection seam for swapping the sort backend.

  • validate_dependency_graph(), GraphValidationReport, and build_dependency_digraph() — pre-resolution graph validation and the underlying networkx.DiGraph builder.

  • CyclicDependencyError, MissingDependencyError — the two domain exceptions the resolver can raise.

  • dependency_dag(), digraph_to_pyvis_html() — compose per-domain DAGs and render them to an interactive HTML page.

See Operations and the DAG for the design rationale and where the resolver fits into the solver lifecycle.