pvlib-rust

A Rust port of pvlib-python — the open-source solar photovoltaic modeling library.

pvlib-rust provides the same algorithms, accuracy, and modeling capabilities as pvlib-python, with Rust's performance and safety guarantees. It covers the full PV simulation pipeline: from solar position and clear-sky irradiance through module temperature and single-diode physics to DC/AC power output.

Performance

Features

• 170+ public functions across 24 modules
• 337 tests with end-to-end validation
• Batch processing — rayon-parallelized, full TMY year (8760 hours) in ~4 ms
• Full simulation pipeline via ModelChain (scalar) and BatchModelChain (time series)
• Builder pattern API for ergonomic configuration
• Auto GHI decomposition — handles weather APIs that only provide GHI (auto Erbs DNI/DHI)
• Bifacial support — rear-side gain modeling with configurable bifaciality factor
• System losses — built-in DC derating for wiring, soiling, mismatch
• NaN-safe — gracefully handles missing values from upstream Python/Polars pipelines
• UTC convenience API — WeatherSeries::from_utc() and solar_position_batch_utc() for weather API integration
• Multiple model options at each step (5 transposition, 6 temperature, 5 IAM, 3 inverter)
• Weather file I/O (TMY3, EPW) and PVGIS API client
• IV curve fitting and single-diode model parameter extraction (Bishop88, De Soto)
• #[inline] annotations on all 99 hot-path functions for optimal loop performance
• No unsafe code

Quick Start

Add to your Cargo.toml:

[dependencies]
pvlib-rust = "0.1.4"
# Or from git for latest:
# pvlib = { package = "pvlib-rust", git = "https://github.com/p-vbordei/pvlib-rust" }

Batch Simulation (Recommended for Production)

Simulate an entire year in milliseconds using rayon-parallelized batch processing:

use chrono::TimeZone;
use chrono_tz::US::Mountain;
use pvlib::batch::{BatchModelChain, WeatherSeries};
use pvlib::location::Location;
use pvlib::irradiance::DiffuseModel;

let location = Location::new(39.74, -105.18, Mountain, 1830.0, "Golden, CO");

// Builder pattern — configure system, losses, bifacial, auto-decomposition
let mc = BatchModelChain::pvwatts(location, 30.0, 180.0, 5000.0)
    .with_gamma_pdc(-0.004)
    .with_inverter(5000.0, 0.96)
    .with_albedo(0.2)
    .with_transposition(DiffuseModel::Perez)
    .with_auto_decomposition(true)   // Auto Erbs GHI→DNI/DHI when missing
    .with_system_losses(0.14)        // 14% DC derating (wiring, soiling, etc.)
    .with_bifacial(0.7, 0.25);      // Bifacial: 70% rear efficiency, 25% ground albedo

// Weather data — one value per hour (8760 for a full year)
let weather = WeatherSeries {
    times,        // Vec<DateTime<Tz>>
    ghi,          // Vec<f64> — global horizontal irradiance [W/m2]
    dni,          // Vec<f64> — direct normal irradiance (zeros OK with auto-decomposition)
    dhi,          // Vec<f64> — diffuse horizontal irradiance (zeros OK with auto-decomposition)
    temp_air,     // Vec<f64> — ambient temperature [C]
    wind_speed,   // Vec<f64> — wind speed [m/s]
    albedo: None, // Optional<Vec<f64>> — ground albedo
};

// Full year simulation — ~4ms on modern hardware
let results = mc.run(&weather).unwrap();

println!("Annual energy: {:.0} kWh", results.total_energy_wh() / 1000.0);
println!("Peak power: {:.0} W", results.peak_power());
println!("Capacity factor: {:.1}%", results.capacity_factor(5000.0) * 100.0);

// Access per-timestep results
for i in 0..results.ac_power.len() {
    // results.solar_zenith[i], results.solar_elevation[i], results.poa_global[i],
    // results.cell_temperature[i], results.dc_power[i], results.ac_power[i]
}

UTC Convenience API

For weather API data (typically UTC timestamps as NaiveDateTime):

use pvlib::batch::{BatchModelChain, WeatherSeries, solar_position_batch_utc};

// Create WeatherSeries from UTC NaiveDateTime timestamps
let weather = WeatherSeries::from_utc(
    &timestamps,           // &[NaiveDateTime] — UTC
    "US/Eastern",          // IANA timezone name
    ghi, dni, dhi, temp_air, wind_speed,
).unwrap();

// Or get just solar position without a full simulation
let (zenith, azimuth, elevation) = solar_position_batch_utc(
    39.74, -105.18, 1830.0, &timestamps,
).unwrap();

Individual batch functions are also available for custom pipelines:

use pvlib::batch;

// All batch functions accept &[f64] and return Vec<f64>
// Automatically parallelized across CPU cores via rayon
let am = batch::airmass_relative_batch(&zenith_vec);
let (ghi, dni, dhi) = batch::ineichen_batch(&zenith_vec, &am, 3.0, 1830.0);
let (dni, dhi) = batch::erbs_batch(&ghi, &zenith, &doy, &dni_extra);
let iam = batch::iam_physical_batch(&aoi, 1.526, 4.0, 0.002);
let pac = batch::pvwatts_ac_batch(&pdc, 5000.0, 0.96, 0.9637);

Single-Timestep Simulation

For real-time or embedded use cases:

use chrono::TimeZone;
use chrono_tz::US::Mountain;
use pvlib::location::Location;
use pvlib::pvsystem::{PVSystem, Array, FixedMount};
use pvlib::modelchain::{ModelChain, WeatherInput};

let location = Location::new(39.74, -105.18, Mountain, 1830.0, "Golden, CO");
let array = Array {
    mount: Box::new(FixedMount { surface_tilt: 30.0, surface_azimuth: 180.0 }),
    nameplate_dc: 5000.0,
    gamma_pdc: -0.004,
    modules_per_string: 10,
    strings: 2,
    albedo: 0.2,
};
let system = PVSystem::new(vec![array], 5000.0);

let mc = ModelChain::with_pvwatts(system, location, 30.0, 180.0, 5000.0, 0.96);

let weather = WeatherInput {
    time: Mountain.with_ymd_and_hms(2024, 6, 21, 12, 0, 0).unwrap(),
    ghi: Some(900.0),
    dni: Some(800.0),
    dhi: Some(150.0),
    temp_air: 30.0,
    wind_speed: 3.0,
    albedo: Some(0.2),
};

let result = mc.run_model_from_weather(&weather).unwrap();
println!("DC: {:.0} W, AC: {:.0} W, Tcell: {:.1} C",
    result.dc_power, result.ac_power, result.cell_temperature);

Step-by-Step Usage

Use individual module functions for maximum control:

use pvlib::{atmosphere, clearsky, irradiance, temperature, iam, inverter};

// Solar position (NREL SPA algorithm)
let location = pvlib::location::Location::new(39.74, -105.18,
    chrono_tz::US::Mountain, 1830.0, "Golden, CO");
let time = chrono_tz::US::Mountain.with_ymd_and_hms(2024, 6, 21, 12, 0, 0).unwrap();
let solpos = location.get_solarposition(time).unwrap();

// Airmass
let am_rel = atmosphere::get_relative_airmass(solpos.zenith);
let pressure = atmosphere::alt2pres(1830.0);
let am_abs = atmosphere::get_absolute_airmass(am_rel, pressure);

// Clear sky irradiance (Ineichen model)
let cs = location.get_clearsky(time, "ineichen");

// Irradiance decomposition (GHI -> DNI + DHI)
let (dni, dhi) = irradiance::erbs(cs.ghi, solpos.zenith, 172, 1366.1);

// Angle of incidence on tilted surface
let aoi = irradiance::aoi(30.0, 180.0, solpos.zenith, solpos.azimuth);

// Incidence angle modifier (Fresnel reflection losses)
let iam_val = iam::physical(aoi, 1.526, 4.0, 0.002);

// Cell temperature (SAPM model)
let (t_cell, _) = temperature::sapm_cell_temperature(
    800.0, 30.0, 3.0, -3.56, -0.075, 3.0, 1000.0);

// AC power (PVWatts inverter)
let pac = inverter::pvwatts_ac(4000.0, 5000.0, 0.96, 0.9637);

Modules

Core Physics

System Modeling

Batch Processing

Advanced Features

I/O & Data

ModelChain Configuration

Both ModelChain (scalar) and BatchModelChain (time series) support configurable model selection:

Factory constructors:

• ModelChain::with_pvwatts() / BatchModelChain::pvwatts() — PVWatts DC/AC, Physical AOI, Perez transposition
• ModelChain::with_sapm() — SAPM temperature, ASHRAE AOI, Hay-Davies transposition
• ModelChain::with_config() — fully custom model selection

Weather Data

Read TMY3 files

let data = pvlib::iotools::read_tmy3("weather.csv").unwrap();
println!("Location: {} ({}, {})",
    data.metadata.name.as_deref().unwrap_or("Unknown"),
    data.metadata.latitude, data.metadata.longitude);
for record in &data.records {
    println!("GHI: {} W/m2, Temp: {} C", record.ghi, record.temp_air);
}

Read EPW files

let data = pvlib::iotools::read_epw("weather.epw").unwrap();

Fetch from PVGIS API

// TMY data for any location worldwide
let tmy = pvlib::iotools::get_pvgis_tmy(45.0, 8.0, None, None, None).unwrap();

// Hourly radiation data
let hourly = pvlib::iotools::get_pvgis_hourly(45.0, 8.0, 2020, 2023,
    false, None, None, None).unwrap();

// Horizon profile
let horizon = pvlib::iotools::get_pvgis_horizon(45.0, 8.0).unwrap();

References

This library implements algorithms from peer-reviewed solar energy literature:

• Solar Position: NREL Solar Position Algorithm (Reda & Andreas, 2004), Spencer (1971)
• Clear Sky: Ineichen & Perez (2002), Bird & Hulstrom (1981), Haurwitz (1945), Simplified Solis (Ineichen, 2008)
• Irradiance: Perez et al. (1990), Hay & Davies (1980), Erbs et al. (1982), DISC (Maxwell, 1987), Boland et al. (2008)
• Temperature: SAPM (King et al., 2004), PVsyst, Faiman (2008), Fuentes (1987), Ross (1980), NOCT SAM
• IAM: Martin & Ruiz (2001), De Soto et al. (2006), Schlick approximation, ASHRAE
• Single Diode: Bishop (1988), De Soto et al. (2006), Newton-Raphson solver
• Inverter: PVWatts (Dobos, 2014), Sandia (King et al., 2007), ADR (Driesse, 2023)
• Tracking: Anderson & Mikofski (2020), Marion & Dobos (2013)
• Soiling: HSU (Coello & Boyle, 2019), Kimber et al. (2006)
• Bifacial: Infinite sheds model (Mikofski et al., 2019)
• Spectrum: Caballero et al. (2018), First Solar spectral correction

Comparison with pvlib-python

pvlib-rust covers the core simulation pipeline of pvlib-python with significant performance advantages:

Building & Testing

cargo build              # Build the library
cargo test               # Run all 337 tests
cargo test --release     # Run tests with optimizations (faster batch)
cargo clippy             # Lint checks
cargo doc --open         # Generate and view API documentation
cargo bench              # Run benchmarks (if configured)

License

Licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

This project is a Rust port of pvlib-python, developed by the pvlib community. All credit for the underlying algorithms and models goes to the original authors and the pvlib-python contributors.