SABER Blockchain Guide¶

From a user’s perspective, highly specific details of how the blockchains are implemented may not be as interesting or important as how to set up their desired B matrix model with SABER, but this section will provide some insight into the (sometimes intricate) structure of a B matrix yaml configuration.

Mathematical Context¶

In SABER, a block chain contains the chain of blocks representing a B-matrix model (or a component of a hybrid B-matrix which could stand alone as a fully-functional B-matrix).

At the source code level, the abstract SaberBlockChainBase class sets up the base level functionality all derived block chains must implement.

The SaberParametricBlockChain, SaberEnsembleBlockChain, and the SaberHybridBlockChain, which all are derived from the abstract base class, provide implementations of the following methods set up by the SaberBlockChainBase base class interface:

void randomize(oops::FieldSet4D &)
void multiply(oops::FieldSet4D &)
size_t ctlVecSize()
void multiplySqrt(const atlas::Field &, oops::FieldSet4D &, const size_t &)
void multiplySqrtAD(const oops::FieldSet4D &, atlas::Field &, const size_t &)
atlas::FunctionSpace & outerFunctionSpace()
oops::Variables & outerVariables()

For mathematical context behind these methods, a B-matrix is a covariance matrix, so it is positive definite (all it’s eigenvalues are positive). Positive definite matrixes can be factored into the form:

\[B = UU^T\]

Though not strictly speaking a square root, the \(U\) matrix is called the square root of B 1.

In the minimization of a variational cost function, the B matrix gets applied to an ‘increment’ of analysis variables (coming from a model).

If we think of the application of the B-matrix in the factored form of first applying \(U^T\) then \(U\), the \(U\) matrices represent linear transformations from the model/analysis variable space to a control vector space. First for \(U^T\):

\[v = U^T \cdot \delta x\]

where \(\delta x\) is an increment vector in the model/analysis variable space, and \(v\) is the control vector. The \(U\) matrix then transforms from the control vector space back into the model/analysis variable space.

With this context, the SaberBlockChainBase interface can start making more sense. The randomize() method produces a random increment according to the B-matrix model contained within the Blockchain, which is used to randomly produce an ensemble representation of B. The multiply() method mutliplies an increment (as an oops::FieldSet4D) by the Blockchain, which will occur in the cost-fuction minimization or in a dirac test. The ctlVecSize() is the size of the intermediate (control) vector \(v\) which is the form an increment vector takes in the very middle of a Blockchain.

The multiplySqrt() and multiplySqrtAD() represent the \(U\) and \(U^T\) matrix transformations. The outerFunctionSpace() method returns the atlas::FunctionSpace containing the model/analysis geometry and grid point connectivity information, and the outerVariables() is a list of the model/analysis variables passed into the B-matrix model.

There is also a fourth, SaberOuterBlockChain class, but it does not derive from the abstract SaberBlockChainBase class. It is an auxiliary container/wrapper used by the three other block chain classes to hold the set of Outer SABER blocks that surround a Central block.

1: This factorization is not generally unique, which ultimately means we have some flexibility in creating our B-matrix model.

Setting up a B-matrix with Blockchains¶

Static, ensemble, and hybrid are the standard flavors of a B matrix model, and their general outline is described in Block chain specification.