---
jupytext:
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

# OOWL: Onshore and Offshore Wind Layouts

**OOWL** (pronounced /aʊl/ like *owl*) draws wind farms with an exact turbine
count inside a boundary you describe, placed by the method you pick. One
description draws one farm or a thousand.

```{code-cell} ipython3
:tags: [remove-input]

import matplotlib.pyplot as plt

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

site = B.OffshorePolygon(area=24_000_000, seed=1)
families = (
    ("Grid", L.Grid(n_turbines=64, lattice_angle=60, seed=4)),
    ("Sunflower", L.Sunflower(n_turbines=64, rotation=15, seed=6)),
    ("Poisson disc", L.PoissonDisc(n_turbines=64, seed=8)),
    ("Perimeter", L.Perimeter(n_turbines=64, seed=3)),
)

fig, axes = plt.subplots(1, 4, figsize=(12.5, 3.3))
for ax, (title, method) in zip(axes, families):
    oowl.Sampler(site, method).sample()[0].plot(ax=ax, title=title)
    ax.set_axis_off()
fig.tight_layout()
```

One offshore boundary, four layout families, 64 turbines in every panel.

## Install

```bash
pip install oowl
```

[Installation](installation.md) covers pip, pixi, and a development checkout.

## Draw one farm

Describe the scenario, then draw from it.

```{code-cell} ipython3
import matplotlib.pyplot as plt

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

boundary = B.Rectangle(9, 5, area=45_000_000)
spec = oowl.Sampler(boundary, L.Grid(n_turbines=92, lattice_angle=60, seed=4))

farm = spec.sample()[0]
print(farm.n_turbines, "turbines at", farm.positions.shape, "coordinates")

ax = farm.plot()
```

## Draw a population

Give a value a range and the description becomes a population.

```{code-cell} ipython3
population = oowl.Sampler(
    boundary=B.OffshorePolygon,
    layout=L.Grid,
    n_turbines=(40, 120),
    density={"minimum_spacing": 800.0},
    seed=7,
)

fig, axes = plt.subplots(1, 3, figsize=(11.0, 3.4))
for ax, drawn in zip(axes, population.sample(3)):
    drawn.plot(ax=ax, title=f"n = {drawn.n_turbines}")
fig.tight_layout()
```

Seeds are derived per scenario, so farm *i* is the same however many are drawn.

## The six layers

| Layer | What it decides |
|---|---|
| **boundaries** | the farm area, including holes, partitions and regions |
| **strings** | optional line guides to place turbines along |
| **layouts** | exact turbine placement inside the area |
| **surfaces** | optional terrain or bathymetry |
| **resources** | wind conditions, sampled with stability |
| **turbines** | turbine models, per position |

A scenario is a {class}`~oowl.Farm`, or a {class}`~oowl.Cluster` when `n_farms`
is given or `domain` scatters a region of sites.

## Where to go next

- {doc}`Quickstart <quickstart>`, a first farm and population
- {doc}`Concepts <concepts>`, the model behind the sampler
- {doc}`Layout families <layouts/families>`, every placement method
- {doc}`Populations <sampling/populations>`, ranges, choices and links
- {doc}`Wind resources <wind-resources/resources>`, direction, speed,
  stability and turbulence
- {doc}`windIO interchange <interoperability/windio>`
- {doc}`API reference <api/index>`

```{toctree}
:maxdepth: 3
:hidden:
:caption: Getting started

installation
quickstart
concepts
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: Boundaries

boundaries/shapes
boundaries/fitted-offshore
boundaries/boundary-modifiers
boundaries/regions
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: Layouts

layouts/families
layouts/fitting
layouts/combining
layouts/multipart
layouts/layout-modifiers
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: Strings

strings/string-layouts
strings/string-modifiers
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: Sampling

sampling/populations
sampling/spacing
sampling/drawing
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: Metrics

metrics/spatial-metrics
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: Surfaces

surfaces/terrain-and-bathymetry
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: Wind resources

wind-resources/resources
wind-resources/stability-and-turbulence
wind-resources/coverage
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: Turbines

turbines/models
turbines/farms
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: Interoperability

interoperability/windio
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: Integrations

integrations/pywake
integrations/topfarm
integrations/optiwindnet-cabling
```

```{toctree}
:maxdepth: 3
:hidden:
:caption: Reference

offshore-reference
api/index
```

```{toctree}
:maxdepth: 3
:hidden:
:caption: Project development

project-development/design
project-development/coding-style
project-development/contributing
project-development/contributors-and-citation
```