How does MatCraft determine when optimization has converged?

Convergence detection is how MatCraft decides when to stop the optimization loop. Running too few iterations risks missing the optimum; running too many wastes computational and experimental resources.

Convergence Criteria

MatCraft supports multiple convergence criteria, which can be combined:

1. Improvement Patience (Default)

The campaign stops if the best objective value has not improved by more than a threshold for a specified number of consecutive iterations:

convergence:
  patience: 5            # Stop after 5 iterations without improvement
  min_improvement: 0.01  # Minimum relative improvement to count as progress

For multi-objective campaigns, "improvement" is measured by the hypervolume indicator of the Pareto front — the volume of objective space dominated by the current front relative to a reference point.

2. Absolute Target

Stop when a target objective value is reached:

convergence:
  target:
    water_flux: 50.0        # Stop when flux >= 50
    salt_rejection: 95.0    # AND rejection >= 95%

3. Maximum Iterations

A hard cap that always applies:

campaign:
  max_iterations: 30  # Never run more than 30 iterations

4. Surrogate Stability

Stop when the surrogate model's predictions stabilize — measured by the mean absolute change in predictions on a held-out validation set between consecutive iterations:

convergence:
  surrogate_stability: 0.005  # Stop when predictions change < 0.5%

Monitoring Convergence

The dashboard and CLI display a real-time convergence plot showing:

• Best objective value (or hypervolume) per iteration
• Surrogate validation error per iteration
• Acquisition function maximum per iteration (indicates how much the model thinks there is to gain)

A declining acquisition maximum is a strong signal that the search space has been well-explored.

Recommendations

• For exploratory campaigns with cheap evaluations, set a high max_iterations (50+) and rely on patience-based stopping.
• For expensive experiments (physical lab work), set a conservative max_iterations (10-15) and manually review candidates at each iteration before approving evaluation.
• The default patience=5, min_improvement=0.01 works well for most problems with 3-10 parameters.