Metadata-Version: 2.4
Name: ks-models
Version: 0.1.1
Summary: Reusable Krusell-Smith numerical methods, grids, Markov tools, and solver validation helpers.
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Dynamic: license-file

# KS Models

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

```bash
pip install ks-models
```

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

The repository also includes the companion solution-methods paper:

- [`documents/KS_Solution_Methods.pdf`](documents/KS_Solution_Methods.pdf)
- [`documents/KS_Solution_Methods.tex`](documents/KS_Solution_Methods.tex)

## 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 manuscript source under `documents/`, the paper 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

Install the public library from PyPI:

```bash
pip install ks-models
```

Or install the local checkout in editable mode:

```bash
pip install -e .
```

Basic library use:

```python
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:

```bash
python examples/generic_vfi_example.py
```

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

```bash
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:

```bash
conda env create -f environment.yml
conda activate ks_models
```

Pip fallback:

```bash
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`](KS_VFI/params.py)   | **Section 4: Notebook Runtime Defaults** |
| KS_HARK | [`KS_HARK/params.py`](KS_HARK/params.py) | **Section 4: Notebook Runtime Defaults** |
| KS_NN   | [`KS_NN/params.py`](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:

```bash
conda activate ks_models
```

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

```bash
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

```text
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`.
