perezsky 1.0.0__tar.gz

perezsky-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+# Build, test and publish to PyPI when a GitHub release is published.
+# PyPI trusted publishing: project "perezsky", owner "WildSolar", repository "PerezSky",
+# workflow "publish.yml", environment "pypi" (no API token needed).
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Test the built wheel
+        run: |
+          uv venv
+          uv pip install dist/*.whl pytest pandas pvlib matplotlib
+          .venv/bin/python -m pytest -q -p no:cacheprovider
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

perezsky-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.claude/
+validation/work/

perezsky-1.0.0/CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata from this file."
+type: software
+title: "perezsky: Perez all-weather sky radiance distribution, plane irradiance and horizon masking"
+abstract: >-
+  Python implementation of the Perez (1993) all-weather sky as a radiance or luminance
+  distribution on a discretised hemisphere, normalised to measured irradiance, with irradiance
+  on arbitrarily oriented planes, masking by a local horizon with a terrain model, Perez (1990)
+  luminous efficacy and export to Radiance. Validated against Radiance's gendaylit and rtrace.
+authors:
+  - family-names: Wild
+    given-names: Michael
+    orcid: "https://orcid.org/0000-0002-7730-3064"
+    affiliation: "ZHAW Zurich University of Applied Sciences"
+version: 1.0.0
+license: MIT
+repository-code: "https://github.com/WildSolar/PerezSky"
+keywords:
+  - solar energy
+  - sky model
+  - Perez
+  - diffuse irradiance
+  - photovoltaics
+  - daylighting
+  - Radiance

perezsky-1.0.0/CLAUDE.md

@@ -0,0 +1,88 @@
+# perezsky — notes for Claude sessions
+
+Python package for the Perez (1993) all-weather sky: radiance/luminance distribution on a
+discretised hemisphere, normalised to measured DNI/DHI. Also covers plane irradiance (incl.
+long time series), horizon masking with a terrain model, Perez (1990) luminous efficacy and
+export to Radiance. Validated against Radiance's gendaylit and rtrace. Extracted from the
+slopevf project (`C:\Users\wimm\Documents\GitHub\General_Irradiation_Model\python`), where the
+same model was corrected relative to the user's older MATLAB code. `README.md` is the full user
+documentation.
+
+## Using it from another project
+
+Declare it in that project's `pyproject.toml` (editable, so it follows this repository), then
+`uv sync`:
+
+```toml
+[project]
+dependencies = ["perezsky[plot]"]
+
+[tool.uv.sources]
+perezsky = { path = "C:/Users/wimm/Documents/packages/PerezSky", editable = true }
+```
+
+To freeze a finished project, depend on a released version from PyPI instead
+(`perezsky>=1.0`, without the uv source). Don't copy the code into the other project.
+Public repository: https://github.com/WildSolar/PerezSky; releases are archived on Zenodo and
+published to PyPI by `.github/workflows/publish.yml` (trusted publishing) when a GitHub release
+is published. Bump the version in `pyproject.toml`, `src/perezsky/__init__.py` and
+`CITATION.cff` together.
+
+```python
+import perezsky as ps
+
+# angles in degrees; azimuth from NORTH, clockwise (east = 90); DNI/DHI/GHI in W/m2
+sky = ps.perez_sky(dni, solar_zenith, solar_azimuth, dhi=dhi,   # or ghi=ghi
+                   day_of_year=doy,                  # date-dependent E0 (optional)
+                   grid="medium",                    # "low" | "medium" | "high" | "ultra"
+                   sun_model="point",                # "point" (beam separate) | "buie" (circumsolar)
+                   horizon=None,                     # ps.Horizon(...), see below
+                   quantity="radiance")              # or "luminance" (cd/m2, lux)
+sky.L, sky.beam, sky.ghi                             # (n_cells, n_t) radiance, (n_t,) point beam, local GHI
+sky.plane_irradiance(tilt, azimuth, albedo)          # dict "beam","sky","ground","total": (n_t, n_planes)
+
+out = ps.poa_irradiance(tilt, azimuth, dni, zen, az, dhi=dhi, albedo=0.2, day_of_year=doy)  # chunked series
+
+hor = ps.Horizon.from_file("site.hor")               # .hor files: SOUTH = 0 (default convention there)
+hor = ps.Horizon.from_horizontool(ht_horizon, albedo=0.3, terrain="facing")
+p = ps.perez_parameters(dni, dhi, zen)               # epsilon, delta, category, a..e
+ps.write_radiance_sky(sky, "sky.rad", index=0)       # writes sky.rad + sky.cal (point sun, no horizon)
+```
+
+Pitfalls:
+
+- **Azimuth conventions.** The API uses north = 0, clockwise (as pvlib and the horizontool
+  API). `.hor` files use south = 0: `Horizon.from_file` assumes that, `Horizon(...)` assumes
+  north unless `convention="south"`. slopevf uses south = 0, positive towards west; convert with
+  `az_north = az_south + 180`.
+- **Night and memory.** `perez_sky` requires the sun above the horizontal and holds
+  n_cells × n_t floats. For long series use `poa_irradiance`, which chunks and returns 0 at
+  night.
+- **Defaults keep the model in its range.** `clamp`, `brightness_correction` and
+  `limit_gradation` are on by default.
+  - Without `limit_gradation`, very bright overcast skies, and clear skies with a sun below
+    about 5°, can give b > 0, and vertical planes then receive many times the GHI.
+  - gendaylit-identical parameters: `airmass_model="kasten1966", solar_constant=1367,
+    limit_gradation=False`. gendaylit also uses day number 0 with `-ang`.
+- **`sun_model`.** `"point"` is the right choice for plane irradiance. `"buie"` spreads the
+  beam over a 6° cone; use it only when angular acceptance matters (concentrators,
+  circumsolar studies).
+- **Horizon.** DNI/DHI are treated as free-horizon values. The terrain model `"facing"`
+  (default) is better than `"horizontal"`; it was validated in slopevf.
+- **Ground term.** `plane_irradiance` treats the ground as an isotropic reflector of the local
+  GHI, the standard approach. Shading by rows or other obstacles is not included; use a
+  dedicated model for that, e.g. slopevf for PV arrays.
+
+## Working on this repository
+
+- Tests: `.venv\Scripts\python.exe -m pytest -q -p no:cacheprovider`. The `radiance` tests
+  compare with gendaylit/rtrace and need `RADIANCE_DIR` (here `C:\Users\wimm\tools\Radiance`);
+  without it they are skipped. Run the full suite with Radiance before committing.
+- Model or numerical changes: rerun `validation/validate.py` (needs Radiance and pvlib) and
+  commit the updated `validation/results/validation.md`. The gendaylit comparison must stay
+  within print precision.
+- Coefficients are transcribed from gendaylit.c, the reference implementation;
+  `tests/test_model.py` holds an independent transcription.
+- git is not on PATH: use GitHub Desktop's bundled
+  `%LOCALAPPDATA%\GitHubDesktop\app-*\resources\app\git\cmd\git.exe`. Commit on `main` with a
+  message file (`commit -F`, UTF-8 without BOM); never push — the user pushes from GitHub Desktop.

perezsky-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Wild
+
+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.

perezsky-1.0.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.5
+Name: perezsky
+Version: 1.0.0
+Summary: Perez (1993) all-weather sky radiance and luminance distribution on a discretised sky, with plane irradiance, horizon masking and Radiance export.
+Project-URL: Homepage, https://github.com/WildSolar/PerezSky
+Project-URL: Repository, https://github.com/WildSolar/PerezSky
+Project-URL: Issues, https://github.com/WildSolar/PerezSky/issues
+Author-email: Michael Wild <michael.wild@zhaw.ch>
+License: MIT
+License-File: LICENSE
+Keywords: Perez,Radiance,daylighting,diffuse irradiance,photovoltaics,sky model,solar energy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.25
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.6; extra == 'dev'
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pvlib>=0.10; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.6; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# perezsky
+
+The Perez (1993) all-weather sky as a radiance (or luminance) distribution on a discretised
+hemisphere, normalised to measured irradiance. On top of it:
+
+- irradiance on arbitrarily oriented planes, also for long time series;
+- masking by a local horizon, with a model of the terrain radiance;
+- luminance and illuminance via the Perez (1990) luminous efficacy models;
+- export of the same sky to Radiance;
+- a polar plot of the sky.
+
+The implementation is validated against Radiance's `gendaylit` and `rtrace`
+([validation/results/validation.md](https://github.com/WildSolar/PerezSky/blob/main/validation/results/validation.md)).
+
+```bash
+pip install perezsky              # with plotting: pip install "perezsky[plot]"
+```
+
+## Quick start
+
+```python
+import perezsky as ps
+
+# one or many time steps; angles in degrees, azimuth from north, clockwise
+sky = ps.perez_sky(dni=[850, 120], solar_zenith=[35, 70], solar_azimuth=[140, 250],
+                   dhi=[90, 200], day_of_year=[172, 172])
+sky.L                      # (n_cells, n_t) sky radiance [W/m2/sr]
+sky.beam                   # (n_t,) DNI of the point sun [W/m2] (0 while hidden by a horizon)
+res = sky.plane_irradiance(tilt=[30, 90], azimuth=[180, 90], albedo=0.2)
+res["total"]               # (n_t, n_planes); also "beam", "sky", "ground"
+
+# a year of hourly data in chunks (sun below the horizontal -> 0)
+out = ps.poa_irradiance(35, 180, dni, solar_zenith, solar_azimuth, dhi=dhi,
+                        albedo=0.2, day_of_year=doy)
+```
+
+## Model
+
+**Sky condition.** For each time step:
+
+- the sky clearness ε = ((DHI + DNI)/DHI + 1.041 Z³) / (1 + 1.041 Z³);
+- the sky brightness Δ = DHI · m / E₀, with the relative air mass m and the extraterrestrial
+  irradiance E₀;
+- one of eight clearness categories, determined by ε.
+
+**Distribution.** The relative distribution is
+
+L ∝ (1 + a exp(b / cos ζ)) · (1 + c exp(d γ) + e cos² γ),
+
+with ζ the zenith angle of the sky element and γ its angle to the sun. The parameters a..e
+come from the coefficients of Perez et al. (1993); for the overcast category, c and d use
+their own formulas.
+
+**Normalisation.**
+
+- The sky cells above the horizontal integrate exactly to DHI, for any grid resolution.
+- With `sun_model="point"` (default), the beam DNI is kept as a separate point source in the
+  exact sun direction. For irradiance on planes, this is more accurate than spreading it over
+  sky cells.
+- With `sun_model="buie"`, the beam is distributed over a circumsolar cone (default 6°)
+  following the Buie et al. (2003) sunshape. Inside the cone it replaces the Perez radiance and
+  integrates to DNI cos Z. This matters when angular acceptance is relevant, e.g. for
+  concentrators.
+
+**Range of validity.** By default the inputs are kept within the range of the model:
+
+- `clamp=True`: ε ∈ [1, 12.01) and Δ ∈ [0.01, 0.6], as gendaylit does.
+- `brightness_correction=True`: Δ ≥ 0.2 for 1.065 < ε < 2.8 when computing a..e, as
+  gendaylit does. gendaylit marks it as a correction of the Perez model, without a
+  reference; see the section below.
+- `limit_gradation=True`: b ≤ 0.
+  - For very bright overcast skies (e.g. cloud enhancement over snow, GHI ≈ 700 W/m² with
+    DNI ≈ 0) and for clear skies with a very low sun, the model gives b > 0.
+  - The factor exp(b / cos ζ) then grows without bound towards the horizon. Vertical planes
+    received up to 30 times the GHI in a real data set.
+  - gendaylit refuses such skies and outputs a black sky ("positive Perez parameter B");
+    perezsky caps b at 0 instead.
+
+**The brightness correction.** It changes only the *shape* of the distribution; the
+normalisation to the actual DHI stays the same.
+
+- **Where it acts:** on dark skies of intermediate clearness (thin or broken cloud with little
+  diffuse light, Δ < 0.2 for 1.065 < ε < 2.8).
+- **Why it is needed:** the parameters are linear in Δ and were fitted to measured skies. For
+  low Δ in categories 2–5 they extrapolate to a gradation 1 + a·exp(b/cos ζ) with
+  a·exp(b) ≈ −1. The zenith then becomes almost black, and the horizon up to 3.5 times
+  brighter than the average sky radiance DHI/π. Real skies of this type do not look like that.
+- **What it does:** raising Δ to 0.2 makes b more negative. The gradation then approaches 1
+  only close to the horizon, which gives a moderately brighter horizon and a zenith of 0.4–1.0
+  times the average radiance.
+- **Size of the effect:** in such hours the sky-diffuse irradiance on vertical planes drops by
+  a median of 4–15% (up to about 45%). In the opposite direction, a few very dark skies
+  (Δ ≈ 0.05) gain up to 25%.
+- **How often:** such hours make up 1–2% of the daylight hours (Davos PVGIS TMY, Greensboro
+  TMY3). Annual sums change by at most 0.2% of the sky-diffuse and 0.1% of the total
+  irradiation, on any plane.
+
+See [validation/results/brightness_correction.md](https://github.com/WildSolar/PerezSky/blob/main/validation/results/brightness_correction.md).
+
+**Other settings.**
+
+- **Air mass:** Kasten & Young (1989) by default; `airmass_model="kasten1966"` selects
+  gendaylit's formula.
+- **E₀:** the solar constant of 1361 W/m², corrected for the Earth–Sun distance (Spencer 1971)
+  if `day_of_year` is given; gendaylit uses 1367 W/m².
+
+**Grids.** Elevation bands of 0.5°, each divided into azimuthal cells of near-constant size,
+with exact solid angles:
+
+| Resolution | Cells |
+|---|---|
+| `low` | 10'401 |
+| `medium` | 20'716 |
+| `high` | 41'335 |
+| `ultra` | 82'594 |
+
+Plane irradiance on `low` is within 0.3% of `ultra`. `poa_irradiance` uses `low` by default.
+
+## Planes and ground
+
+`Sky.plane_irradiance(tilt, azimuth, albedo)` sums three parts:
+
+- **beam:** DNI · cos(incidence), zero while the sun is behind the plane or the horizon;
+- **sky:** the sky cells in front of the plane, weighted with the cosine;
+- **ground:** isotropic reflection of the local global horizontal irradiance below the
+  horizontal, albedo · GHI · (1 − cos tilt)/2.
+
+## Horizon
+
+```python
+hor = ps.Horizon.from_file("site.hor")                     # PVsyst/horizontool .hor: south = 0
+hor = ps.Horizon(azimuth, elevation, convention="north")   # arrays, north = 0
+hor = ps.Horizon.from_horizontool(ht.compute_horizon(lat, lon), albedo=0.3)
+sky = ps.perez_sky(..., horizon=hor)
+```
+
+**Masking.** Sky cells below the horizon get the radiance of the terrain, and the beam is
+blocked while the sun is behind the horizon. DNI and DHI are treated as free-horizon values.
+If they were measured on site behind the horizon, this is still a good approximation for the
+sky: the masked part is replaced anyway.
+
+**Terrain models.**
+
+| `terrain=` | Model | Deviation from ray-traced terrain |
+|---|---|---|
+| `"facing"` (default) | Slopes of 30° facing the observer: beam (if the sun is visible from the observer), isotropic sky, own surroundings | ≤ 2% on tilted planes |
+| `"horizontal"` | albedo · GHI / π | up to 14% |
+
+The deviations were determined with Radiance in the slopevf project. Negative horizon
+elevations are treated as 0.
+
+## Luminance
+
+`perez_sky(..., quantity="luminance")` gives luminance [cd/m²] and illuminance [lux].
+
+- **Conversion:** DNI and DHI are converted with the Perez et al. (1990) luminous efficacies
+  of the direct and diffuse components (`precipitable_water` in cm, default 2 as in
+  gendaylit), and the same distribution is normalised to them.
+- **Efficacies:** `luminous_efficacy(params, zenith)` returns the global, diffuse and direct
+  efficacies [lm/W] directly.
+
+## Radiance export
+
+```python
+ps.write_radiance_sky(sky, "sky.rad", index=0, ground_albedo=0.2)   # writes sky.rad and sky.cal
+```
+
+The exported sky differs from gendaylit's in two ways:
+
+- **No horizon blending.** gendaylit's `perezlum.cal` mixes about 45% ground brightness into
+  the sky at the horizon, which changes vertical-plane irradiance by up to 5%; the exported sky
+  has no such blending.
+- **Same normalisation.** It is normalised to the same DHI as the discrete sky.
+
+`rtrace` on the exported sky reproduces `Sky.plane_irradiance` within 0.1%. Only skies with
+`sun_model="point"` and without horizon can be exported.
+
+## Corrections relative to earlier MATLAB implementations
+
+The MATLAB code this package replaces (`skyLuminanceBatch.m`, `totalSkyLuminance.m`) had
+several deviations from the published model. All of them are corrected here:
+
+- Three coefficients were mistyped:
+  - `x4` of b in category 1: −1.233 instead of −0.1233;
+  - `x3` of c in category 6: −7.1407 instead of −7.1406;
+  - `x4` of d in category 7: 0.2652 instead of 0.2656.
+- The category-1 formula for c raised only (x1 + x2 Z) to the power x3 instead of
+  Δ (x1 + x2 Z): exp(Δ (x1 + x2 Z)^x3) instead of exp((Δ (x1 + x2 Z))^x3).
+- The air mass function was called with the elevation in radians instead of sin(elevation),
+  which gives complex values above 1 rad.
+- The model ran without range limits.
+
+## Validation
+
+`validation/validate.py` (needs Radiance and pvlib) writes
+[validation/results/validation.md](https://github.com/WildSolar/PerezSky/blob/main/validation/results/validation.md):
+
+- **Parameters and luminous efficacies vs. gendaylit:** 86 sky conditions, solar altitudes
+  5–80°, overcast to clear. Agreement within gendaylit's print precision:
+  - parameters a..e to 2.5·10⁻⁶;
+  - diffuse efficacy to 0.06%;
+  - direct efficacy to 0.04 lm/W.
+
+  gendaylit refuses 2 of the conditions as error skies, exactly those with b > 0.
+- **Plane irradiance vs. rtrace:** 5 skies × 9 planes on the exported sky, within 0.1%.
+- **Annual POA vs. pvlib (TMY3, Greensboro):** within about 1% of pvlib's Perez (1990)
+  transposition model for south-facing and vertical planes. The isotropic model deviates by up
+  to 15% (vertical north).
+
+The tests (`pytest`) include the gendaylit and rtrace comparisons, marked `radiance` and skipped
+without Radiance.
+
+## Citation
+
+If you use perezsky in published work, please cite the archived version on Zenodo (see
+[CITATION.cff](https://github.com/WildSolar/PerezSky/blob/main/CITATION.cff); the DOI badge is added with the first release).
+
+## License
+
+MIT, see [LICENSE](https://github.com/WildSolar/PerezSky/blob/main/LICENSE).
+
+## References
+
+- Perez, R., Seals, R., Michalsky, J. (1993). All-weather model for sky luminance
+  distribution — preliminary configuration and validation. Solar Energy 50(3), 235–245.
+- Perez, R., Ineichen, P., Seals, R., Michalsky, J., Stewart, R. (1990). Modeling daylight
+  availability and irradiance components from direct and global irradiance. Solar Energy 44(5),
+  271–289.
+- Buie, D., Monger, A. G., Dey, C. J. (2003). Sunshape distributions for terrestrial solar
+  simulations. Solar Energy 74(2), 113–122.
+- Kasten, F., Young, A. T. (1989). Revised optical air mass tables and approximation formula.
+  Applied Optics 28(22), 4735–4738.
+- Spencer, J. W. (1971). Fourier series representation of the position of the sun. Search 2(5).