Rename consumption_unequiv → consumption_dollars; tighten types; drop factory magic

- consumption_unequiv → consumption_dollars (state, action, params,
  module, test module). The dollar / dollars suffix replaces the
  unequiv / equiv pair on the in-$ side; `consumption_equiv` (the
  utility-equivalized form) keeps its name.
- consumption_dollar_grid.py → consumption_dollars_grid.py.
- `_DERIVED_CATEGORICALS` dicts now include `target_his` alongside
  `his`, `good_health`, `is_married`, `pref_type`. The previous
  `BASE_DERIVED_CATEGORICALS` constant + per-factory merge is gone —
  callers pass the full dict.
- `RegimeSpec` TypedDict fields tightened to `Literal[...]` for the
  four axes.
- `fixed_params` annotations switched to `lcm.typing.UserParams` (the
  pylcm-side alias) across `create_model`, `build_all_regimes`,
  `build_grids`.
- `u_working_life` → `u_can_work`; `u_retired` → `u_cannot_work`.
- `_build_per_target_regime_next_assets` →
  `_build_per_target_regime_assets`; ordering of dispatch site and
  definition aligned (assets → health → claimed_ss →
  lagged_labor_supply). `lagged_supply_transition` →
  `lagged_labor_supply_transition`.
- `MAX_CONSUMPTION_DOLLARS` docstring: drop the in-line rationale,
  add a TODO referencing pylcm#348.
- `aca.create_model` return doc → "pylcm Model" (no "ACA-specific"
  qualifier).
- CI: pylcm pin uses `@main` (PyPI release lags so the git pin
  stays).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hmgaudecker

.github/workflows/main.yml

@@ -26,10 +26,10 @@ jobs:
       - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
-      - name: Install pylcm from main (PyPI release lags)
+      - name: Install pylcm
         run: >-
           pip install "pylcm @
-          git+https://github.com/OpenSourceEconomics/pylcm.git@99a5e31"
+          git+https://github.com/OpenSourceEconomics/pylcm.git@main"
       - name: Install aca-model with test deps
         run: pip install -e . pytest pdbp
       - name: Run pytest

src/aca_model/_benchmark_data/benchmark_params.pkl

@@ -8,10 +8,10 @@
 from typing import Any
 
 from lcm import AgeGrid, DiscreteGrid, Model
+from lcm.typing import UserParams
 
 from aca_model.aca import PolicyVariant
 from aca_model.aca.regimes import build_all_regimes
-from aca_model.baseline.derived_categoricals import BASE_DERIVED_CATEGORICALS
 from aca_model.baseline.regimes import RegimeId
 from aca_model.config import MODEL_CONFIG, GridConfig
 
@@ -20,7 +20,7 @@ def create_model(
     *,
     n_subjects: int,
     policy: PolicyVariant,
-    fixed_params: Mapping[str, Any],
+    fixed_params: UserParams,
     wage_params: Mapping[str, Any],
     derived_categoricals: Mapping[str, DiscreteGrid],
     grid_config: GridConfig,
@@ -39,14 +39,15 @@ def create_model(
             `log_ft_wage_std`, `adj_wage_hours_*`) used only at grid-build
             time to size the assets-floor to `-max_annual_labor_income`.
             Not routed to the pylcm Model.
-        derived_categoricals: Extra categorical mappings for derived
-            variables not in the model's state/action grids. `target_his`
-            is added automatically via `BASE_DERIVED_CATEGORICALS`.
+        derived_categoricals: Categorical mappings for `pd.Series`
+            fixed_params index levels that aren't model state/action
+            grids — `target_his`, `his`, `good_health`, `is_married`,
+            `pref_type`.
         grid_config: Continuous-grid point counts.
         pref_type_grid: Pref-type `DiscreteGrid`.
 
     Returns:
-        pylcm Model with ACA-specific function overrides.
+        pylcm Model.
 
     """
     ages = AgeGrid(
@@ -68,6 +69,6 @@ def create_model(
         regime_id_class=RegimeId,
         description=f"Structural retirement model ({policy.name})",
         fixed_params=fixed_params,
-        derived_categoricals={**BASE_DERIVED_CATEGORICALS, **derived_categoricals},
+        derived_categoricals=derived_categoricals,
         n_subjects=n_subjects,
     )

src/aca_model/aca/model.py

@@ -5,6 +5,7 @@
 from typing import Any
 
 from lcm import DiscreteGrid, Regime
+from lcm.typing import UserParams
 
 from aca_model.aca.health_insurance import PolicyVariant
 from aca_model.aca.regimes._overrides import apply_aca_overrides
@@ -17,7 +18,7 @@ def build_all_regimes(
     *,
     policy: PolicyVariant,
     grid_config: GridConfig,
-    fixed_params: Mapping[str, Any],
+    fixed_params: UserParams,
     wage_params: Mapping[str, Any],
     pref_type_grid: DiscreteGrid,
 ) -> dict[str, Regime]:

src/aca_model/aca/regimes/__init__.py

@@ -35,7 +35,7 @@ def cash_on_hand(
     return assets + after_tax_income + ssi_benefit - hic_premium
 
 
-def consumption_unequiv_floor(
+def consumption_dollars_floor(
     consumption_equiv_floor: float,
     equivalence_scale: FloatND,
 ) -> FloatND:
@@ -45,17 +45,17 @@ def consumption_unequiv_floor(
 
 def transfers(
     cash_on_hand: FloatND,
-    consumption_unequiv_floor: FloatND,
+    consumption_dollars_floor: FloatND,
 ) -> FloatND:
     """Government transfers to enforce the consumption floor."""
-    return jnp.maximum(0.0, consumption_unequiv_floor - cash_on_hand)
+    return jnp.maximum(0.0, consumption_dollars_floor - cash_on_hand)
 
 
 def next_assets(
     cash_on_hand: FloatND,
     transfers: FloatND,
     pension_assets_adjustment: FloatND,
-    consumption_unequiv: ContinuousAction,
+    consumption_dollars: ContinuousAction,
     oop_costs: FloatND,
 ) -> ContinuousState:
     """Compute beginning-of-next-period assets for non-terminal targets.
@@ -67,15 +67,15 @@ def next_assets(
         cash_on_hand
         + transfers
         + pension_assets_adjustment
-        - consumption_unequiv
+        - consumption_dollars
         - oop_costs
     )
 
 
 def next_assets_when_dead(
     cash_on_hand: FloatND,
     transfers: FloatND,
-    consumption_unequiv: ContinuousAction,
+    consumption_dollars: ContinuousAction,
     oop_costs: FloatND,
 ) -> ContinuousState:
     """Compute beginning-of-next-period assets for the dead/terminal target.
@@ -86,17 +86,17 @@ def next_assets_when_dead(
     (which would otherwise need to come from a transition `dead` does not
     have, since `aime` is not a state in the terminal regime).
     """
-    return cash_on_hand + transfers - consumption_unequiv - oop_costs
+    return cash_on_hand + transfers - consumption_dollars - oop_costs
 
 
 def borrowing_constraint(
-    consumption_unequiv: ContinuousAction,
+    consumption_dollars: ContinuousAction,
     cash_on_hand: FloatND,
-    consumption_unequiv_floor: FloatND,
+    consumption_dollars_floor: FloatND,
 ) -> BoolND:
     """Consumption cannot exceed post-transfer resources.
 
-    Post-transfer resources are `max(cash_on_hand, consumption_unequiv_floor)`:
+    Post-transfer resources are `max(cash_on_hand, consumption_dollars_floor)`:
     the transfer system tops `cash_on_hand` to the floor when below,
     otherwise resources are unchanged. The algebraic identity is
     `cash_on_hand + transfers == max(cash_on_hand, floor)`; the `max`
@@ -105,4 +105,4 @@ def borrowing_constraint(
     the kink-boundary comparison at large negative values of `assets`.
     The `max` form returns `floor` exactly.
     """
-    return consumption_unequiv <= jnp.maximum(cash_on_hand, consumption_unequiv_floor)
+    return consumption_dollars <= jnp.maximum(cash_on_hand, consumption_dollars_floor)

src/aca_model/agent/assets_and_income.py

@@ -122,14 +122,14 @@ def leisure_retired(
 
 
 def consumption_equiv(
-    consumption_unequiv: ContinuousAction,
+    consumption_dollars: ContinuousAction,
     equivalence_scale: FloatND,
 ) -> FloatND:
     """Utility-equivalized consumption."""
-    return consumption_unequiv / equivalence_scale
+    return consumption_dollars / equivalence_scale
 
 
-def u_working_life(
+def u_can_work(
     consumption_equiv: FloatND,
     leisure: FloatND,
     consumption_weight: FloatND,
@@ -152,7 +152,7 @@ def u_working_life(
     return u * utility_scale_factor
 
 
-def u_retired(
+def u_cannot_work(
     consumption_equiv: FloatND,
     good_health: IntND,
     consumption_weight: FloatND,
@@ -167,7 +167,7 @@ def u_retired(
         time_endowment=time_endowment,
         leisure_cost_of_bad_health=leisure_cost_of_bad_health,
     )
-    return u_working_life(
+    return u_can_work(
         consumption_equiv=consumption_equiv,
         leisure=leisure,
         consumption_weight=consumption_weight,
@@ -233,7 +233,7 @@ def discount_factor(
 
 
 def utility_scale_factor(
-    average_consumption_unequiv: float,
+    average_consumption_dollars: float,
     consumption_weight: FloatND,
     coefficient_rra: FloatND,
     time_endowment: float,
@@ -242,7 +242,7 @@ def utility_scale_factor(
 ) -> FloatND:
     """Compute the scale factor so utility is approximately 1 at typical values."""
     average_leisure = time_endowment - reference_hours - fixed_cost_of_work_intercept
-    u_cons = average_consumption_unequiv**consumption_weight
+    u_cons = average_consumption_dollars**consumption_weight
     u_leisure = average_leisure ** (1.0 - consumption_weight)
 
     one_minus_rra = jnp.where(

src/aca_model/agent/preferences.py

@@ -14,16 +14,16 @@
 from typing import Any
 
 from lcm import AgeGrid, DiscreteGrid, Model
+from lcm.typing import UserParams
 
-from aca_model.baseline.derived_categoricals import BASE_DERIVED_CATEGORICALS
 from aca_model.baseline.regimes import RegimeId, build_all_regimes
 from aca_model.config import MODEL_CONFIG, GridConfig
 
 
 def create_model(
     *,
     n_subjects: int,
-    fixed_params: Mapping[str, Any],
+    fixed_params: UserParams,
     wage_params: Mapping[str, Any],
     derived_categoricals: Mapping[str, DiscreteGrid],
     grid_config: GridConfig,
@@ -42,11 +42,10 @@ def create_model(
             `log_ft_wage_std`, `adj_wage_hours_*`) used only at grid-build
             time to size the assets-floor to `-max_annual_labor_income`.
             Not routed to the pylcm Model.
-        derived_categoricals: Extra categorical mappings for derived
-            variables not in the model's state/action grids. Needed when
-            `fixed_params` contains `pd.Series` indexed by DAG function
-            outputs. `target_his` is added automatically via
-            `BASE_DERIVED_CATEGORICALS`.
+        derived_categoricals: Categorical mappings for `pd.Series`
+            fixed_params index levels that aren't model state/action
+            grids — `target_his`, `his`, `good_health`, `is_married`,
+            `pref_type`.
         grid_config: Continuous-grid point counts. Pass `GRID_CONFIG` for
             production values or `BENCHMARK_GRID_CONFIG` for the
             fast-but-structurally-faithful benchmark.
@@ -77,6 +76,6 @@ def create_model(
         regime_id_class=RegimeId,
         description="Baseline structural retirement model (pre-ACA)",
         fixed_params=fixed_params,
-        derived_categoricals={**BASE_DERIVED_CATEGORICALS, **derived_categoricals},
+        derived_categoricals=derived_categoricals,
         n_subjects=n_subjects,
     )

src/aca_model/baseline/derived_categoricals.py

@@ -14,6 +14,7 @@
 from typing import Any
 
 from lcm import DiscreteGrid, Regime
+from lcm.typing import UserParams
 
 from aca_model.baseline.regimes import _nongroup as nongroup
 from aca_model.baseline.regimes import _retiree as retiree
@@ -60,7 +61,7 @@ def build_regime(name: str, grids: Grids) -> Regime:
 def build_all_regimes(
     *,
     grid_config: GridConfig,
-    fixed_params: Mapping[str, Any],
+    fixed_params: UserParams,
     wage_params: Mapping[str, Any],
     pref_type_grid: DiscreteGrid,
 ) -> dict[str, Regime]: