Actual source code: mumps.c

      1: /*
      2:     Provides an interface to the MUMPS sparse solver
      3: */
      4: #include <petsc/private/matimpl.h>
      5: #include <petscmat.h>

      7: /*@
      8:   MatMumpsSetIcntl - Set MUMPS parameter ICNTL() <https://mumps-solver.org/index.php?page=doc>

     10:   Logically Collective

     12:   Input Parameters:
     13: + F     - the factored matrix obtained by calling `MatGetFactor()` with a `MatSolverType` of `MATSOLVERMUMPS` and a `MatFactorType` of `MAT_FACTOR_LU` or `MAT_FACTOR_CHOLESKY`
     14: . icntl - index of MUMPS parameter array `ICNTL()`
     15: - ival  - value of MUMPS `ICNTL(icntl)`

     17:   Options Database Key:
     18: . -mat_mumps_icntl_ICNTL ival - change the option numbered `icntl` to `ival`, here ICNTL denotes an integer value

     20:   Level: beginner

     22:   Note:
     23:   Ignored if MUMPS is not installed or `F` is not a MUMPS matrix

     25: .seealso: [](ch_matrices), `Mat`, `MatGetFactor()`, `MatMumpsGetIcntl()`, `MatMumpsSetCntl()`, `MatMumpsGetCntl()`, `MatMumpsGetInfo()`, `MatMumpsGetInfog()`, `MatMumpsGetRinfo()`, `MatMumpsGetRinfog()`
     26: @*/
     27: PetscErrorCode MatMumpsSetIcntl(Mat F, PetscInt icntl, PetscInt ival)
     28: {
     29:   PetscFunctionBegin;
     31:   PetscCheck(F->factortype, PetscObjectComm((PetscObject)F), PETSC_ERR_ARG_WRONGSTATE, "Only for factored matrix");
     34:   PetscTryMethod(F, "MatMumpsSetIcntl_C", (Mat, PetscInt, PetscInt), (F, icntl, ival));
     35:   PetscFunctionReturn(PETSC_SUCCESS);
     36: }

     38: /*@
     39:   MatMumpsGetIcntl - Get MUMPS parameter ICNTL() <https://mumps-solver.org/index.php?page=doc>

     41:   Logically Collective

     43:   Input Parameters:
     44: + F     - the factored matrix obtained by calling `MatGetFactor()` with a `MatSolverType` of `MATSOLVERMUMPS` and a `MatFactorType` of `MAT_FACTOR_LU` or `MAT_FACTOR_CHOLESKY`
     45: - icntl - index of MUMPS parameter array ICNTL()

     47:   Output Parameter:
     48: . ival - value of MUMPS ICNTL(icntl)

     50:   Level: beginner

     52: .seealso: [](ch_matrices), `Mat`, `MatGetFactor()`, `MatMumpsSetIcntl()`, `MatMumpsSetCntl()`, `MatMumpsGetCntl()`, `MatMumpsGetInfo()`, `MatMumpsGetInfog()`, `MatMumpsGetRinfo()`, `MatMumpsGetRinfog()`
     53: @*/
     54: PetscErrorCode MatMumpsGetIcntl(Mat F, PetscInt icntl, PetscInt *ival)
     55: {
     56:   PetscFunctionBegin;
     58:   PetscCheck(F->factortype, PetscObjectComm((PetscObject)F), PETSC_ERR_ARG_WRONGSTATE, "Only for factored matrix");
     60:   PetscAssertPointer(ival, 3);
     61:   PetscUseMethod(F, "MatMumpsGetIcntl_C", (Mat, PetscInt, PetscInt *), (F, icntl, ival));
     62:   PetscFunctionReturn(PETSC_SUCCESS);
     63: }

     65: /*@
     66:   MatMumpsSetCntl - Set MUMPS parameter CNTL() <https://mumps-solver.org/index.php?page=doc>

     68:   Logically Collective

     70:   Input Parameters:
     71: + F     - the factored matrix obtained by calling `MatGetFactor()` with a `MatSolverType` of `MATSOLVERMUMPS` and a `MatFactorType` of `MAT_FACTOR_LU` or `MAT_FACTOR_CHOLESKY`
     72: . icntl - index of MUMPS parameter array `CNTL()`
     73: - val   - value of MUMPS `CNTL(icntl)`

     75:   Options Database Key:
     76: . -mat_mumps_cntl_icntl val - change the option numbered icntl to ival

     78:   Level: beginner

     80:   Note:
     81:   Ignored if MUMPS is not installed or `F` is not a MUMPS matrix

     83: .seealso: [](ch_matrices), `Mat`, `MatGetFactor()`, `MatMumpsSetIcntl()`, `MatMumpsGetIcntl()`, `MatMumpsGetCntl()`, `MatMumpsGetInfo()`, `MatMumpsGetInfog()`, `MatMumpsGetRinfo()`, `MatMumpsGetRinfog()`
     84: @*/
     85: PetscErrorCode MatMumpsSetCntl(Mat F, PetscInt icntl, PetscReal val)
     86: {
     87:   PetscFunctionBegin;
     89:   PetscCheck(F->factortype, PetscObjectComm((PetscObject)F), PETSC_ERR_ARG_WRONGSTATE, "Only for factored matrix");
     92:   PetscTryMethod(F, "MatMumpsSetCntl_C", (Mat, PetscInt, PetscReal), (F, icntl, val));
     93:   PetscFunctionReturn(PETSC_SUCCESS);
     94: }

     96: /*@
     97:   MatMumpsGetCntl - Get MUMPS parameter CNTL() <https://mumps-solver.org/index.php?page=doc>

     99:   Logically Collective

    101:   Input Parameters:
    102: + F     - the factored matrix obtained by calling `MatGetFactor()` with a `MatSolverType` of `MATSOLVERMUMPS` and a `MatFactorType` of `MAT_FACTOR_LU` or `MAT_FACTOR_CHOLESKY`
    103: - icntl - index of MUMPS parameter array CNTL()

    105:   Output Parameter:
    106: . val - value of MUMPS CNTL(icntl)

    108:   Level: beginner

    110: .seealso: [](ch_matrices), `Mat`, `MatGetFactor()`, `MatMumpsSetIcntl()`, `MatMumpsGetIcntl()`, `MatMumpsSetCntl()`, `MatMumpsGetInfo()`, `MatMumpsGetInfog()`, `MatMumpsGetRinfo()`, `MatMumpsGetRinfog()`
    111: @*/
    112: PetscErrorCode MatMumpsGetCntl(Mat F, PetscInt icntl, PetscReal *val)
    113: {
    114:   PetscFunctionBegin;
    116:   PetscCheck(F->factortype, PetscObjectComm((PetscObject)F), PETSC_ERR_ARG_WRONGSTATE, "Only for factored matrix");
    118:   PetscAssertPointer(val, 3);
    119:   PetscUseMethod(F, "MatMumpsGetCntl_C", (Mat, PetscInt, PetscReal *), (F, icntl, val));
    120:   PetscFunctionReturn(PETSC_SUCCESS);
    121: }

    123: /*@
    124:   MatMumpsGetInverse - Get user-specified set of entries in inverse of `A` <https://mumps-solver.org/index.php?page=doc>

    126:   Logically Collective

    128:   Input Parameter:
    129: . F - the factored matrix obtained by calling `MatGetFactor()` with a `MatSolverType` of `MATSOLVERMUMPS` and a `MatFactorType` of `MAT_FACTOR_LU` or `MAT_FACTOR_CHOLESKY`

    131:   Output Parameter:
    132: . spRHS - sequential sparse matrix in `MATTRANSPOSEVIRTUAL` format with requested entries of inverse of `A`

    134:   Level: beginner

    136: .seealso: [](ch_matrices), `Mat`, `MatGetFactor()`, `MatCreateTranspose()`
    137: @*/
    138: PetscErrorCode MatMumpsGetInverse(Mat F, Mat spRHS)
    139: {
    140:   PetscFunctionBegin;
    142:   PetscCheck(F->factortype, PetscObjectComm((PetscObject)F), PETSC_ERR_ARG_WRONGSTATE, "Only for factored matrix");
    143:   PetscUseMethod(F, "MatMumpsGetInverse_C", (Mat, Mat), (F, spRHS));
    144:   PetscFunctionReturn(PETSC_SUCCESS);
    145: }

    147: /*@
    148:   MatMumpsGetInverseTranspose - Get user-specified set of entries in inverse of matrix $A^T $ <https://mumps-solver.org/index.php?page=doc>

    150:   Logically Collective

    152:   Input Parameter:
    153: . F - the factored matrix of A obtained by calling `MatGetFactor()` with a `MatSolverType` of `MATSOLVERMUMPS` and a `MatFactorType` of `MAT_FACTOR_LU` or `MAT_FACTOR_CHOLESKY`

    155:   Output Parameter:
    156: . spRHST - sequential sparse matrix in `MATAIJ` format containing the requested entries of inverse of `A`^T

    158:   Level: beginner

    160: .seealso: [](ch_matrices), `Mat`, `MatGetFactor()`, `MatCreateTranspose()`, `MatMumpsGetInverse()`
    161: @*/
    162: PetscErrorCode MatMumpsGetInverseTranspose(Mat F, Mat spRHST)
    163: {
    164:   PetscBool flg;

    166:   PetscFunctionBegin;
    168:   PetscCheck(F->factortype, PetscObjectComm((PetscObject)F), PETSC_ERR_ARG_WRONGSTATE, "Only for factored matrix");
    169:   PetscCall(PetscObjectTypeCompareAny((PetscObject)spRHST, &flg, MATSEQAIJ, MATMPIAIJ, NULL));
    170:   PetscCheck(flg, PetscObjectComm((PetscObject)spRHST), PETSC_ERR_ARG_WRONG, "Matrix spRHST must be MATAIJ matrix");
    171:   PetscUseMethod(F, "MatMumpsGetInverseTranspose_C", (Mat, Mat), (F, spRHST));
    172:   PetscFunctionReturn(PETSC_SUCCESS);
    173: }

    175: /*@
    176:   MatMumpsSetBlk - Set user-specified variable block sizes to be used with `-mat_mumps_icntl_15 1`

    178:   Not collective, only relevant on the first process of the MPI communicator

    180:   Input Parameters:
    181: + F      - the factored matrix of A obtained by calling `MatGetFactor()` with a `MatSolverType` of `MATSOLVERMUMPS` and a `MatFactorType` of `MAT_FACTOR_LU` or `MAT_FACTOR_CHOLESKY`
    182: . nblk   - the number of blocks
    183: . blkvar - see MUMPS documentation, `blkvar(blkptr(iblk):blkptr(iblk+1)-1)`, (`iblk=1, nblk`) holds the variables associated to block `iblk`
    184: - blkptr - array starting at 1 and of size `nblk + 1` storing the prefix sum of all blocks

    186:   Level: advanced

    188: .seealso: [](ch_matrices), `MATSOLVERMUMPS`, `Mat`, `MatGetFactor()`, `MatMumpsSetIcntl()`, `MatSetVariableBlockSizes()`
    189: @*/
    190: PetscErrorCode MatMumpsSetBlk(Mat F, PetscInt nblk, const PetscInt blkvar[], const PetscInt blkptr[])
    191: {
    192:   PetscFunctionBegin;
    194:   PetscCheck(F->factortype, PetscObjectComm((PetscObject)F), PETSC_ERR_ARG_WRONGSTATE, "Only for factored matrix");
    195:   PetscUseMethod(F, "MatMumpsSetBlk_C", (Mat, PetscInt, const PetscInt[], const PetscInt[]), (F, nblk, blkvar, blkptr));
    196:   PetscFunctionReturn(PETSC_SUCCESS);
    197: }

    199: /*@
    200:   MatMumpsGetInfo - Get MUMPS parameter INFO() <https://mumps-solver.org/index.php?page=doc>

    202:   Logically Collective

    204:   Input Parameters:
    205: + F     - the factored matrix obtained by calling `MatGetFactor()` with a `MatSolverType` of `MATSOLVERMUMPS` and a `MatFactorType` of `MAT_FACTOR_LU` or `MAT_FACTOR_CHOLESKY`
    206: - icntl - index of MUMPS parameter array INFO()

    208:   Output Parameter:
    209: . ival - value of MUMPS INFO(icntl)

    211:   Level: beginner

    213: .seealso: [](ch_matrices), `Mat`, `MatGetFactor()`, `MatMumpsSetIcntl()`, `MatMumpsGetIcntl()`, `MatMumpsSetCntl()`, `MatMumpsGetCntl()`, `MatMumpsGetInfog()`, `MatMumpsGetRinfo()`, `MatMumpsGetRinfog()`
    214: @*/
    215: PetscErrorCode MatMumpsGetInfo(Mat F, PetscInt icntl, PetscInt *ival)
    216: {
    217:   PetscFunctionBegin;
    219:   PetscCheck(F->factortype, PetscObjectComm((PetscObject)F), PETSC_ERR_ARG_WRONGSTATE, "Only for factored matrix");
    220:   PetscAssertPointer(ival, 3);
    221:   PetscUseMethod(F, "MatMumpsGetInfo_C", (Mat, PetscInt, PetscInt *), (F, icntl, ival));
    222:   PetscFunctionReturn(PETSC_SUCCESS);
    223: }

    225: /*@
    226:   MatMumpsGetInfog - Get MUMPS parameter INFOG() <https://mumps-solver.org/index.php?page=doc>

    228:   Logically Collective

    230:   Input Parameters:
    231: + F     - the factored matrix obtained by calling `MatGetFactor()` with a `MatSolverType` of `MATSOLVERMUMPS` and a `MatFactorType` of `MAT_FACTOR_LU` or `MAT_FACTOR_CHOLESKY`
    232: - icntl - index of MUMPS parameter array INFOG()

    234:   Output Parameter:
    235: . ival - value of MUMPS INFOG(icntl)

    237:   Level: beginner

    239: .seealso: [](ch_matrices), `Mat`, `MatGetFactor()`, `MatMumpsSetIcntl()`, `MatMumpsGetIcntl()`, `MatMumpsSetCntl()`, `MatMumpsGetCntl()`, `MatMumpsGetInfo()`, `MatMumpsGetRinfo()`, `MatMumpsGetRinfog()`
    240: @*/
    241: PetscErrorCode MatMumpsGetInfog(Mat F, PetscInt icntl, PetscInt *ival)
    242: {
    243:   PetscFunctionBegin;
    245:   PetscCheck(F->factortype, PetscObjectComm((PetscObject)F), PETSC_ERR_ARG_WRONGSTATE, "Only for factored matrix");
    246:   PetscAssertPointer(ival, 3);
    247:   PetscUseMethod(F, "MatMumpsGetInfog_C", (Mat, PetscInt, PetscInt *), (F, icntl, ival));
    248:   PetscFunctionReturn(PETSC_SUCCESS);
    249: }

    251: /*@
    252:   MatMumpsGetRinfo - Get MUMPS parameter RINFO() <https://mumps-solver.org/index.php?page=doc>

    254:   Logically Collective

    256:   Input Parameters:
    257: + F     - the factored matrix obtained by calling `MatGetFactor()` with a `MatSolverType` of `MATSOLVERMUMPS` and a `MatFactorType` of `MAT_FACTOR_LU` or `MAT_FACTOR_CHOLESKY`
    258: - icntl - index of MUMPS parameter array RINFO()

    260:   Output Parameter:
    261: . val - value of MUMPS RINFO(icntl)

    263:   Level: beginner

    265: .seealso: [](ch_matrices), `Mat`, `MatGetFactor()`, `MatMumpsSetIcntl()`, `MatMumpsGetIcntl()`, `MatMumpsSetCntl()`, `MatMumpsGetCntl()`, `MatMumpsGetInfo()`, `MatMumpsGetInfog()`, `MatMumpsGetRinfog()`
    266: @*/
    267: PetscErrorCode MatMumpsGetRinfo(Mat F, PetscInt icntl, PetscReal *val)
    268: {
    269:   PetscFunctionBegin;
    271:   PetscCheck(F->factortype, PetscObjectComm((PetscObject)F), PETSC_ERR_ARG_WRONGSTATE, "Only for factored matrix");
    272:   PetscAssertPointer(val, 3);
    273:   PetscUseMethod(F, "MatMumpsGetRinfo_C", (Mat, PetscInt, PetscReal *), (F, icntl, val));
    274:   PetscFunctionReturn(PETSC_SUCCESS);
    275: }

    277: /*@
    278:   MatMumpsGetRinfog - Get MUMPS parameter RINFOG() <https://mumps-solver.org/index.php?page=doc>

    280:   Logically Collective

    282:   Input Parameters:
    283: + F     - the factored matrix obtained by calling `MatGetFactor()` with a `MatSolverType` of `MATSOLVERMUMPS` and a `MatFactorType` of `MAT_FACTOR_LU` or `MAT_FACTOR_CHOLESKY`
    284: - icntl - index of MUMPS parameter array RINFOG()

    286:   Output Parameter:
    287: . val - value of MUMPS RINFOG(icntl)

    289:   Level: beginner

    291: .seealso: [](ch_matrices), `Mat`, `MatGetFactor()`, `MatMumpsSetIcntl()`, `MatMumpsGetIcntl()`, `MatMumpsSetCntl()`, `MatMumpsGetCntl()`, `MatMumpsGetInfo()`, `MatMumpsGetInfog()`, `MatMumpsGetRinfo()`
    292: @*/
    293: PetscErrorCode MatMumpsGetRinfog(Mat F, PetscInt icntl, PetscReal *val)
    294: {
    295:   PetscFunctionBegin;
    297:   PetscCheck(F->factortype, PetscObjectComm((PetscObject)F), PETSC_ERR_ARG_WRONGSTATE, "Only for factored matrix");
    298:   PetscAssertPointer(val, 3);
    299:   PetscUseMethod(F, "MatMumpsGetRinfog_C", (Mat, PetscInt, PetscReal *), (F, icntl, val));
    300:   PetscFunctionReturn(PETSC_SUCCESS);
    301: }

    303: /*@
    304:   MatMumpsGetNullPivots - Get MUMPS parameter PIVNUL_LIST() <https://mumps-solver.org/index.php?page=doc>

    306:   Logically Collective

    308:   Input Parameter:
    309: . F - the factored matrix obtained by calling `MatGetFactor()` with a `MatSolverType` of `MATSOLVERMUMPS` and a `MatFactorType` of `MAT_FACTOR_LU` or `MAT_FACTOR_CHOLESKY`

    311:   Output Parameters:
    312: + size  - local size of the array. The size of the array is non-zero only on MPI rank 0
    313: - array - array of rows with null pivot, these rows follow 0-based indexing. The array gets allocated within the function and the user is responsible
    314:           for freeing this array.

    316:   Level: beginner

    318: .seealso: [](ch_matrices), `Mat`, `MatGetFactor()`, `MatMumpsSetIcntl()`, `MatMumpsGetIcntl()`, `MatMumpsSetCntl()`, `MatMumpsGetCntl()`, `MatMumpsGetInfo()`, `MatMumpsGetInfog()`, `MatMumpsGetRinfo()`
    319: @*/
    320: PetscErrorCode MatMumpsGetNullPivots(Mat F, PetscInt *size, PetscInt **array)
    321: {
    322:   PetscFunctionBegin;
    324:   PetscCheck(F->factortype, PetscObjectComm((PetscObject)F), PETSC_ERR_ARG_WRONGSTATE, "Only for factored matrix");
    325:   PetscAssertPointer(size, 2);
    326:   PetscAssertPointer(array, 3);
    327:   PetscUseMethod(F, "MatMumpsGetNullPivots_C", (Mat, PetscInt *, PetscInt **), (F, size, array));
    328:   PetscFunctionReturn(PETSC_SUCCESS);
    329: }