Actual source code: petscda.h
1: /*
2: Regular array object, for easy parallelism of simple grid
3: problems on regular distributed arrays.
4: */
7: #include petscvec.h
8: #include petscao.h
11: /*S
12: DA - Abstract PETSc object that manages distributed field data for a single structured grid
14: Level: beginner
16: Concepts: distributed array
18: .seealso: DACreate1d(), DACreate2d(), DACreate3d(), DADestroy(), VecScatter
19: S*/
20: typedef struct _p_DA* DA;
22: /*E
23: DAStencilType - Determines if the stencil extends only along the coordinate directions, or also
24: to the northeast, northwest etc
26: Level: beginner
28: .seealso: DACreate1d(), DACreate2d(), DACreate3d(), DA
29: E*/
30: typedef enum { DA_STENCIL_STAR,DA_STENCIL_BOX } DAStencilType;
32: /*M
33: DA_STENCIL_STAR - "Star"-type stencil. In logical grid coordinates, only (i,j,k), (i+s,j,k), (i,j+s,k),
34: (i,j,k+s) are in the stencil NOT, for example, (i+s,j+s,k)
36: Level: beginner
38: .seealso: DA_STENCIL_BOX, DAStencilType
39: M*/
41: /*M
42: DA_STENCIL_Box - "Box"-type stencil. In logical grid coordinates, any of (i,j,k), (i+s,j+r,k+t) may
43: be in the stencil.
45: Level: beginner
47: .seealso: DA_STENCIL_STAR, DAStencilType
48: M*/
50: /*E
51: DAPeriodicType - Is the domain periodic in one or more directions
53: Level: beginner
55: .seealso: DACreate1d(), DACreate2d(), DACreate3d(), DA
56: E*/
57: typedef enum { DA_NONPERIODIC,DA_XPERIODIC,DA_YPERIODIC,DA_XYPERIODIC,
58: DA_XYZPERIODIC,DA_XZPERIODIC,DA_YZPERIODIC,DA_ZPERIODIC}
59: DAPeriodicType;
61: /*E
62: DAInterpolationType - Defines the type of interpolation that will be returned by
63: DAGetInterpolation.
65: Level: beginner
67: .seealso: DACreate1d(), DACreate2d(), DACreate3d(), DA, DAGetInterpolation(), DASetInterpolationType()
68: E*/
69: typedef enum { DA_Q0, DA_Q1 } DAInterpolationType;
71: EXTERN PetscErrorCode DASetInterpolationType(DA,DAInterpolationType);
73: /*E
74: DAElementType - Defines the type of elements that will be returned by
75: DAGetElements.
77: Level: beginner
79: .seealso: DACreate1d(), DACreate2d(), DACreate3d(), DA, DAGetInterpolation(), DASetInterpolationType(),
80: DASetElementType(), DAGetElements(), DARestoreElements()
81: E*/
82: typedef enum { DA_ELEMENT_P1, DA_ELEMENT_Q1 } DAElementType;
84: EXTERN PetscErrorCode DASetElementType(DA,DAElementType);
85: EXTERN PetscErrorCode DAGetElements(DA,PetscInt *,const PetscInt*[]);
86: EXTERN PetscErrorCode DARestoreElements(DA,PetscInt *,const PetscInt*[]);
89: #define DAXPeriodic(pt) ((pt)==DA_XPERIODIC||(pt)==DA_XYPERIODIC||(pt)==DA_XZPERIODIC||(pt)==DA_XYZPERIODIC)
90: #define DAYPeriodic(pt) ((pt)==DA_YPERIODIC||(pt)==DA_XYPERIODIC||(pt)==DA_YZPERIODIC||(pt)==DA_XYZPERIODIC)
91: #define DAZPeriodic(pt) ((pt)==DA_ZPERIODIC||(pt)==DA_XZPERIODIC||(pt)==DA_YZPERIODIC||(pt)==DA_XYZPERIODIC)
93: typedef enum { DA_X,DA_Y,DA_Z } DADirection;
98: EXTERN PetscErrorCode DACreate1d(MPI_Comm,DAPeriodicType,PetscInt,PetscInt,PetscInt,PetscInt*,DA *);
99: EXTERN PetscErrorCode DACreate2d(MPI_Comm,DAPeriodicType,DAStencilType,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt*,PetscInt*,DA *);
100: EXTERN PetscErrorCode DACreate3d(MPI_Comm,DAPeriodicType,DAStencilType,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt*,PetscInt*,PetscInt*,DA*);
101: EXTERN PetscErrorCode DADestroy(DA);
102: EXTERN PetscErrorCode DAView(DA,PetscViewer);
103: EXTERN PetscErrorCode DAPrintHelp(DA);
105: EXTERN PetscErrorCode DAGlobalToLocalBegin(DA,Vec,InsertMode,Vec);
106: EXTERN PetscErrorCode DAGlobalToLocalEnd(DA,Vec,InsertMode,Vec);
107: EXTERN PetscErrorCode DAGlobalToNaturalBegin(DA,Vec,InsertMode,Vec);
108: EXTERN PetscErrorCode DAGlobalToNaturalEnd(DA,Vec,InsertMode,Vec);
109: EXTERN PetscErrorCode DANaturalToGlobalBegin(DA,Vec,InsertMode,Vec);
110: EXTERN PetscErrorCode DANaturalToGlobalEnd(DA,Vec,InsertMode,Vec);
111: EXTERN PetscErrorCode DALocalToLocalBegin(DA,Vec,InsertMode,Vec);
112: EXTERN PetscErrorCode DALocalToLocalEnd(DA,Vec,InsertMode,Vec);
113: EXTERN PetscErrorCode DALocalToGlobal(DA,Vec,InsertMode,Vec);
114: EXTERN PetscErrorCode DALocalToGlobalBegin(DA,Vec,Vec);
115: EXTERN PetscErrorCode DALocalToGlobalEnd(DA,Vec,Vec);
116: EXTERN PetscErrorCode DAGetOwnershipRange(DA,PetscInt **,PetscInt **,PetscInt **);
117: EXTERN PetscErrorCode DACreateGlobalVector(DA,Vec *);
118: EXTERN PetscErrorCode DACreateNaturalVector(DA,Vec *);
119: EXTERN PetscErrorCode DACreateLocalVector(DA,Vec *);
120: EXTERN PetscErrorCode DAGetLocalVector(DA,Vec *);
121: EXTERN PetscErrorCode DARestoreLocalVector(DA,Vec *);
122: EXTERN PetscErrorCode DAGetGlobalVector(DA,Vec *);
123: EXTERN PetscErrorCode DARestoreGlobalVector(DA,Vec *);
124: EXTERN PetscErrorCode DALoad(PetscViewer,PetscInt,PetscInt,PetscInt,DA *);
125: EXTERN PetscErrorCode DAGetCorners(DA,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
126: EXTERN PetscErrorCode DAGetGhostCorners(DA,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
127: EXTERN PetscErrorCode DAGetInfo(DA,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,DAPeriodicType*,DAStencilType*);
128: EXTERN PetscErrorCode DAGetProcessorSubset(DA,DADirection,PetscInt,MPI_Comm*);
129: EXTERN PetscErrorCode DARefine(DA,MPI_Comm,DA*);
131: EXTERN PetscErrorCode DAGlobalToNaturalAllCreate(DA,VecScatter*);
132: EXTERN PetscErrorCode DANaturalAllToGlobalCreate(DA,VecScatter*);
134: EXTERN PetscErrorCode DAGetGlobalIndices(DA,PetscInt*,PetscInt**);
135: EXTERN PetscErrorCode DAGetISLocalToGlobalMapping(DA,ISLocalToGlobalMapping*);
136: EXTERN PetscErrorCode DAGetISLocalToGlobalMappingBlck(DA,ISLocalToGlobalMapping*);
138: EXTERN PetscErrorCode DAGetScatter(DA,VecScatter*,VecScatter*,VecScatter*);
140: EXTERN PetscErrorCode DAGetAO(DA,AO*);
141: EXTERN PetscErrorCode DASetCoordinates(DA,Vec);
142: EXTERN PetscErrorCode DAGetCoordinates(DA,Vec *);
143: EXTERN PetscErrorCode DAGetGhostedCoordinates(DA,Vec *);
144: EXTERN PetscErrorCode DAGetCoordinateDA(DA,DA *);
145: EXTERN PetscErrorCode DASetUniformCoordinates(DA,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal);
146: EXTERN PetscErrorCode DASetFieldName(DA,PetscInt,const char[]);
147: EXTERN PetscErrorCode DAGetFieldName(DA,PetscInt,char **);
149: EXTERN PetscErrorCode DAVecGetArray(DA,Vec,void *);
150: EXTERN PetscErrorCode DAVecRestoreArray(DA,Vec,void *);
152: EXTERN PetscErrorCode DASplitComm2d(MPI_Comm,PetscInt,PetscInt,PetscInt,MPI_Comm*);
154: /*S
155: SDA - This provides a simplified interface to the DA distributed
156: array object in PETSc. This is intended for people who are
157: NOT using PETSc vectors or objects but just want to distribute
158: simple rectangular arrays amoung a number of procesors and have
159: PETSc handle moving the ghost-values when needed.
161: In certain applications this can serve as a replacement for
162: BlockComm (which is apparently being phased out?).
165: Level: beginner
167: Concepts: simplified distributed array
169: .seealso: SDACreate1d(), SDACreate2d(), SDACreate3d(), SDADestroy(), DA, SDALocalToLocalBegin(),
170: SDALocalToLocalEnd(), SDAGetCorners(), SDAGetGhostCorners()
171: S*/
172: typedef struct _SDA* SDA;
174: EXTERN PetscErrorCode SDACreate3d(MPI_Comm,DAPeriodicType,DAStencilType,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt*,PetscInt*,PetscInt*,SDA*);
175: EXTERN PetscErrorCode SDACreate2d(MPI_Comm,DAPeriodicType,DAStencilType,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt*,PetscInt*,SDA*);
176: EXTERN PetscErrorCode SDACreate1d(MPI_Comm,DAPeriodicType,PetscInt,PetscInt,PetscInt,PetscInt*,SDA*);
177: EXTERN PetscErrorCode SDADestroy(SDA);
178: EXTERN PetscErrorCode SDALocalToLocalBegin(SDA,PetscScalar*,InsertMode,PetscScalar*);
179: EXTERN PetscErrorCode SDALocalToLocalEnd(SDA,PetscScalar*,InsertMode,PetscScalar*);
180: EXTERN PetscErrorCode SDAGetCorners(SDA,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
181: EXTERN PetscErrorCode SDAGetGhostCorners(SDA,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
183: EXTERN PetscErrorCode MatRegisterDAAD(void);
184: EXTERN PetscErrorCode MatCreateDAAD(DA,Mat*);
186: /*S
187: DALocalInfo - C struct that contains information about a structured grid and a processors logical
188: location in it.
190: Level: beginner
192: Concepts: distributed array
194: Developer note: Then entries in this struct are int instead of PetscInt so that the elements may
195: be extracted in Fortran as if from an integer array
197: .seealso: DACreate1d(), DACreate2d(), DACreate3d(), DADestroy(), DA, DAGetLocalInfo(), DAGetInfo()
198: S*/
199: typedef struct {
200: int dim,dof,sw;
201: DAPeriodicType pt;
202: DAStencilType st;
203: int mx,my,mz; /* global number of grid points in each direction */
204: int xs,ys,zs; /* starting pointd of this processor, excluding ghosts */
205: int xm,ym,zm; /* number of grid points on this processor, excluding ghosts */
206: int gxs,gys,gzs; /* starting point of this processor including ghosts */
207: int gxm,gym,gzm; /* number of grid points on this processor including ghosts */
208: DA da;
209: } DALocalInfo;
211: /*MC
212: DAForEachPointBegin2d - Starts a loop over the local part of a two dimensional DA
214: Synopsis:
215: void DAForEachPointBegin2d(DALocalInfo *info,PetscInt i,PetscInt j);
216:
217: Level: intermediate
219: .seealso: DAForEachPointEnd2d(), DAVecGetArray()
220: M*/
221: #define DAForEachPointBegin2d(info,i,j) {\
222: PetscInt _xints = info->xs,_xinte = info->xs+info->xm,_yints = info->ys,_yinte = info->ys+info->ym;\
223: for (j=_yints; j<_yinte; j++) {\
224: for (i=_xints; i<_xinte; i++) {\
226: /*MC
227: DAForEachPointEnd2d - Ends a loop over the local part of a two dimensional DA
229: Synopsis:
230: void DAForEachPointEnd2d;
231:
232: Level: intermediate
234: .seealso: DAForEachPointBegin2d(), DAVecGetArray()
235: M*/
236: #define DAForEachPointEnd2d }}}
238: /*MC
239: DACoor2d - Structure for holding 2d (x and y) coordinates.
241: Level: intermediate
243: Sample Usage:
244: DACoor2d **coors;
245: Vec vcoors;
246: DA cda;
248: DAGetCoordinates(da,&vcoors);
249: DAGetCoordinateDA(da,&cda);
250: DAVecGetArray(dac,vcoors,&coors);
251: DAGetCorners(dac,&mstart,&nstart,0,&m,&n,0)
252: for (i=mstart; i<mstart+m; i++) {
253: for (j=nstart; j<nstart+n; j++) {
254: x = coors[j][i].x;
255: y = coors[j][i].y;
256: ......
257: }
258: }
259: DAVecRestoreArray(dac,vcoors,&coors);
261: .seealso: DACoor3d, DAForEachPointBegin(), DAGetCoordinateDA(), DAGetCoordinates(), DAGetGhostCoordinates()
262: M*/
263: typedef struct {PetscScalar x,y;} DACoor2d;
265: /*MC
266: DACoor3d - Structure for holding 3d (x, y and z) coordinates.
268: Level: intermediate
270: Sample Usage:
271: DACoor3d **coors;
272: Vec vcoors;
273: DA cda;
275: DAGetCoordinates(da,&vcoors);
276: DAGetCoordinateDA(da,&cda);
277: DAVecGetArray(dac,vcoors,&coors);
278: DAGetCorners(dac,&mstart,&nstart,&pstart,&m,&n,&p)
279: for (i=mstart; i<mstart+m; i++) {
280: for (j=nstart; j<nstart+n; j++) {
281: for (k=pstart; k<pstart+p; k++) {
282: x = coors[k][j][i].x;
283: y = coors[k][j][i].y;
284: z = coors[k][j][i].z;
285: ......
286: }
287: }
288: DAVecRestoreArray(dac,vcoors,&coors);
290: .seealso: DACoor2d, DAForEachPointBegin(), DAGetCoordinateDA(), DAGetCoordinates(), DAGetGhostCoordinates()
291: M*/
292: typedef struct {PetscScalar x,y,z;} DACoor3d;
293:
294: EXTERN PetscErrorCode DAGetLocalInfo(DA,DALocalInfo*);
295: typedef PetscErrorCode (*DALocalFunction1)(DALocalInfo*,void*,void*,void*);
296: EXTERN PetscErrorCode DAFormFunction1(DA,Vec,Vec,void*);
297: EXTERN PetscErrorCode DAFormFunctioni1(DA,PetscInt,Vec,PetscScalar*,void*);
298: EXTERN PetscErrorCode DAComputeJacobian1WithAdic(DA,Vec,Mat,void*);
299: EXTERN PetscErrorCode DAComputeJacobian1WithAdifor(DA,Vec,Mat,void*);
300: EXTERN PetscErrorCode DAMultiplyByJacobian1WithAdic(DA,Vec,Vec,Vec,void*);
301: EXTERN PetscErrorCode DAMultiplyByJacobian1WithAdifor(DA,Vec,Vec,Vec,void*);
302: EXTERN PetscErrorCode DAMultiplyByJacobian1WithAD(DA,Vec,Vec,Vec,void*);
303: EXTERN PetscErrorCode DAComputeJacobian1(DA,Vec,Mat,void*);
304: EXTERN PetscErrorCode DAGetLocalFunction(DA,DALocalFunction1*);
305: EXTERN PetscErrorCode DASetLocalFunction(DA,DALocalFunction1);
306: EXTERN PetscErrorCode DASetLocalFunctioni(DA,PetscErrorCode (*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*));
307: EXTERN PetscErrorCode DASetLocalJacobian(DA,DALocalFunction1);
308: EXTERN PetscErrorCode DASetLocalAdicFunction_Private(DA,DALocalFunction1);
310: /*MC
311: DASetLocalAdicFunction - Caches in a DA a local function computed by ADIC/ADIFOR
313: Collective on DA
315: Synopsis:
316: PetscErrorCode DASetLocalAdicFunction(DA da,DALocalFunction1 ad_lf)
317:
318: Input Parameter:
319: + da - initial distributed array
320: - ad_lf - the local function as computed by ADIC/ADIFOR
322: Level: intermediate
324: .keywords: distributed array, refine
326: .seealso: DACreate1d(), DACreate2d(), DACreate3d(), DADestroy(), DAGetLocalFunction(), DASetLocalFunction(),
327: DASetLocalJacobian()
328: M*/
329: #if defined(PETSC_HAVE_ADIC) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
330: # define DASetLocalAdicFunction(a,d) DASetLocalAdicFunction_Private(a,(DALocalFunction1)d)
331: #else
332: # define DASetLocalAdicFunction(a,d) DASetLocalAdicFunction_Private(a,0)
333: #endif
335: EXTERN PetscErrorCode DASetLocalAdicMFFunction_Private(DA,DALocalFunction1);
336: #if defined(PETSC_HAVE_ADIC) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
337: # define DASetLocalAdicMFFunction(a,d) DASetLocalAdicMFFunction_Private(a,(DALocalFunction1)d)
338: #else
339: # define DASetLocalAdicMFFunction(a,d) DASetLocalAdicMFFunction_Private(a,0)
340: #endif
341: EXTERN PetscErrorCode DASetLocalAdicFunctioni_Private(DA,PetscErrorCode (*)(DALocalInfo*,MatStencil*,void*,void*,void*));
342: #if defined(PETSC_HAVE_ADIC) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
343: # define DASetLocalAdicFunctioni(a,d) DASetLocalAdicFunctioni_Private(a,(PetscErrorCode (*)(DALocalInfo*,MatStencil*,void*,void*,void*))d)
344: #else
345: # define DASetLocalAdicFunctioni(a,d) DASetLocalAdicFunctioni_Private(a,0)
346: #endif
347: EXTERN PetscErrorCode DASetLocalAdicMFFunctioni_Private(DA,PetscErrorCode (*)(DALocalInfo*,MatStencil*,void*,void*,void*));
348: #if defined(PETSC_HAVE_ADIC) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
349: # define DASetLocalAdicMFFunctioni(a,d) DASetLocalAdicMFFunctioni_Private(a,(PetscErrorCode (*)(DALocalInfo*,MatStencil*,void*,void*,void*))d)
350: #else
351: # define DASetLocalAdicMFFunctioni(a,d) DASetLocalAdicMFFunctioni_Private(a,0)
352: #endif
353: EXTERN PetscErrorCode DAFormFunctioniTest1(DA,void*);
355: #include petscmat.h
356: EXTERN PetscErrorCode DAGetColoring(DA,ISColoringType,ISColoring *);
357: EXTERN PetscErrorCode DAGetMatrix(DA,const MatType,Mat *);
358: EXTERN PetscErrorCode DASetGetMatrix(DA,PetscErrorCode (*)(DA,const MatType,Mat *));
359: EXTERN PetscErrorCode DAGetInterpolation(DA,DA,Mat*,Vec*);
360: EXTERN PetscErrorCode DAGetInjection(DA,DA,VecScatter*);
361: EXTERN PetscErrorCode DASetBlockFills(DA,PetscInt*,PetscInt*);
362: EXTERN PetscErrorCode DASetRefinementFactor(DA,PetscInt,PetscInt,PetscInt);
363: EXTERN PetscErrorCode DAGetRefinementFactor(DA,PetscInt*,PetscInt*,PetscInt*);
365: EXTERN PetscErrorCode DAGetAdicArray(DA,PetscTruth,void**,void**,PetscInt*);
366: EXTERN PetscErrorCode DARestoreAdicArray(DA,PetscTruth,void**,void**,PetscInt*);
367: EXTERN PetscErrorCode DAGetAdicMFArray(DA,PetscTruth,void**,void**,PetscInt*);
368: EXTERN PetscErrorCode DARestoreAdicMFArray(DA,PetscTruth,void**,void**,PetscInt*);
369: EXTERN PetscErrorCode DAGetArray(DA,PetscTruth,void**);
370: EXTERN PetscErrorCode DARestoreArray(DA,PetscTruth,void**);
371: EXTERN PetscErrorCode ad_DAGetArray(DA,PetscTruth,void**);
372: EXTERN PetscErrorCode ad_DARestoreArray(DA,PetscTruth,void**);
373: EXTERN PetscErrorCode admf_DAGetArray(DA,PetscTruth,void**);
374: EXTERN PetscErrorCode admf_DARestoreArray(DA,PetscTruth,void**);
376: #include petscpf.h
377: EXTERN PetscErrorCode DACreatePF(DA,PF*);
379: /*S
380: VecPack - Abstract PETSc object that manages treating several distinct vectors as if they
381: were one. The VecPack routines allow one to manage a nonlinear solver that works on a
382: vector that consists of several distinct parts. This is mostly used for LNKS solvers,
383: that is design optimization problems that are written as a nonlinear system
385: Level: beginner
387: Concepts: multi-component, LNKS solvers
389: .seealso: VecPackCreate(), VecPackDestroy()
390: S*/
391: typedef struct _p_VecPack *VecPack;
393: EXTERN PetscErrorCode VecPackCreate(MPI_Comm,VecPack*);
394: EXTERN PetscErrorCode VecPackDestroy(VecPack);
395: EXTERN PetscErrorCode VecPackAddArray(VecPack,PetscInt);
396: EXTERN PetscErrorCode VecPackAddDA(VecPack,DA);
397: EXTERN PetscErrorCode VecPackAddVecScatter(VecPack,VecScatter);
398: EXTERN PetscErrorCode VecPackScatter(VecPack,Vec,...);
399: EXTERN PetscErrorCode VecPackGather(VecPack,Vec,...);
400: EXTERN PetscErrorCode VecPackGetAccess(VecPack,Vec,...);
401: EXTERN PetscErrorCode VecPackRestoreAccess(VecPack,Vec,...);
402: EXTERN PetscErrorCode VecPackGetLocalVectors(VecPack,...);
403: EXTERN PetscErrorCode VecPackGetEntries(VecPack,...);
404: EXTERN PetscErrorCode VecPackRestoreLocalVectors(VecPack,...);
405: EXTERN PetscErrorCode VecPackCreateGlobalVector(VecPack,Vec*);
406: EXTERN PetscErrorCode VecPackGetGlobalIndices(VecPack,...);
407: EXTERN PetscErrorCode VecPackRefine(VecPack,MPI_Comm,VecPack*);
408: EXTERN PetscErrorCode VecPackGetInterpolation(VecPack,VecPack,Mat*,Vec*);
410: #include petscsnes.h
412: /*S
413: DM - Abstract PETSc object that manages an abstract grid object
414:
415: Level: intermediate
417: Concepts: grids, grid refinement
419: Notes: The DA object and the VecPack object are examples of DMs
421: Though the DA objects require the petscsnes.h include files the DM library is
422: NOT dependent on the SNES or KSP library. In fact, the KSP and SNES libraries depend on
423: DM. (This is not great design, but not trivial to fix).
425: .seealso: VecPackCreate(), DA, VecPack
426: S*/
427: typedef struct _p_DM* DM;
429: EXTERN PetscErrorCode DMView(DM,PetscViewer);
430: EXTERN PetscErrorCode DMDestroy(DM);
431: EXTERN PetscErrorCode DMCreateGlobalVector(DM,Vec*);
432: EXTERN PetscErrorCode DMGetColoring(DM,ISColoringType,ISColoring*);
433: EXTERN PetscErrorCode DMGetMatrix(DM,const MatType,Mat*);
434: EXTERN PetscErrorCode DMGetInterpolation(DM,DM,Mat*,Vec*);
435: EXTERN PetscErrorCode DMGetInjection(DM,DM,VecScatter*);
436: EXTERN PetscErrorCode DMRefine(DM,MPI_Comm,DM*);
437: EXTERN PetscErrorCode DMGetInterpolationScale(DM,DM,Mat,Vec*);
439: typedef struct NLF_DAAD* NLF;
441: /*S
442: DMMG - Data structure to easily manage multi-level non-linear solvers on grids managed by DM
443:
444: Level: intermediate
446: Concepts: multigrid, Newton-multigrid
448: .seealso: VecPackCreate(), DA, VecPack, DM, DMMGCreate(), DMMGSetKSP(), DMMGSetSNES()
449: S*/
450: typedef struct _p_DMMG *DMMG;
451: struct _p_DMMG {
452: DM dm; /* grid information for this level */
453: Vec x,b,r; /* global vectors used in multigrid preconditioner for this level*/
454: Mat J; /* matrix on this level */
455: Mat R; /* restriction to next coarser level (not defined on level 0) */
456: PetscInt nlevels; /* number of levels above this one (total number of levels on level 0)*/
457: MPI_Comm comm;
458: PetscErrorCode (*solve)(DMMG*,PetscInt);
459: void *user;
460: PetscTruth galerkin; /* for A_c = R*A*R^T */
462: /* KSP only */
463: KSP ksp;
464: PetscErrorCode (*rhs)(DMMG,Vec);
465: PetscTruth matricesset; /* User had called DMMGSetKSP() and the matrices have been computed */
467: /* SNES only */
468: Mat B;
469: Vec Rscale; /* scaling to restriction before computing Jacobian */
470: PetscErrorCode (*computejacobian)(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
471: PetscErrorCode (*computefunction)(SNES,Vec,Vec,void*);
473: PetscTruth updatejacobian; /* compute new Jacobian when DMMGComputeJacobian_Multigrid() is called */
474: PetscInt updatejacobianperiod; /* how often, inside a SNES, the Jacobian is recomputed */
476: MatFDColoring fdcoloring; /* only used with FD coloring for Jacobian */
477: SNES snes;
478: PetscErrorCode (*initialguess)(DMMG,Vec);
479: Vec w,work1,work2; /* global vectors */
480: Vec lwork1;
482: /* FAS only */
483: NLF nlf; /* FAS smoother object */
484: VecScatter inject; /* inject from this level to the next coarsest */
485: PetscTruth monitor,monitorall;
486: PetscInt presmooth,postsmooth,coarsesmooth;
487: PetscReal rtol,abstol,rrtol; /* convergence tolerance */
488:
489: };
491: EXTERN PetscErrorCode DMMGCreate(MPI_Comm,PetscInt,void*,DMMG**);
492: EXTERN PetscErrorCode DMMGDestroy(DMMG*);
493: EXTERN PetscErrorCode DMMGSetUp(DMMG*);
494: EXTERN PetscErrorCode DMMGSetKSP(DMMG*,PetscErrorCode (*)(DMMG,Vec),PetscErrorCode (*)(DMMG,Mat));
495: EXTERN PetscErrorCode DMMGSetSNES(DMMG*,PetscErrorCode (*)(SNES,Vec,Vec,void*),PetscErrorCode (*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*));
496: EXTERN PetscErrorCode DMMGSetInitialGuess(DMMG*,PetscErrorCode (*)(DMMG,Vec));
497: EXTERN PetscErrorCode DMMGInitialGuessCurrent(DMMG,Vec);
498: EXTERN PetscErrorCode DMMGView(DMMG*,PetscViewer);
499: EXTERN PetscErrorCode DMMGSolve(DMMG*);
500: EXTERN PetscErrorCode DMMGSetUseMatrixFree(DMMG*);
501: EXTERN PetscErrorCode DMMGSetDM(DMMG*,DM);
502: EXTERN PetscErrorCode DMMGSetUpLevel(DMMG*,KSP,PetscInt);
503: EXTERN PetscErrorCode DMMGSetUseGalerkinCoarse(DMMG*);
504: EXTERN PetscErrorCode DMMGSetNullSpace(DMMG*,PetscTruth,PetscInt,PetscErrorCode (*)(DMMG,Vec[]));
506: EXTERN PetscErrorCode DMMGSetSNESLocal_Private(DMMG*,DALocalFunction1,DALocalFunction1,DALocalFunction1,DALocalFunction1);
507: #if defined(PETSC_HAVE_ADIC) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
508: # define DMMGSetSNESLocal(dmmg,function,jacobian,ad_function,admf_function) \
509: DMMGSetSNESLocal_Private(dmmg,(DALocalFunction1)function,(DALocalFunction1)jacobian,(DALocalFunction1)(ad_function),(DALocalFunction1)(admf_function))
510: #else
511: # define DMMGSetSNESLocal(dmmg,function,jacobian,ad_function,admf_function) DMMGSetSNESLocal_Private(dmmg,(DALocalFunction1)function,(DALocalFunction1)jacobian,(DALocalFunction1)0,(DALocalFunction1)0)
512: #endif
514: EXTERN PetscErrorCode DMMGSetSNESLocali_Private(DMMG*,PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*),PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*),PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*));
515: #if defined(PETSC_HAVE_ADIC) && !defined(PETSC_USE_COMPLEX) && !defined(PETSC_USE_SINGLE)
516: # define DMMGSetSNESLocali(dmmg,function,ad_function,admf_function) DMMGSetSNESLocali_Private(dmmg,(PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*))function,(PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*))(ad_function),(PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,void*,void*))(admf_function))
517: #else
518: # define DMMGSetSNESLocali(dmmg,function,ad_function,admf_function) DMMGSetSNESLocali_Private(dmmg,(PetscErrorCode(*)(DALocalInfo*,MatStencil*,void*,PetscScalar*,void*))function,0,0)
519: #endif
521: /*MC
522: DMMGGetb - Returns the right hand side vector from a DMMG solve on the finest grid
524: Synopsis:
525: Vec DMMGGetb(DMMG *dmmg)
527: Not Collective, but resulting vector is parallel
529: Input Parameters:
530: . dmmg - DMMG solve context
532: Level: intermediate
534: Fortran Usage:
535: . DMMGGetb(DMMG dmmg,Vec b,PetscErrorCode ierr)
537: .seealso: DMMGCreate(), DMMGSetSNES(), DMMGSetKSP(), DMMGSetSNESLocal(), DMMGGetb()
539: M*/
540: #define DMMGGetb(ctx) (ctx)[(ctx)[0]->nlevels-1]->b
542: #define DMMGGetr(ctx) (ctx)[(ctx)[0]->nlevels-1]->r
544: /*MC
545: DMMGGetx - Returns the solution vector from a DMMG solve on the finest grid
547: Synopsis:
548: Vec DMMGGetx(DMMG *dmmg)
550: Not Collective, but resulting vector is parallel
552: Input Parameters:
553: . dmmg - DMMG solve context
555: Level: intermediate
557: Fortran Usage:
558: . DMMGGetx(DMMG dmmg,Vec x,PetscErrorCode ierr)
560: .seealso: DMMGCreate(), DMMGSetSNES(), DMMGSetKSP(), DMMGSetSNESLocal()
562: M*/
563: #define DMMGGetx(ctx) (ctx)[(ctx)[0]->nlevels-1]->x
565: /*MC
566: DMMGGetJ - Returns the Jacobian (matrix) for the finest level
568: Synopsis:
569: Mat DMMGGetJ(DMMG *dmmg)
571: Not Collective
573: Input Parameter:
574: . dmmg - DMMG solve context
576: Level: intermediate
578: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetB()
580: M*/
581: #define DMMGGetJ(ctx) (ctx)[(ctx)[0]->nlevels-1]->J
583: /*MC
584: DMMGGetComm - Returns the MPI_Comm for the finest level
586: Synopsis:
587: MPI_Comm DMMGGetJ(DMMG *dmmg)
589: Not Collective
591: Input Parameter:
592: . dmmg - DMMG solve context
594: Level: intermediate
596: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ()
598: M*/
599: #define DMMGGetComm(ctx) (ctx)[(ctx)[0]->nlevels-1]->comm
601: /*MC
602: DMMGGetB - Returns the matrix for the finest level used to construct the preconditioner; usually
603: the same as the Jacobian
605: Synopsis:
606: Mat DMMGGetJ(DMMG *dmmg)
608: Not Collective
610: Input Parameter:
611: . dmmg - DMMG solve context
613: Level: intermediate
615: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ()
617: M*/
618: #define DMMGGetB(ctx) (ctx)[(ctx)[0]->nlevels-1]->B
620: /*MC
621: DMMGGetFine - Returns the DMMG associated with the finest level
623: Synopsis:
624: DMMG DMMGGetFine(DMMG *dmmg)
626: Not Collective
628: Input Parameter:
629: . dmmg - DMMG solve context
631: Level: intermediate
633: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ()
635: M*/
636: #define DMMGGetFine(ctx) (ctx)[(ctx)[0]->nlevels-1]
639: /*MC
640: DMMGGetKSP - Gets the KSP object (linear solver object) for the finest level
642: Synopsis:
643: KSP DMMGGetKSP(DMMG *dmmg)
645: Not Collective
647: Input Parameter:
648: . dmmg - DMMG solve context
650: Level: intermediate
652: Notes: If this is a linear problem (i.e. DMMGSetKSP() was used) then this is the
653: master linear solver. If this is a nonlinear problem (i.e. DMMGSetSNES() was used) this
654: returns the KSP (linear solver) that is associated with the SNES (nonlinear solver)
656: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ(), KSPGetSNES()
658: M*/
659: #define DMMGGetKSP(ctx) (ctx)[(ctx)[0]->nlevels-1]->ksp
661: /*MC
662: DMMGGetSNES - Gets the SNES object (nonlinear solver) for the finest level
664: Synopsis:
665: SNES DMMGGetSNES(DMMG *dmmg)
667: Not Collective
669: Input Parameter:
670: . dmmg - DMMG solve context
672: Level: intermediate
674: Notes: If this is a linear problem (i.e. DMMGSetKSP() was used) then this returns PETSC_NULL
676: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ(), KSPGetKSP()
678: M*/
679: #define DMMGGetSNES(ctx) (ctx)[(ctx)[0]->nlevels-1]->snes
681: /*MC
682: DMMGGetDA - Gets the DA object on the finest level
684: Synopsis:
685: DA DMMGGetDA(DMMG *dmmg)
687: Not Collective
689: Input Parameter:
690: . dmmg - DMMG solve context
692: Level: intermediate
694: Notes: Use only if the DMMG was created with a DA, not a VecPack
696: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ(), KSPGetKSP(), DMMGGetVecPack()
698: M*/
699: #define DMMGGetDA(ctx) (DA)((ctx)[(ctx)[0]->nlevels-1]->dm)
701: /*MC
702: DMMGGetVecPack - Gets the VecPack object on the finest level
704: Synopsis:
705: VecPack DMMGGetVecPack(DMMG *dmmg)
707: Not Collective
709: Input Parameter:
710: . dmmg - DMMG solve context
712: Level: intermediate
714: Notes: Use only if the DMMG was created with a DA, not a VecPack
716: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetJ(), KSPGetKSP(), DMMGGetDA()
718: M*/
719: #define DMMGGetVecPack(ctx) (VecPack)((ctx)[(ctx)[0]->nlevels-1]->dm)
721: /*MC
722: DMMGGetUser - Returns the user context for a particular level
724: Synopsis:
725: void* DMMGGetUser(DMMG *dmmg,PetscInt level)
727: Not Collective
729: Input Parameters:
730: + dmmg - DMMG solve context
731: - level - the number of the level you want the context for
733: Level: intermediate
735: .seealso: DMMGCreate(), DMMGSetUser()
737: M*/
738: #define DMMGGetUser(ctx,level) ((ctx)[level]->user)
740: /*MC
741: DMMGSetUser - Sets the user context for a particular level
743: Synopsis:
744: PetscErrorCode DMMGSetUser(DMMG *dmmg,PetscInt level,void *ctx)
746: Not Collective
748: Input Parameters:
749: + dmmg - DMMG solve context
750: . level - the number of the level you want the context for
751: - ctx - the context
753: Level: intermediate
755: Note: if the context is the same for each level just pass it in with
756: DMMGCreate() and don't call this macro
758: .seealso: DMMGCreate(), DMMGGetUser()
760: M*/
761: #define DMMGSetUser(ctx,level,usr) ((ctx)[level]->user = usr,0)
763: /*MC
764: DMMGGetLevels - Gets the number of levels in a DMMG object
766: Synopsis:
767: PetscInt DMMGGetLevels(DMMG *dmmg)
769: Not Collective
771: Input Parameter:
772: . dmmg - DMMG solve context
774: Level: intermediate
776: .seealso: DMMGCreate(), DMMGGetUser()
778: M*/
779: #define DMMGGetLevels(ctx) (ctx)[0]->nlevels
781: /*MC
782: DMMGGetDMMG - Returns the DMMG struct for the finest level
784: Synopsis:
785: DMMG DMMGGetDMMG(DMMG *dmmg)
787: Not Collective
789: Input Parameter:
790: . dmmg - DMMG solve context
792: Level: intermediate
794: .seealso: DMMGCreate(), DMMGSetUser(), DMMGGetB()
796: M*/
797: #define DMMGGetDMMG(ctx) (ctx)[(ctx)[0]->nlevels-1]
800: #endif