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, log_callback: Callable | None = None) -> networkx.Graph

   Solves the OCVRP 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). This
   function uses it to solve an Open-CVRP i.e., vehicles do not return to the
   depot.

   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


.. py:function:: iterative_hgs_cvrp(A: networkx.Graph, *, capacity: float, time_limit: float, vehicles: int | None = None, seed: int | None = None, max_retries: int = 10, keep_log: bool = False, complete: bool = False) -> networkx.Graph

   DEPRECATED: Backward-compatible alias of `hgs_cvrp()`, use it instead.


.. py:function:: hgs_multiroot(A: networkx.Graph, *, capacity: int, time_limit: float, balanced: bool = False, seed: int | None = None, keep_log: bool = False) -> networkx.Graph

   DEPRECATED: Backward-compatible alias of `hgs_cvrp()`, use it instead.