API reference

The API reference gives an overview of Res-IRF implementation.

  • Buildings module details implementation of HousingStock class.

  • Policies module presents implementation of PublicPolicies class.

Buildings

class buildings.HousingStock(stock, attributes_values, year=2018, attributes2area=None, attributes2horizon=None, attributes2discount=None, attributes2income=None, attributes2consumption=None, price_behavior='myopic', kwh_cumac_transition=None)

Multi-attributes, dynamic housing stock.

HousingStock contains multiple agents. An agent is defined as the combination of a building, an owner and a tenant. Specific agent behavior are declared as method.

add_flow(flow)

Add flow to stock attribute object.

Parameters

flow (pd.Series) – Attributes indexed flow to be added to stock.

static add_tenant_income(building_stock, tenant_income)

Add Income class level to stock using information of tenant income.

Homeowners and social-housing tenant and owner income class are the same.

Parameters

  • building_stock (pd.Series) –

  • tenant_income (pd.Series) –

Returns

Return type

pd.Series

calibration_market_share(energy_prices, market_share_ini, cost_invest=None, consumption='conventional', subsidies=None, option=0)

Calculate intangible costs by calibrating market_share.

Solving the equations system: Intangible costs are calibrated so that the life-cycle cost model, fed with the investment costs, matches the observed market shares in the initial year. However, infinite sets of intangible costs can be found to reproduce the relative market shares. In other words the equation system is under-determined and must be solved with an additional condition. Accordingly, intangible costs are calibrated by incorporating one equation controlling for λ, the ratio of average intangible costs over average life cycle costs. Parameter λ is set as the minimum value for which the system can be solved from 0.15 to 0.6 (exogenous limits). The equation system is independent per agent and should solve for a given lambda per agent. Another constraint imposes that the agents sharing the same initial performance state find the same lambda.

From aggregated observed market share to agent-based: Intangible costs could be calculated for every agent as LCC depends on every attributes. However, the observed market share represents the average values over Energy performance initial and final dimensions. Function defined various way to solve this representation issue:

  • Option 0: Each agent got its own intangible costs to match the observed market share. Regardless of the technical and behavioral characteristics of the agents, their market share will be identical as long as they start and end at the same level of energy performance.

  • Option 1: Intangible cost is aggregated to reflect the average initial market share. Each agents group share the same intangible costs to match the observed market share. It shows diversity among agents initial market share to reflect different technical and behavioral characteristics. Concretely the aggregation of the data is done by a weighted average of the distribution of the households.

  • Option 2: Intangible cost are aggregated over the Heating energy dimension thanks a representative agent of all heating energy. This solution has been implemented to match previous version of Res-IRF.

  • Not implemented: another way would be to calibrate the intangible cost by calculating life-cycle cost for a representative agent.

Parameters

  • energy_prices (pd.DataFrame) –

  • market_share_ini (pd.DataFrame) – Observed market share to match during calibration_year.

  • cost_invest (dict, optional) –

  • consumption ({'conventional', 'actual'}, default 'conventional') –

  • subsidies (list, optional) – subsidies to consider in the market share

  • option ({0, 1, 2}, default 0) –

    0: intangible cost is segmented by agent

    Each agent got its own intangible costs to match the observed market share.

    1: intangible cost is aggregated based on initial market share attributes

    Each agents group share intangible costs to match the observed market share. This option allows some diversity in the calculated market share between member of each group.

    2: intangible cost is aggregated on heating energy level

    Used in Res-IRF 3.0

Returns

  • pd.DataFrame – Intangible cost

  • pd.DataFrame – Market share calculated and observed

static data2area(l2area, ds_seg)

Multiply unitary measured data by surface data.

Parameters

  • l2area (pd.Series) – Attributes indexed data surface.

  • ds_seg (pd.Series or pd.DataFrame) – Attributes indexed data to be multiplied by data area.

Returns

Return type

pd.Series or pd.DataFrame

energy_expenditure(energy_price)

Calculate total energy expenditure (€) by agent for current year.

€ = €/kWh x kWh/m2 x m2/building x buildings

Parameters

energy_price (pd.Series or pd.DataFrame) –

Returns

Total energy expenditure by agent.

Return type

pd.Series

static information_acceleration(knowledge, cost_intangible, share, learning_rate)

Decrease intangible cost to capture peer effects and knowledge diffusion.

Intangible renovation costs decrease according to a logistic curve with the same cumulative production so as to capture peer effects and knowledge diffusion. The rate of decrease (learning_rate) is set at 25% of non-fixed share for a doubling of cumulative production.

Res-IRF splits intangible costs into a fixed share share mimicking hidden costs, and a variable share 1−`share` mimicking adoption externalities. Note that the value of share is fraught with uncertainty, due to the upstream problem of empirically separating the different types of barriers.

Parameters

  • knowledge (pd.Series) – Knowledge indexes should match cost columns.

  • cost_intangible (pd.DataFrame) –

  • share (float) – Share of fixed intangible costs.

  • learning_rate (float) – Rate of decrease of non-fixed share for a doubling of cumulative production.

Returns

cost_intangible

Return type

pd.DataFrame

static information_rate(knowledge, learning_rate, share)

Returns information rate that capture peer effects and knowledge diffusion.

More info_rate is high, more intangible_cost are low. Intangible renovation costs decrease according to a logistic curve with the same cumulative production so as to capture peer effects and knowledge diffusion. intangible_cost[yr] = intangible_cost[calibration_year] * info_rate with info rate [1-info_rate_max ; 1] This function calibrate a logistic function, so rate of decrease is set at 25% for a doubling of cumulative production.

Parameters

  • knowledge (pd.Series) – Knowledge indexes match cost columns to reach final state after transition.

  • share (float) – Share of non-fixed costs.

  • learning_rate (float) – Rate of decrease of non-fixed share for a doubling of cumulative production.

Returns

Return type

pd.Series

ini_energy_cash_flows(energy_price)

Initialize exogenous variable that doesn’t depend on dynamic to fasten the script.

For instance budget_share only depends on energy_price, and income that are exogenous variables. So does, heating_intensity and consumption_actual.

List of attribute initialized by launching self.to_consumption_actual(energy_price):

  • buildings.area: pd.Series (doesn’t depend on time)

  • buildings.budget_share: pd.DataFrame (depends on energy_price and income so depend on time)

  • buildings.heating_intensity: pd.DataFrame (depends on energy_price and income so depend on time)

  • buildings.consumption_conventional: pd.Series (doesn’t depend on time)

  • buildings.consumption_actual: pd.DataFrame (depends on energy_price and income so depend on time)

  • buildings.energy_cash_flows[‘conventional’]: pd.DataFrame

  • buildings.energy_cash_flows_disc[‘conventional’]: pd.DataFrame

  • buildings.energy_cash_flows[‘actual’]: pd.DataFrame

  • buildings.energy_cash_flows_disc[‘actual’]: pd.DataFrame

Parameters

energy_price (pd.DataFrame) –

static initial2final(ds, idx_full, transition)

Catch final state agent values as the initial state of another agent.

When a segment final state match another segment initial state, it’s therefore fasten to directly catch the value.

Parameters

  • ds (pd.Series) – Data to pick values

  • idx_full (pd.MultiIndex) – Corresponds to final state data index

  • transition (list) –

Returns

Return type

pd.Series

static lcc2market_share(lcc_df, nu=8.0)

Returns market share for each segment based on lcc_df.

Parameters

  • lcc_df (pd.DataFrame or pd.Series) –

  • nu (float, optional) –

Returns

Return type

pd.Series, or pd.DataFrame

static learning_by_doing(knowledge, cost, learning_rate, cost_lim=None)

Decrease capital cost after considering learning-by-doing effect.

Investment costs decrease exponentially with the cumulative sum of operations so as to capture a “learning-by-doing” process. The rate of cost reduction is set at 15% in new construction and 10% in renovation for a doubling of production.

Parameters

  • knowledge (pd.Series) – knowledge indexes match cost columns to reach final state after transition

  • cost (pd.DataFrame) –

  • learning_rate (float) –

  • cost_lim (optional, pd.DataFrame) –

Returns

Return type

pd.DataFrame

static mul_consumption(consumption, mul_df, option='initial')

Multiply any pd.DataFrame to consumption.

Parameters

  • consumption (pd.DataFrame or pd.Series) –

  • mul_df (pd.DataFrame or pd.Series) –

  • option (str, {'initial', 'final'}, default 'initial') –

Returns

Return type

pd.DataFrame or pd.Series

to_area(scenario=None, segments=None)

Returns area by agent.

Parameters

  • segments (pd.MultiIndex, optional) – Indexed used to reindex data. Default building stock indexes.

  • scenario (str, optional) – Scenario needs to be specified if attributes2income is a dictionary.

Returns

Area by agent.

Return type

pd.Series

to_consumption(consumption, segments=None, energy_prices=None)

Returns conventional or actual energy consumption.

Parameters

  • consumption (str, {'conventional', 'actual'}) –

  • segments (pd.Index, optional) – If segments is not filled, use self.segments.

  • energy_prices (pd.DataFrame, optional) –

Returns

Conventional or actual energy consumption.

Return type

pd.Series or pd.DataFrame

to_consumption_actual(energy_prices, detailed_output=False, segments=None)

Returns actual energy consumption by agent and years.

A growing number of academic studies point to a gap between the conventional energy consumption predicted by energy performance certificates and actual energy consumption. The most common explanation is a more intense heating of the heating infrastructure after an energy efficiency improvement – a phenomenon commonly referred to as the “rebound effect.”

Heating Intensity = -0.191 * log(Income Share) + 0.1105

Parameters

  • energy_prices (pd.DataFrame) –

  • detailed_output (boolean, default False) –

  • segments (pd.Index, optional) – Indexed used to reindex data. Default building stock indexes.

Returns

Actual energy consumption by agent and years.

Return type

pd.DataFrame

to_consumption_conventional(scenario=None, segments=None)

Returns conventional energy consumption by agent.

Parameters

  • segments (pd.MultiIndex, optional) – Indexed used to reindex data. Default building stock indexes.

  • scenario (str, optional) – Scenario needs to be specified if attributes2income is a dictionary.

Returns

Conventional energy consumption by agent.

Return type

pd.Series

to_consumption_final(consumption='conventional', transition=None)

Returns conventional or actual energy consumption by agent for all possible final state.

Parameters

  • consumption (str, {'conventional', 'actual'}) –

  • list (transition) – Transition defined possible final states.

  • ['Energy performance' (default) – Transition defined possible final states.

  • energy'] ('Heating) – Transition defined possible final states.

Returns

Conventional or actual energy consumption by agent and

Return type

pd.Series or pd.DataFrame

to_discount_factor(scenario_horizon=None, scenario_discount=None, segments=None)

Calculate discount factor by agent.

Discount factor can be used when agents doesn’t anticipate prices evolution. Discount factor does not depend on the year it is calculated.

Returns

Discount factor by agent

Return type

pd.Series

to_discount_rate(scenario=None, segments=None)

Returns discount rate by agent.

Parameters

  • segments (pd.MultiIndex, optional) – Indexed used to reindex data. Default building stock indexes.

  • scenario (str, optional) – Scenario needs to be specified if attributes2income is a dictionary.

Returns

Discount rate by agent.

Return type

pd.Series

static to_discounted(df, rate)

Returns discounted DataFrame from DataFrame and discount rate.

Parameters

  • df (pd.DataFrame) – Time series data by agent. Agents are in row and years in columns.

  • rate (float or pd.Series) – Discount rate constant or by agent.

Returns

Discounted data. Agents are in row and years in columns.

Return type

pd.DataFrame

to_emission_saving(co2_content, transition=None, consumption='conventional', energy_prices=None)

Calculate emission saving by agent between initial and all possible final state.

Parameters

  • co2_content (pd.DataFrame) –

  • transition ((Energy performance, ), (Heating energy, ), (Energy performance, Heating energy)) – Transition defined possible final states.

  • consumption ({'conventional', 'actual'}) –

  • energy_prices (pd.DataFrame) –

Returns

Conventional or actual energy saving by agent.

Return type

pd.Series or pd.DataFrame

to_emission_saving_lc(co2_content, transition=None, consumption='conventional', horizon=30, discount=0.04, energy_prices=None)

Calculate life-cycle emission saving between initial and final state for the entire project duration.

Parameters

  • co2_content (pd.DataFrame) –

  • transition ((Energy performance, ), (Heating energy, ), (Energy performance, Heating energy)) – Transition defined possible final states.

  • consumption ({'conventional', 'actual'}) –

  • horizon (int, default 30) –

  • discount (float, default 0.04) –

  • energy_prices (pd.DataFrame) –

Returns

Conventional or actual emission saving by agent.

Return type

pd.Series or pd.DataFrame

to_energy_lcc(energy_prices, transition=None, consumption='conventional', segments=None)

Return energy-life-cycle-cost discounted by agents, and energy prices.

Energy LCC is calculated on an agent-specific horizon, and discount rate. Time horizon depends on transition (transition defined the investment horizon).

Parameters

  • energy_prices (pd.DataFrame) –

  • transition (list, default ['Energy performance']) –

  • consumption (str, {'conventional', 'actual}, default 'conventional') –

  • segments (pd.MultiIndex, optional) –

Returns

Energy-life-cycle-cost discounted by agents.

Return type

pd.Series

to_energy_lcc_final(energy_prices, transition=None, consumption='conventional', segments=None)

Calculate energy life-cycle cost based on transition.

Parameters

  • energy_prices (pd.DataFrame) –

  • transition ((Energy performance, ), (Heating energy, ), (Energy performance, Heating energy)) – Transition defined possible final states.

  • consumption ({'conventional', 'actual'}) –

  • segments (pd.Index, optional) – Use self.segments if input is not filled.

Returns

Return type

pd.Series, or pd.DataFrame

to_energy_saving(transition=None, consumption='conventional')

Calculate energy saving by agent between initial and all possible final state.

Parameters

  • transition (list, default ['Energy performance', 'Heating energy']) – Transition defined possible final states.

  • consumption (str, {'conventional', 'actual'}) –

Returns

Conventional or actual energy saving by agent.

Return type

pd.Series or pd.DataFrame

to_energy_saving_lc(transition=None, consumption='conventional', discount=0.04)

Calculate life-cycle energy saving between initial and all possible final state for the entire project duration.

Parameters

  • transition ((Energy performance, ), (Heating energy, ), (Energy performance, Heating energy)) – Transition defined possible final states.

  • consumption ({'conventional', 'actual'}) –

  • discount (float, default 0.04) –

Returns

Return type

pd.DataFrame

to_final(ds, transition=None, segments=None)

Returns final state value index by columns and by initial state agent.

For transition attributes, initial state doesn’t influence results.

Parameters

  • ds (pd.Series) –

  • transition (list, default ['Energy performance', 'Heating energy']) –

  • segments (pd.Index, optional) – Use self.segments if input is not filled.

Returns

Return type

pd.DataFrame

to_horizon(scenario=None, segments=None)

Returns investment horizon by agent.

Parameters

  • segments (pd.MultiIndex, optional) – Indexed used to reindex data. Default building stock indexes.

  • scenario (str, optional) – Scenario needs to be specified if attributes2income is a dictionary.

Returns

Investment horizon by agent.

Return type

pd.Series

to_income(scenario=None, segments=None)

Returns annual income by agent.

Parameters

  • segments (pd.MultiIndex, optional) – Indexed used to reindex data. Default building stock indexes.

  • scenario (str, optional) – Scenario needs to be specified if attributes2income is a dictionary.

Returns

Annual income by agent.

Return type

pd.Series

to_io_share_seg()

Calculate attributes share by income class owner.

Returns

Return type

pd.Series

to_lcc_final(energy_prices, cost_invest=None, cost_intangible=None, transition=None, consumption='conventional', subsidies=None, segments=None, energy_lcc=None)

Calculate life-cycle-cost of home-energy retrofits by agent and for every possible transition.

Parameters

  • energy_prices (pd.DataFrame) – index are heating energy and columns are years.

  • cost_invest (dict, optional) – keys are transition (cost_invest[‘Energy performance’]) and item are pd.DataFrame

  • cost_intangible (dict, optional) – keys are transition (cost_intangible[‘Energy performance’]) and item are pd.DataFrame

  • consumption ({'conventional', 'actual'}, default 'conventional) –

  • transition (list, default ['Energy performance']) – define transition. Transition can be defined as attributes transition, energy transition, or attributes-energy transition.

  • subsidies (list, optional) – list of subsidies object

  • segments (pd.MultiIndex or pd.Index, optional) –

  • energy_lcc (pd.Series, optional) – Allow the user to chose manually an energy_lcc. Otherwise self.to_energy_lcc_final will be launched.

Returns

Life-cycle-cost DataFrame is structured for every initial state (index) to every final state defined by transition (columns).

Return type

pd.DataFrame

to_market_share(energy_prices, transition=None, consumption='conventional', cost_invest=None, cost_intangible=None, subsidies=None, nu=8.0, segments=None)

Returns market share for each segment and each possible final state.

Parameter nu characterizing the heterogeneity of preferences is set to 8 in the model. Intangible costs are calibrated so that the observed market shares are reproduced in the initial year.

Parameters

  • energy_prices (pd.DataFrame) –

  • cost_invest (dict, optional) –

  • cost_intangible (dict, optional) –

  • consumption ({'conventional', 'actual'}, default 'conventional) –

  • transition (list, {['Energy performance'], ['Heating energy'], ['Energy performance', 'Heating energy']},) – default [‘Energy performance’]

  • subsidies (list, optional) – List of subsidies object

  • segments (pd.MultiIndex, optional) –

  • nu (float or int, default 8.0) –

Returns

market_share, lcc_final

Return type

pd.DataFrame

to_market_share_energy(energy_prices, consumption='conventional', cost_invest=None, cost_intangible=None, subsidies=None, nu=8.0, segments=None)

Only used for nested technology transition.

Parameters

  • energy_prices (pd.DataFrame) –

  • cost_invest (dict, optional) –

  • cost_intangible (dict, optional) –

  • consumption ({'conventional', 'actual'}, default 'conventional) –

  • subsidies (list, optional) – List of subsidies object

  • segments (pd.MultiIndex, optional) –

  • nu (float or int, default 8.0) –

to_npv(energy_prices, transition=None, consumption='conventional', cost_invest=None, cost_intangible=None, subsidies=None, nu=8.0)

Calculate net present value of home-energy retrofits by agent.

Parameters

  • energy_prices (pd.DataFrame) – index are heating energy and columns are years.

  • cost_invest (dict, optional) – keys are transition (cost_invest[‘Energy performance’]) and item are pd.DataFrame

  • cost_intangible (dict, optional) – keys are transition (cost_intangible[‘Energy performance’]) and item are pd.DataFrame

  • consumption ({'conventional', 'actual'}, default 'conventional) –

  • transition (list, default ['Energy performance']) – define transition. Transition can be defined as attributes transition, energy transition, or attributes-energy transition.

  • subsidies (list, optional) – list of subsidies object

  • nu (float or int, default 8.0) –

Returns

Net present value is structured by agent.

Return type

pd.Series

to_pv(energy_prices, transition=None, consumption='conventional', cost_invest=None, cost_intangible=None, subsidies=None, nu=8.0)

Calculate present value of home-energy retrofits by agent.

Parameters

  • energy_prices (pd.DataFrame) – index are heating energy and columns are years.

  • cost_invest (dict, optional) – keys are transition (cost_invest[‘Energy performance’]) and item are pd.DataFrame

  • cost_intangible (dict, optional) – keys are transition (cost_intangible[‘Energy performance’]) and item are pd.DataFrame

  • consumption ({'conventional', 'actual'}, default 'conventional) –

  • transition (list, default ['Energy performance']) – define transition. Transition can be defined as attributes transition, energy transition, or attributes-energy transition.

  • subsidies (list, optional) – list of subsidies object

  • nu (float or int, default 8.0) –

Returns

Present value is structured by agent.

Return type

pd.Series

to_stock_area(scenario=None, segments=None)

Returns area (surface) of current building stock by agent.

Parameters

  • segments (pd.MultiIndex, optional) –

  • scenario (str, optional) – Scenario needs to be specified if attributes2area is a dictionary.

Returns

Area by agent.

Return type

pd.Series

static to_summed(df, yr_ini, horizon)

Sum each rows of df from yr_ini to its horizon.

Parameters

  • df (pd.DataFrame) – Agents are in row and years in columns.

  • yr_ini (int) –

  • horizon (pd.Series) – pd.MultiIndex as index

Returns

Return type

pd.Series

to_transition(ds, transition=None)

Returns pd.DataFrame from pd.Series by adding final state as column with same value.

Create a MultiIndex columns when it occurs simultaneous transitions.

Parameters

  • ds (pd.Series, pd.DataFrame) –

  • transition (list, default ['Energy performance']) –

Returns

Return type

pd.DataFrame

class buildings.HousingStockConstructed(stock, attributes_values, year, stock_needed_ts, share_multi_family=None, os_share_ht=None, tenants_income=None, stock_area_existing=None, attributes2area=None, attributes2horizon=None, attributes2discount=None, attributes2income=None, attributes2consumption=None)
calibration_market_share(energy_price, market_share_objective, cost_invest=None, consumption='conventional', subsidies=None)

Returns intangible costs construction by calibrating market_share.

Parameters

  • energy_price (pd.DataFrame) –

  • market_share_objective (pd.DataFrame) – Observed market share to match during calibration_year.

  • cost_invest (dict, optional) –

  • consumption ({'conventional', 'actual'}, default 'conventional') –

  • subsidies (list, optional) – subsidies to consider in the market share

Returns

  • pd.DataFrame – Intangible cost

  • pd.DataFrame – Market share calculated and observed

static evolution_area_construction(area_construction_prev, area_construction_ini, area_construction_max, elasticity_area, available_income_ratio)

Evolution of new buildings area based on total available income. Function represents growth.

Parameters

  • area_construction_prev (pd.Series) –

  • area_construction_ini (pd.Series) –

  • area_construction_max (pd.Series) –

  • elasticity_area (pd.Series) –

  • available_income_ratio (float) –

Returns

Return type

pd.Series

to_flow_area_constructed_ini(stock_area_existing)

Initialize construction knowledge.

to_flow_constructed_dm()

Returns flow of constructed buildings segmented by decision-maker (dm) (Housing type, Occupancy status).

  1. Increase in the share of multi-family housing in the total stock.

  2. The share of owner-occupied and rented dwellings is held constant.

Returns

MultiIndex: (Housing type, Occupancy status), value: buildings constructed

Return type

pd.Series

to_flow_constructed_dm_he_ep(energy_price, cost_intangible=None, cost_invest=None, consumption='conventional', nu=8.0, subsidies=None)

Returns flow of constructed buildings segmented.

  1. Calculate construction flow segmented by decision-maker:

  2. Calculate the market-share of Heating energy and Energy performance type by decision-maker: market_share_dm;

  3. Calculate construction flow segmented by decision-maker and heating energy, energy performance;

Parameters

  • energy_price (pd.DataFrame) –

  • cost_intangible (pd.DataFrame, optional) –

  • cost_invest (pd.DataFrame, optional) –

  • consumption ({'conventional', 'actual'}, default 'conventional') –

  • nu (float, default 8.0) –

  • subsidies (list, optional) –

Returns

flow of constructed housing segmented by (Housing type, Occupancy status, Energy performance, Heating energy)

Return type

pd.Series

to_flow_constructed_seg(energy_price, cost_intangible=None, cost_invest=None, consumption=None, nu=8.0, subsidies=None)

Add Income class and Income class owner levels to flow_constructed.

io_share_seg: pd.DataFrame

for each segment (rows) distribution of income class owner decile (columns)

ic_share_seg: pd.DataFrame

for each segment (rows) distribution of income class owner decile (columns)

Parameters

  • energy_price (pd.DataFrame) – cost_intangible: pd.DataFrame, optional

  • cost_intangible (pd.DataFrame, optional) –

  • cost_invest (pd.DataFrame, optional) –

  • consumption ({'conventional', 'actual'}, default 'conventional') –

  • nu (float, default 8.0) –

  • subsidies (list, optional) –

Returns

flow of constructed housing segmented by (Housing type, Occupancy status, Energy performance, Heating energy, Income class, Income class owner)

Return type

pd.Series

to_share_housing_type()

Returns share of Housing type (‘Multi-family’, ‘Single-family’) in the new constructed housings.

Share of multi-family in the total stock to reflect urbanization effects. Demolition dynamic is made endogenously and therefore construction should reflect the evolution..

Share_multifamily[year] = Stock_multifamily[year] / Stock[year] Share_multifamily[year] = (Stock_multifamily[year - 1] + Flow_multifamily_construction) / Stock[year] Share_multifamily[year] = (Share_multifamily[year - 1] * Stock[year - 1] + Flow_multifamily_construction) / Stock[year] Flow_multifamily_construction = Share_multifamily[year] * Stock[year] - Share_multifamily[year - 1] * Stock[year - 1]

Returns

index: housing type, value: share of housing type in the stock of constructed buildings.

Return type

pd.Series

update_area_construction(elasticity_area_new_ini, available_income_real_pop_ds, area_max_construction)

Every year, average area of new buildings increase with available income.

Trend is based on elasticity area / income. eps_area_new decrease over time and reduce elasticity while average area converge towards area_max. exogenous_dict[‘population_total_ds’]

Parameters

  • elasticity_area_new_ini (pd.Series) –

  • available_income_real_pop_ds (pd.Series) –

  • area_max_construction (pd.Series) –

update_flow_constructed_seg(energy_price, cost_intangible=None, cost_invest=None, consumption='conventional', nu=8.0, subsidies=None)

Update HousingConstructed object flow_constructed_seg attribute.

Parameters

  • energy_price (pd.DataFrame) – cost_intangible: pd.DataFrame, optional

  • cost_intangible (dict, optional) –

  • cost_invest (dict, optional) –

  • consumption ({'conventional', 'actual'}, default 'conventional') –

  • nu (float, default 8.0) –

  • subsidies (list, optional) –

class buildings.HousingStockRenovated(stock, attributes_values, year=2018, residual_rate=0.0, destruction_rate=0.0, rate_renovation_ini=None, learning_year=None, npv_min=None, rate_max=None, rate_min=None, attributes2area=None, attributes2horizon=None, attributes2discount=None, attributes2income=None, attributes2consumption=None, kwh_cumac_transition=None)

Class that represents an existing buildings stock that can (i) renovate buildings, (ii) demolition buildings.

Some stocks imply change for other stock: stock_master. Stock_master should be property as the setter methods need to change all dependencies stock: stock_slave. As they need to be initialize there is a private attribute in the init. .. rubric:: Example

A modification of stock will change stock_mobile_seg. stock_mobile_seg cannot change directly.

Some stocks doesn’t have stock_master and stock_slave: they are public. Example:

Some stocks need to be stored in a dict. Their modification need to be updated in the dict. Theses stocks are properties as the setter method updates the stock_dict. As they need to be initialize there is a private attribute in the init. Dict cannot be change directly as they depend on stock (only when to change in the setter method of the stock) .. rubric:: Example

_stock_knowledge_dict = _stock_knowledge_dict.append({year: stock_knowledge})

These stocks can be a slave stock. In that case all updates are in the stock master setter methods. .. rubric:: Example

_stock_mobile & _stock_mobile_dict

calibration_renovation_rate(energy_prices, renovation_rate_ini, consumption='conventional', cost_invest=None, cost_intangible=None, subsidies=None, option=0)

Calibration of the ρ parameter of the renovation rate function (logistic function of the NPV).

Renovation rate of dwellings attributes led is calculated as a logistic function of the NPV. The logistic form captures heterogeneity in heating preference and habits, assuming they are normally distributed. Parameter ρ is calibrated, for each type of attributes. It is then aggregated or not, depending of weighted parameter.

For instance, ρ was calibrated in 2012, for each type of decision-maker and each initial certificates (i.e., 6x6=36 values), so that the NPVs calculated with the subsidies in effect in 2012 (see main article) reproduce the observed renovation rates. Renovation rate observed depends on (Occupancy status, Housing type)

Parameters

  • energy_prices (pd.DataFrame) –

  • renovation_rate_ini (pd.Series) –

  • consumption ({'conventional', 'actual'}, default 'conventional') –

  • cost_invest (dict) –

  • cost_intangible (dict) –

  • subsidies (list) –

  • option (int, default 0) – 0: rho for each agent_mean (based on a NPV mean) 1: unique rho and so unique calibration function for all agents (rho, npv_min, rate_min, rate_max) 2: rho for each individual agent 3: calculate rho mean for group of agents

Returns

  • pd.Series – ρ parameters by segment

  • pd.DataFrame – Concatenation of renovation_rate_ini, renovation_rate_calculated.

static calibration_rho(npv, renovation_rate_target, rate_max, rate_min, npv_min)

Function that returns rho in order to match the targeted renovation rate.

Parameters

  • npv (pd.Series) – Net present value calculated.

  • renovation_rate_target (pd.Series) – Targeted renovation rate.

  • rate_max (float) –

  • rate_min (float) –

  • npv_min (float) –

Returns

Return type

pd.Series

flow_area_renovated_seg_ini(rate_renovation_ini, learning_year)

Initialize flow area renovated.

Flow area renovation is defined as:

renovation rate (2.7%/yr) x number of learning years (10 yrs) x renovated area (m2).

flow_renovation_ep(energy_prices, consumption='conventional', cost_invest=None, cost_intangible=None, subsidies=None, renovation_obligation=None, mutation=0.0, rotation=0.0)

Calculate flow renovation by energy performance final.

Parameters

  • energy_prices (pd.DataFrame) –

  • cost_invest (dict, optional) –

  • cost_intangible (dict, optional) –

  • consumption (str, default 'conventional') –

  • subsidies (dict, optional) –

  • renovation_obligation (RenovationObligation, optional) –

  • mutation (pd.Series or float, default 0.0) –

  • rotation (pd.Series or float, default 0.0) –

Returns

Return type

pd.DataFrame

static renovate_rate_func(npv, rho, npv_min, rate_max, rate_min)

Calculate renovation rate for indexed pd.Series rho and indexed pd.Series npv.

Parameters

  • npv (pd.Series) – Indexes are the first elements of NPV and last value is the actual NPV value.

  • rho (pd.Series) – Rho MultiIndex pd.Series containing rho values and indexed by stock attributes.

  • npv_min (float) –

  • rate_max (float) –

  • rate_min (float) –

Returns

Return type

float

static renovation_rate(npv, rho, npv_min, rate_max, rate_min)

Renovation rate for float values.

Parameters

  • npv (float) –

  • rho (float) –

  • npv_min (float) –

  • rate_max (float) –

  • rate_min (float) –

Returns

Return type

float

to_flow_demolition_seg()

Returns stock_demolition - segmented housing number demolition.

Buildings to destroy are chosen in stock_mobile. 1. type_housing_demolition is respected to match decision-maker proportion; - type_housing_demolition_reindex 2. income_class, income_class_owner, heating_energy match stock_remaining proportion; - type_housing_demolition_wo_performance 3. worst energy_performance_attributes for each segment are targeted. - stock_demolition

Returns

Return type

pd.Series segmented

to_flow_knowledge(flow_area_renovated_seg)

Returns knowledge renovation.

Parameters

flow_area_renovated_seg (pd.DataFrame) – Data array containing renovation are for each segment and each transition.

to_flow_remained(energy_prices, consumption='conventional', cost_invest=None, cost_intangible=None, subsidies=None, renovation_obligation=None, mutation=0.0, rotation=0.0)

Calculate flow_remained for each segment.

Parameters

  • energy_prices (pd.DataFrame) –

  • cost_invest (dict, optional) –

  • cost_intangible (dict, optional) –

  • consumption (str, default 'conventional') –

  • subsidies (list, optional) –

  • renovation_obligation (RenovationObligation, optional) –

  • mutation (pd.Series or float, default 0.0) –

  • rotation (pd.Series or float, default 0.0) –

Returns

  • flow_remained_seg, pd.Series – positive (+) flow for buildings segment reached by the renovation (final state), negative (-) flow for buildings segment (initial state) that have been renovated.

  • flow_area_renovation_seg, pd.Series

to_flow_renovation_ep(energy_prices, consumption='conventional', cost_invest=None, cost_intangible=None, subsidies=None, renovation_obligation=None, mutation=0.0, rotation=0.0, error=1)

Functions only useful if a subsidy_tax is declared. Run a dichotomy to find the subsidy rate that recycle energy tax revenue.

Parameters

  • energy_prices (pd.DataFrame) –

  • cost_invest (dict, optional) –

  • cost_intangible (dict, optional) –

  • consumption (str, default 'conventional') –

  • subsidies (dict, optional) –

  • renovation_obligation (RenovationObligation, optional) –

  • mutation (pd.Series or float, default 0.0) –

  • rotation (pd.Series or float, default 0.0) –

  • error (int, default 1) –

Returns

Return type

pd.DataFrame

to_flow_renovation_ep_energy(energy_prices, consumption='conventional', cost_invest=None, cost_intangible=None, subsidies=None, renovation_obligation=None, mutation=0.0, rotation=0.0)

De-aggregate stock_renovation_attributes by final heating energy.

  1. Flow renovation returns number of renovation by final energy performance.

  2. Heating energy technology market-share is then calculated based on flow renovation.

Parameters

  • energy_prices (pd.DataFrame) –

  • cost_invest (dict, optional) –

  • cost_intangible (dict, optional) –

  • consumption (str, default 'conventional') –

  • subsidies (list, optional) –

  • renovation_obligation (RenovationObligation, optional) –

  • mutation (pd.Series or float, default 0.0) –

  • rotation (pd.Series or float, default 0.0) –

Returns

Return type

pd.DataFrame

to_renovation_rate(energy_prices, transition=None, consumption='conventional', cost_invest=None, cost_intangible=None, subsidies=None, rho=None)

Routine calculating renovation rate from segments for a particular yr.

Cost (energy, investment) & rho parameter are also required.

Parameters

  • energy_prices (pd.DataFrame) –

  • transition (list) –

  • cost_invest (dict, optional) –

  • cost_intangible (dict, optional) –

  • consumption (str, default 'conventional') –

  • subsidies (list, optional) –

  • rho (pd.Series, optional) –

update_stock(flow_remained_seg, flow_area_renovation_seg=None)

Update HousingStock.

Parameters

  • flow_remained_seg (pd.Series) –

  • flow_area_renovation_seg (pd.Series, pd.DataFrame) –

Policies

class policies.EnergyTaxes(name, start, end, unit, value, calibration=False)

Represents energy taxes.

name

Name of the policy.

Type

str

start

Year policy starts.

Type

int

end

Year policy ends.

Type

int

calibration

Should policy be used for the calibration step?

Type

bool, default: False

unit

Unit of measure of the value attribute.

Type

{‘%’, ‘euro/kWh’, ‘euro/tCO2’}

value

Value of energy taxes.

Type

float, pd.Series or pd.DataFrame

price_to_taxes(energy_prices=None, co2_content=None)

Calculate energy taxes cost based on self.unit unit of measure.

Parameters

  • energy_prices (pd.Series or pd.DataFrame, optional) – Energy prices in euro/kWh. Heating energy as index, and years as columns.

  • co2_content (pd.Series or pd.DataFrame, optional) – CO2 content in gCO2/kWh. Heating energy as index, and years as columns.

Returns

Energy tax cost in euro/kWh.

Return type

pd.Series

class policies.PublicPolicy(name, start, end, policy, calibration=False)

Public policy parent class.

name

Name of the policy.

Type

str

start

Year policy starts.

Type

int

end

Year policy ends.

Type

int

policy
Type

{‘energy_taxes’, ‘subsidies’}

calibration

Should policy be used for the calibration step?

Type

bool, default: False

class policies.RegulatedLoan(name, start, end, ir_regulated=None, ir_market=None, principal_max=None, principal_min=None, horizon=None, targets=None, transition=None, calibration=False)

Loan backed by the state to buy technology capex.

Instead of paying interest rate at ir_market (%/yr), households only pays ir_regulated.

name
Type

str

start
Type

int

end
Type

int

ir_regulated
Type

float or pd.Series, optional

ir_market
Type

float or pd.Series, optional

principal_max
Type

float or pd.Series, optional

horizon
Type

int or pd.Series, optional

horizon_max
Type

int or pd.Series, optional

horizon_min
Type

int or pd.Series, optional

targets
Type

pd.DataFrame, optional

interest_cost: calculate interest_cost
loan_approximate2subsidy(principal): calculate subsidies as opportunity cost for the household for a principal.
principal is a capex from a initial state to a final state.
apply_targets(principal)

Returns principal for transition that are targeted by the regulated loan.

Parameters

  • self.targets (pd.DataFrame) – 1 when targeted, otherwise 0

  • principal (pd.DataFrame) – capex of a transition from row to column

Returns

Return type

pd.DataFrame

static interest_cost(interest_rate, n_period, principal)

Returns total interest cost.

Parameters

  • interest_rate (float) – loan interest rate (%/period)

  • n_period (float) – number of periods

  • principal (float) – loan amount

Returns

Return type

float

to_opp_cost(ir_market, horizon, principal)

R eturns the opportunity cost to get the regulated loan.

Calls self.apply_targets to restrict transition that are targeted by the policy.

Parameters

  • ir_market (float or pd.Series) – market interest rate that would be paid without the regulated loan

  • horizon (int or pd.Series) – loan horizon

  • principal (float or pd.Series or pd.DataFrame) – capex of a transition from row to column

Returns

Return type

float, pd.Series, pd.DataFrame

to_opportunity_cost(principal)

Every parameter must be the same shape.

class policies.Subsidies(name, start, end, unit, value, transition=None, cost_max=None, cost_min=None, subsidy_max=None, calibration=False, time_dependent=False, targets=None, area=None, priority=False)

Represents subsidies.

Subsidies values are in euro/m2. Subsidy_max, cost_max or cost_min are transformed in euro/m2.

name

Name of the policy.

Type

str

start

Year policy starts.

Type

int

end

Year policy ends.

Type

int

calibration

Should policy be used for the calibration step?

Type

bool, default: False

unit

Unit of measure of the value attribute.

Type

{‘%’, ‘euro/kWh’, ‘euro/tCO2’}

value

Value of subsidies.

Type

float, pd.Series or pd.DataFrame

transition

Transition to apply the subsidy.

Type

list, default: [‘Energy performance’]

cost_max

Maximum capex cost to receive a subsidy.

Type

float, optional

subsidy_max

Maximum subsidy.

Type

float, optional

to_subsidy(year, cost=None, energy_saving=None)

Calculate subsidy value based on subsidies parameters.

Parameters

  • year (int) –

  • cost (pd.Series, pd.DataFrame, optional) – Necessary if self.unit == ‘%’

  • energy_saving (pd.Series, pd.DataFrame, optional) – Necessary if self.unit == ‘euro/kWh’

to_unit(value)

Transform euro to euro/m2.

Parameters

value (int, float, pd.Series) –

Returns

Return type

pd.Series, pd.DataFrame

class policies.SubsidiesRecyclingTax(name, start, end, tax_unit, tax_value, subsidy_unit, subsidy_value, calibration=False, transition=None)
class policies.ThermalRegulation(name, start, end, target, transition)

ThermalRegulationConstruction represents public policies that require a minimal performance target to build or retrofit a building.

For example, by 2030 all constructions should be Zero Net Building, and by 2040 Positive Energy Building.

apply_regulation(attributes, year)

Remove target of possible attributes.

Parameters

  • attributes (dict) – Key are attribute name (Energy performance) and items are list of possible value taken by attributes.

  • year (int) –

static parse_targets(target)

Returns pd.Series containing a list of element to remove each year because of the regulation.

Parameters

  • target (pd.Series) –

  • end (int) –

Returns

Return type

pd.Series