oowl 0.0.1__tar.gz

oowl-0.0.1/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 DTU Wind and Energy Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

oowl-0.0.1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: oowl
+Version: 0.0.1
+Summary: Onshore and offshore wind layout generation.
+Author: DTU Wind Energy Systems
+License-Expression: MIT
+Project-URL: Repository, https://gitlab.windenergy.dtu.dk/fpwra/OOWL
+Project-URL: Documentation, https://oowl-4781ed.pages.windenergy.dtu.dk
+Keywords: wind farm,onshore,offshore,layout,boundary,geometry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: shapely>=2.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: scipy>=1.10
+Requires-Dist: windIO>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: jupyter; extra == "dev"
+Requires-Dist: ipykernel; extra == "dev"
+Dynamic: license-file
+
+# OOWL
+
+Onshore and Offshore Wind Layouts (OOWL) generates diverse, exact-count
+wind-farm layouts from composable geometry and placement methods.
+
+The Python package is currently imported as `oowl`.
+
+```python
+import oowl
+from oowl import boundaries as B
+from oowl import layouts as L
+
+boundary = B.Rectangle(9000, 5000).with_channels(
+    n_channels=2, width=500, seed=3
+)
+farm = oowl.generate_farm(
+    boundary,
+    L.GridLayout(n_turbines=92, lattice_angle=60, seed=4),
+)
+farm.plot()
+```
+
+## Model
+
+The public API has three independent layers:
+
+- `boundaries` define the allowed polygonal farm area. A `MultiPolygon` remains
+  one logical farm; `BoundaryCluster` explicitly represents multiple farms.
+- `strings` define optional ordered line guides. Breaks and meanders compose as
+  non-mutating geometry modifiers.
+- `layouts` place an exact turbine count. Grids occupy selected intersections
+  of an aligned parallelogram grid, circular layouts select from boundary-
+  clipped concentric rings, contour layouts follow nested inward copies of the
+  farm boundary and retain a central point by default, Poisson layouts provide
+  blue-noise patterns, and string
+  farms distribute turbines along guides.
+
+`oowl.generate_farm(...)` is the single entry point for ordinary boundaries,
+multipart farms, clusters, and standalone string layouts.
+
+```python
+contours = oowl.generate_farm(
+    boundary,
+    L.ContourLayout(n_turbines=80, include_center=True),
+)
+```
+
+## Strings and clusters
+
+```python
+from oowl import strings as S
+
+guide = S.Parallel(S.Straight(), n_strings=5, spacing=0.18)
+guide = guide.with_meander(roughness=0.03, seed=2)
+
+string_farm = oowl.generate_farm(
+    B.Circle(3000),
+    L.StringLayout(60, strings=guide),
+)
+
+cluster = B.BoundaryCluster.from_components(boundary)
+mixed = oowl.generate_farm(
+    cluster,
+    L.MixedLayout(
+        n_turbines=92,
+        layouts=[L.GridLayout(), L.StringLayout(strings=S.Straight())],
+        seed=8,
+    ),
+)
+```
+
+## Units and windIO
+
+Realized boundary and turbine coordinates are interpreted as metres. String
+guide lengths and spacing are relative shape parameters when fitted to a
+boundary; standalone `StringLayout.spacing` is dimensional.
+
+`Farm.positions` is an ordered `(N, 2)` array that maps directly to windIO's
+`coordinates.x` and `coordinates.y`. Cluster provenance stores contiguous farm
+slices so a future adapter can emit windIO's array of wind-farm objects. The
+package does not currently depend on windIO or model turbines, substations, or
+electrical collection arrays.
+
+## Randomness and provenance
+
+Explicit seeds reproduce a farm. An unseeded generation call receives fresh
+entropy and records the resolved seed in `Farm.provenance`, so it can be
+replayed later:
+
+```python
+farm = oowl.generate_farm(boundary, L.GridLayout(92))
+replay = oowl.generate_farm(
+    boundary,
+    L.GridLayout(92),
+    seed=farm.provenance["seed"],
+)
+```
+
+Random boundaries and guides resolve their seed when constructed. Reusing one
+such object therefore reuses the same realized geometry, while constructing a
+new unseeded object produces a new geometry.

oowl-0.0.1/README.md

@@ -0,0 +1,101 @@
+# OOWL
+
+Onshore and Offshore Wind Layouts (OOWL) generates diverse, exact-count
+wind-farm layouts from composable geometry and placement methods.
+
+The Python package is currently imported as `oowl`.
+
+```python
+import oowl
+from oowl import boundaries as B
+from oowl import layouts as L
+
+boundary = B.Rectangle(9000, 5000).with_channels(
+    n_channels=2, width=500, seed=3
+)
+farm = oowl.generate_farm(
+    boundary,
+    L.GridLayout(n_turbines=92, lattice_angle=60, seed=4),
+)
+farm.plot()
+```
+
+## Model
+
+The public API has three independent layers:
+
+- `boundaries` define the allowed polygonal farm area. A `MultiPolygon` remains
+  one logical farm; `BoundaryCluster` explicitly represents multiple farms.
+- `strings` define optional ordered line guides. Breaks and meanders compose as
+  non-mutating geometry modifiers.
+- `layouts` place an exact turbine count. Grids occupy selected intersections
+  of an aligned parallelogram grid, circular layouts select from boundary-
+  clipped concentric rings, contour layouts follow nested inward copies of the
+  farm boundary and retain a central point by default, Poisson layouts provide
+  blue-noise patterns, and string
+  farms distribute turbines along guides.
+
+`oowl.generate_farm(...)` is the single entry point for ordinary boundaries,
+multipart farms, clusters, and standalone string layouts.
+
+```python
+contours = oowl.generate_farm(
+    boundary,
+    L.ContourLayout(n_turbines=80, include_center=True),
+)
+```
+
+## Strings and clusters
+
+```python
+from oowl import strings as S
+
+guide = S.Parallel(S.Straight(), n_strings=5, spacing=0.18)
+guide = guide.with_meander(roughness=0.03, seed=2)
+
+string_farm = oowl.generate_farm(
+    B.Circle(3000),
+    L.StringLayout(60, strings=guide),
+)
+
+cluster = B.BoundaryCluster.from_components(boundary)
+mixed = oowl.generate_farm(
+    cluster,
+    L.MixedLayout(
+        n_turbines=92,
+        layouts=[L.GridLayout(), L.StringLayout(strings=S.Straight())],
+        seed=8,
+    ),
+)
+```
+
+## Units and windIO
+
+Realized boundary and turbine coordinates are interpreted as metres. String
+guide lengths and spacing are relative shape parameters when fitted to a
+boundary; standalone `StringLayout.spacing` is dimensional.
+
+`Farm.positions` is an ordered `(N, 2)` array that maps directly to windIO's
+`coordinates.x` and `coordinates.y`. Cluster provenance stores contiguous farm
+slices so a future adapter can emit windIO's array of wind-farm objects. The
+package does not currently depend on windIO or model turbines, substations, or
+electrical collection arrays.
+
+## Randomness and provenance
+
+Explicit seeds reproduce a farm. An unseeded generation call receives fresh
+entropy and records the resolved seed in `Farm.provenance`, so it can be
+replayed later:
+
+```python
+farm = oowl.generate_farm(boundary, L.GridLayout(92))
+replay = oowl.generate_farm(
+    boundary,
+    L.GridLayout(92),
+    seed=farm.provenance["seed"],
+)
+```
+
+Random boundaries and guides resolve their seed when constructed. Reusing one
+such object therefore reuses the same realized geometry, while constructing a
+new unseeded object produces a new geometry.

oowl-0.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oowl"
+version = "0.0.1"
+description = "Onshore and offshore wind layout generation."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "DTU Wind Energy Systems" }]
+keywords = ["wind farm", "onshore", "offshore", "layout", "boundary", "geometry"]
+dependencies = [
+    "numpy>=1.24",
+    "shapely>=2.0",
+    "matplotlib>=3.7",
+    "scipy>=1.10",
+    "windIO>=2.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "jupyter", "ipykernel"]
+
+[project.urls]
+Repository = "https://gitlab.windenergy.dtu.dk/fpwra/OOWL"
+Documentation = "https://oowl-4781ed.pages.windenergy.dtu.dk"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

oowl-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oowl-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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",
+]