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
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
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
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
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
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)
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).
Increase in the share of multi-family housing in the total stock.
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.
Calculate construction flow segmented by decision-maker:
Calculate the market-share of Heating energy and Energy performance type by decision-maker: market_share_dm;
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
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.
Flow renovation returns number of renovation by final energy performance.
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