iwfm.diagnostics.iteration_callback

iwfm.diagnostics.iteration_callback(pest_dir, iteration=None, model_config=None, apply_changes=False, stability_result=None, verbose=False)[source]

Post-iteration callback for LLM-supervised PEST.

Assembles diagnostic bundle from HDF5 files and PEST output, serializes to JSON, optionally generates and applies parameter change recommendations.

Designed to be called between PEST iterations, either by the LLM supervisor loop or as a standalone diagnostic tool.

Parameters:

  • pest_dir (str) – Root PEST run directory (contains .pst, .res, .rec, .par, .sen files, model/ and diagnostics/ subdirectories).

  • iteration (int, optional) – Current PEST iteration number. If None, auto-detected from .rec file.

  • model_config (dict, optional) – Model dimensions override. If None, uses C2VSimCG defaults.

  • apply_changes (bool) – If True, generate parameter recommendations and write a new .pst file. If False, only produce diagnostic bundle.

  • stability_result (StabilityJacobian, optional) – Stability Jacobian from StabilityCollector.compute(). If provided, attached to the diagnostic bundle.

  • verbose (bool) – Print progress.

Returns:

Result dictionary:

{
    'bundle_json': str,          # Serialized diagnostic bundle
    'bundle': DiagnosticBundle,  # Full bundle object
    'recommendations': dict,     # Parameter recommendations (if apply_changes)
    'output_pst': str,           # Path to new .pst (if apply_changes)
    'iteration': int,
}

Return type:

dict