Refactor: Split graphsAndPaths monolith into focused graphs package#72
Merged
Refactor: Split graphsAndPaths monolith into focused graphs package#72
Conversation
Split the 2295-line graphsAndPaths monolith into 9 single-responsibility sub-modules under alphaDeesp/core/graphs/ (constants, graph_utils, null_flow, shortest_paths, power_flow_graph, constrained_path, structured_overload_graph, overflow_graph, __init__), so each class and helper group can be read, tested and evolved on its own. graphsAndPaths.py is kept as a thin re-export shim to preserve every existing import path. Behaviour is preserved byte-for-byte: class/function bodies are moved, not rewritten. The 109 tests in test_graphs_and_paths_unit.py pass unchanged.
Add docs/refactor-graphs-package.md documenting the motivation, design principles, new layout, dependency graph, backwards-compatibility contract, migration guide and verification strategy of the graphsAndPaths -> alphaDeesp.core.graphs split. Add alphaDeesp/tests/test_graphs_package.py (35 tests) covering the refactor's structural invariants (shim parity, public API stability, sub-module boundaries, import acyclicity) plus behavioural coverage for three areas that were under-tested in the legacy unit file: PowerFlowGraph construction, Structured_Overload_Distribution_Graph end-to-end on a small hand-built graph, and shortest_path_mandatory_and_promoted. Together with the 109 pre-existing unit tests in test_graphs_and_paths_unit.py (which also still pass unchanged) this brings the graphs package up to 144 tests.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refactors the 2295-line
alphaDeesp/core/graphsAndPaths.pymonolith into a well-organizedalphaDeesp/core/graphs/package with single-responsibility modules. The refactor preserves all behavior byte-for-byte while improving code organization, testability, and maintainability. A backward-compatible shim ingraphsAndPaths.pyensures zero breaking changes for existing imports.Key Changes
New package structure: Created
alphaDeesp/core/graphs/with 8 focused modules:power_flow_graph.py— Base class for grid state visualizationoverflow_graph.py— Colored overflow-redispatch graph (1284 lines, bulk of original logic)structured_overload_graph.py— Extracts constrained paths, loop paths, and hubsconstrained_path.py— Main path carrying overloaded linesgraph_utils.py— Pure graph helpers (delete_color_edges, nodepath_to_edgepath, etc.)shortest_paths.py— Shortest-path algorithms with mandatory/promoted-edge constraintsnull_flow.py— Double/un-double null-flow edgesconstants.py— Shared constants (voltage colors)__init__.py— Public API re-exportsBackward compatibility shim:
graphsAndPaths.pyreduced to 49 lines, re-exporting all 16 public symbols from the new package. All existing imports continue to work unchanged.Explicit public API: Added
__all__to clearly define the 16 public names (classes, functions, constants) the package commits to exporting.Comprehensive test coverage: Added
test_graphs_package.pywith 443 lines of tests covering:Documentation: Added
docs/refactor-graphs-package.mdexplaining motivation, design principles, and migration guidance.Implementation Details
https://claude.ai/code/session_01KWk5cYHneZjkrcT2LRnxCi