Accept pd.Series in params and pd.DataFrame in initial conditions

[hmgaudecker]

Summary

@timmens was right in his comments on #272
— requiring a separate preprocessor call before solve() / simulate()
was too clunky. Took me a while to come around, but here we are: pandas
objects are now accepted directly.

• model.solve() and model.simulate() accept pd.Series values in
  params — labeled Series with a named MultiIndex are converted to
  correctly shaped JAX arrays automatically.
• model.simulate() accepts a pd.DataFrame as initial_conditions —
  regime name mapping and discrete label encoding happen transparently.
• Add derived_categoricals parameter to solve() / simulate() for
  DAG function outputs not in the model's state/action grids.
• Extract broadcast_to_template as the single params tree traversal
  primitive — process_params and _resolve_fixed_params become
  one-line wrappers.
• AST-based _get_func_indexing_params — inspects function source for
  subscript patterns to determine array dimensions, with required
  array_param_name to avoid false positives.

Test plan

• All 813 tests pass (pixi run -e tests-cpu tests)
• Pre-commit hooks pass (prek run --all-files)
• Type checking passes (pixi run -e type-checking ty)
• Review auto-conversion in model.py (_maybe_convert_series,
  _maybe_convert_dataframe)
• Review convert_series_in_params and array_from_series in
  pandas_utils.py
• Review broadcast_to_template in params_processing.py

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 pylcm | 🛠️ Build #31992545 | 📁 Comparing 9b570a5 against latest (14b3fef)

🔍 Preview build

Show files changed (32 files in total): 📝 32 modified | ➕ 0 added | ➖ 0 deleted

File	Status
index.html	📝 modified
approximating-continuous-shocks/index.html	📝 modified
benchmarking/index.html	📝 modified
benchmarking-1/index.html	📝 modified
beta-delta/index.html	📝 modified
conventions/index.html	📝 modified
debugging/index.html	📝 modified
defining-models/index.html	📝 modified
dispatchers/index.html	📝 modified
function-representation/index.html	📝 modified
grids/index.html	📝 modified
index-1/index.html	📝 modified
index-2/index.html	📝 modified
index-3/index.html	📝 modified
index-4/index.html	📝 modified
installation/index.html	📝 modified
interpolation/index.html	📝 modified
mahler-yum-2024/index.html	📝 modified
mortality/index.html	📝 modified
pandas-interop/index.html	📝 modified
parameters/index.html	📝 modified
precautionary-savings/index.html	📝 modified
precautionary-savings-health/index.html	📝 modified
regimes/index.html	📝 modified
setup/index.html	📝 modified
shocks/index.html	📝 modified
solving-and-simulating/index.html	📝 modified
stochastic-transitions/index.html	📝 modified
tiny/index.html	📝 modified
tiny-example/index.html	📝 modified
transitions/index.html	📝 modified
write-economics/index.html	📝 modified

[timmens]

Very nice! I prefer this UI 😄

Only one comment:

The pandas_interop docs explain the format and the "why labels" well, but I think there's a gap for users trying to build a mental model of what's happening. The function code uses JAX integer indexing (probs_array[age, health]), but the user provides string-labeled Series, and nothing explains how those two worlds connect.

A short paragraph somewhere before or after the "Series format" section could help. Something along the lines of: your model functions work with plain JAX arrays and integer indexing as usual; the Series is purely an input convenience. Before any model code runs, the conversion inspects your function to figure out which dimensions the array is indexed over, maps labels to integer positions using the model's grids, and hands the function a normal JAX array. Your function never sees pandas.

Not blocking, but I think it'd save users some head-scratching.