utility module

class ezclimate.utility.EZUtility(tree, damage, cost, period_len, eis=0.9, ra=7.0, time_pref=0.005, add_penalty_cost=False, max_penalty=0.0, penalty_scale=1.0)

Bases: object

Calculation of Epstein-Zin utility for the EZ-Climate model.

The Epstein-Zin utility allows for different rates of substitution across time and states. For specification see DLW-paper.

Parameters:

• tree (TreeModel object) – tree structure used
• damage (Damage object) – class that provides damage methods
• cost (Cost object) – class that procides cost methods
• period_len (float) – subinterval length
• eis (float, optional) – elasticity of intertemporal substitution
• ra (float, optional) – risk-aversion
• time_pref (float, optional) – pure rate of time preference

tree

TreeModel object – tree structure used

damage

Damage object – class that provides damage methods

cost

Cost object – class that procides cost methods

period_len

float – subinterval length

decision_times

ndarray – years in the future where decisions will be made

cons_growth

float – consumption growth

growth_term

float – 1 + cons_growth

r

float – the parameter rho from the DLW-paper

a

float – the parameter alpha from the DLW-paper

b

float – the parameter beta from the DLW-paper

adjusted_utility(m, period_cons_eps=None, node_cons_eps=None, final_cons_eps=0.0, first_period_consadj=0.0, return_trees=False)

Calculating adjusted utility for sensitivity analysis. Used e.g. to find zero-coupon bond price. Values in parameters are used to adjusted the utility in different ways.

Parameters:

• m (ndarray) – array of mitigations
• period_cons_eps (ndarray, optional) – array of increases in consumption per period
• node_cons_eps (SmallStorageTree, optional) – increases in consumption per node
• final_cons_eps (float, optional) – value to increase the final utilities by
• first_period_consadj (float, optional) – value to increase consumption at period 0 by
• return_trees (bool, optional) – True if method should return trees calculculated in producing the utility

Returns:

tuple of BaseStorageTree if return_trees else ndarray with utility at period 0

Return type:

ndarray or tuple

Examples

Assuming we have declared a EZUtility object as ‘ezu’ and have a mitigation array ‘m’

>>> ezu.adjusted_utility(m, final_cons_eps=0.1)
array([ 9.83424045])
>>> utility_tree, cons_tree, cost_tree, ce_tree = ezu.adjusted_utility(m, final_cons_eps=0.1, return_trees=True)

>>> arr = np.zeros(int(ezu.decision_times[-1]/ezu.period_len) + 1)
>>> arr[-1] = 0.1
>>> ezu.adjusted_utility(m, period_cons_eps=arr)
array([ 9.83424045])

>>> bst = BigStorageTree(5.0, [0, 15, 45, 85, 185, 285, 385])
>>> bst.set_value(bst.last_period, np.repeat(0.01, len(bst.last)))
>>> ezu.adjusted_utility(m, node_cons_eps=bst)
array([ 9.83391921])

The last example differs from the rest in that the last values of the node_cons_eps will never be used. Hence if you want to update the last period consumption, use one of these two methods.

>>> ezu.adjusted_utility(m, first_period_consadj=0.01)
array([ 9.84518772])

marginal_utility(m, utility_tree, cons_tree, cost_tree, ce_tree)

Calculating marginal utility for sensitivity analysis, e.g. in the SSC decomposition.

Parameters:

• m (ndarray) – array of mitigations
• utility_tree (BigStorageTree object) – utility values from using mitigation m
• cons_tree (BigStorageTree object) – consumption values from using mitigation m
• cost_tree (SmallStorageTree object) – cost values from using mitigation m
• ce_tree (BigStorageTree object) – certain equivalence values from using mitigation m

Returns:

marginal utility tree

Return type:

tuple

Examples

Assuming we have declared a EZUtility object as ‘ezu’ and have a mitigation array ‘m’. >>> >>> utility_tree, cons_tree, cost_tree, ce_tree = ezu.utility(m, return_trees=True) >>> mu_0_tree, mu_1_tree, mu_2_tree = ezu.marginal_utility(m, utility_tree, cons_tree, cost_tree, ce_tree) >>> mu_0_tree[0] # value at period 0 array([ 0.33001256]) >>> mu_1_tree[0] # value at period 0 array([ 0.15691619]) >>> mu_2_tree[0] # value at period 0 array([ 0.13948175])

partial_grad(m, i, delta=1e-08)

Calculate the ith element of the gradient vector.

Parameters:

• m (ndarray) – array of mitigations
• i (int) – node to calculate partial grad for

Returns:

gradient element

Return type:

float

utility(m, return_trees=False)

Calculating utility for the specific mitigation decisions m.

Parameters:

• m (ndarray or list) – array of mitigations
• return_trees (bool) – True if methid should return trees calculated in producing the utility

Returns:

• ndarray or tuple – tuple of BaseStorageTree if return_trees else ndarray with utility at period 0
• Examples
• ———
• Assuming we have declared a EZUtility object as ‘ezu’ and have a mitigation array ‘m’
• >>> ezu.utility(m)
• array([ 9.83391921])
• >>> utility_tree, cons_tree, cost_tree, ce_tree = ezu.utility(m, return_trees=True)