Metadata-Version: 2.4
Name: oowl
Version: 0.1.0
Summary: Onshore and offshore wind layout generation.
Author: DTU Wind Energy Systems
License-Expression: MIT
Project-URL: Repository, https://gitlab.windenergy.dtu.dk/sys/OOWL
Project-URL: Documentation, https://oowl-4781ed.pages.windenergy.dtu.dk
Keywords: wind farm,onshore,offshore,layout,boundary,geometry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0
Requires-Dist: shapely>=2.1
Requires-Dist: matplotlib>=3.8.4
Requires-Dist: scipy>=1.13
Requires-Dist: PyYAML>=6.0.2
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Provides-Extra: windio-compat
Requires-Dist: windIO>=2.1.1; extra == "windio-compat"
Provides-Extra: gwa-compat
Requires-Dist: py_wake; extra == "gwa-compat"
Dynamic: license-file

# OOWL

[![PyPI](https://img.shields.io/pypi/v/oowl.svg)](https://pypi.org/project/oowl/)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![ty](https://img.shields.io/badge/types-ty-261230.svg)](https://github.com/astral-sh/ty)
[![docs](https://img.shields.io/badge/docs-pages-blue.svg)](https://oowl-4781ed.pages.windenergy.dtu.dk)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://gitlab.windenergy.dtu.dk/sys/OOWL/-/blob/main/LICENSE)

**Onshore and Offshore Wind Layouts** (**OOWL**, pronounced /aʊl/ like *owl*)
generates diverse, exact-count wind-farm layouts from composable geometry and
placement methods. It provides boundaries, turbine layouts, wind resources,
turbine models, and curated reference farms, and writes them as windIO.

OOWL is not a wake model or a wind-farm layout optimizer, and it does not try to
reconstruct a particular real wind farm. Those are downstream applications that
consume OOWL's output.

## Installation

OOWL requires Python 3.12 or newer and is imported as `oowl`.

```bash
pip install oowl
```

To work from a checkout, or to develop OOWL.

```bash
git clone https://gitlab.windenergy.dtu.dk/sys/OOWL.git
cd OOWL
pip install -e .

# or the locked development environment
pixi install --locked --environment dev
```

See [Installation](https://oowl-4781ed.pages.windenergy.dtu.dk/installation.html)
for the optional extras and the supported dependency bounds.

## Draw a farm

Describe the scenario you want as a sampler, then draw from it.

```python
import oowl
from oowl import boundaries as B
from oowl import layouts as L

spec = oowl.Sampler(
    B.OffshorePolygon(area=45_000_000, seed=3),
    L.Grid(n_turbines=92, lattice_angle=60, seed=4),
)

farm = spec.sample()[0]
farm.plot()
farm.save("farm.yaml")
```

The sampler is validated when built and can be drawn from repeatedly with the
same result. `sample(n)` returns a tuple of scenarios. Boundaries, strings,
layouts, surfaces, wind resources and turbines are six composable layers. See
[Concepts](https://oowl-4781ed.pages.windenergy.dtu.dk/concepts.html).

## Draw a dataset

Give any value a `(low, high)` range, an `f(rng) -> value` callable or an
`SP.Choice`, and the same description becomes a population.

```python
import oowl
from oowl import boundaries as B, layouts as L, sampling as SP

spec = oowl.Sampler(
    boundary=B.OffshorePolygon,
    layout=SP.Choice(
        [L.Grid, L.PoissonDisc, L.Delaunay],
        probabilities=[0.5, 0.3, 0.2],
    ),
    n_turbines=(40, 90),
    density={"minimum_spacing": 800.0},
    seed=7,
)

farms = spec.sample(200)
for index, farm in enumerate(farms):
    farm.save(f"dataset/farm_{index:04d}.yaml")
```

`density` names how tightly turbines are packed, here a minimum turbine
distance in meters. Count, area and density constrain one geometry, so a
sampler takes any two of them. A count and a spacing scale each boundary to
fit, which keeps every farm buildable. `n_farms=` makes each scenario a
`Cluster` of farms placed together, and `domain=` a region of development
sites.

Seeds are derived per scenario, so `spec.sample(3)` repeats the first three
scenarios of `spec.sample(200)`, `spec.sample(50, start=150)` shards the
population, and `spec.stream()` yields scenarios one at a time.
`[farm.summary() for farm in farms]` gives one row of metrics per farm.

## windIO

`farm.save(path)` and `oowl.load(path)` write and read one farm as a windIO
`wind_energy_system`, with its wind resource and turbine types. `Cluster.save`
and `Cluster.load` use a directory. OOWL writes windIO directly and does not
depend on the `windIO` package. Substations and cable arrays are out of scope.

## Documentation

The documentation is at **<https://oowl-4781ed.pages.windenergy.dtu.dk>**,
with a [Quickstart](https://oowl-4781ed.pages.windenergy.dtu.dk/quickstart.html),
[Concepts](https://oowl-4781ed.pages.windenergy.dtu.dk/concepts.html), the
[API reference](https://oowl-4781ed.pages.windenergy.dtu.dk/api/index.html) and
executable notebooks, including integrations with PyWake, TOPFARM and
OptiWindNet.

## Citation

If you use OOWL, please cite it.

```bibtex
@software{OOWL_0_1_0_2026,
  author = {Rasmussen, Frederik Peder Weilmann and Schøler, Jens Peter and de Alencar, Mauricio Souza},
  title = {{OOWL: Onshore and Offshore Wind Layouts}},
  year = {2026},
  version = {0.1.0},
  url = {https://gitlab.windenergy.dtu.dk/sys/OOWL},
  license = {MIT},
}
```

Citation metadata and the author list are kept in [`CITATION.cff`](https://gitlab.windenergy.dtu.dk/sys/OOWL/-/blob/main/CITATION.cff).

## Contributing

Contributions are welcome. See the [contribution guide](https://gitlab.windenergy.dtu.dk/sys/OOWL/-/blob/main/CONTRIBUTING.md). Run
`pixi run --environment dev lint`, `format-check`, `typecheck`, `test` and
`docs` before submitting, and record user-visible changes in the
[changelog](https://gitlab.windenergy.dtu.dk/sys/OOWL/-/blob/main/CHANGELOG.md).

## License

MIT. See [`LICENSE`](https://gitlab.windenergy.dtu.dk/sys/OOWL/-/blob/main/LICENSE). Copyright (c) 2026 DTU Wind and Energy Systems.
