ExpertOp4Grid v0.3.1 — Code Quality & Maintainability Overhaul

Highlights

This release is a major code quality and maintainability milestone. Six pull requests across a focused sprint bring ExpertOp4Grid's core codebase from a prototype-grade state to a well-structured, statically-analysable library:

• Structured logging replaces all 101 print() calls — embedders now control verbosity
• Type annotations across ~220 function signatures — mypy and radon added to CI
• Architecture cleanup — the 2295-line graphsAndPaths.py monolith split into 8 focused modules with a backward-compatible shim
• Complexity reduction — four critical high-complexity functions (CC up to 68) decomposed into composable, testable helpers
• Safer encoding — twin-node string-prefix hack ("666" + str(id)) replaced by an offset-based scheme that fixes silent collisions
• Packaging refresh — correct python_requires, updated dependency floors, duplicate license removed

---

What's Changed

PR #67 — Code quality cleanup: pyflakes, bare excepts, mutable defaults

• Replaced all 9 bare except: clauses with specific exception types
• Removed 15+ unused imports and dead local variables across alphadeesp.py, graphsAndPaths.py, printer.py, Grid2opSimulation.py, PypownetSimulation.py
• Replaced from alphaDeesp.core.elements import * with explicit imports in three modules (star-import cleanup)
• Fixed two mutable default arguments in AlphaDeesp.__init__ and rank_current_topo_at_node_x
• Added pyflakes lint step to CircleCI — 0 findings on the full CI scope
• Gated print(df) in Simulation.create_df behind a debug flag

PR #68 — Short-term code quality improvements: logging, docstrings, packaging

• Logging migration: all 101 print() calls converted to logger.info/warning/debug across 10 modules; main.py installs basicConfig only for CLI entry point, leaving embedders in control
• Abstract method documentation: replaced all 9 """TODO""" stubs in Simulation with full Sphinx-style docstrings including contracts and backend-specific notes
• CI re-enablement: replaced --ignore flags with pytest.importorskip guards — optional test suites now run automatically when optional dependencies are present
• Packaging cleanup: added python_requires=">=3.9", bumped Grid2Op>=1.12.1 and lightsim2grid>=0.10.3, removed stale pathlib backport and dead commented-out dependencies, deleted duplicate LICENSE.md

PR #69 — Refactor four high-complexity functions into composable helpers

• AlphaDeesp.rank_current_topo_at_node_x: CC 68 → 7, extracted six scoring helpers
• AlphaDeesp.apply_new_topo_to_graph: CC 36 → 7, extracted five topology-pipeline helpers
• OverFlowGraph.detect_edges_to_keep: CC 46 → 2, fully orchestrating main function with four path-classification helpers
• OverFlowGraph.add_relevant_null_flow_lines: CC 44 → 7, extracted five null-flow helpers
• New module core/twin_nodes.py: offset-based twin-node scheme (TWIN_NODE_OFFSET = 10_000_000) replacing fragile "666" + str(id) encoding — fixes silent collisions for substation ids ≥ 1000
• 21 new unit tests in test_alphadeesp_unit.py; 30+ new tests in test_graphs_and_paths_unit.py; total: 130 passing

PR #70 — Add type hints to core base classes and fix mutable defaults

• Fully annotated core/elements.py (all four element dataclasses: Production, Consumption, OriginLine, ExtremityLine)
• Fully annotated core/simulation.py abstract base class — all 10 abstract methods, all helper methods, factory method
• Exported SubstationElement type alias (Union[Production, Consumption, OriginLine, ExtremityLine])
• Fixed mutable defaults ltc=[9] / other_ltc=[] in Grid2opSimulation.__init__ and PypownetSimulation.__init__

PR #71 — Add type hints propagation and mypy/radon to CI

• Signature-level type annotations added to six previously untyped modules: core/alphadeesp.py (~38 signatures), core/graphsAndPaths.py (~76 signatures), core/network.py, core/printer.py, core/grid2op/Grid2opSimulation.py (~33 signatures), core/pypownet/PypownetSimulation.py (~27 signatures)
• Type-annotated functions: 36 → ~220
• Mypy added to CircleCI: strict mode on seed modules (simulation.py, elements.py) blocks the build on failure; permissive mode on remaining modules is informational
• Radon added to CircleCI: cyclomatic complexity, maintainability index, and raw metrics reported on every build

PR #72 — Refactor: Split graphsAndPaths monolith into focused graphs package

• alphaDeesp/core/graphsAndPaths.py (2295 lines) split into alphaDeesp/core/graphs/ package with 8 focused modules: power_flow_graph.py, overflow_graph.py, structured_overload_graph.py, constrained_path.py, graph_utils.py, shortest_paths.py, null_flow.py, constants.py
• Zero breaking changes: graphsAndPaths.py reduced to a 49-line backward-compatible shim re-exporting all 16 public symbols
• Explicit __all__ defines the committed public API
• 443 lines of new tests in test_graphs_package.py covering structural invariants, import acyclicity, and algorithmic correctness
• Architecture documentation added in docs/refactor-graphs-package.md

---

Upgrade Notes

• No breaking changes to the public API. All existing from alphaDeesp.core.graphsAndPaths import ... imports continue to work unchanged.
• Embedders using Grid2opSimulation(ltc=[...]) or PypownetSimulation(ltc=[...]) are unaffected — keyword-argument callers remain compatible.
• Console output is now suppressed by default. To restore verbose output, configure logging before calling the library: logging.basicConfig(level=logging.INFO).
• Minimum Python version is now officially 3.9 (up from the stale 3.6/3.7 classifiers in setup.py).

---

Full Changelog: v0.3.0.post1...v0.3.1

ExpertOp4Grid v0.3.0.post1

Changelog

[0.3.0.post1] - 2026-03-10

New Features

• Standardized overflow graph arrow sizes (PR #66): Implemented linear scaling for penwidth in OverFlowGraph based on absolute delta flow. This ensures arrow sizes are reasonable and readable even for very high delta flows, with a standardized maximum penwidth.
• Improved arrow scaling in PowerFlowGraph: Also applied linear scaling to PowerFlowGraph for consistent visualization across different graph types.

Bug Fixes

• Fixed collapse_red_loops logic: Optimized the node collapse condition to ensure ALL connected edges are coral before collapsing a node into a "point" shape.

Tests

• Added unit tests for arrow scaling and collapse_red_loops in test_graphs_and_paths_unit.py.
• Adapted test_visualization_filtering.py in the recommender repo to verify collapse_red_loops call.

[0.3.0] - 2026-02-10

New Features

• Filter graph components without overloads (PR #64): Added keep_overloads_components() method to OverFlowGraph that filters out connected components not containing any overloaded (black) edges by recolouring them to grey. This ensures only components with actual overloads are considered significant in further analysis.

• Collapse coral-only loop nodes (PR #65): Added collapse_red_loops() method to OverFlowGraph that collapses nodes purely part of coral-only loops into "point" shapes for cleaner visualization. A node is collapsed when all its edges are coral, its shape is "oval", it has no peripheries attribute, and none of its edges are dashed or dotted.

Performance Improvements

• Optimized null flow detection (PR #63): Major refactoring and performance optimization of the null flow line detection pipeline:
  • Extracted _setup_null_flow_styles() to avoid redundant style setup across target path iterations
  • Pre-compute structural info (red loop nodes, constrained path endpoints) once and reuse across all target paths
  • Replace delete_color_edges graph copy operations with direct edge color computation for connex analysis
  • Build gray component graph in a single edge pass instead of 3 sequential copy+remove operations
  • Use single-source Dijkstra per source node instead of per source-target pair, reducing from O(S*T) to O(S) Dijkstra calls
  • Pre-filter edges of interest to component membership for early exits
  • Cache BFS results and incident edge lookups to eliminate redundant computation
  • Flip negative capacities once globally instead of per source-target pair
  • Optimized remove_unused_added_double_edge to avoid subgraph creation
  • Optimized add_double_edges_null_redispatch from 4 nx.get_edge_attributes calls to a single edge pass
  • Increased max_null_flow_path_length default from 5 to 7
  • Properly handle double edges when finding relevant null flow paths

Tests

• Added 78 unit tests for graphsAndPaths helper functions and detect_edges_to_keep (PR #63), covering: delete_color_edges, nodepath_to_edgepath, incident_edges, from_edges_get_nodes, find_multidigraph_edges_by_name, shortest_path_with_promoted_edges, all_simple_edge_paths_multi, add_double_edges_null_redispatch, remove_unused_added_double_edge, detect_edges_to_keep, ConstrainedPath methods, and shortest_path_min_weight_then_hops
• Added 13 unit tests for keep_overloads_components (PR #64), covering: component with/without overloads, multiple mixed components, already-gray edges, empty graph, single edges, parallel edges, gray bridge not merging components, three components, and idempotency

[0.2.8]

Performance Improvements

• Speed up path findings with smarter graph algorithms and rustworkx (PR #61)
• Speed up AlphaDeesp representation creation: optimize create_and_fill_internal_structures, accelerate get_model_obj_from_or and get_model_obj_from_ext (PR #62)
• Added rustworkx as a dependency for faster graph operations

Features

• Added ability to consider undirected edges in loop paths (PR #59)
• Extended topology scoring to reduced specified action space with warm-start support (PR #58)
• Exposed depth and breadth search parameters for reconnectable lines in upper functions

[0.2.7]

• Highlight non-connected paths with additional blue edge path info (PR #57)
• Ambiguous path handling improvements (PR #55, #56)
• Highlight possible overloads (PR #53, #54)
• Display reconnectable lines (PR #52)
• Improved graphviz constrained path visualization (PR #51)
• Getting started guide and examples (PR #50)
• Refactored plotting (PR #47, #48)

Release 0.3.0

[0.3.0] - 2026-02-10
New Features
Filter graph components without overloads (PR #64): Added keep_overloads_components() method to OverFlowGraph that filters out connected components not containing any overloaded (black) edges by recolouring them to grey. This ensures only components with actual overloads are considered significant in further analysis.

Collapse coral-only loop nodes (PR #65): Added collapse_red_loops() method to OverFlowGraph that collapses nodes purely part of coral-only loops into "point" shapes for cleaner visualization. A node is collapsed when all its edges are coral, its shape is "oval", it has no peripheries attribute, and none of its edges are dashed or dotted.

Performance Improvements
Optimized null flow detection (PR #63): Major refactoring and performance optimization of the null flow line detection pipeline:
Extracted _setup_null_flow_styles() to avoid redundant style setup across target path iterations
Pre-compute structural info (red loop nodes, constrained path endpoints) once and reuse across all target paths
Replace delete_color_edges graph copy operations with direct edge color computation for connex analysis
Build gray component graph in a single edge pass instead of 3 sequential copy+remove operations
Use single-source Dijkstra per source node instead of per source-target pair, reducing from O(S*T) to O(S) Dijkstra calls
Pre-filter edges of interest to component membership for early exits
Cache BFS results and incident edge lookups to eliminate redundant computation
Flip negative capacities once globally instead of per source-target pair
Optimized remove_unused_added_double_edge to avoid subgraph creation
Optimized add_double_edges_null_redispatch from 4 nx.get_edge_attributes calls to a single edge pass
Increased max_null_flow_path_length default from 5 to 7
Properly handle double edges when finding relevant null flow paths
Tests
Added 78 unit tests for graphsAndPaths helper functions and detect_edges_to_keep (PR #63), covering: delete_color_edges, nodepath_to_edgepath, incident_edges, from_edges_get_nodes, find_multidigraph_edges_by_name, shortest_path_with_promoted_edges, all_simple_edge_paths_multi, add_double_edges_null_redispatch, remove_unused_added_double_edge, detect_edges_to_keep, ConstrainedPath methods, and shortest_path_min_weight_then_hops
Added 13 unit tests for keep_overloads_components (PR #64), covering: component with/without overloads, multiple mixed components, already-gray edges, empty graph, single edges, parallel edges, gray bridge not merging components, three components, and idempotency

Speedup bottlenecks for larger grids

Speeding up Alphadeesp representation creation (#62) as well as path finding algorithms that use networkx (#61). Those 2 were the main bottlenecks when working with larger grids.

Add undirected red adges to loop paths

see #59

Slight correction

Slight correction to identify back the constrained edge which could be coloured with black but also additional colors

1542daf

Highlight non connected path - extend topo scoring

cf PR #57 (Highlight non connected path) and #58 (Extending topo scoring to reduced specified action space)

Avoid exception because of null loops when consolidation graph

cf commit 93d7cf8

Visualize non reconnectable lines

cf PR #56

Consolidate the graph by managing ambiguous path

cf PR #55