Quickstart Guide¶

Get up and running with scikit-agent in minutes. This guide covers the basic concepts and shows you how to create, solve, and simulate your first economic model.

Installation¶

First, install scikit-agent:

pip install scikit-agent

For development installation:

git clone https://github.com/scikit-agent/scikit-agent.git
cd scikit-agent
pip install -e ".[dev,docs]"

Core Concepts¶

scikit-agent is built around several key concepts:

DBlock (Dynamic Block)¶

A DBlock represents a “block” of model behavior with:

Shocks: Random variables that affect the model
Dynamics: Equations describing how variables evolve
Controls: Decision variables that agents optimize
Rewards: Objective functions that agents maximize

Grid¶

A Grid represents discrete state spaces for numerical solutions.

Simulators¶

Monte Carlo simulation engines for analyzing model behavior.

Your First Model: Consumption-Saving¶

Let’s create a simple consumption-saving model step by step.

Step 1: Import scikit-agent¶

import numpy as np
import skagent as ska
from skagent.models.consumer import consumption_block, cons_problem, calibration

Step 2: Examine the Pre-built Model¶

The consumption block defines a standard consumption-saving problem:

print("Model dynamics:")
for var, eq in consumption_block.dynamics.items():
    print(f"  {var}: {eq}")

print("\nModel shocks:")
for shock, dist in consumption_block.shocks.items():
    print(f"  {shock}: {dist}")

Step 3: Set Up Model Parameters¶

# Use the default calibration or modify it
my_calibration = calibration.copy()
my_calibration.update(
    {
        "DiscFac": 0.95,  # Discount factor
        "CRRA": 2.5,  # Risk aversion
        "R": 1.04,  # Interest rate
    }
)

print("Calibration:")
for param, value in my_calibration.items():
    print(f"  {param}: {value}")

Step 4: Assemble the Recursive Problem¶

A single DBlock describes one period of behavior. To simulate over time, the end-of-period assets a must become next period’s capital k. The prebuilt cons_problem is an RBlock that chains a normalized consumption block with a small “tick” block doing exactly that:

print("Recursive problem blocks:")
for block in cons_problem.blocks:
    print(f"  {block.name}: {list(block.get_dynamics().keys())}")

There is no need to construct the shock distributions by hand; the simulator builds them from the calibration internally.

Step 5: Create a Simple Decision Rule¶

For this example, we’ll use a simple consumption rule (consume 90% of resources):

def simple_consumption_rule(m):
    """Simple rule: consume 90% of market resources"""
    return 0.9 * m


# Wrap in the format expected by the simulator
decision_rules = {"c": simple_consumption_rule}

Step 6: Run a Simulation¶

# Set up initial conditions
initial_conditions = {
    "k": 1.0,  # Initial capital
}

# Create simulator
simulator = ska.MonteCarloSimulator(
    calibration=my_calibration,
    block=cons_problem,
    dr=decision_rules,
    initial=initial_conditions,
    agent_count=1000,
    T_sim=50,
    seed=42,
)

# Run simulation
print("Running simulation...")
simulator.initialize_sim()
results = simulator.simulate()

print(f"Simulation completed. History keys: {list(results.keys())}")

Step 7: Analyze Results¶

import matplotlib.pyplot as plt

# Plot average consumption over time. The history values are numpy
# arrays of shape (T_sim, agent_count).
if "c" in simulator.history:
    consumption_data = simulator.history["c"]
    mean_consumption = np.mean(consumption_data, axis=1)

    plt.figure(figsize=(10, 6))
    plt.plot(mean_consumption)
    plt.title("Average Consumption Over Time")
    plt.xlabel("Period")
    plt.ylabel("Consumption")
    plt.grid(True)
    plt.show()

Working with Grids¶

For more sophisticated solution methods, you’ll work with grids:

# Create a grid for wealth
wealth_grid_config = {"m": {"min": 0.1, "max": 10.0, "count": 50}}

wealth_grid = ska.Grid.from_config(wealth_grid_config)
print(f"Grid shape: {wealth_grid.shape()}")
print(f"First few wealth points: {wealth_grid['m'][:5]}")

Neural Network Solutions¶

scikit-agent supports neural network-based solution methods. Policy networks are built on a BellmanPeriod, which wraps a block together with its discount variable and calibration:

from skagent.bellman import BellmanPeriod

# Wrap the block as a Bellman period, then create a policy network
bp = BellmanPeriod(consumption_block, "DiscFac", my_calibration)
policy_net = ska.BlockPolicyNet(bp, width=64)

print(f"Neural network input size: {policy_net.layers[0].in_features}")
print(f"Neural network output size: {policy_net.output.out_features}")

Next Steps¶

After completing this quickstart:

Learn more about blocks: Read the Block Guide guide to understand different model types and how to create custom models
Explore algorithms: Check out the Algorithms Guide guide for different solution methods including value function iteration and neural network approaches
Master simulation: See the Simulation Guide guide for advanced simulation techniques and analysis methods
Browse examples: Look at the Examples for more complex examples and use cases

Key Takeaways¶

DBlocks are the fundamental building blocks for economic models
Grids discretize continuous state spaces for numerical methods
Simulators generate synthetic data from solved models
Decision rules map states to optimal actions
The package follows scikit-learn conventions for a familiar API

You’re now ready to build more sophisticated economic models with scikit-agent!