dubfi.core.util
===============

.. py:module:: dubfi.core.util

.. autoapi-nested-parse::

   Utility functions for flux inversion problem.

   .. codeauthor:: Valentin Bruch, DWD <valentin.bruch@dwd.de>
   .. versionadded:: 0.1.0 (initial release)



Functions
---------

.. autoapisummary::

   dubfi.core.util.config_overwrite
   dubfi.core.util.get_b_prior
   dubfi.core.util.get_s_prior
   dubfi.core.util.get_prior_cycling
   dubfi.core.util.mix_b


Module Contents
---------------

.. py:function:: config_overwrite(config: dict, changes: dict)

   Overwrite config by given changes, recursively updating dictionaries.


.. py:function:: get_b_prior(flux_cat: numpy.ndarray, config: dict) -> numpy.ndarray

   Construct a priori B matrix from configuration.

   :param flux_cat: names of flux categories (as used in configuration), result
                    will be aligned to this list.
   :type flux_cat: np.ndarray
   :param config: configuration
   :type config: dict

   :returns: **b_prior** -- prior uncertainty matrix (B)
   :rtype: np.ndarray


.. py:function:: get_s_prior(flux_cat: numpy.ndarray, config: dict) -> numpy.ndarray

   Construct a priori scaling factors from config.


.. py:function:: get_prior_cycling(ds: xarray.Dataset, flux_cat: numpy.ndarray, config: dict) -> tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

   Construct a priori B matrix in cycling step from results of previous cycle.

   :param ds: output of previous cycle, coordinates must agree with
              provided coordinates.
   :type ds: xr.Dataset
   :param flux_cat: names of flux categories, result will be aligned to this list.
   :type flux_cat: array
   :param config: configuration
   :type config: dict

   :returns: * **s_prior** (*np.ndarray*) -- prior scaling factors for simpler Kalman filter,
               shape (flux_cat,)
             * **b_prior** (*np.ndarray*) -- error covariance matrix of s_prior, shape (flux_cat, flux_cat)
             * **s_prior_norm_pref** (*np.ndarray*) -- prior scaling factors for extended inversion, shape
               (norm_prefactor, flux_cat)
             * **b_prior_norm_pref** (*np.ndarray*) -- error covariance matrix of s_prior_norm_pref, shape
               (norm_prefactor, flux_cat, flux_cat)
             * *Remarks*
             * *-------*
             * *This function mixes the initial prior and the posterior from a*
             * *previous inversion step. The posterior uncertainty is optionally*
             * *inflated before mixing with the initial prior. It assumes that*
             * *the uncertainties of the initial prior and the posterior are*
             * maximally correlated, see :func:`mix_b`.
             * *.. versionadded:: 0.1.1*


.. py:function:: mix_b(alpha: float, b1: numpy.ndarray, b2: numpy.ndarray, sqrt_b1: numpy.ndarray | None = None) -> numpy.ndarray

   Compute error covariance matrix for alpha * x1 + (1 - alpha) * x2 from error covariance matricess of x1 and x2.

   Consider two vectors x1, x2 with error covariance matrices B1, B2.
   Denote the covariance matrix of x1, x2 by B12, i.e., using cumulante
   notation: B1[i,j] = << x1[i] x1[j] >>, B2[i,j] = << x2[i] x2[j] >>,
   B12[i,j] = << x1[i] x2[j] >>. Then the error covariance matrix of
   x1 + x2 is Bsum = B1 + B2 + B12 + B12.T.

   We assume that B12 = sqrt(B1) sqrt(B2) such that the error
   covariance matrix of the combined vector (x1, x2) is singular with
   minimal rank (equal to rank(B1)=rank(B2)). This describes the
   strongest possible uncertainty correlation between x1 and x2.

   The output of this function is therefore (denote a=alpha):

   a**2 * B1 + (1-a)**2 * B2 + a*(1-a) * ( sqrt(B1) sqrt(B2) + sqrt(B2) sqrt(B1) )

   .. note:: b1 and b2 must be real-symmetric and positive-semidefinite.

   .. versionadded:: 0.1.1