OEM

Workspace.OEM(self: pyarts.arts._Workspace, x: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Vector]] = self.x, yf: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Vector]] = self.yf, jacobian: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Matrix]] = self.jacobian, dxdy: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Matrix]] = self.dxdy, oem_diagnostics: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Vector]] = self.oem_diagnostics, lm_ga_history: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Vector]] = self.lm_ga_history, oem_errors: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.ArrayOfString]] = self.oem_errors, xa: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Vector]] = self.xa, covmat_sx: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.CovarianceMatrix]] = self.covmat_sx, y: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Vector]] = self.y, covmat_se: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.CovarianceMatrix]] = self.covmat_se, jacobian_quantities: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.ArrayOfRetrievalQuantity]] = self.jacobian_quantities, inversion_iterate_agenda: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Agenda]] = self.inversion_iterate_agenda, method: Union[pyarts.arts.WorkspaceVariable, pyarts.arts.String], max_start_cost: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Numeric]] = std::numeric_limits<Numeric>::infinity(), x_norm: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Vector]] = Vector{}, max_iter: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Index]] = 10, stop_dx: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Numeric]] = 0.01, lm_ga_settings: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Vector]] = Vector{}, clear_matrices: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Index]] = 0, display_progress: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Index]] = 0, verbosity: Optional[Union[pyarts.arts.WorkspaceVariable, pyarts.arts.Verbosity]] = self.verbosity) → None

Inversion by the so called optimal estimation method (OEM).

Work in progress …

The cost function to minimise, including a normalisation with lengthof y, is:

cost = cost_y + cost_x

where:

cost_y = 1/m * [y-yf]' * covmat_se_inv * [y-yf]
cost_x = 1/m * [x-xa]' * covmat_sx_inv * [x-xa]

The current implementation provides 3 methods for the minimization of the cost functional: Linear, Gauss-Newton and Levenberg-Marquardt. The Gauss-Newton minimizer attempts to find a minimum solution by fitting a quadratic function to the cost functional. The linear minimizer is a special case of the Gauss-Newton method, since for a linear forward model the exact solution of the minimization problem is obtained after the first step. The Levenberg-Marquardt method adaptively constrains the search region for the next iteration step by means of the so-called gamma-factor. This makes the method more suitable for strongly non-linear problems. If the gamma-factor is 0, Levenberg-Marquardt and Gauss-Newton method are identical. Each minimization method (li,gn,lm) has an indirect variant (li_cg,gn_cg,lm_cg), which uses the conjugate gradient solver for the linear system that has to be solved in each minimzation step. This of advantage for very large problems, that would otherwise require the computation of expensive matrix products.

Description of the special input arguments:

• method: One of the following:

  • "li": A linear problem is assumed and a single iteration is performed.

  • "li_cg": A linear problem is assumed and solved using the CG solver.

  • "gn": Non-linear, with Gauss-Newton iteration scheme.

  • "gn_cg": Non-linear, with Gauss-Newton and conjugate gradient solver.

  • "lm": Non-linear, with Levenberg-Marquardt (LM) iteration scheme.

  • "lm_cg": Non-linear, with Levenberg-Marquardt (LM) iteration scheme and conjugate gradient solver.

• max_start_cost: No inversion is done if the cost matching the a priori state is above this value. If set to a negative value, all values are accepted. This argument also controls if the start cost is calculated. If set to <= 0, the start cost in oem_diagnostics is set to NaN when using “li” and “gn”.

• x_norm: A normalisation vector for x. A normalisation of x can be needed due to limited numerical precision. If this vector is set to be empty no normalisation is done (defualt case). Otherwise, this must be a vector with same length as x, just having values above zero. Elementwise division between x and x_norm (x./x_norm) shall give a vector where all values are in the order of unity. Maybe the best way to set x_norm is x_norm = sqrt( diag( Sx ) ).

• max_iter: Maximum number of iterations to perform. No effect for “li”.

• stop_dx: Iteration stop criterion. The criterion used is the same as given in Rodgers’ “Inverse Methods for Atmospheric Sounding”

• lm_ga_settings: Settings controlling the gamma factor, part of the “LM” method. This is a vector of length 6, having the elements (0-based index):

  0. Start value.

  1. Fractional decrease after succesfull iteration.

  2. Fractional increase after unsuccessful iteration.

  3. Maximum allowed value. If the value is passed, the inversion is halted.

  4. Lower treshold. If the threshold is passed, gamma is set to zero. If gamma must be increased from zero, gamma is set to this value.

  5. Gamma limit. This is an additional stop criterion. Convergence is not considered until there has been one succesful iteration having a gamma <= this value.

  The default setting triggers an error if “lm” is selected.

• clear matrices:

  With this flag set to 1, jacobian and dxdy are returned as empty matrices.

• display_progress:

  Controls if there is any screen output. The overall report level is ignored by this WSM.

Author(s): Patrick Eriksson

Parameters:

• x (Vector, optional) – The state vector. See x, defaults to self.x [INOUT]

• yf (Vector, optional) – A fitted measurement vector. See yf, defaults to self.yf [INOUT]

• jacobian (Matrix, optional) – The Jacobian matrix. See jacobian, defaults to self.jacobian [INOUT]

• dxdy (Matrix, optional) – Contribution function (or gain) matrix. See dxdy, defaults to self.dxdy [OUT]

• oem_diagnostics (Vector, optional) – Basic diagnostics of an OEM type inversion. See oem_diagnostics, defaults to self.oem_diagnostics [OUT]

• lm_ga_history (Vector, optional) – The series of gamma values for a Marquardt-levenberg inversion. See lm_ga_history, defaults to self.lm_ga_history [OUT]

• oem_errors (ArrayOfString, optional) – Errors encountered during OEM execution. See oem_errors, defaults to self.oem_errors [OUT]

• xa (Vector, optional) – The a priori state vector. See xa, defaults to self.xa [IN]

• covmat_sx (CovarianceMatrix, optional) – Covariance matrix of a priori distribution. See covmat_sx, defaults to self.covmat_sx [IN]

• y (Vector, optional) – The measurement vector. See y, defaults to self.y [IN]

• covmat_se (CovarianceMatrix, optional) – Covariance matrix for observation uncertainties. See covmat_se, defaults to self.covmat_se [IN]

• jacobian_quantities (ArrayOfRetrievalQuantity, optional) – The retrieval quantities in the Jacobian matrix. See jacobian_quantities, defaults to self.jacobian_quantities [IN]

• inversion_iterate_agenda (Agenda, optional) – Work in progress … See inversion_iterate_agenda, defaults to self.inversion_iterate_agenda [IN]

• method (String) – Iteration method. For this and all options below, see further above. [IN]

• max_start_cost (Numeric, optional) – Maximum allowed value of cost function at start. Defaults to Inf [IN]

• x_norm (Vector, optional) – Normalisation of Sx. Defaults to [] [IN]

• max_iter (Index, optional) – Maximum number of iterations. Defaults to 10 [IN]

• stop_dx (Numeric, optional) – Stop criterion for iterative inversions. Defaults to 0.01 [IN]

• lm_ga_settings (Vector, optional) – Settings associated with the ga factor of the LM method. Defaults to [] [IN]

• clear_matrices (Index, optional) – An option to save memory. Defaults to 0 [IN]

• display_progress (Index, optional) – Flag to control if inversion diagnostics shall be printed on the screen. Defaults to 0 [IN]

• verbosity (Verbosity) – ARTS verbosity. See verbosity, defaults to self.verbosity [IN]