User Guide

This guide covers how to build, solve, and simulate economic models with scikit-agent.

What is scikit-agent?

scikit-agent is a Python package for agent-based economic modeling that follows scikit-learn conventions. Models are built from composable blocks, each representing a stage or aspect of economic behavior. Several solution methods are available, including value function iteration and neural-network methods; for a model with several decisions or several agents, one of these methods combines with a schedule that decides when each decision is solved. Monte Carlo simulators generate synthetic panel data from a model and its decision rules, handling heterogeneity, aging, and other complex dynamics. The API follows familiar Python conventions throughout.

Getting Started

If you’re new to scikit-agent, start here:

• Installation - Install scikit-agent and set up your environment

• Quickstart Guide - Build and simulate your first model in minutes

Core Concepts

Learn about the fundamental concepts and components:

• Block Guide - Understanding model structure and building custom models

• Reading Model Diagrams - Reading a model’s diagram: the shapes, the plates, and what is not drawn

• Simulation Guide - Monte Carlo simulation and analysis

• Algorithms Guide - Solution methods for solving your models

• Solving Models with the Maliar Method - Neural-network solution via the Maliar method

• Environments Guide - Interactive adapters for reinforcement-learning algorithms

• Constraining an Optimization Problem - The ways to constrain decisions and how solvers enforce them

Topics Covered

• Installation
  • Requirements
  • Install from PyPI
  • Install from Source
  • Development Installation
  • Verify Installation
• Quickstart Guide
  • Installation
  • Core Concepts
  • Simulate a Prebuilt Model
  • Solve for an Optimal Policy
  • Next Steps
  • Key Takeaways
• Block Guide
  • Understanding Model Structure
  • Authoring Blocks for Dynamic Programming
  • Model Validation and Inspection
  • Next Steps
  • Common Patterns
• Reading Model Diagrams
  • Producing a Diagram
  • The Shape Vocabulary
  • Color, Dashing, and Layout
  • Entity Classes as Plates
  • What Is Not Drawn
  • Precedent
  • Configuring the Style
  • Seeing It Rendered
• Simulation Guide
  • Simulation Configuration
  • Running Simulations
  • Analyzing and Visualizing Data
• Algorithms Guide
  • Solution methods
  • Reinforcement Learning
  • Solving a block directly
  • Blocks with more than one decision
  • Value Function Iteration
• Solvers Guide
  • Two pieces: a method and a schedule
  • Choosing a schedule
  • Projecting a population
• Solving Models with the Maliar Method
  • The All-in-One Expectation Operator
  • Two Residual Losses
  • Running the Training Loop
  • Constrained Controls
  • Worked Examples
• Environments Guide
  • Why environments?
  • Environment: stepping a model in plain Python
  • GymEnv: a gymnasium environment for RL libraries
• Constraining an Optimization Problem
  • Declaring Bounds
  • Feasibility by Construction: Bounded Policy Networks
  • Optimality at the Bound: Fischer-Burmeister Complementarity
  • Using Both Together
  • Where Each Mechanism Is Available
• Benchmark Models
  • Roster
  • Using the Registry
  • See Also

Need Help?

• Examples: Browse the Examples for complete working examples

• API Reference: See API Reference for detailed class and function documentation

• GitHub Issues: Report bugs or request features at github.com/scikit-agent/scikit-agent

Contributing

scikit-agent is an open-source project and welcomes contributions, including bug reports, new features, code, documentation, and examples. See our contribution guidelines in the repository for how to get involved.

---

Head to the Quickstart Guide guide to get started.