Actual source code: petscpc.h

      1: /*
      2:       Preconditioner module.
      3: */
     6:  #include petscmat.h

      9: EXTERN PetscErrorCode PCInitializePackage(const char[]);

     11: /*
     12:     PCList contains the list of preconditioners currently registered
     13:    These are added with the PCRegisterDynamic() macro
     14: */
     16: #define PCType char*

     18: /*S
     19:      PC - Abstract PETSc object that manages all preconditioners

     21:    Level: beginner

     23:   Concepts: preconditioners

     25: .seealso:  PCCreate(), PCSetType(), PCType (for list of available types)
     26: S*/
     27: typedef struct _p_PC* PC;

     29: /*E
     30:     PCType - String with the name of a PETSc preconditioner method or the creation function
     31:        with an optional dynamic library name, for example
     32:        http://www.mcs.anl.gov/petsc/lib.a:mypccreate()

     34:    Level: beginner

     36:    Notes: Click on the links below to see details on a particular solver

     38: .seealso: PCSetType(), PC, PCCreate()
     39: E*/
     40: #define PCNONE            "none"
     41: #define PCJACOBI          "jacobi"
     42: #define PCSOR             "sor"
     43: #define PCLU              "lu"
     44: #define PCSHELL           "shell"
     45: #define PCBJACOBI         "bjacobi"
     46: #define PCMG              "mg"
     47: #define PCEISENSTAT       "eisenstat"
     48: #define PCILU             "ilu"
     49: #define PCICC             "icc"
     50: #define PCASM             "asm"
     51: #define PCKSP             "ksp"
     52: #define PCCOMPOSITE       "composite"
     53: #define PCREDUNDANT       "redundant"
     54: #define PCSPAI            "spai"
     55: #define PCNN              "nn"
     56: #define PCCHOLESKY        "cholesky"
     57: #define PCSAMG            "samg"
     58: #define PCPBJACOBI        "pbjacobi"
     59: #define PCMAT             "mat"
     60: #define PCHYPRE           "hypre"
     61: #define PCFIELDSPLIT      "fieldsplit"
     62: #define PCTFS             "tfs"

     64: /* Logging support */

     69: /*E
     70:     PCSide - If the preconditioner is to be applied to the left, right
     71:      or symmetrically around the operator.

     73:    Level: beginner

     75: .seealso:
     76: E*/
     77: typedef enum { PC_LEFT,PC_RIGHT,PC_SYMMETRIC } PCSide;

     79: EXTERN PetscErrorCode PCCreate(MPI_Comm,PC*);
     80: EXTERN PetscErrorCode PCSetType(PC,const PCType);
     81: EXTERN PetscErrorCode PCSetUp(PC);
     82: EXTERN PetscErrorCode PCSetUpOnBlocks(PC);
     83: EXTERN PetscErrorCode PCApply(PC,Vec,Vec);
     84: EXTERN PetscErrorCode PCApplySymmetricLeft(PC,Vec,Vec);
     85: EXTERN PetscErrorCode PCApplySymmetricRight(PC,Vec,Vec);
     86: EXTERN PetscErrorCode PCApplyBAorAB(PC,PCSide,Vec,Vec,Vec);
     87: EXTERN PetscErrorCode PCApplyTranspose(PC,Vec,Vec);
     88: EXTERN PetscErrorCode PCHasApplyTranspose(PC,PetscTruth*);
     89: EXTERN PetscErrorCode PCApplyBAorABTranspose(PC,PCSide,Vec,Vec,Vec);
     90: EXTERN PetscErrorCode PCApplyRichardson(PC,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal,PetscInt);
     91: EXTERN PetscErrorCode PCApplyRichardsonExists(PC,PetscTruth*);

     93: EXTERN PetscErrorCode        PCRegisterDestroy(void);
     94: EXTERN PetscErrorCode        PCRegisterAll(const char[]);

     97: EXTERN PetscErrorCode PCRegister(const char[],const char[],const char[],PetscErrorCode(*)(PC));

     99: /*MC
    100:    PCRegisterDynamic - Adds a method to the preconditioner package.

    102:    Synopsis:
    103:    PetscErrorCode PCRegisterDynamic(char *name_solver,char *path,char *name_create,PetscErrorCode (*routine_create)(PC))

    105:    Not collective

    107:    Input Parameters:
    108: +  name_solver - name of a new user-defined solver
    109: .  path - path (either absolute or relative) the library containing this solver
    110: .  name_create - name of routine to create method context
    111: -  routine_create - routine to create method context

    113:    Notes:
    114:    PCRegisterDynamic() may be called multiple times to add several user-defined preconditioners.

    116:    If dynamic libraries are used, then the fourth input argument (routine_create)
    117:    is ignored.

    119:    Sample usage:
    120: .vb
    121:    PCRegisterDynamic("my_solver","/home/username/my_lib/lib/libO/solaris/mylib",
    122:               "MySolverCreate",MySolverCreate);
    123: .ve

    125:    Then, your solver can be chosen with the procedural interface via
    126: $     PCSetType(pc,"my_solver")
    127:    or at runtime via the option
    128: $     -pc_type my_solver

    130:    Level: advanced

    132:    Notes: ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR}, ${BOPT}, or ${any environmental variable}
    133:            occuring in pathname will be replaced with appropriate values.
    134:          If your function is not being put into a shared library then use PCRegister() instead

    136: .keywords: PC, register

    138: .seealso: PCRegisterAll(), PCRegisterDestroy()
    139: M*/
    140: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
    141: #define PCRegisterDynamic(a,b,c,d) PCRegister(a,b,c,0)
    142: #else
    143: #define PCRegisterDynamic(a,b,c,d) PCRegister(a,b,c,d)
    144: #endif

    146: EXTERN PetscErrorCode PCDestroy(PC);
    147: EXTERN PetscErrorCode PCSetFromOptions(PC);
    148: EXTERN PetscErrorCode PCGetType(PC,PCType*);

    150: EXTERN PetscErrorCode PCGetFactoredMatrix(PC,Mat*);
    151: EXTERN PetscErrorCode PCSetModifySubMatrices(PC,PetscErrorCode(*)(PC,PetscInt,const IS[],const IS[],Mat[],void*),void*);
    152: EXTERN PetscErrorCode PCModifySubMatrices(PC,PetscInt,const IS[],const IS[],Mat[],void*);

    154: EXTERN PetscErrorCode PCSetOperators(PC,Mat,Mat,MatStructure);
    155: EXTERN PetscErrorCode PCGetOperators(PC,Mat*,Mat*,MatStructure*);

    157: EXTERN PetscErrorCode PCView(PC,PetscViewer);

    159: EXTERN PetscErrorCode PCSetOptionsPrefix(PC,const char[]);
    160: EXTERN PetscErrorCode PCAppendOptionsPrefix(PC,const char[]);
    161: EXTERN PetscErrorCode PCGetOptionsPrefix(PC,char*[]);

    163: EXTERN PetscErrorCode PCComputeExplicitOperator(PC,Mat*);

    165: /*
    166:       These are used to provide extra scaling of preconditioned
    167:    operator for time-stepping schemes like in PVODE
    168: */
    169: EXTERN PetscErrorCode PCDiagonalScale(PC,PetscTruth*);
    170: EXTERN PetscErrorCode PCDiagonalScaleLeft(PC,Vec,Vec);
    171: EXTERN PetscErrorCode PCDiagonalScaleRight(PC,Vec,Vec);
    172: EXTERN PetscErrorCode PCDiagonalScaleSet(PC,Vec);

    174: /* ------------- options specific to particular preconditioners --------- */

    176: EXTERN PetscErrorCode PCJacobiSetUseRowMax(PC);
    177: EXTERN PetscErrorCode PCSORSetSymmetric(PC,MatSORType);
    178: EXTERN PetscErrorCode PCSORSetOmega(PC,PetscReal);
    179: EXTERN PetscErrorCode PCSORSetIterations(PC,PetscInt,PetscInt);

    181: EXTERN PetscErrorCode PCEisenstatSetOmega(PC,PetscReal);
    182: EXTERN PetscErrorCode PCEisenstatNoDiagonalScaling(PC);

    184: #define USE_PRECONDITIONER_MATRIX 0
    185: #define USE_TRUE_MATRIX           1
    186: EXTERN PetscErrorCode PCBJacobiSetUseTrueLocal(PC);
    187: EXTERN PetscErrorCode PCBJacobiSetTotalBlocks(PC,PetscInt,const PetscInt[]);
    188: EXTERN PetscErrorCode PCBJacobiSetLocalBlocks(PC,PetscInt,const PetscInt[]);

    190: EXTERN PetscErrorCode PCKSPSetUseTrue(PC);

    192: EXTERN PetscErrorCode PCShellSetApply(PC,PetscErrorCode (*)(void*,Vec,Vec),void*);
    193: EXTERN PetscErrorCode PCShellSetApplyTranspose(PC,PetscErrorCode (*)(void*,Vec,Vec));
    194: EXTERN PetscErrorCode PCShellSetSetUp(PC,PetscErrorCode (*)(void*));
    195: EXTERN PetscErrorCode PCShellSetApplyRichardson(PC,PetscErrorCode (*)(void*,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal,PetscInt),void*);
    196: EXTERN PetscErrorCode PCShellSetView(PC,PetscErrorCode (*)(void*,PetscViewer));
    197: EXTERN PetscErrorCode PCShellSetName(PC,const char[]);
    198: EXTERN PetscErrorCode PCShellGetName(PC,char*[]);

    200: EXTERN PetscErrorCode PCLUSetMatOrdering(PC,MatOrderingType);
    201: EXTERN PetscErrorCode PCLUSetReuseOrdering(PC,PetscTruth);
    202: EXTERN PetscErrorCode PCLUSetReuseFill(PC,PetscTruth);
    203: EXTERN PetscErrorCode PCLUSetUseInPlace(PC);
    204: EXTERN PetscErrorCode PCLUSetFill(PC,PetscReal);
    205: EXTERN PetscErrorCode PCLUSetDamping(PC,PetscReal);
    206: EXTERN PetscErrorCode PCLUSetShift(PC,PetscTruth);
    207: EXTERN PetscErrorCode PCLUSetPivoting(PC,PetscReal);
    208: EXTERN PetscErrorCode PCLUSetPivotInBlocks(PC,PetscTruth);
    209: EXTERN PetscErrorCode PCLUSetZeroPivot(PC,PetscReal);

    211: EXTERN PetscErrorCode PCCholeskySetMatOrdering(PC,MatOrderingType);
    212: EXTERN PetscErrorCode PCCholeskySetReuseOrdering(PC,PetscTruth);
    213: EXTERN PetscErrorCode PCCholeskySetReuseFill(PC,PetscTruth);
    214: EXTERN PetscErrorCode PCCholeskySetUseInPlace(PC);
    215: EXTERN PetscErrorCode PCCholeskySetFill(PC,PetscReal);
    216: EXTERN PetscErrorCode PCCholeskySetDamping(PC,PetscReal);
    217: EXTERN PetscErrorCode PCCholeskySetShift(PC,PetscTruth);
    218: EXTERN PetscErrorCode PCCholeskySetPivotInBlocks(PC,PetscTruth);

    220: EXTERN PetscErrorCode PCILUSetMatOrdering(PC,MatOrderingType);
    221: EXTERN PetscErrorCode PCILUSetUseInPlace(PC);
    222: EXTERN PetscErrorCode PCILUSetFill(PC,PetscReal);
    223: EXTERN PetscErrorCode PCILUSetLevels(PC,PetscInt);
    224: EXTERN PetscErrorCode PCILUSetReuseOrdering(PC,PetscTruth);
    225: EXTERN PetscErrorCode PCILUSetUseDropTolerance(PC,PetscReal,PetscReal,PetscInt);
    226: EXTERN PetscErrorCode PCILUDTSetReuseFill(PC,PetscTruth);
    227: EXTERN PetscErrorCode PCILUSetAllowDiagonalFill(PC);
    228: EXTERN PetscErrorCode PCILUSetDamping(PC,PetscReal);
    229: EXTERN PetscErrorCode PCILUSetShift(PC,PetscTruth);
    230: EXTERN PetscErrorCode PCILUSetPivotInBlocks(PC,PetscTruth);
    231: EXTERN PetscErrorCode PCILUSetZeroPivot(PC,PetscReal);

    233: EXTERN PetscErrorCode PCICCSetMatOrdering(PC,MatOrderingType);
    234: EXTERN PetscErrorCode PCICCSetFill(PC,PetscReal);
    235: EXTERN PetscErrorCode PCICCSetLevels(PC,PetscInt);
    236: EXTERN PetscErrorCode PCICCSetDamping(PC,PetscReal);
    237: EXTERN PetscErrorCode PCICCSetShift(PC,PetscTruth);
    238: EXTERN PetscErrorCode PCICCSetPivotInBlocks(PC,PetscTruth);
    239: EXTERN PetscErrorCode PCICCSetZeroPivot(PC,PetscReal);

    241: EXTERN PetscErrorCode PCASMSetLocalSubdomains(PC,PetscInt,IS[]);
    242: EXTERN PetscErrorCode PCASMSetTotalSubdomains(PC,PetscInt,IS[]);
    243: EXTERN PetscErrorCode PCASMSetOverlap(PC,PetscInt);
    244: /*E
    245:     PCASMType - Type of additive Schwarz method to use

    247: $  PC_ASM_BASIC - symmetric version where residuals from the ghost points are used
    248: $                 and computed values in ghost regions are added together. Classical
    249: $                 standard additive Schwarz
    250: $  PC_ASM_RESTRICT - residuals from ghost points are used but computed values in ghost
    251: $                    region are discarded. Default
    252: $  PC_ASM_INTERPOLATE - residuals from ghost points are not used, computed values in ghost
    253: $                       region are added back in
    254: $  PC_ASM_NONE - ghost point residuals are not used, computed ghost values are discarded
    255: $                not very good.

    257:    Level: beginner

    259: .seealso: PCASMSetType()
    260: E*/
    261: typedef enum {PC_ASM_BASIC = 3,PC_ASM_RESTRICT = 1,PC_ASM_INTERPOLATE = 2,PC_ASM_NONE = 0} PCASMType;
    262: EXTERN PetscErrorCode PCASMSetType(PC,PCASMType);
    263: EXTERN PetscErrorCode PCASMCreateSubdomains2D(PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt *,IS **);
    264: EXTERN PetscErrorCode PCASMSetUseInPlace(PC);
    265: EXTERN PetscErrorCode PCASMGetLocalSubdomains(PC,PetscInt*,IS*[]);
    266: EXTERN PetscErrorCode PCASMGetLocalSubmatrices(PC,PetscInt*,Mat*[]);

    268: /*E
    269:     PCCompositeType - Determines how two or more preconditioner are composed

    271: $  PC_COMPOSITE_ADDITIVE - results from application of all preconditioners are added together
    272: $  PC_COMPOSITE_MULTIPLICATIVE - preconditioners are applied sequentially to the residual freshly
    273: $                                computed after the previous preconditioner application
    274: $  PC_COMPOSITE_SPECIAL - This is very special for a matrix of the form alpha I + R + S
    275: $                         where first preconditioner is built from alpha I + S and second from
    276: $                         alpha I + R

    278:    Level: beginner

    280: .seealso: PCCompositeSetType()
    281: E*/
    282: typedef enum {PC_COMPOSITE_ADDITIVE,PC_COMPOSITE_MULTIPLICATIVE,PC_COMPOSITE_SPECIAL} PCCompositeType;
    283: EXTERN PetscErrorCode PCCompositeSetUseTrue(PC);
    284: EXTERN PetscErrorCode PCCompositeSetType(PC,PCCompositeType);
    285: EXTERN PetscErrorCode PCCompositeAddPC(PC,PCType);
    286: EXTERN PetscErrorCode PCCompositeGetPC(PC pc,PetscInt n,PC *);
    287: EXTERN PetscErrorCode PCCompositeSpecialSetAlpha(PC,PetscScalar);

    289: EXTERN PetscErrorCode PCRedundantSetScatter(PC,VecScatter,VecScatter);
    290: EXTERN PetscErrorCode PCRedundantGetOperators(PC,Mat*,Mat*);
    291: EXTERN PetscErrorCode PCRedundantGetPC(PC,PC*);
    292: EXTERN PetscErrorCode MatGetOrderingList(PetscFList *list);

    294: EXTERN PetscErrorCode PCSPAISetEpsilon(PC,double);
    295: EXTERN PetscErrorCode PCSPAISetNBSteps(PC,PetscInt);
    296: EXTERN PetscErrorCode PCSPAISetMax(PC,PetscInt);
    297: EXTERN PetscErrorCode PCSPAISetMaxNew(PC,PetscInt);
    298: EXTERN PetscErrorCode PCSPAISetBlockSize(PC,PetscInt);
    299: EXTERN PetscErrorCode PCSPAISetCacheSize(PC,PetscInt);
    300: EXTERN PetscErrorCode PCSPAISetVerbose(PC,PetscInt);
    301: EXTERN PetscErrorCode PCSPAISetSp(PC,PetscInt);

    303: EXTERN PetscErrorCode PCHYPRESetType(PC,const char[]);
    304: EXTERN PetscErrorCode PCBJacobiGetLocalBlocks(PC,PetscInt*,const PetscInt*[]);
    305: EXTERN PetscErrorCode PCBJacobiGetTotalBlocks(PC,PetscInt*,const PetscInt*[]);

    307: EXTERN PetscErrorCode PCFieldSplitSetFields(PC,PetscInt,PetscInt*);
    308: EXTERN PetscErrorCode PCFieldSplitSetType(PC,PCCompositeType);

    311: #endif /* __PETSCPC_H */