KarlNaumann / MacroStat / 23245563145

95%

push

github

feat(estimation): add Levenberg-Marquardt parameter estimation module (#64)

* chore(build): add uv.lock for reproducible builds

* feat(estimation): add EstimationResult dataclass

Add EstimationResult dataclass for storing parameter estimation results,
analogous to scipy.optimize.OptimizeResult but designed for MacroStat
models with PyTorch tensors.

Includes success flag, termination status/message, final parameters,
cost, residuals, Jacobian, iteration counts, and optimality measure.

* feat(estimation): add loss functions for parameter estimation

Add three loss functions compatible with both Levenberg-Marquardt
(reduction='none') and torch.optim (reduction='mean'/'sum'):

- mse_loss: Mean squared error between model output and target
- weighted_residuals: Weighted MSE for multi-variable calibration
- composite_loss: Combine multiple loss components

Includes comprehensive tests with 15 test cases covering reduction modes,
variable/timestep selection, weight normalization, and error handling.

* docs(estimation): add Phase 1 demonstration script

Add example script demonstrating loss functions with torch.optim.Adam on
GL06SIM model. Shows complete workflow: generate synthetic data, perturb
parameters, optimize with Adam, compare results.

This satisfies Checkpoint 1 of the implementation plan, showing that loss
functions are compatible with standard PyTorch optimizers.

* fix(estimation): use transition period for parameter sensitivity

The demo was using steady-state timesteps which have ~26M times less
parameter sensitivity than the transition period. Updated to use
timesteps 5-40 (transition) instead of last 20 (steady state).

Results: α1 error 0.100→0.027 (73% reduction), α2 error 0.100→0.026.
Remaining error demonstrates need for Phase 2 LM optimizer.

Also added debug scripts to diagnose the issue.

* docs(estimation): add comprehensive user guide and examples

- Rename estimation_phase1_demo.py → calibration_basic.py
- Make example script... (continued)

382 of 391 branches covered (97.7%)

Branch coverage included in aggregate %.

260 of 290 new or added lines in 5 files covered. (89.66%)

2468 of 2601 relevant lines covered (94.89%)

0.95 hits per line