scxpand.hyperopt.hyperopt_utils

Utilities for Optuna study optimization and trial management.

Functions

cleanup_failed_trial(study_dir, trial_number)	Clean up files and directories for a failed trial.
cleanup_incomplete_trials(study, study_dir)	Clean up trial directories for RUNNING trials without results.
log_trial_progress(trial, study_dir)	Log trial progress to both logger and trials.log file.
report_optuna_trial_result(trial, results, ...)	Report a score to an Optuna trial and handle pruning.
save_study_info(study, study_dir, score_metric)	Save comprehensive study information to JSON file.
trial_callback(study, trial, study_dir)	Optuna callback for logging and handling different trial states.

scxpand.hyperopt.hyperopt_utils.cleanup_failed_trial(study_dir, trial_number)

Clean up files and directories for a failed trial.

This function only removes trial directories and files - it does not modify Optuna trial states. Trial state management should be handled by Optuna itself.

Parameters:

• study_dir (Path) – The study directory path.

• trial_number (int) – The trial number to clean up.

Return type:

None

scxpand.hyperopt.hyperopt_utils.cleanup_incomplete_trials(study, study_dir)

Clean up trial directories for RUNNING trials without results.

Any RUNNING trial without results can be safely cleaned up since there are no concurrent processes that could be actively working on them.

This function cleans up trial directories (not Optuna trial states) for trials that: 1. Are in RUNNING state in Optuna database 2. Have no valid results/checkpoint files (indicating incomplete execution)

Note: This does not modify trial states in Optuna - it only cleans up orphaned directories.

Parameters:

• study (Study) – The Optuna study object.

• study_dir (Path) – The study directory path.

Return type:

int

Returns:

Number of trial directories cleaned up.

scxpand.hyperopt.hyperopt_utils.log_trial_progress(trial, study_dir)

Log trial progress to both logger and trials.log file.

Parameters:

• trial (Trial) – The Optuna trial object.

• study_dir (Path) – Path to the study directory for logging.

Return type:

None

scxpand.hyperopt.hyperopt_utils.report_optuna_trial_result(trial, results, score_metric)

Report a score to an Optuna trial and handle pruning.

Parameters:

• trial (Trial | None) – The Optuna trial object (or None).

• results (dict) – The nested results dictionary.

• score_metric (str) – The metric key to report.

Return type:

None

scxpand.hyperopt.hyperopt_utils.save_study_info(study, study_dir, score_metric)

Save comprehensive study information to JSON file.

Parameters:

• study (Study) – The Optuna study object.

• study_dir (Path) – Directory where study information will be saved.

• score_metric (str) – The metric being optimized.

Return type:

None

scxpand.hyperopt.hyperopt_utils.trial_callback(study, trial, study_dir)

Optuna callback for logging and handling different trial states.

Parameters:

• study (Study) – The Optuna study object.

• trial (Trial) – The Optuna trial object.

• study_dir (Path) – Path to the study directory for logging.

Return type:

None