Fast Upper-Envelope Scan (FUES)

Docs · Notebooks · Paper

---

FUES recovers the upper envelope of the EGM (Carroll 2006) value correspondence in discrete-continuous problems without requiring monotonicity of the optimal policy or numerical optimisation. FUES can also perform orders of magnitude faster than existing upper-envelope methods.

This repo ships a unified upper-envelope interface (uenvelope) that dispatches to FUES and three benchmark methods: MSS (Iskhakov et al. 2017), LTM (Druedahl & Jørgensen 2017), and RFC (Dobrescu & Shanker 2024).

Pre-release (v0.6.0dev1) — Under active development. API may change.

Dobrescu, L.I. and Shanker, A. (2022). "A fast upper envelope scan method for discrete-continuous dynamic programming." SSRN Working Paper.

---

Install

The installable package is dcsmm (contains fues and uenvelope). Requires Python 3.11+.

Option 1 — Library only

Install FUES and the upper-envelope interface without cloning the repo. Lets you use fues and all other benchmark upper-envelope methods in your own applications.

pip install git+https://github.com/akshayshanker/FUES.git

from dcsmm.fues import FUES
from dcsmm.uenvelope import EGM_UE

Runtime dependencies (numba, numpy, scipy, HARK, ConSav) are installed automatically. See pyproject.toml for the full list and version pins.

Option 2 — With examples

Clone the repo and install with example dependencies (matplotlib, pyyaml, seaborn, kikku). Includes everything in Option 1 plus the example models in the repo checkout.

git clone https://github.com/akshayshanker/FUES.git
cd FUES
pip install ".[examples]"

Each example can be run as a simple single solve via run.py:

python examples/retirement/run.py --grid-size 3000

See the retirement example docs for CLI arguments, parameter overrides, and outputs. The interactive notebook walks through the model step by step.

Formal benchmarking and parameter sweeps are run on an HPC cluster using the PBS scripts in experiments/retirement/. Pre-computed paper results (tables and figures) are in replication/.

Option 3 — Developer (editable)

Full setup with editable install, examples, and all dependencies including the dolo-plus compiler. Use this if you are modifying the source.

git clone https://github.com/akshayshanker/FUES.git
cd FUES
bash setup/setup_venv.sh
source .venv/bin/activate

This creates a local .venv, installs dcsmm in editable mode, and verifies the install.

Run the full timing sweep:

python examples/retirement/run.py --run-timings

---

Package layout

Module	Description
src/dcsmm/fues/	FUES algorithm + rooftop-cut (RFC)
src/dcsmm/uenvelope/	Unified dispatch to FUES, MSS, RFC, LTM

External methods wrapped by uenvelope

Package	Method	Reference
HARK	MSS	Iskhakov et al. (2017)
ConSav	LTM	Druedahl & Jørgensen (2017)
Native	RFC	Dobrescu & Shanker (2024)

Directory structure

FUES/
├── src/dcsmm/            # installable package
│   ├── fues/             # FUES + variants
│   └── uenvelope/        # upper-envelope registry
├── examples/
│   ├── retirement/       # retirement choice (+ notebooks/)
│   ├── durables/         # durables with adjustment frictions
│   └── housing_renting/  # discrete housing + capital tax
├── experiments/          # PBS/HPC scripts with param overrides
├── replication/          # paper tables + figures (committed outputs)
├── setup/                # setup_venv.sh, load_env.sh
└── docs/                 # mkdocs site

---

References

• Carroll, C.D. (2006). "The method of endogenous gridpoints for solving dynamic stochastic optimization problems." Economics Letters, 91(3), 312–320.
• Dobrescu, L.I. and Shanker, A. (2022). "A fast upper envelope scan method for discrete-continuous dynamic programming." SSRN Working Paper No. 4181302.
• Dobrescu, L.I. and Shanker, A. (2024). "Using Inverse Euler Equations to Solve Multidimensional Discrete-Continuous Dynamic Models." SSRN Working Paper No. 4850746.
• Druedahl, J. and Jørgensen, T.H. (2017). "A general endogenous grid method for multi-dimensional models with non-convexities and constraints." JEDC, 74, 87–107.
• Druedahl, J. (2021). "A guide on solving non-convex consumption-saving models." Computational Economics, 58, 747–775.
• Fella, G. (2014). "A generalized endogenous grid method for non-smooth and non-concave problems." Review of Economic Dynamics, 17(2), 329–344.
• Iskhakov, F., Jørgensen, T.H., Rust, J. and Schjerning, B. (2017). "The endogenous grid method for discrete-continuous dynamic choice models with (or without) taste shocks." Quantitative Economics, 8(2), 317–365.