Algorithms

This section contains the API documentation for solution algorithms and optimization methods used to solve economic models.

Value Function Iteration

The Value Function Iteration (VBI) algorithm implements backwards induction to derive value functions from model blocks.

Use backwards induction to derive the arrival value function from a continuation value function and stage dynamics.

skagent.algos.vbi.ar_from_data(da)

Produce a function from any inputs to a given value. This is useful for constructing decision rules with fixed actions.

skagent.algos.vbi.get_action_rule(action)

Produce a function from any inputs to a given value. This is useful for constructing decision rules with fixed actions.

skagent.algos.vbi.grid_to_data_array(grid={})

Construct a zero-valued DataArray with the coordinates based on the Grid passed in.

Parameters:

grid (Grid) – A mapping from variable labels to a sequence of numerical values.

Returns:

An xarray.DataArray with coordinates given by both grids.

Return type:

da xarray.DataArray

skagent.algos.vbi.solve(block, continuation, state_grid, disc_params={}, calibration={})

Solve a DBlock using backwards induction on the value function.

Parameters:

  • block (DBlock)

  • continuation

  • state_grid (Grid) – This is a grid over all variables that the optimization will range over. This should be just the information set of the decision variables.

  • disc_params

  • calibration

Core VBI Functions

skagent.algos.vbi.solve(block, continuation, state_grid, disc_params={}, calibration={})

Solve a DBlock using backwards induction on the value function.

Parameters:

  • block (DBlock)

  • continuation

  • state_grid (Grid) – This is a grid over all variables that the optimization will range over. This should be just the information set of the decision variables.

  • disc_params

  • calibration

skagent.algos.vbi.get_action_rule(action)

Produce a function from any inputs to a given value. This is useful for constructing decision rules with fixed actions.

skagent.algos.vbi.ar_from_data(da)

Produce a function from any inputs to a given value. This is useful for constructing decision rules with fixed actions.

skagent.algos.vbi.grid_to_data_array(grid={})

Construct a zero-valued DataArray with the coordinates based on the Grid passed in.

Parameters:

grid (Grid) – A mapping from variable labels to a sequence of numerical values.

Returns:

An xarray.DataArray with coordinates given by both grids.

Return type:

da xarray.DataArray

Maliar-Style Algorithms

Neural network-based solution methods following Maliar et al.

skagent.algos.maliar.generate_givens_from_states(states, block, shock_copies)

Generates omega_i values of the MMW JME ‘21 method.

states : a grid of starting state values (exogenous and endogenous) block: block information (used to get the shock names) shock_copies : int - number of copies of the shocks to be included.

Parameters:

  • states (Grid)

  • block (Block)

  • shock_copies (int)

skagent.algos.maliar.maliar_training_loop(bellman_period, loss_function, states_0_n, parameters, shock_copies=2, max_iterations=5, tolerance=1e-06, random_seed=None, simulation_steps=1)

bellman_period - a model definition loss_function : callable((df, input_vector) -> loss vector states_0_n : Grid a panel of starting states parameters : dict : given parameters for the model

shock_copies: intnumber of copies of shocks to include in the training set omega

must match expected number of shock copies in the loss function TODO: make this better, less ad hoc

loss_function is the “empirical risk Xi^n” in MMW JME’21.

max_iterations: int

Number of times to perform the training loop, if there is no convergence.

tolerance: float

Convergence tolerance. Training stops when either the L2 norm of parameter changes or the absolute difference in loss is below this threshold.

simulation_stepsint

The number of time steps to simulate forward when determining the next omega set for training

Parameters:

states_0_n (Grid)

Neural Network Components

Net

Base neural network class with device management.

class skagent.ann.Net(n_inputs, n_outputs, width=32, n_layers=2, activation='silu', transform=None, init_seed=None, copy_weights_from=None)

Bases: Module

A flexible feedforward neural network with configurable architecture.

Parameters:

  • n_inputs (int) – Number of input features

  • n_outputs (int) – Number of output features

  • width (int, optional) – Width of hidden layers. Default is 32.

  • n_layers (int, optional) – Number of hidden layers (1-10). Default is 2.

  • activation (str, list, callable, or None, optional) –

    Activation function(s) to use. Options: - str: Apply same activation to all layers (‘silu’, ‘relu’, ‘tanh’, ‘sigmoid’) - list: Apply different activations to each layer, e.g., [‘relu’, ‘tanh’, ‘silu’] - callable: Custom activation function - None: No activation (identity function)

    Available activations: ‘silu’, ‘relu’, ‘tanh’, ‘sigmoid’, ‘identity’ Default is ‘silu’.

  • transform (str, list, callable, or None, optional) –

    Transformation to apply to outputs. Options: - str: Apply same transform to all outputs (‘sigmoid’, ‘exp’, ‘tanh’, etc.) - list: Apply different transforms to each output, e.g., [‘sigmoid’, ‘exp’] - callable: Custom transformation function - None: No transformation

    Available transforms: ‘sigmoid’, ‘exp’, ‘tanh’, ‘relu’, ‘softplus’, ‘softmax’, ‘abs’, ‘square’, ‘identity’ Default is None.

property device

Device property for backward compatibility.

forward(x)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

BlockPolicyNet

Specialized neural network for policy functions in economic models.

class skagent.ann.BlockPolicyNet(bellman_period, control_sym=None, apply_open_bounds=True, width=32, **kwargs)

Bases: Net

A neural network for policy functions in dynamic programming problems.

This network inherits from Net and provides economic model integration. It automatically determines input/output dimensions from the model block specification and handles control variable bounds.

Parameters:

  • bellman_period (BellmanPeriod) – The model Bellman Period

  • apply_open_bounds (bool, optional) – If True, then the network forward output is normalized by the upper and/or lower bounds, computed as a function of the input tensor. These bounds are “open” because output can be arbitrarily close to, but not equal to, the bounds. Default is True.

  • control_sym (string, optional) – The symbol for the control variable.

  • width (int, optional) – Width of hidden layers. Default is 32.

  • **kwargs – Additional keyword arguments passed to Net. See Net class documentation for all available options including activation, transform, n_layers, init_seed, copy_weights_from, etc.

decision_function(states_t, shocks_t, parameters)

A decision function, from states, shocks, and parameters, to control variable values.

Parameters:

  • states_t (dict) – symbols : values

  • shocks_t (dict) – symbols: values

  • parameters (dict) – symbols : values

Returns:

  • decisions - dict – symbols : values

forward(x)

Note that this uses the same architecture of the superclass but adds on a normalization layer appropriate to the bounds of the decision rule.

get_core_function(length=None)
get_decision_function()
get_decision_rule(length=None)

Returns the decision rule corresponding to this neural network.

Training Functions

skagent.ann.aggregate_net_loss(inputs, df, loss_function)

Compute a loss function over a tensor of inputs, given a decision function df. Return the mean.

Parameters:

inputs (Grid)

Grid and Computational Tools

Grid Class

class skagent.grid.Grid(labels, values, torched=True)

Bases: object

A class representing a labeled grid of numerical values.

Parameters:

(dict) (config) – dictionary with the following keys: “min” (float): The minimum value for the variable.; “max” (float): The maximum value for the variable; “count” (int): The number of points to generate for the variable.

classmethod from_config(config={}, torched=True)
classmethod from_dict(kv={}, torched=False)
len()

Returns the number of columns, similar to a dict.

n()

Returns the number of values for each symbol

shape()

Returns the shape of the grid values.

to_dict()

Returns a data structure, key: column, similar to tensordict or structured array.

torch()
update_from_dict(kv)

Grid Utility Functions

skagent.grid.make_grid(config)

Make a ‘grid’ of values based on the provided configuration.

Parameters:

(dict) (config) – dictionary with the following keys: “min” (float): The minimum value for the variable; “max” (float): The maximum value for the variable; “count” (int): The number of points to generate for the variable.

Returns:

  • numpy.ndarray (A NumPy array of shape (product_of_counts, num_variables), where) – product_of_counts is the product of all count values in the config dictionary, and num_variables is the number of keys in the config.

skagent.grid.cartesian_product(*arrays)

Create a Cartesian product of input arrays.

Parameters:

*arrays – Variable length arrays to compute product

Returns:

  • Array of shape (product_of_lengths, num_arrays)

  • where product_of_lengths is the product of the lengths of the input arrays,

  • and num_arrays is the number of input arrays. Each row contains one element

  • of the Cartesian product.

This page is under construction. Content will be added as the API develops.