Building

Core agent-based model: household behavior, renovation decisions, and heating system choices.

When to use this module

Use project.building when you need to inspect or extend behavior at dwelling and agent level, including:

• renovation choice logic

• heating-system switching behavior

• stock state transitions on the agent side

Main classes are exposed through ThermalBuildings and AgentBuildings.

class project.building.AgentBuildings(stock, surface, ratio_surface, efficiency, income, preferences, performance_insulation_renovation, lifetime_heater=None, path=None, year=2018, endogenous=True, exogenous=None, expected_utility=None, logger=None, calib_scale=True, quintiles=None, rational_behavior_insulation=None, rational_behavior_heater=None, resources_data=None, detailed_output=True, figures=None, method_health_cost=None, residual_rate=0, constraint_heat_pumps=True, variable_size_heater=True, temp_sink=None, social_discount_rate=0.032, lifetime_insulation=30, vat_heater=0.2, no_friction=None, belief_engineering_calculation=None)

Bases: ThermalBuildings

Class AgentBuildings represents thermal dynamic building stock.

Parameters:

• stock (Series) – Building stock.

• surface (Series) – Surface by dwelling type.

• ratio_surface (dict) – Losses area of each envelop component

• efficiency (Series) – Heating system efficiency.

• income (Series) – Average income value by income class.

• consumption_ini (Series) – Initial energy consumption by dwelling type.

• preferences (dict) – Preferences parameters.

• performance_insulation (dict) – Performance insulation parameters.

• path (str, optional) – Path to save results.

• year (int, default: 2018) – Year of the stock.

• demolition_rate (float, default 0.0) – Demolition rate.

• endogenous (bool, default True) – Enable to calculate endogenous renovation.

• number_exogenous (float or int, default 300000) – Number of exogenous renovation.

• expected_utility ({'market_share', 'max}) –

• logger (default) –

• calib_scale (bool, default True) –

• full_output (None) –

• quintiles (bool or None, default None) –

• financing_cost (bool, default True) –

• rational_behavior_insulation (bool, default None) –

• rational_behavior_heater (bool, default None) –

• resources_data (dict, default None) –

• detailed_output (bool, default True) –

• figures (dict, default None) –

add_attribute(df, levels)

add_flows(flows)

Update stock attribute by adding flow series.

Parameters:

flows (Series, list) –

static add_level(df, ref, level)

Add level to df respecting ref distribution.

Parameters:

• df –

• ref –

• level –

apply_scale(scale, gest='insulation')

apply_subsidies_heater(index, policies_heater, cost_heater, consumption_saved, emission_saved, bill_saved)

Calculate subsidies for each dwelling and each heating system.

Parameters:

• index (Index or MultiIndex) –

• policies_heater (list) –

• cost_heater (DataFrame) –

• consumption_saved (DataFrame) –

• emission_saved (DataFrame) –

apply_subsidies_insulation(index, policies_insulation, cost_insulation, surface, certificate, certificate_before, certificate_before_heater, energy_saved_3uses, consumption_saved, carbon_content, calculate_condition=True, health_cost_saved=None, bill_saved=None)

Calculate subsidies amount for each possible insulation choice.

Parameters:

• index –

• policies_insulation (list) –

• cost_insulation (DataFrame) – Cost for each segment and each possible insulation choice (€).

• surface (Series) – Surface / dwelling for each segment (m2/dwelling).

• certificate (DataFrame) – Certificate by segment after insulation replacement for each possible insulation choice.

• certificate_before (Series) – Certificate by segment before insulation (but after heater replacement)

• certificate_before_heater (Series) – Certificate by segment before insulation, and before heater replacement. Useful to calculate the total number of upgrade this year.

• energy_saved_3uses (DataFrame) – Primary conventional energy consumption saved by the insulation work (% - kWh PE/m2).

• consumption_saved (kWh) –

Returns:

• cost_insulation (DataFrame)

• vat_insulation (DataFrame)

• tax (float)

• subsidies_details (dict)

• subsidies_total (DataFrame)

• condition (dict)

• eligible (dict)

calculate_distortion_heater(stock, cost_heater, emission_saved, carbon_value, bill_saved, cap=True)

calculate_distortion_insulation(index, stock, cost_insulation, consumption_saved, health_cost_saved, bill_saved, carbon_value, cap=True)

Calculate distortion amount for each possible insulation choice.

calculate_financing(cost, subsidies, financing_cost, policies=None)

Apply financing cost.

Parameters:

• cost –

• subsidies –

• financing_cost –

• policies (list) –

Returns:

• cost_total

• cost_financing

• amount_debt

• amount_saving

• discount

• subsidies

calculate_health_cost_saved(stock, health_cost)

calculate_renovation(prices, cost_insulation, cost_heater, carbon_content, health_cost=None, carbon_value=50)

Calculate the economics renovation of the building stock.

Parameters:

• prices (Series) – Energy prices.

• cost_insulation (Series) – Cost of insulation measures.

• cost_heater (Series) – Cost of heater measures.

• carbon_content (Series) – Carbon content of energy carriers.

• health_cost (Series) – Health cost of energy carriers.

• carbon_value (float) – Carbon value.

calibration_exogenous(coefficient_global=None, coefficient_backup=None, constant_heater=None, scale_heater=None, constant_insulation_intensive=None, constant_insulation_extensive=None, scale_insulation=None, energy_prices=None, rational_hidden_cost=None, number_firms_insulation=None, number_firms_heater=None, hi_threshold=None)

Function calibrating buildings object with exogenous data.

Parameters:

• coefficient_global (float) –

• coefficient_backup (Series) –

• constant_heater (Series) –

• scale_heater (float) –

• constant_insulation_intensive (Series) –

• constant_insulation_extensive (Series) –

• scale_insulation (float) –

• energy_prices (Series) – Energy prices for year y. Index are energy carriers {‘Electricity’, ‘Natural gas’, ‘Oil fuel’, ‘Wood fuel’}.

• rational_hidden_cost –

credit_constraint(amount_debt, financing_cost, bill_saved=None)

endogenous_market_share_heater(index, _bill_saved, _subsidies_total, _cost_heater, calib_heater=None, _cost_financing=None, condition=None, flow_replace=None, drop_heater=None, _credit_constraint=None)

endogenous_renovation(stock, bill_saved, subsidies_total, cost_insulation, frequency_insulation, policies_insulation, calib_renovation=None, min_performance=None, subsidies_details=None, cost_financing=None, supply=None, credit_constraint=None, health_cost_saved=None)

Calculate endogenous retrofit based on discrete choice model.

Utility variables are investment cost, energy bill saving, and subsidies. Preferences are object attributes defined initially.

# bill saved calculated based on the new heating system # certificate before work and so subsidies before the new heating system

Parameters:

• stock (Series, default None) –

• bill_saved (DataFrame) –

• subsidies_total (DataFrame) –

• cost_insulation (DataFrame) –

• frequency_insulation (float or int) –

• stock –

• calib_renovation (dict, optional) –

• min_performance (str, optional) –

• subsidies_details (dict, optional) –

• cost_financing (DataFrame, optional) –

• supply (DataFrame, optional) –

• credit_constraint (float, optional) –

Returns:

• Series – Retrofit rate

• DataFrame – Market-share insulation

• DataFrame – Utility insulation

• Series – Consumer surplus

exogenous_market_share_heater(index, choice_heater_idx)

Define exogenous market-share.

Market-share is defined by _market_share_exogenous attribute.

Parameters:

• index (MultiIndex or Index) –

• choice_heater_idx (Index) –

Returns:

• DataFrame – Market-share by segment and possible heater choice.

• Series – Probability replacement.

exogenous_renovation(stock, condition)

Format retrofit rate and market share for each segment.

Global retrofit and retrofit rate to match exogenous numbers. Retrofit all heating system replacement dwelling.

Parameters:

• stock (Series) –

• condition (dict) –

Returns:

• Series – Retrofit rate by segment.

• DataFrame – Market-share by segment and insulation choice.

static find_best_option(criteria, dict_df=None, func='max')

Find best option (columns), and returns

Parameters:

• criteria (DataFrame) – Find for each index the column based on criteria values.

• dict_df (dict) – Dataframe to return.

• func –

Return type:

DataFrame

flow_demolition(demolition_rate, step=1)

Demolition of E, F and G buildings based on their share in the mobile stock.

Return type:

Series

flow_obligation(policies_insulation, prices, cost_insulation, financing_cost=None, frequency_insulation=1, health_cost=None, default_quality=None)

Account for flow obligation if defined in policies_insulation.

Parameters:

• policies_insulation (list) – Check if obligation.

• prices (Series) –

• cost_insulation (Series) –

• financing_cost (dict, optional) –

• frequency_insulation (float or int, default 1) –

• health_cost (Series, optional) –

Returns:

flow_obligation

Return type:

Series

flow_retrofit(prices, cost_heater, cost_insulation, frequency_insulation, policies_heater=None, policies_insulation=None, calib_heater=None, district_heating=None, financing_cost=None, calib_renovation=None, step=1, exogenous_social=None, premature_replacement=None, prices_before=None, supply=None, carbon_value_kwh=None, carbon_value=None, bill_rebate=0, carbon_content=None, health_cost=None, default_quality=None, credit_constraint=True)

Compute heater replacement and insulation retrofit.

1. Heater replacement based on current stock segment.

2. Knowing heater replacement (and new heating system) calculating retrofit rate by segment and market share by segment.

3. Then, managing inflow and outflow.

Parameters:

• prices (Series) –

• cost_heater (Series) –

• calib_heater (DataFrame) –

• cost_insulation –

• policies_heater (list) – Policies for heating system.

• policies_insulation (list) – Policies for insulation.

• financing_cost (optional, dict) –

• calib_renovation (dict, optional) –

Return type:

Series

frame_to_flow(replaced_by, default_quality=None)

Transform insulation transition Dataframe to flow.

Parameters:

replaced_by (DataFrame) –

Returns:

replaced_by – Flow Series.

Return type:

Series

health_cost(health_cost_dpe, health_cost_income, prices, stock=None, method_health_cost=None)

heater_replacement(stock, prices, cost_heater, policies_heater, calib_heater=None, step=1, financing_cost=None, district_heating=None, premature_replacement=None, prices_before=None, supply=None, store_information=True, bill_rebate=0, carbon_content=None, carbon_value=None, credit_constraint=True)

Function returns building stock updated after switching heating system.

Parameters:

• stock (Series) –

• prices (Series) –

• cost_heater (Series) –

• calib_heater (DataFrame, optional) –

• policies_heater (list) –

• calib_heater –

• step (int, optional) –

• financing_cost (dict, optional) –

• district_heating (Series, optional) –

• premature_replacement (Series, optional) –

• prices_before (Series, optional) –

• supply (Series, optional) –

• store_information (bool, optional) –

• carbon_content (Series, optional) –

• carbon_value (float, optional) –

• bill_rebate (float, optional) –

Return type:

Series

insulation_replacement(stock_ini, prices, cost_insulation_raw, frequency_insulation, policies_insulation=None, financing_cost=None, calib_renovation=None, min_performance=None, exogenous_social=None, prices_before=None, supply=None, carbon_value=None, carbon_content=None, calculate_condition=True, bill_rebate=0, credit_constraint=True, health_cost=None, default_quality=None)

Calculate insulation retrofit in the dwelling stock.

1. Intensive margin

2. Extensive margin

Calibrate function first year.

Consumption saving only depends on insulation work. However, certificate upgrade also consider if heating system have switched.

To reduce calculation time, we reduce the number of combination by grouping. Cost, subsidies and constant depends on Housing type, Occupancy status, Housing type and Insulation performance.

Parameters:

• stock_ini (Series) –

• prices (Series) –

• cost_insulation_raw (Series) – €/m2 of losses area by component.

• policies_insulation (list, optional) –

• frequency_insulation (float or int) –

• financing_cost (dict, optional) –

• calib_renovation (dict, optional) –

• min_performance (str, optional) –

• exogenous_social (DataFrame, optional) –

• prices_before (Series; optional) –

• supply (dict, optional) –

• carbon_value (float, optional) –

• carbon_content (float, optional) –

• calculate_condition (bool, optional) –

• bill_rebate (float, optional) –

• credit_constraint (bool, optional) –

Returns:

• Series – Retrofit rate

• DataFrame – Market-share insulation

make_static_analysis(cost_insulation, cost_heater, prices, health_cost, carbon_content, path_out=None, carbon_value=50, selected_options=None, sufix='', social_discount_rate=0.05, private_discount_rate=0.05, lifetime=25, make_plot=False, cost_failures=None, cost_failures_landlords=None, cost_failures_multi=None, income=None, duration_loan=10)

parse_output_consumption(prices, bill_rebate=0)

parse_output_run(prices, inputs, climate=None, step=1, taxes=None, lifetime_insulation=30, social_discount_rate=0.032, bill_rebate=0, coefficient_public_funding=0.2, duration_financing=10, discount_financing=0.05)

Parse output.

Renovation : envelope Retrofit : envelope and/or heating system

Parameters:

• prices (Series) – Energy prices

• inputs (dict) – Exogenous data for post-treatment.

• climate (int, optional) –

• step (int, optional) –

• taxes (list, optional) –

• lifetime_insulation (int, optional) –

• social_discount_rate (float, default 0.032) –

• bill_rebate (float, optional) –

• coefficient_public_funding (float, default 0.2) –

• duration_financing (int, default 10) –

• discount_financing (float, default 0.05) –

Return type:

dict

parse_output_run_cba(prices, inputs, step=1, taxes=None, bill_rebate=0)

static prepare_abatement_plot(rslt_efficiency, rslt_efficiency_carbon, rslt_npv=None, rslt_roi=None)

prepare_consumption(choice_insulation=None, performance_insulation=None, index=None, method_epc='5uses', level_heater='Heating system', full_output=True, store=True, climate=None, default_quality=None)

Standard energy consumption and energy performance certificate for each renovation works option.

Standard energy consumption only depends on building characteristics.

Parameters:

• choice_insulation (MultiIndex) – Insulation choice.

• performance_insulation (MultiIndex) – Insulation performance.

• index (MultiIndex) – Index to calculate consumption.

• method_epc ({'3uses', '5uses'}) – Method to calculate energy performance certificate.

• level_heater (str) – Heating system level to calculate the consumption.

• full_output (bool, default True) – Enable to return full output.

• store (bool, default True) – Enable to store results.

• climate (int) – Climate year.

Returns:

• DataFrame – Final consumption standard.

• DataFrame – Primary consumption standard 3 uses.

• DataFrame – Energy performance certificate.

prepare_cost_insulation(cost_insulation)

Constitute insulation choice set cost. Cost is equal to the sum of each individual cost component.

Parameters:

cost_insulation (Series) –

Returns:

Multiindex series. Levels are Wall, Floor, Roof and Windows and values are boolean.

Return type:

Series

prepare_subsidy_insulation(subsidies_insulation, policy=None)

Constitute insulation choice set subsidies. Subsidies are equal to the sum of each individual subsidy.

Parameters:

• policy –

• subsidies_insulation (DataFrame) –

Returns:

Multiindex columns. Levels are Wall, Floor, Roof and Windows and values are boolean.

Return type:

DataFrame

remove_calibration()

static select_deep_renovation(certificate_after)

Select deep renovation.

Parameters:

certificate_after (DataFrame) – Certificate after renovation.

Return type:

DataFrame

select_renovation_option(consumption_saved, emission_saved, cost_investment, stock, bill_saved, certificate_after, carbon_saved=None, health_cost_saved=None, lifetime=30, discount_rate=0.05, measures='deep_renovation', include_energy=True, include_carbon=False, include_health=False, include_failures=False, cost_failures=None, include_failures_landlords=False, cost_failures_landlords=None, include_failures_multi=False, cost_failures_multi=None, include_credit_constraint=None, income=None, ratio_threshold=0.05, duration_loan=10)

Select renovation option based on measures.

Parameters:

• consumption_saved (Series) – Energy consumption saved by renovation measures.

• emission_saved (Series) – Emission saved by renovation measures.

• cost_investment (Series) – Cost of insulation measures.

• stock (Series) – Stock of buildings.

• certificate_after (Series) – Energy performance certificate after renovation measures.

• lifetime (int, default 30) – Lifetime of insulation measures.

• discount_rate (float, default 0.05) – Discount rate.

• measures (str, default 'deep_renovation') – Type of insulation measures.

• carbon_saved (Series, default None) – Carbon saved by renovation measures.

• bill_saved (Series, default None) – Bill saved by renovation measures.

• health_cost_saved (Series, default None) – Health cost saved by renovation measures.

• include_energy (bool, default True) – Include energy in the calculation of indicators.

• include_carbon (bool, default False) – Include carbon in the calculation of indicators.

• include_health (bool, default False) – Include health in the calculation of indicators.

store_information_heater(cost_heater, subsidies_total, bill_saved, subsidies_details, replacement, vat_heater, cost_financing, amount_debt, amount_saving, discount, consumption_saved, consumption_before, consumption_no_rebound, consumption_actual, epc_upgrade, flow_premature_replacement, subsidies_loan, eligible, hidden_benefits_heater)

Store information yearly heater replacement.

Parameters:

• cost_heater (DataFrame) – Cost of each heating system (EUR).

• subsidies_total (DataFrame) – Total amount of eligible subsidies by dwelling and heating system (EUR).

• subsidies_details (dict) – Amount of eligible subsidies by dwelling and heating system (EUR).

• replacement (Series) – Dwelling updated with a new heating system.

• vat_heater (Series) – vat tax of each heating system (EUR).

• flow_premature_replacement (int) – Number of dwelling that replace their heating system before the end of its lifetime.

• cost_financing (DataFrame) – Cost of financing by dwelling (EUR).

• amount_debt (DataFrame) – Amount of debt by dwelling and income owner (EUR).

• amount_saving (DataFrame) – Amount of saving by dwelling and income owner (EUR).

• discount (float) – Discount rate.

• consumption_saved (DataFrame) – Consumption saved by dwelling and heating system (kWh).

• consumption_before (DataFrame) – Consumption before replacement by dwelling and heating system (kWh).

• consumption_no_rebound (DataFrame) – Consumption after replacement without rebound effect by dwelling and heating system (kWh).

• consumption_actual (DataFrame) – Consumption after replacement with rebound effect by dwelling and heating system (kWh).

• epc_upgrade (DataFrame) – Jump in EPC by dwelling and heating system (EPC).

• subsidies_loan (DataFrame) – Amount of eligible subsidies by dwelling and heating system (EUR).

Return type:

None

store_information_insulation(condition, cost_insulation_raw, tax, cost_insulation, cost_financing, vat_insulation, subsidies_details, subsidies_total, consumption_saved, consumption_saved_actual, consumption_saved_no_rebound, amount_debt, amount_saving, discount, subsidies_loan, eligible)

Store insulation information.

Information are post-treated to weight by the number of replacement.

Parameters:

• condition (dict) –

• cost_insulation_raw (Series) – Cost of insulation for each envelope component of losses surface (€/m2).

• tax (float) – vat to apply (%).

• cost_insulation (DataFrame) – Cost total for each dwelling and each insulation gesture (€). Financing cost included.

• cost_financing (DataFrame) – Financing cost for each dwelling and each insulation gesture (€).

• vat_insulation (DataFrame) – vat applied to each insulation gesture cost (€).

• subsidies_details (dict) – Amount of subsidies for each dwelling and each insulation gesture (€).

• subsidies_total (DataFrame) – Total mount of subsidies for each dwelling and each insulation gesture (€).

• consumption_saved (DataFrame) –

• consumption_saved_actual (DataFrame) –

• consumption_saved_no_rebound (DataFrame) –

• amount_debt (Series) –

• amount_saving (Series) –

• discount (Series) –

• subsidies_loan –

static sum_by_insulation_type(df)

static to_cumac(consumption_saved, discount=0.035, duration=30)

weighted_average(df, weights, levels=None, technology='insulation')

property year

class project.building.ThermalBuildings(stock, surface, ratio_surface, efficiency, income, path=None, year=2018, resources_data=None, detailed_output=None, figures=None, residual_rate=0, temp_sink=None)

Bases: object

ThermalBuildings classes.

Parameters:

• stock (Series) – Building stock.

• surface (Series) – Surface by dwelling type.

• ratio_surface (dict) – Losses area of each envelop component

• efficiency (Series) – Heating system efficiency.

• income (Series) – Average income value by income class.

• consumption_ini (Series) – Initial energy consumption.

• path (str, optional) –

• year (int, default: 2018) –

add_certificate(df)

Add energy performance certificate to df index.

Parameters:

df –

add_energy(df)

apply_calibration(consumption, level_heater='Heating system', agg='energy')

calibration_consumption(prices, consumption_ini, health_cost_income, health_cost_dpe, climate=None)

Calculate energy indicators.

Parameters:

• prices (Series) –

• consumption_ini (Series) –

• climate –

consumption_actual(prices, consumption=None, full_output=False, bill_rebate=0)

Space heating consumption based on standard space heating consumption and heating intensity (kWh/building.a).

Space heating consumption is in kWh/building.y Equation is based on Allibe (2012).

Parameters:

• prices (Series) –

• consumption (Series or None, optional) – kWh/building.a

• full_output (bool, default False) –

• bill_rebate (float, default 0) –

Return type:

Series

consumption_agg(prices=None, freq='year', climate=None, smooth=False, standard=False, efficiency_hour=False, existing=False, agg='all', bill_rebate=0, hourly_profile=None)

Aggregated final energy consumption (TWh final energy).

Parameters:

• prices (Series) – Energy prices.

• freq –

• climate –

• smooth –

• standard (bool, default False) – If yes, consumption standard (conventional). Otherwise, consumption actual.

• efficiency_hour (bool, default False) –

• existing (bool, default False) – If yes, calculate consumption only for existing buildings.

• agg ({'all', 'energy', 'heater'}, default 'all') – Aggregation level.

• bill_rebate (float, default 0) –

• hourly_profile (DataFrame, optional) –

Return type:

float or Series

consumption_heating(index=None, freq='year', climate=None, smooth=False, full_output=False, efficiency_hour=False, level_heater='Heating system', method='5uses', hourly_profile=None, temp_sink=None)

Calculation consumption standard of the current building stock [kWh/m2.a].

Parameters:

• index –

• freq –

• climate –

• smooth –

• full_output (bool, default False) –

• efficiency_hour –

• level_heater ({'Heating system', 'Heating system final'}) –

consumption_heating_store(index, level_heater='Heating system', full_output=True)

Pre-calculate space energy consumption based only on relevant levels.

Climate should be None. Consumption is stored for later use, so climate cannot change calculation.

Parameters:

• index (MultiIndex, Index) – Used to estimate consumption standard.

• level_heater ({'Heating system', 'Heating system final'}, default 'Heating system') –

• unit –

• full_output (bool, default True) –

static energy_bill(prices, consumption, level_heater='Heating system', bill_rebate=0)

Calculate energy bill by dwelling for each stock segment (€/dwelling.a).

Parameters:

• prices (Series or DataFrame or float) – Energy prices for year (€/kWh)

• consumption (Series) – Energy consumption by dwelling (kWh/dwelling.a)

• level_heater – Heating system level to calculate the bill. Enable to calculate energy bill before or after change of heating system.

• bill_rebate (float or Series, default 0) – Bill rebate (€/dwelling.a)

Returns:

Energy bill by dwelling for each stock segment (€/dwelling)

Return type:

Series

property income

need_heating(climate=2006, smooth=False, freq='year', hourly_profile=None, unit='kWh/y')

Calculate heating need of the current building stock.

Return type:

DataFrame

optimal_temperature(prices)

Find indoor temperature based on energy prices, housing performance and income level.

Parameters:

prices (Series) – Energy prices.

simplified_stock(energy_level=False)

Return simplified stock.

Parameters:

energy_level –

Returns:

Simplified stock.

Return type:

Series

size_heater(index=None)

property stock

store_consumption(prices, carbon_content, bill_rebate=0)

Store energy consumption.

Useful to calculate energy saving and rebound effect.

Parameters:

• prices –

• carbon_content –

• bill_rebate –

static to_emission(df, emission)

static to_energy(df, level_heater='Heating system')

to_heating_intensity(index, prices, consumption=None, level_heater='Heating system', bill_rebate=0, full_output=False, rho=5)

Calculate heating intensity of index based on energy prices.

Parameters:

• index (MultiIndex or Index) –

• prices (Series) –

• consumption (Series, default None) –

• level_heater ({'Heating system', 'Heating system final'}) –

• bill_rebate (float or Series, default 0) –

Returns:

Heating intensity

Return type:

Series

to_thermal_comfort(heating_intensity, rho=5)

property year