optiwindnet.baselines.hgs
=========================

.. py:module:: optiwindnet.baselines.hgs




Module Contents
---------------

.. py:function:: hgs_cvrp(A: networkx.Graph, *, capacity: float, time_limit: float, vehicles: int | None = None, vehicles_exact: bool = False, seed: int | None = None, keep_log: bool = False, repair: bool = True, max_retries: int = 10, balanced: bool = False, ringed: bool = False, log_callback: Callable | None = None) -> networkx.Graph

   Solves the O/CVRP using HGS-CVRP with links from ``A``.

   Wraps HybGenSea, which provides bindings to the HGS-CVRP library (Hybrid
   Genetic Search solver for Capacitated Vehicle Routing Problems). By default
   this function solves an Open-CVRP (vehicles do not return to the depot),
   yielding radial layouts. With ``ringed=True`` it solves the closed CVRP
   instead: every route returns to the depot, forming a ring. The ring capacity
   is doubled internally (``2 * capacity``) so each of the ring's two arms holds
   at most ``capacity`` terminals.

   Normalization of input graph is recommended before calling this function.

   For single-root problems, the solver runs on the full graph. For multi-root
   problems, the graph is clustered and each cluster is solved concurrently.

   By default, ``vehicles`` is an upper bound on the feeder count: HGS-CVRP is
   free to use fewer, which it normally does, since a shorter solution seldom
   needs more than the minimum ``ceil(T / capacity)`` feeders. Pass
   ``vehicles_exact=True`` to pin the count to ``vehicles`` instead. This is
   only implemented together with ``balanced=True``: the slack nodes that make
   the loads balanced also make every route come out full, so no route can be
   left empty and the feeder count is necessarily ``vehicles``.

   For multi-root instances, the vehicles (feeders) parameter can only be left
   undefined (meaning unlimited) or set to the minimum feasible value. Any other
   value results in a warning and the minimum being used, or, if
   ``vehicles_exact=True``, in a ``ValueError``.

   If ``repair=True`` (the default), the solution is iteratively repaired
   until no crossings remain (or ``max_retries`` is reached). This may cause the
   actual runtime to be up to ``(max_retries + 1)`` times the given ``time_limit``.

   :param A: graph with allowed edges (if it has 0 edges, use complete graph)
   :param capacity: maximum vehicle capacity
   :param time_limit: [s] solver run time limit
   :param vehicles: maximum number of vehicles (if None, let HGS-CVRP decide;
                    clamped to the minimum for multi-root problems); the exact number of
                    vehicles if ``vehicles_exact=True``
   :param vehicles_exact: whether ``vehicles`` is the exact feeder count instead of
                          an upper bound (requires ``balanced=True``, a single root, and
                          ``ceil(T / capacity) <= vehicles <= T``)
   :param seed: random seed for reproducibility
   :param keep_log: attach solver log to the solution graph
   :param repair: iteratively fix crossings (default True)
   :param max_retries: maximum repair iterations
   :param balanced: balance loads across feeders (per root, if multiple roots)
   :param log_callback: callback to receive each log line produced by HGS-CVRP
                        (only for single-root instances)

   :returns: Solution topology S