torchref.refinement.optimizers.simulated_annealing module

Simulated Annealing optimizer for crystallographic refinement.

Implements a per-parameter Metropolis-Hastings acceptance criterion for fine-grained exploration of parameter space.

torchref.refinement.optimizers.simulated_annealing.optimize_simulated_annealing(state, params, T_initial=1.0, T_final=0.01, n_steps=1000, perturbation_scale=0.01, absolute_scale=False, cooling_schedule='exponential', verbose=0, callback=None)[source]

Run simulated annealing optimization on a LossState.

Uses per-parameter Metropolis criterion where each parameter is independently accepted or rejected.

Parameters:

  • state (LossState) – Configured loss state with targets and weights.

  • params (list of torch.Tensor) – Parameters to optimize.

  • T_initial (float) – Initial temperature. Default is 1.0.

  • T_final (float) – Final temperature. Default is 0.01.

  • n_steps (int) – Number of SA steps. Default is 1000.

  • perturbation_scale (float, list, or dict) – Scale factor for perturbations. Can be: - float: uniform scale for all parameters - list: per-parameter scales (same length as params) - dict: mapping from parameter index to scale (missing indices use 0.01) If absolute_scale=False (default), this is multiplied by parameter magnitude. If absolute_scale=True, this is used directly as the standard deviation. Default is 0.01.

  • absolute_scale (bool) – If True, perturbation_scale is used as absolute std dev for noise. If False (default), perturbation_scale is relative to parameter magnitude.

  • cooling_schedule (str) – Cooling schedule: “exponential” or “linear”. Default is “exponential”.

  • verbose (int) – Verbosity level. Default is 0.

  • callback (callable, optional) – Function called after each step with signature callback(step, T, loss, params). Useful for collecting snapshots during optimization.

Returns:

State with history containing before/after loss values.

Return type:

LossState