Stocks and Lifetime Models

pydantic model flodym.Stock

Stock objects are components of an MFASystem, where materials can accumulate over time. They consist of three flodym.FlodymArray objects: stock (the accumulation), inflow, outflow.

The base class only allows to compute the stock from known inflow and outflow. The subclasses allows computations using a lifetime distribution function, which is necessary if not both inflow and outflow are known.

Config:

  • protected_namespaces: tuple = ()

  • arbitrary_types_allowed: bool = True

Fields:

  • dims (flodym.dimensions.DimensionSet)

  • inflow (flodym.flodym_arrays.StockArray | None)

  • name (str | None)

  • outflow (flodym.flodym_arrays.StockArray | None)

  • process (flodym.processes.Process | None)

  • stock (flodym.flodym_arrays.StockArray | None)

  • time_letter (str)

Validators:

  • validate_stock_arrays » all fields

  • validate_time_first_dim » all fields

field dims: DimensionSet [Required]

Dimensions of the stock, inflow, and outflow arrays. Time must be the first dimension.

field inflow: StockArray | None = None

Inflow into the stock

field name: str | None = 'unnamed'

Name of the stock

field outflow: StockArray | None = None

Outflow from the stock

field process: Process | None = None

Process the stock is associated with, if any. Needed for example for the mass balance.

field stock: StockArray | None = None

Accumulation of the stock

field time_letter: str = 't'

Letter of the time dimension in the dimensions set, to make sure it’s the first one.

check_stock_balance()
abstract compute()
get_stock_balance()

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

Return type:

ndarray

to_stock_type(desired_stock_type, **kwargs)

Return an object of a new stock type with values and dimensions the same as the original. **kwargs can be used to pass additional model attributes as required by the desired stock type, if these are not contained in the original stock type.

Parameters:

desired_stock_type (type)

validator validate_stock_arrays  »  all fields
validator validate_time_first_dim  »  all fields
property process_id: int

ID of the process the stock is associated with.

property shape: tuple

Shape of the stock, inflow, outflow arrays, defined by the dimensions.

pydantic model flodym.SimpleFlowDrivenStock

Given inflows and outflows, the stock can be calculated.

Config:

  • protected_namespaces: tuple = ()

  • arbitrary_types_allowed: bool = True

Fields:

  • dims ()

  • inflow ()

  • name ()

  • outflow ()

  • process ()

  • stock ()

  • time_letter ()

Validators:

  • validate_stock_arrays » all fields

  • validate_time_first_dim » all fields

field dims: DimensionSet [Required]

Dimensions of the stock, inflow, and outflow arrays. Time must be the first dimension.

field inflow: StockArray | None = None

Inflow into the stock

field name: str | None = 'unnamed'

Name of the stock

field outflow: StockArray | None = None

Outflow from the stock

field process: Process | None = None

Process the stock is associated with, if any. Needed for example for the mass balance.

field stock: StockArray | None = None

Accumulation of the stock

field time_letter: str = 't'

Letter of the time dimension in the dimensions set, to make sure it’s the first one.

check_stock_balance()
compute()
get_stock_balance()

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

Return type:

ndarray

to_stock_type(desired_stock_type, **kwargs)

Return an object of a new stock type with values and dimensions the same as the original. **kwargs can be used to pass additional model attributes as required by the desired stock type, if these are not contained in the original stock type.

Parameters:

desired_stock_type (type)

validator validate_stock_arrays  »  all fields
validator validate_time_first_dim  »  all fields
property process_id: int

ID of the process the stock is associated with.

property shape: tuple

Shape of the stock, inflow, outflow arrays, defined by the dimensions.

pydantic model flodym.InflowDrivenDSM

Inflow driven model. Given inflow and lifetime distribution calculate stocks and outflows.

Config:

  • protected_namespaces: tuple = ()

  • arbitrary_types_allowed: bool = True

Fields:

  • dims ()

  • inflow ()

  • lifetime_model ()

  • name ()

  • outflow ()

  • process ()

  • stock ()

  • time_letter ()

Validators:

  • init_cohort_arrays » all fields

  • init_lifetime_model » all fields

  • validate_stock_arrays » all fields

  • validate_time_first_dim » all fields

field dims: DimensionSet [Required]

Dimensions of the stock, inflow, and outflow arrays. Time must be the first dimension.

field inflow: StockArray | None = None

Inflow into the stock

field lifetime_model: LifetimeModel | type [Required]

Lifetime model, which contains the lifetime distribution function. Can be input either as a LifetimeModel subclass, or as an instance of a LifetimeModel subclass. For available subclasses, see flodym.lifetime_models.

field name: str | None = 'unnamed'

Name of the stock

field outflow: StockArray | None = None

Outflow from the stock

field process: Process | None = None

Process the stock is associated with, if any. Needed for example for the mass balance.

field stock: StockArray | None = None

Accumulation of the stock

field time_letter: str = 't'

Letter of the time dimension in the dimensions set, to make sure it’s the first one.

check_stock_balance()
compute()

Determine stocks and outflows and store values in the class instance.

compute_outflow_by_cohort()

Compute outflow by cohort from changes in the stock by cohort and the known inflow.

Return type:

ndarray

compute_stock_by_cohort()

With given inflow and lifetime distribution, the method builds the stock by cohort. s_c[t,c] = i[c] * sf[t,c] for all t, c from the perspective of the stock the inflow has the dimension age-cohort, as each inflow(t) is added to the age-cohort c = t

Return type:

ndarray

get_stock_balance()

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

Return type:

ndarray

validator init_cohort_arrays  »  all fields
validator init_lifetime_model  »  all fields
to_stock_type(desired_stock_type, **kwargs)

Return an object of a new stock type with values and dimensions the same as the original. **kwargs can be used to pass additional model attributes as required by the desired stock type, if these are not contained in the original stock type.

Parameters:

desired_stock_type (type)

validator validate_stock_arrays  »  all fields
validator validate_time_first_dim  »  all fields
property process_id: int

ID of the process the stock is associated with.

property shape: tuple

Shape of the stock, inflow, outflow arrays, defined by the dimensions.

pydantic model flodym.StockDrivenDSM

Stock driven model. Given total stock and lifetime distribution, calculate inflows and outflows.

Config:

  • protected_namespaces: tuple = ()

  • arbitrary_types_allowed: bool = True

Fields:

  • dims ()

  • inflow ()

  • lifetime_model ()

  • name ()

  • outflow ()

  • process ()

  • stock ()

  • time_letter ()

Validators:

  • init_cohort_arrays » all fields

  • init_lifetime_model » all fields

  • validate_stock_arrays » all fields

  • validate_time_first_dim » all fields

field dims: DimensionSet [Required]

Dimensions of the stock, inflow, and outflow arrays. Time must be the first dimension.

field inflow: StockArray | None = None

Inflow into the stock

field lifetime_model: LifetimeModel | type [Required]

Lifetime model, which contains the lifetime distribution function. Can be input either as a LifetimeModel subclass, or as an instance of a LifetimeModel subclass. For available subclasses, see flodym.lifetime_models.

field name: str | None = 'unnamed'

Name of the stock

field outflow: StockArray | None = None

Outflow from the stock

field process: Process | None = None

Process the stock is associated with, if any. Needed for example for the mass balance.

field stock: StockArray | None = None

Accumulation of the stock

field time_letter: str = 't'

Letter of the time dimension in the dimensions set, to make sure it’s the first one.

check_stock_balance()
compute()

Determine inflows and outflows and store values in the class instance.

compute_inflow_and_outflow()

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

Return type:

tuple[ndarray]

get_stock_balance()

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

Return type:

ndarray

inflow_from_balance(m)

determine inflow from mass balance and do not correct negative inflow

Parameters:

m (int)

Return type:

ndarray

validator init_cohort_arrays  »  all fields
validator init_lifetime_model  »  all fields
to_stock_type(desired_stock_type, **kwargs)

Return an object of a new stock type with values and dimensions the same as the original. **kwargs can be used to pass additional model attributes as required by the desired stock type, if these are not contained in the original stock type.

Parameters:

desired_stock_type (type)

validator validate_stock_arrays  »  all fields
validator validate_time_first_dim  »  all fields
property process_id: int

ID of the process the stock is associated with.

property shape: tuple

Shape of the stock, inflow, outflow arrays, defined by the dimensions.

pydantic model flodym.StockDrivenDSM_NIC
Config:

  • protected_namespaces: tuple = ()

  • arbitrary_types_allowed: bool = True

Fields:

  • dims ()

  • inflow ()

  • lifetime_model ()

  • name ()

  • outflow ()

  • process ()

  • stock ()

  • time_letter ()

Validators:

  • init_cohort_arrays » all fields

  • init_lifetime_model » all fields

  • validate_stock_arrays » all fields

  • validate_time_first_dim » all fields

field dims: DimensionSet [Required]

Dimensions of the stock, inflow, and outflow arrays. Time must be the first dimension.

field inflow: StockArray | None = None

Inflow into the stock

field lifetime_model: LifetimeModel | type [Required]

Lifetime model, which contains the lifetime distribution function. Can be input either as a LifetimeModel subclass, or as an instance of a LifetimeModel subclass. For available subclasses, see flodym.lifetime_models.

field name: str | None = 'unnamed'

Name of the stock

field outflow: StockArray | None = None

Outflow from the stock

field process: Process | None = None

Process the stock is associated with, if any. Needed for example for the mass balance.

field stock: StockArray | None = None

Accumulation of the stock

field time_letter: str = 't'

Letter of the time dimension in the dimensions set, to make sure it’s the first one.

check_negative_inflow(m)

Check if inflow is negative.

Parameters:

m (int)

Return type:

bool

check_stock_balance()
compute()

Determine inflows and outflows and store values in the class instance.

compute_inflow_and_outflow()

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

Return type:

tuple[ndarray]

get_stock_balance()

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

Return type:

ndarray

inflow_from_balance(m)

determine inflow from mass balance and do not correct negative inflow

inflow_from_balance_correction(m)

determine inflow from mass balance and correct negative inflow

NOTE: This method of negative inflow correction is only of of many plausible methods of increasing the outflow to keep matching stock levels. It assumes that the surplus stock is removed in the year that it becomes obsolete. Each cohort loses the same fraction. Modellers need to try out whether this method leads to justifiable results. In some situations it is better to change the lifetime assumption than using the NegativeInflowCorrect option.

Parameters:

m (int)

Return type:

ndarray

validator init_cohort_arrays  »  all fields
validator init_lifetime_model  »  all fields
to_stock_type(desired_stock_type, **kwargs)

Return an object of a new stock type with values and dimensions the same as the original. **kwargs can be used to pass additional model attributes as required by the desired stock type, if these are not contained in the original stock type.

Parameters:

desired_stock_type (type)

validator validate_stock_arrays  »  all fields
validator validate_time_first_dim  »  all fields
property process_id: int

ID of the process the stock is associated with.

property shape: tuple

Shape of the stock, inflow, outflow arrays, defined by the dimensions.

pydantic model flodym.LifetimeModel

Contains shared functionality across the various lifetime models.

Fields:

  • dims (flodym.dimensions.DimensionSet)

  • time_letter (str)

field dims: DimensionSet [Required]
field time_letter: str = 't'
cast_any_to_flodym_array(prm_in)
compute_outflow_pdf()

Returns an array year-by-cohort of the probability that an item added to stock in year m (aka cohort m) leaves in in year n. This value equals pdf(n,m).

compute_survival_factor()

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.

abstract set_prms()
property sf
property shape
property t
property t_diag_indices
pydantic model flodym.FixedLifetime

Fixed lifetime, age-cohort leaves the stock in the model year when a certain age, specified as ‘Mean’, is reached.

Fields:

  • dims ()

  • mean (Any)

  • time_letter ()

Validators:

  • cast_mean » all fields

field dims: DimensionSet [Required]
field mean: Any = None
field time_letter: str = 't'
cast_any_to_flodym_array(prm_in)
validator cast_mean  »  all fields
compute_outflow_pdf()

Returns an array year-by-cohort of the probability that an item added to stock in year m (aka cohort m) leaves in in year n. This value equals pdf(n,m).

compute_survival_factor()

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.

set_prms(mean)
Parameters:

mean (FlodymArray)

property sf
property shape
property t
property t_diag_indices
pydantic model flodym.NormalLifetime

Normally distributed lifetime with mean and standard deviation. Watch out for nonzero values, for negative ages, no correction or truncation done here. NOTE: As normal distributions have nonzero pdf for negative ages, which are physically impossible, these outflow contributions can either be ignored ( violates the mass balance) or allocated to the zeroth year of residence, the latter being implemented in the method compute compute_o_c_from_s_c. As alternative, use lognormal or folded normal distribution options.

Fields:

  • dims ()

  • mean ()

  • std ()

  • time_letter ()

Validators:

  • cast_mean_std » all fields

field dims: DimensionSet [Required]
field mean: Any = None
field std: Any = None
field time_letter: str = 't'
cast_any_to_flodym_array(prm_in)
validator cast_mean_std  »  all fields
compute_outflow_pdf()

Returns an array year-by-cohort of the probability that an item added to stock in year m (aka cohort m) leaves in in year n. This value equals pdf(n,m).

compute_survival_factor()

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.

set_prms(mean, std)
Parameters:
property sf
property shape
property t
property t_diag_indices
pydantic model flodym.FoldedNormalLifetime

Folded normal distribution, cf. https://en.wikipedia.org/wiki/Folded_normal_distribution NOTE: call this with the parameters of the normal distribution mu and sigma of curve BEFORE folding, curve after folding will have different mu and sigma.

Fields:

  • dims ()

  • mean ()

  • std ()

  • time_letter ()

Validators:

  • cast_mean_std » all fields

field dims: DimensionSet [Required]
field mean: Any = None
field std: Any = None
field time_letter: str = 't'
cast_any_to_flodym_array(prm_in)
validator cast_mean_std  »  all fields
compute_outflow_pdf()

Returns an array year-by-cohort of the probability that an item added to stock in year m (aka cohort m) leaves in in year n. This value equals pdf(n,m).

compute_survival_factor()

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.

set_prms(mean, std)
Parameters:
property sf
property shape
property t
property t_diag_indices
pydantic model flodym.LogNormalLifetime

Lognormal distribution Here, the mean and stddev of the lognormal curve, not those of the underlying normal distribution, need to be specified! Values chosen according to description on https://docs.scipy.org/doc/scipy-0.13.0/reference/generated/scipy.stats.lognorm.html Same result as EXCEL function “=LOGNORM.VERT(x;LT_LN;SG_LN;TRUE)”

Fields:

  • dims ()

  • mean ()

  • std ()

  • time_letter ()

Validators:

  • cast_mean_std » all fields

field dims: DimensionSet [Required]
field mean: Any = None
field std: Any = None
field time_letter: str = 't'
cast_any_to_flodym_array(prm_in)
validator cast_mean_std  »  all fields
compute_outflow_pdf()

Returns an array year-by-cohort of the probability that an item added to stock in year m (aka cohort m) leaves in in year n. This value equals pdf(n,m).

compute_survival_factor()

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.

set_prms(mean, std)
Parameters:
property sf
property shape
property t
property t_diag_indices
pydantic model flodym.WeibullLifetime

Weibull distribution with standard definition of scale and shape parameters.

Fields:

  • dims ()

  • time_letter ()

  • weibull_scale (Any)

  • weibull_shape (Any)

Validators:

  • cast_shape_scale » all fields

field dims: DimensionSet [Required]
field time_letter: str = 't'
field weibull_scale: Any = None
field weibull_shape: Any = None
cast_any_to_flodym_array(prm_in)
validator cast_shape_scale  »  all fields
compute_outflow_pdf()

Returns an array year-by-cohort of the probability that an item added to stock in year m (aka cohort m) leaves in in year n. This value equals pdf(n,m).

compute_survival_factor()

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.

set_prms(weibull_shape, weibull_scale)
Parameters:
property sf
property shape
property t
property t_diag_indices
flodym.make_empty_stocks(stock_definitions, processes, dims)

Initialise empty Stock objects for each of the stocks listed in stock definitions.

Parameters:
Return type:

dict[str, Stock]