Blocks

This section contains the API documentation for model building blocks.

Block Classes

Block

Base class for all blocks. Provides shared analysis methods, including strategic-relevance analysis (relevance_graph, relies_on).

class skagent.block.Block

Bases: object

display(calibration)

Displays (as in a notebook) an SVG of the visualized graph of this block.

Base style configuration is in model_visualizatio_config.yaml

Parameters:

calibration (dict) – A dictionary of parameters used for calibration. Here, it indicates which symbols are not dynamic.

Returns:

  • img (matplotlib.image.mpimg)

  • svg_content (str)

display_formulas()

Prints the model’s formulas.

formulas(calibration)

Returns a dictionary of string representations of the block’s dynamic formulas.

Parameters:

calibration (dict) – A dictionary of parameters used for calibration. Here, it indicates which symbols are not dynamic.

get_arrival_states(calibration=None)
Return a list of symbols that are:

  • required by the dynamic equations of the block

  • dynamic variables themselves (controlled by dynamic equations)

This is the list of symbols that are implicitly ‘lagged’, or must be provided ‘on arrival’.

Parameters:

calibration (dict, optional) – A dictionary of parameters used for calibration. Here, it indicates which symbols are not dynamic.

get_attributions()

Return the agent assignments of variables as a dict of the form {“agent1” : [“var1”, “var2”, … ], “agent2” : [“var3”, “var4”, …]}

get_controls()

Returns only the Control variables from the Block dynamics.

relevance_graph(calibration=None)

Return the strategic-relevance graph over this block’s controls.

Nodes are the block’s control (decision) variables; a directed edge d1 -> d2 means decision d1 strategically relies on decision d2 (Koller & Milch s-reachability). See skagent.relevance.

Parameters:

calibration (dict, optional) – Calibration parameters, used only to identify parameter symbols. Relevance is a structural property, so this defaults to an empty dict.

Return type:

skagent.relevance.RelevanceGraph

relies_on(first, second, calibration=None)

Whether control first strategically relies on control second.

first relies on second when, to optimize the decision rule at first, the agent must account for the decision rule at second.

Parameters:

  • first (str) – Control variable names in this block. A name that is not a control raises ValueError.

  • second (str) – Control variable names in this block. A name that is not a control raises ValueError.

  • calibration (dict, optional) – See relevance_graph().

Return type:

bool

shock_roles(calibration=None)

How each shock relates to each control’s information set.

For every control, classifies every shock as observed (the information set accounts for it, so a solver may condition on it), hidden (it must be integrated out inside the maximization), or mixed (partly informed and separately relevant, which needs filtering). See skagent.relevance for the criterion.

Parameters:

calibration (dict, optional) – Calibration parameters, used only to identify parameter symbols. Defaults to empty, as for relevance_graph().

Returns:

{control: {shock: role}}.

Return type:

dict

visualize(calibration)

Return a PyDot graph visualization of this block.

Base style configuration is in model_visualization_config.yaml

Parameters:

calibration (dict) – A dictionary of parameters used for calibration. Here, it indicates which symbols are not dynamic.

Returns:

  • graph (pydot.core.Dot) – A PyDot graph representation of the model.

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 (dict) –

    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 (dict) – 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 (dict) – 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, agent=None)

Computes the reward for a given set of variable values

Parameters:

  • vals (Mapping[str, Any]) – Values for every variable the reward formulas depend on.

  • agent (str, optional) – If given, compute only the reward variables attributed to this agent. Their sum is that agent’s payoff. Defaults to all reward variables in the block.

Returns:

Mapping from reward variable to value.

Return type:

dict

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.

Parameters:

  • name (str | None, optional) – New name for the block. If None, keeps the original name.

  • description (str | None, optional) – New description. If None, keeps the original description.

  • shocks (dict | None, optional) – Dictionary of shocks to merge with existing shocks.

  • dynamics (dict | None, optional) – Dictionary of dynamics to merge with existing dynamics.

  • reward (dict | None, optional) – Dictionary of rewards to merge with existing rewards.

Returns:

A new DBlock instance with the merged values.

Return type:

DBlock

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.

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.

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:
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 (number, callable, or None) – The lower bound of the control variable. A number is treated as a constant bound; a callable is an ‘equation function’ whose parameter names are variables in iset. None leaves the control unbounded below.

  • upper_bound (number, callable, or None) – The upper bound of the control variable, declared the same way as lower_bound. None leaves the control unbounded above.

  • 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, Union[Callable, Control]]) – Maps variable names to functions from variables to values. Can include Controls

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:

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.