ebm.model.energy_use module

base_load(heating_systems_projection: DataFrame) → DataFrame[source]
peak_load(heating_systems_projection: DataFrame) → DataFrame[source]
tertiary_load(heating_systems_projection: DataFrame) → DataFrame[source]
heating_rv(heating_systems_projection: DataFrame) → DataFrame[source]
heating_dhw(heating_systems_projection: DataFrame) → DataFrame[source]
cooling(heating_systems_projection: DataFrame) → DataFrame[source]
other(heating_systems_projection: DataFrame) → DataFrame[source]
all_purposes(heating_systems_projection: DataFrame) → DataFrame[source]
efficiency_factor(heating_systems: DataFrame) → DataFrame[source]
energy_use_kwh(energy_need: DataFrame, efficiency_factor: DataFrame, energy_column: str = 'energy_requirement') → DataFrame[source]

Merge energy needs with efficiency parameters and compute delivered energy (kWh).

The function:

  1. Copies the energy_need frame,

  2. Resets its index,

  3. Performs an inner merge with efficiency_factor on (‘building_category’, ‘building_code’, ‘purpose’, ‘year’),

  4. Computes delivered energy kwh using efficiency_kwh(energy_need_col, heating_system_share, load_share, load_efficiency),

  5. Scales kwh_m2 by efficiency_factor if kwh_m2 exists, otherwise sets it to NaN.

Parameters

energy_needpandas.DataFrame

Input dataframe containing energy needs. Must include the join keys: - ‘building_category’ - ‘building_code’ - ‘purpose’ - ‘year’ and the column specified by energy_column (default: ‘energy_requirement’).

efficiency_factorpandas.DataFrame

Dataframe with efficiency parameters. Must include the same join keys as above and: - ‘heating_system_share’ - ‘load_share’ - ‘load_efficiency’ - ‘efficiency_factor’

energy_columnstr, default ‘energy_requirement’

Column name in energy_need representing the energy need passed to efficiency_kwh.

Returns

pandas.DataFrame

The merged dataframe with two additional columns: - ‘kwh’ : Delivered energy computed via efficiency_kwh(…). - ‘kwh_m2’ : If present before the merge, it is scaled by ‘efficiency_factor’;

otherwise it is created and filled with NaN.

Note that the result reflects an inner join of the inputs after energy_need.reset_index(), which may drop unmatched rows from either side and include the old index as a normal column named ‘index’ (unless the original index had a different name).

Raises

KeyError

If any of the required join keys or columns are missing in either input.

Notes

  • The function relies on an external callable efficiency_kwh that must accept vectorized pandas Series for: (energy_need_col, heating_system_share, load_share, load_efficiency), and return a Series of delivered energy in kWh.

  • The merge uses default pandas behavior: how=’inner’ and default suffixes. If both dataframes share other non-key column names (e.g., ‘kwh_m2’), pandas may add suffixes (e.g., ‘_x’, ‘_y’).

  • Existing NaNs in any efficiency inputs will propagate through to ‘kwh’ depending on efficiency_kwh’s implementation.

Examples

>>> # energy_need columns (example):
>>> # ['building_category', 'building_code', 'purpose', 'year',
>>> #  'energy_requirement', 'kwh_m2']
>>> # efficiency_factor columns (example):
>>> # ['building_category', 'building_code', 'purpose', 'year',
>>> #  'heating_system_share', 'load_share', 'load_efficiency', 'efficiency_factor']
>>> out = energy_use_kwh(energy_need, efficiency_factor, energy_column='energy_requirement')
>>> out[['kwh', 'kwh_m2']].head()
efficiency_kwh(energy_need: Series, heating_system_share: Series, load_share: Series, load_efficiency: Series) → Series[source]

Compute delivered electricity (kWh) from energy need, system share, load share, and efficiency.

Result = energy_need * heating_system_share * load_share / load_efficiency

Parameters

energy_need : pd.Series heating_system_share : pd.Series load_share : pd.Series load_efficiency : pd.Series

Raises

ValueError

If the input series are not of equal length. If the input indexes are different.

Returns

pd.Series Energy used in unit (kWh)

building_group_energy_use_kwh(heating_systems_parameter: DataFrame, energy_need: DataFrame) → DataFrame[source]
energy_use_gwh_by_building_group(energy_use_kwh: DataFrame) → DataFrame[source]
calculate_energy_use(database_manager: DatabaseManager, years: YearRange | None = YearRange(start=2020, end=2050), area_parameters: DataFrame | None = None, scurve_parameters: DataFrame | None = None, building_code_parameters: DataFrame | None = None) → DataFrame[source]

calculates energy use in KWh by building_category, TEK, building_condition, year, purpose.

The dataframe is index by row index. (subject to change)

extra columns m2, original_kwh_m2, reduction_yearly, reduction_policy, reduction_condition, reduced_kwh_m2,

behaviour_factor, kwh_m2, energy_requirement, heating_systems, heating_system_share, load_share, load_efficiency, energy_product, heating_system, load, building_group, efficiency_factor

Parameters

database_manager : pd.DataFrame years : YearRange, optional area_parameters : pd.DataFrame, optional scurve_parameters : pd.DataFrame, optional building_code_parameters : pd.DataFrame, optional

Returns

pd.DataFrame

energy use in KWh by building_category, TEK, building_condition, year, purpose ,