AMMM V2 Migration Guide

This guide summarises how to migrate workflows to the active V2 architecture.

What This Guide Covers

• Current V2 entrypoints
• Core behavioural differences from legacy workflows
• Validation checks after migration

1. Active Driver

V2 driver class:

from driver import MMMBaseDriverV2

Implementation location:

• src/driver/base.py

runme.py uses this driver by default and orchestrates the full pipeline.

2. Key V2 Behaviours

• Stage-based output directories (00_... to 80_...).
• Integrated diagnostics workflow:
  • prior predictive checks,
  • convergence reports,
  • calibration and Pareto-k,
  • pair/residual diagnostics.
• Diagnostic gate policy via diagnostics_gating.

3. Recommended Migration Path

1. Run your existing config through python runme.py.
2. Verify all outputs are in stage folders, not old csv/png/json/other roots.
3. Update any scripts that hard-code legacy output paths.
4. Add diagnostic checks to your post-run validation:
   • 50_diagnostics/convergence_report.json
   • 50_diagnostics/calibration_report.json
   • 50_diagnostics/pareto_k_summary.json

4. Path Migration Reference

Common legacy assumptions -> V2 equivalents:

• results/model.nc -> results/20_model_fit/model.nc
• results/model.dill -> results/20_model_fit/model.dill
• results/csv/optimization_results.csv -> results/70_optimisation/optimization_results.csv
• results/csv/budget_scenario_results.csv -> results/70_optimisation/budget_scenario_results.csv
• results/json/llm_interpretations.json -> results/80_interpretation/llm_interpretations.json

5. Minimal V2 Smoke Test

python runme.py --fast

Then confirm:

• 20_model_fit/model.nc
• 50_diagnostics/convergence_report.json
• 30_model_assessment/model_fit_predictions.png

6. Migration Acceptance Checklist

• Driver import updated to MMMBaseDriverV2
• Stage-folder outputs used throughout downstream scripts
• Diagnostic gate fields checked before optimisation/reporting consumption
• No runtime reliance on retired V1-specific files or interfaces