optiwindnet.api =============== .. py:module:: optiwindnet.api Module Contents --------------- .. py:class:: Router Bases: :py:obj:`abc.ABC` Abstract base class for routing algorithms in OptiWindNet. Each Router implementation must define a `route` method. .. py:method:: __repr__() -> str .. py:method:: route(P: networkx.PlanarEmbedding, A: networkx.Graph, cables: list[tuple[int, float | int]], cables_capacity: int, verbose: bool, **kwargs) -> tuple[networkx.Graph, networkx.Graph] :abstractmethod: Run the routing optimization. :param P: Navigation mesh for the location. :param A: Graph of available links. :param cables: set of cable specifications as [(capacity, linear_cost), ...]. :param cables_capacity: highest cable capacity in cables. :param verbose: Whether to print progress/logging info. :param \*\*kwargs: Additional router-specific parameters. :returns: Tuple of (solution topology (selected links), optimized route set). .. py:class:: WindFarmNetwork(cables: int | list[int] | list[tuple[int, float | int]] | numpy.ndarray, turbinesC: numpy.ndarray | None = None, substationsC: numpy.ndarray | None = None, borderC: numpy.ndarray = np.empty((0, 2), dtype=np.float64), obstacleC_: Sequence[numpy.ndarray] = [], name: str = '', handle: str = '', L: networkx.Graph | None = None, router: Router | None = None, verbose: bool = False) Wind farm electrical network. Wrapper of most of OptiWindNet's functionality (optimization, visualization, cost/length evaluation, and gradient calculation). An instance represents a wind farm location, which initially contains the number and positions of wind turbines and substations, the delimited area and eventual obstacles. A cable network may be provided or a ``Router`` instance may be used to create an optimized network. Initialize a wind farm electrical network. :param cables: Multiple formats are accepted (capacity is in number of turbines): * Set of cable specifications as: [(capacity, linear_cost), ...]. * Sequence of maximum capacity per cable type: [capacity_0, capacity_1, ...] * Maximum capacity of all available cables: capacity :param turbinesC: Turbine coordinates (T, 2): [(x, y), ...]. :param substationsC: Substation coordinates (R, 2): [(x, y), ...]. :param borderC: Polygonal border coordinates (_, 2): [(x, y), ...]. :param obstacleC_: One or more polygons for exclusion zones list of (_, 2): [[(x, y), ...], ...]. :param name: Human-readable instance name. Defaults to "". :param handle: Short instance identifier. Defaults to "". :param L: Location geometry (takes precedence over coordinate inputs). :param router: Routing algorithm instance. Defaults to `EWRouter`. :param buffer_dist: Buffer distance to dilate borders / erode obstacles. Defaults to 0. .. rubric:: Notes * If both `L` and coordinates are provided, `L` takes precedence. * Changing coordinate data after creation (`turbinesC` and/or `substationsC`) rebuilds `L` and refreshes the navigation mesh and available links. Example:: wfn = WindFarmNetwork( cables=[(3, 100.0), (5, 150.0)], turbinesC=np.array([[0, 0], [1, 0], [0, 1]]), substationsC=np.array([[10, 0]]), ) wfn.optimize() print(wfn.cost(), wfn.length()) .. py:attribute:: name :value: '' Instance name. .. py:attribute:: handle :value: '' Short instance identifier. .. py:property:: router :type: Router Router instance used for optimization. .. py:property:: cables :type: list[tuple[int, float | int]] Set of cable specifications as [(capacity, linear_cost), ...]. .. py:attribute:: verbose :value: False Enable verbose logging. .. py:property:: L :type: networkx.Graph Location geometry (turbines, substations, borders, obstacles). .. py:property:: polygon :type: shapely.Polygon | shapely.MultiPolygon | None Shapely (Multi)Polygon that bounds the cable-laying area. .. py:property:: P :type: networkx.PlanarEmbedding Triangular mesh over `L` (navigation mesh). .. py:property:: A :type: networkx.Graph Available links graph (search space). .. py:property:: S :type: networkx.Graph Solution topology (selected links). .. py:property:: G :type: networkx.Graph Optimized network with cable routes and types. .. py:property:: buffer_dist :type: float Buffer distance applied to dilate borders / erode obstacles. .. py:method:: cost() -> float Get the total cost of the optimized network. .. py:method:: length() -> float Get the total cable length of the optimized network. .. py:method:: plot_original_vs_buffered(**kwargs) -> matplotlib.axes.Axes | None Plot original and buffered borders and obstacles on a single plot. :param \*\*kwargs: passed to matplotlib's pyplot.figure() :returns: matplotlib Axes instance. .. py:method:: from_yaml(filepath: str, **kwargs) :classmethod: Create a WindFarmNetwork instance from a YAML file. .. py:method:: from_pbf(filepath: pathlib.Path | str, **kwargs) :classmethod: Create a WindFarmNetwork instance from a .OSM.PBF file. .. py:method:: from_windIO(filepath: pathlib.Path | str, **kwargs) :classmethod: Create a WindFarmNetwork instance from WindIO yaml file. .. py:method:: __repr__() -> str Concise one-line summary for console/debugging. Defensive by design: instance attributes are getattr-guarded so the repr never raises, even on a partially-initialized instance (e.g. if ``__init__`` aborted before ``_T``/``_R`` were set). The solved-network branch is reached only when ``_is_stale_SG`` is ``False``, which guarantees ``_G`` exists. .. py:method:: plot(*args, **kwargs) Plot the optimized network. By default, this method utilizes the modern vector SVG-based plotting backend (`svgplot`) which returns an `SvgRepr` suitable for clean interactive inline displays in Jupyter notebooks. To switch to the Matplotlib-based plotting backend (`gplot`), specify the `ax` parameter as a keyword argument. .. note:: Passing `ax=None` explicitly routes to the Matplotlib backend and automatically instantiates a new figure and axes on the fly, allowing Matplotlib figures to be created without importing `matplotlib` or `pyplot` directly in the user code. .. py:method:: plot_location(**kwargs) Plot the original location geometry. .. py:method:: plot_available_links(**kwargs) Plot available links from planar embedding. .. py:method:: plot_navigation_mesh(**kwargs) Plot navigation mesh (planar graph and adjacency). .. py:method:: plot_selected_links(**kwargs) Plot tentative link selection. .. py:method:: terse_links() Get a compact representation of the solution topology. .. py:method:: update_from_terse_links(terse_links: numpy.ndarray, turbinesC: numpy.ndarray | None = None, substationsC: numpy.ndarray | None = None) Update the network from terse link representation. Accepts integers or integer-like floats (e.g., 3.0). .. py:method:: get_network() Export the optimized network as a structured array. .. py:method:: map_detour_vertex() Map detour vertices back to their original coordinate indices. .. py:method:: merge_obstacles_into_border() .. py:method:: add_buffer(buffer_dist) Dilate the cable-laying area by `buffer_dist`. Useful if boundaries are not strictly enforced during optimization. This may happen if boundary compliance is achieved through the application of penalties for violations. OptiWindNet will fail if turbines are outside the border, so choose a `buffer_dist` that is greater than the maximum single step in position. :param buffer_dist: Buffer distance to dilate borders / erode obstacles. .. py:method:: gradient(turbinesC=None, substationsC=None, gradient_type='length') Compute length/cost gradients with respect to node positions. .. py:method:: optimize(turbinesC=None, substationsC=None, router=None, verbose=False) Optimize electrical network. .. py:method:: solution_info() Get model and solver information of the latest solution (runtime, objective, gap, etc.). .. py:class:: EWRouter(maxiter: int = 10000, feeder_route: str = 'segmented', verbose: bool = False, **kwargs) Bases: :py:obj:`Router` A lightweight, ultra-fast router for electrical network optimization. * Uses a modified Esau-Williams heuristic (segmented or straight feeders). * Produces solutions in milliseconds, suitable for quick solutions or warm starts. Create a Esau-Williams-based router. :param maxiter: Maximum iterations. :param feeder_route: Feeder routing mode ("segmented" or "straight"). :param verbose: Enable verbose logging. .. py:attribute:: verbose :value: False .. py:attribute:: maxiter :value: 10000 .. py:attribute:: feeder_route :value: 'segmented' .. py:method:: route(P, A, cables, cables_capacity, verbose=False, **kwargs) Run the routing optimization. :param P: Navigation mesh for the location. :param A: Graph of available links. :param cables: set of cable specifications as [(capacity, linear_cost), ...]. :param cables_capacity: highest cable capacity in cables. :param verbose: Whether to print progress/logging info. :param \*\*kwargs: Additional router-specific parameters. :returns: Tuple of (solution topology (selected links), optimized route set). .. py:class:: HGSRouter(time_limit: float, feeder_limit: int | None = None, max_retries: int = 10, balanced: bool = False, seed: int | None = None, verbose: bool = False, **kwargs) Bases: :py:obj:`Router` A fast router based on Hybrid Genetic Search (HGS-CVRP). Uses the method and implementation by Vidal, 2022: Vidal, T. (2022). Hybrid genetic search for the CVRP: Open-source implementation and SWAP* neighborhood. Computers & Operations Research, 140, 105643. https://doi.org/10.1016/j.cor.2021.105643 * Balances solution quality and runtime. * Produces only radial solutions. Create an HGS-based router. :param time_limit: Maximum runtime for a single HGS run (in seconds). :param feeder_limit: Maximum number of feeders allowed (ignored if multiple substations). :param max_retries: Maximum number of retries if a feasible solution is not found. :param balanced: Whether to balance turbines/loads across feeders. :param seed: Set the seed of the pseudo-random number generator (reproducibility). :param verbose: Enable verbose logging. .. rubric:: Notes * The total runtime may reach up to `(max_retries + 1) * time_limit` in the worst case. .. py:attribute:: time_limit .. py:attribute:: verbose :value: False .. py:attribute:: max_retries :value: 10 .. py:attribute:: feeder_limit :value: None .. py:attribute:: balanced :value: False .. py:attribute:: seed :value: None .. py:method:: route(P, A, cables, cables_capacity, verbose=False, **kwargs) Run the routing optimization. :param P: Navigation mesh for the location. :param A: Graph of available links. :param cables: set of cable specifications as [(capacity, linear_cost), ...]. :param cables_capacity: highest cable capacity in cables. :param verbose: Whether to print progress/logging info. :param \*\*kwargs: Additional router-specific parameters. :returns: Tuple of (solution topology (selected links), optimized route set). .. py:class:: MILPRouter(solver_name: str, time_limit: float, mip_gap: float, solver_options: dict | None = None, model_options: optiwindnet.MILP.ModelOptions | None = None, verbose: bool = False, **kwargs) Bases: :py:obj:`Router` An exact router using mathematical programming. * Uses a Mixed-Integer Linear Programming (MILP) model of the problem. * Produces provably optimal or near-optimal networks (with quality metrics). * Requires a longer runtime than heuristics- and meta-heuristics-based routers. Create a MILP-based router. :param solver_name: Name of solver (e.g., "gurobi", "cbc", "ortools", "cplex", "highs", "scip"). :param time_limit: Maximum runtime (seconds). :param mip_gap: Relative MIP optimality gap tolerance. :param solver_options: Extra solver-specific options. :param model_options: Options for the MILP model. :param verbose: Enable verbose logging. .. py:attribute:: default_heuristic :value: 'rootlust' .. py:attribute:: time_limit .. py:attribute:: mip_gap .. py:attribute:: solver_name .. py:attribute:: solver_options .. py:attribute:: model_options .. py:attribute:: verbose :value: False .. py:attribute:: solver .. py:method:: route(P, A, cables, cables_capacity, verbose=False, S_warm=None, S_warm_has_detour=False, num_retries: int = 2, **kwargs) Run the routing optimization. :param P: Navigation mesh for the location. :param A: Graph of available links. :param cables: set of cable specifications as [(capacity, linear_cost), ...]. :param cables_capacity: highest cable capacity in cables. :param verbose: Whether to print progress/logging info. :param \*\*kwargs: Additional router-specific parameters. :returns: Tuple of (solution topology (selected links), optimized route set).