optiwindnet 0.2.1__tar.gz → 0.2.2__tar.gz

{optiwindnet-0.2.1 → optiwindnet-0.2.2}/CHANGELOG.md

@@ -1,3 +1,39 @@
+# v0.2.2
+
+[Commit history since v0.2.1](https://gitlab.windenergy.dtu.dk/TOPFARM/OptiWindNet/-/compare/v0.2.1...v0.2.2)
+
+## Breaking Changes
+- **Advanced API Cleanups**: Helper functions for root-assignment and link-blockage moved from `optiwindnet.geometric` to `optiwindnet.interarraylib`. Users should import `add_terminal_closest_root()`, `add_link_blockmap()`, and `add_link_cosines()` from `optiwindnet.interarraylib`.
+
+## Important Changes
+- **Default Vector SVG Plotting**: High-level `WindFarmNetwork` plotting methods (`plot()`, `plot_location()`, `plot_available_links()`, `plot_navigation_mesh()`, and `plot_selected_links()`) now use a modern, interactive vector SVG plotting backend (`svgplot`/`svgpplot`) by default. This delivers clean, high-resolution inline displays in Jupyter notebooks. The legacy Matplotlib-based backend remains fully accessible by passing an explicit `ax` argument (including `ax=None` to dynamically instantiate Matplotlib figures).
+- **svgplot() matches gplot()'s features**: SVG plots now support node labeling, boundary/obstacle vertex tagging, and figure legend.
+- **Informative String Representations**: Added descriptive, debugger-safe string representations (`__repr__`) for `WindFarmNetwork` and `Router` subclasses (`EWRouter`, `HGSRouter`, `MILPRouter`) displaying key configuration parameters and solved network metrics.
+- **Shorter Substation Labels**: Pre-packaged offshore wind farm datasets (.osm.pbf format) have been updated with short, human-readable substation abbreviations (such as "Alpha", "Beta", "OSS") to fit cleanly in visualization labels.
+- **New Fused Heuristic**: Added `heuristics.constructor()` with `esau_williams`, `biased_EW`, `rootlust`, and `radial_EW` methods, unifying the constructive routing heuristics. The high-level `EWRouter` now uses this path, offering radial topology and the performant rootlust method.
+- **LKH-3 Solver Parity**: Added `lkh3()` as the preferred LKH entry point, bringing it to feature parity with the HGS solver. It supports single- and multi-root configurations, per-root clustering, warm starts, capacity-violation retries, crossing repair, and improved solver metadata.
+- **Expanded Crossing Diagnostics**: Added Shapely-based `find_geometric_crossings()` for geometry-first validation of arbitrary routesets, including detours, contour clones, shared-run overlap crossings, and branch-split cases.
+- **Robust PathFinder Detours**: Major robustness improvements when routing detours among cable routes that follow boundaries or exclusion zones, significantly reducing cable use on sites with many obstacles.
+
+## Deprecated
+- Standalone EW heuristics (`ClassicEW`, `CPEW`, `NBEW`, `OBEW`, and `EW_presolver`) are deprecated and will be removed in v0.3. They are superseded by the new unified `heuristics.constructor()`. Note that `constructor` expects the available-links graph `A`, not the location graph `L`.
+- The legacy `optiwindnet.interface` module (`heuristic_wrapper()`, `HeuristicFactory`) is deprecated and will be removed in v0.3; use `WindFarmNetwork`/`EWRouter` instead.
+
+## Fixes
+- **Pathfinder Robustness**: Resolved fatal crashes (`KeyError` and triangulation flip failures) when constructing detours.
+- **Diagonal Mesh Exclusion**: Prevented invalid diagonal paths by skipping edges in the site's boundary polygon during navigation mesh generation.
+- **Logging & Diagnostics**: Replaced all remaining raw `print()` statements across the API and utility modules with standard Python logging.
+- **LKH and Heuristic Repairs**: Fixed LKH warm-start tour construction (indexing, walk order within clusters) and aligned HGS/LKH repair behavior for capacity-violating and crossing routes.
+- **Overflow Prevention**: Added checks for LKH weight-matrix construction with clear guidance when inputs need normalization.
+- **Crossing Detection**: Fixed shared-route overlap crossing detection and added geometric handling for route intersections not expressible as available-edge crossings.
+
+## Refactoring & Maintenance
+- **Python 3.11–3.14 Support**: Explicitly declared support for Python 3.11 through 3.14 with standard Trove classifiers on PyPI.
+- **Updated OR-Tools Floor**: Aligned OR-Tools requirements in `pyproject.toml` to `>=9.14.6206` for consistency across development and production environments.
+- **Strict Deprecation Testing**: Test suite configured to treat `DeprecationWarning` as errors to guarantee API health.
+- **Linting & Code Quality**: Enforced strict Ruff linting and formatting rules via continuous integration.
+- **Performance Optimizations**: Optimized pathfinding sector lookups and precomputed chain-end topologies to speed up execution.
+
 # v0.2.1
 
 [Commit history since v0.2.0](https://gitlab.windenergy.dtu.dk/TOPFARM/OptiWindNet/-/compare/v0.2.0...v0.2.1)

{optiwindnet-0.2.1 → optiwindnet-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optiwindnet
-Version: 0.2.1
+Version: 0.2.2
 Summary: Tool for designing and optimizing the electrical cable network of offshore wind farms
 Author-email: DTU Wind Energy <mikf@dtu.dk>, Mauricio Souza de Alencar <ma___@dtu.dk>, Amir Arasteh <am___@dtu.dk>
 License-Expression: MIT
@@ -15,6 +15,10 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Scientific/Engineering
@@ -32,7 +36,7 @@ Requires-Dist: matplotlib>=3.10.1
 Requires-Dist: networkx>=3.6
 Requires-Dist: numba>=0.62.1
 Requires-Dist: numpy>=2.0
-Requires-Dist: ortools>=9.12.4544
+Requires-Dist: ortools>=9.14.6206
 Requires-Dist: peewee>=3.17
 Requires-Dist: Pyomo>=6.9.5
 Requires-Dist: PyYAML>=6.0.2

optiwindnet-0.2.2/_run_chain_tests.py

@@ -0,0 +1,137 @@
+"""Validation driver for the chain-sleeve pathfinding feature.
+
+Loads pickled G_db routesets for four RIDs and re-runs PathFinder, checking
+that the expected feeder paths and total length are produced.
+
+Usage:
+    python _run_chain_tests.py
+"""
+
+import math
+import pickle
+import sys
+from pathlib import Path
+
+from optiwindnet.interarraylib import G_from_S, L_from_G, S_from_G
+from optiwindnet.mesh import make_planar_embedding
+from optiwindnet.pathfinding import PathFinder
+
+EXPECTED = {
+    22822: {
+        'length': 9.4484,
+        'feeders': [[-1, 46, 70, 35], [-1, 46, 70, 26]],
+    },
+    33303: {
+        'length': 9.5741,
+        'feeders': [[-1, 46, 70, 35], [-1, 46, 70, 26]],
+    },
+    33372: {
+        'length': 11.1059,
+        'feeders': [[-1, 40, 57, 44], [-1, 40, 57, 58, 59, 5]],
+    },
+    35875: {
+        'length': None,
+        'feeders': [[-1, 60, 75, 76, 77, 8]],
+    },
+}
+
+
+def _feeder_paths(G):
+    """Extract every -1->...->terminal path through the routeset, mapped to primes."""
+    R = G.graph['R']
+    T = G.graph['T']
+    fnT = G.graph.get('fnT')
+
+    def prime(n):
+        if n < 0:
+            return n
+        if fnT is not None and n < len(fnT):
+            return int(fnT[n])
+        return n
+
+    feeders = []
+    # walk every root->...->terminal path through detour clones and contour
+    # helpers; emit one feeder per terminal-anchored path that starts at root
+    for r in range(-R, 0):
+        for first in G.neighbors(r):
+            # DFS to find paths root → ... → terminal (prime in [0, T))
+            stack = [(first, [r, first], {r, first})]
+            while stack:
+                cur, path, visited = stack.pop()
+                # Terminate on actual terminal node (not a clone whose prime is
+                # a terminal — those happen along contour helpers).
+                if 0 <= cur < T:
+                    feeders.append([prime(x) for x in path])
+                    continue
+                for nxt in G.neighbors(cur):
+                    if nxt in visited:
+                        continue
+                    stack.append((nxt, path + [nxt], visited | {nxt}))
+    return feeders
+
+
+def _run_one(rid):
+    p = Path(__file__).parent / 'tests' / 'locations' / f'G_{rid}.pkl'
+    with open(p, 'rb') as f:
+        G_db = pickle.load(f)
+
+    # reconstruct site → planar+A → topology → tentative → PathFinder
+    L = L_from_G(G_db)
+    L.graph['border'] = G_db.graph['border']
+    L.graph['VertexC'] = G_db.graph['VertexC'][
+        : G_db.graph['T'] + G_db.graph['B'] - G_db.graph.get('D', 0)
+    ] if False else G_db.graph['VertexC'][
+        : G_db.graph['T'] + G_db.graph['B']
+    ].copy()
+    # Stitch the actual VertexC together: terminals + borders + roots
+    import numpy as np
+    R, T, B = G_db.graph['R'], G_db.graph['T'], G_db.graph['B']
+    VertexC = G_db.graph['VertexC']
+    L.graph['VertexC'] = np.vstack((VertexC[: T + B], VertexC[-R:]))
+    L.graph['B'] = B
+    L.graph['R'] = R
+    L.graph['T'] = T
+
+    P, A = make_planar_embedding(L)
+    S = S_from_G(G_db)
+    G_tent = G_from_S(S, A)
+    pf = PathFinder(G_tent, planar=P, A=A)
+    G_out = pf.create_detours()
+    length = G_out.size(weight='length')
+    feeders = _feeder_paths(G_out)
+    return length, feeders
+
+
+def main():
+    failures = 0
+    for rid, expected in EXPECTED.items():
+        try:
+            length, feeders = _run_one(rid)
+        except Exception as e:
+            print(f'  RID {rid}: ERROR {type(e).__name__}: {e}')
+            failures += 1
+            continue
+        ok_len = (
+            expected['length'] is None
+            or math.isclose(length, expected['length'], abs_tol=1e-3)
+        )
+        # Match expected feeders as multisets of prime-vertex sequences
+        got_set = {tuple(f) for f in feeders}
+        want_set = {tuple(f) for f in expected['feeders']}
+        missing = want_set - got_set
+        ok_feeders = not missing
+        status = 'OK' if (ok_len and ok_feeders) else 'FAIL'
+        if status == 'FAIL':
+            failures += 1
+        print(
+            f'RID {rid}: {status}  length={length:.4f}'
+            + (f' (expected {expected["length"]})' if expected['length'] else '')
+        )
+        if missing:
+            print(f'    missing feeders: {sorted(missing)}')
+            print(f'    got feeders:     {sorted(got_set)}')
+    return failures
+
+
+if __name__ == '__main__':
+    sys.exit(main())

{optiwindnet-0.2.1 → optiwindnet-0.2.2}/optiwindnet/MILP/__init__.py

@@ -9,8 +9,8 @@ from ._core import (
     FeederRoute,
     ModelMetadata,
     ModelOptions,
-    OWNWarmupFailed,
     OWNSolutionNotFound,
+    OWNWarmupFailed,
     SolutionInfo,
     Solver,
     Topology,
@@ -99,8 +99,9 @@ def solver_factory(solver_name: str) -> Solver:
                     return SolverFSCIP()
                 else:
                     raise FileNotFoundError(
-                        "Executable 'fscip' not found. Ensure the system PATH includes the "
-                        "path to 'fscip' (part of scipoptsuite from https://www.scipopt.org)."
+                        "Executable 'fscip' not found. Ensure the system PATH includes"
+                        " the path to 'fscip' (part of scipoptsuite from"
+                        ' https://www.scipopt.org).'
                     )
             else:
                 raise ModuleNotFoundError(
@@ -109,9 +110,10 @@ def solver_factory(solver_name: str) -> Solver:
                 )
         case 'highs':
             if find_spec('highspy'):
-                from .pyomo import SolverPyomoAppsi
                 from pyomo.contrib.appsi.solvers.highs import Highs
 
+                from .pyomo import SolverPyomoAppsi
+
                 return SolverPyomoAppsi(solver_name, Highs)
             raise ModuleNotFoundError(
                 "Package 'highspy' not found. Try 'pip install highspy' or "

{optiwindnet-0.2.1 → optiwindnet-0.2.2}/optiwindnet/MILP/_core.py

@@ -5,12 +5,11 @@ import abc
 import logging
 import os
 import sys
+from collections.abc import Mapping
 from dataclasses import asdict, dataclass, field
-from pathlib import Path
-
 from enum import StrEnum, auto
 from itertools import chain
-from collections.abc import Mapping
+from pathlib import Path
 from typing import Any
 
 import networkx as nx
@@ -85,7 +84,9 @@ class FeederRoute(StrEnum):
 
 
 class FeederLimit(StrEnum):
-    'Whether to limit the maximum number of feeders, if set to "specified", additional kwarg "max_feeders" must be given.'
+    'Whether to limit the maximum number of feeders, if set to "specified",'
+
+    ' additional kwarg "max_feeders" must be given.'
 
     UNLIMITED = auto()
     SPECIFIED = auto()

{optiwindnet-0.2.1 → optiwindnet-0.2.2}/optiwindnet/MILP/_core.pyi

@@ -5,12 +5,11 @@
 import abc
 from collections.abc import Mapping
 from dataclasses import dataclass, field
+from enum import StrEnum
 from typing import Any
 
 import networkx as nx
 
-from enum import StrEnum
-
 def physical_core_count() -> int: ...
 
 class OWNWarmupFailed(Exception): ...

{optiwindnet-0.2.1 → optiwindnet-0.2.2}/optiwindnet/MILP/cplex.py

@@ -9,7 +9,7 @@ import pyomo.environ as pyo
 
 from ..interarraylib import G_from_S
 from ..pathfinding import PathFinder
-from ._core import FeederRoute, PoolHandler, Topology, ModelOptions
+from ._core import FeederRoute, ModelOptions, PoolHandler, Topology
 from .pyomo import SolverPyomo
 
 __all__ = ()

{optiwindnet-0.2.1 → optiwindnet-0.2.2}/optiwindnet/MILP/fscip.py

@@ -13,7 +13,6 @@ import networkx as nx
 
 from ..interarraylib import G_from_S
 from ..pathfinding import PathFinder
-from .scip import make_min_length_model, warmup_model
 from ._core import (
     FeederRoute,
     ModelOptions,
@@ -24,6 +23,7 @@ from ._core import (
     Topology,
     physical_core_count,
 )
+from .scip import make_min_length_model, warmup_model
 
 __all__ = ('make_min_length_model', 'warmup_model')
 
@@ -202,7 +202,8 @@ class SolverFSCIP(Solver, PoolHandler):
             num_solutions = model.getNSols()
             if num_solutions == 0:
                 raise OWNSolutionNotFound(
-                    f'Unable to find a solution. Solver {self.name} terminated with: {model.getStatus()}'
+                    f'Unable to find a solution. Solver {self.name} terminated'
+                    f' with: {model.getStatus()}'
                 )
             termination = 'unknown'
             solving_time = float('nan')

{optiwindnet-0.2.1 → optiwindnet-0.2.2}/optiwindnet/MILP/gurobi.py

@@ -100,7 +100,8 @@ class SolverGurobi(SolverPyomo, PoolHandler):
         termination = result['Solver'][0]['Termination condition'].name
         if num_solutions == 0:
             raise OWNSolutionNotFound(
-                f'Unable to find a solution. Solver gurobi terminated with: {termination}'
+                f'Unable to find a solution. Solver gurobi terminated'
+                f' with: {termination}'
             )
         self.result = result
         objective = result['Problem'][0]['Upper bound']

{optiwindnet-0.2.1 → optiwindnet-0.2.2}/optiwindnet/MILP/ortools.py

@@ -185,7 +185,8 @@ class SolverORTools(Solver, PoolHandler):
         termination = result.termination.reason.name
         if num_solutions == 0:
             raise OWNSolutionNotFound(
-                f'Unable to find a solution. Solver {self.name} terminated with: {termination}'
+                f'Unable to find a solution. Solver {self.name} terminated'
+                f' with: {termination}'
             )
         storer.solutions.reverse()
         self._solution_pool = storer.solutions

{optiwindnet-0.2.1 → optiwindnet-0.2.2}/optiwindnet/MILP/pyomo.py

@@ -132,7 +132,8 @@ class SolverPyomo(Solver):
         termination = result['Solver'][0]['Termination condition'].name
         if len(result.solution) == 0:
             raise OWNSolutionNotFound(
-                f'Unable to find a solution. Solver {self.name} terminated with: {termination}'
+                f'Unable to find a solution. Solver {self.name} terminated'
+                f' with: {termination}'
             )
         self.result = result
         if self.name != 'scip':
@@ -238,7 +239,8 @@ class SolverPyomoAppsi(Solver):
         termination = result.termination_condition.name
         if objective is None:
             raise OWNSolutionNotFound(
-                f'Unable to find a solution. Solver {self.name} terminated with: {termination}'
+                f'Unable to find a solution. Solver {self.name} terminated'
+                f' with: {termination}'
             )
         bound = result.best_objective_bound
         solution_info = SolutionInfo(
@@ -503,7 +505,7 @@ def make_min_length_model(
     # radial or branched topology
     if topology is Topology.RADIAL:
         # just need to limit incoming edges since the outgoing are
-        # limited by the m.cons_one_out_edge
+        # limited by the m.cons_single_out_link
         m.cons_radial = pyo.Constraint(
             m.T,
             rule=(

{optiwindnet-0.2.1 → optiwindnet-0.2.2}/optiwindnet/MILP/scip.py

@@ -96,7 +96,8 @@ class SolverSCIP(Solver, PoolHandler):
         num_solutions = model.getNSols()
         if num_solutions == 0:
             raise OWNSolutionNotFound(
-                f'Unable to find a solution. Solver {self.name} terminated with: {model.getStatus()}'
+                f'Unable to find a solution. Solver {self.name} terminated'
+                f' with: {model.getStatus()}'
             )
         bound = model.getDualbound()
         objective = model.getObjVal()

{optiwindnet-0.2.1 → optiwindnet-0.2.2}/optiwindnet/__init__.py

@@ -5,7 +5,8 @@
 __author__ = 'Mauricio Souza de Alencar'
 
 __doc__ = """
-Tool for designing and optimizing the electrical cable network (collection system) for offshore wind power plants.
+Tool for designing and optimizing the electrical cable network (collection system)
+for offshore wind power plants.
 
 https://gitlab.windenergy.dtu.dk/TOPFARM/OptiWindNet/
 """