CalibrationEngine

class hydromodpy.calibration.CalibrationEngine(space, optimizer, evaluator, max_iter=100, batch_size=1, parallel=1, cache=None, cache_context=None, progress=None, session_id=None, on_iteration=None)

Bases: object

Drive an ask/tell loop until convergence or budget is exhausted.

Minimal moving parts: space + optimizer + evaluator. The engine only decides when to stop and which results to forward to the optimizer. Everything else (simulation, catalog, promotion) happens in the evaluator closure.

The evaluator receives a ParamSuggestion and returns an EvaluationResult. Optional caching uses a parameter hash so repeated candidates can reuse previous objective values.

Parameters:

• space (ParameterSpace)

• optimizer (Optimizer)

• evaluator (Callable[[ParamSuggestion], EvaluationResult])

• max_iter (int)

• batch_size (int)

• parallel (int)

• cache (ParamsHashCache | None)

• cache_context (Mapping[str, Any] | None)

• progress (ProgressReporter | None)

• session_id (str | None)

• on_iteration (Callable[[ParamSuggestion, EvaluationResult], None] | None)

on_iteration: Callable[[ParamSuggestion, EvaluationResult], None] | None = None

Called once per evaluated suggestion, cache hits included.

Takes the suggestion alongside its result: a cache hit never reaches the evaluator, so the caller has no other way to know which parameters the iteration carried, and the row it persists would be dropped.