Emit one terminal-regime row per subject in to_dataframe by hmgaudecker · Pull Request #396 · OpenSourceEconomics/pylcm

hmgaudecker · 2026-07-02T20:45:19Z

Closes #386.

What this PR does

SimulationResult.to_dataframe gains a terminal_rows knob:

df = result.to_dataframe()                      # terminal_rows="first" (default)
df = result.to_dataframe(terminal_rows="all")   # absorbing representation

Terminal regimes are absorbing: a subject that enters one is carried with frozen state through every later period the regime is active, so its one-shot terminal payoff (e.g. a bequest) is re-emitted again and again. With "first" (the new default), each subject keeps only its terminal entry row — a dead subject appears once at death, like leaving a panel. "all" reproduces the previous output.

For a subject that dies at age 70:

terminal_rows="all"

subject_id	age	regime_name
0	60	alive
	70	dead
	80	dead

terminal_rows="first" (default)

subject_id	age	regime_name
0	60	alive
	70	dead

Implementation

A post-hoc filter on the assembled flat frame (_keep_first_terminal_row in lcm/result.py): group by subject, keep every row up to and including the first period in a terminal regime; subjects that never enter one keep all rows. The filter runs before the categorical conversion, so it applies identically under use_labels=False. No change to the simulation internals — the fixed-population kernels and the n_subjects invariant stay intact.

Tests

On the Epstein–Zin mortality example (multi-age terminal dead regime, certain death by the horizon): exactly one dead row per subject; "first" equals "all" with each subject's post-entry rows dropped (assert_frame_equal); "all" emits one row per subject and period; "first" is the default; the filter composes with integer codes. Full suite green — no existing test relied on the duplicated rows.

Base branch

Targets feat/certainty-equivalent (#395), whose Epstein–Zin example provides the multi-age terminal test model; lands on main via the usual cascade.

🤖 Generated with Claude Code

…river) Two tests on the 4-CPU distributed seam: - test_distributed_solve_matches_single_device_per_type: the F6 correctness contract — a sharded solve must equal the single-device solve per type slice. Green now; the co-map fix must preserve it (catches a wrong device-local index). - test_distributed_solve_kernel_does_not_all_gather_continuation_v: the red driver — the backward-induction kernel currently all-gathers the continuation V across the type shard; it must read only its device-local slice. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

vmap_1d gains co_mapped_in_axes: an optional per-argument in_axes override so a pytree argument's leading axis can be mapped in lockstep with the mapped variables. The backward-induction co-map uses it to slice each next_regime_to_V_arr leaf to the device-local type, so the continuation-V interpolation reads only its own shard. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Fixed, distributed states (e.g. a permanent type sharded one block per device) never transition, so a regime's continuation value depends only on its own slice of the next-period V-array. The grid-search solve kernel now co-maps each such state with the matching axis of every next_regime_to_V_arr leaf that carries it: an outer vmap peels the leading axis off both the state grid and the continuation V, so the interpolation reads only the device-local slice and XLA inserts no all-gather of the full V-array onto every device. - max_Q_over_a splits the co-mapped (leading) states from the inner productmap and wraps it in per-state co-map vmaps; the V-interpolator drops those coordinates and Q_and_F omits the sliced next-states. - processing detects the co-mappable states (distributed and identity-transition) and builds per-state, per-leaf in_axes so a target regime that prunes the state keeps its full leaf. - Simulation is unchanged: it keeps the full continuation V (subjects are not type-aligned across devices), so the co-map applies to the solve path only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…nuation-v

…seam (#385) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>