energy.solar-generation

Annual AC output (kWh) = kWp x Kk x SF

pub fn solar_generation(arrays: &[PvArray]) -> SolarEstimate

/// One PV array, as the MCS performance estimate describes it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PvArray {
    /// sum of the module data-plate ratings at STC, in watts: 4.32 kWp is 4320
    pub watts_peak: i64,
    /// kWh/kWp from the MCS table for the postcode zone, pitch and orientation
    pub kk: i64,
    /// SF in hundredths, 1.00 (no shading) is 100, 0.89 is 89
    pub shade_factor: i64,
}

/// Annual AC generation, by array and in total.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SolarEstimate {
    /// kWh a year for each array, in the order given
    pub arrays: Vec<i64>,
    /// the sum of the arrays
    pub total: i64,
}

fune!(energy.solar-generation@^1);  // then call solar_generation(…)

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::math_round_div::round_div;  ← from math.round-div ^1.0.0 · built alongside by fune

// watts x Kk x SF (hundredths) / (1000 W/kW x 100) is kWh.
const DIVISOR: i64 = 100_000;

fn check(what: &str, value: i64, max: i64) {
    if value < 0 || value > max {
        panic!("{} must be a whole number from 0 to {}, received {}", what, max, value);
    }
}

/// Annual AC generation by the MCS method, kWp x Kk x SF, rounded half-up to
/// a whole kWh for each array; the total is the sum of the arrays.
///
/// # Panics
/// Panics on no arrays, or a rating, Kk or shade factor out of range.
pub fn solar_generation(arrays: &[PvArray]) -> SolarEstimate {
    if arrays.is_empty() {
        panic!("a solar estimate needs at least one array");
    }
    let kwh: Vec<i64> = arrays
        .iter()
        .map(|a| {
            check("wattsPeak", a.watts_peak, 100_000_000);
            check("kk", a.kk, 5000);
            check("shadeFactor", a.shade_factor, 100);
            round_div(a.watts_peak * a.kk * a.shade_factor, DIVISOR, "half-up")
        })
        .collect();
    let total = kwh.iter().sum();
    SolarEstimate { arrays: kwh, total }
}

fn whole(what: &str, max: i64, v: &Value) -> i64 {
    if let Value::Float(f) = v {
        panic!("{} must be a whole number from 0 to {}, received {}", what, max, f);
    }
    v.as_i64()
}

pub fn pv_array_from_value(v: &Value) -> PvArray {
    PvArray {
        watts_peak: whole("wattsPeak", 100_000_000, v.get("wattsPeak")),
        kk: whole("kk", 5000, v.get("kk")),
        shade_factor: whole("shadeFactor", 100, v.get("shadeFactor")),
    }
}

pub fn solar_estimate_to_value(e: &SolarEstimate) -> Value {
    Value::obj(vec![
        ("arrays", Value::Arr(e.arrays.iter().map(|k| Value::Int(*k)).collect())),
        ("total", Value::Int(e.total)),
    ])
}

pub fn fune_vector(args: &[Value]) -> Value {
    let arrays: Vec<PvArray> = args[0].as_arr().iter().map(pv_array_from_value).collect();
    solar_estimate_to_value(&solar_generation(&arrays))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the Rust package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. A crate’s build.rs runs it before every compile. Or pin a range in fune.project and build in one step:

fune add energy.solar-generation

The manifest, vectors and README with only the Rust implementation. Install it without the registry with fune add ./energy.solar-generation-1.0.0-rust.fune, or fetch it from a terminal with fune pull energy.solar-generation@1.0.0:rust.

The whole function, every language, is one file too: energy.solar-generation-1.0.0.fune, 11,670 bytes, sha256 a6eb49277bb295c09e59a36e09900ec037b8cf1787bf39d098595bf24e77cbd0. It installs into a project of any language.

// fune: before energy.solar-generation

// fune: after energy.solar-generation

// fune: replace math.round-div in energy.solar-generation

// fune: step energy.solar-generation after <n|label>

More from the author

- **kWp**: the sum of the module data-plate ratings (Wp at STC), passed in watts. - **Kk**: kWh per kWp, looked up in MCS's table for the site's postcode zone (the SAP zones), the array pitch (to the nearest 1°) and its orientation from due south (to the nearest 5°). It carries the irradiance and the orientation and pitch factor together. - **SF**: the shade factor, 1.00 with a clear horizon, otherwise 1 - estimated shading loss (for example 0.89), to two places.

## Why the Kk table is an argument

MCS publishes Kk as downloadable tables: 21 postcode zones, each a grid of pitch 0-90° by orientation 0-180°, drawn from the European Commission's PVGIS dataset (multiplied by 0.8). That is tens of thousands of values, and MCS updates them with the standard. Shipping a partial copy would invite silent use of the wrong zone, so the caller looks Kk up (from the MCS tables or their design software) and this capability does the arithmetic and the rounding the same way everywhere.

## Several arrays

MIS 3002 estimates an east/west or multi-roof system array by array, each with its own Kk and SF. Each array is rounded to a whole kWh, **half-up**, and the total is the sum of those rounded figures, so the total always equals the lines on the estimate. (Rounding the unrounded sum instead can differ by a kWh or two.)

MIS 3002 does not state a rounding rule; whole kWh, half-up, matches the estimates installers print.

## Sources

MCS, "MIS 3002: The Solar PV Standard (Installation)", issue 5.0, 10 May 2023, Appendix B "Standard estimation method" and section 4.1.6, https://mcscertified.com/wp-content/uploads/2025/02/MIS-3002_Solar-PV-Systems-V5.0-Final-for-publication.pdf

Files