KS Models

Reusable Krusell-Smith numerical methods, benchmark notebooks, and solver-validation helpers. The package is published on PyPI as:

pip install ks-models

PyPI page: https://pypi.org/project/ks-models/

Methods PDF

The companion methods note is included at the repository root:

• KS_Solution_Methods.pdf: Three Numerical Implementations of the Krusell-Smith Model: KS-VFI, KS-HARK, and KS-NN.

Use this PDF as the technical reference for the benchmark model, solver comparison, and interpretation of the VFI/HARK/NN outputs.

Methods

The repository contains comparative implementations of the frictionless Krusell-Smith benchmark:

Method	Folder	Household block	Aggregate law of motion	Aggregate shock process
KS_VFI	KS_VFI/	Numba VFI + golden-section search	Log-linear OLS PLM	2-state: Z ∈ {−0.01, 0.01}, 98% persistence
KS_HARK	KS_HARK/	HARK MarkovConsumerType (EGM)	Log-linear OLS PLM	2-state: Z ∈ {−0.05, 0.05}, 87.5% persistence
KS_NN	KS_NN/	EGM policy iteration + deterministic distribution transition	Neural-network PLM (PyTorch)	41-state AR(1) discretization

Comparability note: the three methods use different shock calibrations. Cross-method comparisons of σ_K, PLM R², and RMSE reflect differences in the economic environment as well as the solver, and should be read as within-method diagnostics.

Public Repository Scope

This public repository is distributed as a clean source-first research codebase. It includes the method implementations, calibration files, method notebooks, the compiled companion PDF, and the benchmark registry in runs/run_log.csv.

It intentionally excludes most generated run artifacts, cached notebook outputs, temporary files, and large regenerable figure collections. The public notebooks ship without stored outputs and should be executed locally to reproduce plots and benchmark runs.

Environment Setup

Install the public library from PyPI:

pip install ks-models

Or install the local checkout in editable mode:

pip install -e .

Basic library use:

from ks_models.grids import sequence_jacobian_asset_grid
from ks_models.markov import stationary_distribution
from ks_models.problems import DiscreteHouseholdProblem
from ks_models.solvers.vfi import solve_discrete_vfi

Optional thesis adapters live under ks_models.adapters. They are not needed for generic KS use and only work when the corresponding thesis project is on PYTHONPATH.

Runnable examples:

python examples/generic_vfi_example.py

Tutorial notebook:

• examples/ks_models_library_demo.ipynb

For the optional thesis V5 validation use case, run from the thesis repository:

PYTHONPATH=03_MODELS/ks_baseline_methods/KS_models/src:03_MODELS \
python 03_MODELS/ks_baseline_methods/KS_models/examples/v5_cross_solver_example.py

Preferred setup:

conda env create -f environment.yml
conda activate ks_models

Pip fallback:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Central Calibration And SS

The shared calibration is centralized under calibration/:

• calibration/ks_ss_data.py: single source of truth for parameters + active SS loading.
• calibration/ks_ss_computation.py: continuous-time SS routine (CT benchmark).
• calibration/ks_ss_computation_discrete.py: discrete-time SS routine (DT benchmark).
• calibration/ss_results.csv: CT SS output consumed by the central loader.
• calibration/ss_results_discrete.csv: DT SS output consumed by the central loader.
• calibration/calibrate_rho_by_mode.py: per-method/per-mode rho calibration.
• calibration/rho_profiles.json: calibrated rho profiles consumed by notebooks.
• calibration/runtime_controls.py: shared notebook runtime setup helper (mode/profile/anchor env exports).

Current deep calibration constants (from calibration/ks_ss_data.py):

• alpha = 0.35
• delta = 0.10
• gamma = 2.0
• RHO_BASE = 0.05
• dt = 1/12

Runtime Controls

Each notebook first cell exposes only two settings:

Setting	Values	Description
RUN_PROFILE_NOTEBOOK	"smoke" or "definitive"	Quick test vs. full benchmark run
SS_MODE_NOTEBOOK	"discrete" or "continuous"	Steady-state target selection

To change advanced parameters (damping schedule, OOS thresholds, NN training hyper-parameters, etc.),
edit the params.py in the respective method folder:

Method	File	Section
KS_VFI	KS_VFI/params.py	Section 4: Notebook Runtime Defaults
KS_HARK	KS_HARK/params.py	Section 4: Notebook Runtime Defaults
KS_NN	KS_NN/params.py	Section 5: Notebook Runtime Defaults

After any change: restart kernel and run all cells.

All three notebooks call calibration/runtime_controls.py::setup_notebook(...) in the first code cell. That bootstrap applies SS mode, rho-profile override, and PLM anchor environment flags before importing method modules.

What Changes By Mode

When you switch SS_MODE_NOTEBOOK:

• The deterministic SS target changes (continuous -> K_ss ≈ 3.6869, discrete -> K_ss ≈ 3.5448).
• The SS source file changes (calibration/ss_results.csv vs calibration/ss_results_discrete.csv).
• If USE_RHO_PROFILE_NOTEBOOK=True, only rho is overridden per method/mode from calibration/rho_profiles.json.

What does not change:

• The economic model structure and core solvers (VFI/HARK/NN algorithms) are unchanged.
• Deep parameters alpha, delta, gamma, dt, shock structure, and grid logic remain method defaults unless you edit code.

After changing any runtime control:

1. Restart kernel.
2. Run all cells.

Typical Workflow

1. Activate environment:

conda activate ks_models

2. (Optional) Recompute steady states and recalibrate rho profiles:

python calibration/ks_ss_computation.py
python calibration/ks_ss_computation_discrete.py
python calibration/calibrate_rho_by_mode.py --method all --mode both --max-evals 6 --tol-k 0.005

These SS scripts save directly to calibration/ss_results.csv and calibration/ss_results_discrete.csv (not the repository root).

3. Run notebooks:

• KS_VFI/run.ipynb
• KS_HARK/run.ipynb
• KS_NN/run.ipynb

All methods log to runs/run_log.csv.

Notebooks in the public repo are intentionally stored without execution outputs. Run them locally to regenerate diagnostics, tables, and figures.

Repository Layout

KS_models/
├── calibration/
│   ├── ks_ss_data.py
│   ├── ks_ss_computation.py
│   ├── ks_ss_computation_discrete.py
│   ├── calibrate_rho_by_mode.py
│   ├── rho_profiles.json
│   ├── ss_results.csv
│   └── ss_results_discrete.csv
├── KS_VFI/
├── KS_HARK/
├── KS_NN/
├── KS_Solution_Methods.pdf
└── runs/

License

This repository is released under the MIT License. See LICENSE.