Skip to content

Commit 01a5ced

Browse files
docs: rewrite README and replace workflow chart (#545)
* docs: rewrite README and replace workflow chart - New workflow chart in four steps (weather data, cutout, conversion, aggregation), drawn from the code by docs/scripts/workflow_chart.py, as SVG with light and dark variants. - README: shorter intro, step-by-step explanation, runnable example, citing section; images use absolute URLs so they render on PyPI. - Remove the old PNG/ODP/PDF chart. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01F4nx8J3uKBiSyYqsjhGtQw * docs: redraw workflow chart as a flow diagram in the docs palette - One flow diagram instead of four cards: the same data changes shape from weather map to cutout cube, power curve and regional time series. - Technology data and geodata enter as inputs into steps 3 and 4. - Input data can be global or regional (reanalysis or satellite). - Colours from the docs palette only; embedded Overpass font (OFL-1.1). - Region overlap shading is computed with shapely. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01F4nx8J3uKBiSyYqsjhGtQw * docs: refine workflow chart after design review - Footer row now holds only the inputs of steps 3 and 4; datasets and storage move into the step descriptions. - Input arrows join the flow as a clean T; axis labels share a baseline. - Cut-out box snaps to the map grid inside the SARAH disk. - Power curve no longer covers the axis; smoother weather field; lighter cube top face. - Add cooling demand and heat-pump COP; stronger dark-mode hairlines and a halo around the region outline. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01F4nx8J3uKBiSyYqsjhGtQw * docs: add dark-theme variants of notebook figures (#547) Notebook figures are PNGs on white, which shows as white boxes in the dark theme. A build hook now derives a transparent dark variant of each figure: white becomes transparent, thin neutral strokes take the theme's text colour, and data keeps its exact colours. The variant loads lazily, so light-theme readers do not download it. Co-authored-by: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 6d833e2 commit 01a5ced

13 files changed

Lines changed: 706 additions & 46 deletions

‎LICENSES/OFL-1.1.txt‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
SIL OPEN FONT LICENSE
2+
3+
Version 1.1 - 26 February 2007
4+
5+
PREAMBLE
6+
7+
The goals of the Open Font License (OFL) are to stimulate worldwide development of collaborative font projects, to support the font creation efforts of academic and linguistic communities, and to provide a free and open framework in which fonts may be shared and improved in partnership with others.
8+
9+
The OFL allows the licensed fonts to be used, studied, modified and redistributed freely as long as they are not sold by themselves. The fonts, including any derivative works, can be bundled, embedded, redistributed and/or sold with any software provided that any reserved names are not used by derivative works. The fonts and derivatives, however, cannot be released under any other type of license. The requirement for fonts to remain under this license does not apply to any document created using the fonts or their derivatives.
10+
11+
DEFINITIONS
12+
13+
"Font Software" refers to the set of files released by the Copyright Holder(s) under this license and clearly marked as such. This may include source files, build scripts and documentation.
14+
15+
"Reserved Font Name" refers to any names specified as such after the copyright statement(s).
16+
17+
"Original Version" refers to the collection of Font Software components as distributed by the Copyright Holder(s).
18+
19+
"Modified Version" refers to any derivative made by adding to, deleting, or substituting — in part or in whole — any of the components of the Original Version, by changing formats or by porting the Font Software to a new environment.
20+
21+
"Author" refers to any designer, engineer, programmer, technical writer or other person who contributed to the Font Software.
22+
23+
PERMISSION & CONDITIONS
24+
25+
Permission is hereby granted, free of charge, to any person obtaining a copy of the Font Software, to use, study, copy, merge, embed, modify, redistribute, and sell modified and unmodified copies of the Font Software, subject to the following conditions:
26+
27+
1) Neither the Font Software nor any of its individual components, in Original or Modified Versions, may be sold by itself.
28+
29+
2) Original or Modified Versions of the Font Software may be bundled, redistributed and/or sold with any software, provided that each copy contains the above copyright notice and this license. These can be included either as stand-alone text files, human-readable headers or in the appropriate machine-readable metadata fields within text or binary files as long as those fields can be easily viewed by the user.
30+
31+
3) No Modified Version of the Font Software may use the Reserved Font Name(s) unless explicit written permission is granted by the corresponding Copyright Holder. This restriction only applies to the primary font name as presented to the users.
32+
33+
4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font Software shall not be used to promote, endorse or advertise any Modified Version, except to acknowledge the contribution(s) of the Copyright Holder(s) and the Author(s) or with their explicit written permission.
34+
35+
5) The Font Software, modified or unmodified, in part or in whole, must be distributed entirely under this license, and must not be distributed under any other license. The requirement for fonts to remain under this license does not apply to any document created using the Font Software.
36+
37+
TERMINATION
38+
39+
This license becomes null and void if any of the above conditions are not met.
40+
41+
DISCLAIMER
42+
43+
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.

‎README.md‎

Lines changed: 90 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -18,81 +18,126 @@ SPDX-License-Identifier: CC-BY-4.0
1818
[![JOSS](https://joss.theoj.org/papers/10.21105/joss.03294/status.svg)](https://doi.org/10.21105/joss.03294)
1919
[![Discord](https://img.shields.io/discord/911692131440148490?logo=discord)](https://discord.gg/AnuJBk23FU)
2020

21-
atlite is a [free software](https://www.gnu.org/philosophy/free-sw.en.html),
22-
[xarray](https://docs.xarray.dev/en/stable/)-based Python library for
23-
converting weather data (like wind speeds and solar influx) into energy system
24-
data. It is lightweight and keeps computing resource requirements (CPU, RAM)
25-
low. It is therefore well suited for big weather datasets.
26-
27-
atlite converts the following weather data fields into time series relevant
28-
for energy systems, for any subset of a full weather database.
29-
30-
![Weather data fields that atlite processes and the time series it creates](docs/assets/images/workflow_chart.png)
31-
32-
atlite was initially developed by the Renewable Energy Group at
33-
[FIAS](https://fias.institute/) to carry out simulations for the
34-
[CoNDyNet project (archived)](https://web.archive.org/web/20210420004051/http://condynet.de/),
35-
financed by the [German Federal Ministry of Education and Research (BMBF)](https://www.bmftr.bund.de/EN/)
36-
as part of the
37-
[Stromnetze Research Initiative (archived)](https://web.archive.org/web/20190127192900/http://forschung-stromnetze.info/projekte/grundlagen-und-konzepte-fuer-effiziente-dezentrale-stromnetze/).
38-
39-
With atlite, we want to build a bridge between meteorology and energy system
40-
modelling. Traditionally, the two communities have not interacted much, and the
41-
results of one reached the other only slowly. atlite makes it easy to use
42-
meteorological data in energy system models: it offers standard ways to access
43-
weather and climate datasets and to convert them into weather-dependent inputs.
21+
atlite converts weather data into energy system data. It turns wind speed, solar
22+
radiation, temperature and runoff into time series of wind and solar power, hydro
23+
inflow, heating demand and more. atlite is free software, built on
24+
[xarray](https://docs.xarray.dev/en/stable/) and
25+
[dask](https://www.dask.org/). It processes large weather datasets in chunks
26+
and therefore needs little memory.
27+
28+
<picture>
29+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/PyPSA/atlite/master/docs/assets/images/workflow_chart-dark.svg">
30+
<img alt="How atlite works: 1 weather data, 2 cutout, 3 conversion per grid cell, 4 aggregation to regions" src="https://raw.githubusercontent.com/PyPSA/atlite/master/docs/assets/images/workflow_chart.svg">
31+
</picture>
32+
33+
A cutout can combine several datasets, for example ERA5 with the
34+
higher-resolution solar radiation of SARAH. Before aggregation, atlite can also
35+
exclude land that is not available, such as protected areas, to calculate
36+
potentials.
37+
38+
## Example
39+
40+
This example downloads ERA5 data for Germany in January 2023. It then calculates
41+
hourly wind capacity factors for each region in a file of region shapes:
42+
43+
```python
44+
import atlite
45+
import geopandas as gpd
46+
47+
cutout = atlite.Cutout(
48+
path="germany-2023-01.nc",
49+
module="era5-edh",
50+
x=slice(5.5, 15.5),
51+
y=slice(47, 55.5),
52+
time="2023-01",
53+
)
54+
cutout.prepare()
55+
56+
regions = gpd.read_file("regions.geojson").set_index("name")
57+
wind = cutout.wind(
58+
turbine="Vestas_V112_3MW",
59+
shapes=regions,
60+
per_unit=True,
61+
aggregate_time=None,
62+
)
63+
```
4464

45-
For the next development goals, see the
46-
[vision and roadmap project](https://github.com/orgs/PyPSA/projects/12/views/1)
47-
and the list of open
48-
[enhancements](https://github.com/PyPSA/atlite/issues/?q=is%3Aissue%20state%3Aopen%20label%3A%22type%3A%20enhancement%22).
65+
The result is an `xarray.DataArray` with one time series per region. To download
66+
ERA5 data, you need a free account; see
67+
[ERA5 credentials](https://atlite.readthedocs.io/en/latest/home/installation/#era5-credentials).
4968

5069
## Installation
5170

52-
atlite requires Python 3.11 or newer. Install the current stable version with
53-
`conda` from [conda-forge](https://anaconda.org/conda-forge/atlite):
71+
atlite requires Python 3.11 or newer. Install it with `conda` from
72+
[conda-forge](https://anaconda.org/conda-forge/atlite):
5473

55-
``` shell
74+
```shell
5675
conda install -c conda-forge atlite
5776
```
5877

5978
or with `pip` from [PyPI](https://pypi.org/project/atlite/):
6079

61-
``` shell
80+
```shell
6281
pip install atlite
6382
```
6483

6584
To install the latest development version from GitHub:
6685

67-
``` shell
86+
```shell
6887
pip install git+https://github.com/PyPSA/atlite.git
6988
```
7089

7190
## Documentation
7291

73-
Read the [documentation](https://atlite.readthedocs.io/en/latest/).
92+
The [documentation](https://atlite.readthedocs.io/en/latest/) contains an
93+
[introduction](https://atlite.readthedocs.io/en/latest/home/introduction/),
94+
[examples](https://atlite.readthedocs.io/en/latest/examples/examples/) as
95+
Jupyter notebooks and the
96+
[API reference](https://atlite.readthedocs.io/en/latest/api/cutout/).
7497

7598
## Support and contributing
7699

77-
- To **discuss** with other PyPSA and atlite users, organise projects, share news, and
78-
get in touch with the community, join the [Discord server](https://discord.gg/AnuJBk23FU).
79-
- For **bugs and feature requests**, use the [issue tracker](https://github.com/PyPSA/atlite/issues).
80-
- We welcome anyone interested in **contributing** to this project. If you have ideas or
81-
suggestions, or encounter problems, please open an issue or a pull request.
82-
See the [contributing guidelines](https://atlite.readthedocs.io/en/latest/contributing/contributing/).
100+
- To ask questions and talk to other users, join the
101+
[Discord server](https://discord.gg/AnuJBk23FU).
102+
- To report bugs or request features, use the
103+
[issue tracker](https://github.com/PyPSA/atlite/issues).
104+
- We welcome contributions. Read the
105+
[contributing guidelines](https://atlite.readthedocs.io/en/latest/contributing/contributing/)
106+
and open an issue or a pull request.
83107

84-
## Authors and copyright
108+
For the next development goals, see the
109+
[roadmap](https://github.com/orgs/PyPSA/projects/12/views/1) and the open
110+
[enhancements](https://github.com/PyPSA/atlite/issues/?q=is%3Aissue%20state%3Aopen%20label%3A%22type%3A%20enhancement%22).
85111

86-
Copyright (C) Contributors to atlite <https://github.com/pypsa/atlite>
112+
## Citing
113+
114+
If you use atlite in your research, please cite the
115+
[paper in the Journal of Open Source Software](https://doi.org/10.21105/joss.03294).
116+
The [citing page](https://atlite.readthedocs.io/en/latest/home/citing/) has
117+
the BibTeX entry.
118+
119+
## Origin
87120

88-
See the [contributors](https://atlite.readthedocs.io/en/latest/contributing/contributors/) for details.
121+
atlite began as a lightweight version of the Aarhus University RE Atlas
122+
([Andresen et al., 2015](https://doi.org/10.1016/j.energy.2015.09.071)). The
123+
Renewable Energy Group at [FIAS](https://fias.institute/) developed it for the
124+
[CoNDyNet project (archived)](https://web.archive.org/web/20210420004051/http://condynet.de/),
125+
funded by the [German Federal Ministry of Education and Research (BMBF)](https://www.bmftr.bund.de/EN/)
126+
as part of the
127+
[Stromnetze Research Initiative (archived)](https://web.archive.org/web/20190127192900/http://forschung-stromnetze.info/projekte/grundlagen-und-konzepte-fuer-effiziente-dezentrale-stromnetze/).
128+
Today, volunteers from different institutions maintain atlite; see the
129+
[contributors](https://atlite.readthedocs.io/en/latest/contributing/contributors/).
130+
131+
atlite connects meteorology and energy system modelling, two communities that
132+
have long worked apart. Models such as [PyPSA-Eur](https://github.com/PyPSA/pypsa-eur)
133+
use its time series.
89134

90135
## License
91136

92-
This work is licensed under multiple licenses:
137+
Copyright (C) Contributors to atlite <https://github.com/pypsa/atlite>
93138

94-
- All original source code is licensed under [MIT](LICENSES/MIT.txt).
139+
- The source code is licensed under [MIT](LICENSES/MIT.txt).
95140
- The documentation is licensed under [CC-BY-4.0](LICENSES/CC-BY-4.0.txt).
96141
- Configuration and data files are mostly licensed under [CC0-1.0](LICENSES/CC0-1.0.txt).
97142

98-
See the individual files for license details.
143+
See the individual files for details.

‎REUSE.toml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,9 @@ path = "docs/examples/profiles_and_efficiencies_from_sam/**.csv"
1414
precedence = "aggregate"
1515
SPDX-FileCopyrightText = "Contributors to atlite <https://github.com/pypsa/atlite>"
1616
SPDX-License-Identifier = "CC-BY-4.0"
17+
18+
[[annotations]]
19+
path = ["docs/assets/images/workflow_chart.svg", "docs/assets/images/workflow_chart-dark.svg"]
20+
precedence = "override"
21+
SPDX-FileCopyrightText = ["Contributors to atlite <https://github.com/pypsa/atlite>", "2021 The Overpass Project Authors <https://github.com/RedHatOfficial/Overpass>"]
22+
SPDX-License-Identifier = "CC-BY-4.0 AND OFL-1.1"

‎docs/assets/images/workflow_chart-dark.svg‎

Lines changed: 1 addition & 0 deletions
Loading
-18.1 KB
Binary file not shown.
-20.8 KB
Binary file not shown.
-167 KB
Binary file not shown.

‎docs/assets/images/workflow_chart.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/hooks/notebook_figures.py‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# SPDX-FileCopyrightText: Contributors to atlite <https://github.com/pypsa/atlite>
2+
#
3+
# SPDX-License-Identifier: MIT
4+
"""
5+
Add dark-theme variants of the figures in the example notebooks.
6+
7+
The notebooks store matplotlib figures as PNG on a white background. The light
8+
theme shows them unchanged. For the dark theme, this hook removes the white:
9+
10+
- White becomes transparent.
11+
- Thin shapes (text, ticks, lines, grids), anti-aliased fringes and near-white
12+
pixels are un-mixed from white, so that they keep their hue on any
13+
background. Neutral thin shapes next to white take the theme's text colour.
14+
- Everything else (maps, heatmaps, bars, colorbars, line cores, text on data)
15+
keeps its exact original colour.
16+
17+
Material shows each variant only in its theme.
18+
"""
19+
20+
from __future__ import annotations
21+
22+
import base64
23+
import hashlib
24+
import io
25+
import re
26+
from functools import cache, partial
27+
from pathlib import Path
28+
from typing import TYPE_CHECKING
29+
30+
import numpy as np
31+
from mkdocs.utils import get_relative_url
32+
from PIL import Image
33+
from scipy.ndimage import binary_dilation, binary_opening, gaussian_filter, white_tophat
34+
35+
if TYPE_CHECKING:
36+
from mkdocs.config.defaults import MkDocsConfig
37+
from mkdocs.structure.pages import Page
38+
39+
INK = np.array([226, 228, 233]) / 255
40+
INK_OPACITY = 0.82
41+
INK_CONTEXT = 0.15
42+
CHROMA_TOLERANCE = 0.15
43+
WHITE_ALPHA = 0.02
44+
HAZE_ALPHA = 0.25
45+
FRINGE_ALPHA = 0.5
46+
CORE_ALPHA = 0.8
47+
POCKET_CONTRAST = 0.2
48+
RIM_WIDTH = 2
49+
STROKE_WIDTH = 4
50+
SIGMA = 2
51+
52+
_y, _x = np.ogrid[-STROKE_WIDTH : STROKE_WIDTH + 1, -STROKE_WIDTH : STROKE_WIDTH + 1]
53+
DISK = _x**2 + _y**2 <= STROKE_WIDTH**2
54+
SQUARE = np.ones((5, 5), dtype=bool)
55+
56+
FIGURES = "assets/images/notebook-figures"
57+
IMG = re.compile(r'<img (?P<attrs>[^>]*?)src="data:image/png;base64,(?P<data>[^"]+)"')
58+
59+
60+
@cache
61+
def to_dark(png: bytes) -> bytes:
62+
"""
63+
Convert a figure on white background to a transparent dark-theme figure.
64+
65+
Returns
66+
-------
67+
bytes
68+
PNG with transparent background and light neutral strokes.
69+
"""
70+
rgba = np.asarray(Image.open(io.BytesIO(png)).convert("RGBA"), dtype=float) / 255
71+
rgb = rgba[..., :3] * rgba[..., 3:] + 1 - rgba[..., 3:]
72+
alpha = 1 - rgb.min(axis=-1)
73+
color = 1 - (1 - rgb) / np.maximum(alpha, 1e-6)[..., None]
74+
chroma = color.max(axis=-1) - color.min(axis=-1)
75+
neutral = np.clip(1 - chroma / CHROMA_TOLERANCE, 0, 1)
76+
white = alpha < WHITE_ALPHA
77+
78+
thin = ~binary_opening(~white, DISK)
79+
rim = binary_dilation(white, iterations=RIM_WIDTH)
80+
haze = (neutral > 0.5) & (alpha < HAZE_ALPHA)
81+
near_ink = binary_dilation((neutral > 0.5) & (alpha > 0.5), SQUARE)
82+
bright = white_tophat(1 - alpha, footprint=SQUARE) > POCKET_CONTRAST
83+
pocket = bright & (alpha < FRINGE_ALPHA) & ~near_ink
84+
unmix = thin | rim | haze | pocket
85+
86+
context = np.clip(gaussian_filter(white.astype(float), SIGMA) / INK_CONTEXT, 0, 1)
87+
ink = neutral * thin * context
88+
core = np.clip((alpha - FRINGE_ALPHA) / (CORE_ALPHA - FRINGE_ALPHA), 0, 1)
89+
solid = np.where(unmix, core * (1 - ink), 1)[..., None]
90+
91+
color = color * (1 - ink[..., None]) + INK * ink[..., None]
92+
alpha = alpha * (1 - ink * (1 - INK_OPACITY))
93+
transparent = np.dstack([color, alpha])
94+
opaque = np.dstack([rgb, np.ones_like(alpha)])
95+
out = opaque * solid + transparent * (1 - solid)
96+
97+
image = Image.fromarray((out * 255).round().astype(np.uint8))
98+
buffer = io.BytesIO()
99+
image.save(buffer, "png", optimize=True)
100+
return buffer.getvalue()
101+
102+
103+
def _theme_variants(match: re.Match[str], page: Page, site_dir: str) -> str:
104+
attrs, data = match["attrs"], match["data"]
105+
png = to_dark(base64.b64decode(data))
106+
path = f"{FIGURES}/{hashlib.sha256(png).hexdigest()[:16]}.png"
107+
file = Path(site_dir, path)
108+
file.parent.mkdir(parents=True, exist_ok=True)
109+
file.write_bytes(png)
110+
url = get_relative_url(path, page.url)
111+
return (
112+
f'<img {attrs}src="data:image/png;base64,{data}#only-light">'
113+
f'<img {attrs}loading="lazy" src="{url}#only-dark"'
114+
)
115+
116+
117+
def on_post_page(output: str, page: Page, config: MkDocsConfig) -> str:
118+
"""
119+
Add a dark-theme variant to each PNG figure of a notebook page.
120+
121+
The dark variants are written as separate files and load lazily, so that
122+
readers of the light theme do not download them.
123+
124+
Returns
125+
-------
126+
str
127+
The page HTML with light and dark figure variants.
128+
"""
129+
if not page.file.src_uri.endswith(".ipynb"):
130+
return output
131+
replace = partial(_theme_variants, page=page, site_dir=config.site_dir)
132+
return IMG.sub(replace, output)

‎docs/index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,8 @@ dataset. With [ERA5](https://www.ecmwf.int/en/forecasts/datasets/reanalysis-data
2828
the default dataset, atlite gives hourly time series on a grid of about
2929
30 km x 30 km.
3030

31-
![Weather data fields that atlite processes and the time series it creates](assets/images/workflow_chart.png)
31+
![How atlite works: 1 weather data, 2 cutout, 3 conversion per grid cell, 4 aggregation to regions](assets/images/workflow_chart.svg#only-light)
32+
![How atlite works: 1 weather data, 2 cutout, 3 conversion per grid cell, 4 aggregation to regions](assets/images/workflow_chart-dark.svg#only-dark)
3233

3334
atlite builds a bridge between meteorology and energy system modelling.
3435
These two communities have traditionally worked apart, and results from one

0 commit comments

Comments
 (0)