Blocks¶

This section contains the API documentation for model building blocks.

Block Classes¶

DBlock¶

class skagent.block.DBlock(name='', description='', shocks=<factory>, dynamics=<factory>, reward=<factory>)¶

Bases: Block

Represents a ‘block’ of model behavior. It prioritizes a representation of the dynamics of the block. Control variables are designated by the appropriate dynamic rule.

Parameters:

shocks (Mapping(str, Distribution or tuple)) –
A mapping from variable names to Distribution objects, representing exogenous shocks.

Optionally, the mapping can be to tuples of Distribution constructors and dictionary of input arguments. In this case, the dictionary can map argument names to numbers, or to strings. The strings are parsed as mathematical expressions and evaluated in the scope of a calibration dictionary.
dynamics (Mapping(str, str or callable)) – An ordered dictionary mapping variable names to mathematical expressions. These expressions can be simple functions, in which case the argument names should match the variable inputs. Or these can be strings, which are parsed into functions. The order of dynamic equations matters, as they are applied sequentially as update rules.
reward (Mapping(str, str)) – A dictionary mapping variable names to agent role labels. The variable name will almost always appear in ‘dynamics’. The agent role indicates which agent views the variable as a reward to optimize.
name (str)
description (str)

calc_reward(vals)¶: Computes the reward for a given set of variable values

construct_shocks(calibration, rng=None)¶

Constructs all shocks given calibration. This method mutates the DBlock.

Parameters:

calibration (dict) – Calibration parameters for shock construction
rng (np.random.Generator, optional) – Random number generator to use for distribution construction

deep_replace(name=None, description=None, shocks=None, dynamics=None, reward=None)¶: Creates a deep copy of the block with new shocks, dynamics, and rewards dictionaries. These dictionaries will have updated values based on the inputs.

description: str = ''¶

discretize(disc_params)¶: Returns a new DBlock which is a copy of this one, but with shock discretized.

dynamics: dict¶

get_arrival_value_function(disc_params, dr, continuation)¶

Returns an arrival value function, which is the value of the states upon arrival into the block.

This involves taking an expectation over shocks (which must first be discretized), a decision rule, and a continuation value function.)

get_decision_value_function(dr, continuation)¶

Given a decision rule and a continuation value function, return a function for the value at the decision step/tac, after the shock have been realized.

## TODO: it would be better to systematize these value functions per block ## better, then construct them with ‘partial’ methods

get_dynamics()¶

get_shocks()¶

get_state_rule_value_function_from_continuation(continuation, screen=False)¶: Given a continuation value function, returns a state-rule value function: the value for each state and decision rule. This value includes both the reward for executing the rule ‘this period’, and the continuation value of the resulting states.

get_vars()¶: Returns the variables that are created/modified by the Block. Does not include variables that are only used as arguments to the dynamics. TODO: Get a way to find these.

iter_dblocks()¶: A DBlock is its own leaf.

name: str = ''¶

reward: dict¶

shocks: dict¶

transition(pre, dr, screen=False, until=None, fix=None)¶

RBlock¶

class skagent.block.RBlock(name='', description='', blocks=<factory>)¶

Bases: Block

A recursive block.

Parameters:

...
name (str)
description (str)
blocks (List[Block])

blocks: List[Block]¶

construct_shocks(calibration, rng=None)¶

Construct all shocks given a calibration dictionary.

Parameters:

calibration (dict) – Calibration parameters for shock construction
rng (np.random.Generator, optional) – Random number generator to use for distribution construction

description: str = ''¶

discretize(disc_params)¶: Recursively discretizes all the blocks. It replaces any DBlocks with new blocks with discretized shocks.

get_controls()¶: Returns only the Control variables from the Block dynamics.

get_dynamics()¶

get_shocks()¶

get_vars()¶

iter_dblocks()¶: Iterate over all DBlock leaves in this RBlock tree.

name: str = ''¶

property reward¶: The reward attributions for all subblocks.

Control¶

class skagent.block.Control(iset, lower_bound=None, upper_bound=None, agent=None)¶

Bases: object

Used to designate a variable that is a control variable.

Parameters:

iset (list of str) – The labels of the variables that are in the information set of this control.
lower_bound (function) – An ‘equation function’ which evaluates to the lower bound of the control variable.
upper_bound (function) – An ‘equation function’ which evaluates to the upper bound of the control variable.
agent (str) – A label identifying the agent role to which this control is attributed.

Aggregate¶

class skagent.block.Aggregate(dist)¶

Bases: object

Used to designate a shock as an aggregate shock. If so designated, draws from the shock will be scalar rather than array valued.

Parameters:: dist (Distribution)

Model Utilities¶

Simulation Dynamics¶

skagent.block.simulate_dynamics(dynamics, pre, dr)¶

From the beginning-of-period state (pre), follow the dynamics, including any decision rules, to compute the end-of-period state.

Parameters:: dynamics (Mapping[str, Callable]) – Maps variable names to functions from variables to values. Can include Controls ## TODO: Make collection of equations into a named type

preMapping[str, Any]: Bound values for all variables that must be known before beginning the period’s dynamics.
drMapping[str, Callable]: Decision rules for all the Control variables in the dynamics.

Parameters:

pre (Mapping[str, Any])
dr (Mapping[str, Callable])

Shock Construction¶

skagent.block.construct_shocks(shock_data, scope, rng=None)¶

Returns a dictionary from shock labels to Distributions.

When the corresponding value in shock_data contains a distribution constructor and input information, any symbolic expressions used in the inputs are evaluated in the provided scope.

Parameters:

shock_data (Mapping(str, Distribution or tuple)) –

A mapping from variable names to Distribution objects, representing exogenous shocks.

Optionally, the mapping can be to tuples of Distribution constructors and dictionary of input arguments. In this case, the dictionary can map argument names to numbers, or to strings. The strings are parsed as mathematical expressions and evaluated in the scope of a calibration dictionary.

scope: dict(str, values): Variables assigned to numerical values. The scope in which expressions will be evaluated
rng: np.random.Generator, optional: Random number generator to pass to distribution constructors. If provided, distributions created from tuples will use this RNG.

Discretized Shock Distribution¶

skagent.block.discretized_shock_dstn(shocks, disc_params)¶

Discretizes a collection of independent shocks and combines them into one DiscreteDistributionLabeled.

Shocks are discretized only if they have a corresponding element of disc_params defined.

Parameters:

shocks (dict of Distribution) – A dictionary of Distributions, representing independent exogenous shocks.
disc_params (dict of dict) – A dictionary of dictionaries with arguments to Distribution.discretize. Keys of this dictionary should be shared with the shocks argument.