Reference for ultralytics/engine/tuner.py

def __call__(self, model=None, iterations: int = 10, cleanup: bool = True):
    """
    Execute the hyperparameter evolution process when the Tuner instance is called.

    This method iterates through the specified number of iterations, performing the following steps:
    1. Sync MongoDB results to CSV (if using distributed mode)
    2. Mutate hyperparameters using the best previous results or defaults
    3. Train a YOLO model with the mutated hyperparameters
    4. Log fitness scores and hyperparameters to MongoDB and/or CSV
    5. Track the best performing configuration across all iterations

    Args:
        model (Model | None, optional): A pre-initialized YOLO model to be used for training.
        iterations (int): The number of generations to run the evolution for.
        cleanup (bool): Whether to delete iteration weights to reduce storage space during tuning.
    """
    t0 = time.time()
    best_save_dir, best_metrics = None, None
    (self.tune_dir / "weights").mkdir(parents=True, exist_ok=True)

    # Sync MongoDB to CSV at startup for proper resume logic
    if self.mongodb:
        self._sync_mongodb_to_csv()

    start = 0
    if self.tune_csv.exists():
        x = np.loadtxt(self.tune_csv, ndmin=2, delimiter=",", skiprows=1)
        start = x.shape[0]
        LOGGER.info(f"{self.prefix}Resuming tuning run {self.tune_dir} from iteration {start + 1}...")
    for i in range(start, iterations):
        # Linearly decay sigma from 0.2 → 0.1 over first 300 iterations
        frac = min(i / 300.0, 1.0)
        sigma_i = 0.2 - 0.1 * frac

        # Mutate hyperparameters
        mutated_hyp = self._mutate(sigma=sigma_i)
        LOGGER.info(f"{self.prefix}Starting iteration {i + 1}/{iterations} with hyperparameters: {mutated_hyp}")

        metrics = {}
        train_args = {**vars(self.args), **mutated_hyp}
        save_dir = get_save_dir(get_cfg(train_args))
        weights_dir = save_dir / "weights"
        try:
            # Train YOLO model with mutated hyperparameters (run in subprocess to avoid dataloader hang)
            launch = [__import__("sys").executable, "-m", "ultralytics.cfg.__init__"]  # workaround yolo not found
            cmd = [*launch, "train", *(f"{k}={v}" for k, v in train_args.items())]
            return_code = subprocess.run(cmd, check=True).returncode
            ckpt_file = weights_dir / ("best.pt" if (weights_dir / "best.pt").exists() else "last.pt")
            metrics = torch_load(ckpt_file)["train_metrics"]
            assert return_code == 0, "training failed"

            # Cleanup
            time.sleep(1)
            gc.collect()
            torch.cuda.empty_cache()

        except Exception as e:
            LOGGER.error(f"training failure for hyperparameter tuning iteration {i + 1}\n{e}")

        # Save results - MongoDB takes precedence
        fitness = metrics.get("fitness", 0.0)
        if self.mongodb:
            self._save_to_mongodb(fitness, mutated_hyp, metrics, i + 1)
            self._sync_mongodb_to_csv()
            total_mongo_iterations = self.collection.count_documents({})
            if total_mongo_iterations >= iterations:
                LOGGER.info(
                    f"{self.prefix}Target iterations ({iterations}) reached in MongoDB ({total_mongo_iterations}). Stopping."
                )
                break
        else:
            # Save to CSV only if no MongoDB
            log_row = [round(fitness, 5)] + [mutated_hyp[k] for k in self.space.keys()]
            headers = "" if self.tune_csv.exists() else (",".join(["fitness"] + list(self.space.keys())) + "\n")
            with open(self.tune_csv, "a", encoding="utf-8") as f:
                f.write(headers + ",".join(map(str, log_row)) + "\n")

        # Get best results
        x = np.loadtxt(self.tune_csv, ndmin=2, delimiter=",", skiprows=1)
        fitness = x[:, 0]  # first column
        best_idx = fitness.argmax()
        best_is_current = best_idx == (i - start)
        if best_is_current:
            best_save_dir = str(save_dir)
            best_metrics = {k: round(v, 5) for k, v in metrics.items()}
            for ckpt in weights_dir.glob("*.pt"):
                shutil.copy2(ckpt, self.tune_dir / "weights")
        elif cleanup and best_save_dir:
            shutil.rmtree(best_save_dir, ignore_errors=True)  # remove iteration dirs to reduce storage space

        # Plot tune results
        plot_tune_results(str(self.tune_csv))

        # Save and print tune results
        header = (
            f"{self.prefix}{i + 1}/{iterations} iterations complete ✅ ({time.time() - t0:.2f}s)\n"
            f"{self.prefix}Results saved to {colorstr('bold', self.tune_dir)}\n"
            f"{self.prefix}Best fitness={fitness[best_idx]} observed at iteration {best_idx + 1}\n"
            f"{self.prefix}Best fitness metrics are {best_metrics}\n"
            f"{self.prefix}Best fitness model is {best_save_dir}"
        )
        LOGGER.info("\n" + header)
        data = {k: float(x[best_idx, i + 1]) for i, k in enumerate(self.space.keys())}
        YAML.save(
            self.tune_dir / "best_hyperparameters.yaml",
            data=data,
            header=remove_colorstr(header.replace(self.prefix, "# ")) + "\n",
        )
        YAML.print(self.tune_dir / "best_hyperparameters.yaml")