hmt-calibrate

name	hmt-calibrate
description	Run automated Manning's n calibration against observed water surface elevations using Bayesian optimization or Nelder-Mead. Use this when the user wants to calibrate, optimize, or fit model parameters to observations.

Run automated Manning's n calibration against observed water surface elevations.

Prerequisites

• Project opened from a base_case/ subdirectory
• Observation CSV: columns x, y, wse or name, x, y, wse (comment lines start with #)
• Solver paths configured in hmt_config.json

Steps

1. Check that a project is open. If not, ask the user to run /hmt-open pointing to base_case/<project_file>.

2. Validate the observation file. Ask the user for the observation CSV path (e.g., HWMs.dat).

   hmt-cli check_observation_format --args '{"csv_file": "<path>"}'
   

   Show the preview table. On error: report and ask for a corrected path.

3. Show available materials.

   hmt-cli get_materials
   

4. Ask the user for calibration parameters. For each material to calibrate:

   • Material name, minimum n, maximum n, optional initial guess

5. Build validated parameter specifications.

   hmt-cli build_param_specs --args '{"specs": [
     {"type": "manning_n", "material_name": "<name>", "min": <min>, "max": <max>, "initial": <init>},
     ...
   ]}'
   

   Show the specs and confirm with the user.

6. Optional: single test evaluation at initial values to verify the setup.

   hmt-cli evaluate_parameters --args '{"param_specs": <specs_with_initial_values>, "observation_csv": "<path>"}'
   

   If RMSE = 1e6, the simulation failed — check pyHMT2D.log before proceeding.

7. Ask for settings: number of iterations (default: automatic) and method ("gp" or "nelder-mead").

8. Run the calibration.

   hmt-cli run_calibration --args '{"param_specs": <specs>, "observation_csv": "<path>", "n_iterations": <N>, "method": "gp"}'
   

   Periodically show progress while waiting:

   tail -20 calib_progress.log
   

9. Report results: best parameter values table, best RMSE, iterations completed, history CSV path.

Troubleshooting:

• RMSE = 1,000,000 → check pyHMT2D.log for solver errors
• Material not found → name must match exactly; copy from hmt-cli get_materials output