optiwindnet 0.2.2__tar.gz → 0.2.3__tar.gz

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

@@ -1,3 +1,40 @@
+# v0.2.3
+
+[Commit history since v0.2.2](https://gitlab.windenergy.dtu.dk/TOPFARM/OptiWindNet/-/compare/v0.2.2...v0.2.3)
+
+Drop-in replacement for v0.2.2. The APIs deprecated in v0.2.2 are still available and still emit `DeprecationWarning`; they are scheduled for removal in v0.3.
+
+## Important Changes
+- **Balanced Subtrees Actually Balanced (MILP and HGS)**: `balanced=True` promises subtree loads differing at most by one unit, but both solver families only bounded those loads from below, letting a subtree grow up to `capacity`. This is now fixed consistently on both sides:
+  - *MILP*: the upper bound `ceil(T / feeders)` is now enforced across the pyomo, SCIP and OR-Tools model builders.
+  - *HGS*: `hgs_cvrp()` used to request more slack nodes than there were routes whenever `T < feeders * (capacity - 1)`, forcing the surplus through clipped `inf` arcs and inflating the reported objective. The balanced sub-problem is now solved at `capacity_effective = ceil(T / feeders)`, reported in `solver_details`.
+- **Exact Feeder Count (MILP and HGS)**: a new, mirrored way to pin the feeder count instead of only bounding it from above. Because `balanced` is only expressible once the feeder count is pinned, this makes balanced solutions reachable above the minimum feeder count.
+  - *MILP*: `feeder_limit="exactly"` pins the feeder count to `max_feeders` (whereas `"specified"` remains an upper bound).
+  - *HGS*: `hgs_cvrp(vehicles=F, vehicles_exact=True)` — exposed as `HGSRouter(feeder_limit=F, feeder_exact=True)` — pins the feeder count to `F`, whereas `vehicles` alone remains an upper bound that HGS-CVRP normally undershoots. It currently requires `balanced=True` and a single substation; `F` must lie between `ceil(T / capacity)` and `T`.
+- **Reversible lat/lon Coordinates**: `L_from_yaml()` and `L_from_pbf()` now project all coordinates into the single UTM zone holding the most turbines (instead of the zone of the first point), minimizing distortion for the bulk of the layout, and retain that zone as the graph attributes `utm_zone_number` and `utm_zone_letter`. This makes `VertexC` reversible back to lat/lon via `utm.to_latlon()`. Multi-zone `.yaml` input no longer raises an assertion.
+- **Tunable `EWRouter`**: the `method` and `bias_margin` parameters of `heuristics.constructor()` are now exposed on `EWRouter`, giving access to the `esau_williams`, `biased_EW`, `rootlust` and `radial_EW` methods from the high-level API.
+- **Concurrent HiGHS**: the pyomo HiGHS solver now runs a concurrent branch-and-bound tree search, in line with the other MILP backends. This speedup requires `highspy` v1.15 or newer; older versions accept the setting but run the search serially.
+- **New Locations**: added Revolution, Sunrise, Hornsea 2, Norfolk Vanguard West, East Anglia 3 and Hollandse Kust Noord.
+
+## Bug Fixes
+- **Multi-Root Warmstart Eligibility**: `is_warmstart_eligible()` compared only the first root's feeder count against the feeder limit, while the model constrains the total across all roots.
+- **`PathFinder` Malformed Chain**: two spanning fences of the same subtree meeting at a single chain-end vertex form a dead-end pocket, which could leave a chain short an access cone. Chain detection is now keyed on the subtree alone within a chain-end vertex.
+- **`scaffolded()` Correctness**: fence hops and shortened-contour hops are now converted to primed edges (in both `PathFinder.scaffolded()` and `interarraylib.scaffolded()`), and a supertriangle/clone id collision was fixed.
+- **Sexagesimal Coordinate Parsing**: `_translate_latlonstr()` failed to reset minutes/seconds between coordinates, corrupting the parsed values.
+
+## Deprecated
+- `WindFarmNetwork.from_yaml()` is renamed to `WindFarmNetwork.from_own_yaml()`; the old name still works and emits a `DeprecationWarning`.
+- Reminder — the following remain available in this release and will be removed in v0.3. Users are advised to migrate now:
+  - Standalone EW heuristics (`ClassicEW`, `CPEW`, `NBEW`, `OBEW`, `EW_presolver`) → `heuristics.constructor()` (or the high-level `WindFarmNetwork`/`EWRouter`). See the [Legacy heuristics migration guide](https://optiwindnet.readthedocs.io/stable/notebooks/14-Legacy_heuristics.html), which pairs each legacy call with its `constructor()` equivalent.
+  - `optiwindnet.interface` (`heuristic_wrapper()`, `HeuristicFactory`) → `WindFarmNetwork`/`EWRouter`.
+  - HGS aliases `hgs_multiroot()` / `iterative_hgs_cvrp()` → `hgs_cvrp()`.
+  - LKH entry points `lkh()` / `iterative_lkh()` → `lkh3()`.
+
+## Refactoring & Maintenance
+- **Docstrings**: project-wide docstring formatting pass — standardized markup of string values for Sphinx rendering, unicode arrows, and docstrings for the database model.
+- **Test Coverage**: expanded coverage for `geometric`, `interarraylib`, `plotting`, `svg`, `repair`, `themes` and `baselines.utils`.
+- **CI**: isolated OR-Tools in a shared subprocess to resolve solver DLL conflicts, switched SCIP download to GitHub, bumped SCIPOptSuite, installed python tooling from conda, and added manual-dispatch pipeline targets.
+
 # v0.2.2
 
 [Commit history since v0.2.1](https://gitlab.windenergy.dtu.dk/TOPFARM/OptiWindNet/-/compare/v0.2.1...v0.2.2)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optiwindnet
-Version: 0.2.2
+Version: 0.2.3
 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

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

@@ -33,14 +33,15 @@ __all__ = (
 def solver_factory(solver_name: str) -> Solver:
     """Create a Solver object tied to the specified external MILP solver.
 
-    Note that the only solver that is a dependency of OptiWindNet is 'ortools'.
+    Note that the only solver that is a dependency of OptiWindNet is ``'ortools'``.
     Check OptiWindNet's documentation on how to install optional solvers.
 
-    Legacy compatibility: if solver_name == 'ortools' then the CP-SAT backend is used.
+    Legacy compatibility: if ``solver_name == 'ortools'`` then the CP-SAT backend
+    is used.
 
     Args:
-      solver_name: one of 'ortools.cp_sat', 'ortools.gscip',
-        'ortools.highs', 'cplex', 'gurobi', 'cbc', 'scip', 'highs'.
+      solver_name: one of ``'ortools.cp_sat'``, ``'ortools.gscip'``,
+        ``'ortools.highs'``, ``'cplex'``, ``'gurobi'``, ``'cbc'``, ``'scip'``, ``'highs'``.
 
     Returns:
       Solver instance that can produce solutions for the cable routing problem.

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

@@ -3,13 +3,16 @@
 
 import abc
 import logging
+import math
 import os
 import sys
 from collections.abc import Mapping
 from dataclasses import asdict, dataclass, field
 from enum import StrEnum, auto
+from inspect import cleandoc
 from itertools import chain
 from pathlib import Path
+from textwrap import indent
 from typing import Any
 
 import networkx as nx
@@ -19,7 +22,7 @@ from ..interarraylib import G_from_S
 from ..pathfinding import PathFinder
 
 _lggr = logging.getLogger(__name__)
-error, info = _lggr.error, _lggr.info
+error, info, warn = _lggr.error, _lggr.info, _lggr.warning
 
 
 def physical_core_count() -> int:
@@ -76,7 +79,7 @@ class Topology(StrEnum):
 
 
 class FeederRoute(StrEnum):
-    'If feeder routes must be "straight" or can be detoured ("segmented").'
+    "If feeder routes must be ``'straight'`` or can be detoured (``'segmented'``)."
 
     STRAIGHT = auto()
     SEGMENTED = auto()
@@ -84,11 +87,15 @@ 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 number of feeders. Both ``'specified'`` (an upper
+    bound) and ``'exactly'`` (an exact count) require the additional kwarg
+    ``'max_feeders'``. Option ``'balanced'`` is only enforceable if the feeder
+    count is pinned to a single value, i.e. ``'minimum'``, ``'exactly'``, or
+    ``'specified'`` with ``'max_feeders'`` at the minimum.
+    """
 
     UNLIMITED = auto()
+    EXACTLY = auto()
     SPECIFIED = auto()
     MINIMUM = auto()
     MIN_PLUS1 = auto()
@@ -97,6 +104,74 @@ class FeederLimit(StrEnum):
     DEFAULT = UNLIMITED
 
 
+def feeder_and_load_bounds(
+    T: int,
+    capacity: int,
+    feeder_limit: FeederLimit,
+    max_feeders: int,
+    balanced: bool,
+) -> tuple[int, int | None, int | None, int | None]:
+    """Derive the feeder-count and feeder-load bounds a model must enforce.
+
+    The feeder count is bounded below by ``min_feeders = ceil(T/capacity)``
+    regardless of ``feeder_limit`` (a valid inequality). ``feeders_ub`` is
+    ``None`` when the count is unbounded above; when it equals ``feeders_lb``,
+    the count is pinned and callers should emit an equality constraint.
+
+    Balanced subtrees (loads differing at most by one unit) are only expressible
+    with a pinned feeder count ``F``, in which case the loads must lie in
+    ``{T // F, ceil(T / F)}``. A load bound of ``None`` means "do not emit":
+    either ``balanced`` is off, or it is not enforceable (a warning is issued),
+    or the bound is already implied by the flow variable's own bounds.
+
+    Returns:
+        ``(feeders_lb, feeders_ub, load_lb, load_ub)``
+    """
+    min_feeders = math.ceil(T / capacity)
+    if feeder_limit is FeederLimit.UNLIMITED:
+        feeders_lb, feeders_ub = min_feeders, None
+    elif feeder_limit is FeederLimit.MINIMUM:
+        feeders_lb = feeders_ub = min_feeders
+    elif feeder_limit is FeederLimit.EXACTLY:
+        if max_feeders < min_feeders:
+            raise ValueError('max_feeders is below the minimum necessary')
+        if max_feeders > T:
+            raise ValueError('max_feeders is above the number of terminals')
+        feeders_lb = feeders_ub = max_feeders
+    elif feeder_limit is FeederLimit.SPECIFIED:
+        if max_feeders < min_feeders:
+            raise ValueError('max_feeders is below the minimum necessary')
+        feeders_lb, feeders_ub = min_feeders, max_feeders
+    elif feeder_limit in (
+        FeederLimit.MIN_PLUS1,
+        FeederLimit.MIN_PLUS2,
+        FeederLimit.MIN_PLUS3,
+    ):
+        plus = int(feeder_limit.value[-1])
+        feeders_lb, feeders_ub = min_feeders, min_feeders + plus
+    else:
+        raise NotImplementedError('Unknown value:', feeder_limit)
+
+    if not balanced:
+        return feeders_lb, feeders_ub, None, None
+    if feeders_lb != feeders_ub:
+        warn(
+            'Model option <balanced = True> requires a single possible feeder'
+            f' count, but <feeder_limit = {feeder_limit.value.upper()}> allows a'
+            ' range: model will not enforce balanced subtrees.'
+        )
+        return feeders_lb, feeders_ub, None, None
+    F = feeders_lb
+    load_lb, load_ub = T // F, math.ceil(T / F)
+    # bounds at the extremes are already implied by the flow variable's bounds
+    return (
+        feeders_lb,
+        feeders_ub,
+        load_lb if load_lb > 1 else None,
+        load_ub if load_ub < capacity else None,
+    )
+
+
 class ModelOptions(dict):
     """Hold options for the modelling of the cable routing problem.
 
@@ -119,7 +194,8 @@ class ModelOptions(dict):
         max_feeders=(
             int,
             0,
-            'Maximum number of feeders (used only if <feeder_limit = "specified">)',
+            'Number of feeders: the maximum if <feeder_limit = "specified">, '
+            'the exact count if <feeder_limit = "exactly">',
         ),
     )
 
@@ -149,13 +225,14 @@ class ModelOptions(dict):
     @classmethod
     def help(cls):
         for k, v in cls.hints.items():
+            doc = indent(cleandoc(v.__doc__ or ''), '    ')
             print(
                 f'{k} in {{'
                 + ', '.join(
                     f'"{m}"' for n, m in v.__members__.items() if n != 'DEFAULT'
                 )
                 + f'}} default: {cls.hints[k].DEFAULT.value}\n'
-                f'    {v.__doc__}\n'
+                f'{doc}\n'
             )
         for name, (kind, default, desc) in cls.simple.items():
             print(f'{name} [{kind.__name__}] default: {default}\n    {desc}\n')
@@ -242,11 +319,11 @@ class Solver(abc.ABC):
         Args:
           time_limit: maximum time (s) the solver is allowed to run.
           mip_gap: relative difference from incumbent solution to lower bound
-            at which the search may be stopped before time_limit is reached.
+            at which the search may be stopped before ``time_limit`` is reached.
           options: additional options to pass to solver (see solver manual).
 
         Returns:
-          General information about the solution search (use get_solution() for
+          General information about the solution search (use ``get_solution()`` for
             the actual solution).
         """
         pass
@@ -289,7 +366,7 @@ class Solver(abc.ABC):
         """Create a topology graph from the solution to the MILP model.
 
         Returns:
-          Graph topology `S` from the solution.
+          Graph topology ``S`` from the solution.
         """
         metadata = self.metadata
         S = nx.Graph(R=metadata.R, T=metadata.T)
@@ -342,7 +419,7 @@ class PoolHandler(abc.ABC):
 
     @abc.abstractmethod
     def _objective_at(self, index: int) -> float:
-        "Get objective value from solution pool at position `index`"
+        "Get objective value from solution pool at position ``index``"
         pass
 
     @abc.abstractmethod

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

@@ -11,6 +11,13 @@ from typing import Any
 import networkx as nx
 
 def physical_core_count() -> int: ...
+def feeder_and_load_bounds(
+    T: int,
+    capacity: int,
+    feeder_limit: FeederLimit,
+    max_feeders: int,
+    balanced: bool,
+) -> tuple[int, int | None, int | None, int | None]: ...
 
 class OWNWarmupFailed(Exception): ...
 class OWNSolutionNotFound(Exception): ...
@@ -27,6 +34,7 @@ class FeederRoute(StrEnum):
 
 class FeederLimit(StrEnum):
     UNLIMITED: str
+    EXACTLY: str
     SPECIFIED: str
     MINIMUM: str
     MIN_PLUS1: str

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

@@ -28,10 +28,11 @@ error, info = _lggr.error, _lggr.info
 
 class SolverGurobi(SolverPyomo, PoolHandler):
     """
-    For setting `threadlimit`, the SolverGurobi instance must have this option in
-    its `options` attribute before the call to .set_problem().
+    For setting ``threadlimit``, the SolverGurobi instance must have this option in
+    its ``options`` attribute before the call to :meth:`set_problem`.
+
+    Example::
 
-    Example:
       solver.options.update(threadlimit=8)
       solver.set_problem(...)
       solver.solve(...)
@@ -62,7 +63,7 @@ class SolverGurobi(SolverPyomo, PoolHandler):
         warmstart: nx.Graph | None = None,
     ):
         """
-        This will keep the Gurobi license in use until a call to `get_solution()`.
+        This will keep the Gurobi license in use until a call to :meth:`get_solution`.
         """
         solver = pyo.SolverFactory(
             'gurobi_persistent',

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

@@ -2,7 +2,6 @@
 # https://gitlab.windenergy.dtu.dk/TOPFARM/OptiWindNet/
 
 import logging
-import math
 from datetime import timedelta
 from itertools import chain
 from typing import Any
@@ -24,6 +23,7 @@ from ._core import (
     SolutionInfo,
     Solver,
     Topology,
+    feeder_and_load_bounds,
     physical_core_count,
 )
 
@@ -72,7 +72,8 @@ class SolverORTools(Solver, PoolHandler):
     """OR-Tools MathOpt wrapper using the selected backend.
 
     This class wraps and changes the behavior of MathOpt in order to save all
-    solutions found to a pool. Meant to be used with `investigate_pool()`.
+    solutions found to a pool. Meant to be used with
+    :meth:`.PoolHandler._investigate_pool`.
     """
 
     name: str
@@ -120,8 +121,8 @@ class SolverORTools(Solver, PoolHandler):
     ) -> SolutionInfo:
         """Wrapper for MathOpt solve() that saves all solutions.
 
-        This method uses a MIP_SOLUTION callback to fill a solution pool stored
-        in the attribute self.solutions.
+        This method uses a ``MIP_SOLUTION`` callback to fill a solution pool stored
+        in the attribute ``self.solutions``.
         """
         try:
             model = self.model
@@ -315,13 +316,16 @@ def make_min_length_model(
     Args:
       A: graph with the available edges to choose from
       capacity: maximum link flow capacity
-      topology: one of Topology.{BRANCHED, RADIAL}
+      topology: one of ``Topology.{BRANCHED, RADIAL}``
       feeder_route:
-        FeederRoute.SEGMENTED -> feeder routes may be detoured around subtrees;
-        FeederRoute.STRAIGHT -> feeder routes must be straight, direct lines
-      feeder_limit: one of FeederLimit.{MINIMUM, UNLIMITED, SPECIFIED,
-        MIN_PLUS1, MIN_PLUS2, MIN_PLUS3}
-      max_feeders: only used if feeder_limit is FeederLimit.SPECIFIED
+        ``FeederRoute.SEGMENTED`` → feeder routes may be detoured around subtrees;
+        ``FeederRoute.STRAIGHT`` → feeder routes must be straight, direct lines
+      feeder_limit: one of ``FeederLimit.{MINIMUM, UNLIMITED, EXACTLY, SPECIFIED,
+        MIN_PLUS1, MIN_PLUS2, MIN_PLUS3}``
+      balanced: enforce subtree loads differing at most by one unit (only
+        possible if ``feeder_limit`` pins the feeder count to a single value)
+      max_feeders: upper bound if ``feeder_limit`` is ``FeederLimit.SPECIFIED``,
+        exact count if it is ``FeederLimit.EXACTLY``, unused otherwise
     """
     R = A.graph['R']
     T = A.graph['T']
@@ -429,62 +433,41 @@ def make_min_length_model(
         )
 
     # feeder limits
-    min_feeders = math.ceil(T / k)
+    feeders_lb, feeders_ub, load_lb, load_ub = feeder_and_load_bounds(
+        T, k, feeder_limit, max_feeders, balanced
+    )
+    if feeders_ub is not None and feeder_limit.name.startswith('MIN_PLUS'):
+        # derived from the minimum: surface it in the solution's metadata
+        max_feeders = feeders_ub
     all_feeder_vars_sum = sum(link_[t, r] for r in _R for t in _T)
-    if feeder_limit is FeederLimit.UNLIMITED:
+    if feeders_lb == feeders_ub:
+        m.add_linear_constraint(
+            all_feeder_vars_sum == feeders_lb, name='feeder_limit_eq'
+        )
+    elif feeders_ub is None:
         # valid inequality: number of feeders is at least the minimum
         m.add_linear_constraint(
-            all_feeder_vars_sum >= min_feeders, name='feeder_limit_lb'
+            all_feeder_vars_sum >= feeders_lb, name='feeder_limit_lb'
         )
-        if balanced:
-            warn(
-                'Model option <balanced = True> is incompatible with <feeder_limit'
-                ' = UNLIMITED>: model will not enforce balanced subtrees.'
-            )
     else:
-        is_equal_not_range = False
-        if feeder_limit is FeederLimit.SPECIFIED:
-            if max_feeders == min_feeders:
-                is_equal_not_range = True
-            elif max_feeders < min_feeders:
-                raise ValueError('max_feeders is below the minimum necessary')
-        elif feeder_limit is FeederLimit.MINIMUM:
-            is_equal_not_range = True
-        elif feeder_limit is FeederLimit.MIN_PLUS1:
-            max_feeders = min_feeders + 1
-        elif feeder_limit is FeederLimit.MIN_PLUS2:
-            max_feeders = min_feeders + 2
-        elif feeder_limit is FeederLimit.MIN_PLUS3:
-            max_feeders = min_feeders + 3
-        else:
-            raise NotImplementedError('Unknown value:', feeder_limit)
-        if is_equal_not_range:
+        m.add_linear_constraint(
+            expr=all_feeder_vars_sum,
+            lb=feeders_lb,
+            ub=feeders_ub,
+            name='feeder_limit_interval',
+        )
+
+    # enforce balanced subtrees (subtree loads differ at most by one unit)
+    if load_lb is not None:
+        for t, r in stars:
             m.add_linear_constraint(
-                all_feeder_vars_sum == min_feeders, name='feeder_limit_eq'
+                flow_[t, r] >= link_[t, r] * load_lb, name=f'balanced_lb_{t}~r{-r}'
             )
-        else:
+    if load_ub is not None:
+        for t, r in stars:
             m.add_linear_constraint(
-                expr=all_feeder_vars_sum,
-                lb=min_feeders,
-                ub=max_feeders,
-                name='feeder_limit_interval',
+                flow_[t, r] <= link_[t, r] * load_ub, name=f'balanced_ub_{t}~r{-r}'
             )
-        # enforce balanced subtrees (subtree loads differ at most by one unit)
-        if balanced:
-            if is_equal_not_range:
-                feeder_min_load = T // min_feeders
-                if feeder_min_load < capacity:
-                    for t, r in stars:
-                        m.add_linear_constraint(
-                            flow_[t, r] >= link_[t, r] * feeder_min_load,
-                            name=f'balanced_{t}~r{-r}',
-                        )
-            else:
-                warn(
-                    'Model option <balanced = True> is incompatible with '
-                    'having a range of possible feeder counts: model will '
-                    'not enforce balanced subtrees.'
-                )
 
     # radial or branched topology
     if topology is Topology.RADIAL:
@@ -552,9 +535,9 @@ _make_min_length_model_fingerprint = fun_fingerprint(make_min_length_model)
 def warmup_model(
     model: mathopt.Model, metadata: ModelMetadata, S: nx.Graph
 ) -> mathopt.Model:
-    """Set initial solution into `model`.
+    """Set initial solution into ``model``.
 
-    Changes `model` and `metadata` in-place.
+    Changes ``model`` and ``metadata`` in-place.
 
     Args:
       model: CP-SAT model to apply the solution to.

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

@@ -2,7 +2,6 @@
 # https://gitlab.windenergy.dtu.dk/TOPFARM/OptiWindNet/
 
 import logging
-import math
 from collections import namedtuple
 from itertools import chain
 from typing import Any
@@ -24,6 +23,7 @@ from ._core import (
     SolutionInfo,
     Solver,
     Topology,
+    feeder_and_load_bounds,
     physical_core_count,
 )
 
@@ -68,7 +68,10 @@ _default_options = dict(
         liftAndProjectCuts='off',
         residualCapacityCuts='off',
     ),
-    highs={},
+    highs=dict(
+        parallel='on',
+        # threads=0,  # 0 means automatic and is HiGHS's default
+    ),
     scip={},
 )
 
@@ -223,12 +226,17 @@ class SolverPyomoAppsi(Solver):
             exc.args += ('.set_problem() must be called before .solve()',)
             raise
         applied_options = self.options | options
+        for key, value in applied_options.items():
+            if key in solver.config:
+                solver.config[key] = value
+            else:
+                solver._solver_options[key] = value
         stopping = {
             _optkey[name].time_limit: time_limit,
             _optkey[name].mip_gap: mip_gap,
         }
         self.stopping = stopping
-        for k, v in (applied_options | stopping).items():
+        for k, v in stopping.items():
             solver.config[k] = v
         solver.config.load_solution = False
         solver.config.stream_solver = verbose
@@ -290,13 +298,16 @@ def make_min_length_model(
     Args:
       A: graph with the available edges to choose from
       capacity: maximum link flow capacity
-      topology: one of Topology.{BRANCHED, RADIAL}
+      topology: one of ``Topology.{BRANCHED, RADIAL}``
       feeder_route:
-        FeederRoute.SEGMENTED -> feeder routes may be detoured around subtrees;
-        FeederRoute.STRAIGHT -> feeder routes must be straight, direct lines
-      feeder_limit: one of FeederLimit.{MINIMUM, UNLIMITED, SPECIFIED,
-        MIN_PLUS1, MIN_PLUS2, MIN_PLUS3}
-      max_feeders: only used if feeder_limit is FeederLimit.SPECIFIED
+        ``FeederRoute.SEGMENTED`` → feeder routes may be detoured around subtrees;
+        ``FeederRoute.STRAIGHT`` → feeder routes must be straight, direct lines
+      feeder_limit: one of ``FeederLimit.{MINIMUM, UNLIMITED, EXACTLY, SPECIFIED,
+        MIN_PLUS1, MIN_PLUS2, MIN_PLUS3}``
+      balanced: enforce subtree loads differing at most by one unit (only
+        possible if ``feeder_limit`` pins the feeder count to a single value)
+      max_feeders: upper bound if ``feeder_limit`` is ``FeederLimit.SPECIFIED``,
+        exact count if it is ``FeederLimit.EXACTLY``, unused otherwise
     """
     R = A.graph['R']
     T = A.graph['T']
@@ -431,76 +442,46 @@ def make_min_length_model(
     )
 
     # feeder limits
-    min_feeders = math.ceil(T / m.k)
-    if feeder_limit is FeederLimit.UNLIMITED:
+    feeders_lb, feeders_ub, load_lb, load_ub = feeder_and_load_bounds(
+        T, capacity, feeder_limit, max_feeders, balanced
+    )
+    if feeders_ub is not None and feeder_limit.name.startswith('MIN_PLUS'):
+        # derived from the minimum: surface it in the solution's metadata
+        max_feeders = feeders_ub
+    if feeders_lb == feeders_ub:
+        m.cons_feeder_limit_eq = pyo.Constraint(
+            rule=(lambda m: sum(m.link_[t, r] for r in _R for t in _T) == feeders_lb),
+            name='feeder_limit_eq',
+        )
+    else:
         # valid inequality: number of feeders is at least the minimum
         m.cons_feeder_limit_lb = pyo.Constraint(
-            rule=(lambda m: sum(m.link_[t, r] for r in _R for t in _T) >= min_feeders),
+            rule=(lambda m: sum(m.link_[t, r] for r in _R for t in _T) >= feeders_lb),
             name='feeder_limit_lb',
         )
-        if balanced:
-            warn(
-                'Model option <balanced = True> is incompatible with <feeder_limit'
-                ' = UNLIMITED>: model will not enforce balanced subtrees.'
-            )
-    else:
-        is_equal_not_range = False
-        if feeder_limit is FeederLimit.SPECIFIED:
-            if max_feeders == min_feeders:
-                is_equal_not_range = True
-            elif max_feeders < min_feeders:
-                raise ValueError('max_feeders is below the minimum necessary')
-        elif feeder_limit is FeederLimit.MINIMUM:
-            is_equal_not_range = True
-        elif feeder_limit is FeederLimit.MIN_PLUS1:
-            max_feeders = min_feeders + 1
-        elif feeder_limit is FeederLimit.MIN_PLUS2:
-            max_feeders = min_feeders + 2
-        elif feeder_limit is FeederLimit.MIN_PLUS3:
-            max_feeders = min_feeders + 3
-        else:
-            raise NotImplementedError('Unknown value:', feeder_limit)
-        if is_equal_not_range:
-            m.cons_feeder_limit_eq = pyo.Constraint(
-                rule=(
-                    lambda m: sum(m.link_[t, r] for r in _R for t in _T) == min_feeders
-                ),
-                name='feeder_limit_eq',
-            )
-        else:
-            m.cons_feeder_limit_lb = pyo.Constraint(
-                rule=(
-                    lambda m: sum(m.link_[t, r] for r in _R for t in _T) >= min_feeders
-                ),
-                name='feeder_limit_lb',
-            )
+        if feeders_ub is not None:
             m.cons_feeder_limit_ub = pyo.Constraint(
                 rule=(
-                    lambda m: sum(m.link_[t, r] for r in _R for t in _T) <= max_feeders
+                    lambda m: sum(m.link_[t, r] for r in _R for t in _T) <= feeders_ub
                 ),
                 name='feeder_limit_ub',
             )
-        # enforce balanced subtrees (subtree loads differ at most by one unit)
-        if balanced:
-            if is_equal_not_range:
-                feeder_min_load = T // min_feeders
-                if feeder_min_load < capacity:
-                    m.cons_balanced = pyo.Constraint(
-                        m.T,
-                        m.R,
-                        rule=(
-                            lambda m, t, r: (
-                                m.flow_[t, r] >= m.link_[t, r] * feeder_min_load
-                            )
-                        ),
-                        name='balanced',
-                    )
-            else:
-                warn(
-                    'Model option <balanced = True> is incompatible with '
-                    'having a range of possible feeder counts: model will '
-                    'not enforce balanced subtrees.'
-                )
+
+    # enforce balanced subtrees (subtree loads differ at most by one unit)
+    if load_lb is not None:
+        m.cons_balanced_lb = pyo.Constraint(
+            m.T,
+            m.R,
+            rule=(lambda m, t, r: m.flow_[t, r] >= m.link_[t, r] * load_lb),
+            name='balanced_lb',
+        )
+    if load_ub is not None:
+        m.cons_balanced_ub = pyo.Constraint(
+            m.T,
+            m.R,
+            rule=(lambda m, t, r: m.flow_[t, r] <= m.link_[t, r] * load_ub),
+            name='balanced_ub',
+        )
 
     # radial or branched topology
     if topology is Topology.RADIAL:
@@ -581,9 +562,9 @@ _make_min_length_model_fingerprint = fun_fingerprint(make_min_length_model)
 def warmup_model(
     model: pyo.ConcreteModel, metadata: ModelMetadata, S: nx.Graph
 ) -> pyo.ConcreteModel:
-    """Set initial solution into `model`.
+    """Set initial solution into ``model``.
 
-    Changes `model` and `metadata` in-place.
+    Changes ``model`` and ``metadata`` in-place.
 
     Args:
       model: pyomo model to apply the solution to.