Actual source code: petscsnes.h

  1: /* $Id: petscsnes.h,v 1.107 2001/03/22 20:31:48 bsmith Exp $ */
  2: /*
  3:     User interface for the nonlinear solvers and unconstrained minimization package.
  4: */
  7: #include "petscsles.h"

  9: /*S
 10:      SNES - Abstract PETSc object that manages all nonlinear solves

 12:    Level: beginner

 14:   Concepts: nonlinear solvers

 16: .seealso:  SNESCreate(), SNESSetType(), SNESType, TS, SLES, KSP, PC, SNESProblemType
 17: S*/
 18: typedef struct _p_SNES* SNES;

 20: #define SNES_COOKIE         PETSC_COOKIE+13
 21: #define MATSNESMFCTX_COOKIE PETSC_COOKIE+29

 23: /*E
 24:     SNESType - String with the name of a PETSc SNES method or the creation function
 25:        with an optional dynamic library name, for example
 26:        http://www.mcs.anl.gov/petsc/lib.a:mysnescreate()

 28:    Level: beginner

 30: .seealso: SNESSetType(), SNES
 31: E*/
 32: #define SNESEQLS          "ls"
 33: #define SNESEQTR          "tr"
 34: #define SNESEQTEST        "test"
 35: #define SNESUMLS          "umls"
 36: #define SNESUMTR          "umtr"
 37: typedef char *SNESType;

 39: /*E
 40:     SNESProblemType - Determines the type of problem this SNES object is to be used to solve

 42:    Level: beginner

 44: .seealso: SNESCreate()
 45: E*/
 46: typedef enum {SNES_NONLINEAR_EQUATIONS,SNES_UNCONSTRAINED_MINIMIZATION,SNES_LEAST_SQUARES} SNESProblemType;

 48: EXTERN int SNESCreate(MPI_Comm,SNESProblemType,SNES*);
 49: EXTERN int SNESDestroy(SNES);
 50: EXTERN int SNESSetType(SNES,SNESType);
 51: EXTERN int SNESSetMonitor(SNES,int(*)(SNES,int,double,void*),void *,int (*)(void *));
 52: EXTERN int SNESClearMonitor(SNES);
 53: EXTERN int SNESSetConvergenceHistory(SNES,double*,int *,int,PetscTruth);
 54: EXTERN int SNESGetConvergenceHistory(SNES,double**,int **,int *);
 55: EXTERN int SNESSetUp(SNES,Vec);
 56: EXTERN int SNESSolve(SNES,Vec,int*);

 58: extern PetscFList SNESList;
 59: EXTERN int SNESRegisterDestroy(void);
 60: EXTERN int SNESRegisterAll(char *);

 62: EXTERN int SNESRegister(char*,char*,char*,int(*)(SNES));
 63: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
 64: #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,0)
 65: #else
 66: #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,d)
 67: #endif

 69: EXTERN int SNESGetSLES(SNES,SLES*);
 70: EXTERN int SNESGetSolution(SNES,Vec*);
 71: EXTERN int SNESGetSolutionUpdate(SNES,Vec*);
 72: EXTERN int SNESGetFunction(SNES,Vec*,void**,int(**)(SNES,Vec,Vec,void*));
 73: EXTERN int SNESView(SNES,PetscViewer);

 75: EXTERN int SNESSetOptionsPrefix(SNES,char*);
 76: EXTERN int SNESAppendOptionsPrefix(SNES,char*);
 77: EXTERN int SNESGetOptionsPrefix(SNES,char**);
 78: EXTERN int SNESSetFromOptions(SNES);
 79: EXTERN int SNESSetTypeFromOptions(SNES);

 81: EXTERN int MatCreateSNESMF(SNES,Vec,Mat*);
 82: EXTERN int MatCreateMF(Vec,Mat*);
 83: EXTERN int MatSNESMFSetBase(Mat,Vec);
 84: EXTERN int MatSNESMFFormJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
 85: EXTERN int MatSNESMFSetFunction(Mat,Vec,int(*)(SNES,Vec,Vec,void*),void *);
 86: EXTERN int MatSNESMFAddNullSpace(Mat,MatNullSpace);
 87: EXTERN int MatSNESMFSetHHistory(Mat,Scalar *,int);
 88: EXTERN int MatSNESMFResetHHistory(Mat);
 89: EXTERN int MatSNESMFSetFunctionError(Mat,double);
 90: EXTERN int MatSNESMFSetPeriod(Mat,int);
 91: EXTERN int MatSNESMFGetH(Mat,Scalar *);
 92: EXTERN int MatSNESMFKSPMonitor(KSP,int,double,void *);
 93: EXTERN int MatSNESMFSetFromOptions(Mat);
 94: typedef struct _p_MatSNESMFCtx   *MatSNESMFCtx;

 96: #define MATSNESMF_DEFAULT "default"
 97: #define MATSNESMF_WP      "wp"
 98: typedef char* MatSNESMFType;
 99: EXTERN int MatSNESMFSetType(Mat,MatSNESMFType);
100: EXTERN int MatSNESMFRegister(char *,char *,char *,int (*)(MatSNESMFCtx));
101: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
102: #define MatSNESMFRegisterDynamic(a,b,c,d) MatSNESMFRegister(a,b,c,0)
103: #else
104: #define MatSNESMFRegisterDynamic(a,b,c,d) MatSNESMFRegister(a,b,c,d)
105: #endif
106: EXTERN int MatSNESMFRegisterAll(char *);
107: EXTERN int MatSNESMFRegisterDestroy(void);
108: EXTERN int MatSNESMFDefaultSetUmin(Mat,double);
109: EXTERN int MatSNESMFWPSetComputeNormA(Mat,PetscTruth);
110: EXTERN int MatSNESMFWPSetComputeNormU(Mat,PetscTruth);

112: EXTERN int SNESGetType(SNES,SNESType*);
113: EXTERN int SNESDefaultMonitor(SNES,int,double,void *);
114: EXTERN int SNESVecViewMonitor(SNES,int,double,void *);
115: EXTERN int SNESVecViewUpdateMonitor(SNES,int,double,void *);
116: EXTERN int SNESDefaultSMonitor(SNES,int,double,void *);
117: EXTERN int SNESSetTolerances(SNES,double,double,double,int,int);
118: EXTERN int SNESGetTolerances(SNES,double*,double*,double*,int*,int*);
119: EXTERN int SNESSetTrustRegionTolerance(SNES,double);
120: EXTERN int SNESGetIterationNumber(SNES,int*);
121: EXTERN int SNESGetFunctionNorm(SNES,Scalar*);
122: EXTERN int SNESGetNumberUnsuccessfulSteps(SNES,int*);
123: EXTERN int SNESGetNumberLinearIterations(SNES,int*);
124: EXTERN int SNES_KSP_SetParametersEW(SNES,int,double,double,double,double,double,double);
125: EXTERN int SNES_KSP_SetConvergenceTestEW(SNES);

127: /*
128:      Reuse the default KSP monitor routines for SNES
129: */
130: EXTERN int SNESLGMonitorCreate(char*,char*,int,int,int,int,PetscDrawLG*);
131: EXTERN int SNESLGMonitor(SNES,int,double,void*);
132: EXTERN int SNESLGMonitorDestroy(PetscDrawLG);

134: EXTERN int SNESSetApplicationContext(SNES,void *);
135: EXTERN int SNESGetApplicationContext(SNES,void **);

137: /*E
138:     SNESConvergedReason - reason a SNES method was said to 
139:          have converged or diverged

141:    Level: beginner

143:    Notes: this must match finclude/petscsnes.h 

145: .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
146: E*/
147: typedef enum {/* converged */
148:               SNES_CONVERGED_FNORM_ABS         =  2, /* F < F_minabs */
149:               SNES_CONVERGED_FNORM_RELATIVE    =  3, /* F < F_mintol*F_initial */
150:               SNES_CONVERGED_PNORM_RELATIVE    =  4, /* step size small */
151:               SNES_CONVERGED_GNORM_ABS         =  5, /* grad F < grad F_min */
152:               SNES_CONVERGED_TR_REDUCTION      =  6,
153:               SNES_CONVERGED_TR_DELTA          =  7,
154:               /* diverged */
155:               SNES_DIVERGED_FUNCTION_COUNT     = -2,
156:               SNES_DIVERGED_FNORM_NAN          = -4,
157:               SNES_DIVERGED_MAX_IT             = -5,
158:               SNES_DIVERGED_LS_FAILURE         = -6,
159:               SNES_DIVERGED_TR_REDUCTION       = -7,
160:               SNES_DIVERGED_LOCAL_MIN          = -8,  /* || J^T b || is small, implies converged to local minimum of F() */
161:               SNES_CONVERGED_ITERATING         =  0} SNESConvergedReason;

163: EXTERN int SNESSetConvergenceTest(SNES,int (*)(SNES,double,double,double,SNESConvergedReason*,void*),void*);
164: EXTERN int SNESConverged_UM_LS(SNES,double,double,double,SNESConvergedReason*,void*);
165: EXTERN int SNESConverged_UM_TR(SNES,double,double,double,SNESConvergedReason*,void*);
166: EXTERN int SNESConverged_EQ_LS(SNES,double,double,double,SNESConvergedReason*,void*);
167: EXTERN int SNESConverged_EQ_TR(SNES,double,double,double,SNESConvergedReason*,void*);
168: EXTERN int SNESGetConvergedReason(SNES,SNESConvergedReason*);

170: /* --------- Solving systems of nonlinear equations --------------- */
171: EXTERN int SNESSetFunction(SNES,Vec,int(*)(SNES,Vec,Vec,void*),void *);
172: EXTERN int SNESComputeFunction(SNES,Vec,Vec);
173: EXTERN int SNESSetJacobian(SNES,Mat,Mat,int(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *);
174: EXTERN int SNESGetJacobian(SNES,Mat*,Mat*,void **,int(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*));
175: EXTERN int SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
176: EXTERN int SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
177: EXTERN int SNESSetLineSearch(SNES,int(*)(SNES,void*,Vec,Vec,Vec,Vec,Vec,double,double*,double*,int*),void*);
178: EXTERN int SNESNoLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,double,double*,double*,int*);
179: EXTERN int SNESNoLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,Vec,Vec,double,double*,double*,int*);
180: EXTERN int SNESCubicLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,double,double*,double*,int*);
181: EXTERN int SNESQuadraticLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,double,double*,double*,int*);
182: EXTERN int SNESSetLineSearchCheck(SNES,int(*)(SNES,void*,Vec,PetscTruth*),void*);
183: EXTERN int SNESSetLineSearchParams(SNES,double,double,double);
184: EXTERN int SNESGetLineSearchParams(SNES,double*,double*,double*);

186: /* --------- Unconstrained minimization routines --------------------------------*/
187: EXTERN int SNESSetHessian(SNES,Mat,Mat,int(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *);
188: EXTERN int SNESGetHessian(SNES,Mat*,Mat*,void **);
189: EXTERN int SNESDefaultComputeHessian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
190: EXTERN int SNESDefaultComputeHessianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
191: EXTERN int SNESSetGradient(SNES,Vec,int(*)(SNES,Vec,Vec,void*),void*);
192: EXTERN int SNESGetGradient(SNES,Vec*,void**);
193: EXTERN int SNESGetGradientNorm(SNES,Scalar*);
194: EXTERN int SNESComputeGradient(SNES,Vec,Vec);
195: EXTERN int SNESSetMinimizationFunction(SNES,int(*)(SNES,Vec,double*,void*),void*);
196: EXTERN int SNESComputeMinimizationFunction(SNES,Vec,double*);
197: EXTERN int SNESGetMinimizationFunction(SNES,double*,void**);
198: EXTERN int SNESSetMinimizationFunctionTolerance(SNES,double);
199: EXTERN int SNESLineSearchSetDampingParameter(SNES,Scalar*);


202: /* Should these 2 routines be private? */
203: EXTERN int SNESComputeHessian(SNES,Vec,Mat*,Mat*,MatStructure*);
204: EXTERN int SNESComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*);

206: #endif