skretrieval.retrieval.scipy.SciPyMinimizer

skretrieval.retrieval.scipy.SciPyMinimizer#

class skretrieval.retrieval.scipy.SciPyMinimizer(method='trf', max_nfev=20, ftol=0.001, xtol=None, x_scale='jac', tr_solver='exact', apply_state_scaling=False, matrix_free_state_scale: float | ndarray | None = None, include_bounds=False, num_passes=1, jacobian_mode='materialized', matrix_free_fallback='raise', tr_options: dict | None = None, matrix_free_diagnostics='full', fisher_diagonal_probe_count=32, posterior_diagonal_probe_count=1024, posterior_diagonal_probe_batch_size=32, diagonal_error_random_seed=0, averaging_kernel_row_sum_mode='approximate', averaging_kernel_resolution_mode='approximate', averaging_kernel_row_sum_rtol=0.001, averaging_kernel_row_sum_maxiter=30, matrix_free_solver='lsmr', minimize_options: dict | None = None, materialized_jacobian_source='calculate_radiance', diagnostic_only=False, verbose=2, **kwargs)[source]#

Bases: Minimizer

A minimization wrapper around SciPy’s least_squares function.

Parameters:

  • method (str, optional) – Minimization method, see scipy.least_squares, by default “trf”. Recommended to only use “lm” or “trf”.

  • max_nfev (int, optional) – Maximum function evaluations, see scipy.optimize.least_squares, by default 20.

  • ftol (float | None, optional) – Tolerance on the cost function, by default 1e-3.

  • xtol (float | None, optional) – Tolerance on the change in state. The default, None, disables this termination condition.

  • x_scale (str | float | np.ndarray, optional) – Internal scaling applied by the minimizer, by default “jac”. When using jacobian_mode="matrix_free", x_scale="jac" is replaced by 1.0 because SciPy does not support Jacobian scaling for LinearOperator Jacobians.

  • tr_solver (str, optional) – For the “trf” method, how to solve the trust region problem, by default “exact”

  • apply_state_scaling (bool, optional) – If true, then the state vector is scaled relative to the apriori in the solver, useful when the state vector elements are of largely varying magnitudes and you have a well specified prior, by default False

  • matrix_free_state_scale (float or numpy.ndarray, optional) – Explicit positive diagonal change of variables for matrix-free solvers. The physical state is matrix_free_state_scale * z where z is the solver coordinate. This changes optimizer conditioning without changing the retrieval objective. It is mutually exclusive with apply_state_scaling.

  • include_bounds (bool, optional) – If true, bounds are included inside the solver, by default False.

  • num_passes (int, optional) – Number of passes through the minimizer. Between passes the noise covariance is adjusted so measurements with large residuals receive less weight, by default 1.

  • jacobian_mode (str, optional) – Jacobian strategy. "materialized" keeps the existing dense/sparse Jacobian path, "matrix_free" uses SASKTRAN2 JVP/VJP products with SciPy’s LSMR trust-region solver, and "auto" tries matrix-free before falling back according to matrix_free_fallback.

  • matrix_free_fallback (str, optional) – Either "materialized" or "raise", by default "raise". Controls what happens when matrix-free products are unavailable for the current forward model, state vector, or measurement vector. jacobian_mode="auto" always falls back to the materialized path.

  • tr_options (dict | None, optional) – Trust-region solver options passed to scipy.optimize.least_squares(). For matrix-free LSMR, options such as {"maxiter": 10} can cap inner solver iterations and directly reduce JVP/VJP calls.

  • matrix_free_diagnostics (str, optional) – Diagnostic strategy for matrix-free retrievals. "full" forms covariance and averaging-kernel diagnostics by repeated products. "fisher_diagonal" estimates the measurement-information diagonal with VJP-only randomized probes, retains the complete sparse prior precision, and returns an approximate posterior covariance diagonal without dense state matrices. "none" skips those post-solve diagnostics and avoids the extra product calls.

  • fisher_diagonal_probe_count (int, optional) – Number of measurement-space VJP probes used by the fast diagonal diagnostic, by default 32.

  • posterior_diagonal_probe_count (int, optional) – Number of inexpensive sparse inverse probes used after estimating the Fisher diagonal, by default 1024.

  • posterior_diagonal_probe_batch_size (int, optional) – Number of sparse inverse right-hand sides solved together, by default 32.

  • diagonal_error_random_seed (int, optional) – Deterministic seed for both randomized diagonal estimators, by default 0.

  • averaging_kernel_row_sum_mode (str, optional) – "approximate" returns within-state-element row sums from the diagonal-Fisher information matrix at negligible extra cost. "matrix_free" solves for full-Hessian row sums with preconditioned CG, and "none" disables the diagnostic. The default is "approximate".

  • averaging_kernel_resolution_mode (str, optional) – "approximate" computes Gaussian-equivalent FWHM resolution from sparse diagonal-Fisher averaging-kernel moments. "matrix_free" evaluates the same moments with full-Hessian JVP/VJP products and requires matrix-free row sums. "none" disables resolution diagnostics. The default is "approximate".

  • averaging_kernel_row_sum_rtol (float, optional) – Relative tolerance for the optional matrix-free row-sum solve, by default 1e-3.

  • averaging_kernel_row_sum_maxiter (int, optional) – Maximum preconditioned CG iterations for matrix-free row sums, by default 30.

  • matrix_free_solver (str, optional) – Matrix-free optimizer to use. "lsmr" uses scipy.optimize.least_squares() with a scipy.sparse.linalg.LinearOperator. "lbfgsb" uses gradient-only L-BFGS-B with VJP products.

  • minimize_options (dict | None, optional) – Options passed to scipy.optimize.minimize() when matrix_free_solver="lbfgsb".

  • materialized_jacobian_source (str, optional) – Forward-model source used by the dense/sparse Jacobian path. "calculate_radiance" keeps the legacy SASKTRAN2 weighting function path, while "linearization" calls Engine.linearize(...).jacobian and materializes the Jacobian through SASKTRAN2’s linearization object.

  • diagnostic_only (bool, optional) – Evaluate matrix-free diagnostics at the supplied initial state without taking an optimization step, by default False.

  • verbose (int, optional) – SciPy optimizer reporting level: 0 is silent, 1 reports termination, and 2 reports every iteration. The default is 2.

__init__(method='trf', max_nfev=20, ftol=0.001, xtol=None, x_scale='jac', tr_solver='exact', apply_state_scaling=False, matrix_free_state_scale: float | ndarray | None = None, include_bounds=False, num_passes=1, jacobian_mode='materialized', matrix_free_fallback='raise', tr_options: dict | None = None, matrix_free_diagnostics='full', fisher_diagonal_probe_count=32, posterior_diagonal_probe_count=1024, posterior_diagonal_probe_batch_size=32, diagonal_error_random_seed=0, averaging_kernel_row_sum_mode='approximate', averaging_kernel_resolution_mode='approximate', averaging_kernel_row_sum_rtol=0.001, averaging_kernel_row_sum_maxiter=30, matrix_free_solver='lsmr', minimize_options: dict | None = None, materialized_jacobian_source='calculate_radiance', diagnostic_only=False, verbose=2, **kwargs) → None[source]#

A minimization wrapper around SciPy’s least_squares function.

Parameters:

  • method (str, optional) – Minimization method, see scipy.least_squares, by default “trf”. Recommended to only use “lm” or “trf”.

  • max_nfev (int, optional) – Maximum function evaluations, see scipy.optimize.least_squares, by default 20.

  • ftol (float | None, optional) – Tolerance on the cost function, by default 1e-3.

  • xtol (float | None, optional) – Tolerance on the change in state. The default, None, disables this termination condition.

  • x_scale (str | float | np.ndarray, optional) – Internal scaling applied by the minimizer, by default “jac”. When using jacobian_mode="matrix_free", x_scale="jac" is replaced by 1.0 because SciPy does not support Jacobian scaling for LinearOperator Jacobians.

  • tr_solver (str, optional) – For the “trf” method, how to solve the trust region problem, by default “exact”

  • apply_state_scaling (bool, optional) – If true, then the state vector is scaled relative to the apriori in the solver, useful when the state vector elements are of largely varying magnitudes and you have a well specified prior, by default False

  • matrix_free_state_scale (float or numpy.ndarray, optional) – Explicit positive diagonal change of variables for matrix-free solvers. The physical state is matrix_free_state_scale * z where z is the solver coordinate. This changes optimizer conditioning without changing the retrieval objective. It is mutually exclusive with apply_state_scaling.

  • include_bounds (bool, optional) – If true, bounds are included inside the solver, by default False.

  • num_passes (int, optional) – Number of passes through the minimizer. Between passes the noise covariance is adjusted so measurements with large residuals receive less weight, by default 1.

  • jacobian_mode (str, optional) – Jacobian strategy. "materialized" keeps the existing dense/sparse Jacobian path, "matrix_free" uses SASKTRAN2 JVP/VJP products with SciPy’s LSMR trust-region solver, and "auto" tries matrix-free before falling back according to matrix_free_fallback.

  • matrix_free_fallback (str, optional) – Either "materialized" or "raise", by default "raise". Controls what happens when matrix-free products are unavailable for the current forward model, state vector, or measurement vector. jacobian_mode="auto" always falls back to the materialized path.

  • tr_options (dict | None, optional) – Trust-region solver options passed to scipy.optimize.least_squares(). For matrix-free LSMR, options such as {"maxiter": 10} can cap inner solver iterations and directly reduce JVP/VJP calls.

  • matrix_free_diagnostics (str, optional) – Diagnostic strategy for matrix-free retrievals. "full" forms covariance and averaging-kernel diagnostics by repeated products. "fisher_diagonal" estimates the measurement-information diagonal with VJP-only randomized probes, retains the complete sparse prior precision, and returns an approximate posterior covariance diagonal without dense state matrices. "none" skips those post-solve diagnostics and avoids the extra product calls.

  • fisher_diagonal_probe_count (int, optional) – Number of measurement-space VJP probes used by the fast diagonal diagnostic, by default 32.

  • posterior_diagonal_probe_count (int, optional) – Number of inexpensive sparse inverse probes used after estimating the Fisher diagonal, by default 1024.

  • posterior_diagonal_probe_batch_size (int, optional) – Number of sparse inverse right-hand sides solved together, by default 32.

  • diagonal_error_random_seed (int, optional) – Deterministic seed for both randomized diagonal estimators, by default 0.

  • averaging_kernel_row_sum_mode (str, optional) – "approximate" returns within-state-element row sums from the diagonal-Fisher information matrix at negligible extra cost. "matrix_free" solves for full-Hessian row sums with preconditioned CG, and "none" disables the diagnostic. The default is "approximate".

  • averaging_kernel_resolution_mode (str, optional) – "approximate" computes Gaussian-equivalent FWHM resolution from sparse diagonal-Fisher averaging-kernel moments. "matrix_free" evaluates the same moments with full-Hessian JVP/VJP products and requires matrix-free row sums. "none" disables resolution diagnostics. The default is "approximate".

  • averaging_kernel_row_sum_rtol (float, optional) – Relative tolerance for the optional matrix-free row-sum solve, by default 1e-3.

  • averaging_kernel_row_sum_maxiter (int, optional) – Maximum preconditioned CG iterations for matrix-free row sums, by default 30.

  • matrix_free_solver (str, optional) – Matrix-free optimizer to use. "lsmr" uses scipy.optimize.least_squares() with a scipy.sparse.linalg.LinearOperator. "lbfgsb" uses gradient-only L-BFGS-B with VJP products.

  • minimize_options (dict | None, optional) – Options passed to scipy.optimize.minimize() when matrix_free_solver="lbfgsb".

  • materialized_jacobian_source (str, optional) – Forward-model source used by the dense/sparse Jacobian path. "calculate_radiance" keeps the legacy SASKTRAN2 weighting function path, while "linearization" calls Engine.linearize(...).jacobian and materializes the Jacobian through SASKTRAN2’s linearization object.

  • diagnostic_only (bool, optional) – Evaluate matrix-free diagnostics at the supplied initial state without taking an optimization step, by default False.

  • verbose (int, optional) – SciPy optimizer reporting level: 0 is silent, 1 reports termination, and 2 reports every iteration. The default is 2.

Methods

__init__([method, max_nfev, ftol, xtol, ...])

A minimization wrapper around SciPy's least_squares function.

retrieve(measurement_l1, forward_model, ...)

retrieve(measurement_l1: RadianceBase, forward_model: ForwardModel, retrieval_target: RetrievalTarget)[source]#
Parameters:

  • measurement_l1 (RadianceBase) – The data we are trying to match, either from a real instrument or simulations.

  • forward_model (ForwardModel) – A model for the data in measurement_l1

  • retrieval_target (RetrievalTarget) – What we are trying to retrieve

Returns:

Various parameters specific to the minimizer

Return type:

dict