The ForcingCovariance Class

class stat_fem.ForcingCovariance(function_space, sigma, l, cutoff=0.001, regularization=1e-08, cov=<function sqexp>)

Class representing a sparse forcing covariance matrix

This class represents a forcing covariance matrix, which describes uncertainty in the underlying forcing function of the FEM solution to the PDE. In large simulations, this matrix cannot be stored as a dense matrix, and thus we approximate this as a sparse matrix. The current implementation does this by cutting off terms that are less than the diagonal by a certain factor, which is controlled by the cutoff attribute. The covariance matrix is usually regularized by adding a small nugget to the diagonal to ensure that it is well behaved. The implementation also makes the assumption that the correlation function can be assumed to be approximately constant over an entire mesh cell. This is effectively assuming that the correlation length is much longer than the mesh spacing, which is typically the case of interest in this type of problem.

The class is effectively a wrapper to an underlying sparse PETSc 'aij' Compressed Row Storage (CSR) matrix. The main operation that it supports is multiplication with a column vector, which must be a Firedrake Vector class. This operation is used in the data-conditioned FEM solves. This is exposed via the mult method, which behaves like the underlying PETSc multiplication method.

Because the sparsity of the matrix is not known ahead of time and the way that PETSc handles memory allocation, this currently limits the size of problems that can reasonably be addressed, as it must compute all matrix elements before cutting off the matrix and store the nonzero elements in memory prior to allocating the PETSc matrix. This is done row-by-row at the moment, which means that a processor must store several vectors over the entire global mesh in order to compute the local rows of the matrix.

Parameters required to initialize a new ForcingCovariance object are the function space over which the FEM solution will be computed, the standard deviation and correlation length scale used in computing the covariance function, and optional parameters to specify the cutoff value for making the covariance matrix sparse and regularization nugget to be added. Note that the default parameters may not work well for your particular problem – in particular, if the cutoff is too small there is a good chance you end up with a dense matrix that may require too much memory.

__init__(function_space, sigma, l, cutoff=0.001, regularization=1e-08, cov=<function sqexp>)

Create new forcing covariance

Creates a new ForcingCovariance object from a function space, parameters, and covariance function. Required parameters are the function space and sigma and correlation length parameters needed to compute the covariance matrix.

Note that this just initializes the object, and does not compute the matrix entries or assemble the final PETSc matrix. This is done using the assemble method, though if you attempt to use an unassembled matrix assembly will automatically be done. However the domain decomposition is done here to determine the number of DOFs handled by each process.

assemble()

Compute values of G and assemble the sparse matrix

This method creates the underlying sparse covariance matrix based on the pre-computed entries, allocates memory, sets the values, and finalizes assembly. No inputs, no return value. If this method is called and the matrix has already been assembled, it will return with no effect.

destroy()

Destroy allocated covariance forcing matrix

Deallocates memory for an assembled forcing matrix. If memory has not been allocated, returns with no effect. No inputs, no return value.

get_nx()

Return number of global nodal DOFs for FEM

Returns the number of global nodal DOFs for the FEM over all processes.

Returns:number of global DOFs Return type:int

get_nx_local()

Return number of local nodal DOFs for FEM

Returns the number of local nodal DOFs for the FEM for the current process.

Returns:number of local DOFs Return type:int

mult(x, y)

Perform matrix multiplication with firedrake vector

The principal operation done with a ForcingCovariance object is matrix multiplication with a vector. This method is a wrapper to the underlying method for the PETSc object, which modifies the y vector argument in-place. The provided vectors must be Firedrake Vector objects.

If the underlying covariance sparse matrix has not been assembled, it will be assembled prior to performing the matrix multiplication.

Parameters:

• x (Vector) – Firedrake vector that will be multiplied with the covariance matrix. Must be a distributed vector with the same row allocations as the covariance matrix.
• y (Vector) – Firedrake vector that will hold the result of multiplying the input vector with the covariance matrix. Must be a distributed vector with the same row allocations as the covariance matrix. Modified in place.

Returns:

None