GCC Code Coverage Report

Directory:	./
File:	src/sys/mat/matstruct.c
Date:	2025-11-19 04:19:03

	Exec	Total	Coverage
Lines:	53	53	100.0%
Functions:	2	2	100.0%
Branches:	180	394	45.7%

  
      Line
      Branch
      Exec
      Source
    
      /*
    
         - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    
         SLEPc - Scalable Library for Eigenvalue Problem Computations
    
         Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain
    
         This file is part of SLEPc.
    
         SLEPc is distributed under a 2-clause BSD license (see LICENSE).
    
         - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    
      */
    
      #include <slepc/private/slepcimpl.h>            /*I "slepcsys.h" I*/
    
      /*@
    
         MatCreateBSE - Create a matrix that can be used to define a structured eigenvalue
    
         problem of type BSE (Bethe-Salpeter Equation).
    
         Collective
    
         Input Parameters:
    
      +  R - matrix for the diagonal block (resonant)
    
      -  C - matrix for the off-diagonal block (coupling)
    
         Output Parameter:
    
      .  H  - the resulting matrix
    
         Notes:
    
         The resulting matrix has the block form $$H = \begin{bmatrix} R & C \\ -C^* & -R^T \end{bmatrix},$$
    
         where $R$ is assumed
    
         to be (complex) Hermitian and $C$ complex symmetric. Note that this function does
    
         not check these properties, so if the matrices provided by the user do not satisfy
    
         them, then the solver will not behave as expected.
    
         The obtained matrix can be used as an input matrix to `EPS` eigensolvers via
    
         `EPSSetOperators()` for the case that the problem type is `EPS_BSE`. Note that the user
    
         cannot just build a matrix with the required structure, it must be done via this
    
         function.
    
         In the current implementation, `H` is a `MATNEST` matrix, where `R` and `C` form the top
    
         block row, while the bottom block row is composed of matrices of type
    
         `MATTRANSPOSEVIRTUAL` and `MATHERMITIANTRANSPOSEVIRTUAL` scaled by -1.
    
         Level: intermediate
    
      .seealso: [](sec:structured), `MatCreateNest()`, `EPSSetOperators()`, `EPSSetProblemType()`, `MatCreateHamiltonian()`
    
      @*/
    
      334
      PetscErrorCode MatCreateBSE(Mat R,Mat C,Mat *H)
    
      {
    
      334
        PetscInt       Mr,Mc,Nr,Nc,mr,mc,nr,nc;
    
      334
        Mat            block[4] = { R, C, NULL, NULL };
    
      334
        SlepcMatStruct mctx;
    
        1/2✓ Branch 0 taken 2 times.
✗ Branch 1 not taken.

      334
        PetscFunctionBegin;
    
        3/16✗ Branch 0 not taken.
✓ Branch 1 taken 2 times.
✗ Branch 2 not taken.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.
✗ Branch 6 not taken.
✗ Branch 7 not taken.
✗ Branch 8 not taken.
✓ Branch 9 taken 2 times.
✗ Branch 10 not taken.
✗ Branch 11 not taken.
✗ Branch 12 not taken.
✗ Branch 13 not taken.
✗ Branch 14 not taken.
✗ Branch 15 not taken.

      334
        PetscValidHeaderSpecific(R,MAT_CLASSID,1);
    
        3/16✗ Branch 0 not taken.
✓ Branch 1 taken 2 times.
✗ Branch 2 not taken.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.
✗ Branch 6 not taken.
✗ Branch 7 not taken.
✗ Branch 8 not taken.
✓ Branch 9 taken 2 times.
✗ Branch 10 not taken.
✗ Branch 11 not taken.
✗ Branch 12 not taken.
✗ Branch 13 not taken.
✗ Branch 14 not taken.
✗ Branch 15 not taken.

      334
        PetscValidHeaderSpecific(C,MAT_CLASSID,2);
    
        13/32✓ Branch 0 taken 2 times.
✗ Branch 1 not taken.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✓ Branch 4 taken 2 times.
✗ Branch 5 not taken.
✓ Branch 6 taken 2 times.
✗ Branch 7 not taken.
✓ Branch 8 taken 2 times.
✗ Branch 9 not taken.
✗ Branch 10 not taken.
✓ Branch 11 taken 2 times.
✓ Branch 12 taken 2 times.
✗ Branch 13 not taken.
✗ Branch 14 not taken.
✓ Branch 15 taken 2 times.
✓ Branch 16 taken 2 times.
✗ Branch 17 not taken.
✓ Branch 18 taken 2 times.
✗ Branch 19 not taken.
✗ Branch 20 not taken.
✓ Branch 21 taken 2 times.
✗ Branch 22 not taken.
✗ Branch 23 not taken.
✗ Branch 24 not taken.
✓ Branch 25 taken 2 times.
✗ Branch 26 not taken.
✗ Branch 27 not taken.
✗ Branch 28 not taken.
✓ Branch 29 taken 2 times.
✗ Branch 30 not taken.
✗ Branch 31 not taken.

      334
        PetscCheckSameTypeAndComm(R,1,C,2);
    
        2/8✗ Branch 0 not taken.
✓ Branch 1 taken 2 times.
✗ Branch 2 not taken.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.
✗ Branch 6 not taken.
✗ Branch 7 not taken.

      334
        PetscAssertPointer(H,3);
    
        /* check sizes */
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(MatGetSize(R,&Mr,&Nr));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(MatGetLocalSize(R,&mr,&nr));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(MatGetSize(C,&Mc,&Nc));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(MatGetLocalSize(C,&mc,&nc));
    
        2/6✓ Branch 0 taken 10 times.
✗ Branch 1 not taken.
✗ Branch 2 not taken.
✓ Branch 3 taken 10 times.
✗ Branch 4 not taken.
✗ Branch 5 not taken.

      334
        PetscCheck(Mc==Mr && mc==mr,PetscObjectComm((PetscObject)R),PETSC_ERR_ARG_INCOMP,"Incompatible row dimensions");
    
        2/6✓ Branch 0 taken 10 times.
✗ Branch 1 not taken.
✗ Branch 2 not taken.
✓ Branch 3 taken 10 times.
✗ Branch 4 not taken.
✗ Branch 5 not taken.

      334
        PetscCheck(Nc==Nr && nc==nr,PetscObjectComm((PetscObject)R),PETSC_ERR_ARG_INCOMP,"Incompatible column dimensions");
    
        /* bottom block row */
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(MatCreateHermitianTranspose(C,&block[2]));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(MatScale(block[2],-1.0));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(MatCreateTranspose(R,&block[3]));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(MatScale(block[3],-1.0));
    
        /* create nest matrix and compose context */
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(MatCreateNest(PetscObjectComm((PetscObject)R),2,NULL,2,NULL,block,H));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(MatDestroy(&block[2]));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(MatDestroy(&block[3]));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(PetscNew(&mctx));
    
      334
        mctx->cookie = SLEPC_MAT_STRUCT_BSE;
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      334
        PetscCall(PetscObjectContainerCompose((PetscObject)*H,"SlepcMatStruct",mctx,PetscCtxDestroyDefault));
    
        6/12✓ Branch 0 taken 2 times.
✗ Branch 1 not taken.
✗ Branch 2 not taken.
✓ Branch 3 taken 2 times.
✓ Branch 4 taken 2 times.
✗ Branch 5 not taken.
✓ Branch 6 taken 2 times.
✗ Branch 7 not taken.
✓ Branch 8 taken 2 times.
✗ Branch 9 not taken.
✗ Branch 10 not taken.
✓ Branch 11 taken 2 times.

      50
        PetscFunctionReturn(PETSC_SUCCESS);
    
      }
    
      /*@
    
         MatCreateHamiltonian - Create a matrix that can be used to define a structured
    
         eigenvalue problem of Hamiltonian type.
    
         Collective
    
         Input Parameters:
    
      +  A - matrix for the (0,0) block
    
      .  B - matrix for the (0,1) block, must be real symmetric or complex Hermitian
    
      -  C - matrix for the (1,0) block, must be real symmetric or complex Hermitian
    
         Output Parameter:
    
      .  H  - the resulting matrix
    
         Notes:
    
         The resulting matrix has the block form $$H = \begin{bmatrix} A & B \\ C & -A^* \end{bmatrix},$$
    
         where $B$ and $C$ are
    
         assumed to be symmetric in the real case or Hermitian in the comples case. Note
    
         that this function does not check this property, so if the matrices provided by
    
         the user do not satisfy it, then the solver will not behave as expected.
    
         The obtained matrix can be used as an input matrix to `EPS` eigensolvers via
    
         `EPSSetOperators()` for the case that the problem type is `EPS_HAMILT`. Note that the
    
         user cannot just build a matrix with the required structure, it must be done via
    
         this function.
    
         In the current implementation, `H` is a `MATNEST` matrix, where the (1,1) block is
    
         a matrix of type `MATHERMITIANTRANSPOSEVIRTUAL` obtained from `A` and scaled by -1.
    
         Level: intermediate
    
      .seealso: [](sec:structured), `MatCreateNest()`, `EPSSetOperators()`, `EPSSetProblemType()`, `MatCreateBSE()`
    
      @*/
    
      95
      PetscErrorCode MatCreateHamiltonian(Mat A,Mat B,Mat C,Mat *H)
    
      {
    
      95
        PetscInt       Ma,Mb,Mc,Na,Nb,Nc,ma,mb,mc,na,nb,nc;
    
      95
        Mat            block[4] = { A, B, C, NULL };
    
      95
        SlepcMatStruct mctx;
    
        1/2✓ Branch 0 taken 2 times.
✗ Branch 1 not taken.

      95
        PetscFunctionBegin;
    
        3/16✗ Branch 0 not taken.
✓ Branch 1 taken 2 times.
✗ Branch 2 not taken.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.
✗ Branch 6 not taken.
✗ Branch 7 not taken.
✗ Branch 8 not taken.
✓ Branch 9 taken 2 times.
✗ Branch 10 not taken.
✗ Branch 11 not taken.
✗ Branch 12 not taken.
✗ Branch 13 not taken.
✗ Branch 14 not taken.
✗ Branch 15 not taken.

      95
        PetscValidHeaderSpecific(A,MAT_CLASSID,1);
    
        3/16✗ Branch 0 not taken.
✓ Branch 1 taken 2 times.
✗ Branch 2 not taken.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.
✗ Branch 6 not taken.
✗ Branch 7 not taken.
✗ Branch 8 not taken.
✓ Branch 9 taken 2 times.
✗ Branch 10 not taken.
✗ Branch 11 not taken.
✗ Branch 12 not taken.
✗ Branch 13 not taken.
✗ Branch 14 not taken.
✗ Branch 15 not taken.

      95
        PetscValidHeaderSpecific(B,MAT_CLASSID,2);
    
        3/16✗ Branch 0 not taken.
✓ Branch 1 taken 2 times.
✗ Branch 2 not taken.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.
✗ Branch 6 not taken.
✗ Branch 7 not taken.
✗ Branch 8 not taken.
✓ Branch 9 taken 2 times.
✗ Branch 10 not taken.
✗ Branch 11 not taken.
✗ Branch 12 not taken.
✗ Branch 13 not taken.
✗ Branch 14 not taken.
✗ Branch 15 not taken.

      95
        PetscValidHeaderSpecific(C,MAT_CLASSID,3);
    
        13/32✓ Branch 0 taken 2 times.
✗ Branch 1 not taken.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✓ Branch 4 taken 2 times.
✗ Branch 5 not taken.
✓ Branch 6 taken 2 times.
✗ Branch 7 not taken.
✓ Branch 8 taken 2 times.
✗ Branch 9 not taken.
✗ Branch 10 not taken.
✓ Branch 11 taken 2 times.
✓ Branch 12 taken 2 times.
✗ Branch 13 not taken.
✗ Branch 14 not taken.
✓ Branch 15 taken 2 times.
✓ Branch 16 taken 2 times.
✗ Branch 17 not taken.
✓ Branch 18 taken 2 times.
✗ Branch 19 not taken.
✗ Branch 20 not taken.
✓ Branch 21 taken 2 times.
✗ Branch 22 not taken.
✗ Branch 23 not taken.
✗ Branch 24 not taken.
✓ Branch 25 taken 2 times.
✗ Branch 26 not taken.
✗ Branch 27 not taken.
✗ Branch 28 not taken.
✓ Branch 29 taken 2 times.
✗ Branch 30 not taken.
✗ Branch 31 not taken.

      95
        PetscCheckSameTypeAndComm(A,1,B,2);
    
        13/32✓ Branch 0 taken 2 times.
✗ Branch 1 not taken.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✓ Branch 4 taken 2 times.
✗ Branch 5 not taken.
✓ Branch 6 taken 2 times.
✗ Branch 7 not taken.
✓ Branch 8 taken 2 times.
✗ Branch 9 not taken.
✗ Branch 10 not taken.
✓ Branch 11 taken 2 times.
✓ Branch 12 taken 2 times.
✗ Branch 13 not taken.
✗ Branch 14 not taken.
✓ Branch 15 taken 2 times.
✓ Branch 16 taken 2 times.
✗ Branch 17 not taken.
✓ Branch 18 taken 2 times.
✗ Branch 19 not taken.
✗ Branch 20 not taken.
✓ Branch 21 taken 2 times.
✗ Branch 22 not taken.
✗ Branch 23 not taken.
✗ Branch 24 not taken.
✓ Branch 25 taken 2 times.
✗ Branch 26 not taken.
✗ Branch 27 not taken.
✗ Branch 28 not taken.
✓ Branch 29 taken 2 times.
✗ Branch 30 not taken.
✗ Branch 31 not taken.

      95
        PetscCheckSameTypeAndComm(A,1,C,3);
    
        2/8✗ Branch 0 not taken.
✓ Branch 1 taken 2 times.
✗ Branch 2 not taken.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.
✗ Branch 6 not taken.
✗ Branch 7 not taken.

      95
        PetscAssertPointer(H,4);
    
        /* check sizes */
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      95
        PetscCall(MatGetSize(A,&Ma,&Na));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      95
        PetscCall(MatGetLocalSize(A,&ma,&na));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      95
        PetscCall(MatGetSize(B,&Mb,&Nb));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      95
        PetscCall(MatGetLocalSize(B,&mb,&nb));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      95
        PetscCall(MatGetSize(C,&Mc,&Nc));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      95
        PetscCall(MatGetLocalSize(C,&mc,&nc));
    
        2/6✓ Branch 0 taken 10 times.
✗ Branch 1 not taken.
✗ Branch 2 not taken.
✓ Branch 3 taken 10 times.
✗ Branch 4 not taken.
✗ Branch 5 not taken.

      95
        PetscCheck(Mb==Ma && mb==ma,PetscObjectComm((PetscObject)A),PETSC_ERR_ARG_INCOMP,"Incompatible row dimensions");
    
        2/6✓ Branch 0 taken 10 times.
✗ Branch 1 not taken.
✗ Branch 2 not taken.
✓ Branch 3 taken 10 times.
✗ Branch 4 not taken.
✗ Branch 5 not taken.

      95
        PetscCheck(Nc==Na && nc==na,PetscObjectComm((PetscObject)A),PETSC_ERR_ARG_INCOMP,"Incompatible column dimensions");
    
        /* (1,1) block */
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      95
        PetscCall(MatCreateHermitianTranspose(A,&block[3]));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      95
        PetscCall(MatScale(block[3],-1.0));
    
        /* create nest matrix and compose context */
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      95
        PetscCall(MatCreateNest(PetscObjectComm((PetscObject)A),2,NULL,2,NULL,block,H));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      95
        PetscCall(MatDestroy(&block[3]));
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      95
        PetscCall(PetscNew(&mctx));
    
      95
        mctx->cookie = SLEPC_MAT_STRUCT_HAMILT;
    
        4/6✓ Branch 0 taken 2 times.
✓ Branch 1 taken 8 times.
✓ Branch 2 taken 2 times.
✗ Branch 3 not taken.
✗ Branch 4 not taken.
✓ Branch 5 taken 2 times.

      95
        PetscCall(PetscObjectContainerCompose((PetscObject)*H,"SlepcMatStruct",mctx,PetscCtxDestroyDefault));
    
        6/12✓ Branch 0 taken 2 times.
✗ Branch 1 not taken.
✗ Branch 2 not taken.
✓ Branch 3 taken 2 times.
✓ Branch 4 taken 2 times.
✗ Branch 5 not taken.
✓ Branch 6 taken 2 times.
✗ Branch 7 not taken.
✓ Branch 8 taken 2 times.
✗ Branch 9 not taken.
✗ Branch 10 not taken.
✓ Branch 11 taken 2 times.

      19
        PetscFunctionReturn(PETSC_SUCCESS);
    
      }

Line	Branch	Exec	Source
1			/*
2			- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3			SLEPc - Scalable Library for Eigenvalue Problem Computations
4			Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain
5
6			This file is part of SLEPc.
7			SLEPc is distributed under a 2-clause BSD license (see LICENSE).
8			- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9			*/
10
11			#include <slepc/private/slepcimpl.h> /I "slepcsys.h" I/
12
13			/*@
14			MatCreateBSE - Create a matrix that can be used to define a structured eigenvalue
15			problem of type BSE (Bethe-Salpeter Equation).
16
17			Collective
18
19			Input Parameters:
20			+ R - matrix for the diagonal block (resonant)
21			- C - matrix for the off-diagonal block (coupling)
22
23			Output Parameter:
24			. H - the resulting matrix
25
26			Notes:
27			The resulting matrix has the block form $$H = \begin{bmatrix} R & C \\ -C^* & -R^T \end{bmatrix},$$
28			where $R$ is assumed
29			to be (complex) Hermitian and $C$ complex symmetric. Note that this function does
30			not check these properties, so if the matrices provided by the user do not satisfy
31			them, then the solver will not behave as expected.
32
33			The obtained matrix can be used as an input matrix to `EPS` eigensolvers via
34			`EPSSetOperators()` for the case that the problem type is `EPS_BSE`. Note that the user
35			cannot just build a matrix with the required structure, it must be done via this
36			function.
37
38			In the current implementation, `H` is a `MATNEST` matrix, where `R` and `C` form the top
39			block row, while the bottom block row is composed of matrices of type
40			`MATTRANSPOSEVIRTUAL` and `MATHERMITIANTRANSPOSEVIRTUAL` scaled by -1.
41
42			Level: intermediate
43
44			.seealso: [](sec:structured), `MatCreateNest()`, `EPSSetOperators()`, `EPSSetProblemType()`, `MatCreateHamiltonian()`
45			@*/
46		334	PetscErrorCode MatCreateBSE(Mat R,Mat C,Mat *H)
47			{
48		334	PetscInt Mr,Mc,Nr,Nc,mr,mc,nr,nc;
49		334	Mat block[4] = { R, C, NULL, NULL };
50		334	SlepcMatStruct mctx;
51
52	1/2 ✓ Branch 0 taken 2 times. ✗ Branch 1 not taken.	334	PetscFunctionBegin;
53	3/16 ✗ Branch 0 not taken. ✓ Branch 1 taken 2 times. ✗ Branch 2 not taken. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times. ✗ Branch 6 not taken. ✗ Branch 7 not taken. ✗ Branch 8 not taken. ✓ Branch 9 taken 2 times. ✗ Branch 10 not taken. ✗ Branch 11 not taken. ✗ Branch 12 not taken. ✗ Branch 13 not taken. ✗ Branch 14 not taken. ✗ Branch 15 not taken.	334	PetscValidHeaderSpecific(R,MAT_CLASSID,1);
54	3/16 ✗ Branch 0 not taken. ✓ Branch 1 taken 2 times. ✗ Branch 2 not taken. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times. ✗ Branch 6 not taken. ✗ Branch 7 not taken. ✗ Branch 8 not taken. ✓ Branch 9 taken 2 times. ✗ Branch 10 not taken. ✗ Branch 11 not taken. ✗ Branch 12 not taken. ✗ Branch 13 not taken. ✗ Branch 14 not taken. ✗ Branch 15 not taken.	334	PetscValidHeaderSpecific(C,MAT_CLASSID,2);
55	13/32 ✓ Branch 0 taken 2 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✓ Branch 4 taken 2 times. ✗ Branch 5 not taken. ✓ Branch 6 taken 2 times. ✗ Branch 7 not taken. ✓ Branch 8 taken 2 times. ✗ Branch 9 not taken. ✗ Branch 10 not taken. ✓ Branch 11 taken 2 times. ✓ Branch 12 taken 2 times. ✗ Branch 13 not taken. ✗ Branch 14 not taken. ✓ Branch 15 taken 2 times. ✓ Branch 16 taken 2 times. ✗ Branch 17 not taken. ✓ Branch 18 taken 2 times. ✗ Branch 19 not taken. ✗ Branch 20 not taken. ✓ Branch 21 taken 2 times. ✗ Branch 22 not taken. ✗ Branch 23 not taken. ✗ Branch 24 not taken. ✓ Branch 25 taken 2 times. ✗ Branch 26 not taken. ✗ Branch 27 not taken. ✗ Branch 28 not taken. ✓ Branch 29 taken 2 times. ✗ Branch 30 not taken. ✗ Branch 31 not taken.	334	PetscCheckSameTypeAndComm(R,1,C,2);
56	2/8 ✗ Branch 0 not taken. ✓ Branch 1 taken 2 times. ✗ Branch 2 not taken. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times. ✗ Branch 6 not taken. ✗ Branch 7 not taken.	334	PetscAssertPointer(H,3);
57
58			/* check sizes */
59	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(MatGetSize(R,&Mr,&Nr));
60	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(MatGetLocalSize(R,&mr,&nr));
61	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(MatGetSize(C,&Mc,&Nc));
62	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(MatGetLocalSize(C,&mc,&nc));
63	2/6 ✓ Branch 0 taken 10 times. ✗ Branch 1 not taken. ✗ Branch 2 not taken. ✓ Branch 3 taken 10 times. ✗ Branch 4 not taken. ✗ Branch 5 not taken.	334	PetscCheck(Mc==Mr && mc==mr,PetscObjectComm((PetscObject)R),PETSC_ERR_ARG_INCOMP,"Incompatible row dimensions");
64	2/6 ✓ Branch 0 taken 10 times. ✗ Branch 1 not taken. ✗ Branch 2 not taken. ✓ Branch 3 taken 10 times. ✗ Branch 4 not taken. ✗ Branch 5 not taken.	334	PetscCheck(Nc==Nr && nc==nr,PetscObjectComm((PetscObject)R),PETSC_ERR_ARG_INCOMP,"Incompatible column dimensions");
65
66			/* bottom block row */
67	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(MatCreateHermitianTranspose(C,&block[2]));
68	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(MatScale(block[2],-1.0));
69	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(MatCreateTranspose(R,&block[3]));
70	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(MatScale(block[3],-1.0));
71
72			/* create nest matrix and compose context */
73	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(MatCreateNest(PetscObjectComm((PetscObject)R),2,NULL,2,NULL,block,H));
74	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(MatDestroy(&block[2]));
75	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(MatDestroy(&block[3]));
76
77	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(PetscNew(&mctx));
78		334	mctx->cookie = SLEPC_MAT_STRUCT_BSE;
79	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	334	PetscCall(PetscObjectContainerCompose((PetscObject)*H,"SlepcMatStruct",mctx,PetscCtxDestroyDefault));
80	6/12 ✓ Branch 0 taken 2 times. ✗ Branch 1 not taken. ✗ Branch 2 not taken. ✓ Branch 3 taken 2 times. ✓ Branch 4 taken 2 times. ✗ Branch 5 not taken. ✓ Branch 6 taken 2 times. ✗ Branch 7 not taken. ✓ Branch 8 taken 2 times. ✗ Branch 9 not taken. ✗ Branch 10 not taken. ✓ Branch 11 taken 2 times.	50	PetscFunctionReturn(PETSC_SUCCESS);
81			}
82
83			/*@
84			MatCreateHamiltonian - Create a matrix that can be used to define a structured
85			eigenvalue problem of Hamiltonian type.
86
87			Collective
88
89			Input Parameters:
90			+ A - matrix for the (0,0) block
91			. B - matrix for the (0,1) block, must be real symmetric or complex Hermitian
92			- C - matrix for the (1,0) block, must be real symmetric or complex Hermitian
93
94			Output Parameter:
95			. H - the resulting matrix
96
97			Notes:
98			The resulting matrix has the block form $$H = \begin{bmatrix} A & B \\ C & -A^* \end{bmatrix},$$
99			where $B$ and $C$ are
100			assumed to be symmetric in the real case or Hermitian in the comples case. Note
101			that this function does not check this property, so if the matrices provided by
102			the user do not satisfy it, then the solver will not behave as expected.
103
104			The obtained matrix can be used as an input matrix to `EPS` eigensolvers via
105			`EPSSetOperators()` for the case that the problem type is `EPS_HAMILT`. Note that the
106			user cannot just build a matrix with the required structure, it must be done via
107			this function.
108
109			In the current implementation, `H` is a `MATNEST` matrix, where the (1,1) block is
110			a matrix of type `MATHERMITIANTRANSPOSEVIRTUAL` obtained from `A` and scaled by -1.
111
112			Level: intermediate
113
114			.seealso: [](sec:structured), `MatCreateNest()`, `EPSSetOperators()`, `EPSSetProblemType()`, `MatCreateBSE()`
115			@*/
116		95	PetscErrorCode MatCreateHamiltonian(Mat A,Mat B,Mat C,Mat *H)
117			{
118		95	PetscInt Ma,Mb,Mc,Na,Nb,Nc,ma,mb,mc,na,nb,nc;
119		95	Mat block[4] = { A, B, C, NULL };
120		95	SlepcMatStruct mctx;
121
122	1/2 ✓ Branch 0 taken 2 times. ✗ Branch 1 not taken.	95	PetscFunctionBegin;
123	3/16 ✗ Branch 0 not taken. ✓ Branch 1 taken 2 times. ✗ Branch 2 not taken. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times. ✗ Branch 6 not taken. ✗ Branch 7 not taken. ✗ Branch 8 not taken. ✓ Branch 9 taken 2 times. ✗ Branch 10 not taken. ✗ Branch 11 not taken. ✗ Branch 12 not taken. ✗ Branch 13 not taken. ✗ Branch 14 not taken. ✗ Branch 15 not taken.	95	PetscValidHeaderSpecific(A,MAT_CLASSID,1);
124	3/16 ✗ Branch 0 not taken. ✓ Branch 1 taken 2 times. ✗ Branch 2 not taken. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times. ✗ Branch 6 not taken. ✗ Branch 7 not taken. ✗ Branch 8 not taken. ✓ Branch 9 taken 2 times. ✗ Branch 10 not taken. ✗ Branch 11 not taken. ✗ Branch 12 not taken. ✗ Branch 13 not taken. ✗ Branch 14 not taken. ✗ Branch 15 not taken.	95	PetscValidHeaderSpecific(B,MAT_CLASSID,2);
125	3/16 ✗ Branch 0 not taken. ✓ Branch 1 taken 2 times. ✗ Branch 2 not taken. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times. ✗ Branch 6 not taken. ✗ Branch 7 not taken. ✗ Branch 8 not taken. ✓ Branch 9 taken 2 times. ✗ Branch 10 not taken. ✗ Branch 11 not taken. ✗ Branch 12 not taken. ✗ Branch 13 not taken. ✗ Branch 14 not taken. ✗ Branch 15 not taken.	95	PetscValidHeaderSpecific(C,MAT_CLASSID,3);
126	13/32 ✓ Branch 0 taken 2 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✓ Branch 4 taken 2 times. ✗ Branch 5 not taken. ✓ Branch 6 taken 2 times. ✗ Branch 7 not taken. ✓ Branch 8 taken 2 times. ✗ Branch 9 not taken. ✗ Branch 10 not taken. ✓ Branch 11 taken 2 times. ✓ Branch 12 taken 2 times. ✗ Branch 13 not taken. ✗ Branch 14 not taken. ✓ Branch 15 taken 2 times. ✓ Branch 16 taken 2 times. ✗ Branch 17 not taken. ✓ Branch 18 taken 2 times. ✗ Branch 19 not taken. ✗ Branch 20 not taken. ✓ Branch 21 taken 2 times. ✗ Branch 22 not taken. ✗ Branch 23 not taken. ✗ Branch 24 not taken. ✓ Branch 25 taken 2 times. ✗ Branch 26 not taken. ✗ Branch 27 not taken. ✗ Branch 28 not taken. ✓ Branch 29 taken 2 times. ✗ Branch 30 not taken. ✗ Branch 31 not taken.	95	PetscCheckSameTypeAndComm(A,1,B,2);
127	13/32 ✓ Branch 0 taken 2 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✓ Branch 4 taken 2 times. ✗ Branch 5 not taken. ✓ Branch 6 taken 2 times. ✗ Branch 7 not taken. ✓ Branch 8 taken 2 times. ✗ Branch 9 not taken. ✗ Branch 10 not taken. ✓ Branch 11 taken 2 times. ✓ Branch 12 taken 2 times. ✗ Branch 13 not taken. ✗ Branch 14 not taken. ✓ Branch 15 taken 2 times. ✓ Branch 16 taken 2 times. ✗ Branch 17 not taken. ✓ Branch 18 taken 2 times. ✗ Branch 19 not taken. ✗ Branch 20 not taken. ✓ Branch 21 taken 2 times. ✗ Branch 22 not taken. ✗ Branch 23 not taken. ✗ Branch 24 not taken. ✓ Branch 25 taken 2 times. ✗ Branch 26 not taken. ✗ Branch 27 not taken. ✗ Branch 28 not taken. ✓ Branch 29 taken 2 times. ✗ Branch 30 not taken. ✗ Branch 31 not taken.	95	PetscCheckSameTypeAndComm(A,1,C,3);
128	2/8 ✗ Branch 0 not taken. ✓ Branch 1 taken 2 times. ✗ Branch 2 not taken. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times. ✗ Branch 6 not taken. ✗ Branch 7 not taken.	95	PetscAssertPointer(H,4);
129
130			/* check sizes */
131	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	95	PetscCall(MatGetSize(A,&Ma,&Na));
132	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	95	PetscCall(MatGetLocalSize(A,&ma,&na));
133	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	95	PetscCall(MatGetSize(B,&Mb,&Nb));
134	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	95	PetscCall(MatGetLocalSize(B,&mb,&nb));
135	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	95	PetscCall(MatGetSize(C,&Mc,&Nc));
136	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	95	PetscCall(MatGetLocalSize(C,&mc,&nc));
137	2/6 ✓ Branch 0 taken 10 times. ✗ Branch 1 not taken. ✗ Branch 2 not taken. ✓ Branch 3 taken 10 times. ✗ Branch 4 not taken. ✗ Branch 5 not taken.	95	PetscCheck(Mb==Ma && mb==ma,PetscObjectComm((PetscObject)A),PETSC_ERR_ARG_INCOMP,"Incompatible row dimensions");
138	2/6 ✓ Branch 0 taken 10 times. ✗ Branch 1 not taken. ✗ Branch 2 not taken. ✓ Branch 3 taken 10 times. ✗ Branch 4 not taken. ✗ Branch 5 not taken.	95	PetscCheck(Nc==Na && nc==na,PetscObjectComm((PetscObject)A),PETSC_ERR_ARG_INCOMP,"Incompatible column dimensions");
139
140			/* (1,1) block */
141	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	95	PetscCall(MatCreateHermitianTranspose(A,&block[3]));
142	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	95	PetscCall(MatScale(block[3],-1.0));
143
144			/* create nest matrix and compose context */
145	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	95	PetscCall(MatCreateNest(PetscObjectComm((PetscObject)A),2,NULL,2,NULL,block,H));
146	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	95	PetscCall(MatDestroy(&block[3]));
147
148	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	95	PetscCall(PetscNew(&mctx));
149		95	mctx->cookie = SLEPC_MAT_STRUCT_HAMILT;
150	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 8 times. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	95	PetscCall(PetscObjectContainerCompose((PetscObject)*H,"SlepcMatStruct",mctx,PetscCtxDestroyDefault));
151	6/12 ✓ Branch 0 taken 2 times. ✗ Branch 1 not taken. ✗ Branch 2 not taken. ✓ Branch 3 taken 2 times. ✓ Branch 4 taken 2 times. ✗ Branch 5 not taken. ✓ Branch 6 taken 2 times. ✗ Branch 7 not taken. ✓ Branch 8 taken 2 times. ✗ Branch 9 not taken. ✗ Branch 10 not taken. ✓ Branch 11 taken 2 times.	19	PetscFunctionReturn(PETSC_SUCCESS);
152			}
153

Function (Line)	Call count	Block coverage
MatCreateBSE (line 46)	called 334 times	58.0%
MatCreateHamiltonian (line 116)	called 95 times	58.0%