Energy methods
PV climate classifications
Compare KGPV, JRC parametric climates, ML21 and PVCZ. The implementation includes validated source readers, fixed PVCZ thresholds, frozen JSON cluster models, and offline global/Chile/Canary reference maps. Source periods, input units, published labels and documented refits stay explicit.
Image-based module counting
Count regular module-grid candidates from resolved RGB aerial imagery, with automatic table/frame detection, review flags and geographic exports. This experimental method does not establish an as-built inventory.
Project origins and method attribution
The project was inspired by Julián Andrés Ascencio Vásquez (2021),
Modelling and worldwide assessment of performance and aging of photovoltaic
modules and systems, University of Ljubljana. The early methods build on
that research; subsequent additions also draw on other literature and new
project developments. The full catalogue
contains the original method papers, data sources, software and standards;
references.bib provides BibTeX. Each method exposes
REFERENCE_IDS; portable fitted-state exports retain those IDs.
Cite the sources for each method actually used, including the thesis for work derived from it. Use descriptive method names such as acceptance band and typical daily profiles, with author names in citations. The published TDP and acceptance-band methods are adapted explicitly below. The shape-constrained PV basis is repository-specific and uses the Stark–Parker BVLS algorithm through SciPy. Operational screening is informed by IEC TS 63019 and does not establish IEC conformity, verified causes or certified availability.
Country-neutral, typed Python methods for photovoltaic performance assessment.
Install as energy-methods and import energy_methods. The workspace root
documents installation and quality checks.
Scientific scope
- Climate Change Yield Assessment (CCYA) follows thesis sections 7.5.1-7.5.3: historical monthly calibration, future irradiance/temperature/degradation components and annual/cumulative comparisons. The CCYA guide maps equations and explicitly documents fitting and normalization choices.
- Acceptance bands follow the two-stage bin/curve method in Ascencio-Vásquez et al. (2020).
- Typical Daily Profiles pool original hourly observations by calendar month and hour, with separate year-to-year profiles, following Ascencio-Vásquez et al. (2021).
- Effective POA uses pvlib solar position, Erbs decomposition and Hay-Davies transposition. Inferred geometry is a model hypothesis, not verified as-built configuration.
- The physical response is analytically concave and nondecreasing in irradiance, and nonincreasing in ambient temperature within its declared domain.
- Monotone LightGBM is a separate trainable alternative. Monotonicity does not guarantee concavity. No accuracy target is guaranteed.
- The IEC-informed screen preserves observable states and leaves operational causes unconfirmed. It does not establish IEC availability or storm damage.
All fitting receives the chronological training partition only. Test generation must never be used for filtering, geometry selection or model selection. Reported zeros remain observations; missing values are never filled with zero.
Public interfaces
| Module | Entry points | Units and behavior |
|---|---|---|
acceptance_band |
fit_acceptance_band, performance_ratio, pr_acceptance_mask |
POA in W/m²; interval energy in MWh; DC STC rating in MW. Unsupported bands raise BandFitUnavailable. |
poa |
transpose_ghi, fit_effective_poa, solar_elevation_midpoint, shift_weather |
Timezone-aware UTC hourly interval starts, WGS84 coordinates. Geometry and lag fitting reads training labels only. |
physics |
fit_physics_model |
Accepted POA, ambient °C and hourly MWh. Two analytically constrained model families. |
lightgbm |
fit_lightgbm |
Separate monotone tree model; explicitly bounded threads and deterministic configuration. |
metrics |
energy_metrics |
Matching nonnegative actual/expected pairs, including reported zeros. |
status |
classify_status |
Ten observable hourly states plus envelope, band disagreement, near-zero and persistence evidence. |
tdp |
analyze_tdp |
Country-neutral DataFrame interface; configurable fixed profile clock, default UTC. |
ccya |
fit_ccya, CCYAModel.project, fit_site_adaptation |
Monthly GHI in W/m², ambient °C, native-calendar days and measured DC yield in kWh/kWp; complete years and separate scenario/member projections. |
Fitted bands and models expose to_dict() with portable numerical state. LightGBM
exports its text booster representation, not a pickle. Physical models and tree
models expose weather_support() independently of their broader prediction
domain. This prevents an in-domain numerical value from silently becoming an
independently supported operating reference.
Training and evaluation order
- Establish a chronological training cutoff in UTC and keep later observations for evaluation. Never use a random row split for the time-series result.
- Infer geometry/clock lag only from that training partition, or use qualified
as-built metadata.
fit_effective_poatreatstraining_endas inclusive; an exclusive cutoff can be represented ascutoff - pd.Timedelta(1, 'ns'). - Fit the acceptance band on training POA/energy. Apply the frozen band to the training rows used for model fitting. Do not remove poor holdout observations to inflate validation scores.
- Where independently qualified DC STC capacity exists, apply the separate
inclusive
0.50 <= PR <= 1.00training gate. An absent DC rating makes this gate unavailable; AC capacity is not a substitute. PR isE_AC / (P_DC_STC * POA/1000 * elapsed_hours). - Fit the physical or LightGBM response to accepted training rows. Evaluate later observations on matching actual/expected intervals, retaining zeros.
- Refit a separate final model only after the evaluation choices are frozen. Keep the held-out reference and the final in-sample reference labelled separately. New training does not reproduce an older frozen model by identity.
EnergyMetrics.score_pct is 100*(1-WAPE), where WAPE uses the sum of measured
energy as denominator. It may be negative. It is undefined when the measured
energy denominator is zero. It is not classification accuracy, R² or a promise
of 75% performance. Actual/expected energy bias and errors are also reported.
Acceptance-band interpretation
The implementation preserves the previously documented interpretation of the 2020 paper, rather than claiming the printed pseudocode is internally consistent:
- Gaussian within-bin means/population standard deviations define the percentile ordinates. Low accuracy uses 20/50/80%; medium and high use 5/50/95%.
- The bin width (50 W/m²), maximum irradiance (1,300 W/m²), minimum ten observations per bin and seven populated bins are explicit project settings.
- The power normalization is the positive training-energy Q95, not capacity. Quartic fits use irradiance/1,000 and normalized energy for conditioning.
- Mixed-order roughness uses squared differences at offsets ±2 and absolute differences at offsets ±1. Only observed neighboring bin IDs contribute. The roughness itself is compared with its empirical 90th percentile; the printed comparison of a power ordinate with a roughness threshold is not used.
- Lower and upper signed distances use their respective percentile curves minus the fitted center. Outward residuals are trimmed at Gaussian 25/75% distance thresholds before separate quartic side fitting.
- Bounds require populated bins within the intersection of the three retained fitting domains. Unsupported or crossing bounds return NaN. They are never extrapolated, swapped or replaced with a different filter on failure.
The published independent variable is POA. Calling a GHI-based envelope a direct implementation would be misleading; the application must explicitly document such an adaptation. The standard workflow uses transposed effective POA.
Effective POA and time alignment
Solar position is calculated at twelve equal midpoint substeps per hour. Hourly GHI is distributed in proportion to positive cosine of true zenith, preserving the hourly mean when the sun is above the horizon. Erbs decomposition and Hay-Davies transposition follow. Applying an hourly empirical decomposition at these synthetic substeps is a declared integration approximation. There is no claim to reconstruct clouds or infer a surveyed array orientation.
The geometry bank is finite and supplied by the caller. Fixed and single-axis
configurations are supported. A positive lag of one means the feature at hour
t uses source weather at t-1; missing edges remain missing. Lag selection
requires a regular UTC hourly grid and no circular wrapping. Training objective
rows cannot use generation or shifted source weather after the cutoff. Original
solar elevation remains unshifted for operating-state evidence.
Solar position, decomposition and GHI disaggregation are prepared once per geometry-bank fit, then reused. There is no unbounded global cache. The bank does not require a candidate-by-hour-by-substep tensor, limiting peak memory.
References: Erbs, Hay-Davies, interval transposition.
Physical response versus LightGBM
The concave-spline raw response is
Q * (r*g + sum(d_k*min(g,k)) + c*g*(tmax-t)),
with nonnegative r, d_k, c, g=POA/1000, t=(Tamb-25)/25 and training
normalization Q. Successive irradiance slopes cannot increase; the temperature
derivative cannot be positive. The thermal-quadratic alternative uses an
equivalent nonnegative transformed basis that constrains the hottest/brightest
irradiance slope to remain nonnegative. Both use constrained least squares with
explicit regularization. The shape domain defaults to POA 0–1,300 W/m² and
ambient temperature −20–60 °C. The POA ≤1 W/m² zero-output convention is a separate
startup cutoff, so the raw shape guarantee excludes that discontinuity.
These parameters are empirical; they do not establish module temperature, thermal coefficients, shading, bifacial gain or recoverable losses.
LightGBM uses the squared-error regression objective with [+1,-1] feature
monotonicity, deterministic CPU mode, forced column histograms and bounded worker
counts. Monotonic constraints are not compatible with LightGBM's regression_l1
objective. Tree monotonicity alone cannot guarantee a concave irradiance response.
Training and prediction thread limits are both explicit to prevent nested fleet
parallelism from oversubscribing the machine.
LightGBM parameters document the underlying constraints and deterministic-mode limitations across different versions/platforms.
Typical Daily Profiles
analyze_tdp receives site_id, timezone-aware timestamp, and a configured value
column (default actual_mwh). By default a useful day has 24 finite nonnegative
hourly observations and a year-month needs at least 15 useful days. Each reported
quantile needs at least ten observations. These project conventions are explicit
configuration, not implied publication constants. The Chile workflow uses fixed
UTC−04; the core default is UTC. Fixed-clock TDPs and civil-time DST reporting
must remain distinct.
Positive flat generation days are excluded only when complete solar elevation
is available and at least four observed daylight hours cover 75% of expected
daylight hours. Values must agree within the configured tolerance and at least
one must be positive. Reported zero days are retained, including zero-only sites.
Without solar elevation the flat-day screen is marked unavailable. Weather
profiles should disable the positive-flat screen; ambient temperature should
also set nonnegative=False.
Year-month qualification happens before AVG pooling. AVG combines original hourly observations from eligible year-months; it does not average annual percentiles. Raw profiles retain all physically valid observed values before these day/month gates. Every hour retains its own observation count.
The paper's historical net-capacity normalized-yield and net-PR gates require independently verified capacity effective dates and supported historical POA. This implementation does not infer those from undated registry MW or substitute DC capacity. The output explicitly reports that limitation. The earlier DC-PR training gate and acceptance band are separate from TDP input qualification.
Operating-state evidence
The ten states preserve the recovered ASVA decision order: missing generation, invalid generation, night without generation, low resource without generation, generation at low resource, no generation with adequate resource, reference unavailable, below reference, within tolerance and above reference. Missing resource inputs remain unavailable, even when output is zero.
Resource-present trace output is identified before model-support gates. Positive
output comparisons require the matching stage's training-weather support and
accepted-training Q95 (including accepted zeros). The envelope is
expected ± max(20%*expected, 5%*training_Q95), with an expected-output floor of
5% Q95. These are engineering thresholds, not IEC thresholds or calibrated
prediction intervals. Band-inside plus below/above-model output is not, by itself,
the recovered asymmetric model/band disagreement flag.
Persistence requires at least two consecutive elapsed hours with the same no-generation-with-resource or below-reference state. Timestamp gaps and changes between those states break a run. These runs do not establish verified outage duration. Solar elevation outside physical ±90° is treated as unavailable.
The information category remains Information unavailable (§5.18); causes and capability are unconfirmed. Positive hourly energy only establishes generation during some part of that interval. No dispatch/curtailment, equipment fault, maintenance, storm-damage diagnosis or IEC availability percentage is inferred. See the IEC TS 63019:2019 scope.
Verification and performance
uv run ruff check methods
uv run ty check methods
uv run pytest methods/tests
uv run python methods/benchmarks/benchmark_poa.py --hours 2160
Tests cover physical shape constraints, training/test isolation, POA horizontal closure, exact lag edges, band support, PR units/boundaries, all ten statuses, state precedence, timestamp-gap persistence, TDP pooling, missingness and zero retention, and LightGBM determinism/portable inference. Benchmark inputs are synthetic and labelled; its measured timing is machine-specific.
Climate classification and mapping
energy_methods.kgpv implements the KGPV temperature/precipitation rules,
fixed irradiation thresholds and published 24-to-12 zone merging.
energy_methods.climatology builds monthly climatologies from bounded batches.
energy_methods.mapping provides coordinate normalization, explicit regridding,
cell areas, class summaries and bounded GeoJSON export.
Run energy-kgpv --help; see the complete workflow and assumptions.
The thesis citation and the specific 2019 KGPV paper are both retained.
Soiling and snow risk mapping
country_boundaries selects and exports country shapefiles/GeoJSON;
country_mapping builds finer regional grids, masks by polygons, plots clipped
maps and exports clipped cells. These helpers also work with KGPV and degradation.
See country selection, CRS handling and examples.
energy_methods.weather_risk implements thesis Eqs. 3.2–3.4 and the five
classes in Tables 6.6–6.7. weather_risk_mapping validates complete-year AOD550
and physical ground snow-depth inputs and maps the resulting indicators.
See equations, units and conventions and the offline
worldwide gallery example. Soiling rate is in %/day; snow energy loss is in %/year.
These are empirical screening indicators, with explicit missingness and
threshold boundaries, rather than independently validated site losses.
Climate degradation mapping
energy_methods.degradation implements the thesis's hydrolysis,
photo-degradation, thermomechanical and combined-rate equations, with an explicit
module calibration. degradation_mapping processes annual stresses, classifies
total rates in 0.2%/year bins and summarizes mapped mechanisms by KGPV zone.
Run energy-degradation --help; see inputs, scientific assumptions and the
synthetic example. This method follows the thesis,
the Kaaya model and the 2019 degradation mapping paper, all of which are cited.
energy_methods.degradation_weather supplies the published GHI-Faiman temperature
and Wald UVA/UVB transformations used by the applied map analysis.
The near-Rengo pilot extends module-candidate counting with orientation correction, autocorrelation and source-resolution checks.
energy_methods.pv_site_3d builds local metric terrain meshes and common table
planes from geographic module footprints, declared elevation grids and explicit
mounting parameters. See the 3D site method and other-site recipe.
It preserves missingness and source datum; it does not recover depth from imagery.
Metadata
Release files for energy-methods 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| energy_methods-0.1.0.tar.gz | 191.0 kB | Without provenance | Details for energy_methods-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| energy_methods-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for energy_methods-0.1.0-py3-none-any.whl |
Total release size: 375.0 kB
Release files / energy_methods-0.1.0.tar.gz
| Download URL | energy_methods-0.1.0.tar.gz |
|---|---|
| Size | 191.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d8deb71052b9db97cb824f3e97dc9b68dd9494f864879abc92ff4802a6ce0d26
|
|
BLAKE2b-256 checksum How to use checksums |
c54006f0347221edf29662414652efce8b5a3b748937e5944994b5663dc5f5f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / energy_methods-0.1.0-py3-none-any.whl
| Download URL | energy_methods-0.1.0-py3-none-any.whl |
|---|---|
| Size | 184.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
db77eeb5f839f510ec659ac8dddf40699d85bdfb5f3c79640ffc76e9e9807f07
|
|
BLAKE2b-256 checksum How to use checksums |
de46a064f5fdeb099e873536c68f195015054fec6511e24220021473350d6548
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for energy-methods 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.