Guide: Running the Model

This guide explains how to run AMMM V2 with the current runme.py entrypoint or directly through MMMBaseDriverV2.

What This Guide Covers

• Running the full pipeline with real CLI flags
• Understanding the stage-based outputs
• Checking diagnostics before trusting optimisation and interpretation outputs

Recommended Path: runme.py

From the project root:

python runme.py

Common variants:

# Explicit inputs
python runme.py --config data-config/demo_config.yml --data data-config/demo_data.csv --holidays data-config/holidays.csv

# Fast iteration
python runme.py --fast

# Disable scenarios
python runme.py --no-scenarios

# Multi-period planning
python runme.py --multiperiod --multiperiod-weeks 13

runme.py auto-detects files in this order:

1. data-config/
2. examples/default/
3. fallback demo files

Python API Path (Advanced)

Preferred import:

from driver import MMMBaseDriverV2

Compatibility import (package-root contexts):

from src.driver import MMMBaseDriverV2

Example:

from driver import MMMBaseDriverV2

driver = MMMBaseDriverV2(
    config_filename="data-config/demo_config.yml",
    input_filename="data-config/demo_data.csv",
    holidays_filename="data-config/holidays.csv",
    results_filename="results",
)

driver.main()

Expected Output Structure

Each run writes stage folders under your results root:

results/
├── 00_run_metadata/
├── 10_pre_diagnostics/
├── 20_model_fit/
├── 30_model_assessment/
├── 40_decomposition/
├── 50_diagnostics/
├── 60_response_curves/
├── 70_optimisation/
└── 80_interpretation/

Key files to check first:

• 20_model_fit/model.nc
• 20_model_fit/model.dill (if serialisation succeeds)
• 50_diagnostics/convergence_report.json
• 50_diagnostics/calibration_report.json
• 70_optimisation/optimization_results.csv (when optimisation is run)

Validation Checks Before Decision Use

1. Confirm 50_diagnostics/convergence_report.json has converged: true.
2. Confirm 50_diagnostics/calibration_report.json has well_calibrated: true (or document caveats).
3. Check 50_diagnostics/pareto_k_summary.json and its ok field.
4. Only then consume outputs in 40_decomposition/, 60_response_curves/, 70_optimisation/, and 80_interpretation/.

Note: statistical diagnostics indicate computational adequacy and predictive quality; they do not by themselves establish causal validity.