energy.solar-generation

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

def solar_generation(arrays: Sequence[PvArray]) -> SolarEstimate

@dataclass(frozen=True)
class PvArray:
    """One PV array, as the MCS performance estimate describes it."""

    #: sum of the module data-plate ratings at STC, in watts: 4.32 kWp is 4320
    watts_peak: int
    #: kWh/kWp from the MCS table for the postcode zone, pitch and orientation
    kk: int
    #: SF in hundredths, 1.00 (no shading) is 100, 0.89 is 89
    shade_factor: int

@dataclass(frozen=True)
class SolarEstimate:
    """Annual AC generation, by array and in total."""

    #: kWh a year for each array, in the order given
    arrays: List[int]
    #: the sum of the arrays
    total: int

from fune.energy.solar_generation import solar_generation  # energy.solar-generation@^1

from typing import Sequence

from .energy_solar_generation_types import PvArray, SolarEstimate
from .math_round_div import 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.
DIVISOR = 100_000


def _check(what: str, value: object, maximum: int) -> None:
    if not isinstance(value, int) or isinstance(value, bool) or value < 0 or value > maximum:
        raise ValueError("%s must be a whole number from 0 to %d, received %s" % (what, maximum, value))


def solar_generation(arrays: Sequence[PvArray]) -> SolarEstimate:
    """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.
    """
    if len(arrays) == 0:
        raise ValueError("a solar estimate needs at least one array")
    kwh = []
    for a in arrays:
        _check("wattsPeak", a.watts_peak, 100_000_000)
        _check("kk", a.kk, 5000)
        _check("shadeFactor", a.shade_factor, 100)
        kwh.append(round_div(a.watts_peak * a.kk * a.shade_factor, DIVISOR, "half-up"))
    return SolarEstimate(arrays=kwh, total=sum(kwh))

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the Python 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. 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 Python implementation. Install it without the registry with fune add ./energy.solar-generation-1.0.0-python.fune, or fetch it from a terminal with fune pull energy.solar-generation@1.0.0:python.

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