MatCreateNestFromMultipleShifts#

Creates a MATNEST matrix that represents a family of shifted matrices \(K + \sigma_i M\) for a number of shifts \(\sigma_i\).

Synopsis#

#include "petscmat.h" 
PetscErrorCode MatCreateNestFromMultipleShifts(Mat K, PetscInt nshift, const PetscScalar sigma[], const PetscScalar sigma_imaginary[], Mat M, PetscBool explicitmat, MatStructure str, Mat *A)

Collective

Input Parameters#

K - the first Mat (stiffness) forming the shifted matrices
nshift - number of shifts
sigma - array of shifts \(\sigma_i\), its length is nshift
sigma_imaginary - imaginary parts of the shifts \(\sigma_i\) in case of complex-conjugate pairs (can be NULL); only used when PetscScalar is PetscReal
M - the second Mat (mass) forming the shifted matrices (if NULL the identity matrix is assumed)
explicitmat - whether the shifted matrices should be built explicitly or not
str - MatStructure flag

Output Parameter#

A - the resulting matrix

Notes#

This is intended for solving a family of shifted linear systems, \((K + \sigma_i M) x_i = b\), where in some applications \(M = I\). This function returns a MATNEST A whose nshift diagonal blocks are the matrices \(K + \sigma_i M\), either built explicitly or not, depending on the explicitmat argument. If not explicit, the diagonal blocks are created as MATCOMPOSITE. If explicitmat is true, and \(M\) is not the identity, then \(K + \sigma_i M\) is built with a call to MatAXPY(), where the flag str is used to indicate the relation between the sparsity patterns of \(K\) and \(M\). The flag is also stored in A and reused for the same purpose by solvers that build a shifted matrix explicitly from A, such as KSPEKSM, so it must describe the relation between the two patterns even when explicitmat is PETSC_FALSE.

To solve all the shifted linear systems simultaneously, pass this matrix to a KSP solver such as KSPEKSM, along with compatible solution and right-hand side vectors. Since the right-hand side \(b\) is the same for all the shifted linear systems, one can call MatCreateVecNestFromMultipleShifts() to easily create a nested Vec containing nshift references to \(b\).

When PetscScalar is PetscReal it is possible to provide complex conjugate pairs of shifts by passing a nonzero imaginary part in sigma_imaginary[i]. In that case A is no longer block diagonal but contains 2x2 diagonal blocks for each complex-conjugate pair.

Level#

intermediate

Location#

src/mat/impls/nest/multishift.c

Examples#

src/ksp/ksp/tutorials/ex90.c

Index of all Mat routines
Table of Contents for all manual pages
Index of all manual pages