SABER Blocks

SABER blocks implement several key of operations that can be applied to an oops::FieldSet3D (wrapper for an atlas::FieldSet) representing an analysis increment (see SABER block interface below).

SABER includes blocks for generic/basic operations as well as blocks for more specialized covariance models like BUMP, Spectral Filtering, Explicit Diffusion, and GSI (Gridpoint Statistical Interpolation). See SABER Block Index for more information on specific blocks.

Central vs Outer SABER Blocks

SABER blocks are either a Central block or an Outer block, though some blocks (e.g. correlation operators which can be used in ensemble filtering) support implementations as both. A typical block chain may have at most one Central block, but may have many Outer blocks (see (45)). The most important operations performed by a Block are the multiply()/multiplyAD(), and blocks are generally named for what they do in these methods.

A Central block represents a correlation operator/matrix. Outer blocks could represent a number of mathematical operations such as interpolation, scaling, or coordinate transformations. They may also perform utility operations (which leaves a fieldset unchanged) such as writing the fieldset passed to the block.

A key distinction between Central and Outer blocks is that Central blocks have no multiplyAD(). A Central block is applied once, where as Outer blocks are typically applied first as and adjoint, then later using the forward multiply().

SABER block interface

All SABER blocks have a constructor that takes as input arguments:

  • a oops GeometryData,

  • a list of outer variables,

  • a configuration with elements on the SABER error covariance,

  • a set of SABER block parameters (see next section),

  • a background,

  • a first guess

A single oops::FieldSet3D is passed as argument for all the SABER block application methods. Blocks are sometimes interoperable in any order, though, coordinate transformations and interpolations are not generally interoperable. Both Central and Outer blocks implement a multiply(oops::FieldSet3D), and see Central block interface and Outer block interface sections for more information.

Methods that are only used to calibrate an error covariance model are presented in the section on calibration.

Among the other methods, note that the read() method should be used to read any calibration data, i.e. block data that has been pre-calculated/fit (from an ensemble of forecasts, explicitly pre-scribed, or otherwise computed).

Central block interface

SABER Central blocks inherit from the SaberCentralBlockBase base class. The default design outlined by the base class is for a specific (derived) central block to implement a set of Sqrt methods:

  • multiplySqrtAD(): factorization of the block, in adjoint direction (transforms from analysis to control vector space).

  • multiplySqrt(): factorization of the block, in forward direction (transforms from control to analysis vector space).

  • ctlVecSize(): returns the size (length) of the control vector.

  • randomCtlVec(): creates a random control vector (a default implementation is provided - see warning).

Warning

This default implementation of randomCtlVec will NOT produce identical results across different MPI layouts. Such a property can only be obtained with an overriding implementation that is specific to each block.

If these methods are implemented in a derived central block, the base class provides the default implementation of the following methods:

  • multiply(): applies the block (by first applying multiplySqrtAD() then applying multiplySqrt()) to an input FieldSet3D.

  • randomize(): fills a FieldSet3D with a centered Gaussian random sample with the covariance of the block (using the randomCtlVec() and multiplySqrt() methods).

However, depending on the intended use of the block the base class multiply() and randomize():can be directly overwritten in a derived class (instead of implementing the full set of Sqrt methods).

For multivariate assimilation (e.g., variable-dependent localization), multiple different central blocks can be wrapped into a single ‘meta’-central block. This ‘meta’-central block (similar to the SaberCentralBlockBase base class) contains default implementations for some methods mentioned above, which can be optionally overridden by a specific Central block own implementations. Please note that the crossed multivariate strategy (see :ref:<documentation arriving soon>) CANNOT use overridding multiply() and randomize(), and needs to use the default implementation (via the Sqrt methods) of the ‘meta’-central block instead.

Outer block interface

SABER Outer blocks inherit from the SaberOuterBlockBase base class which requires a specific Outer block to implement the following methods:

  • multiply(): apply the block in the forward direction.

  • multiplyAD: apply the adjoint of the block to an input FieldSet3D.

  • innerGeometryData(): returns the oops::GeometryData for the next block.

  • innerVars(): returns the oops::Variables for the next block.

The last two methods innerGeometryData() and innerVars() help link blocks together in a block-chain. They return the variables and geometry the block will pass to the following block in the adjoint direction (multiplyAD()); which are the same as the variables/geometry the block accepts in the forward direction (multiply()).

In some special cases (like block calibration), the following operations may also need to be implemented:

  • leftInverseMultiply(): apply the inverse of the block on the left of an input FieldSet3D.

  • rightInverseMultiply(): apply the inverse of the block on the right of an input FieldSet3D.

Base parameters

All SABER blocks share some common base parameters:

  • saber block name: the name of the SABER block. The only required parameter.

  • active variables: variables modified by the block. This should include at least the variables returned by the mandatoryActiveVars() block method.

  • The block’s mode configuration (the two options are mutually exclusive):

    • read: In this mode, a SABER block will be constructed and its training/fit parameters will be read from a file specified in the configuration. Cannot be used with calibration.

    • calibration: In this mode, a SABER block will be constructed and its training/fit parameters will be calculated at runtime. Cannot be used with read.

  • fieldsMetaData: a configuration containing metadata such as a vertical coordinate or geographic mask.

  • skip inverse: boolean flag to skip application of the inverse in calibration mode. Defaults is false.

  • state variables to inverse: state variables to be interpolated at construction time from one functionSpace to another. To be used for interpolation blocks only, when the outer and inner Geometry differ. Default is no variables.

Other parameters related to testing are listed in SABER block testing.

Most SABER blocks also have their own specific parameters. See the documentation of each specific block for more information.

Diffusion blocks

ML Balance Operator