DISCUSS: Migration path from legacy RandomState to NumPy Generator

The decision needed

Our RNG plumbing is the 2015-era scikit-learn idiom: check_random_state (util/random.py) normalizes to np.random.RandomState, reaches into np.random.mtrand._rand for the global instance, and rng_integers exists solely to bridge RandomState/Generator signature differences. NumPy has recommended Generator/default_rng since 1.17 (2019): the actively developed API, faster bit generators, better streams. We accept Generator today, but every internal default and documented example takes the legacy path.

This is a decision, not a patch, because reproducibility is the product: for integer seeds, default_rng(seed) and RandomState(seed) produce different streams, so a silent default switch changes every seeded simulation result in downstream research and the QuantEcon lectures.

Questions for this thread

1. Do we migrate defaults at all, or only document Generator as the preferred input?
2. If we migrate: flag-day at a major-ish version with a loud changelog, or a transition period where integer seeds emit a FutureWarning naming the change date?
3. What do the lecture repositories need from us (coordination, pinned examples)?
4. Does check_random_state grow a default="generator" parameter, or do we adopt np.random.default_rng passthrough plus spawn for parallel paths?

Suggested outcome

A short policy (target version, warning strategy, docs plan) recorded here, then this thread closes and spawns the implementation issue. Related: the vendoring of rng_integers (this milestone) is worth doing first regardless; a completed migration eventually deletes the vendored copy too.

From the July 2026 technical-debt audit (AI-assisted; claims verified against 28d4b3b on 2026-07-25).

Start by reading util/random.py, especially check_random_state and rng_integers, then review the reproducibility concern around RandomState versus Generator. Compare the migration and documentation options raised in the four questions, including the lecture repositories and vendored rng_integers. Done means agreeing on a short policy covering the target version, warning strategy, and docs plan, then opening a separate implementation issue.