oowl 0.0.1__py3-none-any.whl

oowl/__init__.py

@@ -0,0 +1,45 @@
+"""OOWL: onshore and offshore wind layout generation.
+
+Three composable layers combined by a single entry point:
+
+* :mod:`oowl.boundaries` -- region generators (``Circle``, ``Rectangle``,
+  ``RadialPolygon``, ...), composable with modifiers (shipping channels,
+  exclusion zones).
+* :mod:`oowl.layouts` -- turbine placement algorithms (``GridLayout``),
+  sized strictly by turbine count and fitted to a boundary by a pluggable
+  :class:`~oowl.layouts.fitters.Fitter`.
+* :mod:`oowl.strings` -- optional ordered guide geometry consumed by
+  ``StringLayout``.
+
+Combine them with :func:`generate_farm`, and persist results with windIO via
+:meth:`Farm.save <oowl.layouts.base.Farm.save>` / :func:`load`.
+"""
+
+from __future__ import annotations
+
+from . import boundaries, layouts, plotting, site, strings
+from .api import generate_farm
+from .layouts import Farm
+from .plotting import plot_boundary, plot_farm
+from .site import SiteConditions, Weibull, WindRose, generate_site_conditions
+from .windio import load, save
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "boundaries",
+    "layouts",
+    "strings",
+    "plotting",
+    "site",
+    "generate_farm",
+    "generate_site_conditions",
+    "Farm",
+    "SiteConditions",
+    "Weibull",
+    "WindRose",
+    "plot_boundary",
+    "plot_farm",
+    "load",
+    "save",
+]

oowl/_random.py

@@ -0,0 +1,71 @@
+"""Shared random-number utilities."""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = [
+    "as_rng",
+    "farthest_point_sample",
+    "resolve_seed",
+    "spawn_seeds",
+]
+
+
+_MAX_SEED = np.iinfo(np.uint64).max
+
+
+def resolve_seed(seed: int | np.random.Generator | None) -> int:
+    """Resolve ``seed`` to a replayable non-negative integer.
+
+    ``None`` receives fresh operating-system entropy. Passing a generator
+    consumes one integer from it, isolating the generated object from later
+    changes to that generator's state.
+    """
+    if isinstance(seed, np.random.Generator):
+        return int(seed.integers(0, _MAX_SEED, dtype=np.uint64))
+    if seed is None:
+        return int(np.random.SeedSequence().entropy)
+    if not isinstance(seed, (int, np.integer)) or int(seed) < 0:
+        raise ValueError("seed must be a non-negative integer, Generator, or None")
+    return int(seed)
+
+
+def spawn_seeds(seed: int, n_children: int) -> tuple[int, ...]:
+    """Derive independent, deterministic child seeds from ``seed``."""
+    if n_children < 0:
+        raise ValueError("n_children must be >= 0")
+    children = np.random.SeedSequence(int(seed)).spawn(n_children)
+    return tuple(
+        int(child.generate_state(1, dtype=np.uint64)[0])
+        for child in children
+    )
+
+
+def as_rng(seed: int | np.random.Generator | None) -> np.random.Generator:
+    """Return a NumPy ``Generator`` from a seed, generator, or ``None``."""
+    if isinstance(seed, np.random.Generator):
+        return seed
+    return np.random.default_rng(seed)
+
+
+def farthest_point_sample(pts: np.ndarray, n: int, rng) -> np.ndarray:
+    """Select *n* points from *pts* using farthest-point sampling.
+
+    Iteratively picks the point farthest from all previously selected points,
+    producing a spatially uniform subsample that preserves coverage.
+    """
+    m = len(pts)
+    if m <= n:
+        return pts
+
+    selected = [int(rng.integers(m))]
+    dist_sq = np.sum((pts - pts[selected[0]]) ** 2, axis=1)
+
+    for _ in range(n - 1):
+        idx = int(np.argmax(dist_sq))
+        selected.append(idx)
+        new_dist_sq = np.sum((pts - pts[idx]) ** 2, axis=1)
+        dist_sq = np.minimum(dist_sq, new_dist_sq)
+
+    return pts[selected]

oowl/api.py

@@ -0,0 +1,243 @@
+"""Single public entry point for ordinary, multipart, and clustered farms."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from copy import copy
+
+import numpy as np
+
+from ._random import as_rng, resolve_seed, spawn_seeds
+from .boundaries.base import Boundary
+from .boundaries.composites import BoundaryCluster
+from .layouts.base import Farm, LayoutAlgorithm, _allocate_counts, _combine_guides
+from .layouts.composites import MixedLayout
+
+__all__ = ["generate_farm"]
+
+
+def generate_farm(
+    boundary: Boundary | LayoutAlgorithm,
+    layout: LayoutAlgorithm | MixedLayout | Sequence[LayoutAlgorithm] | None = None,
+    seed=None,
+) -> Farm:
+    """Generate one exact-count layout, optionally fitted to a boundary.
+
+    A multipart ordinary boundary remains one farm and uses one algorithm.
+    ``BoundaryCluster`` coordinates multiple logical farms and accepts one
+    fixed algorithm, a ``MixedLayout``, or an explicit algorithm per farm.
+    """
+    if layout is None:
+        if not isinstance(boundary, LayoutAlgorithm):
+            raise TypeError("standalone generation requires a LayoutAlgorithm")
+        layout = boundary
+        boundary = None
+
+    if isinstance(boundary, BoundaryCluster):
+        if isinstance(layout, MixedLayout):
+            effective_seed = layout.seed if seed is None else seed
+            return _generate_distributed_cluster(
+                boundary,
+                layout.n_turbines,
+                layout.layouts,
+                layout.probabilities,
+                effective_seed,
+                selection_method="mixed",
+            )
+        if isinstance(layout, LayoutAlgorithm):
+            if layout.n_turbines is None:
+                raise ValueError("n_turbines is required for cluster generation")
+            effective_seed = layout.seed if seed is None else seed
+            return _generate_distributed_cluster(
+                boundary,
+                layout.n_turbines,
+                (layout,),
+                (1.0,),
+                effective_seed,
+                selection_method="fixed",
+            )
+        return _generate_explicit_cluster(boundary, layout, seed)
+
+    if boundary is None:
+        if not isinstance(layout, LayoutAlgorithm):
+            raise TypeError("standalone generation requires a LayoutAlgorithm")
+        algorithm = copy(layout)
+        if seed is not None:
+            algorithm.seed = seed
+        return algorithm.generate()
+
+    if isinstance(layout, MixedLayout):
+        return _generate_mixed_single(boundary, layout, seed)
+    if not isinstance(layout, LayoutAlgorithm):
+        raise TypeError("an ordinary Boundary requires one LayoutAlgorithm")
+    algorithm = copy(layout)
+    if seed is not None:
+        algorithm.seed = seed
+    return algorithm.generate(boundary)
+
+
+def _with_selection(result, root_seed, index, algorithm, child_seed):
+    provenance = dict(result.provenance)
+    provenance["seed"] = int(root_seed)
+    provenance["selection"] = {
+        "method": "mixed",
+        "index": int(index),
+        "algorithm": type(algorithm).__name__,
+        "seed": int(child_seed),
+    }
+    return Farm(
+        result.positions, result.boundary, provenance, guide=result.guide
+    )
+
+
+def _generate_mixed_single(boundary, mixed, seed):
+    root_seed = resolve_seed(mixed.seed if seed is None else seed)
+    selection_seed, child_seed = spawn_seeds(root_seed, 2)
+    rng = as_rng(selection_seed)
+    index = int(rng.choice(len(mixed.layouts), p=mixed.probabilities))
+    algorithm = copy(mixed.layouts[index])
+    algorithm.n_turbines = mixed.n_turbines
+    algorithm.seed = child_seed
+    result = algorithm.generate(boundary)
+    return _with_selection(result, root_seed, index, algorithm, child_seed)
+
+
+def _generate_distributed_cluster(
+    boundary,
+    n_turbines,
+    layouts,
+    probabilities,
+    seed,
+    selection_method,
+):
+    root_seed = resolve_seed(seed)
+    selection_seed, farm_root = spawn_seeds(root_seed, 2)
+    counts = _allocate_counts(
+        n_turbines, [farm.area for farm in boundary.boundaries]
+    )
+    selection_rng = as_rng(selection_seed)
+    selected = selection_rng.choice(
+        len(layouts), size=len(boundary.boundaries), p=probabilities
+    )
+    farm_seeds = spawn_seeds(farm_root, len(boundary.boundaries))
+    assignments = []
+    for count, layout_index, farm_seed in zip(counts, selected, farm_seeds):
+        layout_index = int(layout_index)
+        template = layouts[layout_index]
+        assignments.append((
+            template,
+            int(count),
+            farm_seed,
+            {
+                "method": selection_method,
+                "index": layout_index,
+                "algorithm": type(template).__name__,
+            },
+        ))
+    return _aggregate_cluster(
+        boundary, assignments, root_seed, n_turbines
+    )
+
+
+def _generate_explicit_cluster(boundary, layouts, seed):
+    if isinstance(layouts, LayoutAlgorithm) or not isinstance(layouts, Sequence):
+        raise TypeError(
+            "BoundaryCluster requires a sequence of LayoutAlgorithm objects"
+        )
+    layouts = tuple(layouts)
+    if len(layouts) != len(boundary.boundaries):
+        raise ValueError(
+            f"BoundaryCluster has {len(boundary.boundaries)} farms but "
+            f"received {len(layouts)} layouts"
+        )
+    for index, algorithm in enumerate(layouts):
+        if not isinstance(algorithm, LayoutAlgorithm):
+            raise TypeError(
+                f"cluster layout {index} must be a LayoutAlgorithm, "
+                f"not {type(algorithm).__name__}"
+            )
+        if algorithm.n_turbines is None:
+            raise ValueError(f"cluster layout {index} must define n_turbines")
+
+    root_seed = resolve_seed(seed) if seed is not None else None
+    override_seeds = (
+        spawn_seeds(root_seed, len(layouts)) if root_seed is not None else None
+    )
+    assignments = []
+    for index, template in enumerate(layouts):
+        override = override_seeds[index] if override_seeds is not None else None
+        assignments.append((
+            template,
+            template.n_turbines,
+            override,
+            {
+                "method": "explicit",
+                "index": index,
+                "algorithm": type(template).__name__,
+            },
+        ))
+    return _aggregate_cluster(
+        boundary,
+        assignments,
+        root_seed,
+        sum(algorithm.n_turbines for algorithm in layouts),
+    )
+
+
+def _aggregate_cluster(boundary, assignments, root_seed, requested_n):
+    positions = []
+    guides = []
+    farms = []
+    start = 0
+
+    for index, (farm_boundary, assignment) in enumerate(
+        zip(boundary.boundaries, assignments)
+    ):
+        template, count, override_seed, selection = assignment
+        count = int(count)
+        algorithm = copy(template)
+        algorithm.n_turbines = count
+        if override_seed is not None:
+            algorithm.seed = override_seed
+
+        child_provenance = None
+        child_seed = int(override_seed) if override_seed is not None else None
+        if count:
+            try:
+                result = algorithm.generate(farm_boundary)
+            except (TypeError, ValueError) as exc:
+                raise type(exc)(
+                    f"Could not generate cluster farm {index}: {exc}"
+                ) from exc
+            positions.append(result.positions)
+            guides.append(result.guide)
+            child_provenance = result.provenance
+            child_seed = child_provenance.get("seed")
+
+        stop = start + count
+        farms.append({
+            "farm_index": index,
+            "area": float(farm_boundary.area),
+            "n_turbines": count,
+            "start": start,
+            "stop": stop,
+            "seed": child_seed,
+            "selection": selection,
+            "layout": child_provenance,
+        })
+        start = stop
+
+    combined = np.concatenate(positions) if positions else np.empty((0, 2))
+    return Farm(
+        combined,
+        boundary,
+        {
+            "kind": "cluster",
+            "seed": int(root_seed) if root_seed is not None else None,
+            "requested_n": int(requested_n),
+            "achieved_n": int(len(combined)),
+            "farms": farms,
+            "modifiers": [],
+        },
+        guide=_combine_guides(guides),
+    )

oowl/boundaries/__init__.py

@@ -0,0 +1,36 @@
+"""Boundary geometries for wind farms.
+
+Concrete boundaries subclass :class:`Boundary` and return a Shapely
+``Polygon`` / ``MultiPolygon``. Extras (shipping channels, exclusion zones) are
+:class:`BoundaryModifier` objects applied via :class:`CompositeBoundary`, so
+they compose with any boundary. :class:`BoundaryCluster` explicitly groups
+boundaries belonging to separately configured farms.
+"""
+
+from __future__ import annotations
+
+from .base import Boundary
+from .composites import BoundaryCluster, CompositeBoundary
+from .hull import ConvexHull
+from .modifiers import BoundaryModifier, ExclusionZones, ShippingChannels
+from .primitives import Annulus, Circle, Ellipse, Rectangle, RegularPolygon, Square
+from .radial import RadialPolygon, RandomRadialPolygon, SmoothBlob
+
+__all__ = [
+    "Boundary",
+    "BoundaryCluster",
+    "CompositeBoundary",
+    "Rectangle",
+    "Square",
+    "RegularPolygon",
+    "Circle",
+    "Ellipse",
+    "Annulus",
+    "RadialPolygon",
+    "RandomRadialPolygon",
+    "SmoothBlob",
+    "ConvexHull",
+    "BoundaryModifier",
+    "ShippingChannels",
+    "ExclusionZones",
+]

oowl/boundaries/base.py

@@ -0,0 +1,117 @@
+"""Base classes for boundary geometries.
+
+A :class:`Boundary` owns a Shapely ``Polygon`` / ``MultiPolygon`` and exposes the
+small interface that layout fitters need (``area``, ``bounds``, ``centroid``,
+``contains``). Concrete shapes live in :mod:`primitives`, :mod:`radial` and
+:mod:`hull`. Extras such as shipping channels and exclusion zones are applied as
+:class:`~oowl.boundaries.modifiers.BoundaryModifier` objects through a
+:class:`~oowl.boundaries.composites.CompositeBoundary`, so they mix
+into *any* boundary.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+import numpy as np
+import shapely
+from shapely.geometry import MultiPolygon, Polygon
+from shapely.geometry.base import BaseGeometry
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .modifiers import BoundaryModifier
+
+__all__ = ["Boundary"]
+
+Point2D = tuple[float, float]
+
+
+class Boundary(ABC):
+    """Abstract wind farm boundary backed by a Shapely geometry."""
+
+    @abstractmethod
+    def _build_geometry(self) -> BaseGeometry:
+        """Construct and return the Shapely geometry for this boundary."""
+
+    @cached_property
+    def geometry(self) -> Polygon | MultiPolygon:
+        """The Shapely ``Polygon`` / ``MultiPolygon`` for this boundary."""
+        geometry = self._build_geometry()
+        if not isinstance(geometry, (Polygon, MultiPolygon)):
+            raise TypeError("boundary geometry must be a Polygon or MultiPolygon")
+        if geometry.is_empty or geometry.area <= 0:
+            raise ValueError("boundary geometry must have positive area")
+        if not geometry.is_valid:
+            raise ValueError("boundary geometry must be valid")
+        return geometry
+
+    # -- properties layouts/fitters rely on -------------------------------
+    @property
+    def area(self) -> float:
+        return self.geometry.area
+
+    @cached_property
+    def bounds(self) -> tuple[float, float, float, float]:
+        return self.geometry.bounds
+
+    @cached_property
+    def centroid(self) -> Point2D:
+        c = self.geometry.centroid
+        return (c.x, c.y)
+
+    def contains(self, points) -> np.ndarray:
+        """Vectorised point-in-boundary test, inclusive of the boundary edge.
+
+        Points lying exactly on the boundary count as contained, so turbines
+        that touch an edge are not spuriously dropped. For point queries this is
+        the ``covers`` predicate.
+
+        Parameters
+        ----------
+        points:
+            Array-like of shape ``(N, 2)`` (or ``(2,)``).
+
+        Returns
+        -------
+        numpy.ndarray
+            Boolean array of length ``N``.
+        """
+        pts = np.asarray(points, dtype=float).reshape(-1, 2)
+        return shapely.intersects_xy(self.geometry, pts[:, 0], pts[:, 1])
+
+    # -- composition (modifiers) ------------------------------------------
+    def with_modifiers(self, *modifiers: "BoundaryModifier"):
+        """Return a new boundary with ``modifiers`` applied in order."""
+        from .composites import CompositeBoundary
+
+        return CompositeBoundary(self, modifiers)
+
+    def with_channels(self, **kwargs):
+        """Cut shipping channels through this boundary (see ``ShippingChannels``)."""
+        from .modifiers import ShippingChannels
+
+        return self.with_modifiers(ShippingChannels(**kwargs))
+
+    def with_exclusions(self, *holes):
+        """Subtract exclusion zones (geometries or boundaries) from this boundary."""
+        from .modifiers import ExclusionZones
+
+        return self.with_modifiers(ExclusionZones(holes))
+
+    # -- plotting ----------------------------------------------------------
+    def plot(self, ax=None, **kwargs):
+        from ..plotting import plot_boundary
+
+        return plot_boundary(self.geometry, ax=ax, **kwargs)
+
+
+class _GeometryBoundary(Boundary):
+    """Internal boundary view over an existing polygon geometry."""
+
+    def __init__(self, geometry: Polygon | MultiPolygon):
+        self._geometry = geometry
+
+    def _build_geometry(self) -> BaseGeometry:
+        return self._geometry

oowl/boundaries/composites.py

@@ -0,0 +1,102 @@
+"""Compositions of logical farm boundaries and modifier chains."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from shapely.ops import unary_union
+
+from .base import Boundary, _GeometryBoundary
+from .modifiers import BoundaryModifier
+
+__all__ = ["CompositeBoundary", "BoundaryCluster"]
+
+
+class CompositeBoundary(Boundary):
+    """A base boundary with an ordered chain of geometry modifiers."""
+
+    def __init__(self, base: Boundary, modifiers: Iterable[BoundaryModifier]):
+        if not isinstance(base, Boundary):
+            raise TypeError("base must be a Boundary")
+        modifiers = tuple(modifiers)
+        for modifier in modifiers:
+            if not isinstance(modifier, BoundaryModifier):
+                raise TypeError("boundary modifiers must be BoundaryModifier objects")
+        if isinstance(base, CompositeBoundary):
+            self.base = base.base
+            self.modifiers = base.modifiers + modifiers
+        else:
+            self.base = base
+            self.modifiers = modifiers
+
+    def _build_geometry(self):
+        geometry = self.base.geometry
+        for modifier in self.modifiers:
+            geometry = modifier.apply(geometry)
+        return geometry
+
+    def with_modifiers(self, *modifiers):
+        return CompositeBoundary(self.base, self.modifiers + tuple(modifiers))
+
+
+class BoundaryCluster(Boundary):
+    """An ordered collection of non-overlapping logical wind farms."""
+
+    def __init__(self, boundaries: Iterable[Boundary]):
+        try:
+            members = tuple(boundaries)
+        except TypeError as exc:
+            raise TypeError(
+                "boundaries must be an iterable of Boundary objects"
+            ) from exc
+        if not members:
+            raise ValueError("BoundaryCluster requires at least one boundary")
+        for index, boundary in enumerate(members):
+            if isinstance(boundary, BoundaryCluster):
+                raise TypeError("nested BoundaryCluster objects are not supported")
+            if not isinstance(boundary, Boundary):
+                raise TypeError(
+                    f"cluster member {index} must be a Boundary, "
+                    f"not {type(boundary).__name__}"
+                )
+        for left in range(len(members)):
+            for right in range(left + 1, len(members)):
+                overlap = members[left].geometry.intersection(
+                    members[right].geometry
+                )
+                if overlap.area > 0:
+                    raise ValueError(
+                        f"cluster boundaries {left} and {right} overlap in area"
+                    )
+        self.boundaries = members
+
+    @classmethod
+    def from_components(cls, boundary: Boundary):
+        if not isinstance(boundary, Boundary):
+            raise TypeError("boundary must be a Boundary")
+        geometry = boundary.geometry
+        polygons = (
+            geometry.geoms
+            if geometry.geom_type == "MultiPolygon"
+            else [geometry]
+        )
+        return cls(_GeometryBoundary(polygon) for polygon in polygons)
+
+    def _build_geometry(self):
+        return unary_union([boundary.geometry for boundary in self.boundaries])
+
+    def with_modifiers(self, *modifiers):
+        for modifier in modifiers:
+            if not isinstance(modifier, BoundaryModifier):
+                raise TypeError("boundary modifiers must be BoundaryModifier objects")
+        geometries = [boundary.geometry for boundary in self.boundaries]
+        for modifier in modifiers:
+            geometries = modifier.apply_to_cluster(geometries)
+        members = [
+            _GeometryBoundary(geometry)
+            for geometry in geometries
+            if not geometry.is_empty and geometry.area > 0
+        ]
+        if not members:
+            raise ValueError("cluster modifiers removed every farm boundary")
+        return BoundaryCluster(members)

oowl/boundaries/hull.py

@@ -0,0 +1,38 @@
+"""Point-cloud based boundary shapes."""
+
+from __future__ import annotations
+
+import numpy as np
+from shapely.geometry import MultiPoint, Polygon
+from shapely.geometry.base import BaseGeometry
+
+from .._random import as_rng, resolve_seed
+from .base import Boundary, Point2D
+
+__all__ = ["ConvexHull"]
+
+
+class ConvexHull(Boundary):
+    """Convex boundary as the convex hull of random scattered points."""
+
+    def __init__(
+        self,
+        n_points: int = 20,
+        spread: float = 1.0,
+        center: Point2D = (0.0, 0.0),
+        seed: int | np.random.Generator | None = None,
+    ):
+        if n_points < 3:
+            raise ValueError("n_points must be >= 3")
+        self.n_points = n_points
+        self.spread = spread
+        self.center = center
+        self.seed = resolve_seed(seed)
+
+    def _build_geometry(self) -> BaseGeometry:
+        rng = as_rng(self.seed)
+        pts = rng.normal(loc=self.center, scale=self.spread, size=(self.n_points, 2))
+        hull = MultiPoint(pts).convex_hull
+        if not isinstance(hull, Polygon):
+            raise ValueError("convex hull did not produce a polygon; add more points")
+        return hull