Skip to content

ISO 52010 - Calculation procedure

def Calculation_ISO_52010(building_object, path_weather_file, weather_source="pvgis") -> simdf_52010

Input

Name Type Description
building_object dict or object Building structure; if it is a mapping, a default set of orientations is used. Otherwise, the function reads building_object.orientation_elements.
path_weather_file str | PathLike Path to an EPW weather file (used when weather_source="epw").
weather_source str Selects the input weather pipeline. Supported values: "pvgis" (TMY fetch via PVGIS) or "epw" (local EPW).

Purpose

Implements the EN ISO 52010-1 processing pipeline to convert raw climatic data (EPW/PVGIS TMY) into simulation-ready time series and to compute solar irradiance on arbitrary surfaces plus window shading reduction factors. The function returns a wrapper around a pandas.DataFrame containing all derived variables.

How it works

  1. Fetch raw weather

    • pvgis → ISO52010.get_tmy_data_pvgis(building_object)
    • epw → ISO52010.get_tmy_data_epw(path_weather_file)
      The result exposes:
    • weather_data → base DataFrame with hourly variables (UTC)
    • utc_offset → integer hours to shift from UTC to local time
    • latitude, longitude

  2. Normalize the time index

    • If not a leap year (len(sim_df) == 8760), rebuild index to a nominal year 2009 using original month/day/hour.
    • Apply np.roll by utc_offset to every column to align to local time.
    • Rename index axis from time(UTC) → time(local) and add helpers:
      • day of year (1–365/366)
      • hour of day (1–24, ISO52010 convention)

  3. Define surface orientations (tilt/azimuth pairs) 

    HOR → (beta=0,   gamma=0)
SV  → (beta=90,  gamma=0)
EV  → (beta=90,  gamma=90)
NV  → (beta=90,  gamma=180)
WV  → (beta=90,  gamma=-90)

    If building_object is a dict, the set {'EV','HOR','SV','NV','WV'} is used; otherwise building_object.orientation_elements is read.

  4. For each orientation

    • Call ISO52010.Solar_irradiance_calculation(...) with: latitude, longitude, timezone, the selected (beta, gamma), input DHI (Gd(h)), DNI (Gb(n)), albedo, and a calendar built from the index.
    • Concatenate resulting columns (renamed):
      • I_sol_tot_{ori}, I_sol_dif_{ori}, I_sol_dir_w_{ori}
    • Compute window shading reduction factor with ISO52010.Shading_reduction_factor_window(...) and append its columns if present.

  5. Warm-up period
    Prepend December to the beginning of the series to form a warm-up period: 

    sim_df = pd.concat([sim_df[sim_df.index.month == 12], sim_df])

  6. Return wrapper 

return simdf_52010(sim_df=sim_df)

Outputs

Type Description
simdf_52010 Small wrapper carrying sim_df: pd.DataFrame with weather (local time), solar irradiances by orientation, shading factors, and utility calendar columns.

Columns Added by the Procedure

  • Calendar helpers: day of year, hour of day (1–24)
  • Solar (per orientation):
  • I_sol_tot_{ORI} → total solar irradiance on the plane (W/m²)
  • I_sol_dif_{ORI} → diffuse component on the plane (W/m²)
  • I_sol_dir_w_{ORI} → direct beam on the plane adjusted by window incidence (W/m²)
  • Shading (when available): one or more W_{window_name} and H_sun_{window_name} series from Shading_reduction_factor_window

The base weather columns depend on the chosen source but typically include dry-bulb temperature, relative humidity, wind speed, DHI = Gd(h), DNI = Gb(n), and global horizontal.

Orientation & Angles

  • beta = tilt (0° = horizontal, 90° = vertical)
  • gamma = azimuth (0° = South, 90° = East, 180° = North, -90°/270° = West)
  • Time index is local after the utc_offset roll.

Notes

  • Leap year handling: if len(sim_df) > 8760 (8784 hours), the index is left as-is and n_days_year=366.
  • np.roll shifts all columns equally; ensure the source weather data are aligned and cyclical.
  • The warm-up prepend duplicates December; if you perform annual KPIs, exclude the first month accordingly.
  • Shading_reduction_factor_window requires geometric window metadata inside building_object.

Example

sim = Calculation_ISO_52010(
    building_object=my_building,
    path_weather_file="../weather/rome.epw",
    weather_source="epw"
)
df = sim.sim_df
print(df.filter(like="I_sol_tot_").head())

Reference

  • EN ISO 52010-1:2017 – Energy performance of buildings — External climatic conditions
  • Weather_data_bui – convenience wrapper that returns a simulation_df built on top of this pipeline
  • ISO52010.Solar_irradiance_calculation – solar geometry & plane-of-array irradiance
  • ISO52010.Shading_reduction_factor_window – window shading factors per orientation