PVSimulator

PV production simulator based on pvlib for a single location and a full reference year.

The PVSimulator provides an end-to-end workflow to simulate hourly photovoltaic electricity production over a year, using PVGIS irradiance data and pvlib's physical models.

The simulator encapsulates:

• Geographical and temporal context (location, timezone, reference year)
• PV module characteristics (efficiency, temperature coefficient)
• Installation configuration (mounting type, system losses)
• Weather data acquisition with plane-of-array (POA) irradiance
• PV system modeling via pvlib.modelchain.ModelChain
• Post-processing and KPI computation

Results are returned as a pandas DataFrame with hourly resolution and include both energy production and other key performance indicators.

Notes

• The simulation is normalized per square meter of PV module area.
• Weather data are sourced from PVGIS (SARAH3 database).
• No degradation, curtailment, or grid constraints are modeled.
• Inverter behavior is assumed ideal; system losses are applied ex-post.
• The simulator is designed for annual simulations (single year).

Attributes:

Name	Type	Description
environment	dict	Environmental configuration including latitude, longitude, and simulation year.
installation	dict	Installation parameters such as mounting type, tilt/azimuth (derived), and system losses.
pv_module	dict	PV module parameters including efficiency and temperature coefficient.
location	Location	pvlib Location object with timezone.
weather_data	DataFrame	Hourly POA weather data used for simulation.
pv_system	PVSystem	Configured PV system model.
results	DataFrame	Hourly simulation outputs and KPIs (computed after calling compute_pv_production).

Presets

The simulator supports two predefined installation presets, which control mounting assumptions and irradiance processing:

1. freestanding_opt_tilt: Ground-mounted or freestanding PV system. Surface tilt is optimized by PVGIS for maximum annual yield. Temperature model: freestanding (well-ventilated).

2. flat_roof: Fixed horizontal installation (tilt = 0°, azimuth = 180°). No tilt optimization is applied. Temperature model: insulated (reduced ventilation).

Examples:

>>> env = {"latitude": 48.85, "longitude": 2.35, "year": 2023}
>>> module = {"efficiency": 0.20, "temperature_coefficient": -0.004}
>>> install = {"type": "freestanding_opt_tilt", "system_losses": 0.14}
>>> sim = PVSimulator(env, module, install)
>>> sim.compute_pv_production()
>>> df = sim.results

Attributes

environment property writable

Environmental configuration for the simulation.

Contains geographical coordinates and the reference year. Validation ensures physically meaningful ranges.

Returns:

Name	Type	Description
dict	dict	Environment dictionary.

installation property writable

PV installation configuration.

Includes mounting type, system losses, and derived geometric parameters (tilt and azimuth).

Returns:

Name	Type	Description
dict	dict	Installation dictionary.

pv_module property writable

Photovoltaic module parameters.

Defines conversion efficiency and temperature sensitivity used in PVWatts-style power modeling.

Returns:

Name	Type	Description
dict	dict	PV module dictionary.

results property writable

Simulation results and KPIs.

Available after calling compute_pv_production.

Returns:

Type	Description
DataFrame	pd.DataFrame: Hourly PV production and performance indicators.

Functions

__init__(environment, pv_module, installation)

Initialize a PVSimulator with environmental context, PV module characteristics, and installation settings.

This constructor: - Validates all input dictionaries - Determines the local timezone from coordinates - Fetches hourly POA irradiance data from PVGIS - Instantiates a pvlib.PVSystem object ready for simulation

Parameters:

Name	Type	Description	Default
environment	dict	Environmental parameters with keys: - latitude (float): Site latitude in degrees. - longitude (float): Site longitude in degrees. - year (int): Reference year for the simulation.	required
pv_module	dict	PV module parameters with keys: - efficiency (float): Module efficiency (0 < η ≤ 1). - temperature_coefficient (float): Power temperature coefficient (1/°C).	required
installation	dict	Installation parameters with keys: - type (str): Installation type ("freestanding_opt_tilt" or "flat_roof"). - system_losses (float): Aggregate system losses (0–1).	required

Raises:

Type	Description
ValueError	If any input dictionary is invalid or contains out-of-range values.

compute_pv_production()

Compute hourly PV electricity production and key performance indicators.

The simulation uses pvlib.modelchain.ModelChain driven by plane-of-array irradiance. System losses are applied after physical modeling.

Computed outputs include: - AC PV production (W/m²) - Performance ratio - Capacity factor - Module operating temperature - POA irradiance

Returns:

Type	Description
DataFrame	pd.DataFrame: Hourly PV production and KPI time series.

get_timezone(lat, lon)

Get the timezone string from geographic coordinates.

Parameters:

Name	Type	Description	Default
lat	float	Latitude in degrees.	required
lon	float	Longitude in degrees.	required

Returns:

Name	Type	Description
str	str	Timezone identifier (e.g., "Europe/Paris"), or None if not found.