Rust Solar Toolkit (rsun)¶

rsun is a Rust port of GRASS GIS r.sun — a complete implementation of the ESRA clear-sky solar radiation model (Hofierka & Suri, 2002). It computes global solar radiation and sunshine duration on arbitrary terrain, with CPU parallelism, GPU acceleration, and multi-platform deployment.

Why Rust?¶

Architecture¶

graph TD
    DEM[DEM GeoTIFF] --> IO[rsun-core::io]
    IO --> GRID[Grid + SolarParams]
    GRID --> CPU[rsun-core::compute_day]
    GRID --> GPU[rsun-gpu::RadiationPipeline]
    CPU --> RESULT[DayResult]
    GPU --> RESULT
    RESULT --> TIFF[Output GeoTIFF]
    RESULT --> NUMPY[NumPy Array]
    RESULT --> JSON[WASM JSON]

    CLI[rsun-cli] --> IO
    CLI --> CPU
    CLI --> GPU
    PY[rsun-py] --> CPU
    PY --> GPU
    WASM[rsun-wasm] --> CPU

    style CPU fill:#2d6a4f,color:#fff
    style GPU fill:#1d3557,color:#fff
    style CLI fill:#457b9d,color:#fff
    style PY fill:#e9c46a,color:#000
    style WASM fill:#f4a261,color:#000

Crate Workspace¶

Core Module Map¶

Algorithm Correspondence¶

Every rsun function maps directly to a GRASS r.sun routine and a Lean 4 formal definition:

Lean 4 Proven Properties¶

The Lean 4 theorem prover has formally verified mathematical bounds on every core equation. These bounds are also validated at runtime by unit tests in rsun-core/tests/lean4_validation_tests.rs.

Performance¶

CPU (rsun-core)¶

• Parallelism: Rayon distributes pixel computation across all available cores
• Time complexity: \(O(\text{pixels} \times \text{time\_steps})\) per day, where time steps \(= \lceil\text{day\_length} / \text{step}\rceil\)
• Step impact: step=0.5 (default) gives ~24 steps/day; step=0.25 doubles compute time for ~1% accuracy gain

GPU (rsun-gpu)¶

• Backend: wgpu compute shaders (WGSL) — works on Vulkan, Metal, DX12
• Pipeline: Two-pass: (1) horizon pre-computation, (2) per-pixel daily radiation loop
• Workgroup size: 64 threads per workgroup, 2D dispatch for large DEMs
• Fallback: Auto-detects GPU; falls back to CPU if unavailable

CLI Reference¶

rsun compute --dem <PATH> --day <SPEC> [OPTIONS]
rsun terrain --dem <PATH> --slope-out <PATH> --aspect-out <PATH>
rsun info

compute Options¶

Python API¶

import rsun

# From file (requires GDAL at build time)
result = rsun.compute_day_from_file("dem.tif", day=172, step=0.5, linke=3.0, albedo=0.2)
result.glob_rad    # numpy array [Wh/m²]
result.insol_time  # numpy array [hours]

# From numpy arrays
result = rsun.compute_day(dem, slope, aspect, lat, lon, day=172)

# Terrain analysis
slope, aspect = rsun.compute_terrain(dem, ew_res=10.0, ns_res=10.0)

# GPU info
gpus = rsun.gpu_info()  # list of available GPU adapters

WebAssembly API¶

import init, { compute_day } from './rsun_wasm.js';
await init();

const result = compute_day(dem_array, rows, cols, lat_rad, lon_rad, day, step);
// result.glob_rad  — Float32Array
// result.insol_time — Float32Array

CPU-only; limited to DEMs under 1 million pixels.

Validation Against GRASS r.sun¶

The validation/compare.sh script runs rsun and GRASS r.sun on the same DEM (mcn_10m.tif) for 4 representative days (winter solstice, spring equinox, summer solstice, fall equinox) and computes:

• RMSE — Root mean square error across all valid pixels
• MaxRelErr% — Maximum relative error at any pixel

Acceptance criteria: MaxRelErr < 5% for all days.

cd rsun && bash validation/compare.sh

References¶

1. Hofierka, J. & Suri, M. (2002). The solar radiation model for Open Source GIS: implementation and applications. Proceedings of the Open Source GIS - GRASS Users Conference.
2. Spencer, J.W. (1971). Fourier series representation of the position of the Sun. Search, 2(5), 172.
3. Kasten, F. & Young, A.T. (1989). Revised optical air mass tables and approximation formula. Applied Optics, 28(22), 4735–4738.
4. Jenco, M. (1992). Distribution of direct solar radiation on georelief. Geograficky Casopis, 44, 342–355.
5. Suri, M. & Hofierka, J. (2004). A new GIS-based solar radiation model and its application to photovoltaic assessments. Transactions in GIS, 8(2), 175–190.