hqs_nmr.analysis.montecarlo

Routines and tools for montecarlo minimization.

Functions

`metropolis_acceptance`(delta_loss, temperature)	Metropolis acceptance criterion.
`simulated_annealing`(initial_guess, ...)	Run a simulated annealing minimization.
`simulated_annealing_multiscale`(...[, ...])	Perform simulated annealing runs on decreasingly broadened signals.

Classes

HardcodedSAMultiscaleParameters()

Collection of the (for now) hardcoded parameters for the multiscale simulated annealing.

class hqs_nmr.analysis.montecarlo.HardcodedSAMultiscaleParameters

Collection of the (for now) hardcoded parameters for the multiscale simulated annealing.

Parameters:

fit_score_power – power used when computing cumulative fit scores.
num_shifts_fit_scores – number of shifts at which to compute the fit scores.
norm_cfs_threshold – maximum normalized cumulative-fit-score step.
norm_cfs_threshold_final – normalized cumulative-fit-score step at stage end.
cfs_target_min_fraction – lower fraction of random CFS target interval.

fit_score_power: float = 2

num_shifts_fit_scores: int = 600

norm_cfs_threshold: float = 0.15

norm_cfs_threshold_final: float = 0.04

cfs_target_min_fraction: float = 0.1

__init__() → None

class hqs_nmr.analysis.montecarlo._AnnealedCumulativeFitScoreSampler(cumulative_fit_score: ndarray, cfs_domain: ndarray, cfs_threshold_initial: float, cfs_threshold_final: float, cfs_target_min_fraction: float, max_iterations: int, iteration: int = 0)

Generate iteration-aware CFS proposals for simulated annealing.

This preserves the two-array sampler interface while retaining the stage-local fit-score data and iteration state required for annealing.

cumulative_fit_score: ndarray

cfs_domain: ndarray

cfs_threshold_initial: float

cfs_threshold_final: float

cfs_target_min_fraction: float

max_iterations: int

iteration: int = 0

__init__(cumulative_fit_score: ndarray, cfs_domain: ndarray, cfs_threshold_initial: float, cfs_threshold_final: float, cfs_target_min_fraction: float, max_iterations: int, iteration: int = 0) → None

hqs_nmr.analysis.montecarlo.metropolis_acceptance(delta_loss: float, temperature: float) → bool

Metropolis acceptance criterion.

Parameters:

delta_loss (float) – difference in the loss function.
temperature (float) – Temperature.

Returns:

whether the criterion is satisfied or not.

Return type:

bool

hqs_nmr.analysis.montecarlo.simulated_annealing(initial_guess: ~numpy.ndarray, loss_function: ~typing.Callable[[~numpy.ndarray], float], temperatures: ~numpy.ndarray, sampler_method: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], None], acceptance_criterion: ~typing.Callable[[float, float], bool] = <function metropolis_acceptance>, recorder: ~hqs_nmr.analysis._annealing_diagnostics.AnnealingRecorder | None = None) → ndarray

Run a simulated annealing minimization.

Parameters:

initial_guess (np.ndarray) – initial guess for the minimization.
loss_function (Callable[[np.ndarray], float]) – loss function to minimize.
temperatures (np.ndarray) – temperatures for the simulated annealing.
sampler_method (Callable[[np.ndarray, np.ndarray], None]) – method generating a new guess from the current guess. Signature (current_guess, preallocated_new_guess).
acceptance_criterion (Callable[[float, float], bool], optional) – acceptance criterion for new guesses. Defaults to metropolis_acceptance.
recorder – optional diagnostics sink. None disables diagnostics collection.

Returns:

best guess found.

Return type:

np.ndarray

hqs_nmr.analysis.montecarlo.simulated_annealing_multiscale(initial_guess: ndarray, reference: ndarray, reference_x: ndarray, greens_functions_reduced: ndarray, omegas_gf: ndarray, intrinsic_width: float, shifts_boundaries: ndarray, run_parameters: MultiscaleAnnealingParams | None = None, verbose: bool = False, recorder: AnnealingRecorder | None = None) → tuple[ndarray, AnnealingRecorder | None]

Perform simulated annealing runs on decreasingly broadened signals.

This method performs consecutive simulated annealing runs on decreasingly broadened reference and simulated spectra. This helps smoothen the loss function, fixed to be the integral of the absolute value of the difference between the reference and simulated spectra. This approach provides a smoother path for the search of the best solution. It also allows for dynamic adjustments to the convergence parameters: temperature, step size, minimum temperature and cooling schedule. For example, since we always start from the best solution from the previous run, we can start a lower temperatures as we decrease the broadening: we want to avoid too much exploration since we assume we have done it in larger broadening runs.

Parameters:

initial_guess (np.ndarray) – initial guess for the minimization.
reference (np.ndarray) – reference spectrum.
reference_x (np.ndarray) – x-axis of the reference spectrum.
greens_functions_reduced (np.ndarray) – greens functions of the simulated spectrum.
omegas_gf (np.ndarray) – frequencies of the greens functions.
intrinsic_width (float) – intrinsic width of the simulated spectrum.
shifts_boundaries (np.ndarray) – Boundaries for the shifts.
run_parameters (Optional[MultiscaleAnnealingParams]) – parameters for the multiscale run. If None, default values are used for initial and minimum temperatures and cooling rates.
verbose (bool) – controls whether to print debug information. Defaults to False.
recorder – optional diagnostics sink. None disables diagnostics collection.

Returns:

best guess and diagnostics recorder.

Return type:

tuple[np.ndarray, Optional[AnnealingRecorder]]