Dynamic Stock Model

Class DynamicStockModel Check https://github.com/IndEcol/ODYM for latest version.

Methods for efficient handling of dynamic stock models (DSMs)

Created on Mon Jun 30 17:21:28 2014

@author: Stefan Pauliuk, NTNU Trondheim, Norway, later Uni Freiburg, Germany with contributions from Sebastiaan Deetman, CML, Leiden, NL Tomer Fishman, IDC Herzliya, IL Chris Mutel, PSI, Villingen, CH

standard abbreviation: DSM or dsm

dependencies:

numpy >= 1.9 scipy >= 0.14

Repository for this class, documentation, and tutorials: https://github.com/IndEcol/ODYM

class odym.dynamic_stock_model.DynamicStockModel(t=None, i=None, o=None, s=None, lt=None, s_c=None, o_c=None, name='DSM', pdf=None, sf=None)

Class containing a dynamic stock model

t

Type:

Series of years or other time intervals

i

Type:

Discrete time series of inflow to stock

o

Type:

Discrete time series of outflow from stock

o_c

Type:

Discrete time series of outflow from stock, by cohort

s_c

Type:

dynamic stock model (stock broken down by year and age- cohort)

s

Type:

Discrete time series for stock, total

lt

Type:

lifetime distribution: dictionary

pdf

Type:

probability density function, distribution of outflow from a specific age-cohort

sf

Type:

survival function for different age-cohorts, year x age-cohort table

namestring, optional

Name of the dynamic stock model, default is ‘DSM’

check_stock_balance()

Check wether inflow, outflow, and stock are balanced. If possible, the method returns the vector ‘Balance’, where Balance = inflow - outflow - stock_change

compute_evolution_initialstock(InitialStock, SwitchTime)

Assume InitialStock is a vector that contains the age structure of the stock at time t0, and it covers as many historic cohorts as there are elements in it. This method then computes the future stock and outflow from the year SwitchTime onwards. Only future years, i.e., years after SwitchTime, are computed. NOTE: This method ignores and deletes previously calculated s_c and o_c. The InitialStock is a vector of the age-cohort composition of the stock at SwitchTime, with length SwitchTime

compute_i_from_s(InitialStock)

Given a stock at t0 broken down by different cohorts tx … t0, an “initial stock”. This method calculates the original inflow that generated this stock. Example:

compute_o_c_from_s_c()

Compute outflow by cohort from stock by cohort.

compute_outflow_mb()

Compute outflow from process via mass balance. Needed in cases where lifetime is zero.

compute_outflow_pdf()

Lifetime model. The method compute outflow_pdf returns an array year-by-cohort of the probability of a item added to stock in year m (aka cohort m) leaves in in year n. This value equals pdf(n,m). The pdf is computed from the survival table sf, where the type of the lifetime distribution enters. The shape of the output pdf array is NoofYears * NoofYears, but the meaning is years by age-cohorts. The method does nothing if the pdf alreay exists.

compute_outflow_total()

Determine total outflow as row sum of cohort-specific outflow.

compute_s_c_inflow_driven()

With given inflow and lifetime distribution, the method builds the stock by cohort.

compute_sf()

Survival table self.sf(m,n) denotes the share of an inflow in year n (age-cohort) still present at the end of year m (after m-n years). The computation is self.sf(m,n) = ProbDist.sf(m-n), where ProbDist is the appropriate scipy function for the lifetime model chosen. For lifetimes 0 the sf is also 0, meaning that the age-cohort leaves during the same year of the inflow. The method compute outflow_sf returns an array year-by-cohort of the surviving fraction of a flow added to stock

in year m (aka cohort m) in in year n. This value equals sf(n,m).

This is the only method for the inflow-driven model where the lifetime distribution directly enters the computation. All other stock variables are determined by mass balance. The shape of the output sf array is NoofYears * NoofYears, and the meaning is years by age-cohorts. The method does nothing if the sf alreay exists. For example, sf could be assigned to the dynamic stock model

from an exogenous computation to save time.

compute_stock_change()

Determine stock change from time series for stock. Formula: stock_change(t) = stock(t) - stock(t-1).

compute_stock_driven_model(NegativeInflowCorrect=False)

With given total stock and lifetime distribution, the method builds the stock by cohort and the inflow.

compute_stock_driven_model_initialstock(InitialStock, SwitchTime, NegativeInflowCorrect=False)

With given total stock and lifetime distribution, the method builds the stock by cohort and the inflow. The extra parameter InitialStock is a vector that contains the age structure of the stock at the END of the year

Switchtime -1 = t0.

* Convention 1: Stocks are measured AT THE END OF THE YEAR. Flows occur DURING THE YEAR. Convention 2: The model time t spans both historic and future age-cohorts, and the index SwitchTime -1 indicates the first future age-cohort. Convention 3: SwitchTime = len(InitialStock) + 1, that means SwitchTime is counted starting from 1 and not 0. Convention 4: The future stock time series has 0 as its first len(InitialStock) elements. * In the year SwitchTime the model switches from the historic stock to the stock-driven approach. The year SwitchTime is the first year with the stock-driven approach. InitialStock contains the age-cohort composition of the stock AT THE END of year SwitchTime -1.

InitialStock must have length = SwithTime -1.

For the option “NegativeInflowCorrect”, see the explanations for the method compute_stock_driven_model(self, NegativeInflowCorrect = True). NegativeInflowCorrect only affects the future stock time series and works exactly as for the stock-driven model without initial stock.

compute_stock_driven_model_initialstock_typesplit(FutureStock, InitialStock, SFArrayCombined, TypeSplit)

With given total future stock and lifetime distribution, the method builds the stock by cohort and the inflow. The age structure of the initial stock is given for each technology, and a type split of total inflow into different technology types is given as well.

SPECIFICATION: Stocks are always measured AT THE END of the discrete time interval.

Indices:

t: time: Entire time frame: from earliest age-cohort to latest model year. c: age-cohort: same as time. T: Switch time: DEFINED as first year where historic stock is NOT present, = last year where historic stock

is present +1.

Switchtime is calculated internally, by subtracting the length of the historic stock from the total model length.

g: product type

Data:

FutureStock[t], total future stock at end of each year, starting at T InitialStock[c,g], 0…T-1;0…T-1, stock at the end of T-1, by age-cohort c, ranging from 0…T-1, and product type g

c-dimension has full length, all future years must be 0.

SFArrayCombined[t,c,g], Survival function of age-cohort c at end of year t for product type g

this array spans both historic and future age-cohorts

Typesplit[t,g], splits total inflow into product types for future years

The extra parameter InitialStock is a vector that contains the age structure of the stock at time t0, and it covers as many historic cohorts as there are elements in it. In the year SwitchTime the model switches from the historic stock to the stock-driven approach. Only future years, i.e., years after SwitchTime, are computed and returned. The InitialStock is a vector of the age-cohort composition of the stock at SwitchTime, with length SwitchTime. The parameter TypeSplit splits the total inflow into Ng types.

compute_stock_driven_model_initialstock_typesplit_negativeinflowcorrect(SwitchTime, InitialStock, SFArrayCombined, TypeSplit, NegativeInflowCorrect=False)

With given total future stock and lifetime distribution, the method builds the stock by cohort and the inflow. The age structure of the initial stock is given for each technology, and a type split of total inflow into different technology types is given as well. For the option “NegativeInflowCorrect”, see the explanations for the method compute_stock_driven_model(self, NegativeInflowCorrect = True). NegativeInflowCorrect only affects the future stock time series and works exactly as for the stock-driven model without initial stock.

SPECIFICATION: Stocks are always measured AT THE END of the discrete time interval.

Indices:

t: time: Entire time frame: from earliest age-cohort to latest model year. c: age-cohort: same as time. T: Switch time: DEFINED as first year where historic stock is NOT present, = last year where historic stock is present +1.

Switchtime must be given as argument. Example: if the first three age-cohorts are historic, SwitchTime is 3, which indicates the 4th year. That also means that the first 3 time-entries for the stock and typesplit arrays must be 0.

g: product type

Data:

s[t], total future stock time series, at end of each year, starting at T, trailing 0s for historic years.

! is not handed over with the function call but earlier, when defining the dsm.

InitialStock[c,g], 0…T-1;0…T-1, stock at the end of T-1, by age-cohort c, ranging from 0…T-1, and product type g

c-dimension has full length, all future years must be 0.

SFArrayCombined[t,c,g], Survival function of age-cohort c at end of year t for product type g

this array spans both historic and future age-cohorts

Typesplit[t,g], splits total inflow into product types for future years NegativeInflowCorrect BOOL, retains items in stock if their leaving would lead to negative inflows.

The extra parameter InitialStock is a vector that contains the age structure of the stock at time t0, and it

covers as many historic cohorts as there are elements in it.

In the year SwitchTime the model switches from the historic stock to the stock-driven approach. Only future years, i.e., years after SwitchTime, are computed and returned. The InitialStock is a vector of the age-cohort composition of the stock at SwitchTime, with length SwitchTime. The parameter TypeSplit splits the total inflow into Ng types.

compute_stock_total()

Determine total stock as row sum of cohort-specific stock.

dimension_check()

This method checks which variables are present and checks whether data types and dimensions match