Krusell-Smith Models (TFM 2026)

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 thesis/manuscript source under documents/, the thesis-facing figure assets under documents/Figures/, 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

The reusable library lives under src/ks_models and can be installed locally:

pip install -e .

After installation, thesis cross-solver validation can be run with:

ks-v5-cross-solve --grids 100 500 2000

The package is structurally ready for TestPyPI/PyPI publication once the public package name, versioning policy, and thesis citation policy are finalized. Until then, local editable installs or pinned Git installs are preferable for thesis reproducibility.

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/
├── runs/
└── documents/

License

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