dafi.random_field.covariance

Covariance matrices.

dafi.random_field.covariance.array_to_sparse(mat, tol)

Convert numpy array to sparse by setting small entries to zero.

Parameters:

• mat (ndarray) – Numpy array.

• tol (float) – Tolerance for sparse matrix. Any entry less than tol will be set to zero.

Returns:

mat_sp – Matrix converted to sparse matrix.

Return type:

csc_matrix

dafi.random_field.covariance.bc_cov(kernel='sqrexp', stddev=1.0, sp_tol=1e-08, dirichlet_coords=None, neumann_coords=None, neumann_dir=None, int_val=None, int_der=None, prior_mean=None, perturb=1e-05, kernel_kwargs={})

Create covariance matrix based on specified kernel and enforcing boundary conditions and observations.

Note: kernel_kwargs must contain coords.

See:

Michelén Ströfer, et al. “Enforcing boundary conditions on physical fields in Bayesian inversion.” Computer Methods in Applied Mechanics and Engineering, 367, 113097, 2020. doi:10.1016/j.cma.2020.113097.

Parameters:

• kernel (function) – See generate_cov.

• stddev (ndarray) – See generate_cov.

• sp_tol (float) – See generate_cov.

• dirichlet_coords (ndarray) – Coordinates of points where Dirichlet boundary condition is enforced (e.g. cell faces). dtype=float, ndim=2, shape=(npoints, ncoords)

• neumann_coords (ndarray) – Coordinates of points where Neumann boundary condition is enforced (e.g. cell faces). dtype=float, ndim=2, shape=(npoints, ncoords)

• neumann_dir (ndarray) – Index of coordinate direction for the gradient. dtype=float, ndim=1, shape=(npoints)

• int_value (dictionary) – Dictionary containing the coordinates (coords, ndarray, ndim=2, shape=(npoints, ncoords)), values (val, ndarray, ndim=1, shape=(npoints)), standard deviation (stddev, ndarray, ndim=1, shape=(npoints)), and baseline (prior, e.g. interpolate from prior mean) values (val_base, ndarray, ndim=1, shape=(npoints)), of npoints internal value observations.

• int_der (dictionary) – Dictionary of internal derivative observations. See int_value. Additionally contains the direction (coordinate index) (dir, ndarray, ndim=1, shape=(npoints))

• prior_mean (ndarray) – Mean vector prior to enforcing internal observations. dtype=float, ndim=1, shape=(nstate)

• perturb (float) – Small quantity to add to a matrix diagonal before inversion.

• kernel_kwargs (dictionary) – Keyword arguments for chosen kernel function.

Returns:

• mean (ndarray) – Modified mean

• cov (scipy.sparse.csc_matrix) – Covariance matrix. See generate_cov. dtype=float, ndim=2, shape=(nstate, nstate)

dafi.random_field.covariance.check_mat(mat, type='cov', tol=1e-08)

Perform checks for correlation or covariance matrices.

Checks if matrix is symmetric and positive definite. For a correlation matrix also checks that the diagonal terms are close to 1 and the off diagonal have magnitude less than or equal to 1.

Parameters:

• mat (ndarray) – Correlation or covariance matrix. Can be ndarray, matrix, or scipy sparse matrix. dtype=float, ndim=2, shape=(N, N)

• type (str) – Matrix type: use ‘corr’ for a correlation matrix and ‘cov’ for a covariance matrix.

• tol (float) – Tolerance used when checking if two values are close to each other.

Returns:

• passed (bool) – Whether all tests passed succesfully.

• message (str) – Information on which tests did not pass.

dafi.random_field.covariance.corr_to_cov(corr, stddev)

Convert a correlation matrix to a covariance matrix.

Parameters:

• corr (scipy.sparse.csc_matrix) – Correlation matrix. dtype=float, ndim=2, shape=(nstate, nstate)

• stddev (ndarray) – Standard deviation of each state. Alternatively, provide a float for a constant standard deviation. dtype=float, ndim=1, shape=(nstate)

Returns:

cov – Covariance matrix. dtype=float, ndim=2, shape=(nstate, nstate)

Return type:

scipy.sparse.csc_matrix

dafi.random_field.covariance.cov_to_corr(cov)

Convert a covariance matrix to a correlation matrix.

Parameters:

cov (ndarray) – Covariance matrix. dtype=float, ndim=2, shape=(nstate, nstate)

Returns:

corr – Correlation matrix. dtype=float, ndim=2, shape=(nstate, nstate)

Return type:

ndarray

dafi.random_field.covariance.generate_cov(kernel='sqrexp', stddev=1.0, sp_tol=1e-08, **kwargs)

Generate a covariance matrix using the specified correlatiion kernel and standard deviation.

Additional kwargs are passed to the kernel function.

Parameters:

• kernel (function) – Function that returns a correlation matrix. All additional arguments are passed to this function. Alternatively, a string with the name of one of the implemented kernels.

• stddev (ndarray) – Standard deviation of each state. Alternatively, provide a float for a constant standard deviation. dtype=float, ndim=1, shape=(nstate)

• sp_tol (float) – Tolerance for sparse matrix. Any entry with correlation less than sp_tol will be set to zero.

Returns:

cov – Covariance matrix. dtype=float, ndim=2, shape=(nstate, nstate)

Return type:

scipy.sparse.csc_matrix

dafi.random_field.covariance.kernel_input_file(filename, Type='corr')

Create a correlation matrix by reading it from a file.

Parameters:

• filename (str) – Name (path) of file containing hte correlation or covariance matrix.

• Type (str) – The type of matrix contained in the file. Options are ‘corr’ for correlation matrix or ‘cov’ for covariance matrix.

Returns:

corr – Correlation matrix. dtype=float, ndim=2, shape=(nstate, nstate)

Return type:

ndarray

dafi.random_field.covariance.kernel_mixed_periodic_sqrexp(coords, length_scales, factor=6.0, period=None)

Create a correlation matrix using the square exponential function in some directions and the periodic kernel in others.

Parameters:

• coords (ndarray) – Array of coordinates. Each row correspond to a different point and the number of columns is the number of physical dimensions (e.g. 3 for (x,y,z)). dtype=float, ndim=2, shape=(npoints, ndims)

• length_scales (list) – Length scale for each physical dimensions. List length is ndims. Each entry is either a one dimensional ndarray of length nstate (length scale field) or a float (constant length scale). For periodic directions the factor argument is used (see factor).

• factor (float) – Factor used in the physical interpretation of the periodic length scale. The provided lengthscale (\(l\)) is modified as \(l = l * factor / p\) where \(p\) is the periodicity. A factor of about 6 results in similar physical interpretation of the provided length scale as for the non-periodic directions.

• period (list) – List of periodicity for each physical dimension (length ndims). Each entry is either a float (periodicity) or ‘None’ for non-periodic directions.

Returns:

corr – Correlation matrix. dtype=float, ndim=2, shape=(nstate, nstate)

Return type:

ndarray

dafi.random_field.covariance.kernel_sqrexp(coords, length_scales)

Create a correlation matrix using the square exponential function.

Parameters:

• coords (ndarray) – Array of coordinates. Each row correspond to a different point and the number of columns is the number of physical dimensions (e.g. 3 for (x,y,z)). dtype=float, ndim=2, shape=(npoints, ndims)

• length_scales (list) – Length scale for each physical dimensions. List length is ndims. Each entry is either a one dimensional ndarray of length nstate (length scale field) or a float (constant length scale).

Returns:

corr – Correlation matrix. dtype=float, ndim=2, shape=(nstate, nstate)

Return type:

ndarray

dafi.random_field.covariance.source_cov_to_output_corr(cov, weights, mat)

Convert the input field covariance to the output field correlation.

The input and output field are related by a PDE described by the matrix mat. This is used to create PDE-informed covariance matrices. See:

Wu, Jin-Long, et al. “Physics-Informed Covariance Kernel for Model-Form Uncertainty Quantification with Application to Turbulent Flows.” Computers & Fluids, vol. 193, Oct. 2019, p. 104292. doi:10.1016/j.compfluid.2019.104292.

Parameters:

• cov (ndarray) – Covariance matrix. dtype=float, ndim=2, shape=(nstate, nstate)

• weights (ndarray) – Weight (e.g. cell volume) associated with each state. dtype=float, ndim=1, shape=(nstate)

• mat (ndarray) – Matrix corresponding to the PDE. dtype=float, ndim=2, shape=(nstate, nstate)

Returns:

corr – Correlation structure of output field. dtype=float, ndim=2, shape=(nstate, nstate)

Return type:

ndarray

dafi.random_field.covariance.sparse_to_nan(mat)

Convert a sparse matrix to a matrix with NaNs instead of zeros.