pycif.plugins.controlvects.standard — API reference

Configuration reference: standard plugin

pycif.plugins.controlvects.standard.build_full_b.build_b_block(controlvect, tracer)

Build the B matrix block corresponding to ‘tracer’

Parameters:

• controlvect (ControlVect) – the controlvector plugin

• tracer (tracer plugin) – the tracer to compute the corresping B block

Returns:

B matrix block

Return type:

2D array

pycif.plugins.controlvects.standard.build_full_b.build_b(controlvect, component=None, parameter=None)

Compute the full B matrix

Parameters:

• controlvect (ControlVect) – the controlvector plugin

• component (str, optional) – only compute B block for a given tracer (‘component’, ‘tracer’). Must be used with the ‘tracer’ argument. Defaults to None.

• parameter (str, optional) – only compute B block for a given tracer (‘component’, ‘tracer’). Must be used with the ‘component’ argument. Defaults to None.Defaults to None.

Returns:

B matrix

Return type:

2D array

pycif.plugins.controlvects.standard.crop.crop(self, datei, datef)

Crop the control vector temporally

Parameters:

• self

• datei

• datef

pycif.plugins.controlvects.standard.dump.dump(self, cntrl_file, to_netcdf=False, dir_netcdf=None, ensemble=False, **kwargs)

Dumps a control vector into a pickle file. Does not save large correlations.

Parameters:

• self (pycif.utils.classes.controlvects.ControlVect) – the Control Vector to dump

• cntrl_file (str) – path to the file to dump as pickle

• to_netcdf (bool) – save to netcdf files if True

• dir_netcdf (str) – root path for the netcdf directory

pycif.plugins.controlvects.standard.dump.load(self, cntrl_file, component2load=None, tracer2load=None, target_tracer=None, ensemble=False, **kwargs)

pycif.plugins.controlvects.standard.init_bprod.init_bprod(cntrlv, options={}, **kwargs)

Initilializes the product of chi by sqrt-B. It allows translating information from the minimization space to the control space. This first needs to initialize correlation matrices

Parameters:

cntrlv (dict) – definition of the control vector

Return type:

updated control vector

pycif.plugins.controlvects.standard.init_structure.init_structure(cntrlv, **kwargs)

Initializes the prior control vector. Loops over all components and tracers and process temporal and horizontal resolution.

Parameters:

• cntrlv (Plugin) – definition of the control vector.

• datei (datetime) – initial date of the inversion window

• datei – end date of the inversion window

pycif.plugins.controlvects.standard.init_xb.init_xb(cntrlv, trid, **kwargs)

Initializes the prior control vector. Loops over all components and tracers and process temporal and horizontal resolution.

Parameters:

• cntrlv (Plugin) – definition of the control vector.

• datei (datetime) – initial date of the inversion window

• datei – end date of the inversion window

pycif.plugins.controlvects.standard.sqrtbprod.sqrtbprod(cntrlv, chi, inverse=False, ensemble=False, **kwargs)

Multiplies Chi by B**0.5.

pycif.plugins.controlvects.standard.sqrtbprod.sqrtbprod_ad(cntrlv, dx, inverse=False, compute_sqrt=True, **kwargs)

pycif.plugins.controlvects.standard.utils.build_hcorr.build_hcorrelations(load_dir: str | PathLike[str], dump_dir: str | PathLike[str], hresol: str, hresoldim: int, zlat: ndarray[tuple[Any, ...], dtype[floating]], zlon: ndarray[tuple[Any, ...], dtype[floating]], sigma_sea: int, sigma_land: int, is_lbc: bool, landseamask: ndarray[tuple[Any, ...], dtype[floating]] | None = None, projection: Literal['gps', 'xy'] = 'gps', evalues_cutoff: float = 0.0, crop_chi: bool = False, use_sparse: bool = False, n_modes: int | None = None, sparse_cutoff: float = 0.1, target_prec: float | None = None, dump: bool = False) → tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]]]

Reads from cache file or compute the horizontal correlation matrix eigen values and vectors.

Parameters

load_dirstr or path-like

Directory to load precomputed eigen values and vectors from

dump_dirstr or path-like

Directory to dump computed eigen values and vectors in if ‘dump’ is True

hresolstr

Horizontal resolution type

hresoldimint

Horizontal grid size

zlat2D array

Grid latitudes

zlon2D array

Grid longitudes

sigma_seaint

Decay distance in km for correlation between sea cells

sigma_landint

Decay distance in km for correlation between land cells

is_lbcbool

Is lateral boundary condition

landseamask2D array, optional

Land-sea mask, pixels are 1 for land and 0 for sea, by default None

projection‘gps’ or ‘xy’, optional

Projection used to compute distances, by default “gps”

evalues_cutofffloat, optional

Truncates eigenvalues below this value, by default 0.0

crop_chibool, optional

Truncated eigen values and vector are cropped is True, otherwise they are padded with zeros, by default False

use_sparsebool, optional

Use sparse matrix with ‘eigsh’, by default False

n_modesint | None, optional

Number of eigenvalues to compute for sparse matrix, by default None

sparse_cutofffloat, optional

Correlation value threshold for sparse arrays, correlation below this value are set to zero, by default 0.1

target_precfloat, optional

Target precision for sparse matrix, by default 1e-2

dumpbool, optional

Dumps computed eigen values and vector if True, by default False

Returns

1D array, 2D array

square roots of eigenvalues and eigenvectors

pycif.plugins.controlvects.standard.utils.build_hcorr.compute_hcorrel_matrix(zlat: ndarray[tuple[Any, ...], dtype[floating]], zlon: ndarray[tuple[Any, ...], dtype[floating]], sigma: int | ndarray[tuple[Any, ...], dtype[integer]], projection: Literal['gps', 'xy'] = 'gps') → ndarray[tuple[Any, ...], dtype[floating]]

pycif.plugins.controlvects.standard.utils.build_hcorr.compute_hcorrel_dense(zlat: ndarray[tuple[Any, ...], dtype[floating]], zlon: ndarray[tuple[Any, ...], dtype[floating]], sigma: int | ndarray[tuple[Any, ...], dtype[integer]], projection: Literal['gps', 'xy'] = 'gps') → tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]]]

pycif.plugins.controlvects.standard.utils.build_hcorr.compute_hcorrel_sparse(zlat: ndarray[tuple[Any, ...], dtype[floating]], zlon: ndarray[tuple[Any, ...], dtype[floating]], sigma: int | ndarray[tuple[Any, ...], dtype[integer]], projection: Literal['gps', 'xy'] = 'gps', n_modes: int | None = None, sparse_cutoff: float = 0.1, target_prec: float | None = None) → tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]]]

pycif.plugins.controlvects.standard.utils.build_hcorr.get_hcorr_file(hcorr_dir: str | PathLike[str], hresol: str, hresoldim: int, nlon: int, nlat: int, sigma_sea: int, sigma_land: int, k: int | None = None, is_lbc: bool = False, legacy_path: bool = False) → Path

Returns the path to the horizontal correlations eigenvalues and eigenvectors cache file corresdonding to the given parameters.

If ‘legacy_path’ is True return the legacy path is the file exists to ensure compatibility with file generated with older versions

pycif.plugins.controlvects.standard.utils.build_hcorr.dump_hcorr(evalues: ndarray[tuple[Any, ...], dtype[floating]], evectors: ndarray[tuple[Any, ...], dtype[floating]], hcorr_dir: str | PathLike[str], hresol: str, hresoldim: int, nlon: int, nlat: int, sigma_sea: int, sigma_land: int, k: int | None = None, is_lbc: bool = False, overwrite: bool = False) → None

Dumps the horizontal correlations eigenvalues and eigenvectors to a cache file corresdonding to the given parameters

pycif.plugins.controlvects.standard.utils.build_hcorr.read_hcorr(hcorr_dir: str | PathLike[str], hresol: str, hresoldim: int, nlon: int, nlat: int, sigma_sea: int, sigma_land: int, k: int | None = None, is_lbc: bool = False, missing_ok: bool = False) → tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]]] | tuple[None, None]

Reads the horizontal correlations eigenvalues and eigenvectors form the cache file corresdonding to the given parameters.

pycif.plugins.controlvects.standard.utils.build_lsm.build_lsm(corr, hresol, tracer)

pycif.plugins.controlvects.standard.utils.build_tcorr.build_tcorrelations(period, subperiod, dates, sigma_t, sigma_type, evalmin=0.5, dump=False, dir_dump='', crop_chi=False, corr_plg=None, tracer=None, **kwargs)

Build temporal correlation matrix based on timedelta between periods. For period i and j, the corresponding correlation is: c(i,j) = exp(-timedelta(i, j) / sigma)

Parameters:

• period (int) – period duration

• subperiod (int) – sub-period duration

• dates (np.array) – dates sub-dividing the control vector periods

• sigma_t (float) – decay distance for correlation between periods (in days)

• evalmin (float) – flag out all eigenvalues below this value. Default is 0.5

• dump (bool) – dumps computed correlations if True

• dir_dump (str) – directory where correlation matrices are stored

Returns:

• square roots of eigenvalues

• eigenvectors

Return type:

tuple with

pycif.plugins.controlvects.standard.utils.build_tcorr.dump_tcorr(period, subperiod, dates, sigma_t, sigma_type, evalues, evectors, dir_dump, overwrite=False)

Dumps eigenvalues and vectors to a bin file. The default file format is: f”{dir_dump}/tempcor_{datei.strftime(‘%Y%m%d%H%M’)}_{datef.strftime(‘%Y%m%d%H%M’)}_per{period}-{subperiod}_ct{sigma_t}_{sigma_type}.bin”

Parameters:

• period (int) – period duration

• subperiod (int) – subperiod duration

• dates (np.array) – dates sub-dividing the control vector periods

• sigma_t (float) – decay distance for correlation between periods (in days)

pycif.plugins.controlvects.standard.utils.build_tcorr.read_tcorr(period, subperiod, dates, sigma_t, sigma_type, dir_dump)

Reads temporal correlations from existing bin file

Parameters:

• period (int) – period duration

• subperiod (int) – subperiod duration

• dates (np.array) – dates sub-dividing the control vector periods

• sigma_t (float) – decay distance for correlation between periods (in days)

• dir_dump (str) – where the horizontal correlations have been stored

pycif.plugins.controlvects.standard.utils.build_vcorr.build_vcorrelations(vresol, nlev, sigma_lev, method, corr_plg=None, tracer=None, dump=False, dir_dump='', evalmin=0, crop_chi=False, **kwargs)

Build vertical correlation matrix based on distance between levels

Returns:

• square roots of eigenvalues

• eigenvectors

Return type:

tuple with

pycif.plugins.controlvects.standard.utils.build_vcorr.dump_vcorr(vresol, nlev, sigma_lev, method, evalues, evectors, dir_dump, overwrite=False)

Dumps eigenvalues and vectors to a binary file. The default file format is: f”{dir_dump}/vertcor_{vresol}_{nlev}_{method}.bin” )

pycif.plugins.controlvects.standard.utils.build_vcorr.read_vcorr(vresol, nlev, sigma_lev, method, dir_dump)

Reads vertical correlations from existing text file

pycif.plugins.controlvects.standard.utils.dimensions.hresol2dim(tracer, dom, **kwargs)

Computes the horizontal size of a control vector from its resolution

Parameters:

• tracer (Plugin) – definition of the tracer, including the resolution and additional information on the resolution

• domain (dict) – the domain grid

Returns

int: the size of the control vector for this component

pycif.plugins.controlvects.standard.utils.dimensions.vresol2dim(tracer, dom, **kwargs)

Computes the horizontal size of a control vector from its resolution

Parameters:

• tracer (Plugin) – definition of the tracer, including the resolution and additional information on the resolution

• domain (dict) – the domain grid

Returns

int: the size of the control vector for this component

pycif.plugins.controlvects.standard.utils.get_correlations.get_hcorr(cntrlv, tracer)

pycif.plugins.controlvects.standard.utils.get_correlations.get_tcorr(cntrlv, tracer, corr)

pycif.plugins.controlvects.standard.utils.get_correlations.get_vcorr(cntrlv, tracer)

pycif.plugins.controlvects.standard.utils.get_physical.get_physical(controlvect, tracer, comp, trcr, **kwargs)

pycif.plugins.controlvects.standard.utils.rescale_std.rescale_std(controlvect, tracer, comp, trcr, glob_err, **kwargs)

Re-scale errors for a given tracer depending on the specied total budget

Parameters:

• controlvect – reference control vector

• tracer – tracer object

• glob_err – error on global budget

Returns: