starling.structure.bme_utils.theta_scan

theta_scan(observables: List[ExperimentalObservable], calculated_values: ndarray, theta_range: Tuple[float, float] | ndarray = (0.01, 10.0), n_points: int = 15, log_scale: bool = True, max_iterations: int = 50000, optimizer: str = 'L-BFGS-B', verbose: bool = False, progress_callback: Callable[[int, int, float], None] | None = None, initial_weights: ndarray | None = None, method: str = 'perpendicular') → ThetaScanResult[source]

Scan a range of regularization parameters (theta) for BME reweighting.

Parameters:

  • observables (List[ExperimentalObservable]) – Experimental observables to use for reweighting.

  • calculated_values (np.ndarray) – Calculated values from the ensemble. Shape typically (n_models, n_observables).

  • theta_range (tuple or np.ndarray, optional) – If a tuple (min, max) is given, a grid of n_points thetas is created; if an array is supplied it is used directly. Default (0.01, 10.0).

  • n_points (int, optional) – Number of theta samples when theta_range is a tuple. Default 15.

  • log_scale (bool, optional) – If True and theta_range is a tuple, sample theta logarithmically. Default True.

  • max_iterations (int, optional) – Maximum optimizer iterations forwarded to BME.fit. Default from module.

  • optimizer (str, optional) – Optimizer name forwarded to BME.fit. Default from module.

  • verbose (bool, optional) – If True, print progress messages. Default False.

  • progress_callback (callable, optional) – Optional callback called as progress_callback(current_index, total, theta).

  • initial_weights (np.ndarray or None, optional) – Optional initial weight vector for BME.

  • method (str, optional) – Method used to pick optimal theta (‘perpendicular’ or ‘curvature’).

Returns:

Object containing theta grid, metric arrays, individual BMEResult objects, and the selected optimal theta and index.

Return type:

ThetaScanResult

Raises:

ValueError – If n_points < 1 when a tuple theta_range is provided, or if log_scale is True and theta_range tuple contains non-positive endpoints.