ptyrad.solver.hypertune

Hypertune / Optuna workflow related functions

Functions

compute_optuna_error(model, indices, metric)	Helper function to compute the current error for Optuna
create_optuna_pruner(pruner_params)	Creates an Optuna pruner instance for early termination of unpromising trials.
create_optuna_sampler(sampler_params)	Creates an Optuna sampler instance from a configuration dictionary.
get_optuna_suggest(trial, suggest, name, kwargs)	Helper function to get Optuna's trial.suggest_X methods
optuna_objective(trial, params, init, ...[, ...])	Objective function for Optuna hyperparameter tuning in ptychographic reconstruction.
parse_hypertune_params_to_str(hypertune_params)	Helper function to parse hypertune params to strings for appending

ptyrad.solver.hypertune.create_optuna_sampler(sampler_params)

Creates an Optuna sampler instance from a configuration dictionary.

This factory function supports all standard Optuna samplers except PartialFixedSampler (which requires a sequential setup). Different samplers require specific configurations; for example, GridSampler requires a fully defined search_space mapped within the configs dictionary, and will ignore any step/range setups defined elsewhere in the tuning parameters.

For standard PtyRAD hyperparameter tuning, the recommended setup is the Tree-structured Parzen Estimator (TPE): {‘name’: ‘TPESampler’, ‘configs’: {‘multivariate’: True, ‘group’: True, ‘constant_liar’: True}}

Parameters:

sampler_params (dict) – A dictionary defining the sampler. Must contain a ‘name’ key (str) specifying the Optuna sampler class (e.g., ‘TPESampler’, ‘GridSampler’). Can optionally contain a ‘configs’ key (dict) with keyword arguments for the sampler’s constructor.

Returns:

The instantiated Optuna sampler object.

Return type:

optuna.samplers.BaseSampler

Raises:

ValueError – If the specified sampler name is ‘PartialFixedSampler’ or is not a recognized class within optuna.samplers.

ptyrad.solver.hypertune.create_optuna_pruner(pruner_params)

Creates an Optuna pruner instance for early termination of unpromising trials.

This factory function supports all standard Optuna pruners except WilcoxonPruner (which requires nested evaluation). It handles nested pruner instantiations automatically, such as when using a PatientPruner that requires a wrapped_pruner_configs dictionary inside its configs to define its base pruner.

Note that the objective function must contain iterative steps for pruning to take effect. For standard PtyRAD hyperparameter tuning, the recommended setup is Hyperband: {‘name’: ‘HyperbandPruner’, ‘configs’: {‘min_resource’: 5, ‘reduction_factor’: 2}}

Parameters:

pruner_params (dict or None) – A dictionary defining the pruner. Must contain a ‘name’ key (str) specifying the Optuna pruner class (e.g., ‘HyperbandPruner’, ‘PatientPruner’). Can optionally contain a ‘configs’ key (dict) with keyword arguments for the constructor. If None is passed, the function returns None (disabling pruning).

Returns:

The instantiated Optuna pruner object, or None if pruner_params is None.

Return type:

optuna.pruners.BasePruner or None

Raises:

ValueError – If the specified pruner is ‘WilcoxonPruner’, ‘NopPruner’ (which should be bypassed by setting pruner_params = None instead), or is not a recognized class within optuna.pruners.

ptyrad.solver.hypertune.optuna_objective(trial, params, init, loss_fn, constraint_fn, device='cuda')

Objective function for Optuna hyperparameter tuning in ptychographic reconstruction.

This function is used by Optuna to optimize the hyperparameters of the ptychographic reconstruction process. The function updates the reconstruction parameters based on the trial’s suggestions and runs the reconstruction loop to evaluate the performance. The function also implements Optuna’s pruning mechanism to stop unpromising trials early.

Parameters:

• trial (optuna.trial.Trial) – A trial object that suggests hyperparameter values and handles pruning.

• params (dict) – A dictionary containing all the parameters for the reconstruction, including experimental parameters, model parameters, and hyperparameter tuning configurations.

• init (Initializer) – An instance of the Initializer class that holds initialized variables and methods for updating them based on the trial’s suggestions.

• loss_fn (CombinedLoss) – The loss function object that calculates the reconstruction loss.

• constraint_fn (CombinedConstraint) – The constraint function object that applies constraints during optimization.

• device (str, optional) – The device to run the reconstruction on, e.g., ‘cuda’. Defaults to ‘cuda’.

Returns:

The total loss for the final iteration of the reconstruction process, used by Optuna to evaluate the trial’s performance.

Return type:

float

Raises:

• optuna.exceptions.TrialPruned – Raised when the trial should be pruned based on the

• intermediate results. –

ptyrad.solver.hypertune.get_optuna_suggest(trial, suggest, name, kwargs)

Helper function to get Optuna’s trial.suggest_X methods

ptyrad.solver.hypertune.compute_optuna_error(model, indices, metric)

Helper function to compute the current error for Optuna

ptyrad.solver.hypertune.parse_hypertune_params_to_str(hypertune_params)

Helper function to parse hypertune params to strings for appending