Actual source code: dm.c
1: #include <petscvec.h>
2: #include <petsc/private/dmimpl.h>
3: #include <petsc/private/dmlabelimpl.h>
4: #include <petsc/private/petscdsimpl.h>
5: #include <petscdmplex.h>
6: #include <petscdmfield.h>
7: #include <petscsf.h>
8: #include <petscds.h>
10: #if defined(PETSC_HAVE_VALGRIND)
11: # include <valgrind/memcheck.h>
12: #endif
14: PetscClassId DM_CLASSID;
15: PetscClassId DMLABEL_CLASSID;
16: PetscLogEvent DM_Convert, DM_GlobalToLocal, DM_LocalToGlobal, DM_LocalToLocal, DM_LocatePoints, DM_Coarsen, DM_Refine, DM_CreateInterpolation, DM_CreateRestriction, DM_CreateInjection, DM_CreateMatrix, DM_Load, DM_AdaptInterpolator;
18: const char *const DMBoundaryTypes[] = {"NONE","GHOSTED","MIRROR","PERIODIC","TWIST","DMBoundaryType","DM_BOUNDARY_", NULL};
19: const char *const DMBoundaryConditionTypes[] = {"INVALID","ESSENTIAL","NATURAL","INVALID","INVALID","ESSENTIAL_FIELD","NATURAL_FIELD","INVALID","INVALID","ESSENTIAL_BD_FIELD","NATURAL_RIEMANN","DMBoundaryConditionType","DM_BC_", NULL};
20: const char *const DMPolytopeTypes[] = {"vertex", "segment", "tensor_segment", "triangle", "quadrilateral", "tensor_quad", "tetrahedron", "hexahedron", "triangular_prism", "tensor_triangular_prism", "tensor_quadrilateral_prism", "pyramid", "FV_ghost_cell", "interior_ghost_cell", "unknown", "invalid", "DMPolytopeType", "DM_POLYTOPE_", NULL};
22: /*@
23: DMCreate - Creates an empty DM object. The type can then be set with DMSetType().
25: If you never call DMSetType() it will generate an
26: error when you try to use the vector.
28: Collective
30: Input Parameter:
31: . comm - The communicator for the DM object
33: Output Parameter:
34: . dm - The DM object
36: Level: beginner
38: .seealso: DMSetType(), DMDA, DMSLICED, DMCOMPOSITE, DMPLEX, DMMOAB, DMNETWORK
39: @*/
40: PetscErrorCode DMCreate(MPI_Comm comm,DM *dm)
41: {
42: DM v;
43: PetscDS ds;
48: *dm = NULL;
49: DMInitializePackage();
51: PetscHeaderCreate(v, DM_CLASSID, "DM", "Distribution Manager", "DM", comm, DMDestroy, DMView);
53: v->setupcalled = PETSC_FALSE;
54: v->setfromoptionscalled = PETSC_FALSE;
55: v->ltogmap = NULL;
56: v->bs = 1;
57: v->coloringtype = IS_COLORING_GLOBAL;
58: PetscSFCreate(comm, &v->sf);
59: PetscSFCreate(comm, &v->sectionSF);
60: v->labels = NULL;
61: v->adjacency[0] = PETSC_FALSE;
62: v->adjacency[1] = PETSC_TRUE;
63: v->depthLabel = NULL;
64: v->celltypeLabel = NULL;
65: v->localSection = NULL;
66: v->globalSection = NULL;
67: v->defaultConstraintSection = NULL;
68: v->defaultConstraintMat = NULL;
69: v->L = NULL;
70: v->maxCell = NULL;
71: v->bdtype = NULL;
72: v->dimEmbed = PETSC_DEFAULT;
73: v->dim = PETSC_DETERMINE;
74: {
75: PetscInt i;
76: for (i = 0; i < 10; ++i) {
77: v->nullspaceConstructors[i] = NULL;
78: v->nearnullspaceConstructors[i] = NULL;
79: }
80: }
81: PetscDSCreate(PetscObjectComm((PetscObject) v), &ds);
82: DMSetRegionDS(v, NULL, NULL, ds);
83: PetscDSDestroy(&ds);
84: v->dmBC = NULL;
85: v->coarseMesh = NULL;
86: v->outputSequenceNum = -1;
87: v->outputSequenceVal = 0.0;
88: DMSetVecType(v,VECSTANDARD);
89: DMSetMatType(v,MATAIJ);
91: *dm = v;
92: return(0);
93: }
95: /*@
96: DMClone - Creates a DM object with the same topology as the original.
98: Collective
100: Input Parameter:
101: . dm - The original DM object
103: Output Parameter:
104: . newdm - The new DM object
106: Level: beginner
108: Notes:
109: For some DM implementations this is a shallow clone, the result of which may share (referent counted) information with its parent. For example,
110: DMClone() applied to a DMPLEX object will result in a new DMPLEX that shares the topology with the original DMPLEX. It does not
111: share the PetscSection of the original DM.
113: The clone is considered set up iff the original is.
115: .seealso: DMDestroy(), DMCreate(), DMSetType(), DMSetLocalSection(), DMSetGlobalSection()
117: @*/
118: PetscErrorCode DMClone(DM dm, DM *newdm)
119: {
120: PetscSF sf;
121: Vec coords;
122: void *ctx;
123: PetscInt dim, cdim;
129: DMCreate(PetscObjectComm((PetscObject) dm), newdm);
130: DMCopyLabels(dm, *newdm, PETSC_COPY_VALUES, PETSC_TRUE);
131: (*newdm)->leveldown = dm->leveldown;
132: (*newdm)->levelup = dm->levelup;
133: (*newdm)->prealloc_only = dm->prealloc_only;
134: PetscFree((*newdm)->vectype);
135: PetscStrallocpy(dm->vectype,(char**)&(*newdm)->vectype);
136: PetscFree((*newdm)->mattype);
137: PetscStrallocpy(dm->mattype,(char**)&(*newdm)->mattype);
138: DMGetDimension(dm, &dim);
139: DMSetDimension(*newdm, dim);
140: if (dm->ops->clone) {
141: (*dm->ops->clone)(dm, newdm);
142: }
143: (*newdm)->setupcalled = dm->setupcalled;
144: DMGetPointSF(dm, &sf);
145: DMSetPointSF(*newdm, sf);
146: DMGetApplicationContext(dm, &ctx);
147: DMSetApplicationContext(*newdm, ctx);
148: if (dm->coordinateDM) {
149: DM ncdm;
150: PetscSection cs;
151: PetscInt pEnd = -1, pEndMax = -1;
153: DMGetLocalSection(dm->coordinateDM, &cs);
154: if (cs) {PetscSectionGetChart(cs, NULL, &pEnd);}
155: MPI_Allreduce(&pEnd,&pEndMax,1,MPIU_INT,MPI_MAX,PetscObjectComm((PetscObject)dm));
156: if (pEndMax >= 0) {
157: DMClone(dm->coordinateDM, &ncdm);
158: DMCopyDisc(dm->coordinateDM, ncdm);
159: DMSetLocalSection(ncdm, cs);
160: DMSetCoordinateDM(*newdm, ncdm);
161: DMDestroy(&ncdm);
162: }
163: }
164: DMGetCoordinateDim(dm, &cdim);
165: DMSetCoordinateDim(*newdm, cdim);
166: DMGetCoordinatesLocal(dm, &coords);
167: if (coords) {
168: DMSetCoordinatesLocal(*newdm, coords);
169: } else {
170: DMGetCoordinates(dm, &coords);
171: if (coords) {DMSetCoordinates(*newdm, coords);}
172: }
173: {
174: PetscBool isper;
175: const PetscReal *maxCell, *L;
176: const DMBoundaryType *bd;
177: DMGetPeriodicity(dm, &isper, &maxCell, &L, &bd);
178: DMSetPeriodicity(*newdm, isper, maxCell, L, bd);
179: }
180: {
181: PetscBool useCone, useClosure;
183: DMGetAdjacency(dm, PETSC_DEFAULT, &useCone, &useClosure);
184: DMSetAdjacency(*newdm, PETSC_DEFAULT, useCone, useClosure);
185: }
186: return(0);
187: }
189: /*@C
190: DMSetVecType - Sets the type of vector created with DMCreateLocalVector() and DMCreateGlobalVector()
192: Logically Collective on da
194: Input Parameter:
195: + da - initial distributed array
196: . ctype - the vector type, currently either VECSTANDARD, VECCUDA, or VECVIENNACL
198: Options Database:
199: . -dm_vec_type ctype
201: Level: intermediate
203: .seealso: DMCreate(), DMDestroy(), DM, DMDAInterpolationType, VecType, DMGetVecType(), DMSetMatType(), DMGetMatType()
204: @*/
205: PetscErrorCode DMSetVecType(DM da,VecType ctype)
206: {
211: PetscFree(da->vectype);
212: PetscStrallocpy(ctype,(char**)&da->vectype);
213: return(0);
214: }
216: /*@C
217: DMGetVecType - Gets the type of vector created with DMCreateLocalVector() and DMCreateGlobalVector()
219: Logically Collective on da
221: Input Parameter:
222: . da - initial distributed array
224: Output Parameter:
225: . ctype - the vector type
227: Level: intermediate
229: .seealso: DMCreate(), DMDestroy(), DM, DMDAInterpolationType, VecType, DMSetMatType(), DMGetMatType(), DMSetVecType()
230: @*/
231: PetscErrorCode DMGetVecType(DM da,VecType *ctype)
232: {
235: *ctype = da->vectype;
236: return(0);
237: }
239: /*@
240: VecGetDM - Gets the DM defining the data layout of the vector
242: Not collective
244: Input Parameter:
245: . v - The Vec
247: Output Parameter:
248: . dm - The DM
250: Level: intermediate
252: .seealso: VecSetDM(), DMGetLocalVector(), DMGetGlobalVector(), DMSetVecType()
253: @*/
254: PetscErrorCode VecGetDM(Vec v, DM *dm)
255: {
261: PetscObjectQuery((PetscObject) v, "__PETSc_dm", (PetscObject*) dm);
262: return(0);
263: }
265: /*@
266: VecSetDM - Sets the DM defining the data layout of the vector.
268: Not collective
270: Input Parameters:
271: + v - The Vec
272: - dm - The DM
274: Note: This is NOT the same as DMCreateGlobalVector() since it does not change the view methods or perform other customization, but merely sets the DM member.
276: Level: intermediate
278: .seealso: VecGetDM(), DMGetLocalVector(), DMGetGlobalVector(), DMSetVecType()
279: @*/
280: PetscErrorCode VecSetDM(Vec v, DM dm)
281: {
287: PetscObjectCompose((PetscObject) v, "__PETSc_dm", (PetscObject) dm);
288: return(0);
289: }
291: /*@C
292: DMSetISColoringType - Sets the type of coloring, global or local, that is created by the DM
294: Logically Collective on dm
296: Input Parameters:
297: + dm - the DM context
298: - ctype - the matrix type
300: Options Database:
301: . -dm_is_coloring_type - global or local
303: Level: intermediate
305: .seealso: DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMCreateMatrix(), DMSetMatrixPreallocateOnly(), MatType, DMGetMatType(),
306: DMGetISColoringType()
307: @*/
308: PetscErrorCode DMSetISColoringType(DM dm,ISColoringType ctype)
309: {
312: dm->coloringtype = ctype;
313: return(0);
314: }
316: /*@C
317: DMGetISColoringType - Gets the type of coloring, global or local, that is created by the DM
319: Logically Collective on dm
321: Input Parameter:
322: . dm - the DM context
324: Output Parameter:
325: . ctype - the matrix type
327: Options Database:
328: . -dm_is_coloring_type - global or local
330: Level: intermediate
332: .seealso: DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMCreateMatrix(), DMSetMatrixPreallocateOnly(), MatType, DMGetMatType(),
333: DMGetISColoringType()
334: @*/
335: PetscErrorCode DMGetISColoringType(DM dm,ISColoringType *ctype)
336: {
339: *ctype = dm->coloringtype;
340: return(0);
341: }
343: /*@C
344: DMSetMatType - Sets the type of matrix created with DMCreateMatrix()
346: Logically Collective on dm
348: Input Parameters:
349: + dm - the DM context
350: - ctype - the matrix type
352: Options Database:
353: . -dm_mat_type ctype
355: Level: intermediate
357: .seealso: DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMCreateMatrix(), DMSetMatrixPreallocateOnly(), MatType, DMGetMatType(), DMSetMatType(), DMGetMatType()
358: @*/
359: PetscErrorCode DMSetMatType(DM dm,MatType ctype)
360: {
365: PetscFree(dm->mattype);
366: PetscStrallocpy(ctype,(char**)&dm->mattype);
367: return(0);
368: }
370: /*@C
371: DMGetMatType - Gets the type of matrix created with DMCreateMatrix()
373: Logically Collective on dm
375: Input Parameter:
376: . dm - the DM context
378: Output Parameter:
379: . ctype - the matrix type
381: Options Database:
382: . -dm_mat_type ctype
384: Level: intermediate
386: .seealso: DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMCreateMatrix(), DMSetMatrixPreallocateOnly(), MatType, DMSetMatType(), DMSetMatType(), DMGetMatType()
387: @*/
388: PetscErrorCode DMGetMatType(DM dm,MatType *ctype)
389: {
392: *ctype = dm->mattype;
393: return(0);
394: }
396: /*@
397: MatGetDM - Gets the DM defining the data layout of the matrix
399: Not collective
401: Input Parameter:
402: . A - The Mat
404: Output Parameter:
405: . dm - The DM
407: Level: intermediate
409: Developer Note: Since the Mat class doesn't know about the DM class the DM object is associated with
410: the Mat through a PetscObjectCompose() operation
412: .seealso: MatSetDM(), DMCreateMatrix(), DMSetMatType()
413: @*/
414: PetscErrorCode MatGetDM(Mat A, DM *dm)
415: {
421: PetscObjectQuery((PetscObject) A, "__PETSc_dm", (PetscObject*) dm);
422: return(0);
423: }
425: /*@
426: MatSetDM - Sets the DM defining the data layout of the matrix
428: Not collective
430: Input Parameters:
431: + A - The Mat
432: - dm - The DM
434: Level: intermediate
436: Developer Note: Since the Mat class doesn't know about the DM class the DM object is associated with
437: the Mat through a PetscObjectCompose() operation
440: .seealso: MatGetDM(), DMCreateMatrix(), DMSetMatType()
441: @*/
442: PetscErrorCode MatSetDM(Mat A, DM dm)
443: {
449: PetscObjectCompose((PetscObject) A, "__PETSc_dm", (PetscObject) dm);
450: return(0);
451: }
453: /*@C
454: DMSetOptionsPrefix - Sets the prefix used for searching for all
455: DM options in the database.
457: Logically Collective on dm
459: Input Parameter:
460: + da - the DM context
461: - prefix - the prefix to prepend to all option names
463: Notes:
464: A hyphen (-) must NOT be given at the beginning of the prefix name.
465: The first character of all runtime options is AUTOMATICALLY the hyphen.
467: Level: advanced
469: .seealso: DMSetFromOptions()
470: @*/
471: PetscErrorCode DMSetOptionsPrefix(DM dm,const char prefix[])
472: {
477: PetscObjectSetOptionsPrefix((PetscObject)dm,prefix);
478: if (dm->sf) {
479: PetscObjectSetOptionsPrefix((PetscObject)dm->sf,prefix);
480: }
481: if (dm->sectionSF) {
482: PetscObjectSetOptionsPrefix((PetscObject)dm->sectionSF,prefix);
483: }
484: return(0);
485: }
487: /*@C
488: DMAppendOptionsPrefix - Appends to the prefix used for searching for all
489: DM options in the database.
491: Logically Collective on dm
493: Input Parameters:
494: + dm - the DM context
495: - prefix - the prefix string to prepend to all DM option requests
497: Notes:
498: A hyphen (-) must NOT be given at the beginning of the prefix name.
499: The first character of all runtime options is AUTOMATICALLY the hyphen.
501: Level: advanced
503: .seealso: DMSetOptionsPrefix(), DMGetOptionsPrefix()
504: @*/
505: PetscErrorCode DMAppendOptionsPrefix(DM dm,const char prefix[])
506: {
511: PetscObjectAppendOptionsPrefix((PetscObject)dm,prefix);
512: return(0);
513: }
515: /*@C
516: DMGetOptionsPrefix - Gets the prefix used for searching for all
517: DM options in the database.
519: Not Collective
521: Input Parameters:
522: . dm - the DM context
524: Output Parameters:
525: . prefix - pointer to the prefix string used is returned
527: Notes:
528: On the fortran side, the user should pass in a string 'prefix' of
529: sufficient length to hold the prefix.
531: Level: advanced
533: .seealso: DMSetOptionsPrefix(), DMAppendOptionsPrefix()
534: @*/
535: PetscErrorCode DMGetOptionsPrefix(DM dm,const char *prefix[])
536: {
541: PetscObjectGetOptionsPrefix((PetscObject)dm,prefix);
542: return(0);
543: }
545: static PetscErrorCode DMCountNonCyclicReferences(DM dm, PetscBool recurseCoarse, PetscBool recurseFine, PetscInt *ncrefct)
546: {
547: PetscInt refct = ((PetscObject) dm)->refct;
551: *ncrefct = 0;
552: if (dm->coarseMesh && dm->coarseMesh->fineMesh == dm) {
553: refct--;
554: if (recurseCoarse) {
555: PetscInt coarseCount;
557: DMCountNonCyclicReferences(dm->coarseMesh, PETSC_TRUE, PETSC_FALSE,&coarseCount);
558: refct += coarseCount;
559: }
560: }
561: if (dm->fineMesh && dm->fineMesh->coarseMesh == dm) {
562: refct--;
563: if (recurseFine) {
564: PetscInt fineCount;
566: DMCountNonCyclicReferences(dm->fineMesh, PETSC_FALSE, PETSC_TRUE,&fineCount);
567: refct += fineCount;
568: }
569: }
570: *ncrefct = refct;
571: return(0);
572: }
574: PetscErrorCode DMDestroyLabelLinkList_Internal(DM dm)
575: {
576: DMLabelLink next = dm->labels;
580: /* destroy the labels */
581: while (next) {
582: DMLabelLink tmp = next->next;
584: if (next->label == dm->depthLabel) dm->depthLabel = NULL;
585: if (next->label == dm->celltypeLabel) dm->celltypeLabel = NULL;
586: DMLabelDestroy(&next->label);
587: PetscFree(next);
588: next = tmp;
589: }
590: dm->labels = NULL;
591: return(0);
592: }
594: /*@C
595: DMDestroy - Destroys a vector packer or DM.
597: Collective on dm
599: Input Parameter:
600: . dm - the DM object to destroy
602: Level: developer
604: .seealso DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix()
606: @*/
607: PetscErrorCode DMDestroy(DM *dm)
608: {
609: PetscInt cnt;
610: DMNamedVecLink nlink,nnext;
614: if (!*dm) return(0);
617: /* count all non-cyclic references in the doubly-linked list of coarse<->fine meshes */
618: DMCountNonCyclicReferences(*dm,PETSC_TRUE,PETSC_TRUE,&cnt);
619: --((PetscObject)(*dm))->refct;
620: if (--cnt > 0) {*dm = NULL; return(0);}
621: if (((PetscObject)(*dm))->refct < 0) return(0);
622: ((PetscObject)(*dm))->refct = 0;
624: DMClearGlobalVectors(*dm);
625: DMClearLocalVectors(*dm);
627: nnext=(*dm)->namedglobal;
628: (*dm)->namedglobal = NULL;
629: for (nlink=nnext; nlink; nlink=nnext) { /* Destroy the named vectors */
630: nnext = nlink->next;
631: if (nlink->status != DMVEC_STATUS_IN) SETERRQ1(((PetscObject)*dm)->comm,PETSC_ERR_ARG_WRONGSTATE,"DM still has Vec named '%s' checked out",nlink->name);
632: PetscFree(nlink->name);
633: VecDestroy(&nlink->X);
634: PetscFree(nlink);
635: }
636: nnext=(*dm)->namedlocal;
637: (*dm)->namedlocal = NULL;
638: for (nlink=nnext; nlink; nlink=nnext) { /* Destroy the named local vectors */
639: nnext = nlink->next;
640: if (nlink->status != DMVEC_STATUS_IN) SETERRQ1(((PetscObject)*dm)->comm,PETSC_ERR_ARG_WRONGSTATE,"DM still has Vec named '%s' checked out",nlink->name);
641: PetscFree(nlink->name);
642: VecDestroy(&nlink->X);
643: PetscFree(nlink);
644: }
646: /* Destroy the list of hooks */
647: {
648: DMCoarsenHookLink link,next;
649: for (link=(*dm)->coarsenhook; link; link=next) {
650: next = link->next;
651: PetscFree(link);
652: }
653: (*dm)->coarsenhook = NULL;
654: }
655: {
656: DMRefineHookLink link,next;
657: for (link=(*dm)->refinehook; link; link=next) {
658: next = link->next;
659: PetscFree(link);
660: }
661: (*dm)->refinehook = NULL;
662: }
663: {
664: DMSubDomainHookLink link,next;
665: for (link=(*dm)->subdomainhook; link; link=next) {
666: next = link->next;
667: PetscFree(link);
668: }
669: (*dm)->subdomainhook = NULL;
670: }
671: {
672: DMGlobalToLocalHookLink link,next;
673: for (link=(*dm)->gtolhook; link; link=next) {
674: next = link->next;
675: PetscFree(link);
676: }
677: (*dm)->gtolhook = NULL;
678: }
679: {
680: DMLocalToGlobalHookLink link,next;
681: for (link=(*dm)->ltoghook; link; link=next) {
682: next = link->next;
683: PetscFree(link);
684: }
685: (*dm)->ltoghook = NULL;
686: }
687: /* Destroy the work arrays */
688: {
689: DMWorkLink link,next;
690: if ((*dm)->workout) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Work array still checked out");
691: for (link=(*dm)->workin; link; link=next) {
692: next = link->next;
693: PetscFree(link->mem);
694: PetscFree(link);
695: }
696: (*dm)->workin = NULL;
697: }
698: /* destroy the labels */
699: DMDestroyLabelLinkList_Internal(*dm);
700: /* destroy the fields */
701: DMClearFields(*dm);
702: /* destroy the boundaries */
703: {
704: DMBoundary next = (*dm)->boundary;
705: while (next) {
706: DMBoundary b = next;
708: next = b->next;
709: PetscFree(b);
710: }
711: }
713: PetscObjectDestroy(&(*dm)->dmksp);
714: PetscObjectDestroy(&(*dm)->dmsnes);
715: PetscObjectDestroy(&(*dm)->dmts);
717: if ((*dm)->ctx && (*dm)->ctxdestroy) {
718: (*(*dm)->ctxdestroy)(&(*dm)->ctx);
719: }
720: MatFDColoringDestroy(&(*dm)->fd);
721: ISLocalToGlobalMappingDestroy(&(*dm)->ltogmap);
722: PetscFree((*dm)->vectype);
723: PetscFree((*dm)->mattype);
725: PetscSectionDestroy(&(*dm)->localSection);
726: PetscSectionDestroy(&(*dm)->globalSection);
727: PetscLayoutDestroy(&(*dm)->map);
728: PetscSectionDestroy(&(*dm)->defaultConstraintSection);
729: MatDestroy(&(*dm)->defaultConstraintMat);
730: PetscSFDestroy(&(*dm)->sf);
731: PetscSFDestroy(&(*dm)->sectionSF);
732: if ((*dm)->useNatural) {
733: if ((*dm)->sfNatural) {
734: PetscSFDestroy(&(*dm)->sfNatural);
735: }
736: PetscObjectDereference((PetscObject) (*dm)->sfMigration);
737: }
738: if ((*dm)->coarseMesh && (*dm)->coarseMesh->fineMesh == *dm) {
739: DMSetFineDM((*dm)->coarseMesh,NULL);
740: }
742: DMDestroy(&(*dm)->coarseMesh);
743: if ((*dm)->fineMesh && (*dm)->fineMesh->coarseMesh == *dm) {
744: DMSetCoarseDM((*dm)->fineMesh,NULL);
745: }
746: DMDestroy(&(*dm)->fineMesh);
747: DMFieldDestroy(&(*dm)->coordinateField);
748: DMDestroy(&(*dm)->coordinateDM);
749: VecDestroy(&(*dm)->coordinates);
750: VecDestroy(&(*dm)->coordinatesLocal);
751: PetscFree((*dm)->L);
752: PetscFree((*dm)->maxCell);
753: PetscFree((*dm)->bdtype);
754: if ((*dm)->transformDestroy) {(*(*dm)->transformDestroy)(*dm, (*dm)->transformCtx);}
755: DMDestroy(&(*dm)->transformDM);
756: VecDestroy(&(*dm)->transform);
758: DMClearDS(*dm);
759: DMDestroy(&(*dm)->dmBC);
760: /* if memory was published with SAWs then destroy it */
761: PetscObjectSAWsViewOff((PetscObject)*dm);
763: if ((*dm)->ops->destroy) {
764: (*(*dm)->ops->destroy)(*dm);
765: }
766: DMMonitorCancel(*dm);
767: /* We do not destroy (*dm)->data here so that we can reference count backend objects */
768: PetscHeaderDestroy(dm);
769: return(0);
770: }
772: /*@
773: DMSetUp - sets up the data structures inside a DM object
775: Collective on dm
777: Input Parameter:
778: . dm - the DM object to setup
780: Level: developer
782: .seealso DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix()
784: @*/
785: PetscErrorCode DMSetUp(DM dm)
786: {
791: if (dm->setupcalled) return(0);
792: if (dm->ops->setup) {
793: (*dm->ops->setup)(dm);
794: }
795: dm->setupcalled = PETSC_TRUE;
796: return(0);
797: }
799: /*@
800: DMSetFromOptions - sets parameters in a DM from the options database
802: Collective on dm
804: Input Parameter:
805: . dm - the DM object to set options for
807: Options Database:
808: + -dm_preallocate_only - Only preallocate the matrix for DMCreateMatrix(), but do not fill it with zeros
809: . -dm_vec_type <type> - type of vector to create inside DM
810: . -dm_mat_type <type> - type of matrix to create inside DM
811: - -dm_is_coloring_type - <global or local>
813: DMPLEX Specific Checks
814: + -dm_plex_check_symmetry - Check that the adjacency information in the mesh is symmetric - DMPlexCheckSymmetry()
815: . -dm_plex_check_skeleton - Check that each cell has the correct number of vertices (only for homogeneous simplex or tensor meshes) - DMPlexCheckSkeleton()
816: . -dm_plex_check_faces - Check that the faces of each cell give a vertex order this is consistent with what we expect from the cell type - DMPlexCheckFaces()
817: . -dm_plex_check_geometry - Check that cells have positive volume - DMPlexCheckGeometry()
818: . -dm_plex_check_pointsf - Check some necessary conditions for PointSF - DMPlexCheckPointSF()
819: . -dm_plex_check_interface_cones - Check points on inter-partition interfaces have conforming order of cone points - DMPlexCheckInterfaceCones()
820: - -dm_plex_check_all - Perform all the checks above
822: Level: intermediate
824: .seealso DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(),
825: DMPlexCheckSymmetry(), DMPlexCheckSkeleton(), DMPlexCheckFaces(), DMPlexCheckGeometry(), DMPlexCheckPointSF(), DMPlexCheckInterfaceCones()
827: @*/
828: PetscErrorCode DMSetFromOptions(DM dm)
829: {
830: char typeName[256];
831: PetscBool flg;
836: dm->setfromoptionscalled = PETSC_TRUE;
837: if (dm->sf) {PetscSFSetFromOptions(dm->sf);}
838: if (dm->sectionSF) {PetscSFSetFromOptions(dm->sectionSF);}
839: PetscObjectOptionsBegin((PetscObject)dm);
840: PetscOptionsBool("-dm_preallocate_only","only preallocate matrix, but do not set column indices","DMSetMatrixPreallocateOnly",dm->prealloc_only,&dm->prealloc_only,NULL);
841: PetscOptionsFList("-dm_vec_type","Vector type used for created vectors","DMSetVecType",VecList,dm->vectype,typeName,256,&flg);
842: if (flg) {
843: DMSetVecType(dm,typeName);
844: }
845: PetscOptionsFList("-dm_mat_type","Matrix type used for created matrices","DMSetMatType",MatList,dm->mattype ? dm->mattype : typeName,typeName,sizeof(typeName),&flg);
846: if (flg) {
847: DMSetMatType(dm,typeName);
848: }
849: PetscOptionsEnum("-dm_is_coloring_type","Global or local coloring of Jacobian","DMSetISColoringType",ISColoringTypes,(PetscEnum)dm->coloringtype,(PetscEnum*)&dm->coloringtype,NULL);
850: if (dm->ops->setfromoptions) {
851: (*dm->ops->setfromoptions)(PetscOptionsObject,dm);
852: }
853: /* process any options handlers added with PetscObjectAddOptionsHandler() */
854: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject) dm);
855: PetscOptionsEnd();
856: return(0);
857: }
859: /*@C
860: DMViewFromOptions - View from Options
862: Collective on DM
864: Input Parameters:
865: + dm - the DM object
866: . obj - Optional object
867: - name - command line option
869: Level: intermediate
870: .seealso: DM, DMView, PetscObjectViewFromOptions(), DMCreate()
871: @*/
872: PetscErrorCode DMViewFromOptions(DM dm,PetscObject obj,const char name[])
873: {
878: PetscObjectViewFromOptions((PetscObject)dm,obj,name);
879: return(0);
880: }
882: /*@C
883: DMView - Views a DM
885: Collective on dm
887: Input Parameter:
888: + dm - the DM object to view
889: - v - the viewer
891: Level: beginner
893: .seealso DMDestroy(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix()
895: @*/
896: PetscErrorCode DMView(DM dm,PetscViewer v)
897: {
898: PetscErrorCode ierr;
899: PetscBool isbinary;
900: PetscMPIInt size;
901: PetscViewerFormat format;
905: if (!v) {
906: PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)dm),&v);
907: }
909: /* Ideally, we would like to have this test on.
910: However, it currently breaks socket viz via GLVis.
911: During DMView(parallel_mesh,glvis_viewer), each
912: process opens a sequential ASCII socket to visualize
913: the local mesh, and PetscObjectView(dm,local_socket)
914: is internally called inside VecView_GLVis, incurring
915: in an error here */
917: PetscViewerCheckWritable(v);
919: PetscViewerGetFormat(v,&format);
920: MPI_Comm_size(PetscObjectComm((PetscObject)dm),&size);
921: if (size == 1 && format == PETSC_VIEWER_LOAD_BALANCE) return(0);
922: PetscObjectPrintClassNamePrefixType((PetscObject)dm,v);
923: PetscObjectTypeCompare((PetscObject)v,PETSCVIEWERBINARY,&isbinary);
924: if (isbinary) {
925: PetscInt classid = DM_FILE_CLASSID;
926: char type[256];
928: PetscViewerBinaryWrite(v,&classid,1,PETSC_INT);
929: PetscStrncpy(type,((PetscObject)dm)->type_name,256);
930: PetscViewerBinaryWrite(v,type,256,PETSC_CHAR);
931: }
932: if (dm->ops->view) {
933: (*dm->ops->view)(dm,v);
934: }
935: return(0);
936: }
938: /*@
939: DMCreateGlobalVector - Creates a global vector from a DM object
941: Collective on dm
943: Input Parameter:
944: . dm - the DM object
946: Output Parameter:
947: . vec - the global vector
949: Level: beginner
951: .seealso DMCreateLocalVector(), DMGetGlobalVector(), DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix()
953: @*/
954: PetscErrorCode DMCreateGlobalVector(DM dm,Vec *vec)
955: {
961: if (!dm->ops->createglobalvector) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMCreateGlobalVector",((PetscObject)dm)->type_name);
962: (*dm->ops->createglobalvector)(dm,vec);
963: if (PetscDefined(USE_DEBUG)) {
964: DM vdm;
966: VecGetDM(*vec,&vdm);
967: if (!vdm) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"DM type '%s' did not attach the DM to the vector\n",((PetscObject)dm)->type_name);
968: }
969: return(0);
970: }
972: /*@
973: DMCreateLocalVector - Creates a local vector from a DM object
975: Not Collective
977: Input Parameter:
978: . dm - the DM object
980: Output Parameter:
981: . vec - the local vector
983: Level: beginner
985: .seealso DMCreateGlobalVector(), DMGetLocalVector(), DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix()
987: @*/
988: PetscErrorCode DMCreateLocalVector(DM dm,Vec *vec)
989: {
995: if (!dm->ops->createlocalvector) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMCreateLocalVector",((PetscObject)dm)->type_name);
996: (*dm->ops->createlocalvector)(dm,vec);
997: if (PetscDefined(USE_DEBUG)) {
998: DM vdm;
1000: VecGetDM(*vec,&vdm);
1001: if (!vdm) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_LIB,"DM type '%s' did not attach the DM to the vector\n",((PetscObject)dm)->type_name);
1002: }
1003: return(0);
1004: }
1006: /*@
1007: DMGetLocalToGlobalMapping - Accesses the local-to-global mapping in a DM.
1009: Collective on dm
1011: Input Parameter:
1012: . dm - the DM that provides the mapping
1014: Output Parameter:
1015: . ltog - the mapping
1017: Level: intermediate
1019: Notes:
1020: This mapping can then be used by VecSetLocalToGlobalMapping() or
1021: MatSetLocalToGlobalMapping().
1023: .seealso: DMCreateLocalVector()
1024: @*/
1025: PetscErrorCode DMGetLocalToGlobalMapping(DM dm,ISLocalToGlobalMapping *ltog)
1026: {
1027: PetscInt bs = -1, bsLocal[2], bsMinMax[2];
1033: if (!dm->ltogmap) {
1034: PetscSection section, sectionGlobal;
1036: DMGetLocalSection(dm, §ion);
1037: if (section) {
1038: const PetscInt *cdofs;
1039: PetscInt *ltog;
1040: PetscInt pStart, pEnd, n, p, k, l;
1042: DMGetGlobalSection(dm, §ionGlobal);
1043: PetscSectionGetChart(section, &pStart, &pEnd);
1044: PetscSectionGetStorageSize(section, &n);
1045: PetscMalloc1(n, <og); /* We want the local+overlap size */
1046: for (p = pStart, l = 0; p < pEnd; ++p) {
1047: PetscInt bdof, cdof, dof, off, c, cind = 0;
1049: /* Should probably use constrained dofs */
1050: PetscSectionGetDof(section, p, &dof);
1051: PetscSectionGetConstraintDof(section, p, &cdof);
1052: PetscSectionGetConstraintIndices(section, p, &cdofs);
1053: PetscSectionGetOffset(sectionGlobal, p, &off);
1054: /* If you have dofs, and constraints, and they are unequal, we set the blocksize to 1 */
1055: bdof = cdof && (dof-cdof) ? 1 : dof;
1056: if (dof) {
1057: if (bs < 0) {bs = bdof;}
1058: else if (bs != bdof) {bs = 1;}
1059: }
1060: for (c = 0; c < dof; ++c, ++l) {
1061: if ((cind < cdof) && (c == cdofs[cind])) ltog[l] = off < 0 ? off-c : off+c;
1062: else ltog[l] = (off < 0 ? -(off+1) : off) + c;
1063: }
1064: }
1065: /* Must have same blocksize on all procs (some might have no points) */
1066: bsLocal[0] = bs < 0 ? PETSC_MAX_INT : bs; bsLocal[1] = bs;
1067: PetscGlobalMinMaxInt(PetscObjectComm((PetscObject) dm), bsLocal, bsMinMax);
1068: if (bsMinMax[0] != bsMinMax[1]) {bs = 1;}
1069: else {bs = bsMinMax[0];}
1070: bs = bs < 0 ? 1 : bs;
1071: /* Must reduce indices by blocksize */
1072: if (bs > 1) {
1073: for (l = 0, k = 0; l < n; l += bs, ++k) ltog[k] = ltog[l]/bs;
1074: n /= bs;
1075: }
1076: ISLocalToGlobalMappingCreate(PetscObjectComm((PetscObject)dm), bs, n, ltog, PETSC_OWN_POINTER, &dm->ltogmap);
1077: PetscLogObjectParent((PetscObject)dm, (PetscObject)dm->ltogmap);
1078: } else {
1079: if (!dm->ops->getlocaltoglobalmapping) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMGetLocalToGlobalMapping",((PetscObject)dm)->type_name);
1080: (*dm->ops->getlocaltoglobalmapping)(dm);
1081: }
1082: }
1083: *ltog = dm->ltogmap;
1084: return(0);
1085: }
1087: /*@
1088: DMGetBlockSize - Gets the inherent block size associated with a DM
1090: Not Collective
1092: Input Parameter:
1093: . dm - the DM with block structure
1095: Output Parameter:
1096: . bs - the block size, 1 implies no exploitable block structure
1098: Level: intermediate
1100: .seealso: ISCreateBlock(), VecSetBlockSize(), MatSetBlockSize(), DMGetLocalToGlobalMapping()
1101: @*/
1102: PetscErrorCode DMGetBlockSize(DM dm,PetscInt *bs)
1103: {
1107: if (dm->bs < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"DM does not have enough information to provide a block size yet");
1108: *bs = dm->bs;
1109: return(0);
1110: }
1112: /*@C
1113: DMCreateInterpolation - Gets interpolation matrix between two DM objects
1115: Collective on dmc
1117: Input Parameter:
1118: + dmc - the DM object
1119: - dmf - the second, finer DM object
1121: Output Parameter:
1122: + mat - the interpolation
1123: - vec - the scaling (optional)
1125: Level: developer
1127: Notes:
1128: For DMDA objects this only works for "uniform refinement", that is the refined mesh was obtained DMRefine() or the coarse mesh was obtained by
1129: DMCoarsen(). The coordinates set into the DMDA are completely ignored in computing the interpolation.
1131: For DMDA objects you can use this interpolation (more precisely the interpolation from the DMGetCoordinateDM()) to interpolate the mesh coordinate vectors
1132: EXCEPT in the periodic case where it does not make sense since the coordinate vectors are not periodic.
1135: .seealso DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateColoring(), DMCreateMatrix(), DMRefine(), DMCoarsen(), DMCreateRestriction(), DMCreateInterpolationScale()
1137: @*/
1138: PetscErrorCode DMCreateInterpolation(DM dmc,DM dmf,Mat *mat,Vec *vec)
1139: {
1146: if (!dmc->ops->createinterpolation) SETERRQ1(PetscObjectComm((PetscObject)dmc),PETSC_ERR_SUP,"DM type %s does not implement DMCreateInterpolation",((PetscObject)dmc)->type_name);
1147: PetscLogEventBegin(DM_CreateInterpolation,dmc,dmf,0,0);
1148: (*dmc->ops->createinterpolation)(dmc,dmf,mat,vec);
1149: PetscLogEventEnd(DM_CreateInterpolation,dmc,dmf,0,0);
1150: return(0);
1151: }
1153: /*@
1154: DMCreateInterpolationScale - Forms L = 1/(R*1) such that diag(L)*R preserves scale and is thus suitable for state (versus residual) restriction.
1156: Input Parameters:
1157: + dac - DM that defines a coarse mesh
1158: . daf - DM that defines a fine mesh
1159: - mat - the restriction (or interpolation operator) from fine to coarse
1161: Output Parameter:
1162: . scale - the scaled vector
1164: Level: developer
1166: .seealso: DMCreateInterpolation()
1168: @*/
1169: PetscErrorCode DMCreateInterpolationScale(DM dac,DM daf,Mat mat,Vec *scale)
1170: {
1172: Vec fine;
1173: PetscScalar one = 1.0;
1176: DMCreateGlobalVector(daf,&fine);
1177: DMCreateGlobalVector(dac,scale);
1178: VecSet(fine,one);
1179: MatRestrict(mat,fine,*scale);
1180: VecDestroy(&fine);
1181: VecReciprocal(*scale);
1182: return(0);
1183: }
1185: /*@
1186: DMCreateRestriction - Gets restriction matrix between two DM objects
1188: Collective on dmc
1190: Input Parameter:
1191: + dmc - the DM object
1192: - dmf - the second, finer DM object
1194: Output Parameter:
1195: . mat - the restriction
1198: Level: developer
1200: Notes:
1201: For DMDA objects this only works for "uniform refinement", that is the refined mesh was obtained DMRefine() or the coarse mesh was obtained by
1202: DMCoarsen(). The coordinates set into the DMDA are completely ignored in computing the interpolation.
1205: .seealso DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateColoring(), DMCreateMatrix(), DMRefine(), DMCoarsen(), DMCreateInterpolation()
1207: @*/
1208: PetscErrorCode DMCreateRestriction(DM dmc,DM dmf,Mat *mat)
1209: {
1216: if (!dmc->ops->createrestriction) SETERRQ1(PetscObjectComm((PetscObject)dmc),PETSC_ERR_SUP,"DM type %s does not implement DMCreateRestriction",((PetscObject)dmc)->type_name);
1217: PetscLogEventBegin(DM_CreateRestriction,dmc,dmf,0,0);
1218: (*dmc->ops->createrestriction)(dmc,dmf,mat);
1219: PetscLogEventEnd(DM_CreateRestriction,dmc,dmf,0,0);
1220: return(0);
1221: }
1223: /*@
1224: DMCreateInjection - Gets injection matrix between two DM objects
1226: Collective on dac
1228: Input Parameter:
1229: + dac - the DM object
1230: - daf - the second, finer DM object
1232: Output Parameter:
1233: . mat - the injection
1235: Level: developer
1237: Notes:
1238: For DMDA objects this only works for "uniform refinement", that is the refined mesh was obtained DMRefine() or the coarse mesh was obtained by
1239: DMCoarsen(). The coordinates set into the DMDA are completely ignored in computing the injection.
1241: .seealso DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateColoring(), DMCreateMatrix(), DMCreateInterpolation()
1243: @*/
1244: PetscErrorCode DMCreateInjection(DM dac,DM daf,Mat *mat)
1245: {
1252: if (!dac->ops->createinjection) SETERRQ1(PetscObjectComm((PetscObject)dac),PETSC_ERR_SUP,"DM type %s does not implement DMCreateInjection",((PetscObject)dac)->type_name);
1253: PetscLogEventBegin(DM_CreateInjection,dac,daf,0,0);
1254: (*dac->ops->createinjection)(dac,daf,mat);
1255: PetscLogEventEnd(DM_CreateInjection,dac,daf,0,0);
1256: return(0);
1257: }
1259: /*@
1260: DMCreateMassMatrix - Gets mass matrix between two DM objects, M_ij = \int \phi_i \psi_j
1262: Collective on dac
1264: Input Parameter:
1265: + dac - the DM object
1266: - daf - the second, finer DM object
1268: Output Parameter:
1269: . mat - the interpolation
1271: Level: developer
1273: .seealso DMCreateMatrix(), DMRefine(), DMCoarsen(), DMCreateRestriction(), DMCreateInterpolation(), DMCreateInjection()
1274: @*/
1275: PetscErrorCode DMCreateMassMatrix(DM dac, DM daf, Mat *mat)
1276: {
1283: if (!dac->ops->createmassmatrix) SETERRQ1(PetscObjectComm((PetscObject)dac),PETSC_ERR_SUP,"DM type %s does not implement DMCreateMassMatrix",((PetscObject)dac)->type_name);
1284: (*dac->ops->createmassmatrix)(dac, daf, mat);
1285: return(0);
1286: }
1288: /*@
1289: DMCreateColoring - Gets coloring for a DM
1291: Collective on dm
1293: Input Parameter:
1294: + dm - the DM object
1295: - ctype - IS_COLORING_LOCAL or IS_COLORING_GLOBAL
1297: Output Parameter:
1298: . coloring - the coloring
1300: Notes:
1301: Coloring of matrices can be computed directly from the sparse matrix nonzero structure via the MatColoring object or from the mesh from which the
1302: matrix comes from. In general using the mesh produces a more optimal coloring (fewer colors).
1304: This produces a coloring with the distance of 2, see MatSetColoringDistance() which can be used for efficiently computing Jacobians with MatFDColoringCreate()
1306: Level: developer
1308: .seealso DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateMatrix(), DMSetMatType(), MatColoring, MatFDColoringCreate()
1310: @*/
1311: PetscErrorCode DMCreateColoring(DM dm,ISColoringType ctype,ISColoring *coloring)
1312: {
1318: if (!dm->ops->getcoloring) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMCreateColoring",((PetscObject)dm)->type_name);
1319: (*dm->ops->getcoloring)(dm,ctype,coloring);
1320: return(0);
1321: }
1323: /*@
1324: DMCreateMatrix - Gets empty Jacobian for a DM
1326: Collective on dm
1328: Input Parameter:
1329: . dm - the DM object
1331: Output Parameter:
1332: . mat - the empty Jacobian
1334: Level: beginner
1336: Notes:
1337: This properly preallocates the number of nonzeros in the sparse matrix so you
1338: do not need to do it yourself.
1340: By default it also sets the nonzero structure and puts in the zero entries. To prevent setting
1341: the nonzero pattern call DMSetMatrixPreallocateOnly()
1343: For structured grid problems, when you call MatView() on this matrix it is displayed using the global natural ordering, NOT in the ordering used
1344: internally by PETSc.
1346: For structured grid problems, in general it is easiest to use MatSetValuesStencil() or MatSetValuesLocal() to put values into the matrix because MatSetValues() requires
1347: the indices for the global numbering for DMDAs which is complicated.
1349: .seealso DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMSetMatType()
1351: @*/
1352: PetscErrorCode DMCreateMatrix(DM dm,Mat *mat)
1353: {
1359: if (!dm->ops->creatematrix) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMCreateMatrix",((PetscObject)dm)->type_name);
1360: MatInitializePackage();
1361: PetscLogEventBegin(DM_CreateMatrix,0,0,0,0);
1362: (*dm->ops->creatematrix)(dm,mat);
1363: if (PetscDefined(USE_DEBUG)) {
1364: DM mdm;
1366: MatGetDM(*mat,&mdm);
1367: if (!mdm) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"DM type '%s' did not attach the DM to the matrix\n",((PetscObject)dm)->type_name);
1368: }
1369: /* Handle nullspace and near nullspace */
1370: if (dm->Nf) {
1371: MatNullSpace nullSpace;
1372: PetscInt Nf, f;
1374: DMGetNumFields(dm, &Nf);
1375: for (f = 0; f < Nf; ++f) {
1376: if (dm->nullspaceConstructors[f]) {
1377: (*dm->nullspaceConstructors[f])(dm, f, f, &nullSpace);
1378: MatSetNullSpace(*mat, nullSpace);
1379: MatNullSpaceDestroy(&nullSpace);
1380: break;
1381: }
1382: }
1383: for (f = 0; f < Nf; ++f) {
1384: if (dm->nearnullspaceConstructors[f]) {
1385: (*dm->nearnullspaceConstructors[f])(dm, f, f, &nullSpace);
1386: MatSetNearNullSpace(*mat, nullSpace);
1387: MatNullSpaceDestroy(&nullSpace);
1388: }
1389: }
1390: }
1391: PetscLogEventEnd(DM_CreateMatrix,0,0,0,0);
1392: return(0);
1393: }
1395: /*@
1396: DMSetMatrixPreallocateOnly - When DMCreateMatrix() is called the matrix will be properly
1397: preallocated but the nonzero structure and zero values will not be set.
1399: Logically Collective on dm
1401: Input Parameter:
1402: + dm - the DM
1403: - only - PETSC_TRUE if only want preallocation
1405: Level: developer
1406: .seealso DMCreateMatrix(), DMSetMatrixStructureOnly()
1407: @*/
1408: PetscErrorCode DMSetMatrixPreallocateOnly(DM dm, PetscBool only)
1409: {
1412: dm->prealloc_only = only;
1413: return(0);
1414: }
1416: /*@
1417: DMSetMatrixStructureOnly - When DMCreateMatrix() is called, the matrix structure will be created
1418: but the array for values will not be allocated.
1420: Logically Collective on dm
1422: Input Parameter:
1423: + dm - the DM
1424: - only - PETSC_TRUE if only want matrix stucture
1426: Level: developer
1427: .seealso DMCreateMatrix(), DMSetMatrixPreallocateOnly()
1428: @*/
1429: PetscErrorCode DMSetMatrixStructureOnly(DM dm, PetscBool only)
1430: {
1433: dm->structure_only = only;
1434: return(0);
1435: }
1437: /*@C
1438: DMGetWorkArray - Gets a work array guaranteed to be at least the input size, restore with DMRestoreWorkArray()
1440: Not Collective
1442: Input Parameters:
1443: + dm - the DM object
1444: . count - The minium size
1445: - dtype - MPI data type, often MPIU_REAL, MPIU_SCALAR, MPIU_INT)
1447: Output Parameter:
1448: . array - the work array
1450: Level: developer
1452: .seealso DMDestroy(), DMCreate()
1453: @*/
1454: PetscErrorCode DMGetWorkArray(DM dm,PetscInt count,MPI_Datatype dtype,void *mem)
1455: {
1457: DMWorkLink link;
1458: PetscMPIInt dsize;
1463: if (dm->workin) {
1464: link = dm->workin;
1465: dm->workin = dm->workin->next;
1466: } else {
1467: PetscNewLog(dm,&link);
1468: }
1469: MPI_Type_size(dtype,&dsize);
1470: if (((size_t)dsize*count) > link->bytes) {
1471: PetscFree(link->mem);
1472: PetscMalloc(dsize*count,&link->mem);
1473: link->bytes = dsize*count;
1474: }
1475: link->next = dm->workout;
1476: dm->workout = link;
1477: #if defined(PETSC_HAVE_VALGRIND)
1478: VALGRIND_MAKE_MEM_NOACCESS((char*)link->mem + (size_t)dsize*count, link->bytes - (size_t)dsize*count);
1479: VALGRIND_MAKE_MEM_UNDEFINED(link->mem, (size_t)dsize*count);
1480: #endif
1481: *(void**)mem = link->mem;
1482: return(0);
1483: }
1485: /*@C
1486: DMRestoreWorkArray - Restores a work array guaranteed to be at least the input size, restore with DMRestoreWorkArray()
1488: Not Collective
1490: Input Parameters:
1491: + dm - the DM object
1492: . count - The minium size
1493: - dtype - MPI data type, often MPIU_REAL, MPIU_SCALAR, MPIU_INT
1495: Output Parameter:
1496: . array - the work array
1498: Level: developer
1500: Developer Notes:
1501: count and dtype are ignored, they are only needed for DMGetWorkArray()
1502: .seealso DMDestroy(), DMCreate()
1503: @*/
1504: PetscErrorCode DMRestoreWorkArray(DM dm,PetscInt count,MPI_Datatype dtype,void *mem)
1505: {
1506: DMWorkLink *p,link;
1511: for (p=&dm->workout; (link=*p); p=&link->next) {
1512: if (link->mem == *(void**)mem) {
1513: *p = link->next;
1514: link->next = dm->workin;
1515: dm->workin = link;
1516: *(void**)mem = NULL;
1517: return(0);
1518: }
1519: }
1520: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Array was not checked out");
1521: }
1523: /*@C
1524: DMSetNullSpaceConstructor - Provide a callback function which constructs the nullspace for a given field
1526: Logically collective on DM
1528: Input Parameters:
1529: + dm - The DM
1530: . field - The field number for the nullspace
1531: - nullsp - A callback to create the nullspace
1533: Notes:
1534: The callback is intended to provide nullspaces when function spaces are joined or split, such as in DMCreateSubDM(). The calling sequence is
1535: $ PetscErrorCode nullsp(DM dm, PetscInt origField, PetscInt field, MatNullSpace *nullSpace)
1536: $ dm - The present DM
1537: $ origField - The field number given above, in the original DM
1538: $ field - The field number in dm
1539: $ nullSpace - The nullspace for the given field
1541: This function is currently not available from Fortran.
1543: .seealso: DMGetNullSpaceConstructor(), DMSetNearNullSpaceConstructor(), DMGetNearNullSpaceConstructor(), DMCreateSubDM(), DMCreateSuperDM()
1544: */
1545: PetscErrorCode DMSetNullSpaceConstructor(DM dm, PetscInt field, PetscErrorCode (*nullsp)(DM dm, PetscInt origField, PetscInt field, MatNullSpace *nullSpace))
1546: {
1549: if (field >= 10) SETERRQ1(PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_OUTOFRANGE, "Cannot handle %d >= 10 fields", field);
1550: dm->nullspaceConstructors[field] = nullsp;
1551: return(0);
1552: }
1554: /*@C
1555: DMGetNullSpaceConstructor - Return the callback function which constructs the nullspace for a given field, or NULL
1557: Not collective
1559: Input Parameters:
1560: + dm - The DM
1561: - field - The field number for the nullspace
1563: Output Parameter:
1564: . nullsp - A callback to create the nullspace
1566: Notes:
1567: The callback is intended to provide nullspaces when function spaces are joined or split, such as in DMCreateSubDM(). The calling sequence is
1568: $ PetscErrorCode nullsp(DM dm, PetscInt origField, PetscInt field, MatNullSpace *nullSpace)
1569: $ dm - The present DM
1570: $ origField - The field number given above, in the original DM
1571: $ field - The field number in dm
1572: $ nullSpace - The nullspace for the given field
1574: This function is currently not available from Fortran.
1576: .seealso: DMSetNullSpaceConstructor(), DMSetNearNullSpaceConstructor(), DMGetNearNullSpaceConstructor(), DMCreateSubDM(), DMCreateSuperDM()
1577: */
1578: PetscErrorCode DMGetNullSpaceConstructor(DM dm, PetscInt field, PetscErrorCode (**nullsp)(DM dm, PetscInt origField, PetscInt field, MatNullSpace *nullSpace))
1579: {
1583: if (field >= 10) SETERRQ1(PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_OUTOFRANGE, "Cannot handle %d >= 10 fields", field);
1584: *nullsp = dm->nullspaceConstructors[field];
1585: return(0);
1586: }
1588: /*@C
1589: DMSetNearNullSpaceConstructor - Provide a callback function which constructs the near-nullspace for a given field
1591: Logically collective on DM
1593: Input Parameters:
1594: + dm - The DM
1595: . field - The field number for the nullspace
1596: - nullsp - A callback to create the near-nullspace
1598: Notes:
1599: The callback is intended to provide nullspaces when function spaces are joined or split, such as in DMCreateSubDM(). The calling sequence is
1600: $ PetscErrorCode nullsp(DM dm, PetscInt origField, PetscInt field, MatNullSpace *nullSpace)
1601: $ dm - The present DM
1602: $ origField - The field number given above, in the original DM
1603: $ field - The field number in dm
1604: $ nullSpace - The nullspace for the given field
1606: This function is currently not available from Fortran.
1608: .seealso: DMGetNearNullSpaceConstructor(), DMSetNullSpaceConstructor(), DMGetNullSpaceConstructor(), DMCreateSubDM(), DMCreateSuperDM()
1609: */
1610: PetscErrorCode DMSetNearNullSpaceConstructor(DM dm, PetscInt field, PetscErrorCode (*nullsp)(DM dm, PetscInt origField, PetscInt field, MatNullSpace *nullSpace))
1611: {
1614: if (field >= 10) SETERRQ1(PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_OUTOFRANGE, "Cannot handle %d >= 10 fields", field);
1615: dm->nearnullspaceConstructors[field] = nullsp;
1616: return(0);
1617: }
1619: /*@C
1620: DMGetNearNullSpaceConstructor - Return the callback function which constructs the near-nullspace for a given field, or NULL
1622: Not collective
1624: Input Parameters:
1625: + dm - The DM
1626: - field - The field number for the nullspace
1628: Output Parameter:
1629: . nullsp - A callback to create the near-nullspace
1631: Notes:
1632: The callback is intended to provide nullspaces when function spaces are joined or split, such as in DMCreateSubDM(). The calling sequence is
1633: $ PetscErrorCode nullsp(DM dm, PetscInt origField, PetscInt field, MatNullSpace *nullSpace)
1634: $ dm - The present DM
1635: $ origField - The field number given above, in the original DM
1636: $ field - The field number in dm
1637: $ nullSpace - The nullspace for the given field
1639: This function is currently not available from Fortran.
1641: .seealso: DMSetNearNullSpaceConstructor(), DMSetNullSpaceConstructor(), DMGetNullSpaceConstructor(), DMCreateSubDM(), DMCreateSuperDM()
1642: */
1643: PetscErrorCode DMGetNearNullSpaceConstructor(DM dm, PetscInt field, PetscErrorCode (**nullsp)(DM dm, PetscInt origField, PetscInt field, MatNullSpace *nullSpace))
1644: {
1648: if (field >= 10) SETERRQ1(PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_OUTOFRANGE, "Cannot handle %d >= 10 fields", field);
1649: *nullsp = dm->nearnullspaceConstructors[field];
1650: return(0);
1651: }
1653: /*@C
1654: DMCreateFieldIS - Creates a set of IS objects with the global indices of dofs for each field
1656: Not collective
1658: Input Parameter:
1659: . dm - the DM object
1661: Output Parameters:
1662: + numFields - The number of fields (or NULL if not requested)
1663: . fieldNames - The name for each field (or NULL if not requested)
1664: - fields - The global indices for each field (or NULL if not requested)
1666: Level: intermediate
1668: Notes:
1669: The user is responsible for freeing all requested arrays. In particular, every entry of names should be freed with
1670: PetscFree(), every entry of fields should be destroyed with ISDestroy(), and both arrays should be freed with
1671: PetscFree().
1673: .seealso DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix()
1674: @*/
1675: PetscErrorCode DMCreateFieldIS(DM dm, PetscInt *numFields, char ***fieldNames, IS **fields)
1676: {
1677: PetscSection section, sectionGlobal;
1682: if (numFields) {
1684: *numFields = 0;
1685: }
1686: if (fieldNames) {
1688: *fieldNames = NULL;
1689: }
1690: if (fields) {
1692: *fields = NULL;
1693: }
1694: DMGetLocalSection(dm, §ion);
1695: if (section) {
1696: PetscInt *fieldSizes, *fieldNc, **fieldIndices;
1697: PetscInt nF, f, pStart, pEnd, p;
1699: DMGetGlobalSection(dm, §ionGlobal);
1700: PetscSectionGetNumFields(section, &nF);
1701: PetscMalloc3(nF,&fieldSizes,nF,&fieldNc,nF,&fieldIndices);
1702: PetscSectionGetChart(sectionGlobal, &pStart, &pEnd);
1703: for (f = 0; f < nF; ++f) {
1704: fieldSizes[f] = 0;
1705: PetscSectionGetFieldComponents(section, f, &fieldNc[f]);
1706: }
1707: for (p = pStart; p < pEnd; ++p) {
1708: PetscInt gdof;
1710: PetscSectionGetDof(sectionGlobal, p, &gdof);
1711: if (gdof > 0) {
1712: for (f = 0; f < nF; ++f) {
1713: PetscInt fdof, fcdof, fpdof;
1715: PetscSectionGetFieldDof(section, p, f, &fdof);
1716: PetscSectionGetFieldConstraintDof(section, p, f, &fcdof);
1717: fpdof = fdof-fcdof;
1718: if (fpdof && fpdof != fieldNc[f]) {
1719: /* Layout does not admit a pointwise block size */
1720: fieldNc[f] = 1;
1721: }
1722: fieldSizes[f] += fpdof;
1723: }
1724: }
1725: }
1726: for (f = 0; f < nF; ++f) {
1727: PetscMalloc1(fieldSizes[f], &fieldIndices[f]);
1728: fieldSizes[f] = 0;
1729: }
1730: for (p = pStart; p < pEnd; ++p) {
1731: PetscInt gdof, goff;
1733: PetscSectionGetDof(sectionGlobal, p, &gdof);
1734: if (gdof > 0) {
1735: PetscSectionGetOffset(sectionGlobal, p, &goff);
1736: for (f = 0; f < nF; ++f) {
1737: PetscInt fdof, fcdof, fc;
1739: PetscSectionGetFieldDof(section, p, f, &fdof);
1740: PetscSectionGetFieldConstraintDof(section, p, f, &fcdof);
1741: for (fc = 0; fc < fdof-fcdof; ++fc, ++fieldSizes[f]) {
1742: fieldIndices[f][fieldSizes[f]] = goff++;
1743: }
1744: }
1745: }
1746: }
1747: if (numFields) *numFields = nF;
1748: if (fieldNames) {
1749: PetscMalloc1(nF, fieldNames);
1750: for (f = 0; f < nF; ++f) {
1751: const char *fieldName;
1753: PetscSectionGetFieldName(section, f, &fieldName);
1754: PetscStrallocpy(fieldName, (char**) &(*fieldNames)[f]);
1755: }
1756: }
1757: if (fields) {
1758: PetscMalloc1(nF, fields);
1759: for (f = 0; f < nF; ++f) {
1760: PetscInt bs, in[2], out[2];
1762: ISCreateGeneral(PetscObjectComm((PetscObject)dm), fieldSizes[f], fieldIndices[f], PETSC_OWN_POINTER, &(*fields)[f]);
1763: in[0] = -fieldNc[f];
1764: in[1] = fieldNc[f];
1765: MPIU_Allreduce(in, out, 2, MPIU_INT, MPI_MAX, PetscObjectComm((PetscObject)dm));
1766: bs = (-out[0] == out[1]) ? out[1] : 1;
1767: ISSetBlockSize((*fields)[f], bs);
1768: }
1769: }
1770: PetscFree3(fieldSizes,fieldNc,fieldIndices);
1771: } else if (dm->ops->createfieldis) {
1772: (*dm->ops->createfieldis)(dm, numFields, fieldNames, fields);
1773: }
1774: return(0);
1775: }
1778: /*@C
1779: DMCreateFieldDecomposition - Returns a list of IS objects defining a decomposition of a problem into subproblems
1780: corresponding to different fields: each IS contains the global indices of the dofs of the
1781: corresponding field. The optional list of DMs define the DM for each subproblem.
1782: Generalizes DMCreateFieldIS().
1784: Not collective
1786: Input Parameter:
1787: . dm - the DM object
1789: Output Parameters:
1790: + len - The number of subproblems in the field decomposition (or NULL if not requested)
1791: . namelist - The name for each field (or NULL if not requested)
1792: . islist - The global indices for each field (or NULL if not requested)
1793: - dmlist - The DMs for each field subproblem (or NULL, if not requested; if NULL is returned, no DMs are defined)
1795: Level: intermediate
1797: Notes:
1798: The user is responsible for freeing all requested arrays. In particular, every entry of names should be freed with
1799: PetscFree(), every entry of is should be destroyed with ISDestroy(), every entry of dm should be destroyed with DMDestroy(),
1800: and all of the arrays should be freed with PetscFree().
1802: .seealso DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateFieldIS()
1803: @*/
1804: PetscErrorCode DMCreateFieldDecomposition(DM dm, PetscInt *len, char ***namelist, IS **islist, DM **dmlist)
1805: {
1810: if (len) {
1812: *len = 0;
1813: }
1814: if (namelist) {
1816: *namelist = NULL;
1817: }
1818: if (islist) {
1820: *islist = NULL;
1821: }
1822: if (dmlist) {
1824: *dmlist = NULL;
1825: }
1826: /*
1827: Is it a good idea to apply the following check across all impls?
1828: Perhaps some impls can have a well-defined decomposition before DMSetUp?
1829: This, however, follows the general principle that accessors are not well-behaved until the object is set up.
1830: */
1831: if (!dm->setupcalled) SETERRQ(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_WRONGSTATE, "Decomposition defined only after DMSetUp");
1832: if (!dm->ops->createfielddecomposition) {
1833: PetscSection section;
1834: PetscInt numFields, f;
1836: DMGetLocalSection(dm, §ion);
1837: if (section) {PetscSectionGetNumFields(section, &numFields);}
1838: if (section && numFields && dm->ops->createsubdm) {
1839: if (len) *len = numFields;
1840: if (namelist) {PetscMalloc1(numFields,namelist);}
1841: if (islist) {PetscMalloc1(numFields,islist);}
1842: if (dmlist) {PetscMalloc1(numFields,dmlist);}
1843: for (f = 0; f < numFields; ++f) {
1844: const char *fieldName;
1846: DMCreateSubDM(dm, 1, &f, islist ? &(*islist)[f] : NULL, dmlist ? &(*dmlist)[f] : NULL);
1847: if (namelist) {
1848: PetscSectionGetFieldName(section, f, &fieldName);
1849: PetscStrallocpy(fieldName, (char**) &(*namelist)[f]);
1850: }
1851: }
1852: } else {
1853: DMCreateFieldIS(dm, len, namelist, islist);
1854: /* By default there are no DMs associated with subproblems. */
1855: if (dmlist) *dmlist = NULL;
1856: }
1857: } else {
1858: (*dm->ops->createfielddecomposition)(dm,len,namelist,islist,dmlist);
1859: }
1860: return(0);
1861: }
1863: /*@
1864: DMCreateSubDM - Returns an IS and DM encapsulating a subproblem defined by the fields passed in.
1865: The fields are defined by DMCreateFieldIS().
1867: Not collective
1869: Input Parameters:
1870: + dm - The DM object
1871: . numFields - The number of fields in this subproblem
1872: - fields - The field numbers of the selected fields
1874: Output Parameters:
1875: + is - The global indices for the subproblem
1876: - subdm - The DM for the subproblem
1878: Note: You need to call DMPlexSetMigrationSF() on the original DM if you want the Global-To-Natural map to be automatically constructed
1880: Level: intermediate
1882: .seealso DMPlexSetMigrationSF(), DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateFieldIS()
1883: @*/
1884: PetscErrorCode DMCreateSubDM(DM dm, PetscInt numFields, const PetscInt fields[], IS *is, DM *subdm)
1885: {
1893: if (!dm->ops->createsubdm) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMCreateSubDM",((PetscObject)dm)->type_name);
1894: (*dm->ops->createsubdm)(dm, numFields, fields, is, subdm);
1895: return(0);
1896: }
1898: /*@C
1899: DMCreateSuperDM - Returns an arrays of ISes and DM encapsulating a superproblem defined by the DMs passed in.
1901: Not collective
1903: Input Parameter:
1904: + dms - The DM objects
1905: - len - The number of DMs
1907: Output Parameters:
1908: + is - The global indices for the subproblem, or NULL
1909: - superdm - The DM for the superproblem
1911: Note: You need to call DMPlexSetMigrationSF() on the original DM if you want the Global-To-Natural map to be automatically constructed
1913: Level: intermediate
1915: .seealso DMPlexSetMigrationSF(), DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateFieldIS()
1916: @*/
1917: PetscErrorCode DMCreateSuperDM(DM dms[], PetscInt len, IS **is, DM *superdm)
1918: {
1919: PetscInt i;
1927: if (len < 0) SETERRQ1(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Number of DMs must be nonnegative: %D", len);
1928: if (len) {
1929: DM dm = dms[0];
1930: if (!dm->ops->createsuperdm) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMCreateSuperDM",((PetscObject)dm)->type_name);
1931: (*dm->ops->createsuperdm)(dms, len, is, superdm);
1932: }
1933: return(0);
1934: }
1937: /*@C
1938: DMCreateDomainDecomposition - Returns lists of IS objects defining a decomposition of a problem into subproblems
1939: corresponding to restrictions to pairs nested subdomains: each IS contains the global
1940: indices of the dofs of the corresponding subdomains. The inner subdomains conceptually
1941: define a nonoverlapping covering, while outer subdomains can overlap.
1942: The optional list of DMs define the DM for each subproblem.
1944: Not collective
1946: Input Parameter:
1947: . dm - the DM object
1949: Output Parameters:
1950: + len - The number of subproblems in the domain decomposition (or NULL if not requested)
1951: . namelist - The name for each subdomain (or NULL if not requested)
1952: . innerislist - The global indices for each inner subdomain (or NULL, if not requested)
1953: . outerislist - The global indices for each outer subdomain (or NULL, if not requested)
1954: - dmlist - The DMs for each subdomain subproblem (or NULL, if not requested; if NULL is returned, no DMs are defined)
1956: Level: intermediate
1958: Notes:
1959: The user is responsible for freeing all requested arrays. In particular, every entry of names should be freed with
1960: PetscFree(), every entry of is should be destroyed with ISDestroy(), every entry of dm should be destroyed with DMDestroy(),
1961: and all of the arrays should be freed with PetscFree().
1963: .seealso DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateFieldDecomposition()
1964: @*/
1965: PetscErrorCode DMCreateDomainDecomposition(DM dm, PetscInt *len, char ***namelist, IS **innerislist, IS **outerislist, DM **dmlist)
1966: {
1967: PetscErrorCode ierr;
1968: DMSubDomainHookLink link;
1969: PetscInt i,l;
1978: /*
1979: Is it a good idea to apply the following check across all impls?
1980: Perhaps some impls can have a well-defined decomposition before DMSetUp?
1981: This, however, follows the general principle that accessors are not well-behaved until the object is set up.
1982: */
1983: if (!dm->setupcalled) SETERRQ(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_WRONGSTATE, "Decomposition defined only after DMSetUp");
1984: if (dm->ops->createdomaindecomposition) {
1985: (*dm->ops->createdomaindecomposition)(dm,&l,namelist,innerislist,outerislist,dmlist);
1986: /* copy subdomain hooks and context over to the subdomain DMs */
1987: if (dmlist && *dmlist) {
1988: for (i = 0; i < l; i++) {
1989: for (link=dm->subdomainhook; link; link=link->next) {
1990: if (link->ddhook) {(*link->ddhook)(dm,(*dmlist)[i],link->ctx);}
1991: }
1992: if (dm->ctx) (*dmlist)[i]->ctx = dm->ctx;
1993: }
1994: }
1995: if (len) *len = l;
1996: }
1997: return(0);
1998: }
2001: /*@C
2002: DMCreateDomainDecompositionScatters - Returns scatters to the subdomain vectors from the global vector
2004: Not collective
2006: Input Parameters:
2007: + dm - the DM object
2008: . n - the number of subdomain scatters
2009: - subdms - the local subdomains
2011: Output Parameters:
2012: + n - the number of scatters returned
2013: . iscat - scatter from global vector to nonoverlapping global vector entries on subdomain
2014: . oscat - scatter from global vector to overlapping global vector entries on subdomain
2015: - gscat - scatter from global vector to local vector on subdomain (fills in ghosts)
2017: Notes:
2018: This is an alternative to the iis and ois arguments in DMCreateDomainDecomposition that allow for the solution
2019: of general nonlinear problems with overlapping subdomain methods. While merely having index sets that enable subsets
2020: of the residual equations to be created is fine for linear problems, nonlinear problems require local assembly of
2021: solution and residual data.
2023: Level: developer
2025: .seealso DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateFieldIS()
2026: @*/
2027: PetscErrorCode DMCreateDomainDecompositionScatters(DM dm,PetscInt n,DM *subdms,VecScatter **iscat,VecScatter **oscat,VecScatter **gscat)
2028: {
2034: if (!dm->ops->createddscatters) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMCreateDomainDecompositionScatters",((PetscObject)dm)->type_name);
2035: (*dm->ops->createddscatters)(dm,n,subdms,iscat,oscat,gscat);
2036: return(0);
2037: }
2039: /*@
2040: DMRefine - Refines a DM object
2042: Collective on dm
2044: Input Parameter:
2045: + dm - the DM object
2046: - comm - the communicator to contain the new DM object (or MPI_COMM_NULL)
2048: Output Parameter:
2049: . dmf - the refined DM, or NULL
2051: Options Dtabase Keys:
2052: . -dm_plex_cell_refiner <strategy> - chooses the refinement strategy, e.g. regular, tohex
2054: Note: If no refinement was done, the return value is NULL
2056: Level: developer
2058: .seealso DMCoarsen(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation()
2059: @*/
2060: PetscErrorCode DMRefine(DM dm,MPI_Comm comm,DM *dmf)
2061: {
2062: PetscErrorCode ierr;
2063: DMRefineHookLink link;
2067: if (!dm->ops->refine) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMRefine",((PetscObject)dm)->type_name);
2068: PetscLogEventBegin(DM_Refine,dm,0,0,0);
2069: (*dm->ops->refine)(dm,comm,dmf);
2070: if (*dmf) {
2071: (*dmf)->ops->creatematrix = dm->ops->creatematrix;
2073: PetscObjectCopyFortranFunctionPointers((PetscObject)dm,(PetscObject)*dmf);
2075: (*dmf)->ctx = dm->ctx;
2076: (*dmf)->leveldown = dm->leveldown;
2077: (*dmf)->levelup = dm->levelup + 1;
2079: DMSetMatType(*dmf,dm->mattype);
2080: for (link=dm->refinehook; link; link=link->next) {
2081: if (link->refinehook) {
2082: (*link->refinehook)(dm,*dmf,link->ctx);
2083: }
2084: }
2085: }
2086: PetscLogEventEnd(DM_Refine,dm,0,0,0);
2087: return(0);
2088: }
2090: /*@C
2091: DMRefineHookAdd - adds a callback to be run when interpolating a nonlinear problem to a finer grid
2093: Logically Collective
2095: Input Arguments:
2096: + coarse - nonlinear solver context on which to run a hook when restricting to a coarser level
2097: . refinehook - function to run when setting up a coarser level
2098: . interphook - function to run to update data on finer levels (once per SNESSolve())
2099: - ctx - [optional] user-defined context for provide data for the hooks (may be NULL)
2101: Calling sequence of refinehook:
2102: $ refinehook(DM coarse,DM fine,void *ctx);
2104: + coarse - coarse level DM
2105: . fine - fine level DM to interpolate problem to
2106: - ctx - optional user-defined function context
2108: Calling sequence for interphook:
2109: $ interphook(DM coarse,Mat interp,DM fine,void *ctx)
2111: + coarse - coarse level DM
2112: . interp - matrix interpolating a coarse-level solution to the finer grid
2113: . fine - fine level DM to update
2114: - ctx - optional user-defined function context
2116: Level: advanced
2118: Notes:
2119: This function is only needed if auxiliary data needs to be passed to fine grids while grid sequencing
2121: If this function is called multiple times, the hooks will be run in the order they are added.
2123: This function is currently not available from Fortran.
2125: .seealso: DMCoarsenHookAdd(), SNESFASGetInterpolation(), SNESFASGetInjection(), PetscObjectCompose(), PetscContainerCreate()
2126: @*/
2127: PetscErrorCode DMRefineHookAdd(DM coarse,PetscErrorCode (*refinehook)(DM,DM,void*),PetscErrorCode (*interphook)(DM,Mat,DM,void*),void *ctx)
2128: {
2129: PetscErrorCode ierr;
2130: DMRefineHookLink link,*p;
2134: for (p=&coarse->refinehook; *p; p=&(*p)->next) { /* Scan to the end of the current list of hooks */
2135: if ((*p)->refinehook == refinehook && (*p)->interphook == interphook && (*p)->ctx == ctx) return(0);
2136: }
2137: PetscNew(&link);
2138: link->refinehook = refinehook;
2139: link->interphook = interphook;
2140: link->ctx = ctx;
2141: link->next = NULL;
2142: *p = link;
2143: return(0);
2144: }
2146: /*@C
2147: DMRefineHookRemove - remove a callback from the list of hooks to be run when interpolating a nonlinear problem to a finer grid
2149: Logically Collective
2151: Input Arguments:
2152: + coarse - nonlinear solver context on which to run a hook when restricting to a coarser level
2153: . refinehook - function to run when setting up a coarser level
2154: . interphook - function to run to update data on finer levels (once per SNESSolve())
2155: - ctx - [optional] user-defined context for provide data for the hooks (may be NULL)
2157: Level: advanced
2159: Notes:
2160: This function does nothing if the hook is not in the list.
2162: This function is currently not available from Fortran.
2164: .seealso: DMCoarsenHookRemove(), SNESFASGetInterpolation(), SNESFASGetInjection(), PetscObjectCompose(), PetscContainerCreate()
2165: @*/
2166: PetscErrorCode DMRefineHookRemove(DM coarse,PetscErrorCode (*refinehook)(DM,DM,void*),PetscErrorCode (*interphook)(DM,Mat,DM,void*),void *ctx)
2167: {
2168: PetscErrorCode ierr;
2169: DMRefineHookLink link,*p;
2173: for (p=&coarse->refinehook; *p; p=&(*p)->next) { /* Search the list of current hooks */
2174: if ((*p)->refinehook == refinehook && (*p)->interphook == interphook && (*p)->ctx == ctx) {
2175: link = *p;
2176: *p = link->next;
2177: PetscFree(link);
2178: break;
2179: }
2180: }
2181: return(0);
2182: }
2184: /*@
2185: DMInterpolate - interpolates user-defined problem data to a finer DM by running hooks registered by DMRefineHookAdd()
2187: Collective if any hooks are
2189: Input Arguments:
2190: + coarse - coarser DM to use as a base
2191: . interp - interpolation matrix, apply using MatInterpolate()
2192: - fine - finer DM to update
2194: Level: developer
2196: .seealso: DMRefineHookAdd(), MatInterpolate()
2197: @*/
2198: PetscErrorCode DMInterpolate(DM coarse,Mat interp,DM fine)
2199: {
2200: PetscErrorCode ierr;
2201: DMRefineHookLink link;
2204: for (link=fine->refinehook; link; link=link->next) {
2205: if (link->interphook) {
2206: (*link->interphook)(coarse,interp,fine,link->ctx);
2207: }
2208: }
2209: return(0);
2210: }
2212: /*@
2213: DMInterpolateSolution - Interpolates a solution from a coarse mesh to a fine mesh.
2215: Collective on DM
2217: Input Arguments:
2218: + coarse - coarse DM
2219: . fine - fine DM
2220: . interp - (optional) the matrix computed by DMCreateInterpolation(). Implementations may not need this, but if it
2221: is available it can avoid some recomputation. If it is provided, MatInterpolate() will be used if
2222: the coarse DM does not have a specialized implementation.
2223: - coarseSol - solution on the coarse mesh
2225: Output Arguments:
2226: . fineSol - the interpolation of coarseSol to the fine mesh
2228: Level: developer
2230: Note: This function exists because the interpolation of a solution vector between meshes is not always a linear
2231: map. For example, if a boundary value problem has an inhomogeneous Dirichlet boundary condition that is compressed
2232: out of the solution vector. Or if interpolation is inherently a nonlinear operation, such as a method using
2233: slope-limiting reconstruction.
2235: .seealso DMInterpolate(), DMCreateInterpolation()
2236: @*/
2237: PetscErrorCode DMInterpolateSolution(DM coarse, DM fine, Mat interp, Vec coarseSol, Vec fineSol)
2238: {
2239: PetscErrorCode (*interpsol)(DM,DM,Mat,Vec,Vec) = NULL;
2249: PetscObjectQueryFunction((PetscObject)coarse,"DMInterpolateSolution_C", &interpsol);
2250: if (interpsol) {
2251: (*interpsol)(coarse, fine, interp, coarseSol, fineSol);
2252: } else if (interp) {
2253: MatInterpolate(interp, coarseSol, fineSol);
2254: } else SETERRQ1(PetscObjectComm((PetscObject)coarse), PETSC_ERR_SUP, "DM %s does not implement DMInterpolateSolution()", ((PetscObject)coarse)->type_name);
2255: return(0);
2256: }
2258: /*@
2259: DMGetRefineLevel - Gets the number of refinements that have generated this DM.
2261: Not Collective
2263: Input Parameter:
2264: . dm - the DM object
2266: Output Parameter:
2267: . level - number of refinements
2269: Level: developer
2271: .seealso DMCoarsen(), DMGetCoarsenLevel(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation()
2273: @*/
2274: PetscErrorCode DMGetRefineLevel(DM dm,PetscInt *level)
2275: {
2278: *level = dm->levelup;
2279: return(0);
2280: }
2282: /*@
2283: DMSetRefineLevel - Sets the number of refinements that have generated this DM.
2285: Not Collective
2287: Input Parameter:
2288: + dm - the DM object
2289: - level - number of refinements
2291: Level: advanced
2293: Notes:
2294: This value is used by PCMG to determine how many multigrid levels to use
2296: .seealso DMCoarsen(), DMGetCoarsenLevel(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation()
2298: @*/
2299: PetscErrorCode DMSetRefineLevel(DM dm,PetscInt level)
2300: {
2303: dm->levelup = level;
2304: return(0);
2305: }
2307: PetscErrorCode DMGetBasisTransformDM_Internal(DM dm, DM *tdm)
2308: {
2312: *tdm = dm->transformDM;
2313: return(0);
2314: }
2316: PetscErrorCode DMGetBasisTransformVec_Internal(DM dm, Vec *tv)
2317: {
2321: *tv = dm->transform;
2322: return(0);
2323: }
2325: /*@
2326: DMHasBasisTransform - Whether we employ a basis transformation from functions in global vectors to functions in local vectors
2328: Input Parameter:
2329: . dm - The DM
2331: Output Parameter:
2332: . flg - PETSC_TRUE if a basis transformation should be done
2334: Level: developer
2336: .seealso: DMPlexGlobalToLocalBasis(), DMPlexLocalToGlobalBasis(), DMPlexCreateBasisRotation()
2337: @*/
2338: PetscErrorCode DMHasBasisTransform(DM dm, PetscBool *flg)
2339: {
2340: Vec tv;
2346: DMGetBasisTransformVec_Internal(dm, &tv);
2347: *flg = tv ? PETSC_TRUE : PETSC_FALSE;
2348: return(0);
2349: }
2351: PetscErrorCode DMConstructBasisTransform_Internal(DM dm)
2352: {
2353: PetscSection s, ts;
2354: PetscScalar *ta;
2355: PetscInt cdim, pStart, pEnd, p, Nf, f, Nc, dof;
2359: DMGetCoordinateDim(dm, &cdim);
2360: DMGetLocalSection(dm, &s);
2361: PetscSectionGetChart(s, &pStart, &pEnd);
2362: PetscSectionGetNumFields(s, &Nf);
2363: DMClone(dm, &dm->transformDM);
2364: DMGetLocalSection(dm->transformDM, &ts);
2365: PetscSectionSetNumFields(ts, Nf);
2366: PetscSectionSetChart(ts, pStart, pEnd);
2367: for (f = 0; f < Nf; ++f) {
2368: PetscSectionGetFieldComponents(s, f, &Nc);
2369: /* We could start to label fields by their transformation properties */
2370: if (Nc != cdim) continue;
2371: for (p = pStart; p < pEnd; ++p) {
2372: PetscSectionGetFieldDof(s, p, f, &dof);
2373: if (!dof) continue;
2374: PetscSectionSetFieldDof(ts, p, f, PetscSqr(cdim));
2375: PetscSectionAddDof(ts, p, PetscSqr(cdim));
2376: }
2377: }
2378: PetscSectionSetUp(ts);
2379: DMCreateLocalVector(dm->transformDM, &dm->transform);
2380: VecGetArray(dm->transform, &ta);
2381: for (p = pStart; p < pEnd; ++p) {
2382: for (f = 0; f < Nf; ++f) {
2383: PetscSectionGetFieldDof(ts, p, f, &dof);
2384: if (dof) {
2385: PetscReal x[3] = {0.0, 0.0, 0.0};
2386: PetscScalar *tva;
2387: const PetscScalar *A;
2389: /* TODO Get quadrature point for this dual basis vector for coordinate */
2390: (*dm->transformGetMatrix)(dm, x, PETSC_TRUE, &A, dm->transformCtx);
2391: DMPlexPointLocalFieldRef(dm->transformDM, p, f, ta, (void *) &tva);
2392: PetscArraycpy(tva, A, PetscSqr(cdim));
2393: }
2394: }
2395: }
2396: VecRestoreArray(dm->transform, &ta);
2397: return(0);
2398: }
2400: PetscErrorCode DMCopyTransform(DM dm, DM newdm)
2401: {
2407: newdm->transformCtx = dm->transformCtx;
2408: newdm->transformSetUp = dm->transformSetUp;
2409: newdm->transformDestroy = NULL;
2410: newdm->transformGetMatrix = dm->transformGetMatrix;
2411: if (newdm->transformSetUp) {DMConstructBasisTransform_Internal(newdm);}
2412: return(0);
2413: }
2415: /*@C
2416: DMGlobalToLocalHookAdd - adds a callback to be run when global to local is called
2418: Logically Collective
2420: Input Arguments:
2421: + dm - the DM
2422: . beginhook - function to run at the beginning of DMGlobalToLocalBegin()
2423: . endhook - function to run after DMGlobalToLocalEnd() has completed
2424: - ctx - [optional] user-defined context for provide data for the hooks (may be NULL)
2426: Calling sequence for beginhook:
2427: $ beginhook(DM fine,VecScatter out,VecScatter in,DM coarse,void *ctx)
2429: + dm - global DM
2430: . g - global vector
2431: . mode - mode
2432: . l - local vector
2433: - ctx - optional user-defined function context
2436: Calling sequence for endhook:
2437: $ endhook(DM fine,VecScatter out,VecScatter in,DM coarse,void *ctx)
2439: + global - global DM
2440: - ctx - optional user-defined function context
2442: Level: advanced
2444: .seealso: DMRefineHookAdd(), SNESFASGetInterpolation(), SNESFASGetInjection(), PetscObjectCompose(), PetscContainerCreate()
2445: @*/
2446: PetscErrorCode DMGlobalToLocalHookAdd(DM dm,PetscErrorCode (*beginhook)(DM,Vec,InsertMode,Vec,void*),PetscErrorCode (*endhook)(DM,Vec,InsertMode,Vec,void*),void *ctx)
2447: {
2448: PetscErrorCode ierr;
2449: DMGlobalToLocalHookLink link,*p;
2453: for (p=&dm->gtolhook; *p; p=&(*p)->next) {} /* Scan to the end of the current list of hooks */
2454: PetscNew(&link);
2455: link->beginhook = beginhook;
2456: link->endhook = endhook;
2457: link->ctx = ctx;
2458: link->next = NULL;
2459: *p = link;
2460: return(0);
2461: }
2463: static PetscErrorCode DMGlobalToLocalHook_Constraints(DM dm, Vec g, InsertMode mode, Vec l, void *ctx)
2464: {
2465: Mat cMat;
2466: Vec cVec;
2467: PetscSection section, cSec;
2468: PetscInt pStart, pEnd, p, dof;
2473: DMGetDefaultConstraints(dm,&cSec,&cMat);
2474: if (cMat && (mode == INSERT_VALUES || mode == INSERT_ALL_VALUES || mode == INSERT_BC_VALUES)) {
2475: PetscInt nRows;
2477: MatGetSize(cMat,&nRows,NULL);
2478: if (nRows <= 0) return(0);
2479: DMGetLocalSection(dm,§ion);
2480: MatCreateVecs(cMat,NULL,&cVec);
2481: MatMult(cMat,l,cVec);
2482: PetscSectionGetChart(cSec,&pStart,&pEnd);
2483: for (p = pStart; p < pEnd; p++) {
2484: PetscSectionGetDof(cSec,p,&dof);
2485: if (dof) {
2486: PetscScalar *vals;
2487: VecGetValuesSection(cVec,cSec,p,&vals);
2488: VecSetValuesSection(l,section,p,vals,INSERT_ALL_VALUES);
2489: }
2490: }
2491: VecDestroy(&cVec);
2492: }
2493: return(0);
2494: }
2496: /*@
2497: DMGlobalToLocal - update local vectors from global vector
2499: Neighbor-wise Collective on dm
2501: Input Parameters:
2502: + dm - the DM object
2503: . g - the global vector
2504: . mode - INSERT_VALUES or ADD_VALUES
2505: - l - the local vector
2507: Notes:
2508: The communication involved in this update can be overlapped with computation by using
2509: DMGlobalToLocalBegin() and DMGlobalToLocalEnd().
2511: Level: beginner
2513: .seealso DMCoarsen(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMGlobalToLocalEnd(), DMLocalToGlobalBegin(), DMLocalToGlobal(), DMLocalToGlobalBegin(), DMLocalToGlobalEnd()
2515: @*/
2516: PetscErrorCode DMGlobalToLocal(DM dm,Vec g,InsertMode mode,Vec l)
2517: {
2521: DMGlobalToLocalBegin(dm,g,mode,l);
2522: DMGlobalToLocalEnd(dm,g,mode,l);
2523: return(0);
2524: }
2526: /*@
2527: DMGlobalToLocalBegin - Begins updating local vectors from global vector
2529: Neighbor-wise Collective on dm
2531: Input Parameters:
2532: + dm - the DM object
2533: . g - the global vector
2534: . mode - INSERT_VALUES or ADD_VALUES
2535: - l - the local vector
2537: Level: intermediate
2539: .seealso DMCoarsen(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMGlobalToLocal(), DMGlobalToLocalEnd(), DMLocalToGlobalBegin(), DMLocalToGlobal(), DMLocalToGlobalBegin(), DMLocalToGlobalEnd()
2541: @*/
2542: PetscErrorCode DMGlobalToLocalBegin(DM dm,Vec g,InsertMode mode,Vec l)
2543: {
2544: PetscSF sf;
2545: PetscErrorCode ierr;
2546: DMGlobalToLocalHookLink link;
2551: for (link=dm->gtolhook; link; link=link->next) {
2552: if (link->beginhook) {
2553: (*link->beginhook)(dm,g,mode,l,link->ctx);
2554: }
2555: }
2556: DMGetSectionSF(dm, &sf);
2557: if (sf) {
2558: const PetscScalar *gArray;
2559: PetscScalar *lArray;
2560: PetscMemType lmtype,gmtype;
2562: if (mode == ADD_VALUES) SETERRQ1(PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_OUTOFRANGE, "Invalid insertion mode %D", mode);
2563: VecGetArrayAndMemType(l, &lArray, &lmtype);
2564: VecGetArrayReadAndMemType(g, &gArray, &gmtype);
2565: PetscSFBcastWithMemTypeBegin(sf, MPIU_SCALAR, gmtype, gArray, lmtype, lArray, MPI_REPLACE);
2566: VecRestoreArrayAndMemType(l, &lArray);
2567: VecRestoreArrayReadAndMemType(g, &gArray);
2568: } else {
2569: if (!dm->ops->globaltolocalbegin) SETERRQ1(PetscObjectComm((PetscObject)dm), PETSC_ERR_SUP, "Missing DMGlobalToLocalBegin() for type %s",((PetscObject)dm)->type_name);
2570: (*dm->ops->globaltolocalbegin)(dm,g,mode == INSERT_ALL_VALUES ? INSERT_VALUES : (mode == ADD_ALL_VALUES ? ADD_VALUES : mode),l);
2571: }
2572: return(0);
2573: }
2575: /*@
2576: DMGlobalToLocalEnd - Ends updating local vectors from global vector
2578: Neighbor-wise Collective on dm
2580: Input Parameters:
2581: + dm - the DM object
2582: . g - the global vector
2583: . mode - INSERT_VALUES or ADD_VALUES
2584: - l - the local vector
2586: Level: intermediate
2588: .seealso DMCoarsen(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMGlobalToLocal(), DMLocalToGlobalBegin(), DMLocalToGlobal(), DMLocalToGlobalBegin(), DMLocalToGlobalEnd()
2590: @*/
2591: PetscErrorCode DMGlobalToLocalEnd(DM dm,Vec g,InsertMode mode,Vec l)
2592: {
2593: PetscSF sf;
2594: PetscErrorCode ierr;
2595: const PetscScalar *gArray;
2596: PetscScalar *lArray;
2597: PetscBool transform;
2598: DMGlobalToLocalHookLink link;
2599: PetscMemType lmtype,gmtype;
2603: DMGetSectionSF(dm, &sf);
2604: DMHasBasisTransform(dm, &transform);
2605: if (sf) {
2606: if (mode == ADD_VALUES) SETERRQ1(PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_OUTOFRANGE, "Invalid insertion mode %D", mode);
2608: VecGetArrayAndMemType(l, &lArray, &lmtype);
2609: VecGetArrayReadAndMemType(g, &gArray, &gmtype);
2610: PetscSFBcastEnd(sf, MPIU_SCALAR, gArray, lArray,MPI_REPLACE);
2611: VecRestoreArrayAndMemType(l, &lArray);
2612: VecRestoreArrayReadAndMemType(g, &gArray);
2613: if (transform) {DMPlexGlobalToLocalBasis(dm, l);}
2614: } else {
2615: if (!dm->ops->globaltolocalend) SETERRQ1(PetscObjectComm((PetscObject)dm), PETSC_ERR_SUP, "Missing DMGlobalToLocalEnd() for type %s",((PetscObject)dm)->type_name);
2616: (*dm->ops->globaltolocalend)(dm,g,mode == INSERT_ALL_VALUES ? INSERT_VALUES : (mode == ADD_ALL_VALUES ? ADD_VALUES : mode),l);
2617: }
2618: DMGlobalToLocalHook_Constraints(dm,g,mode,l,NULL);
2619: for (link=dm->gtolhook; link; link=link->next) {
2620: if (link->endhook) {(*link->endhook)(dm,g,mode,l,link->ctx);}
2621: }
2622: return(0);
2623: }
2625: /*@C
2626: DMLocalToGlobalHookAdd - adds a callback to be run when a local to global is called
2628: Logically Collective
2630: Input Arguments:
2631: + dm - the DM
2632: . beginhook - function to run at the beginning of DMLocalToGlobalBegin()
2633: . endhook - function to run after DMLocalToGlobalEnd() has completed
2634: - ctx - [optional] user-defined context for provide data for the hooks (may be NULL)
2636: Calling sequence for beginhook:
2637: $ beginhook(DM fine,Vec l,InsertMode mode,Vec g,void *ctx)
2639: + dm - global DM
2640: . l - local vector
2641: . mode - mode
2642: . g - global vector
2643: - ctx - optional user-defined function context
2646: Calling sequence for endhook:
2647: $ endhook(DM fine,Vec l,InsertMode mode,Vec g,void *ctx)
2649: + global - global DM
2650: . l - local vector
2651: . mode - mode
2652: . g - global vector
2653: - ctx - optional user-defined function context
2655: Level: advanced
2657: .seealso: DMRefineHookAdd(), SNESFASGetInterpolation(), SNESFASGetInjection(), PetscObjectCompose(), PetscContainerCreate()
2658: @*/
2659: PetscErrorCode DMLocalToGlobalHookAdd(DM dm,PetscErrorCode (*beginhook)(DM,Vec,InsertMode,Vec,void*),PetscErrorCode (*endhook)(DM,Vec,InsertMode,Vec,void*),void *ctx)
2660: {
2661: PetscErrorCode ierr;
2662: DMLocalToGlobalHookLink link,*p;
2666: for (p=&dm->ltoghook; *p; p=&(*p)->next) {} /* Scan to the end of the current list of hooks */
2667: PetscNew(&link);
2668: link->beginhook = beginhook;
2669: link->endhook = endhook;
2670: link->ctx = ctx;
2671: link->next = NULL;
2672: *p = link;
2673: return(0);
2674: }
2676: static PetscErrorCode DMLocalToGlobalHook_Constraints(DM dm, Vec l, InsertMode mode, Vec g, void *ctx)
2677: {
2678: Mat cMat;
2679: Vec cVec;
2680: PetscSection section, cSec;
2681: PetscInt pStart, pEnd, p, dof;
2686: DMGetDefaultConstraints(dm,&cSec,&cMat);
2687: if (cMat && (mode == ADD_VALUES || mode == ADD_ALL_VALUES || mode == ADD_BC_VALUES)) {
2688: PetscInt nRows;
2690: MatGetSize(cMat,&nRows,NULL);
2691: if (nRows <= 0) return(0);
2692: DMGetLocalSection(dm,§ion);
2693: MatCreateVecs(cMat,NULL,&cVec);
2694: PetscSectionGetChart(cSec,&pStart,&pEnd);
2695: for (p = pStart; p < pEnd; p++) {
2696: PetscSectionGetDof(cSec,p,&dof);
2697: if (dof) {
2698: PetscInt d;
2699: PetscScalar *vals;
2700: VecGetValuesSection(l,section,p,&vals);
2701: VecSetValuesSection(cVec,cSec,p,vals,mode);
2702: /* for this to be the true transpose, we have to zero the values that
2703: * we just extracted */
2704: for (d = 0; d < dof; d++) {
2705: vals[d] = 0.;
2706: }
2707: }
2708: }
2709: MatMultTransposeAdd(cMat,cVec,l,l);
2710: VecDestroy(&cVec);
2711: }
2712: return(0);
2713: }
2714: /*@
2715: DMLocalToGlobal - updates global vectors from local vectors
2717: Neighbor-wise Collective on dm
2719: Input Parameters:
2720: + dm - the DM object
2721: . l - the local vector
2722: . mode - if INSERT_VALUES then no parallel communication is used, if ADD_VALUES then all ghost points from the same base point accumulate into that base point.
2723: - g - the global vector
2725: Notes:
2726: The communication involved in this update can be overlapped with computation by using
2727: DMLocalToGlobalBegin() and DMLocalToGlobalEnd().
2729: In the ADD_VALUES case you normally would zero the receiving vector before beginning this operation.
2730: INSERT_VALUES is not supported for DMDA; in that case simply compute the values directly into a global vector instead of a local one.
2732: Level: beginner
2734: .seealso DMLocalToGlobalBegin(), DMLocalToGlobalEnd(), DMCoarsen(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMGlobalToLocal(), DMGlobalToLocalEnd(), DMGlobalToLocalBegin()
2736: @*/
2737: PetscErrorCode DMLocalToGlobal(DM dm,Vec l,InsertMode mode,Vec g)
2738: {
2742: DMLocalToGlobalBegin(dm,l,mode,g);
2743: DMLocalToGlobalEnd(dm,l,mode,g);
2744: return(0);
2745: }
2747: /*@
2748: DMLocalToGlobalBegin - begins updating global vectors from local vectors
2750: Neighbor-wise Collective on dm
2752: Input Parameters:
2753: + dm - the DM object
2754: . l - the local vector
2755: . mode - if INSERT_VALUES then no parallel communication is used, if ADD_VALUES then all ghost points from the same base point accumulate into that base point.
2756: - g - the global vector
2758: Notes:
2759: In the ADD_VALUES case you normally would zero the receiving vector before beginning this operation.
2760: INSERT_VALUES is not supported for DMDA, in that case simply compute the values directly into a global vector instead of a local one.
2762: Level: intermediate
2764: .seealso DMLocalToGlobal(), DMLocalToGlobalEnd(), DMCoarsen(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMGlobalToLocal(), DMGlobalToLocalEnd(), DMGlobalToLocalBegin()
2766: @*/
2767: PetscErrorCode DMLocalToGlobalBegin(DM dm,Vec l,InsertMode mode,Vec g)
2768: {
2769: PetscSF sf;
2770: PetscSection s, gs;
2771: DMLocalToGlobalHookLink link;
2772: Vec tmpl;
2773: const PetscScalar *lArray;
2774: PetscScalar *gArray;
2775: PetscBool isInsert, transform, l_inplace = PETSC_FALSE, g_inplace = PETSC_FALSE;
2776: PetscErrorCode ierr;
2777: PetscMemType lmtype=PETSC_MEMTYPE_HOST,gmtype=PETSC_MEMTYPE_HOST;
2781: for (link=dm->ltoghook; link; link=link->next) {
2782: if (link->beginhook) {
2783: (*link->beginhook)(dm,l,mode,g,link->ctx);
2784: }
2785: }
2786: DMLocalToGlobalHook_Constraints(dm,l,mode,g,NULL);
2787: DMGetSectionSF(dm, &sf);
2788: DMGetLocalSection(dm, &s);
2789: switch (mode) {
2790: case INSERT_VALUES:
2791: case INSERT_ALL_VALUES:
2792: case INSERT_BC_VALUES:
2793: isInsert = PETSC_TRUE; break;
2794: case ADD_VALUES:
2795: case ADD_ALL_VALUES:
2796: case ADD_BC_VALUES:
2797: isInsert = PETSC_FALSE; break;
2798: default:
2799: SETERRQ1(PetscObjectComm((PetscObject) dm), PETSC_ERR_ARG_OUTOFRANGE, "Invalid insertion mode %D", mode);
2800: }
2801: if ((sf && !isInsert) || (s && isInsert)) {
2802: DMHasBasisTransform(dm, &transform);
2803: if (transform) {
2804: DMGetNamedLocalVector(dm, "__petsc_dm_transform_local_copy", &tmpl);
2805: VecCopy(l, tmpl);
2806: DMPlexLocalToGlobalBasis(dm, tmpl);
2807: VecGetArrayRead(tmpl, &lArray);
2808: } else if (isInsert) {
2809: VecGetArrayRead(l, &lArray);
2810: } else {
2811: VecGetArrayReadAndMemType(l, &lArray, &lmtype);
2812: l_inplace = PETSC_TRUE;
2813: }
2814: if (s && isInsert) {
2815: VecGetArray(g, &gArray);
2816: } else {
2817: VecGetArrayAndMemType(g, &gArray, &gmtype);
2818: g_inplace = PETSC_TRUE;
2819: }
2820: if (sf && !isInsert) {
2821: PetscSFReduceWithMemTypeBegin(sf, MPIU_SCALAR, lmtype, lArray, gmtype, gArray, MPIU_SUM);
2822: } else if (s && isInsert) {
2823: PetscInt gStart, pStart, pEnd, p;
2825: DMGetGlobalSection(dm, &gs);
2826: PetscSectionGetChart(s, &pStart, &pEnd);
2827: VecGetOwnershipRange(g, &gStart, NULL);
2828: for (p = pStart; p < pEnd; ++p) {
2829: PetscInt dof, gdof, cdof, gcdof, off, goff, d, e;
2831: PetscSectionGetDof(s, p, &dof);
2832: PetscSectionGetDof(gs, p, &gdof);
2833: PetscSectionGetConstraintDof(s, p, &cdof);
2834: PetscSectionGetConstraintDof(gs, p, &gcdof);
2835: PetscSectionGetOffset(s, p, &off);
2836: PetscSectionGetOffset(gs, p, &goff);
2837: /* Ignore off-process data and points with no global data */
2838: if (!gdof || goff < 0) continue;
2839: if (dof != gdof) SETERRQ5(PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "Inconsistent sizes, p: %d dof: %d gdof: %d cdof: %d gcdof: %d", p, dof, gdof, cdof, gcdof);
2840: /* If no constraints are enforced in the global vector */
2841: if (!gcdof) {
2842: for (d = 0; d < dof; ++d) gArray[goff-gStart+d] = lArray[off+d];
2843: /* If constraints are enforced in the global vector */
2844: } else if (cdof == gcdof) {
2845: const PetscInt *cdofs;
2846: PetscInt cind = 0;
2848: PetscSectionGetConstraintIndices(s, p, &cdofs);
2849: for (d = 0, e = 0; d < dof; ++d) {
2850: if ((cind < cdof) && (d == cdofs[cind])) {++cind; continue;}
2851: gArray[goff-gStart+e++] = lArray[off+d];
2852: }
2853: } else SETERRQ5(PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "Inconsistent sizes, p: %d dof: %d gdof: %d cdof: %d gcdof: %d", p, dof, gdof, cdof, gcdof);
2854: }
2855: }
2856: if (g_inplace) {
2857: VecRestoreArrayAndMemType(g, &gArray);
2858: } else {
2859: VecRestoreArray(g, &gArray);
2860: }
2861: if (transform) {
2862: VecRestoreArrayRead(tmpl, &lArray);
2863: DMRestoreNamedLocalVector(dm, "__petsc_dm_transform_local_copy", &tmpl);
2864: } else if (l_inplace) {
2865: VecRestoreArrayReadAndMemType(l, &lArray);
2866: } else {
2867: VecRestoreArrayRead(l, &lArray);
2868: }
2869: } else {
2870: if (!dm->ops->localtoglobalbegin) SETERRQ1(PetscObjectComm((PetscObject)dm), PETSC_ERR_SUP, "Missing DMLocalToGlobalBegin() for type %s",((PetscObject)dm)->type_name);
2871: (*dm->ops->localtoglobalbegin)(dm,l,mode == INSERT_ALL_VALUES ? INSERT_VALUES : (mode == ADD_ALL_VALUES ? ADD_VALUES : mode),g);
2872: }
2873: return(0);
2874: }
2876: /*@
2877: DMLocalToGlobalEnd - updates global vectors from local vectors
2879: Neighbor-wise Collective on dm
2881: Input Parameters:
2882: + dm - the DM object
2883: . l - the local vector
2884: . mode - INSERT_VALUES or ADD_VALUES
2885: - g - the global vector
2887: Level: intermediate
2889: .seealso DMCoarsen(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMGlobalToLocalEnd(), DMGlobalToLocalEnd()
2891: @*/
2892: PetscErrorCode DMLocalToGlobalEnd(DM dm,Vec l,InsertMode mode,Vec g)
2893: {
2894: PetscSF sf;
2895: PetscSection s;
2896: DMLocalToGlobalHookLink link;
2897: PetscBool isInsert, transform;
2898: PetscErrorCode ierr;
2902: DMGetSectionSF(dm, &sf);
2903: DMGetLocalSection(dm, &s);
2904: switch (mode) {
2905: case INSERT_VALUES:
2906: case INSERT_ALL_VALUES:
2907: isInsert = PETSC_TRUE; break;
2908: case ADD_VALUES:
2909: case ADD_ALL_VALUES:
2910: isInsert = PETSC_FALSE; break;
2911: default:
2912: SETERRQ1(PetscObjectComm((PetscObject) dm), PETSC_ERR_ARG_OUTOFRANGE, "Invalid insertion mode %D", mode);
2913: }
2914: if (sf && !isInsert) {
2915: const PetscScalar *lArray;
2916: PetscScalar *gArray;
2917: Vec tmpl;
2919: DMHasBasisTransform(dm, &transform);
2920: if (transform) {
2921: DMGetNamedLocalVector(dm, "__petsc_dm_transform_local_copy", &tmpl);
2922: VecGetArrayRead(tmpl, &lArray);
2923: } else {
2924: VecGetArrayReadAndMemType(l, &lArray, NULL);
2925: }
2926: VecGetArrayAndMemType(g, &gArray, NULL);
2927: PetscSFReduceEnd(sf, MPIU_SCALAR, lArray, gArray, MPIU_SUM);
2928: if (transform) {
2929: VecRestoreArrayRead(tmpl, &lArray);
2930: DMRestoreNamedLocalVector(dm, "__petsc_dm_transform_local_copy", &tmpl);
2931: } else {
2932: VecRestoreArrayReadAndMemType(l, &lArray);
2933: }
2934: VecRestoreArrayAndMemType(g, &gArray);
2935: } else if (s && isInsert) {
2936: } else {
2937: if (!dm->ops->localtoglobalend) SETERRQ1(PetscObjectComm((PetscObject)dm), PETSC_ERR_SUP, "Missing DMLocalToGlobalEnd() for type %s",((PetscObject)dm)->type_name);
2938: (*dm->ops->localtoglobalend)(dm,l,mode == INSERT_ALL_VALUES ? INSERT_VALUES : (mode == ADD_ALL_VALUES ? ADD_VALUES : mode),g);
2939: }
2940: for (link=dm->ltoghook; link; link=link->next) {
2941: if (link->endhook) {(*link->endhook)(dm,g,mode,l,link->ctx);}
2942: }
2943: return(0);
2944: }
2946: /*@
2947: DMLocalToLocalBegin - Maps from a local vector (including ghost points
2948: that contain irrelevant values) to another local vector where the ghost
2949: points in the second are set correctly. Must be followed by DMLocalToLocalEnd().
2951: Neighbor-wise Collective on dm
2953: Input Parameters:
2954: + dm - the DM object
2955: . g - the original local vector
2956: - mode - one of INSERT_VALUES or ADD_VALUES
2958: Output Parameter:
2959: . l - the local vector with correct ghost values
2961: Level: intermediate
2963: Notes:
2964: The local vectors used here need not be the same as those
2965: obtained from DMCreateLocalVector(), BUT they
2966: must have the same parallel data layout; they could, for example, be
2967: obtained with VecDuplicate() from the DM originating vectors.
2969: .seealso DMCoarsen(), DMDestroy(), DMView(), DMCreateLocalVector(), DMCreateGlobalVector(), DMCreateInterpolation(), DMLocalToLocalEnd(), DMGlobalToLocalEnd(), DMLocalToGlobalBegin()
2971: @*/
2972: PetscErrorCode DMLocalToLocalBegin(DM dm,Vec g,InsertMode mode,Vec l)
2973: {
2974: PetscErrorCode ierr;
2978: if (!dm->ops->localtolocalbegin) SETERRQ(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"This DM does not support local to local maps");
2979: (*dm->ops->localtolocalbegin)(dm,g,mode == INSERT_ALL_VALUES ? INSERT_VALUES : (mode == ADD_ALL_VALUES ? ADD_VALUES : mode),l);
2980: return(0);
2981: }
2983: /*@
2984: DMLocalToLocalEnd - Maps from a local vector (including ghost points
2985: that contain irrelevant values) to another local vector where the ghost
2986: points in the second are set correctly. Must be preceded by DMLocalToLocalBegin().
2988: Neighbor-wise Collective on dm
2990: Input Parameters:
2991: + da - the DM object
2992: . g - the original local vector
2993: - mode - one of INSERT_VALUES or ADD_VALUES
2995: Output Parameter:
2996: . l - the local vector with correct ghost values
2998: Level: intermediate
3000: Notes:
3001: The local vectors used here need not be the same as those
3002: obtained from DMCreateLocalVector(), BUT they
3003: must have the same parallel data layout; they could, for example, be
3004: obtained with VecDuplicate() from the DM originating vectors.
3006: .seealso DMCoarsen(), DMDestroy(), DMView(), DMCreateLocalVector(), DMCreateGlobalVector(), DMCreateInterpolation(), DMLocalToLocalBegin(), DMGlobalToLocalEnd(), DMLocalToGlobalBegin()
3008: @*/
3009: PetscErrorCode DMLocalToLocalEnd(DM dm,Vec g,InsertMode mode,Vec l)
3010: {
3011: PetscErrorCode ierr;
3015: if (!dm->ops->localtolocalend) SETERRQ(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"This DM does not support local to local maps");
3016: (*dm->ops->localtolocalend)(dm,g,mode == INSERT_ALL_VALUES ? INSERT_VALUES : (mode == ADD_ALL_VALUES ? ADD_VALUES : mode),l);
3017: return(0);
3018: }
3021: /*@
3022: DMCoarsen - Coarsens a DM object
3024: Collective on dm
3026: Input Parameter:
3027: + dm - the DM object
3028: - comm - the communicator to contain the new DM object (or MPI_COMM_NULL)
3030: Output Parameter:
3031: . dmc - the coarsened DM
3033: Level: developer
3035: .seealso DMRefine(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation()
3037: @*/
3038: PetscErrorCode DMCoarsen(DM dm, MPI_Comm comm, DM *dmc)
3039: {
3040: PetscErrorCode ierr;
3041: DMCoarsenHookLink link;
3045: if (!dm->ops->coarsen) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMCoarsen",((PetscObject)dm)->type_name);
3046: PetscLogEventBegin(DM_Coarsen,dm,0,0,0);
3047: (*dm->ops->coarsen)(dm, comm, dmc);
3048: if (*dmc) {
3049: DMSetCoarseDM(dm,*dmc);
3050: (*dmc)->ops->creatematrix = dm->ops->creatematrix;
3051: PetscObjectCopyFortranFunctionPointers((PetscObject)dm,(PetscObject)*dmc);
3052: (*dmc)->ctx = dm->ctx;
3053: (*dmc)->levelup = dm->levelup;
3054: (*dmc)->leveldown = dm->leveldown + 1;
3055: DMSetMatType(*dmc,dm->mattype);
3056: for (link=dm->coarsenhook; link; link=link->next) {
3057: if (link->coarsenhook) {(*link->coarsenhook)(dm,*dmc,link->ctx);}
3058: }
3059: }
3060: PetscLogEventEnd(DM_Coarsen,dm,0,0,0);
3061: if (!(*dmc)) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "NULL coarse mesh produced");
3062: return(0);
3063: }
3065: /*@C
3066: DMCoarsenHookAdd - adds a callback to be run when restricting a nonlinear problem to the coarse grid
3068: Logically Collective
3070: Input Arguments:
3071: + fine - nonlinear solver context on which to run a hook when restricting to a coarser level
3072: . coarsenhook - function to run when setting up a coarser level
3073: . restricthook - function to run to update data on coarser levels (once per SNESSolve())
3074: - ctx - [optional] user-defined context for provide data for the hooks (may be NULL)
3076: Calling sequence of coarsenhook:
3077: $ coarsenhook(DM fine,DM coarse,void *ctx);
3079: + fine - fine level DM
3080: . coarse - coarse level DM to restrict problem to
3081: - ctx - optional user-defined function context
3083: Calling sequence for restricthook:
3084: $ restricthook(DM fine,Mat mrestrict,Vec rscale,Mat inject,DM coarse,void *ctx)
3086: + fine - fine level DM
3087: . mrestrict - matrix restricting a fine-level solution to the coarse grid
3088: . rscale - scaling vector for restriction
3089: . inject - matrix restricting by injection
3090: . coarse - coarse level DM to update
3091: - ctx - optional user-defined function context
3093: Level: advanced
3095: Notes:
3096: This function is only needed if auxiliary data needs to be set up on coarse grids.
3098: If this function is called multiple times, the hooks will be run in the order they are added.
3100: In order to compose with nonlinear preconditioning without duplicating storage, the hook should be implemented to
3101: extract the finest level information from its context (instead of from the SNES).
3103: This function is currently not available from Fortran.
3105: .seealso: DMCoarsenHookRemove(), DMRefineHookAdd(), SNESFASGetInterpolation(), SNESFASGetInjection(), PetscObjectCompose(), PetscContainerCreate()
3106: @*/
3107: PetscErrorCode DMCoarsenHookAdd(DM fine,PetscErrorCode (*coarsenhook)(DM,DM,void*),PetscErrorCode (*restricthook)(DM,Mat,Vec,Mat,DM,void*),void *ctx)
3108: {
3109: PetscErrorCode ierr;
3110: DMCoarsenHookLink link,*p;
3114: for (p=&fine->coarsenhook; *p; p=&(*p)->next) { /* Scan to the end of the current list of hooks */
3115: if ((*p)->coarsenhook == coarsenhook && (*p)->restricthook == restricthook && (*p)->ctx == ctx) return(0);
3116: }
3117: PetscNew(&link);
3118: link->coarsenhook = coarsenhook;
3119: link->restricthook = restricthook;
3120: link->ctx = ctx;
3121: link->next = NULL;
3122: *p = link;
3123: return(0);
3124: }
3126: /*@C
3127: DMCoarsenHookRemove - remove a callback from the list of hooks to be run when restricting a nonlinear problem to the coarse grid
3129: Logically Collective
3131: Input Arguments:
3132: + fine - nonlinear solver context on which to run a hook when restricting to a coarser level
3133: . coarsenhook - function to run when setting up a coarser level
3134: . restricthook - function to run to update data on coarser levels (once per SNESSolve())
3135: - ctx - [optional] user-defined context for provide data for the hooks (may be NULL)
3137: Level: advanced
3139: Notes:
3140: This function does nothing if the hook is not in the list.
3142: This function is currently not available from Fortran.
3144: .seealso: DMCoarsenHookAdd(), DMRefineHookAdd(), SNESFASGetInterpolation(), SNESFASGetInjection(), PetscObjectCompose(), PetscContainerCreate()
3145: @*/
3146: PetscErrorCode DMCoarsenHookRemove(DM fine,PetscErrorCode (*coarsenhook)(DM,DM,void*),PetscErrorCode (*restricthook)(DM,Mat,Vec,Mat,DM,void*),void *ctx)
3147: {
3148: PetscErrorCode ierr;
3149: DMCoarsenHookLink link,*p;
3153: for (p=&fine->coarsenhook; *p; p=&(*p)->next) { /* Search the list of current hooks */
3154: if ((*p)->coarsenhook == coarsenhook && (*p)->restricthook == restricthook && (*p)->ctx == ctx) {
3155: link = *p;
3156: *p = link->next;
3157: PetscFree(link);
3158: break;
3159: }
3160: }
3161: return(0);
3162: }
3165: /*@
3166: DMRestrict - restricts user-defined problem data to a coarser DM by running hooks registered by DMCoarsenHookAdd()
3168: Collective if any hooks are
3170: Input Arguments:
3171: + fine - finer DM to use as a base
3172: . restrct - restriction matrix, apply using MatRestrict()
3173: . rscale - scaling vector for restriction
3174: . inject - injection matrix, also use MatRestrict()
3175: - coarse - coarser DM to update
3177: Level: developer
3179: .seealso: DMCoarsenHookAdd(), MatRestrict()
3180: @*/
3181: PetscErrorCode DMRestrict(DM fine,Mat restrct,Vec rscale,Mat inject,DM coarse)
3182: {
3183: PetscErrorCode ierr;
3184: DMCoarsenHookLink link;
3187: for (link=fine->coarsenhook; link; link=link->next) {
3188: if (link->restricthook) {
3189: (*link->restricthook)(fine,restrct,rscale,inject,coarse,link->ctx);
3190: }
3191: }
3192: return(0);
3193: }
3195: /*@C
3196: DMSubDomainHookAdd - adds a callback to be run when restricting a problem to the coarse grid
3198: Logically Collective on global
3200: Input Arguments:
3201: + global - global DM
3202: . ddhook - function to run to pass data to the decomposition DM upon its creation
3203: . restricthook - function to run to update data on block solve (at the beginning of the block solve)
3204: - ctx - [optional] user-defined context for provide data for the hooks (may be NULL)
3207: Calling sequence for ddhook:
3208: $ ddhook(DM global,DM block,void *ctx)
3210: + global - global DM
3211: . block - block DM
3212: - ctx - optional user-defined function context
3214: Calling sequence for restricthook:
3215: $ restricthook(DM global,VecScatter out,VecScatter in,DM block,void *ctx)
3217: + global - global DM
3218: . out - scatter to the outer (with ghost and overlap points) block vector
3219: . in - scatter to block vector values only owned locally
3220: . block - block DM
3221: - ctx - optional user-defined function context
3223: Level: advanced
3225: Notes:
3226: This function is only needed if auxiliary data needs to be set up on subdomain DMs.
3228: If this function is called multiple times, the hooks will be run in the order they are added.
3230: In order to compose with nonlinear preconditioning without duplicating storage, the hook should be implemented to
3231: extract the global information from its context (instead of from the SNES).
3233: This function is currently not available from Fortran.
3235: .seealso: DMRefineHookAdd(), SNESFASGetInterpolation(), SNESFASGetInjection(), PetscObjectCompose(), PetscContainerCreate()
3236: @*/
3237: PetscErrorCode DMSubDomainHookAdd(DM global,PetscErrorCode (*ddhook)(DM,DM,void*),PetscErrorCode (*restricthook)(DM,VecScatter,VecScatter,DM,void*),void *ctx)
3238: {
3239: PetscErrorCode ierr;
3240: DMSubDomainHookLink link,*p;
3244: for (p=&global->subdomainhook; *p; p=&(*p)->next) { /* Scan to the end of the current list of hooks */
3245: if ((*p)->ddhook == ddhook && (*p)->restricthook == restricthook && (*p)->ctx == ctx) return(0);
3246: }
3247: PetscNew(&link);
3248: link->restricthook = restricthook;
3249: link->ddhook = ddhook;
3250: link->ctx = ctx;
3251: link->next = NULL;
3252: *p = link;
3253: return(0);
3254: }
3256: /*@C
3257: DMSubDomainHookRemove - remove a callback from the list to be run when restricting a problem to the coarse grid
3259: Logically Collective
3261: Input Arguments:
3262: + global - global DM
3263: . ddhook - function to run to pass data to the decomposition DM upon its creation
3264: . restricthook - function to run to update data on block solve (at the beginning of the block solve)
3265: - ctx - [optional] user-defined context for provide data for the hooks (may be NULL)
3267: Level: advanced
3269: Notes:
3271: This function is currently not available from Fortran.
3273: .seealso: DMSubDomainHookAdd(), SNESFASGetInterpolation(), SNESFASGetInjection(), PetscObjectCompose(), PetscContainerCreate()
3274: @*/
3275: PetscErrorCode DMSubDomainHookRemove(DM global,PetscErrorCode (*ddhook)(DM,DM,void*),PetscErrorCode (*restricthook)(DM,VecScatter,VecScatter,DM,void*),void *ctx)
3276: {
3277: PetscErrorCode ierr;
3278: DMSubDomainHookLink link,*p;
3282: for (p=&global->subdomainhook; *p; p=&(*p)->next) { /* Search the list of current hooks */
3283: if ((*p)->ddhook == ddhook && (*p)->restricthook == restricthook && (*p)->ctx == ctx) {
3284: link = *p;
3285: *p = link->next;
3286: PetscFree(link);
3287: break;
3288: }
3289: }
3290: return(0);
3291: }
3293: /*@
3294: DMSubDomainRestrict - restricts user-defined problem data to a block DM by running hooks registered by DMSubDomainHookAdd()
3296: Collective if any hooks are
3298: Input Arguments:
3299: + fine - finer DM to use as a base
3300: . oscatter - scatter from domain global vector filling subdomain global vector with overlap
3301: . gscatter - scatter from domain global vector filling subdomain local vector with ghosts
3302: - coarse - coarer DM to update
3304: Level: developer
3306: .seealso: DMCoarsenHookAdd(), MatRestrict()
3307: @*/
3308: PetscErrorCode DMSubDomainRestrict(DM global,VecScatter oscatter,VecScatter gscatter,DM subdm)
3309: {
3310: PetscErrorCode ierr;
3311: DMSubDomainHookLink link;
3314: for (link=global->subdomainhook; link; link=link->next) {
3315: if (link->restricthook) {
3316: (*link->restricthook)(global,oscatter,gscatter,subdm,link->ctx);
3317: }
3318: }
3319: return(0);
3320: }
3322: /*@
3323: DMGetCoarsenLevel - Get's the number of coarsenings that have generated this DM.
3325: Not Collective
3327: Input Parameter:
3328: . dm - the DM object
3330: Output Parameter:
3331: . level - number of coarsenings
3333: Level: developer
3335: .seealso DMCoarsen(), DMGetRefineLevel(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation()
3337: @*/
3338: PetscErrorCode DMGetCoarsenLevel(DM dm,PetscInt *level)
3339: {
3343: *level = dm->leveldown;
3344: return(0);
3345: }
3347: /*@
3348: DMSetCoarsenLevel - Sets the number of coarsenings that have generated this DM.
3350: Not Collective
3352: Input Parameters:
3353: + dm - the DM object
3354: - level - number of coarsenings
3356: Level: developer
3358: .seealso DMCoarsen(), DMGetCoarsenLevel(), DMGetRefineLevel(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation()
3359: @*/
3360: PetscErrorCode DMSetCoarsenLevel(DM dm,PetscInt level)
3361: {
3364: dm->leveldown = level;
3365: return(0);
3366: }
3370: /*@C
3371: DMRefineHierarchy - Refines a DM object, all levels at once
3373: Collective on dm
3375: Input Parameter:
3376: + dm - the DM object
3377: - nlevels - the number of levels of refinement
3379: Output Parameter:
3380: . dmf - the refined DM hierarchy
3382: Level: developer
3384: .seealso DMCoarsenHierarchy(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation()
3386: @*/
3387: PetscErrorCode DMRefineHierarchy(DM dm,PetscInt nlevels,DM dmf[])
3388: {
3393: if (nlevels < 0) SETERRQ(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_OUTOFRANGE,"nlevels cannot be negative");
3394: if (nlevels == 0) return(0);
3396: if (dm->ops->refinehierarchy) {
3397: (*dm->ops->refinehierarchy)(dm,nlevels,dmf);
3398: } else if (dm->ops->refine) {
3399: PetscInt i;
3401: DMRefine(dm,PetscObjectComm((PetscObject)dm),&dmf[0]);
3402: for (i=1; i<nlevels; i++) {
3403: DMRefine(dmf[i-1],PetscObjectComm((PetscObject)dm),&dmf[i]);
3404: }
3405: } else SETERRQ(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"No RefineHierarchy for this DM yet");
3406: return(0);
3407: }
3409: /*@C
3410: DMCoarsenHierarchy - Coarsens a DM object, all levels at once
3412: Collective on dm
3414: Input Parameter:
3415: + dm - the DM object
3416: - nlevels - the number of levels of coarsening
3418: Output Parameter:
3419: . dmc - the coarsened DM hierarchy
3421: Level: developer
3423: .seealso DMRefineHierarchy(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation()
3425: @*/
3426: PetscErrorCode DMCoarsenHierarchy(DM dm, PetscInt nlevels, DM dmc[])
3427: {
3432: if (nlevels < 0) SETERRQ(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_OUTOFRANGE,"nlevels cannot be negative");
3433: if (nlevels == 0) return(0);
3435: if (dm->ops->coarsenhierarchy) {
3436: (*dm->ops->coarsenhierarchy)(dm, nlevels, dmc);
3437: } else if (dm->ops->coarsen) {
3438: PetscInt i;
3440: DMCoarsen(dm,PetscObjectComm((PetscObject)dm),&dmc[0]);
3441: for (i=1; i<nlevels; i++) {
3442: DMCoarsen(dmc[i-1],PetscObjectComm((PetscObject)dm),&dmc[i]);
3443: }
3444: } else SETERRQ(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"No CoarsenHierarchy for this DM yet");
3445: return(0);
3446: }
3448: /*@C
3449: DMSetApplicationContextDestroy - Sets a user function that will be called to destroy the application context when the DM is destroyed
3451: Not Collective
3453: Input Parameters:
3454: + dm - the DM object
3455: - destroy - the destroy function
3457: Level: intermediate
3459: .seealso DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMGetApplicationContext()
3461: @*/
3462: PetscErrorCode DMSetApplicationContextDestroy(DM dm,PetscErrorCode (*destroy)(void**))
3463: {
3466: dm->ctxdestroy = destroy;
3467: return(0);
3468: }
3470: /*@
3471: DMSetApplicationContext - Set a user context into a DM object
3473: Not Collective
3475: Input Parameters:
3476: + dm - the DM object
3477: - ctx - the user context
3479: Level: intermediate
3481: .seealso DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMGetApplicationContext()
3483: @*/
3484: PetscErrorCode DMSetApplicationContext(DM dm,void *ctx)
3485: {
3488: dm->ctx = ctx;
3489: return(0);
3490: }
3492: /*@
3493: DMGetApplicationContext - Gets a user context from a DM object
3495: Not Collective
3497: Input Parameter:
3498: . dm - the DM object
3500: Output Parameter:
3501: . ctx - the user context
3503: Level: intermediate
3505: .seealso DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMGetApplicationContext()
3507: @*/
3508: PetscErrorCode DMGetApplicationContext(DM dm,void *ctx)
3509: {
3512: *(void**)ctx = dm->ctx;
3513: return(0);
3514: }
3516: /*@C
3517: DMSetVariableBounds - sets a function to compute the lower and upper bound vectors for SNESVI.
3519: Logically Collective on dm
3521: Input Parameter:
3522: + dm - the DM object
3523: - f - the function that computes variable bounds used by SNESVI (use NULL to cancel a previous function that was set)
3525: Level: intermediate
3527: .seealso DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMGetApplicationContext(),
3528: DMSetJacobian()
3530: @*/
3531: PetscErrorCode DMSetVariableBounds(DM dm,PetscErrorCode (*f)(DM,Vec,Vec))
3532: {
3535: dm->ops->computevariablebounds = f;
3536: return(0);
3537: }
3539: /*@
3540: DMHasVariableBounds - does the DM object have a variable bounds function?
3542: Not Collective
3544: Input Parameter:
3545: . dm - the DM object to destroy
3547: Output Parameter:
3548: . flg - PETSC_TRUE if the variable bounds function exists
3550: Level: developer
3552: .seealso DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMGetApplicationContext()
3554: @*/
3555: PetscErrorCode DMHasVariableBounds(DM dm,PetscBool *flg)
3556: {
3560: *flg = (dm->ops->computevariablebounds) ? PETSC_TRUE : PETSC_FALSE;
3561: return(0);
3562: }
3564: /*@C
3565: DMComputeVariableBounds - compute variable bounds used by SNESVI.
3567: Logically Collective on dm
3569: Input Parameters:
3570: . dm - the DM object
3572: Output parameters:
3573: + xl - lower bound
3574: - xu - upper bound
3576: Level: advanced
3578: Notes:
3579: This is generally not called by users. It calls the function provided by the user with DMSetVariableBounds()
3581: .seealso DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMGetApplicationContext()
3583: @*/
3584: PetscErrorCode DMComputeVariableBounds(DM dm, Vec xl, Vec xu)
3585: {
3592: if (!dm->ops->computevariablebounds) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMComputeVariableBounds",((PetscObject)dm)->type_name);
3593: (*dm->ops->computevariablebounds)(dm, xl,xu);
3594: return(0);
3595: }
3597: /*@
3598: DMHasColoring - does the DM object have a method of providing a coloring?
3600: Not Collective
3602: Input Parameter:
3603: . dm - the DM object
3605: Output Parameter:
3606: . flg - PETSC_TRUE if the DM has facilities for DMCreateColoring().
3608: Level: developer
3610: .seealso DMCreateColoring()
3612: @*/
3613: PetscErrorCode DMHasColoring(DM dm,PetscBool *flg)
3614: {
3618: *flg = (dm->ops->getcoloring) ? PETSC_TRUE : PETSC_FALSE;
3619: return(0);
3620: }
3622: /*@
3623: DMHasCreateRestriction - does the DM object have a method of providing a restriction?
3625: Not Collective
3627: Input Parameter:
3628: . dm - the DM object
3630: Output Parameter:
3631: . flg - PETSC_TRUE if the DM has facilities for DMCreateRestriction().
3633: Level: developer
3635: .seealso DMCreateRestriction()
3637: @*/
3638: PetscErrorCode DMHasCreateRestriction(DM dm,PetscBool *flg)
3639: {
3643: *flg = (dm->ops->createrestriction) ? PETSC_TRUE : PETSC_FALSE;
3644: return(0);
3645: }
3648: /*@
3649: DMHasCreateInjection - does the DM object have a method of providing an injection?
3651: Not Collective
3653: Input Parameter:
3654: . dm - the DM object
3656: Output Parameter:
3657: . flg - PETSC_TRUE if the DM has facilities for DMCreateInjection().
3659: Level: developer
3661: .seealso DMCreateInjection()
3663: @*/
3664: PetscErrorCode DMHasCreateInjection(DM dm,PetscBool *flg)
3665: {
3671: if (dm->ops->hascreateinjection) {
3672: (*dm->ops->hascreateinjection)(dm,flg);
3673: } else {
3674: *flg = (dm->ops->createinjection) ? PETSC_TRUE : PETSC_FALSE;
3675: }
3676: return(0);
3677: }
3679: PetscFunctionList DMList = NULL;
3680: PetscBool DMRegisterAllCalled = PETSC_FALSE;
3682: /*@C
3683: DMSetType - Builds a DM, for a particular DM implementation.
3685: Collective on dm
3687: Input Parameters:
3688: + dm - The DM object
3689: - method - The name of the DM type
3691: Options Database Key:
3692: . -dm_type <type> - Sets the DM type; use -help for a list of available types
3694: Notes:
3695: See "petsc/include/petscdm.h" for available DM types (for instance, DM1D, DM2D, or DM3D).
3697: Level: intermediate
3699: .seealso: DMGetType(), DMCreate()
3700: @*/
3701: PetscErrorCode DMSetType(DM dm, DMType method)
3702: {
3703: PetscErrorCode (*r)(DM);
3704: PetscBool match;
3709: PetscObjectTypeCompare((PetscObject) dm, method, &match);
3710: if (match) return(0);
3712: DMRegisterAll();
3713: PetscFunctionListFind(DMList,method,&r);
3714: if (!r) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_UNKNOWN_TYPE, "Unknown DM type: %s", method);
3716: if (dm->ops->destroy) {
3717: (*dm->ops->destroy)(dm);
3718: }
3719: PetscMemzero(dm->ops,sizeof(*dm->ops));
3720: PetscObjectChangeTypeName((PetscObject)dm,method);
3721: (*r)(dm);
3722: return(0);
3723: }
3725: /*@C
3726: DMGetType - Gets the DM type name (as a string) from the DM.
3728: Not Collective
3730: Input Parameter:
3731: . dm - The DM
3733: Output Parameter:
3734: . type - The DM type name
3736: Level: intermediate
3738: .seealso: DMSetType(), DMCreate()
3739: @*/
3740: PetscErrorCode DMGetType(DM dm, DMType *type)
3741: {
3747: DMRegisterAll();
3748: *type = ((PetscObject)dm)->type_name;
3749: return(0);
3750: }
3752: /*@C
3753: DMConvert - Converts a DM to another DM, either of the same or different type.
3755: Collective on dm
3757: Input Parameters:
3758: + dm - the DM
3759: - newtype - new DM type (use "same" for the same type)
3761: Output Parameter:
3762: . M - pointer to new DM
3764: Notes:
3765: Cannot be used to convert a sequential DM to parallel or parallel to sequential,
3766: the MPI communicator of the generated DM is always the same as the communicator
3767: of the input DM.
3769: Level: intermediate
3771: .seealso: DMCreate()
3772: @*/
3773: PetscErrorCode DMConvert(DM dm, DMType newtype, DM *M)
3774: {
3775: DM B;
3776: char convname[256];
3777: PetscBool sametype/*, issame */;
3784: PetscObjectTypeCompare((PetscObject) dm, newtype, &sametype);
3785: /* PetscStrcmp(newtype, "same", &issame); */
3786: if (sametype) {
3787: *M = dm;
3788: PetscObjectReference((PetscObject) dm);
3789: return(0);
3790: } else {
3791: PetscErrorCode (*conv)(DM, DMType, DM*) = NULL;
3793: /*
3794: Order of precedence:
3795: 1) See if a specialized converter is known to the current DM.
3796: 2) See if a specialized converter is known to the desired DM class.
3797: 3) See if a good general converter is registered for the desired class
3798: 4) See if a good general converter is known for the current matrix.
3799: 5) Use a really basic converter.
3800: */
3802: /* 1) See if a specialized converter is known to the current DM and the desired class */
3803: PetscStrncpy(convname,"DMConvert_",sizeof(convname));
3804: PetscStrlcat(convname,((PetscObject) dm)->type_name,sizeof(convname));
3805: PetscStrlcat(convname,"_",sizeof(convname));
3806: PetscStrlcat(convname,newtype,sizeof(convname));
3807: PetscStrlcat(convname,"_C",sizeof(convname));
3808: PetscObjectQueryFunction((PetscObject)dm,convname,&conv);
3809: if (conv) goto foundconv;
3811: /* 2) See if a specialized converter is known to the desired DM class. */
3812: DMCreate(PetscObjectComm((PetscObject)dm), &B);
3813: DMSetType(B, newtype);
3814: PetscStrncpy(convname,"DMConvert_",sizeof(convname));
3815: PetscStrlcat(convname,((PetscObject) dm)->type_name,sizeof(convname));
3816: PetscStrlcat(convname,"_",sizeof(convname));
3817: PetscStrlcat(convname,newtype,sizeof(convname));
3818: PetscStrlcat(convname,"_C",sizeof(convname));
3819: PetscObjectQueryFunction((PetscObject)B,convname,&conv);
3820: if (conv) {
3821: DMDestroy(&B);
3822: goto foundconv;
3823: }
3825: #if 0
3826: /* 3) See if a good general converter is registered for the desired class */
3827: conv = B->ops->convertfrom;
3828: DMDestroy(&B);
3829: if (conv) goto foundconv;
3831: /* 4) See if a good general converter is known for the current matrix */
3832: if (dm->ops->convert) {
3833: conv = dm->ops->convert;
3834: }
3835: if (conv) goto foundconv;
3836: #endif
3838: /* 5) Use a really basic converter. */
3839: SETERRQ2(PetscObjectComm((PetscObject)dm), PETSC_ERR_SUP, "No conversion possible between DM types %s and %s", ((PetscObject) dm)->type_name, newtype);
3841: foundconv:
3842: PetscLogEventBegin(DM_Convert,dm,0,0,0);
3843: (*conv)(dm,newtype,M);
3844: /* Things that are independent of DM type: We should consult DMClone() here */
3845: {
3846: PetscBool isper;
3847: const PetscReal *maxCell, *L;
3848: const DMBoundaryType *bd;
3849: DMGetPeriodicity(dm, &isper, &maxCell, &L, &bd);
3850: DMSetPeriodicity(*M, isper, maxCell, L, bd);
3851: (*M)->prealloc_only = dm->prealloc_only;
3852: PetscFree((*M)->vectype);
3853: PetscStrallocpy(dm->vectype,(char**)&(*M)->vectype);
3854: PetscFree((*M)->mattype);
3855: PetscStrallocpy(dm->mattype,(char**)&(*M)->mattype);
3856: }
3857: PetscLogEventEnd(DM_Convert,dm,0,0,0);
3858: }
3859: PetscObjectStateIncrease((PetscObject) *M);
3860: return(0);
3861: }
3863: /*--------------------------------------------------------------------------------------------------------------------*/
3865: /*@C
3866: DMRegister - Adds a new DM component implementation
3868: Not Collective
3870: Input Parameters:
3871: + name - The name of a new user-defined creation routine
3872: - create_func - The creation routine itself
3874: Notes:
3875: DMRegister() may be called multiple times to add several user-defined DMs
3878: Sample usage:
3879: .vb
3880: DMRegister("my_da", MyDMCreate);
3881: .ve
3883: Then, your DM type can be chosen with the procedural interface via
3884: .vb
3885: DMCreate(MPI_Comm, DM *);
3886: DMSetType(DM,"my_da");
3887: .ve
3888: or at runtime via the option
3889: .vb
3890: -da_type my_da
3891: .ve
3893: Level: advanced
3895: .seealso: DMRegisterAll(), DMRegisterDestroy()
3897: @*/
3898: PetscErrorCode DMRegister(const char sname[],PetscErrorCode (*function)(DM))
3899: {
3903: DMInitializePackage();
3904: PetscFunctionListAdd(&DMList,sname,function);
3905: return(0);
3906: }
3908: /*@C
3909: DMLoad - Loads a DM that has been stored in binary with DMView().
3911: Collective on viewer
3913: Input Parameters:
3914: + newdm - the newly loaded DM, this needs to have been created with DMCreate() or
3915: some related function before a call to DMLoad().
3916: - viewer - binary file viewer, obtained from PetscViewerBinaryOpen() or
3917: HDF5 file viewer, obtained from PetscViewerHDF5Open()
3919: Level: intermediate
3921: Notes:
3922: The type is determined by the data in the file, any type set into the DM before this call is ignored.
3924: Notes for advanced users:
3925: Most users should not need to know the details of the binary storage
3926: format, since DMLoad() and DMView() completely hide these details.
3927: But for anyone who's interested, the standard binary matrix storage
3928: format is
3929: .vb
3930: has not yet been determined
3931: .ve
3933: .seealso: PetscViewerBinaryOpen(), DMView(), MatLoad(), VecLoad()
3934: @*/
3935: PetscErrorCode DMLoad(DM newdm, PetscViewer viewer)
3936: {
3937: PetscBool isbinary, ishdf5;
3943: PetscViewerCheckReadable(viewer);
3944: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERBINARY,&isbinary);
3945: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERHDF5,&ishdf5);
3946: PetscLogEventBegin(DM_Load,viewer,0,0,0);
3947: if (isbinary) {
3948: PetscInt classid;
3949: char type[256];
3951: PetscViewerBinaryRead(viewer,&classid,1,NULL,PETSC_INT);
3952: if (classid != DM_FILE_CLASSID) SETERRQ1(PetscObjectComm((PetscObject)newdm),PETSC_ERR_ARG_WRONG,"Not DM next in file, classid found %d",(int)classid);
3953: PetscViewerBinaryRead(viewer,type,256,NULL,PETSC_CHAR);
3954: DMSetType(newdm, type);
3955: if (newdm->ops->load) {(*newdm->ops->load)(newdm,viewer);}
3956: } else if (ishdf5) {
3957: if (newdm->ops->load) {(*newdm->ops->load)(newdm,viewer);}
3958: } else SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid viewer; open viewer with PetscViewerBinaryOpen() or PetscViewerHDF5Open()");
3959: PetscLogEventEnd(DM_Load,viewer,0,0,0);
3960: return(0);
3961: }
3963: /*@
3964: DMGetLocalBoundingBox - Returns the bounding box for the piece of the DM on this process.
3966: Not collective
3968: Input Parameter:
3969: . dm - the DM
3971: Output Parameters:
3972: + lmin - local minimum coordinates (length coord dim, optional)
3973: - lmax - local maximim coordinates (length coord dim, optional)
3975: Level: beginner
3977: Note: If the DM is a DMDA and has no coordinates, the index bounds are returned instead.
3980: .seealso: DMGetCoordinates(), DMGetCoordinatesLocal(), DMGetBoundingBox()
3981: @*/
3982: PetscErrorCode DMGetLocalBoundingBox(DM dm, PetscReal lmin[], PetscReal lmax[])
3983: {
3984: Vec coords = NULL;
3985: PetscReal min[3] = {PETSC_MAX_REAL, PETSC_MAX_REAL, PETSC_MAX_REAL};
3986: PetscReal max[3] = {PETSC_MIN_REAL, PETSC_MIN_REAL, PETSC_MIN_REAL};
3987: const PetscScalar *local_coords;
3988: PetscInt N, Ni;
3989: PetscInt cdim, i, j;
3990: PetscErrorCode ierr;
3994: DMGetCoordinateDim(dm, &cdim);
3995: DMGetCoordinates(dm, &coords);
3996: if (coords) {
3997: VecGetArrayRead(coords, &local_coords);
3998: VecGetLocalSize(coords, &N);
3999: Ni = N/cdim;
4000: for (i = 0; i < Ni; ++i) {
4001: for (j = 0; j < 3; ++j) {
4002: min[j] = j < cdim ? PetscMin(min[j], PetscRealPart(local_coords[i*cdim+j])) : 0;
4003: max[j] = j < cdim ? PetscMax(max[j], PetscRealPart(local_coords[i*cdim+j])) : 0;
4004: }
4005: }
4006: VecRestoreArrayRead(coords, &local_coords);
4007: } else {
4008: PetscBool isda;
4010: PetscObjectTypeCompare((PetscObject) dm, DMDA, &isda);
4011: if (isda) {DMGetLocalBoundingIndices_DMDA(dm, min, max);}
4012: }
4013: if (lmin) {PetscArraycpy(lmin, min, cdim);}
4014: if (lmax) {PetscArraycpy(lmax, max, cdim);}
4015: return(0);
4016: }
4018: /*@
4019: DMGetBoundingBox - Returns the global bounding box for the DM.
4021: Collective
4023: Input Parameter:
4024: . dm - the DM
4026: Output Parameters:
4027: + gmin - global minimum coordinates (length coord dim, optional)
4028: - gmax - global maximim coordinates (length coord dim, optional)
4030: Level: beginner
4032: .seealso: DMGetLocalBoundingBox(), DMGetCoordinates(), DMGetCoordinatesLocal()
4033: @*/
4034: PetscErrorCode DMGetBoundingBox(DM dm, PetscReal gmin[], PetscReal gmax[])
4035: {
4036: PetscReal lmin[3], lmax[3];
4037: PetscInt cdim;
4038: PetscMPIInt count;
4043: DMGetCoordinateDim(dm, &cdim);
4044: PetscMPIIntCast(cdim, &count);
4045: DMGetLocalBoundingBox(dm, lmin, lmax);
4046: if (gmin) {MPIU_Allreduce(lmin, gmin, count, MPIU_REAL, MPIU_MIN, PetscObjectComm((PetscObject) dm));}
4047: if (gmax) {MPIU_Allreduce(lmax, gmax, count, MPIU_REAL, MPIU_MAX, PetscObjectComm((PetscObject) dm));}
4048: return(0);
4049: }
4051: /******************************** FEM Support **********************************/
4053: PetscErrorCode DMPrintCellVector(PetscInt c, const char name[], PetscInt len, const PetscScalar x[])
4054: {
4055: PetscInt f;
4059: PetscPrintf(PETSC_COMM_SELF, "Cell %D Element %s\n", c, name);
4060: for (f = 0; f < len; ++f) {
4061: PetscPrintf(PETSC_COMM_SELF, " | %g |\n", (double)PetscRealPart(x[f]));
4062: }
4063: return(0);
4064: }
4066: PetscErrorCode DMPrintCellMatrix(PetscInt c, const char name[], PetscInt rows, PetscInt cols, const PetscScalar A[])
4067: {
4068: PetscInt f, g;
4072: PetscPrintf(PETSC_COMM_SELF, "Cell %D Element %s\n", c, name);
4073: for (f = 0; f < rows; ++f) {
4074: PetscPrintf(PETSC_COMM_SELF, " |");
4075: for (g = 0; g < cols; ++g) {
4076: PetscPrintf(PETSC_COMM_SELF, " % 9.5g", PetscRealPart(A[f*cols+g]));
4077: }
4078: PetscPrintf(PETSC_COMM_SELF, " |\n");
4079: }
4080: return(0);
4081: }
4083: PetscErrorCode DMPrintLocalVec(DM dm, const char name[], PetscReal tol, Vec X)
4084: {
4085: PetscInt localSize, bs;
4086: PetscMPIInt size;
4087: Vec x, xglob;
4088: const PetscScalar *xarray;
4089: PetscErrorCode ierr;
4092: MPI_Comm_size(PetscObjectComm((PetscObject) dm),&size);
4093: VecDuplicate(X, &x);
4094: VecCopy(X, x);
4095: VecChop(x, tol);
4096: PetscPrintf(PetscObjectComm((PetscObject) dm),"%s:\n",name);
4097: if (size > 1) {
4098: VecGetLocalSize(x,&localSize);
4099: VecGetArrayRead(x,&xarray);
4100: VecGetBlockSize(x,&bs);
4101: VecCreateMPIWithArray(PetscObjectComm((PetscObject) dm),bs,localSize,PETSC_DETERMINE,xarray,&xglob);
4102: } else {
4103: xglob = x;
4104: }
4105: VecView(xglob,PETSC_VIEWER_STDOUT_(PetscObjectComm((PetscObject) dm)));
4106: if (size > 1) {
4107: VecDestroy(&xglob);
4108: VecRestoreArrayRead(x,&xarray);
4109: }
4110: VecDestroy(&x);
4111: return(0);
4112: }
4114: /*@
4115: DMGetSection - Get the PetscSection encoding the local data layout for the DM. This is equivalent to DMGetLocalSection(). Deprecated in v3.12
4117: Input Parameter:
4118: . dm - The DM
4120: Output Parameter:
4121: . section - The PetscSection
4123: Options Database Keys:
4124: . -dm_petscsection_view - View the Section created by the DM
4126: Level: advanced
4128: Notes:
4129: Use DMGetLocalSection() in new code.
4131: This gets a borrowed reference, so the user should not destroy this PetscSection.
4133: .seealso: DMGetLocalSection(), DMSetLocalSection(), DMGetGlobalSection()
4134: @*/
4135: PetscErrorCode DMGetSection(DM dm, PetscSection *section)
4136: {
4140: DMGetLocalSection(dm,section);
4141: return(0);
4142: }
4144: /*@
4145: DMGetLocalSection - Get the PetscSection encoding the local data layout for the DM.
4147: Input Parameter:
4148: . dm - The DM
4150: Output Parameter:
4151: . section - The PetscSection
4153: Options Database Keys:
4154: . -dm_petscsection_view - View the Section created by the DM
4156: Level: intermediate
4158: Note: This gets a borrowed reference, so the user should not destroy this PetscSection.
4160: .seealso: DMSetLocalSection(), DMGetGlobalSection()
4161: @*/
4162: PetscErrorCode DMGetLocalSection(DM dm, PetscSection *section)
4163: {
4169: if (!dm->localSection && dm->ops->createlocalsection) {
4170: PetscInt d;
4172: if (dm->setfromoptionscalled) for (d = 0; d < dm->Nds; ++d) {PetscDSSetFromOptions(dm->probs[d].ds);}
4173: (*dm->ops->createlocalsection)(dm);
4174: if (dm->localSection) {PetscObjectViewFromOptions((PetscObject) dm->localSection, NULL, "-dm_petscsection_view");}
4175: }
4176: *section = dm->localSection;
4177: return(0);
4178: }
4180: /*@
4181: DMSetSection - Set the PetscSection encoding the local data layout for the DM. This is equivalent to DMSetLocalSection(). Deprecated in v3.12
4183: Input Parameters:
4184: + dm - The DM
4185: - section - The PetscSection
4187: Level: advanced
4189: Notes:
4190: Use DMSetLocalSection() in new code.
4192: Any existing Section will be destroyed
4194: .seealso: DMSetLocalSection(), DMGetLocalSection(), DMSetGlobalSection()
4195: @*/
4196: PetscErrorCode DMSetSection(DM dm, PetscSection section)
4197: {
4201: DMSetLocalSection(dm,section);
4202: return(0);
4203: }
4205: /*@
4206: DMSetLocalSection - Set the PetscSection encoding the local data layout for the DM.
4208: Input Parameters:
4209: + dm - The DM
4210: - section - The PetscSection
4212: Level: intermediate
4214: Note: Any existing Section will be destroyed
4216: .seealso: DMGetLocalSection(), DMSetGlobalSection()
4217: @*/
4218: PetscErrorCode DMSetLocalSection(DM dm, PetscSection section)
4219: {
4220: PetscInt numFields = 0;
4221: PetscInt f;
4227: PetscObjectReference((PetscObject)section);
4228: PetscSectionDestroy(&dm->localSection);
4229: dm->localSection = section;
4230: if (section) {PetscSectionGetNumFields(dm->localSection, &numFields);}
4231: if (numFields) {
4232: DMSetNumFields(dm, numFields);
4233: for (f = 0; f < numFields; ++f) {
4234: PetscObject disc;
4235: const char *name;
4237: PetscSectionGetFieldName(dm->localSection, f, &name);
4238: DMGetField(dm, f, NULL, &disc);
4239: PetscObjectSetName(disc, name);
4240: }
4241: }
4242: /* The global section will be rebuilt in the next call to DMGetGlobalSection(). */
4243: PetscSectionDestroy(&dm->globalSection);
4244: return(0);
4245: }
4247: /*@
4248: DMGetDefaultConstraints - Get the PetscSection and Mat that specify the local constraint interpolation. See DMSetDefaultConstraints() for a description of the purpose of constraint interpolation.
4250: not collective
4252: Input Parameter:
4253: . dm - The DM
4255: Output Parameter:
4256: + section - The PetscSection describing the range of the constraint matrix: relates rows of the constraint matrix to dofs of the default section. Returns NULL if there are no local constraints.
4257: - mat - The Mat that interpolates local constraints: its width should be the layout size of the default section. Returns NULL if there are no local constraints.
4259: Level: advanced
4261: Note: This gets borrowed references, so the user should not destroy the PetscSection or the Mat.
4263: .seealso: DMSetDefaultConstraints()
4264: @*/
4265: PetscErrorCode DMGetDefaultConstraints(DM dm, PetscSection *section, Mat *mat)
4266: {
4271: if (!dm->defaultConstraintSection && !dm->defaultConstraintMat && dm->ops->createdefaultconstraints) {(*dm->ops->createdefaultconstraints)(dm);}
4272: if (section) {*section = dm->defaultConstraintSection;}
4273: if (mat) {*mat = dm->defaultConstraintMat;}
4274: return(0);
4275: }
4277: /*@
4278: DMSetDefaultConstraints - Set the PetscSection and Mat that specify the local constraint interpolation.
4280: If a constraint matrix is specified, then it is applied during DMGlobalToLocalEnd() when mode is INSERT_VALUES, INSERT_BC_VALUES, or INSERT_ALL_VALUES. Without a constraint matrix, the local vector l returned by DMGlobalToLocalEnd() contains values that have been scattered from a global vector without modification; with a constraint matrix A, l is modified by computing c = A * l, l[s[i]] = c[i], where the scatter s is defined by the PetscSection returned by DMGetDefaultConstraintMatrix().
4282: If a constraint matrix is specified, then its adjoint is applied during DMLocalToGlobalBegin() when mode is ADD_VALUES, ADD_BC_VALUES, or ADD_ALL_VALUES. Without a constraint matrix, the local vector l is accumulated into a global vector without modification; with a constraint matrix A, l is first modified by computing c[i] = l[s[i]], l[s[i]] = 0, l = l + A'*c, which is the adjoint of the operation described above.
4284: collective on dm
4286: Input Parameters:
4287: + dm - The DM
4288: + section - The PetscSection describing the range of the constraint matrix: relates rows of the constraint matrix to dofs of the default section. Must have a local communicator (PETSC_COMM_SELF or derivative).
4289: - mat - The Mat that interpolates local constraints: its width should be the layout size of the default section: NULL indicates no constraints. Must have a local communicator (PETSC_COMM_SELF or derivative).
4291: Level: advanced
4293: Note: This increments the references of the PetscSection and the Mat, so they user can destroy them
4295: .seealso: DMGetDefaultConstraints()
4296: @*/
4297: PetscErrorCode DMSetDefaultConstraints(DM dm, PetscSection section, Mat mat)
4298: {
4299: PetscMPIInt result;
4304: if (section) {
4306: MPI_Comm_compare(PETSC_COMM_SELF,PetscObjectComm((PetscObject)section),&result);
4307: if (result != MPI_CONGRUENT && result != MPI_IDENT) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_NOTSAMECOMM,"constraint section must have local communicator");
4308: }
4309: if (mat) {
4311: MPI_Comm_compare(PETSC_COMM_SELF,PetscObjectComm((PetscObject)mat),&result);
4312: if (result != MPI_CONGRUENT && result != MPI_IDENT) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_NOTSAMECOMM,"constraint matrix must have local communicator");
4313: }
4314: PetscObjectReference((PetscObject)section);
4315: PetscSectionDestroy(&dm->defaultConstraintSection);
4316: dm->defaultConstraintSection = section;
4317: PetscObjectReference((PetscObject)mat);
4318: MatDestroy(&dm->defaultConstraintMat);
4319: dm->defaultConstraintMat = mat;
4320: return(0);
4321: }
4323: #if defined(PETSC_USE_DEBUG)
4324: /*
4325: DMDefaultSectionCheckConsistency - Check the consistentcy of the global and local sections.
4327: Input Parameters:
4328: + dm - The DM
4329: . localSection - PetscSection describing the local data layout
4330: - globalSection - PetscSection describing the global data layout
4332: Level: intermediate
4334: .seealso: DMGetSectionSF(), DMSetSectionSF()
4335: */
4336: static PetscErrorCode DMDefaultSectionCheckConsistency_Internal(DM dm, PetscSection localSection, PetscSection globalSection)
4337: {
4338: MPI_Comm comm;
4339: PetscLayout layout;
4340: const PetscInt *ranges;
4341: PetscInt pStart, pEnd, p, nroots;
4342: PetscMPIInt size, rank;
4343: PetscBool valid = PETSC_TRUE, gvalid;
4344: PetscErrorCode ierr;
4347: PetscObjectGetComm((PetscObject)dm,&comm);
4349: MPI_Comm_size(comm, &size);
4350: MPI_Comm_rank(comm, &rank);
4351: PetscSectionGetChart(globalSection, &pStart, &pEnd);
4352: PetscSectionGetConstrainedStorageSize(globalSection, &nroots);
4353: PetscLayoutCreate(comm, &layout);
4354: PetscLayoutSetBlockSize(layout, 1);
4355: PetscLayoutSetLocalSize(layout, nroots);
4356: PetscLayoutSetUp(layout);
4357: PetscLayoutGetRanges(layout, &ranges);
4358: for (p = pStart; p < pEnd; ++p) {
4359: PetscInt dof, cdof, off, gdof, gcdof, goff, gsize, d;
4361: PetscSectionGetDof(localSection, p, &dof);
4362: PetscSectionGetOffset(localSection, p, &off);
4363: PetscSectionGetConstraintDof(localSection, p, &cdof);
4364: PetscSectionGetDof(globalSection, p, &gdof);
4365: PetscSectionGetConstraintDof(globalSection, p, &gcdof);
4366: PetscSectionGetOffset(globalSection, p, &goff);
4367: if (!gdof) continue; /* Censored point */
4368: if ((gdof < 0 ? -(gdof+1) : gdof) != dof) {PetscSynchronizedPrintf(comm, "[%d]Global dof %d for point %d not equal to local dof %d\n", rank, gdof, p, dof); valid = PETSC_FALSE;}
4369: if (gcdof && (gcdof != cdof)) {PetscSynchronizedPrintf(comm, "[%d]Global constraints %d for point %d not equal to local constraints %d\n", rank, gcdof, p, cdof); valid = PETSC_FALSE;}
4370: if (gdof < 0) {
4371: gsize = gdof < 0 ? -(gdof+1)-gcdof : gdof-gcdof;
4372: for (d = 0; d < gsize; ++d) {
4373: PetscInt offset = -(goff+1) + d, r;
4375: PetscFindInt(offset,size+1,ranges,&r);
4376: if (r < 0) r = -(r+2);
4377: if ((r < 0) || (r >= size)) {PetscSynchronizedPrintf(comm, "[%d]Point %d mapped to invalid process %d (%d, %d)\n", rank, p, r, gdof, goff); valid = PETSC_FALSE;break;}
4378: }
4379: }
4380: }
4381: PetscLayoutDestroy(&layout);
4382: PetscSynchronizedFlush(comm, NULL);
4383: MPIU_Allreduce(&valid, &gvalid, 1, MPIU_BOOL, MPI_LAND, comm);
4384: if (!gvalid) {
4385: DMView(dm, NULL);
4386: SETERRQ(comm, PETSC_ERR_ARG_WRONG, "Inconsistent local and global sections");
4387: }
4388: return(0);
4389: }
4390: #endif
4392: /*@
4393: DMGetGlobalSection - Get the PetscSection encoding the global data layout for the DM.
4395: Collective on dm
4397: Input Parameter:
4398: . dm - The DM
4400: Output Parameter:
4401: . section - The PetscSection
4403: Level: intermediate
4405: Note: This gets a borrowed reference, so the user should not destroy this PetscSection.
4407: .seealso: DMSetLocalSection(), DMGetLocalSection()
4408: @*/
4409: PetscErrorCode DMGetGlobalSection(DM dm, PetscSection *section)
4410: {
4416: if (!dm->globalSection) {
4417: PetscSection s;
4419: DMGetLocalSection(dm, &s);
4420: if (!s) SETERRQ(PetscObjectComm((PetscObject) dm), PETSC_ERR_ARG_WRONGSTATE, "DM must have a default PetscSection in order to create a global PetscSection");
4421: if (!dm->sf) SETERRQ(PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_WRONGSTATE, "DM must have a point PetscSF in order to create a global PetscSection");
4422: PetscSectionCreateGlobalSection(s, dm->sf, PETSC_FALSE, PETSC_FALSE, &dm->globalSection);
4423: PetscLayoutDestroy(&dm->map);
4424: PetscSectionGetValueLayout(PetscObjectComm((PetscObject)dm), dm->globalSection, &dm->map);
4425: PetscSectionViewFromOptions(dm->globalSection, NULL, "-global_section_view");
4426: }
4427: *section = dm->globalSection;
4428: return(0);
4429: }
4431: /*@
4432: DMSetGlobalSection - Set the PetscSection encoding the global data layout for the DM.
4434: Input Parameters:
4435: + dm - The DM
4436: - section - The PetscSection, or NULL
4438: Level: intermediate
4440: Note: Any existing Section will be destroyed
4442: .seealso: DMGetGlobalSection(), DMSetLocalSection()
4443: @*/
4444: PetscErrorCode DMSetGlobalSection(DM dm, PetscSection section)
4445: {
4451: PetscObjectReference((PetscObject)section);
4452: PetscSectionDestroy(&dm->globalSection);
4453: dm->globalSection = section;
4454: #if defined(PETSC_USE_DEBUG)
4455: if (section) {DMDefaultSectionCheckConsistency_Internal(dm, dm->localSection, section);}
4456: #endif
4457: return(0);
4458: }
4460: /*@
4461: DMGetSectionSF - Get the PetscSF encoding the parallel dof overlap for the DM. If it has not been set,
4462: it is created from the default PetscSection layouts in the DM.
4464: Input Parameter:
4465: . dm - The DM
4467: Output Parameter:
4468: . sf - The PetscSF
4470: Level: intermediate
4472: Note: This gets a borrowed reference, so the user should not destroy this PetscSF.
4474: .seealso: DMSetSectionSF(), DMCreateSectionSF()
4475: @*/
4476: PetscErrorCode DMGetSectionSF(DM dm, PetscSF *sf)
4477: {
4478: PetscInt nroots;
4484: if (!dm->sectionSF) {
4485: PetscSFCreate(PetscObjectComm((PetscObject)dm),&dm->sectionSF);
4486: }
4487: PetscSFGetGraph(dm->sectionSF, &nroots, NULL, NULL, NULL);
4488: if (nroots < 0) {
4489: PetscSection section, gSection;
4491: DMGetLocalSection(dm, §ion);
4492: if (section) {
4493: DMGetGlobalSection(dm, &gSection);
4494: DMCreateSectionSF(dm, section, gSection);
4495: } else {
4496: *sf = NULL;
4497: return(0);
4498: }
4499: }
4500: *sf = dm->sectionSF;
4501: return(0);
4502: }
4504: /*@
4505: DMSetSectionSF - Set the PetscSF encoding the parallel dof overlap for the DM
4507: Input Parameters:
4508: + dm - The DM
4509: - sf - The PetscSF
4511: Level: intermediate
4513: Note: Any previous SF is destroyed
4515: .seealso: DMGetSectionSF(), DMCreateSectionSF()
4516: @*/
4517: PetscErrorCode DMSetSectionSF(DM dm, PetscSF sf)
4518: {
4524: PetscObjectReference((PetscObject) sf);
4525: PetscSFDestroy(&dm->sectionSF);
4526: dm->sectionSF = sf;
4527: return(0);
4528: }
4530: /*@C
4531: DMCreateSectionSF - Create the PetscSF encoding the parallel dof overlap for the DM based upon the PetscSections
4532: describing the data layout.
4534: Input Parameters:
4535: + dm - The DM
4536: . localSection - PetscSection describing the local data layout
4537: - globalSection - PetscSection describing the global data layout
4539: Notes: One usually uses DMGetSectionSF() to obtain the PetscSF
4541: Level: developer
4543: Developer Note: Since this routine has for arguments the two sections from the DM and puts the resulting PetscSF
4544: directly into the DM, perhaps this function should not take the local and global sections as
4545: input and should just obtain them from the DM?
4547: .seealso: DMGetSectionSF(), DMSetSectionSF(), DMGetLocalSection(), DMGetGlobalSection()
4548: @*/
4549: PetscErrorCode DMCreateSectionSF(DM dm, PetscSection localSection, PetscSection globalSection)
4550: {
4555: PetscSFSetGraphSection(dm->sectionSF, localSection, globalSection);
4556: return(0);
4557: }
4559: /*@
4560: DMGetPointSF - Get the PetscSF encoding the parallel section point overlap for the DM.
4562: Input Parameter:
4563: . dm - The DM
4565: Output Parameter:
4566: . sf - The PetscSF
4568: Level: intermediate
4570: Note: This gets a borrowed reference, so the user should not destroy this PetscSF.
4572: .seealso: DMSetPointSF(), DMGetSectionSF(), DMSetSectionSF(), DMCreateSectionSF()
4573: @*/
4574: PetscErrorCode DMGetPointSF(DM dm, PetscSF *sf)
4575: {
4579: *sf = dm->sf;
4580: return(0);
4581: }
4583: /*@
4584: DMSetPointSF - Set the PetscSF encoding the parallel section point overlap for the DM.
4586: Input Parameters:
4587: + dm - The DM
4588: - sf - The PetscSF
4590: Level: intermediate
4592: .seealso: DMGetPointSF(), DMGetSectionSF(), DMSetSectionSF(), DMCreateSectionSF()
4593: @*/
4594: PetscErrorCode DMSetPointSF(DM dm, PetscSF sf)
4595: {
4601: PetscObjectReference((PetscObject) sf);
4602: PetscSFDestroy(&dm->sf);
4603: dm->sf = sf;
4604: return(0);
4605: }
4607: static PetscErrorCode DMSetDefaultAdjacency_Private(DM dm, PetscInt f, PetscObject disc)
4608: {
4609: PetscClassId id;
4613: PetscObjectGetClassId(disc, &id);
4614: if (id == PETSCFE_CLASSID) {
4615: DMSetAdjacency(dm, f, PETSC_FALSE, PETSC_TRUE);
4616: } else if (id == PETSCFV_CLASSID) {
4617: DMSetAdjacency(dm, f, PETSC_TRUE, PETSC_FALSE);
4618: } else {
4619: DMSetAdjacency(dm, f, PETSC_FALSE, PETSC_TRUE);
4620: }
4621: return(0);
4622: }
4624: static PetscErrorCode DMFieldEnlarge_Static(DM dm, PetscInt NfNew)
4625: {
4626: RegionField *tmpr;
4627: PetscInt Nf = dm->Nf, f;
4631: if (Nf >= NfNew) return(0);
4632: PetscMalloc1(NfNew, &tmpr);
4633: for (f = 0; f < Nf; ++f) tmpr[f] = dm->fields[f];
4634: for (f = Nf; f < NfNew; ++f) {tmpr[f].disc = NULL; tmpr[f].label = NULL; tmpr[f].avoidTensor = PETSC_FALSE;}
4635: PetscFree(dm->fields);
4636: dm->Nf = NfNew;
4637: dm->fields = tmpr;
4638: return(0);
4639: }
4641: /*@
4642: DMClearFields - Remove all fields from the DM
4644: Logically collective on dm
4646: Input Parameter:
4647: . dm - The DM
4649: Level: intermediate
4651: .seealso: DMGetNumFields(), DMSetNumFields(), DMSetField()
4652: @*/
4653: PetscErrorCode DMClearFields(DM dm)
4654: {
4655: PetscInt f;
4660: for (f = 0; f < dm->Nf; ++f) {
4661: PetscObjectDestroy(&dm->fields[f].disc);
4662: DMLabelDestroy(&dm->fields[f].label);
4663: }
4664: PetscFree(dm->fields);
4665: dm->fields = NULL;
4666: dm->Nf = 0;
4667: return(0);
4668: }
4670: /*@
4671: DMGetNumFields - Get the number of fields in the DM
4673: Not collective
4675: Input Parameter:
4676: . dm - The DM
4678: Output Parameter:
4679: . Nf - The number of fields
4681: Level: intermediate
4683: .seealso: DMSetNumFields(), DMSetField()
4684: @*/
4685: PetscErrorCode DMGetNumFields(DM dm, PetscInt *numFields)
4686: {
4690: *numFields = dm->Nf;
4691: return(0);
4692: }
4694: /*@
4695: DMSetNumFields - Set the number of fields in the DM
4697: Logically collective on dm
4699: Input Parameters:
4700: + dm - The DM
4701: - Nf - The number of fields
4703: Level: intermediate
4705: .seealso: DMGetNumFields(), DMSetField()
4706: @*/
4707: PetscErrorCode DMSetNumFields(DM dm, PetscInt numFields)
4708: {
4709: PetscInt Nf, f;
4714: DMGetNumFields(dm, &Nf);
4715: for (f = Nf; f < numFields; ++f) {
4716: PetscContainer obj;
4718: PetscContainerCreate(PetscObjectComm((PetscObject) dm), &obj);
4719: DMAddField(dm, NULL, (PetscObject) obj);
4720: PetscContainerDestroy(&obj);
4721: }
4722: return(0);
4723: }
4725: /*@
4726: DMGetField - Return the discretization object for a given DM field
4728: Not collective
4730: Input Parameters:
4731: + dm - The DM
4732: - f - The field number
4734: Output Parameters:
4735: + label - The label indicating the support of the field, or NULL for the entire mesh
4736: - field - The discretization object
4738: Level: intermediate
4740: .seealso: DMAddField(), DMSetField()
4741: @*/
4742: PetscErrorCode DMGetField(DM dm, PetscInt f, DMLabel *label, PetscObject *field)
4743: {
4747: if ((f < 0) || (f >= dm->Nf)) SETERRQ2(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Field number %d must be in [0, %d)", f, dm->Nf);
4748: if (label) *label = dm->fields[f].label;
4749: if (field) *field = dm->fields[f].disc;
4750: return(0);
4751: }
4753: /* Does not clear the DS */
4754: PetscErrorCode DMSetField_Internal(DM dm, PetscInt f, DMLabel label, PetscObject field)
4755: {
4759: DMFieldEnlarge_Static(dm, f+1);
4760: DMLabelDestroy(&dm->fields[f].label);
4761: PetscObjectDestroy(&dm->fields[f].disc);
4762: dm->fields[f].label = label;
4763: dm->fields[f].disc = field;
4764: PetscObjectReference((PetscObject) label);
4765: PetscObjectReference((PetscObject) field);
4766: return(0);
4767: }
4769: /*@
4770: DMSetField - Set the discretization object for a given DM field
4772: Logically collective on dm
4774: Input Parameters:
4775: + dm - The DM
4776: . f - The field number
4777: . label - The label indicating the support of the field, or NULL for the entire mesh
4778: - field - The discretization object
4780: Level: intermediate
4782: .seealso: DMAddField(), DMGetField()
4783: @*/
4784: PetscErrorCode DMSetField(DM dm, PetscInt f, DMLabel label, PetscObject field)
4785: {
4792: if (f < 0) SETERRQ1(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Field number %d must be non-negative", f);
4793: DMSetField_Internal(dm, f, label, field);
4794: DMSetDefaultAdjacency_Private(dm, f, field);
4795: DMClearDS(dm);
4796: return(0);
4797: }
4799: /*@
4800: DMAddField - Add the discretization object for the given DM field
4802: Logically collective on dm
4804: Input Parameters:
4805: + dm - The DM
4806: . label - The label indicating the support of the field, or NULL for the entire mesh
4807: - field - The discretization object
4809: Level: intermediate
4811: .seealso: DMSetField(), DMGetField()
4812: @*/
4813: PetscErrorCode DMAddField(DM dm, DMLabel label, PetscObject field)
4814: {
4815: PetscInt Nf = dm->Nf;
4822: DMFieldEnlarge_Static(dm, Nf+1);
4823: dm->fields[Nf].label = label;
4824: dm->fields[Nf].disc = field;
4825: PetscObjectReference((PetscObject) label);
4826: PetscObjectReference((PetscObject) field);
4827: DMSetDefaultAdjacency_Private(dm, Nf, field);
4828: DMClearDS(dm);
4829: return(0);
4830: }
4832: /*@
4833: DMSetFieldAvoidTensor - Set flag to avoid defining the field on tensor cells
4835: Logically collective on dm
4837: Input Parameters:
4838: + dm - The DM
4839: . f - The field index
4840: - avoidTensor - The flag to avoid defining the field on tensor cells
4842: Level: intermediate
4844: .seealso: DMGetFieldAvoidTensor(), DMSetField(), DMGetField()
4845: @*/
4846: PetscErrorCode DMSetFieldAvoidTensor(DM dm, PetscInt f, PetscBool avoidTensor)
4847: {
4849: if ((f < 0) || (f >= dm->Nf)) SETERRQ2(PetscObjectComm((PetscObject) dm), PETSC_ERR_ARG_OUTOFRANGE, "Field %D is not in [0, %D)", f, dm->Nf);
4850: dm->fields[f].avoidTensor = avoidTensor;
4851: return(0);
4852: }
4854: /*@
4855: DMGetFieldAvoidTensor - Get flag to avoid defining the field on tensor cells
4857: Logically collective on dm
4859: Input Parameters:
4860: + dm - The DM
4861: - f - The field index
4863: Output Parameter:
4864: . avoidTensor - The flag to avoid defining the field on tensor cells
4866: Level: intermediate
4868: .seealso: DMSetFieldAvoidTensor(), DMSetField(), DMGetField()
4869: @*/
4870: PetscErrorCode DMGetFieldAvoidTensor(DM dm, PetscInt f, PetscBool *avoidTensor)
4871: {
4873: if ((f < 0) || (f >= dm->Nf)) SETERRQ2(PetscObjectComm((PetscObject) dm), PETSC_ERR_ARG_OUTOFRANGE, "Field %D is not in [0, %D)", f, dm->Nf);
4874: *avoidTensor = dm->fields[f].avoidTensor;
4875: return(0);
4876: }
4878: /*@
4879: DMCopyFields - Copy the discretizations for the DM into another DM
4881: Collective on dm
4883: Input Parameter:
4884: . dm - The DM
4886: Output Parameter:
4887: . newdm - The DM
4889: Level: advanced
4891: .seealso: DMGetField(), DMSetField(), DMAddField(), DMCopyDS(), DMGetDS(), DMGetCellDS()
4892: @*/
4893: PetscErrorCode DMCopyFields(DM dm, DM newdm)
4894: {
4895: PetscInt Nf, f;
4899: if (dm == newdm) return(0);
4900: DMGetNumFields(dm, &Nf);
4901: DMClearFields(newdm);
4902: for (f = 0; f < Nf; ++f) {
4903: DMLabel label;
4904: PetscObject field;
4905: PetscBool useCone, useClosure;
4907: DMGetField(dm, f, &label, &field);
4908: DMSetField(newdm, f, label, field);
4909: DMGetAdjacency(dm, f, &useCone, &useClosure);
4910: DMSetAdjacency(newdm, f, useCone, useClosure);
4911: }
4912: return(0);
4913: }
4915: /*@
4916: DMGetAdjacency - Returns the flags for determining variable influence
4918: Not collective
4920: Input Parameters:
4921: + dm - The DM object
4922: - f - The field number, or PETSC_DEFAULT for the default adjacency
4924: Output Parameter:
4925: + useCone - Flag for variable influence starting with the cone operation
4926: - useClosure - Flag for variable influence using transitive closure
4928: Notes:
4929: $ FEM: Two points p and q are adjacent if q \in closure(star(p)), useCone = PETSC_FALSE, useClosure = PETSC_TRUE
4930: $ FVM: Two points p and q are adjacent if q \in support(p+cone(p)), useCone = PETSC_TRUE, useClosure = PETSC_FALSE
4931: $ FVM++: Two points p and q are adjacent if q \in star(closure(p)), useCone = PETSC_TRUE, useClosure = PETSC_TRUE
4932: Further explanation can be found in the User's Manual Section on the Influence of Variables on One Another.
4934: Level: developer
4936: .seealso: DMSetAdjacency(), DMGetField(), DMSetField()
4937: @*/
4938: PetscErrorCode DMGetAdjacency(DM dm, PetscInt f, PetscBool *useCone, PetscBool *useClosure)
4939: {
4944: if (f < 0) {
4945: if (useCone) *useCone = dm->adjacency[0];
4946: if (useClosure) *useClosure = dm->adjacency[1];
4947: } else {
4948: PetscInt Nf;
4951: DMGetNumFields(dm, &Nf);
4952: if (f >= Nf) SETERRQ2(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Field number %d must be in [0, %d)", f, Nf);
4953: if (useCone) *useCone = dm->fields[f].adjacency[0];
4954: if (useClosure) *useClosure = dm->fields[f].adjacency[1];
4955: }
4956: return(0);
4957: }
4959: /*@
4960: DMSetAdjacency - Set the flags for determining variable influence
4962: Not collective
4964: Input Parameters:
4965: + dm - The DM object
4966: . f - The field number
4967: . useCone - Flag for variable influence starting with the cone operation
4968: - useClosure - Flag for variable influence using transitive closure
4970: Notes:
4971: $ FEM: Two points p and q are adjacent if q \in closure(star(p)), useCone = PETSC_FALSE, useClosure = PETSC_TRUE
4972: $ FVM: Two points p and q are adjacent if q \in support(p+cone(p)), useCone = PETSC_TRUE, useClosure = PETSC_FALSE
4973: $ FVM++: Two points p and q are adjacent if q \in star(closure(p)), useCone = PETSC_TRUE, useClosure = PETSC_TRUE
4974: Further explanation can be found in the User's Manual Section on the Influence of Variables on One Another.
4976: Level: developer
4978: .seealso: DMGetAdjacency(), DMGetField(), DMSetField()
4979: @*/
4980: PetscErrorCode DMSetAdjacency(DM dm, PetscInt f, PetscBool useCone, PetscBool useClosure)
4981: {
4984: if (f < 0) {
4985: dm->adjacency[0] = useCone;
4986: dm->adjacency[1] = useClosure;
4987: } else {
4988: PetscInt Nf;
4991: DMGetNumFields(dm, &Nf);
4992: if (f >= Nf) SETERRQ2(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Field number %d must be in [0, %d)", f, Nf);
4993: dm->fields[f].adjacency[0] = useCone;
4994: dm->fields[f].adjacency[1] = useClosure;
4995: }
4996: return(0);
4997: }
4999: /*@
5000: DMGetBasicAdjacency - Returns the flags for determining variable influence, using either the default or field 0 if it is defined
5002: Not collective
5004: Input Parameters:
5005: . dm - The DM object
5007: Output Parameter:
5008: + useCone - Flag for variable influence starting with the cone operation
5009: - useClosure - Flag for variable influence using transitive closure
5011: Notes:
5012: $ FEM: Two points p and q are adjacent if q \in closure(star(p)), useCone = PETSC_FALSE, useClosure = PETSC_TRUE
5013: $ FVM: Two points p and q are adjacent if q \in support(p+cone(p)), useCone = PETSC_TRUE, useClosure = PETSC_FALSE
5014: $ FVM++: Two points p and q are adjacent if q \in star(closure(p)), useCone = PETSC_TRUE, useClosure = PETSC_TRUE
5016: Level: developer
5018: .seealso: DMSetBasicAdjacency(), DMGetField(), DMSetField()
5019: @*/
5020: PetscErrorCode DMGetBasicAdjacency(DM dm, PetscBool *useCone, PetscBool *useClosure)
5021: {
5022: PetscInt Nf;
5029: DMGetNumFields(dm, &Nf);
5030: if (!Nf) {
5031: DMGetAdjacency(dm, PETSC_DEFAULT, useCone, useClosure);
5032: } else {
5033: DMGetAdjacency(dm, 0, useCone, useClosure);
5034: }
5035: return(0);
5036: }
5038: /*@
5039: DMSetBasicAdjacency - Set the flags for determining variable influence, using either the default or field 0 if it is defined
5041: Not collective
5043: Input Parameters:
5044: + dm - The DM object
5045: . useCone - Flag for variable influence starting with the cone operation
5046: - useClosure - Flag for variable influence using transitive closure
5048: Notes:
5049: $ FEM: Two points p and q are adjacent if q \in closure(star(p)), useCone = PETSC_FALSE, useClosure = PETSC_TRUE
5050: $ FVM: Two points p and q are adjacent if q \in support(p+cone(p)), useCone = PETSC_TRUE, useClosure = PETSC_FALSE
5051: $ FVM++: Two points p and q are adjacent if q \in star(closure(p)), useCone = PETSC_TRUE, useClosure = PETSC_TRUE
5053: Level: developer
5055: .seealso: DMGetBasicAdjacency(), DMGetField(), DMSetField()
5056: @*/
5057: PetscErrorCode DMSetBasicAdjacency(DM dm, PetscBool useCone, PetscBool useClosure)
5058: {
5059: PetscInt Nf;
5064: DMGetNumFields(dm, &Nf);
5065: if (!Nf) {
5066: DMSetAdjacency(dm, PETSC_DEFAULT, useCone, useClosure);
5067: } else {
5068: DMSetAdjacency(dm, 0, useCone, useClosure);
5069: }
5070: return(0);
5071: }
5073: /* Complete labels that are being used for FEM BC */
5074: static PetscErrorCode DMCompleteBoundaryLabel_Internal(DM dm, PetscDS ds, PetscInt field, PetscInt bdNum, const char labelname[])
5075: {
5076: DMLabel label;
5077: PetscObject obj;
5078: PetscClassId id;
5079: PetscInt Nbd, bd;
5080: PetscBool isFE = PETSC_FALSE;
5081: PetscBool duplicate = PETSC_FALSE;
5085: DMGetField(dm, field, NULL, &obj);
5086: PetscObjectGetClassId(obj, &id);
5087: if (id == PETSCFE_CLASSID) isFE = PETSC_TRUE;
5088: DMGetLabel(dm, labelname, &label);
5089: if (isFE && label) {
5090: /* Only want to modify label once */
5091: PetscDSGetNumBoundary(ds, &Nbd);
5092: for (bd = 0; bd < PetscMin(Nbd, bdNum); ++bd) {
5093: const char *lname;
5095: PetscDSGetBoundary(ds, bd, NULL, NULL, &lname, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL);
5096: PetscStrcmp(lname, labelname, &duplicate);
5097: if (duplicate) break;
5098: }
5099: if (!duplicate) {
5100: DM plex;
5102: DMConvert(dm, DMPLEX, &plex);
5103: if (plex) {DMPlexLabelComplete(plex, label);}
5104: DMDestroy(&plex);
5105: }
5106: }
5107: return(0);
5108: }
5110: static PetscErrorCode DMDSEnlarge_Static(DM dm, PetscInt NdsNew)
5111: {
5112: DMSpace *tmpd;
5113: PetscInt Nds = dm->Nds, s;
5117: if (Nds >= NdsNew) return(0);
5118: PetscMalloc1(NdsNew, &tmpd);
5119: for (s = 0; s < Nds; ++s) tmpd[s] = dm->probs[s];
5120: for (s = Nds; s < NdsNew; ++s) {tmpd[s].ds = NULL; tmpd[s].label = NULL; tmpd[s].fields = NULL;}
5121: PetscFree(dm->probs);
5122: dm->Nds = NdsNew;
5123: dm->probs = tmpd;
5124: return(0);
5125: }
5127: /*@
5128: DMGetNumDS - Get the number of discrete systems in the DM
5130: Not collective
5132: Input Parameter:
5133: . dm - The DM
5135: Output Parameter:
5136: . Nds - The number of PetscDS objects
5138: Level: intermediate
5140: .seealso: DMGetDS(), DMGetCellDS()
5141: @*/
5142: PetscErrorCode DMGetNumDS(DM dm, PetscInt *Nds)
5143: {
5147: *Nds = dm->Nds;
5148: return(0);
5149: }
5151: /*@
5152: DMClearDS - Remove all discrete systems from the DM
5154: Logically collective on dm
5156: Input Parameter:
5157: . dm - The DM
5159: Level: intermediate
5161: .seealso: DMGetNumDS(), DMGetDS(), DMSetField()
5162: @*/
5163: PetscErrorCode DMClearDS(DM dm)
5164: {
5165: PetscInt s;
5170: for (s = 0; s < dm->Nds; ++s) {
5171: PetscDSDestroy(&dm->probs[s].ds);
5172: DMLabelDestroy(&dm->probs[s].label);
5173: ISDestroy(&dm->probs[s].fields);
5174: }
5175: PetscFree(dm->probs);
5176: dm->probs = NULL;
5177: dm->Nds = 0;
5178: return(0);
5179: }
5181: /*@
5182: DMGetDS - Get the default PetscDS
5184: Not collective
5186: Input Parameter:
5187: . dm - The DM
5189: Output Parameter:
5190: . prob - The default PetscDS
5192: Level: intermediate
5194: .seealso: DMGetCellDS(), DMGetRegionDS()
5195: @*/
5196: PetscErrorCode DMGetDS(DM dm, PetscDS *prob)
5197: {
5203: if (dm->Nds <= 0) {
5204: PetscDS ds;
5206: PetscDSCreate(PetscObjectComm((PetscObject) dm), &ds);
5207: DMSetRegionDS(dm, NULL, NULL, ds);
5208: PetscDSDestroy(&ds);
5209: }
5210: *prob = dm->probs[0].ds;
5211: return(0);
5212: }
5214: /*@
5215: DMGetCellDS - Get the PetscDS defined on a given cell
5217: Not collective
5219: Input Parameters:
5220: + dm - The DM
5221: - point - Cell for the DS
5223: Output Parameter:
5224: . prob - The PetscDS defined on the given cell
5226: Level: developer
5228: .seealso: DMGetDS(), DMSetRegionDS()
5229: @*/
5230: PetscErrorCode DMGetCellDS(DM dm, PetscInt point, PetscDS *prob)
5231: {
5232: PetscDS probDef = NULL;
5233: PetscInt s;
5239: if (point < 0) SETERRQ1(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Mesh point cannot be negative: %D", point);
5240: *prob = NULL;
5241: for (s = 0; s < dm->Nds; ++s) {
5242: PetscInt val;
5244: if (!dm->probs[s].label) {probDef = dm->probs[s].ds;}
5245: else {
5246: DMLabelGetValue(dm->probs[s].label, point, &val);
5247: if (val >= 0) {*prob = dm->probs[s].ds; break;}
5248: }
5249: }
5250: if (!*prob) *prob = probDef;
5251: return(0);
5252: }
5254: /*@
5255: DMGetRegionDS - Get the PetscDS for a given mesh region, defined by a DMLabel
5257: Not collective
5259: Input Parameters:
5260: + dm - The DM
5261: - label - The DMLabel defining the mesh region, or NULL for the entire mesh
5263: Output Parameters:
5264: + fields - The IS containing the DM field numbers for the fields in this DS, or NULL
5265: - prob - The PetscDS defined on the given region, or NULL
5267: Note: If the label is missing, this function returns an error
5269: Level: advanced
5271: .seealso: DMGetRegionNumDS(), DMSetRegionDS(), DMGetDS(), DMGetCellDS()
5272: @*/
5273: PetscErrorCode DMGetRegionDS(DM dm, DMLabel label, IS *fields, PetscDS *ds)
5274: {
5275: PetscInt Nds = dm->Nds, s;
5282: for (s = 0; s < Nds; ++s) {
5283: if (dm->probs[s].label == label) {
5284: if (fields) *fields = dm->probs[s].fields;
5285: if (ds) *ds = dm->probs[s].ds;
5286: return(0);
5287: }
5288: }
5289: return(0);
5290: }
5292: /*@
5293: DMSetRegionDS - Set the PetscDS for a given mesh region, defined by a DMLabel
5295: Collective on dm
5297: Input Parameters:
5298: + dm - The DM
5299: . label - The DMLabel defining the mesh region, or NULL for the entire mesh
5300: . fields - The IS containing the DM field numbers for the fields in this DS, or NULL for all fields
5301: - prob - The PetscDS defined on the given cell
5303: Note: If the label has a DS defined, it will be replaced. Otherwise, it will be added to the DM. If DS is replaced,
5304: the fields argument is ignored.
5306: Level: advanced
5308: .seealso: DMGetRegionDS(), DMSetRegionNumDS(), DMGetDS(), DMGetCellDS()
5309: @*/
5310: PetscErrorCode DMSetRegionDS(DM dm, DMLabel label, IS fields, PetscDS ds)
5311: {
5312: PetscInt Nds = dm->Nds, s;
5319: for (s = 0; s < Nds; ++s) {
5320: if (dm->probs[s].label == label) {
5321: PetscDSDestroy(&dm->probs[s].ds);
5322: dm->probs[s].ds = ds;
5323: return(0);
5324: }
5325: }
5326: DMDSEnlarge_Static(dm, Nds+1);
5327: PetscObjectReference((PetscObject) label);
5328: PetscObjectReference((PetscObject) fields);
5329: PetscObjectReference((PetscObject) ds);
5330: if (!label) {
5331: /* Put the NULL label at the front, so it is returned as the default */
5332: for (s = Nds-1; s >=0; --s) dm->probs[s+1] = dm->probs[s];
5333: Nds = 0;
5334: }
5335: dm->probs[Nds].label = label;
5336: dm->probs[Nds].fields = fields;
5337: dm->probs[Nds].ds = ds;
5338: return(0);
5339: }
5341: /*@
5342: DMGetRegionNumDS - Get the PetscDS for a given mesh region, defined by the region number
5344: Not collective
5346: Input Parameters:
5347: + dm - The DM
5348: - num - The region number, in [0, Nds)
5350: Output Parameters:
5351: + label - The region label, or NULL
5352: . fields - The IS containing the DM field numbers for the fields in this DS, or NULL
5353: - ds - The PetscDS defined on the given region, or NULL
5355: Level: advanced
5357: .seealso: DMGetRegionDS(), DMSetRegionDS(), DMGetDS(), DMGetCellDS()
5358: @*/
5359: PetscErrorCode DMGetRegionNumDS(DM dm, PetscInt num, DMLabel *label, IS *fields, PetscDS *ds)
5360: {
5361: PetscInt Nds;
5366: DMGetNumDS(dm, &Nds);
5367: if ((num < 0) || (num >= Nds)) SETERRQ2(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Region number %D is not in [0, %D)", num, Nds);
5368: if (label) {
5370: *label = dm->probs[num].label;
5371: }
5372: if (fields) {
5374: *fields = dm->probs[num].fields;
5375: }
5376: if (ds) {
5378: *ds = dm->probs[num].ds;
5379: }
5380: return(0);
5381: }
5383: /*@
5384: DMSetRegionNumDS - Set the PetscDS for a given mesh region, defined by the region number
5386: Not collective
5388: Input Parameters:
5389: + dm - The DM
5390: . num - The region number, in [0, Nds)
5391: . label - The region label, or NULL
5392: . fields - The IS containing the DM field numbers for the fields in this DS, or NULL to prevent setting
5393: - ds - The PetscDS defined on the given region, or NULL to prevent setting
5395: Level: advanced
5397: .seealso: DMGetRegionDS(), DMSetRegionDS(), DMGetDS(), DMGetCellDS()
5398: @*/
5399: PetscErrorCode DMSetRegionNumDS(DM dm, PetscInt num, DMLabel label, IS fields, PetscDS ds)
5400: {
5401: PetscInt Nds;
5407: DMGetNumDS(dm, &Nds);
5408: if ((num < 0) || (num >= Nds)) SETERRQ2(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Region number %D is not in [0, %D)", num, Nds);
5409: PetscObjectReference((PetscObject) label);
5410: DMLabelDestroy(&dm->probs[num].label);
5411: dm->probs[num].label = label;
5412: if (fields) {
5414: PetscObjectReference((PetscObject) fields);
5415: ISDestroy(&dm->probs[num].fields);
5416: dm->probs[num].fields = fields;
5417: }
5418: if (ds) {
5420: PetscObjectReference((PetscObject) ds);
5421: PetscDSDestroy(&dm->probs[num].ds);
5422: dm->probs[num].ds = ds;
5423: }
5424: return(0);
5425: }
5427: /*@
5428: DMFindRegionNum - Find the region number for a given PetscDS, or -1 if it is not found.
5430: Not collective
5432: Input Parameters:
5433: + dm - The DM
5434: - ds - The PetscDS defined on the given region
5436: Output Parameter:
5437: . num - The region number, in [0, Nds), or -1 if not found
5439: Level: advanced
5441: .seealso: DMGetRegionNumDS(), DMGetRegionDS(), DMSetRegionDS(), DMGetDS(), DMGetCellDS()
5442: @*/
5443: PetscErrorCode DMFindRegionNum(DM dm, PetscDS ds, PetscInt *num)
5444: {
5445: PetscInt Nds, n;
5452: DMGetNumDS(dm, &Nds);
5453: for (n = 0; n < Nds; ++n) if (ds == dm->probs[n].ds) break;
5454: if (n >= Nds) *num = -1;
5455: else *num = n;
5456: return(0);
5457: }
5459: /*@
5460: DMCreateDS - Create the discrete systems for the DM based upon the fields added to the DM
5462: Collective on dm
5464: Input Parameter:
5465: . dm - The DM
5467: Note: If the label has a DS defined, it will be replaced. Otherwise, it will be added to the DM.
5469: Level: intermediate
5471: .seealso: DMSetField, DMAddField(), DMGetDS(), DMGetCellDS(), DMGetRegionDS(), DMSetRegionDS()
5472: @*/
5473: PetscErrorCode DMCreateDS(DM dm)
5474: {
5475: MPI_Comm comm;
5476: PetscDS dsDef;
5477: DMLabel *labelSet;
5478: PetscInt dE, Nf = dm->Nf, f, s, Nl, l, Ndef, k;
5479: PetscBool doSetup = PETSC_TRUE, flg;
5484: if (!dm->fields) return(0);
5485: PetscObjectGetComm((PetscObject) dm, &comm);
5486: DMGetCoordinateDim(dm, &dE);
5487: /* Determine how many regions we have */
5488: PetscMalloc1(Nf, &labelSet);
5489: Nl = 0;
5490: Ndef = 0;
5491: for (f = 0; f < Nf; ++f) {
5492: DMLabel label = dm->fields[f].label;
5493: PetscInt l;
5495: if (!label) {++Ndef; continue;}
5496: for (l = 0; l < Nl; ++l) if (label == labelSet[l]) break;
5497: if (l < Nl) continue;
5498: labelSet[Nl++] = label;
5499: }
5500: /* Create default DS if there are no labels to intersect with */
5501: DMGetRegionDS(dm, NULL, NULL, &dsDef);
5502: if (!dsDef && Ndef && !Nl) {
5503: IS fields;
5504: PetscInt *fld, nf;
5506: for (f = 0, nf = 0; f < Nf; ++f) if (!dm->fields[f].label) ++nf;
5507: if (nf) {
5508: PetscMalloc1(nf, &fld);
5509: for (f = 0, nf = 0; f < Nf; ++f) if (!dm->fields[f].label) fld[nf++] = f;
5510: ISCreate(PETSC_COMM_SELF, &fields);
5511: PetscObjectSetOptionsPrefix((PetscObject) fields, "dm_fields_");
5512: ISSetType(fields, ISGENERAL);
5513: ISGeneralSetIndices(fields, nf, fld, PETSC_OWN_POINTER);
5515: PetscDSCreate(comm, &dsDef);
5516: DMSetRegionDS(dm, NULL, fields, dsDef);
5517: PetscDSDestroy(&dsDef);
5518: ISDestroy(&fields);
5519: }
5520: }
5521: DMGetRegionDS(dm, NULL, NULL, &dsDef);
5522: if (dsDef) {PetscDSSetCoordinateDimension(dsDef, dE);}
5523: /* Intersect labels with default fields */
5524: if (Ndef && Nl) {
5525: DM plex;
5526: DMLabel cellLabel;
5527: IS fieldIS, allcellIS, defcellIS = NULL;
5528: PetscInt *fields;
5529: const PetscInt *cells;
5530: PetscInt depth, nf = 0, n, c;
5532: DMConvert(dm, DMPLEX, &plex);
5533: DMPlexGetDepth(plex, &depth);
5534: DMGetStratumIS(plex, "dim", depth, &allcellIS);
5535: if (!allcellIS) {DMGetStratumIS(plex, "depth", depth, &allcellIS);}
5536: for (l = 0; l < Nl; ++l) {
5537: DMLabel label = labelSet[l];
5538: IS pointIS;
5540: ISDestroy(&defcellIS);
5541: DMLabelGetStratumIS(label, 1, &pointIS);
5542: ISDifference(allcellIS, pointIS, &defcellIS);
5543: ISDestroy(&pointIS);
5544: }
5545: ISDestroy(&allcellIS);
5547: DMLabelCreate(PETSC_COMM_SELF, "defaultCells", &cellLabel);
5548: ISGetLocalSize(defcellIS, &n);
5549: ISGetIndices(defcellIS, &cells);
5550: for (c = 0; c < n; ++c) {DMLabelSetValue(cellLabel, cells[c], 1);}
5551: ISRestoreIndices(defcellIS, &cells);
5552: ISDestroy(&defcellIS);
5553: DMPlexLabelComplete(plex, cellLabel);
5555: PetscMalloc1(Ndef, &fields);
5556: for (f = 0; f < Nf; ++f) if (!dm->fields[f].label) fields[nf++] = f;
5557: ISCreate(PETSC_COMM_SELF, &fieldIS);
5558: PetscObjectSetOptionsPrefix((PetscObject) fieldIS, "dm_fields_");
5559: ISSetType(fieldIS, ISGENERAL);
5560: ISGeneralSetIndices(fieldIS, nf, fields, PETSC_OWN_POINTER);
5562: PetscDSCreate(comm, &dsDef);
5563: DMSetRegionDS(dm, cellLabel, fieldIS, dsDef);
5564: DMLabelDestroy(&cellLabel);
5565: PetscDSSetCoordinateDimension(dsDef, dE);
5566: PetscDSDestroy(&dsDef);
5567: ISDestroy(&fieldIS);
5568: DMDestroy(&plex);
5569: }
5570: /* Create label DSes
5571: - WE ONLY SUPPORT IDENTICAL OR DISJOINT LABELS
5572: */
5573: /* TODO Should check that labels are disjoint */
5574: for (l = 0; l < Nl; ++l) {
5575: DMLabel label = labelSet[l];
5576: PetscDS ds;
5577: IS fields;
5578: PetscInt *fld, nf;
5580: PetscDSCreate(comm, &ds);
5581: for (f = 0, nf = 0; f < Nf; ++f) if (label == dm->fields[f].label || !dm->fields[f].label) ++nf;
5582: PetscMalloc1(nf, &fld);
5583: for (f = 0, nf = 0; f < Nf; ++f) if (label == dm->fields[f].label || !dm->fields[f].label) fld[nf++] = f;
5584: ISCreate(PETSC_COMM_SELF, &fields);
5585: PetscObjectSetOptionsPrefix((PetscObject) fields, "dm_fields_");
5586: ISSetType(fields, ISGENERAL);
5587: ISGeneralSetIndices(fields, nf, fld, PETSC_OWN_POINTER);
5588: DMSetRegionDS(dm, label, fields, ds);
5589: ISDestroy(&fields);
5590: PetscDSSetCoordinateDimension(ds, dE);
5591: {
5592: DMPolytopeType ct;
5593: PetscInt lStart, lEnd;
5594: PetscBool isHybridLocal = PETSC_FALSE, isHybrid;
5596: DMLabelGetBounds(label, &lStart, &lEnd);
5597: if (lStart >= 0) {
5598: DMPlexGetCellType(dm, lStart, &ct);
5599: switch (ct) {
5600: case DM_POLYTOPE_POINT_PRISM_TENSOR:
5601: case DM_POLYTOPE_SEG_PRISM_TENSOR:
5602: case DM_POLYTOPE_TRI_PRISM_TENSOR:
5603: case DM_POLYTOPE_QUAD_PRISM_TENSOR:
5604: isHybridLocal = PETSC_TRUE;break;
5605: default: break;
5606: }
5607: }
5608: MPI_Allreduce(&isHybridLocal, &isHybrid, 1, MPIU_BOOL, MPI_LOR, comm);
5609: PetscDSSetHybrid(ds, isHybrid);
5610: }
5611: PetscDSDestroy(&ds);
5612: }
5613: PetscFree(labelSet);
5614: /* Set fields in DSes */
5615: for (s = 0; s < dm->Nds; ++s) {
5616: PetscDS ds = dm->probs[s].ds;
5617: IS fields = dm->probs[s].fields;
5618: const PetscInt *fld;
5619: PetscInt nf;
5621: ISGetLocalSize(fields, &nf);
5622: ISGetIndices(fields, &fld);
5623: for (f = 0; f < nf; ++f) {
5624: PetscObject disc = dm->fields[fld[f]].disc;
5625: PetscBool isHybrid;
5626: PetscClassId id;
5628: PetscDSGetHybrid(ds, &isHybrid);
5629: /* If this is a cohesive cell, then it needs the lower dimensional discretization */
5630: if (isHybrid && f < nf-1) {PetscFEGetHeightSubspace((PetscFE) disc, 1, (PetscFE *) &disc);}
5631: PetscDSSetDiscretization(ds, f, disc);
5632: /* We allow people to have placeholder fields and construct the Section by hand */
5633: PetscObjectGetClassId(disc, &id);
5634: if ((id != PETSCFE_CLASSID) && (id != PETSCFV_CLASSID)) doSetup = PETSC_FALSE;
5635: }
5636: ISRestoreIndices(fields, &fld);
5637: }
5638: /* Allow k-jet tabulation */
5639: PetscOptionsGetInt(NULL, ((PetscObject) dm)->prefix, "-dm_ds_jet_degree", &k, &flg);
5640: if (flg) {
5641: for (s = 0; s < dm->Nds; ++s) {
5642: PetscDS ds = dm->probs[s].ds;
5643: PetscInt Nf, f;
5645: PetscDSGetNumFields(ds, &Nf);
5646: for (f = 0; f < Nf; ++f) {PetscDSSetJetDegree(ds, f, k);}
5647: }
5648: }
5649: /* Setup DSes */
5650: if (doSetup) {
5651: for (s = 0; s < dm->Nds; ++s) {PetscDSSetUp(dm->probs[s].ds);}
5652: }
5653: return(0);
5654: }
5656: /*@
5657: DMComputeExactSolution - Compute the exact solution for a given DM, using the PetscDS information.
5659: Collective on DM
5661: Input Parameters:
5662: + dm - The DM
5663: - time - The time
5665: Output Parameters:
5666: + u - The vector will be filled with exact solution values, or NULL
5667: - u_t - The vector will be filled with the time derivative of exact solution values, or NULL
5669: Note: The user must call PetscDSSetExactSolution() beforehand
5671: Level: developer
5673: .seealso: PetscDSSetExactSolution()
5674: @*/
5675: PetscErrorCode DMComputeExactSolution(DM dm, PetscReal time, Vec u, Vec u_t)
5676: {
5677: PetscErrorCode (**exacts)(PetscInt, PetscReal, const PetscReal x[], PetscInt, PetscScalar *u, void *ctx);
5678: void **ectxs;
5679: PetscInt Nf, Nds, s;
5680: PetscErrorCode ierr;
5686: DMGetNumFields(dm, &Nf);
5687: PetscMalloc2(Nf, &exacts, Nf, &ectxs);
5688: DMGetNumDS(dm, &Nds);
5689: for (s = 0; s < Nds; ++s) {
5690: PetscDS ds;
5691: DMLabel label;
5692: IS fieldIS;
5693: const PetscInt *fields, id = 1;
5694: PetscInt dsNf, f;
5696: DMGetRegionNumDS(dm, s, &label, &fieldIS, &ds);
5697: PetscDSGetNumFields(ds, &dsNf);
5698: ISGetIndices(fieldIS, &fields);
5699: PetscArrayzero(exacts, Nf);
5700: PetscArrayzero(ectxs, Nf);
5701: if (u) {
5702: for (f = 0; f < dsNf; ++f) {
5703: const PetscInt field = fields[f];
5704: PetscDSGetExactSolution(ds, field, &exacts[field], &ectxs[field]);
5705: }
5706: ISRestoreIndices(fieldIS, &fields);
5707: if (label) {
5708: DMProjectFunctionLabel(dm, time, label, 1, &id, 0, NULL, exacts, ectxs, INSERT_ALL_VALUES, u);
5709: } else {
5710: DMProjectFunction(dm, time, exacts, ectxs, INSERT_ALL_VALUES, u);
5711: }
5712: }
5713: if (u_t) {
5714: PetscArrayzero(exacts, Nf);
5715: PetscArrayzero(ectxs, Nf);
5716: for (f = 0; f < dsNf; ++f) {
5717: const PetscInt field = fields[f];
5718: PetscDSGetExactSolutionTimeDerivative(ds, field, &exacts[field], &ectxs[field]);
5719: }
5720: ISRestoreIndices(fieldIS, &fields);
5721: if (label) {
5722: DMProjectFunctionLabel(dm, time, label, 1, &id, 0, NULL, exacts, ectxs, INSERT_ALL_VALUES, u_t);
5723: } else {
5724: DMProjectFunction(dm, time, exacts, ectxs, INSERT_ALL_VALUES, u_t);
5725: }
5726: }
5727: }
5728: if (u) {
5729: PetscObjectSetName((PetscObject) u, "Exact Solution");
5730: PetscObjectSetOptionsPrefix((PetscObject) u, "exact_");
5731: }
5732: if (u_t) {
5733: PetscObjectSetName((PetscObject) u, "Exact Solution Time Derivative");
5734: PetscObjectSetOptionsPrefix((PetscObject) u_t, "exact_t_");
5735: }
5736: PetscFree2(exacts, ectxs);
5737: return(0);
5738: }
5740: /*@
5741: DMCopyDS - Copy the discrete systems for the DM into another DM
5743: Collective on dm
5745: Input Parameter:
5746: . dm - The DM
5748: Output Parameter:
5749: . newdm - The DM
5751: Level: advanced
5753: .seealso: DMCopyFields(), DMAddField(), DMGetDS(), DMGetCellDS(), DMGetRegionDS(), DMSetRegionDS()
5754: @*/
5755: PetscErrorCode DMCopyDS(DM dm, DM newdm)
5756: {
5757: PetscInt Nds, s;
5761: if (dm == newdm) return(0);
5762: DMGetNumDS(dm, &Nds);
5763: DMClearDS(newdm);
5764: for (s = 0; s < Nds; ++s) {
5765: DMLabel label;
5766: IS fields;
5767: PetscDS ds;
5768: PetscInt Nbd, bd;
5770: DMGetRegionNumDS(dm, s, &label, &fields, &ds);
5771: DMSetRegionDS(newdm, label, fields, ds);
5772: PetscDSGetNumBoundary(ds, &Nbd);
5773: for (bd = 0; bd < Nbd; ++bd) {
5774: const char *labelname, *name;
5775: PetscInt field;
5777: /* Do not check if label exists here, since p4est calls this for the reference tree which does not have the labels */
5778: PetscDSGetBoundary(ds, bd, NULL, &name, &labelname, &field, NULL, NULL, NULL, NULL, NULL, NULL, NULL);
5779: DMCompleteBoundaryLabel_Internal(newdm, ds, field, bd, labelname);
5780: }
5781: }
5782: return(0);
5783: }
5785: /*@
5786: DMCopyDisc - Copy the fields and discrete systems for the DM into another DM
5788: Collective on dm
5790: Input Parameter:
5791: . dm - The DM
5793: Output Parameter:
5794: . newdm - The DM
5796: Level: advanced
5798: .seealso: DMCopyFields(), DMCopyDS()
5799: @*/
5800: PetscErrorCode DMCopyDisc(DM dm, DM newdm)
5801: {
5805: DMCopyFields(dm, newdm);
5806: DMCopyDS(dm, newdm);
5807: return(0);
5808: }
5810: PetscErrorCode DMRestrictHook_Coordinates(DM dm,DM dmc,void *ctx)
5811: {
5812: DM dm_coord,dmc_coord;
5814: Vec coords,ccoords;
5815: Mat inject;
5817: DMGetCoordinateDM(dm,&dm_coord);
5818: DMGetCoordinateDM(dmc,&dmc_coord);
5819: DMGetCoordinates(dm,&coords);
5820: DMGetCoordinates(dmc,&ccoords);
5821: if (coords && !ccoords) {
5822: DMCreateGlobalVector(dmc_coord,&ccoords);
5823: PetscObjectSetName((PetscObject)ccoords,"coordinates");
5824: DMCreateInjection(dmc_coord,dm_coord,&inject);
5825: MatRestrict(inject,coords,ccoords);
5826: MatDestroy(&inject);
5827: DMSetCoordinates(dmc,ccoords);
5828: VecDestroy(&ccoords);
5829: }
5830: return(0);
5831: }
5833: static PetscErrorCode DMSubDomainHook_Coordinates(DM dm,DM subdm,void *ctx)
5834: {
5835: DM dm_coord,subdm_coord;
5837: Vec coords,ccoords,clcoords;
5838: VecScatter *scat_i,*scat_g;
5840: DMGetCoordinateDM(dm,&dm_coord);
5841: DMGetCoordinateDM(subdm,&subdm_coord);
5842: DMGetCoordinates(dm,&coords);
5843: DMGetCoordinates(subdm,&ccoords);
5844: if (coords && !ccoords) {
5845: DMCreateGlobalVector(subdm_coord,&ccoords);
5846: PetscObjectSetName((PetscObject)ccoords,"coordinates");
5847: DMCreateLocalVector(subdm_coord,&clcoords);
5848: PetscObjectSetName((PetscObject)clcoords,"coordinates");
5849: DMCreateDomainDecompositionScatters(dm_coord,1,&subdm_coord,NULL,&scat_i,&scat_g);
5850: VecScatterBegin(scat_i[0],coords,ccoords,INSERT_VALUES,SCATTER_FORWARD);
5851: VecScatterEnd(scat_i[0],coords,ccoords,INSERT_VALUES,SCATTER_FORWARD);
5852: VecScatterBegin(scat_g[0],coords,clcoords,INSERT_VALUES,SCATTER_FORWARD);
5853: VecScatterEnd(scat_g[0],coords,clcoords,INSERT_VALUES,SCATTER_FORWARD);
5854: DMSetCoordinates(subdm,ccoords);
5855: DMSetCoordinatesLocal(subdm,clcoords);
5856: VecScatterDestroy(&scat_i[0]);
5857: VecScatterDestroy(&scat_g[0]);
5858: VecDestroy(&ccoords);
5859: VecDestroy(&clcoords);
5860: PetscFree(scat_i);
5861: PetscFree(scat_g);
5862: }
5863: return(0);
5864: }
5866: /*@
5867: DMGetDimension - Return the topological dimension of the DM
5869: Not collective
5871: Input Parameter:
5872: . dm - The DM
5874: Output Parameter:
5875: . dim - The topological dimension
5877: Level: beginner
5879: .seealso: DMSetDimension(), DMCreate()
5880: @*/
5881: PetscErrorCode DMGetDimension(DM dm, PetscInt *dim)
5882: {
5886: *dim = dm->dim;
5887: return(0);
5888: }
5890: /*@
5891: DMSetDimension - Set the topological dimension of the DM
5893: Collective on dm
5895: Input Parameters:
5896: + dm - The DM
5897: - dim - The topological dimension
5899: Level: beginner
5901: .seealso: DMGetDimension(), DMCreate()
5902: @*/
5903: PetscErrorCode DMSetDimension(DM dm, PetscInt dim)
5904: {
5905: PetscDS ds;
5911: dm->dim = dim;
5912: DMGetDS(dm, &ds);
5913: if (ds->dimEmbed < 0) {PetscDSSetCoordinateDimension(ds, dm->dim);}
5914: return(0);
5915: }
5917: /*@
5918: DMGetDimPoints - Get the half-open interval for all points of a given dimension
5920: Collective on dm
5922: Input Parameters:
5923: + dm - the DM
5924: - dim - the dimension
5926: Output Parameters:
5927: + pStart - The first point of the given dimension
5928: - pEnd - The first point following points of the given dimension
5930: Note:
5931: The points are vertices in the Hasse diagram encoding the topology. This is explained in
5932: https://arxiv.org/abs/0908.4427. If no points exist of this dimension in the storage scheme,
5933: then the interval is empty.
5935: Level: intermediate
5937: .seealso: DMPLEX, DMPlexGetDepthStratum(), DMPlexGetHeightStratum()
5938: @*/
5939: PetscErrorCode DMGetDimPoints(DM dm, PetscInt dim, PetscInt *pStart, PetscInt *pEnd)
5940: {
5941: PetscInt d;
5946: DMGetDimension(dm, &d);
5947: if ((dim < 0) || (dim > d)) SETERRQ2(PetscObjectComm((PetscObject) dm), PETSC_ERR_ARG_OUTOFRANGE, "Invalid dimension %d 1", dim, d);
5948: if (!dm->ops->getdimpoints) SETERRQ1(PetscObjectComm((PetscObject)dm), PETSC_ERR_SUP, "DM type %s does not implement DMGetDimPoints",((PetscObject)dm)->type_name);
5949: (*dm->ops->getdimpoints)(dm, dim, pStart, pEnd);
5950: return(0);
5951: }
5953: /*@
5954: DMSetCoordinates - Sets into the DM a global vector that holds the coordinates
5956: Collective on dm
5958: Input Parameters:
5959: + dm - the DM
5960: - c - coordinate vector
5962: Notes:
5963: The coordinates do include those for ghost points, which are in the local vector.
5965: The vector c should be destroyed by the caller.
5967: Level: intermediate
5969: .seealso: DMSetCoordinatesLocal(), DMGetCoordinates(), DMGetCoordinatesLocal(), DMGetCoordinateDM(), DMDASetUniformCoordinates()
5970: @*/
5971: PetscErrorCode DMSetCoordinates(DM dm, Vec c)
5972: {
5978: PetscObjectReference((PetscObject) c);
5979: VecDestroy(&dm->coordinates);
5980: dm->coordinates = c;
5981: VecDestroy(&dm->coordinatesLocal);
5982: DMCoarsenHookAdd(dm,DMRestrictHook_Coordinates,NULL,NULL);
5983: DMSubDomainHookAdd(dm,DMSubDomainHook_Coordinates,NULL,NULL);
5984: return(0);
5985: }
5987: /*@
5988: DMSetCoordinatesLocal - Sets into the DM a local vector that holds the coordinates
5990: Not collective
5992: Input Parameters:
5993: + dm - the DM
5994: - c - coordinate vector
5996: Notes:
5997: The coordinates of ghost points can be set using DMSetCoordinates()
5998: followed by DMGetCoordinatesLocal(). This is intended to enable the
5999: setting of ghost coordinates outside of the domain.
6001: The vector c should be destroyed by the caller.
6003: Level: intermediate
6005: .seealso: DMGetCoordinatesLocal(), DMSetCoordinates(), DMGetCoordinates(), DMGetCoordinateDM()
6006: @*/
6007: PetscErrorCode DMSetCoordinatesLocal(DM dm, Vec c)
6008: {
6014: PetscObjectReference((PetscObject) c);
6015: VecDestroy(&dm->coordinatesLocal);
6017: dm->coordinatesLocal = c;
6019: VecDestroy(&dm->coordinates);
6020: return(0);
6021: }
6023: /*@
6024: DMGetCoordinates - Gets a global vector with the coordinates associated with the DM.
6026: Collective on dm
6028: Input Parameter:
6029: . dm - the DM
6031: Output Parameter:
6032: . c - global coordinate vector
6034: Note:
6035: This is a borrowed reference, so the user should NOT destroy this vector. When the DM is
6036: destroyed the array will no longer be valid.
6038: Each process has only the local coordinates (does NOT have the ghost coordinates).
6040: For DMDA, in two and three dimensions coordinates are interlaced (x_0,y_0,x_1,y_1,...)
6041: and (x_0,y_0,z_0,x_1,y_1,z_1...)
6043: Level: intermediate
6045: .seealso: DMSetCoordinates(), DMGetCoordinatesLocal(), DMGetCoordinateDM(), DMDASetUniformCoordinates()
6046: @*/
6047: PetscErrorCode DMGetCoordinates(DM dm, Vec *c)
6048: {
6054: if (!dm->coordinates && dm->coordinatesLocal) {
6055: DM cdm = NULL;
6056: PetscBool localized;
6058: DMGetCoordinateDM(dm, &cdm);
6059: DMCreateGlobalVector(cdm, &dm->coordinates);
6060: DMGetCoordinatesLocalized(dm, &localized);
6061: /* Block size is not correctly set by CreateGlobalVector() if coordinates are localized */
6062: if (localized) {
6063: PetscInt cdim;
6065: DMGetCoordinateDim(dm, &cdim);
6066: VecSetBlockSize(dm->coordinates, cdim);
6067: }
6068: PetscObjectSetName((PetscObject) dm->coordinates, "coordinates");
6069: DMLocalToGlobalBegin(cdm, dm->coordinatesLocal, INSERT_VALUES, dm->coordinates);
6070: DMLocalToGlobalEnd(cdm, dm->coordinatesLocal, INSERT_VALUES, dm->coordinates);
6071: }
6072: *c = dm->coordinates;
6073: return(0);
6074: }
6076: /*@
6077: DMGetCoordinatesLocalSetUp - Prepares a local vector of coordinates, so that DMGetCoordinatesLocalNoncollective() can be used as non-collective afterwards.
6079: Collective on dm
6081: Input Parameter:
6082: . dm - the DM
6084: Level: advanced
6086: .seealso: DMGetCoordinatesLocalNoncollective()
6087: @*/
6088: PetscErrorCode DMGetCoordinatesLocalSetUp(DM dm)
6089: {
6094: if (!dm->coordinatesLocal && dm->coordinates) {
6095: DM cdm = NULL;
6096: PetscBool localized;
6098: DMGetCoordinateDM(dm, &cdm);
6099: DMCreateLocalVector(cdm, &dm->coordinatesLocal);
6100: DMGetCoordinatesLocalized(dm, &localized);
6101: /* Block size is not correctly set by CreateLocalVector() if coordinates are localized */
6102: if (localized) {
6103: PetscInt cdim;
6105: DMGetCoordinateDim(dm, &cdim);
6106: VecSetBlockSize(dm->coordinates, cdim);
6107: }
6108: PetscObjectSetName((PetscObject) dm->coordinatesLocal, "coordinates");
6109: DMGlobalToLocalBegin(cdm, dm->coordinates, INSERT_VALUES, dm->coordinatesLocal);
6110: DMGlobalToLocalEnd(cdm, dm->coordinates, INSERT_VALUES, dm->coordinatesLocal);
6111: }
6112: return(0);
6113: }
6115: /*@
6116: DMGetCoordinatesLocal - Gets a local vector with the coordinates associated with the DM.
6118: Collective on dm
6120: Input Parameter:
6121: . dm - the DM
6123: Output Parameter:
6124: . c - coordinate vector
6126: Note:
6127: This is a borrowed reference, so the user should NOT destroy this vector
6129: Each process has the local and ghost coordinates
6131: For DMDA, in two and three dimensions coordinates are interlaced (x_0,y_0,x_1,y_1,...)
6132: and (x_0,y_0,z_0,x_1,y_1,z_1...)
6134: Level: intermediate
6136: .seealso: DMSetCoordinatesLocal(), DMGetCoordinates(), DMSetCoordinates(), DMGetCoordinateDM(), DMGetCoordinatesLocalNoncollective()
6137: @*/
6138: PetscErrorCode DMGetCoordinatesLocal(DM dm, Vec *c)
6139: {
6145: DMGetCoordinatesLocalSetUp(dm);
6146: *c = dm->coordinatesLocal;
6147: return(0);
6148: }
6150: /*@
6151: DMGetCoordinatesLocalNoncollective - Non-collective version of DMGetCoordinatesLocal(). Fails if global coordinates have been set and DMGetCoordinatesLocalSetUp() not called.
6153: Not collective
6155: Input Parameter:
6156: . dm - the DM
6158: Output Parameter:
6159: . c - coordinate vector
6161: Level: advanced
6163: .seealso: DMGetCoordinatesLocalSetUp(), DMGetCoordinatesLocal(), DMSetCoordinatesLocal(), DMGetCoordinates(), DMSetCoordinates(), DMGetCoordinateDM()
6164: @*/
6165: PetscErrorCode DMGetCoordinatesLocalNoncollective(DM dm, Vec *c)
6166: {
6170: if (!dm->coordinatesLocal && dm->coordinates) SETERRQ(PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_WRONGSTATE, "DMGetCoordinatesLocalSetUp() has not been called");
6171: *c = dm->coordinatesLocal;
6172: return(0);
6173: }
6175: /*@
6176: DMGetCoordinatesLocalTuple - Gets a local vector with the coordinates of specified points and section describing its layout.
6178: Not collective
6180: Input Parameter:
6181: + dm - the DM
6182: - p - the IS of points whose coordinates will be returned
6184: Output Parameter:
6185: + pCoordSection - the PetscSection describing the layout of pCoord, i.e. each point corresponds to one point in p, and DOFs correspond to coordinates
6186: - pCoord - the Vec with coordinates of points in p
6188: Note:
6189: DMGetCoordinatesLocalSetUp() must be called first. This function employs DMGetCoordinatesLocalNoncollective() so it is not collective.
6191: This creates a new vector, so the user SHOULD destroy this vector
6193: Each process has the local and ghost coordinates
6195: For DMDA, in two and three dimensions coordinates are interlaced (x_0,y_0,x_1,y_1,...)
6196: and (x_0,y_0,z_0,x_1,y_1,z_1...)
6198: Level: advanced
6200: .seealso: DMSetCoordinatesLocal(), DMGetCoordinatesLocal(), DMGetCoordinatesLocalNoncollective(), DMGetCoordinatesLocalSetUp(), DMGetCoordinates(), DMSetCoordinates(), DMGetCoordinateDM()
6201: @*/
6202: PetscErrorCode DMGetCoordinatesLocalTuple(DM dm, IS p, PetscSection *pCoordSection, Vec *pCoord)
6203: {
6204: PetscSection cs, newcs;
6205: Vec coords;
6206: const PetscScalar *arr;
6207: PetscScalar *newarr=NULL;
6208: PetscInt n;
6209: PetscErrorCode ierr;
6216: if (!dm->coordinatesLocal) SETERRQ(PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_WRONGSTATE, "DMGetCoordinatesLocalSetUp() has not been called or coordinates not set");
6217: if (!dm->coordinateDM || !dm->coordinateDM->localSection) SETERRQ(PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_WRONGSTATE, "DM not supported");
6218: cs = dm->coordinateDM->localSection;
6219: coords = dm->coordinatesLocal;
6220: VecGetArrayRead(coords, &arr);
6221: PetscSectionExtractDofsFromArray(cs, MPIU_SCALAR, arr, p, &newcs, pCoord ? ((void**)&newarr) : NULL);
6222: VecRestoreArrayRead(coords, &arr);
6223: if (pCoord) {
6224: PetscSectionGetStorageSize(newcs, &n);
6225: /* set array in two steps to mimic PETSC_OWN_POINTER */
6226: VecCreateSeqWithArray(PetscObjectComm((PetscObject)p), 1, n, NULL, pCoord);
6227: VecReplaceArray(*pCoord, newarr);
6228: } else {
6229: PetscFree(newarr);
6230: }
6231: if (pCoordSection) {*pCoordSection = newcs;}
6232: else {PetscSectionDestroy(&newcs);}
6233: return(0);
6234: }
6236: PetscErrorCode DMGetCoordinateField(DM dm, DMField *field)
6237: {
6243: if (!dm->coordinateField) {
6244: if (dm->ops->createcoordinatefield) {
6245: (*dm->ops->createcoordinatefield)(dm,&dm->coordinateField);
6246: }
6247: }
6248: *field = dm->coordinateField;
6249: return(0);
6250: }
6252: PetscErrorCode DMSetCoordinateField(DM dm, DMField field)
6253: {
6259: PetscObjectReference((PetscObject)field);
6260: DMFieldDestroy(&dm->coordinateField);
6261: dm->coordinateField = field;
6262: return(0);
6263: }
6265: /*@
6266: DMGetCoordinateDM - Gets the DM that prescribes coordinate layout and scatters between global and local coordinates
6268: Collective on dm
6270: Input Parameter:
6271: . dm - the DM
6273: Output Parameter:
6274: . cdm - coordinate DM
6276: Level: intermediate
6278: .seealso: DMSetCoordinateDM(), DMSetCoordinates(), DMSetCoordinatesLocal(), DMGetCoordinates(), DMGetCoordinatesLocal()
6279: @*/
6280: PetscErrorCode DMGetCoordinateDM(DM dm, DM *cdm)
6281: {
6287: if (!dm->coordinateDM) {
6288: DM cdm;
6290: if (!dm->ops->createcoordinatedm) SETERRQ(PetscObjectComm((PetscObject)dm), PETSC_ERR_SUP, "Unable to create coordinates for this DM");
6291: (*dm->ops->createcoordinatedm)(dm, &cdm);
6292: /* Just in case the DM sets the coordinate DM when creating it (DMP4est can do this, because it may not setup
6293: * until the call to CreateCoordinateDM) */
6294: DMDestroy(&dm->coordinateDM);
6295: dm->coordinateDM = cdm;
6296: }
6297: *cdm = dm->coordinateDM;
6298: return(0);
6299: }
6301: /*@
6302: DMSetCoordinateDM - Sets the DM that prescribes coordinate layout and scatters between global and local coordinates
6304: Logically Collective on dm
6306: Input Parameters:
6307: + dm - the DM
6308: - cdm - coordinate DM
6310: Level: intermediate
6312: .seealso: DMGetCoordinateDM(), DMSetCoordinates(), DMSetCoordinatesLocal(), DMGetCoordinates(), DMGetCoordinatesLocal()
6313: @*/
6314: PetscErrorCode DMSetCoordinateDM(DM dm, DM cdm)
6315: {
6321: PetscObjectReference((PetscObject)cdm);
6322: DMDestroy(&dm->coordinateDM);
6323: dm->coordinateDM = cdm;
6324: return(0);
6325: }
6327: /*@
6328: DMGetCoordinateDim - Retrieve the dimension of embedding space for coordinate values.
6330: Not Collective
6332: Input Parameter:
6333: . dm - The DM object
6335: Output Parameter:
6336: . dim - The embedding dimension
6338: Level: intermediate
6340: .seealso: DMSetCoordinateDim(), DMGetCoordinateSection(), DMGetCoordinateDM(), DMGetLocalSection(), DMSetLocalSection()
6341: @*/
6342: PetscErrorCode DMGetCoordinateDim(DM dm, PetscInt *dim)
6343: {
6347: if (dm->dimEmbed == PETSC_DEFAULT) {
6348: dm->dimEmbed = dm->dim;
6349: }
6350: *dim = dm->dimEmbed;
6351: return(0);
6352: }
6354: /*@
6355: DMSetCoordinateDim - Set the dimension of the embedding space for coordinate values.
6357: Not Collective
6359: Input Parameters:
6360: + dm - The DM object
6361: - dim - The embedding dimension
6363: Level: intermediate
6365: .seealso: DMGetCoordinateDim(), DMSetCoordinateSection(), DMGetCoordinateSection(), DMGetLocalSection(), DMSetLocalSection()
6366: @*/
6367: PetscErrorCode DMSetCoordinateDim(DM dm, PetscInt dim)
6368: {
6369: PetscDS ds;
6374: dm->dimEmbed = dim;
6375: DMGetDS(dm, &ds);
6376: PetscDSSetCoordinateDimension(ds, dim);
6377: return(0);
6378: }
6380: /*@
6381: DMGetCoordinateSection - Retrieve the layout of coordinate values over the mesh.
6383: Collective on dm
6385: Input Parameter:
6386: . dm - The DM object
6388: Output Parameter:
6389: . section - The PetscSection object
6391: Level: intermediate
6393: .seealso: DMGetCoordinateDM(), DMGetLocalSection(), DMSetLocalSection()
6394: @*/
6395: PetscErrorCode DMGetCoordinateSection(DM dm, PetscSection *section)
6396: {
6397: DM cdm;
6403: DMGetCoordinateDM(dm, &cdm);
6404: DMGetLocalSection(cdm, section);
6405: return(0);
6406: }
6408: /*@
6409: DMSetCoordinateSection - Set the layout of coordinate values over the mesh.
6411: Not Collective
6413: Input Parameters:
6414: + dm - The DM object
6415: . dim - The embedding dimension, or PETSC_DETERMINE
6416: - section - The PetscSection object
6418: Level: intermediate
6420: .seealso: DMGetCoordinateSection(), DMGetLocalSection(), DMSetLocalSection()
6421: @*/
6422: PetscErrorCode DMSetCoordinateSection(DM dm, PetscInt dim, PetscSection section)
6423: {
6424: DM cdm;
6430: DMGetCoordinateDM(dm, &cdm);
6431: DMSetLocalSection(cdm, section);
6432: if (dim == PETSC_DETERMINE) {
6433: PetscInt d = PETSC_DEFAULT;
6434: PetscInt pStart, pEnd, vStart, vEnd, v, dd;
6436: PetscSectionGetChart(section, &pStart, &pEnd);
6437: DMGetDimPoints(dm, 0, &vStart, &vEnd);
6438: pStart = PetscMax(vStart, pStart);
6439: pEnd = PetscMin(vEnd, pEnd);
6440: for (v = pStart; v < pEnd; ++v) {
6441: PetscSectionGetDof(section, v, &dd);
6442: if (dd) {d = dd; break;}
6443: }
6444: if (d >= 0) {DMSetCoordinateDim(dm, d);}
6445: }
6446: return(0);
6447: }
6449: /*@
6450: DMProjectCoordinates - Project coordinates to a different space
6452: Input Parameters:
6453: + dm - The DM object
6454: - disc - The new coordinate discretization
6456: Level: intermediate
6458: .seealso: DMGetCoordinateField()
6459: @*/
6460: PetscErrorCode DMProjectCoordinates(DM dm, PetscFE disc)
6461: {
6462: PetscObject discOld;
6463: PetscClassId classid;
6464: DM cdmOld,cdmNew;
6465: Vec coordsOld,coordsNew;
6466: Mat matInterp;
6473: DMGetCoordinateDM(dm, &cdmOld);
6474: /* Check current discretization is compatible */
6475: DMGetField(cdmOld, 0, NULL, &discOld);
6476: PetscObjectGetClassId(discOld, &classid);
6477: if (classid != PETSCFE_CLASSID) {
6478: if (classid == PETSC_CONTAINER_CLASSID) {
6479: PetscFE feLinear;
6480: DMPolytopeType ct;
6481: PetscInt dim, dE, cStart;
6482: PetscBool simplex;
6484: /* Assume linear vertex coordinates */
6485: DMGetDimension(dm, &dim);
6486: DMGetCoordinateDim(dm, &dE);
6487: DMPlexGetHeightStratum(cdmOld, 0, &cStart, NULL);
6488: DMPlexGetCellType(dm, cStart, &ct);
6489: switch (ct) {
6490: case DM_POLYTOPE_TRI_PRISM:
6491: case DM_POLYTOPE_TRI_PRISM_TENSOR:
6492: SETERRQ(PETSC_COMM_SELF, PETSC_ERR_SUP, "Cannot autoamtically create coordinate space for prisms");
6493: default: break;
6494: }
6495: simplex = DMPolytopeTypeGetNumVertices(ct) == DMPolytopeTypeGetDim(ct)+1 ? PETSC_TRUE : PETSC_FALSE;
6496: PetscFECreateLagrange(PETSC_COMM_SELF, dim, dE, simplex, 1, -1, &feLinear);
6497: DMSetField(cdmOld, 0, NULL, (PetscObject) feLinear);
6498: PetscFEDestroy(&feLinear);
6499: DMCreateDS(cdmOld);
6500: } else {
6501: const char *discname;
6503: PetscObjectGetType(discOld, &discname);
6504: SETERRQ1(PetscObjectComm(discOld), PETSC_ERR_SUP, "Discretization type %s not supported", discname);
6505: }
6506: }
6507: /* Make a fresh clone of the coordinate DM */
6508: DMClone(cdmOld, &cdmNew);
6509: DMSetField(cdmNew, 0, NULL, (PetscObject) disc);
6510: DMCreateDS(cdmNew);
6511: /* Project the coordinate vector from old to new space */
6512: DMGetCoordinates(dm, &coordsOld);
6513: DMCreateGlobalVector(cdmNew, &coordsNew);
6514: DMCreateInterpolation(cdmOld, cdmNew, &matInterp, NULL);
6515: MatInterpolate(matInterp, coordsOld, coordsNew);
6516: MatDestroy(&matInterp);
6517: /* Set new coordinate structures */
6518: DMSetCoordinateField(dm, NULL);
6519: DMSetCoordinateDM(dm, cdmNew);
6520: DMSetCoordinates(dm, coordsNew);
6521: VecDestroy(&coordsNew);
6522: DMDestroy(&cdmNew);
6523: return(0);
6524: }
6526: /*@C
6527: DMGetPeriodicity - Get the description of mesh periodicity
6529: Input Parameters:
6530: . dm - The DM object
6532: Output Parameters:
6533: + per - Whether the DM is periodic or not
6534: . maxCell - Over distances greater than this, we can assume a point has crossed over to another sheet, when trying to localize cell coordinates
6535: . L - If we assume the mesh is a torus, this is the length of each coordinate
6536: - bd - This describes the type of periodicity in each topological dimension
6538: Level: developer
6540: .seealso: DMGetPeriodicity()
6541: @*/
6542: PetscErrorCode DMGetPeriodicity(DM dm, PetscBool *per, const PetscReal **maxCell, const PetscReal **L, const DMBoundaryType **bd)
6543: {
6546: if (per) *per = dm->periodic;
6547: if (L) *L = dm->L;
6548: if (maxCell) *maxCell = dm->maxCell;
6549: if (bd) *bd = dm->bdtype;
6550: return(0);
6551: }
6553: /*@C
6554: DMSetPeriodicity - Set the description of mesh periodicity
6556: Input Parameters:
6557: + dm - The DM object
6558: . per - Whether the DM is periodic or not.
6559: . maxCell - Over distances greater than this, we can assume a point has crossed over to another sheet, when trying to localize cell coordinates. Pass NULL to remove such information.
6560: . L - If we assume the mesh is a torus, this is the length of each coordinate
6561: - bd - This describes the type of periodicity in each topological dimension
6563: Notes: If per is PETSC_TRUE and maxCell is not provided, coordinates need to be already localized, or must be localized by hand by the user.
6565: Level: developer
6567: .seealso: DMGetPeriodicity()
6568: @*/
6569: PetscErrorCode DMSetPeriodicity(DM dm, PetscBool per, const PetscReal maxCell[], const PetscReal L[], const DMBoundaryType bd[])
6570: {
6571: PetscInt dim, d;
6580: DMGetDimension(dm, &dim);
6581: if (maxCell) {
6582: if (!dm->maxCell) {PetscMalloc1(dim, &dm->maxCell);}
6583: for (d = 0; d < dim; ++d) dm->maxCell[d] = maxCell[d];
6584: } else { /* remove maxCell information to disable automatic computation of localized vertices */
6585: PetscFree(dm->maxCell);
6586: }
6588: if (L) {
6589: if (!dm->L) {PetscMalloc1(dim, &dm->L);}
6590: for (d = 0; d < dim; ++d) dm->L[d] = L[d];
6591: }
6592: if (bd) {
6593: if (!dm->bdtype) {PetscMalloc1(dim, &dm->bdtype);}
6594: for (d = 0; d < dim; ++d) dm->bdtype[d] = bd[d];
6595: }
6596: dm->periodic = per;
6597: return(0);
6598: }
6600: /*@
6601: DMLocalizeCoordinate - If a mesh is periodic (a torus with lengths L_i, some of which can be infinite), project the coordinate onto [0, L_i) in each dimension.
6603: Input Parameters:
6604: + dm - The DM
6605: . in - The input coordinate point (dim numbers)
6606: - endpoint - Include the endpoint L_i
6608: Output Parameter:
6609: . out - The localized coordinate point
6611: Level: developer
6613: .seealso: DMLocalizeCoordinates(), DMLocalizeAddCoordinate()
6614: @*/
6615: PetscErrorCode DMLocalizeCoordinate(DM dm, const PetscScalar in[], PetscBool endpoint, PetscScalar out[])
6616: {
6617: PetscInt dim, d;
6621: DMGetCoordinateDim(dm, &dim);
6622: if (!dm->maxCell) {
6623: for (d = 0; d < dim; ++d) out[d] = in[d];
6624: } else {
6625: if (endpoint) {
6626: for (d = 0; d < dim; ++d) {
6627: if ((PetscAbsReal(PetscRealPart(in[d])/dm->L[d] - PetscFloorReal(PetscRealPart(in[d])/dm->L[d])) < PETSC_SMALL) && (PetscRealPart(in[d])/dm->L[d] > PETSC_SMALL)) {
6628: out[d] = in[d] - dm->L[d]*(PetscFloorReal(PetscRealPart(in[d])/dm->L[d]) - 1);
6629: } else {
6630: out[d] = in[d] - dm->L[d]*PetscFloorReal(PetscRealPart(in[d])/dm->L[d]);
6631: }
6632: }
6633: } else {
6634: for (d = 0; d < dim; ++d) {
6635: out[d] = in[d] - dm->L[d]*PetscFloorReal(PetscRealPart(in[d])/dm->L[d]);
6636: }
6637: }
6638: }
6639: return(0);
6640: }
6642: /*
6643: DMLocalizeCoordinate_Internal - If a mesh is periodic, and the input point is far from the anchor, pick the coordinate sheet of the torus which moves it closer.
6645: Input Parameters:
6646: + dm - The DM
6647: . dim - The spatial dimension
6648: . anchor - The anchor point, the input point can be no more than maxCell away from it
6649: - in - The input coordinate point (dim numbers)
6651: Output Parameter:
6652: . out - The localized coordinate point
6654: Level: developer
6656: Note: This is meant to get a set of coordinates close to each other, as in a cell. The anchor is usually the one of the vertices on a containing cell
6658: .seealso: DMLocalizeCoordinates(), DMLocalizeAddCoordinate()
6659: */
6660: PetscErrorCode DMLocalizeCoordinate_Internal(DM dm, PetscInt dim, const PetscScalar anchor[], const PetscScalar in[], PetscScalar out[])
6661: {
6662: PetscInt d;
6665: if (!dm->maxCell) {
6666: for (d = 0; d < dim; ++d) out[d] = in[d];
6667: } else {
6668: for (d = 0; d < dim; ++d) {
6669: if ((dm->bdtype[d] != DM_BOUNDARY_NONE) && (PetscAbsScalar(anchor[d] - in[d]) > dm->maxCell[d])) {
6670: out[d] = PetscRealPart(anchor[d]) > PetscRealPart(in[d]) ? dm->L[d] + in[d] : in[d] - dm->L[d];
6671: } else {
6672: out[d] = in[d];
6673: }
6674: }
6675: }
6676: return(0);
6677: }
6679: PetscErrorCode DMLocalizeCoordinateReal_Internal(DM dm, PetscInt dim, const PetscReal anchor[], const PetscReal in[], PetscReal out[])
6680: {
6681: PetscInt d;
6684: if (!dm->maxCell) {
6685: for (d = 0; d < dim; ++d) out[d] = in[d];
6686: } else {
6687: for (d = 0; d < dim; ++d) {
6688: if ((dm->bdtype[d] != DM_BOUNDARY_NONE) && (PetscAbsReal(anchor[d] - in[d]) > dm->maxCell[d])) {
6689: out[d] = anchor[d] > in[d] ? dm->L[d] + in[d] : in[d] - dm->L[d];
6690: } else {
6691: out[d] = in[d];
6692: }
6693: }
6694: }
6695: return(0);
6696: }
6698: /*
6699: DMLocalizeAddCoordinate_Internal - If a mesh is periodic, and the input point is far from the anchor, pick the coordinate sheet of the torus which moves it closer.
6701: Input Parameters:
6702: + dm - The DM
6703: . dim - The spatial dimension
6704: . anchor - The anchor point, the input point can be no more than maxCell away from it
6705: . in - The input coordinate delta (dim numbers)
6706: - out - The input coordinate point (dim numbers)
6708: Output Parameter:
6709: . out - The localized coordinate in + out
6711: Level: developer
6713: Note: This is meant to get a set of coordinates close to each other, as in a cell. The anchor is usually the one of the vertices on a containing cell
6715: .seealso: DMLocalizeCoordinates(), DMLocalizeCoordinate()
6716: */
6717: PetscErrorCode DMLocalizeAddCoordinate_Internal(DM dm, PetscInt dim, const PetscScalar anchor[], const PetscScalar in[], PetscScalar out[])
6718: {
6719: PetscInt d;
6722: if (!dm->maxCell) {
6723: for (d = 0; d < dim; ++d) out[d] += in[d];
6724: } else {
6725: for (d = 0; d < dim; ++d) {
6726: const PetscReal maxC = dm->maxCell[d];
6728: if ((dm->bdtype[d] != DM_BOUNDARY_NONE) && (PetscAbsScalar(anchor[d] - in[d]) > maxC)) {
6729: const PetscScalar newCoord = PetscRealPart(anchor[d]) > PetscRealPart(in[d]) ? dm->L[d] + in[d] : in[d] - dm->L[d];
6731: if (PetscAbsScalar(newCoord - anchor[d]) > maxC)
6732: SETERRQ4(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "%D-Coordinate %g more than %g away from anchor %g", d, (double) PetscRealPart(in[d]), (double) maxC, (double) PetscRealPart(anchor[d]));
6733: out[d] += newCoord;
6734: } else {
6735: out[d] += in[d];
6736: }
6737: }
6738: }
6739: return(0);
6740: }
6742: /*@
6743: DMGetCoordinatesLocalizedLocal - Check if the DM coordinates have been localized for cells on this process
6745: Not collective
6747: Input Parameter:
6748: . dm - The DM
6750: Output Parameter:
6751: areLocalized - True if localized
6753: Level: developer
6755: .seealso: DMLocalizeCoordinates(), DMGetCoordinatesLocalized(), DMSetPeriodicity()
6756: @*/
6757: PetscErrorCode DMGetCoordinatesLocalizedLocal(DM dm,PetscBool *areLocalized)
6758: {
6759: DM cdm;
6760: PetscSection coordSection;
6761: PetscInt cStart, cEnd, sStart, sEnd, c, dof;
6762: PetscBool isPlex, alreadyLocalized;
6768: *areLocalized = PETSC_FALSE;
6770: /* We need some generic way of refering to cells/vertices */
6771: DMGetCoordinateDM(dm, &cdm);
6772: PetscObjectTypeCompare((PetscObject) cdm, DMPLEX, &isPlex);
6773: if (!isPlex) return(0);
6775: DMGetCoordinateSection(dm, &coordSection);
6776: DMPlexGetHeightStratum(cdm, 0, &cStart, &cEnd);
6777: PetscSectionGetChart(coordSection, &sStart, &sEnd);
6778: alreadyLocalized = PETSC_FALSE;
6779: for (c = cStart; c < cEnd; ++c) {
6780: if (c < sStart || c >= sEnd) continue;
6781: PetscSectionGetDof(coordSection, c, &dof);
6782: if (dof) { alreadyLocalized = PETSC_TRUE; break; }
6783: }
6784: *areLocalized = alreadyLocalized;
6785: return(0);
6786: }
6788: /*@
6789: DMGetCoordinatesLocalized - Check if the DM coordinates have been localized for cells
6791: Collective on dm
6793: Input Parameter:
6794: . dm - The DM
6796: Output Parameter:
6797: areLocalized - True if localized
6799: Level: developer
6801: .seealso: DMLocalizeCoordinates(), DMSetPeriodicity(), DMGetCoordinatesLocalizedLocal()
6802: @*/
6803: PetscErrorCode DMGetCoordinatesLocalized(DM dm,PetscBool *areLocalized)
6804: {
6805: PetscBool localized;
6811: DMGetCoordinatesLocalizedLocal(dm,&localized);
6812: MPIU_Allreduce(&localized,areLocalized,1,MPIU_BOOL,MPI_LOR,PetscObjectComm((PetscObject)dm));
6813: return(0);
6814: }
6816: /*@
6817: DMLocalizeCoordinates - If a mesh is periodic, create local coordinates for cells having periodic faces
6819: Collective on dm
6821: Input Parameter:
6822: . dm - The DM
6824: Level: developer
6826: .seealso: DMSetPeriodicity(), DMLocalizeCoordinate(), DMLocalizeAddCoordinate()
6827: @*/
6828: PetscErrorCode DMLocalizeCoordinates(DM dm)
6829: {
6830: DM cdm;
6831: PetscSection coordSection, cSection;
6832: Vec coordinates, cVec;
6833: PetscScalar *coords, *coords2, *anchor, *localized;
6834: PetscInt Nc, vStart, vEnd, v, sStart, sEnd, newStart = PETSC_MAX_INT, newEnd = PETSC_MIN_INT, dof, d, off, off2, bs, coordSize;
6835: PetscBool alreadyLocalized, alreadyLocalizedGlobal;
6836: PetscInt maxHeight = 0, h;
6837: PetscInt *pStart = NULL, *pEnd = NULL;
6842: if (!dm->periodic) return(0);
6843: DMGetCoordinatesLocalized(dm, &alreadyLocalized);
6844: if (alreadyLocalized) return(0);
6846: /* We need some generic way of refering to cells/vertices */
6847: DMGetCoordinateDM(dm, &cdm);
6848: {
6849: PetscBool isplex;
6851: PetscObjectTypeCompare((PetscObject) cdm, DMPLEX, &isplex);
6852: if (isplex) {
6853: DMPlexGetDepthStratum(cdm, 0, &vStart, &vEnd);
6854: DMPlexGetMaxProjectionHeight(cdm,&maxHeight);
6855: DMGetWorkArray(dm,2*(maxHeight + 1),MPIU_INT,&pStart);
6856: pEnd = &pStart[maxHeight + 1];
6857: newStart = vStart;
6858: newEnd = vEnd;
6859: for (h = 0; h <= maxHeight; h++) {
6860: DMPlexGetHeightStratum(cdm, h, &pStart[h], &pEnd[h]);
6861: newStart = PetscMin(newStart,pStart[h]);
6862: newEnd = PetscMax(newEnd,pEnd[h]);
6863: }
6864: } else SETERRQ(PetscObjectComm((PetscObject) cdm), PETSC_ERR_ARG_WRONG, "Coordinate localization requires a DMPLEX coordinate DM");
6865: }
6866: DMGetCoordinatesLocal(dm, &coordinates);
6867: if (!coordinates) SETERRQ(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"Missing local coordinates vector");
6868: DMGetCoordinateSection(dm, &coordSection);
6869: VecGetBlockSize(coordinates, &bs);
6870: PetscSectionGetChart(coordSection,&sStart,&sEnd);
6872: PetscSectionCreate(PetscObjectComm((PetscObject) dm), &cSection);
6873: PetscSectionSetNumFields(cSection, 1);
6874: PetscSectionGetFieldComponents(coordSection, 0, &Nc);
6875: PetscSectionSetFieldComponents(cSection, 0, Nc);
6876: PetscSectionSetChart(cSection, newStart, newEnd);
6878: DMGetWorkArray(dm, 2 * bs, MPIU_SCALAR, &anchor);
6879: localized = &anchor[bs];
6880: alreadyLocalized = alreadyLocalizedGlobal = PETSC_TRUE;
6881: for (h = 0; h <= maxHeight; h++) {
6882: PetscInt cStart = pStart[h], cEnd = pEnd[h], c;
6884: for (c = cStart; c < cEnd; ++c) {
6885: PetscScalar *cellCoords = NULL;
6886: PetscInt b;
6888: if (c < sStart || c >= sEnd) alreadyLocalized = PETSC_FALSE;
6889: DMPlexVecGetClosure(cdm, coordSection, coordinates, c, &dof, &cellCoords);
6890: for (b = 0; b < bs; ++b) anchor[b] = cellCoords[b];
6891: for (d = 0; d < dof/bs; ++d) {
6892: DMLocalizeCoordinate_Internal(dm, bs, anchor, &cellCoords[d*bs], localized);
6893: for (b = 0; b < bs; b++) {
6894: if (cellCoords[d*bs + b] != localized[b]) break;
6895: }
6896: if (b < bs) break;
6897: }
6898: if (d < dof/bs) {
6899: if (c >= sStart && c < sEnd) {
6900: PetscInt cdof;
6902: PetscSectionGetDof(coordSection, c, &cdof);
6903: if (cdof != dof) alreadyLocalized = PETSC_FALSE;
6904: }
6905: PetscSectionSetDof(cSection, c, dof);
6906: PetscSectionSetFieldDof(cSection, c, 0, dof);
6907: }
6908: DMPlexVecRestoreClosure(cdm, coordSection, coordinates, c, &dof, &cellCoords);
6909: }
6910: }
6911: MPI_Allreduce(&alreadyLocalized,&alreadyLocalizedGlobal,1,MPIU_BOOL,MPI_LAND,PetscObjectComm((PetscObject)dm));
6912: if (alreadyLocalizedGlobal) {
6913: DMRestoreWorkArray(dm, 2 * bs, MPIU_SCALAR, &anchor);
6914: PetscSectionDestroy(&cSection);
6915: DMRestoreWorkArray(dm,2*(maxHeight + 1),MPIU_INT,&pStart);
6916: return(0);
6917: }
6918: for (v = vStart; v < vEnd; ++v) {
6919: PetscSectionGetDof(coordSection, v, &dof);
6920: PetscSectionSetDof(cSection, v, dof);
6921: PetscSectionSetFieldDof(cSection, v, 0, dof);
6922: }
6923: PetscSectionSetUp(cSection);
6924: PetscSectionGetStorageSize(cSection, &coordSize);
6925: VecCreate(PETSC_COMM_SELF, &cVec);
6926: PetscObjectSetName((PetscObject)cVec,"coordinates");
6927: VecSetBlockSize(cVec, bs);
6928: VecSetSizes(cVec, coordSize, PETSC_DETERMINE);
6929: VecSetType(cVec, VECSTANDARD);
6930: VecGetArrayRead(coordinates, (const PetscScalar**)&coords);
6931: VecGetArray(cVec, &coords2);
6932: for (v = vStart; v < vEnd; ++v) {
6933: PetscSectionGetDof(coordSection, v, &dof);
6934: PetscSectionGetOffset(coordSection, v, &off);
6935: PetscSectionGetOffset(cSection, v, &off2);
6936: for (d = 0; d < dof; ++d) coords2[off2+d] = coords[off+d];
6937: }
6938: for (h = 0; h <= maxHeight; h++) {
6939: PetscInt cStart = pStart[h], cEnd = pEnd[h], c;
6941: for (c = cStart; c < cEnd; ++c) {
6942: PetscScalar *cellCoords = NULL;
6943: PetscInt b, cdof;
6945: PetscSectionGetDof(cSection,c,&cdof);
6946: if (!cdof) continue;
6947: DMPlexVecGetClosure(cdm, coordSection, coordinates, c, &dof, &cellCoords);
6948: PetscSectionGetOffset(cSection, c, &off2);
6949: for (b = 0; b < bs; ++b) anchor[b] = cellCoords[b];
6950: for (d = 0; d < dof/bs; ++d) {DMLocalizeCoordinate_Internal(dm, bs, anchor, &cellCoords[d*bs], &coords2[off2+d*bs]);}
6951: DMPlexVecRestoreClosure(cdm, coordSection, coordinates, c, &dof, &cellCoords);
6952: }
6953: }
6954: DMRestoreWorkArray(dm, 2 * bs, MPIU_SCALAR, &anchor);
6955: DMRestoreWorkArray(dm,2*(maxHeight + 1),MPIU_INT,&pStart);
6956: VecRestoreArrayRead(coordinates, (const PetscScalar**)&coords);
6957: VecRestoreArray(cVec, &coords2);
6958: DMSetCoordinateSection(dm, PETSC_DETERMINE, cSection);
6959: DMSetCoordinatesLocal(dm, cVec);
6960: VecDestroy(&cVec);
6961: PetscSectionDestroy(&cSection);
6962: return(0);
6963: }
6965: /*@
6966: DMLocatePoints - Locate the points in v in the mesh and return a PetscSF of the containing cells
6968: Collective on v (see explanation below)
6970: Input Parameters:
6971: + dm - The DM
6972: . v - The Vec of points
6973: . ltype - The type of point location, e.g. DM_POINTLOCATION_NONE or DM_POINTLOCATION_NEAREST
6974: - cells - Points to either NULL, or a PetscSF with guesses for which cells contain each point.
6976: Output Parameter:
6977: + v - The Vec of points, which now contains the nearest mesh points to the given points if DM_POINTLOCATION_NEAREST is used
6978: - cells - The PetscSF containing the ranks and local indices of the containing points.
6981: Level: developer
6983: Notes:
6984: To do a search of the local cells of the mesh, v should have PETSC_COMM_SELF as its communicator.
6985: To do a search of all the cells in the distributed mesh, v should have the same communicator as dm.
6987: If *cellSF is NULL on input, a PetscSF will be created.
6988: If *cellSF is not NULL on input, it should point to an existing PetscSF, whose graph will be used as initial guesses.
6990: An array that maps each point to its containing cell can be obtained with
6992: $ const PetscSFNode *cells;
6993: $ PetscInt nFound;
6994: $ const PetscInt *found;
6995: $
6996: $ PetscSFGetGraph(cellSF,NULL,&nFound,&found,&cells);
6998: Where cells[i].rank is the rank of the cell containing point found[i] (or i if found == NULL), and cells[i].index is
6999: the index of the cell in its rank's local numbering.
7001: .seealso: DMSetCoordinates(), DMSetCoordinatesLocal(), DMGetCoordinates(), DMGetCoordinatesLocal(), DMPointLocationType
7002: @*/
7003: PetscErrorCode DMLocatePoints(DM dm, Vec v, DMPointLocationType ltype, PetscSF *cellSF)
7004: {
7011: if (*cellSF) {
7012: PetscMPIInt result;
7015: MPI_Comm_compare(PetscObjectComm((PetscObject)v),PetscObjectComm((PetscObject)*cellSF),&result);
7016: if (result != MPI_IDENT && result != MPI_CONGRUENT) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"cellSF must have a communicator congruent to v's");
7017: } else {
7018: PetscSFCreate(PetscObjectComm((PetscObject)v),cellSF);
7019: }
7020: if (!dm->ops->locatepoints) SETERRQ(PetscObjectComm((PetscObject)dm), PETSC_ERR_SUP, "Point location not available for this DM");
7021: PetscLogEventBegin(DM_LocatePoints,dm,0,0,0);
7022: (*dm->ops->locatepoints)(dm,v,ltype,*cellSF);
7023: PetscLogEventEnd(DM_LocatePoints,dm,0,0,0);
7024: return(0);
7025: }
7027: /*@
7028: DMGetOutputDM - Retrieve the DM associated with the layout for output
7030: Collective on dm
7032: Input Parameter:
7033: . dm - The original DM
7035: Output Parameter:
7036: . odm - The DM which provides the layout for output
7038: Level: intermediate
7040: .seealso: VecView(), DMGetGlobalSection()
7041: @*/
7042: PetscErrorCode DMGetOutputDM(DM dm, DM *odm)
7043: {
7044: PetscSection section;
7045: PetscBool hasConstraints, ghasConstraints;
7051: DMGetLocalSection(dm, §ion);
7052: PetscSectionHasConstraints(section, &hasConstraints);
7053: MPI_Allreduce(&hasConstraints, &ghasConstraints, 1, MPIU_BOOL, MPI_LOR, PetscObjectComm((PetscObject) dm));
7054: if (!ghasConstraints) {
7055: *odm = dm;
7056: return(0);
7057: }
7058: if (!dm->dmBC) {
7059: PetscSection newSection, gsection;
7060: PetscSF sf;
7062: DMClone(dm, &dm->dmBC);
7063: DMCopyDisc(dm, dm->dmBC);
7064: PetscSectionClone(section, &newSection);
7065: DMSetLocalSection(dm->dmBC, newSection);
7066: PetscSectionDestroy(&newSection);
7067: DMGetPointSF(dm->dmBC, &sf);
7068: PetscSectionCreateGlobalSection(section, sf, PETSC_TRUE, PETSC_FALSE, &gsection);
7069: DMSetGlobalSection(dm->dmBC, gsection);
7070: PetscSectionDestroy(&gsection);
7071: }
7072: *odm = dm->dmBC;
7073: return(0);
7074: }
7076: /*@
7077: DMGetOutputSequenceNumber - Retrieve the sequence number/value for output
7079: Input Parameter:
7080: . dm - The original DM
7082: Output Parameters:
7083: + num - The output sequence number
7084: - val - The output sequence value
7086: Level: intermediate
7088: Note: This is intended for output that should appear in sequence, for instance
7089: a set of timesteps in an HDF5 file, or a set of realizations of a stochastic system.
7091: .seealso: VecView()
7092: @*/
7093: PetscErrorCode DMGetOutputSequenceNumber(DM dm, PetscInt *num, PetscReal *val)
7094: {
7099: return(0);
7100: }
7102: /*@
7103: DMSetOutputSequenceNumber - Set the sequence number/value for output
7105: Input Parameters:
7106: + dm - The original DM
7107: . num - The output sequence number
7108: - val - The output sequence value
7110: Level: intermediate
7112: Note: This is intended for output that should appear in sequence, for instance
7113: a set of timesteps in an HDF5 file, or a set of realizations of a stochastic system.
7115: .seealso: VecView()
7116: @*/
7117: PetscErrorCode DMSetOutputSequenceNumber(DM dm, PetscInt num, PetscReal val)
7118: {
7121: dm->outputSequenceNum = num;
7122: dm->outputSequenceVal = val;
7123: return(0);
7124: }
7126: /*@C
7127: DMOutputSequenceLoad - Retrieve the sequence value from a Viewer
7129: Input Parameters:
7130: + dm - The original DM
7131: . name - The sequence name
7132: - num - The output sequence number
7134: Output Parameter:
7135: . val - The output sequence value
7137: Level: intermediate
7139: Note: This is intended for output that should appear in sequence, for instance
7140: a set of timesteps in an HDF5 file, or a set of realizations of a stochastic system.
7142: .seealso: DMGetOutputSequenceNumber(), DMSetOutputSequenceNumber(), VecView()
7143: @*/
7144: PetscErrorCode DMOutputSequenceLoad(DM dm, PetscViewer viewer, const char *name, PetscInt num, PetscReal *val)
7145: {
7146: PetscBool ishdf5;
7153: PetscObjectTypeCompare((PetscObject) viewer, PETSCVIEWERHDF5, &ishdf5);
7154: if (ishdf5) {
7155: #if defined(PETSC_HAVE_HDF5)
7156: PetscScalar value;
7158: DMSequenceLoad_HDF5_Internal(dm, name, num, &value, viewer);
7159: *val = PetscRealPart(value);
7160: #endif
7161: } else SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Invalid viewer; open viewer with PetscViewerHDF5Open()");
7162: return(0);
7163: }
7165: /*@
7166: DMGetUseNatural - Get the flag for creating a mapping to the natural order on distribution
7168: Not collective
7170: Input Parameter:
7171: . dm - The DM
7173: Output Parameter:
7174: . useNatural - The flag to build the mapping to a natural order during distribution
7176: Level: beginner
7178: .seealso: DMSetUseNatural(), DMCreate()
7179: @*/
7180: PetscErrorCode DMGetUseNatural(DM dm, PetscBool *useNatural)
7181: {
7185: *useNatural = dm->useNatural;
7186: return(0);
7187: }
7189: /*@
7190: DMSetUseNatural - Set the flag for creating a mapping to the natural order after distribution
7192: Collective on dm
7194: Input Parameters:
7195: + dm - The DM
7196: - useNatural - The flag to build the mapping to a natural order during distribution
7198: Note: This also causes the map to be build after DMCreateSubDM() and DMCreateSuperDM()
7200: Level: beginner
7202: .seealso: DMGetUseNatural(), DMCreate(), DMPlexDistribute(), DMCreateSubDM(), DMCreateSuperDM()
7203: @*/
7204: PetscErrorCode DMSetUseNatural(DM dm, PetscBool useNatural)
7205: {
7209: dm->useNatural = useNatural;
7210: return(0);
7211: }
7214: /*@C
7215: DMCreateLabel - Create a label of the given name if it does not already exist
7217: Not Collective
7219: Input Parameters:
7220: + dm - The DM object
7221: - name - The label name
7223: Level: intermediate
7225: .seealso: DMLabelCreate(), DMHasLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()
7226: @*/
7227: PetscErrorCode DMCreateLabel(DM dm, const char name[])
7228: {
7229: PetscBool flg;
7230: DMLabel label;
7236: DMHasLabel(dm, name, &flg);
7237: if (!flg) {
7238: DMLabelCreate(PETSC_COMM_SELF, name, &label);
7239: DMAddLabel(dm, label);
7240: DMLabelDestroy(&label);
7241: }
7242: return(0);
7243: }
7245: /*@C
7246: DMCreateLabelAtIndex - Create a label of the given name at the iven index. If it already exists, move it to this index.
7248: Not Collective
7250: Input Parameters:
7251: + dm - The DM object
7252: . l - The index for the label
7253: - name - The label name
7255: Level: intermediate
7257: .seealso: DMCreateLabel(), DMLabelCreate(), DMHasLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()
7258: @*/
7259: PetscErrorCode DMCreateLabelAtIndex(DM dm, PetscInt l, const char name[])
7260: {
7261: DMLabelLink orig, prev = NULL;
7262: DMLabel label;
7263: PetscInt Nl, m;
7264: PetscBool flg, match;
7265: const char *lname;
7271: DMHasLabel(dm, name, &flg);
7272: if (!flg) {
7273: DMLabelCreate(PETSC_COMM_SELF, name, &label);
7274: DMAddLabel(dm, label);
7275: DMLabelDestroy(&label);
7276: }
7277: DMGetNumLabels(dm, &Nl);
7278: if (l >= Nl) SETERRQ2(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Label index %D must be in [0, %D)", l, Nl);
7279: for (m = 0, orig = dm->labels; m < Nl; ++m, prev = orig, orig = orig->next) {
7280: PetscObjectGetName((PetscObject) orig->label, &lname);
7281: PetscStrcmp(name, lname, &match);
7282: if (match) break;
7283: }
7284: if (m == l) return(0);
7285: if (!m) dm->labels = orig->next;
7286: else prev->next = orig->next;
7287: if (!l) {
7288: orig->next = dm->labels;
7289: dm->labels = orig;
7290: } else {
7291: for (m = 0, prev = dm->labels; m < l-1; ++m, prev = prev->next);
7292: orig->next = prev->next;
7293: prev->next = orig;
7294: }
7295: return(0);
7296: }
7298: /*@C
7299: DMGetLabelValue - Get the value in a Sieve Label for the given point, with 0 as the default
7301: Not Collective
7303: Input Parameters:
7304: + dm - The DM object
7305: . name - The label name
7306: - point - The mesh point
7308: Output Parameter:
7309: . value - The label value for this point, or -1 if the point is not in the label
7311: Level: beginner
7313: .seealso: DMLabelGetValue(), DMSetLabelValue(), DMGetStratumIS()
7314: @*/
7315: PetscErrorCode DMGetLabelValue(DM dm, const char name[], PetscInt point, PetscInt *value)
7316: {
7317: DMLabel label;
7323: DMGetLabel(dm, name, &label);
7324: if (!label) SETERRQ1(PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "No label named %s was found", name);
7325: DMLabelGetValue(label, point, value);
7326: return(0);
7327: }
7329: /*@C
7330: DMSetLabelValue - Add a point to a Sieve Label with given value
7332: Not Collective
7334: Input Parameters:
7335: + dm - The DM object
7336: . name - The label name
7337: . point - The mesh point
7338: - value - The label value for this point
7340: Output Parameter:
7342: Level: beginner
7344: .seealso: DMLabelSetValue(), DMGetStratumIS(), DMClearLabelValue()
7345: @*/
7346: PetscErrorCode DMSetLabelValue(DM dm, const char name[], PetscInt point, PetscInt value)
7347: {
7348: DMLabel label;
7354: DMGetLabel(dm, name, &label);
7355: if (!label) {
7356: DMCreateLabel(dm, name);
7357: DMGetLabel(dm, name, &label);
7358: }
7359: DMLabelSetValue(label, point, value);
7360: return(0);
7361: }
7363: /*@C
7364: DMClearLabelValue - Remove a point from a Sieve Label with given value
7366: Not Collective
7368: Input Parameters:
7369: + dm - The DM object
7370: . name - The label name
7371: . point - The mesh point
7372: - value - The label value for this point
7374: Output Parameter:
7376: Level: beginner
7378: .seealso: DMLabelClearValue(), DMSetLabelValue(), DMGetStratumIS()
7379: @*/
7380: PetscErrorCode DMClearLabelValue(DM dm, const char name[], PetscInt point, PetscInt value)
7381: {
7382: DMLabel label;
7388: DMGetLabel(dm, name, &label);
7389: if (!label) return(0);
7390: DMLabelClearValue(label, point, value);
7391: return(0);
7392: }
7394: /*@C
7395: DMGetLabelSize - Get the number of different integer ids in a Label
7397: Not Collective
7399: Input Parameters:
7400: + dm - The DM object
7401: - name - The label name
7403: Output Parameter:
7404: . size - The number of different integer ids, or 0 if the label does not exist
7406: Level: beginner
7408: .seealso: DMLabelGetNumValues(), DMSetLabelValue()
7409: @*/
7410: PetscErrorCode DMGetLabelSize(DM dm, const char name[], PetscInt *size)
7411: {
7412: DMLabel label;
7419: DMGetLabel(dm, name, &label);
7420: *size = 0;
7421: if (!label) return(0);
7422: DMLabelGetNumValues(label, size);
7423: return(0);
7424: }
7426: /*@C
7427: DMGetLabelIdIS - Get the integer ids in a label
7429: Not Collective
7431: Input Parameters:
7432: + mesh - The DM object
7433: - name - The label name
7435: Output Parameter:
7436: . ids - The integer ids, or NULL if the label does not exist
7438: Level: beginner
7440: .seealso: DMLabelGetValueIS(), DMGetLabelSize()
7441: @*/
7442: PetscErrorCode DMGetLabelIdIS(DM dm, const char name[], IS *ids)
7443: {
7444: DMLabel label;
7451: DMGetLabel(dm, name, &label);
7452: *ids = NULL;
7453: if (label) {
7454: DMLabelGetValueIS(label, ids);
7455: } else {
7456: /* returning an empty IS */
7457: ISCreateGeneral(PETSC_COMM_SELF,0,NULL,PETSC_USE_POINTER,ids);
7458: }
7459: return(0);
7460: }
7462: /*@C
7463: DMGetStratumSize - Get the number of points in a label stratum
7465: Not Collective
7467: Input Parameters:
7468: + dm - The DM object
7469: . name - The label name
7470: - value - The stratum value
7472: Output Parameter:
7473: . size - The stratum size
7475: Level: beginner
7477: .seealso: DMLabelGetStratumSize(), DMGetLabelSize(), DMGetLabelIds()
7478: @*/
7479: PetscErrorCode DMGetStratumSize(DM dm, const char name[], PetscInt value, PetscInt *size)
7480: {
7481: DMLabel label;
7488: DMGetLabel(dm, name, &label);
7489: *size = 0;
7490: if (!label) return(0);
7491: DMLabelGetStratumSize(label, value, size);
7492: return(0);
7493: }
7495: /*@C
7496: DMGetStratumIS - Get the points in a label stratum
7498: Not Collective
7500: Input Parameters:
7501: + dm - The DM object
7502: . name - The label name
7503: - value - The stratum value
7505: Output Parameter:
7506: . points - The stratum points, or NULL if the label does not exist or does not have that value
7508: Level: beginner
7510: .seealso: DMLabelGetStratumIS(), DMGetStratumSize()
7511: @*/
7512: PetscErrorCode DMGetStratumIS(DM dm, const char name[], PetscInt value, IS *points)
7513: {
7514: DMLabel label;
7521: DMGetLabel(dm, name, &label);
7522: *points = NULL;
7523: if (!label) return(0);
7524: DMLabelGetStratumIS(label, value, points);
7525: return(0);
7526: }
7528: /*@C
7529: DMSetStratumIS - Set the points in a label stratum
7531: Not Collective
7533: Input Parameters:
7534: + dm - The DM object
7535: . name - The label name
7536: . value - The stratum value
7537: - points - The stratum points
7539: Level: beginner
7541: .seealso: DMLabelSetStratumIS(), DMGetStratumSize()
7542: @*/
7543: PetscErrorCode DMSetStratumIS(DM dm, const char name[], PetscInt value, IS points)
7544: {
7545: DMLabel label;
7552: DMGetLabel(dm, name, &label);
7553: if (!label) return(0);
7554: DMLabelSetStratumIS(label, value, points);
7555: return(0);
7556: }
7558: /*@C
7559: DMClearLabelStratum - Remove all points from a stratum from a Sieve Label
7561: Not Collective
7563: Input Parameters:
7564: + dm - The DM object
7565: . name - The label name
7566: - value - The label value for this point
7568: Output Parameter:
7570: Level: beginner
7572: .seealso: DMLabelClearStratum(), DMSetLabelValue(), DMGetStratumIS(), DMClearLabelValue()
7573: @*/
7574: PetscErrorCode DMClearLabelStratum(DM dm, const char name[], PetscInt value)
7575: {
7576: DMLabel label;
7582: DMGetLabel(dm, name, &label);
7583: if (!label) return(0);
7584: DMLabelClearStratum(label, value);
7585: return(0);
7586: }
7588: /*@
7589: DMGetNumLabels - Return the number of labels defined by the mesh
7591: Not Collective
7593: Input Parameter:
7594: . dm - The DM object
7596: Output Parameter:
7597: . numLabels - the number of Labels
7599: Level: intermediate
7601: .seealso: DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()
7602: @*/
7603: PetscErrorCode DMGetNumLabels(DM dm, PetscInt *numLabels)
7604: {
7605: DMLabelLink next = dm->labels;
7606: PetscInt n = 0;
7611: while (next) {++n; next = next->next;}
7612: *numLabels = n;
7613: return(0);
7614: }
7616: /*@C
7617: DMGetLabelName - Return the name of nth label
7619: Not Collective
7621: Input Parameters:
7622: + dm - The DM object
7623: - n - the label number
7625: Output Parameter:
7626: . name - the label name
7628: Level: intermediate
7630: .seealso: DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()
7631: @*/
7632: PetscErrorCode DMGetLabelName(DM dm, PetscInt n, const char **name)
7633: {
7634: DMLabelLink next = dm->labels;
7635: PetscInt l = 0;
7641: while (next) {
7642: if (l == n) {
7643: PetscObjectGetName((PetscObject) next->label, name);
7644: return(0);
7645: }
7646: ++l;
7647: next = next->next;
7648: }
7649: SETERRQ1(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Label %D does not exist in this DM", n);
7650: }
7652: /*@C
7653: DMHasLabel - Determine whether the mesh has a label of a given name
7655: Not Collective
7657: Input Parameters:
7658: + dm - The DM object
7659: - name - The label name
7661: Output Parameter:
7662: . hasLabel - PETSC_TRUE if the label is present
7664: Level: intermediate
7666: .seealso: DMCreateLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()
7667: @*/
7668: PetscErrorCode DMHasLabel(DM dm, const char name[], PetscBool *hasLabel)
7669: {
7670: DMLabelLink next = dm->labels;
7671: const char *lname;
7678: *hasLabel = PETSC_FALSE;
7679: while (next) {
7680: PetscObjectGetName((PetscObject) next->label, &lname);
7681: PetscStrcmp(name, lname, hasLabel);
7682: if (*hasLabel) break;
7683: next = next->next;
7684: }
7685: return(0);
7686: }
7688: /*@C
7689: DMGetLabel - Return the label of a given name, or NULL
7691: Not Collective
7693: Input Parameters:
7694: + dm - The DM object
7695: - name - The label name
7697: Output Parameter:
7698: . label - The DMLabel, or NULL if the label is absent
7700: Note: Some of the default labels in a DMPlex will be
7701: $ "depth" - Holds the depth (co-dimension) of each mesh point
7702: $ "celltype" - Holds the topological type of each cell
7703: $ "ghost" - If the DM is distributed with overlap, this marks the cells and faces in the overlap
7704: $ "Cell Sets" - Mirrors the cell sets defined by GMsh and ExodusII
7705: $ "Face Sets" - Mirrors the face sets defined by GMsh and ExodusII
7706: $ "Vertex Sets" - Mirrors the vertex sets defined by GMsh
7708: Level: intermediate
7710: .seealso: DMCreateLabel(), DMHasLabel(), DMPlexGetDepthLabel(), DMPlexGetCellType()
7711: @*/
7712: PetscErrorCode DMGetLabel(DM dm, const char name[], DMLabel *label)
7713: {
7714: DMLabelLink next = dm->labels;
7715: PetscBool hasLabel;
7716: const char *lname;
7723: *label = NULL;
7724: while (next) {
7725: PetscObjectGetName((PetscObject) next->label, &lname);
7726: PetscStrcmp(name, lname, &hasLabel);
7727: if (hasLabel) {
7728: *label = next->label;
7729: break;
7730: }
7731: next = next->next;
7732: }
7733: return(0);
7734: }
7736: /*@C
7737: DMGetLabelByNum - Return the nth label
7739: Not Collective
7741: Input Parameters:
7742: + dm - The DM object
7743: - n - the label number
7745: Output Parameter:
7746: . label - the label
7748: Level: intermediate
7750: .seealso: DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()
7751: @*/
7752: PetscErrorCode DMGetLabelByNum(DM dm, PetscInt n, DMLabel *label)
7753: {
7754: DMLabelLink next = dm->labels;
7755: PetscInt l = 0;
7760: while (next) {
7761: if (l == n) {
7762: *label = next->label;
7763: return(0);
7764: }
7765: ++l;
7766: next = next->next;
7767: }
7768: SETERRQ1(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Label %D does not exist in this DM", n);
7769: }
7771: /*@C
7772: DMAddLabel - Add the label to this mesh
7774: Not Collective
7776: Input Parameters:
7777: + dm - The DM object
7778: - label - The DMLabel
7780: Level: developer
7782: .seealso: DMCreateLabel(), DMHasLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()
7783: @*/
7784: PetscErrorCode DMAddLabel(DM dm, DMLabel label)
7785: {
7786: DMLabelLink l, *p, tmpLabel;
7787: PetscBool hasLabel;
7788: const char *lname;
7789: PetscBool flg;
7794: PetscObjectGetName((PetscObject) label, &lname);
7795: DMHasLabel(dm, lname, &hasLabel);
7796: if (hasLabel) SETERRQ1(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Label %s already exists in this DM", lname);
7797: PetscCalloc1(1, &tmpLabel);
7798: tmpLabel->label = label;
7799: tmpLabel->output = PETSC_TRUE;
7800: for (p=&dm->labels; (l=*p); p=&l->next) {}
7801: *p = tmpLabel;
7802: PetscObjectReference((PetscObject)label);
7803: PetscStrcmp(lname, "depth", &flg);
7804: if (flg) dm->depthLabel = label;
7805: PetscStrcmp(lname, "celltype", &flg);
7806: if (flg) dm->celltypeLabel = label;
7807: return(0);
7808: }
7810: /*@C
7811: DMRemoveLabel - Remove the label given by name from this mesh
7813: Not Collective
7815: Input Parameters:
7816: + dm - The DM object
7817: - name - The label name
7819: Output Parameter:
7820: . label - The DMLabel, or NULL if the label is absent
7822: Level: developer
7824: Notes:
7825: DMRemoveLabel(dm,name,NULL) removes the label from dm and calls
7826: DMLabelDestroy() on the label.
7828: DMRemoveLabel(dm,name,&label) removes the label from dm, but it DOES NOT
7829: call DMLabelDestroy(). Instead, the label is returned and the user is
7830: responsible of calling DMLabelDestroy() at some point.
7832: .seealso: DMCreateLabel(), DMHasLabel(), DMGetLabel(), DMGetLabelValue(), DMSetLabelValue(), DMLabelDestroy(), DMRemoveLabelBySelf()
7833: @*/
7834: PetscErrorCode DMRemoveLabel(DM dm, const char name[], DMLabel *label)
7835: {
7836: DMLabelLink link, *pnext;
7837: PetscBool hasLabel;
7838: const char *lname;
7844: if (label) {
7846: *label = NULL;
7847: }
7848: for (pnext=&dm->labels; (link=*pnext); pnext=&link->next) {
7849: PetscObjectGetName((PetscObject) link->label, &lname);
7850: PetscStrcmp(name, lname, &hasLabel);
7851: if (hasLabel) {
7852: *pnext = link->next; /* Remove from list */
7853: PetscStrcmp(name, "depth", &hasLabel);
7854: if (hasLabel) dm->depthLabel = NULL;
7855: PetscStrcmp(name, "celltype", &hasLabel);
7856: if (hasLabel) dm->celltypeLabel = NULL;
7857: if (label) *label = link->label;
7858: else {DMLabelDestroy(&link->label);}
7859: PetscFree(link);
7860: break;
7861: }
7862: }
7863: return(0);
7864: }
7866: /*@
7867: DMRemoveLabelBySelf - Remove the label from this mesh
7869: Not Collective
7871: Input Parameters:
7872: + dm - The DM object
7873: . label - (Optional) The DMLabel to be removed from the DM
7874: - failNotFound - Should it fail if the label is not found in the DM?
7876: Level: developer
7878: Notes:
7879: Only exactly the same instance is removed if found, name match is ignored.
7880: If the DM has an exclusive reference to the label, it gets destroyed and
7881: *label nullified.
7883: .seealso: DMCreateLabel(), DMHasLabel(), DMGetLabel() DMGetLabelValue(), DMSetLabelValue(), DMLabelDestroy(), DMRemoveLabel()
7884: @*/
7885: PetscErrorCode DMRemoveLabelBySelf(DM dm, DMLabel *label, PetscBool failNotFound)
7886: {
7887: DMLabelLink link, *pnext;
7888: PetscBool hasLabel = PETSC_FALSE;
7894: if (!*label && !failNotFound) return(0);
7897: for (pnext=&dm->labels; (link=*pnext); pnext=&link->next) {
7898: if (*label == link->label) {
7899: hasLabel = PETSC_TRUE;
7900: *pnext = link->next; /* Remove from list */
7901: if (*label == dm->depthLabel) dm->depthLabel = NULL;
7902: if (*label == dm->celltypeLabel) dm->celltypeLabel = NULL;
7903: if (((PetscObject) link->label)->refct < 2) *label = NULL; /* nullify if exclusive reference */
7904: DMLabelDestroy(&link->label);
7905: PetscFree(link);
7906: break;
7907: }
7908: }
7909: if (!hasLabel && failNotFound) SETERRQ(PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_WRONG, "Given label not found in DM");
7910: return(0);
7911: }
7913: /*@C
7914: DMGetLabelOutput - Get the output flag for a given label
7916: Not Collective
7918: Input Parameters:
7919: + dm - The DM object
7920: - name - The label name
7922: Output Parameter:
7923: . output - The flag for output
7925: Level: developer
7927: .seealso: DMSetLabelOutput(), DMCreateLabel(), DMHasLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()
7928: @*/
7929: PetscErrorCode DMGetLabelOutput(DM dm, const char name[], PetscBool *output)
7930: {
7931: DMLabelLink next = dm->labels;
7932: const char *lname;
7939: while (next) {
7940: PetscBool flg;
7942: PetscObjectGetName((PetscObject) next->label, &lname);
7943: PetscStrcmp(name, lname, &flg);
7944: if (flg) {*output = next->output; return(0);}
7945: next = next->next;
7946: }
7947: SETERRQ1(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "No label named %s was present in this dm", name);
7948: }
7950: /*@C
7951: DMSetLabelOutput - Set the output flag for a given label
7953: Not Collective
7955: Input Parameters:
7956: + dm - The DM object
7957: . name - The label name
7958: - output - The flag for output
7960: Level: developer
7962: .seealso: DMGetLabelOutput(), DMCreateLabel(), DMHasLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()
7963: @*/
7964: PetscErrorCode DMSetLabelOutput(DM dm, const char name[], PetscBool output)
7965: {
7966: DMLabelLink next = dm->labels;
7967: const char *lname;
7973: while (next) {
7974: PetscBool flg;
7976: PetscObjectGetName((PetscObject) next->label, &lname);
7977: PetscStrcmp(name, lname, &flg);
7978: if (flg) {next->output = output; return(0);}
7979: next = next->next;
7980: }
7981: SETERRQ1(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "No label named %s was present in this dm", name);
7982: }
7984: /*@
7985: DMCopyLabels - Copy labels from one mesh to another with a superset of the points
7987: Collective on dmA
7989: Input Parameter:
7990: + dmA - The DM object with initial labels
7991: . dmB - The DM object with copied labels
7992: . mode - Copy labels by pointers (PETSC_OWN_POINTER) or duplicate them (PETSC_COPY_VALUES)
7993: - all - Copy all labels including "depth", "dim", and "celltype" (PETSC_TRUE) which are otherwise ignored (PETSC_FALSE)
7995: Level: intermediate
7997: Note: This is typically used when interpolating or otherwise adding to a mesh
7999: .seealso: DMGetCoordinates(), DMGetCoordinatesLocal(), DMGetCoordinateDM(), DMGetCoordinateSection(), DMShareLabels()
8000: @*/
8001: PetscErrorCode DMCopyLabels(DM dmA, DM dmB, PetscCopyMode mode, PetscBool all)
8002: {
8003: DMLabel label, labelNew;
8004: const char *name;
8005: PetscBool flg;
8006: DMLabelLink link;
8014: if (mode==PETSC_USE_POINTER) SETERRQ(PetscObjectComm((PetscObject)dmA), PETSC_ERR_SUP, "PETSC_USE_POINTER not supported for objects");
8015: if (dmA == dmB) return(0);
8016: for (link=dmA->labels; link; link=link->next) {
8017: label=link->label;
8018: PetscObjectGetName((PetscObject)label, &name);
8019: if (!all) {
8020: PetscStrcmp(name, "depth", &flg);
8021: if (flg) continue;
8022: PetscStrcmp(name, "dim", &flg);
8023: if (flg) continue;
8024: PetscStrcmp(name, "celltype", &flg);
8025: if (flg) continue;
8026: }
8027: if (mode==PETSC_COPY_VALUES) {
8028: DMLabelDuplicate(label, &labelNew);
8029: } else {
8030: labelNew = label;
8031: }
8032: DMAddLabel(dmB, labelNew);
8033: if (mode==PETSC_COPY_VALUES) {DMLabelDestroy(&labelNew);}
8034: }
8035: return(0);
8036: }
8038: PetscErrorCode DMSetLabelValue_Fast(DM dm, DMLabel *label, const char name[], PetscInt point, PetscInt value)
8039: {
8043: if (!*label) {
8044: DMCreateLabel(dm, name);
8045: DMGetLabel(dm, name, label);
8046: }
8047: DMLabelSetValue(*label, point, value);
8048: return(0);
8049: }
8051: /*
8052: Many mesh programs, such as Triangle and TetGen, allow only a single label for each mesh point. Therefore, we would
8053: like to encode all label IDs using a single, universal label. We can do this by assigning an integer to every
8054: (label, id) pair in the DM.
8056: However, a mesh point can have multiple labels, so we must separate all these values. We will assign a bit range to
8057: each label.
8058: */
8059: PetscErrorCode DMUniversalLabelCreate(DM dm, DMUniversalLabel *universal)
8060: {
8061: DMUniversalLabel ul;
8062: PetscBool *active;
8063: PetscInt pStart, pEnd, p, Nl, l, m;
8064: PetscErrorCode ierr;
8067: PetscMalloc1(1, &ul);
8068: DMLabelCreate(PETSC_COMM_SELF, "universal", &ul->label);
8069: DMGetNumLabels(dm, &Nl);
8070: PetscCalloc1(Nl, &active);
8071: ul->Nl = 0;
8072: for (l = 0; l < Nl; ++l) {
8073: PetscBool isdepth, iscelltype;
8074: const char *name;
8076: DMGetLabelName(dm, l, &name);
8077: PetscStrncmp(name, "depth", 6, &isdepth);
8078: PetscStrncmp(name, "celltype", 9, &iscelltype);
8079: active[l] = !(isdepth || iscelltype) ? PETSC_TRUE : PETSC_FALSE;
8080: if (active[l]) ++ul->Nl;
8081: }
8082: PetscCalloc5(ul->Nl, &ul->names, ul->Nl, &ul->indices, ul->Nl+1, &ul->offsets, ul->Nl+1, &ul->bits, ul->Nl, &ul->masks);
8083: ul->Nv = 0;
8084: for (l = 0, m = 0; l < Nl; ++l) {
8085: DMLabel label;
8086: PetscInt nv;
8087: const char *name;
8089: if (!active[l]) continue;
8090: DMGetLabelName(dm, l, &name);
8091: DMGetLabelByNum(dm, l, &label);
8092: DMLabelGetNumValues(label, &nv);
8093: PetscStrallocpy(name, &ul->names[m]);
8094: ul->indices[m] = l;
8095: ul->Nv += nv;
8096: ul->offsets[m+1] = nv;
8097: ul->bits[m+1] = PetscCeilReal(PetscLog2Real(nv+1));
8098: ++m;
8099: }
8100: for (l = 1; l <= ul->Nl; ++l) {
8101: ul->offsets[l] = ul->offsets[l-1] + ul->offsets[l];
8102: ul->bits[l] = ul->bits[l-1] + ul->bits[l];
8103: }
8104: for (l = 0; l < ul->Nl; ++l) {
8105: PetscInt b;
8107: ul->masks[l] = 0;
8108: for (b = ul->bits[l]; b < ul->bits[l+1]; ++b) ul->masks[l] |= 1 << b;
8109: }
8110: PetscMalloc1(ul->Nv, &ul->values);
8111: for (l = 0, m = 0; l < Nl; ++l) {
8112: DMLabel label;
8113: IS valueIS;
8114: const PetscInt *varr;
8115: PetscInt nv, v;
8117: if (!active[l]) continue;
8118: DMGetLabelByNum(dm, l, &label);
8119: DMLabelGetNumValues(label, &nv);
8120: DMLabelGetValueIS(label, &valueIS);
8121: ISGetIndices(valueIS, &varr);
8122: for (v = 0; v < nv; ++v) {
8123: ul->values[ul->offsets[m]+v] = varr[v];
8124: }
8125: ISRestoreIndices(valueIS, &varr);
8126: ISDestroy(&valueIS);
8127: PetscSortInt(nv, &ul->values[ul->offsets[m]]);
8128: ++m;
8129: }
8130: DMPlexGetChart(dm, &pStart, &pEnd);
8131: for (p = pStart; p < pEnd; ++p) {
8132: PetscInt uval = 0;
8133: PetscBool marked = PETSC_FALSE;
8135: for (l = 0, m = 0; l < Nl; ++l) {
8136: DMLabel label;
8137: PetscInt val, defval, loc, nv;
8139: if (!active[l]) continue;
8140: DMGetLabelByNum(dm, l, &label);
8141: DMLabelGetValue(label, p, &val);
8142: DMLabelGetDefaultValue(label, &defval);
8143: if (val == defval) {++m; continue;}
8144: nv = ul->offsets[m+1]-ul->offsets[m];
8145: marked = PETSC_TRUE;
8146: PetscFindInt(val, nv, &ul->values[ul->offsets[m]], &loc);
8147: if (loc < 0) SETERRQ1(PETSC_COMM_SELF, PETSC_ERR_PLIB, "Label value %D not found in compression array", val);
8148: uval += (loc+1) << ul->bits[m];
8149: ++m;
8150: }
8151: if (marked) {DMLabelSetValue(ul->label, p, uval);}
8152: }
8153: PetscFree(active);
8154: *universal = ul;
8155: return(0);
8156: }
8158: PetscErrorCode DMUniversalLabelDestroy(DMUniversalLabel *universal)
8159: {
8160: PetscInt l;
8164: for (l = 0; l < (*universal)->Nl; ++l) {PetscFree((*universal)->names[l]);}
8165: DMLabelDestroy(&(*universal)->label);
8166: PetscFree5((*universal)->names, (*universal)->indices, (*universal)->offsets, (*universal)->bits, (*universal)->masks);
8167: PetscFree((*universal)->values);
8168: PetscFree(*universal);
8169: *universal = NULL;
8170: return(0);
8171: }
8173: PetscErrorCode DMUniversalLabelGetLabel(DMUniversalLabel ul, DMLabel *ulabel)
8174: {
8177: *ulabel = ul->label;
8178: return(0);
8179: }
8181: PetscErrorCode DMUniversalLabelCreateLabels(DMUniversalLabel ul, PetscBool preserveOrder, DM dm)
8182: {
8183: PetscInt Nl = ul->Nl, l;
8188: for (l = 0; l < Nl; ++l) {
8189: if (preserveOrder) {DMCreateLabelAtIndex(dm, ul->indices[l], ul->names[l]);}
8190: else {DMCreateLabel(dm, ul->names[l]);}
8191: }
8192: if (preserveOrder) {
8193: for (l = 0; l < ul->Nl; ++l) {
8194: const char *name;
8195: PetscBool match;
8197: DMGetLabelName(dm, ul->indices[l], &name);
8198: PetscStrcmp(name, ul->names[l], &match);
8199: if (!match) SETERRQ3(PetscObjectComm((PetscObject) dm), PETSC_ERR_ARG_WRONG, "Label %D name %s does not match new name %s", l, name, ul->names[l]);
8200: }
8201: }
8202: return(0);
8203: }
8205: PetscErrorCode DMUniversalLabelSetLabelValue(DMUniversalLabel ul, DM dm, PetscBool useIndex, PetscInt p, PetscInt value)
8206: {
8207: PetscInt l;
8211: for (l = 0; l < ul->Nl; ++l) {
8212: DMLabel label;
8213: PetscInt lval = (value & ul->masks[l]) >> ul->bits[l];
8215: if (lval) {
8216: if (useIndex) {DMGetLabelByNum(dm, ul->indices[l], &label);}
8217: else {DMGetLabel(dm, ul->names[l], &label);}
8218: DMLabelSetValue(label, p, ul->values[ul->offsets[l]+lval-1]);
8219: }
8220: }
8221: return(0);
8222: }
8224: /*@
8225: DMGetCoarseDM - Get the coarse mesh from which this was obtained by refinement
8227: Input Parameter:
8228: . dm - The DM object
8230: Output Parameter:
8231: . cdm - The coarse DM
8233: Level: intermediate
8235: .seealso: DMSetCoarseDM()
8236: @*/
8237: PetscErrorCode DMGetCoarseDM(DM dm, DM *cdm)
8238: {
8242: *cdm = dm->coarseMesh;
8243: return(0);
8244: }
8246: /*@
8247: DMSetCoarseDM - Set the coarse mesh from which this was obtained by refinement
8249: Input Parameters:
8250: + dm - The DM object
8251: - cdm - The coarse DM
8253: Level: intermediate
8255: .seealso: DMGetCoarseDM()
8256: @*/
8257: PetscErrorCode DMSetCoarseDM(DM dm, DM cdm)
8258: {
8264: PetscObjectReference((PetscObject)cdm);
8265: DMDestroy(&dm->coarseMesh);
8266: dm->coarseMesh = cdm;
8267: return(0);
8268: }
8270: /*@
8271: DMGetFineDM - Get the fine mesh from which this was obtained by refinement
8273: Input Parameter:
8274: . dm - The DM object
8276: Output Parameter:
8277: . fdm - The fine DM
8279: Level: intermediate
8281: .seealso: DMSetFineDM()
8282: @*/
8283: PetscErrorCode DMGetFineDM(DM dm, DM *fdm)
8284: {
8288: *fdm = dm->fineMesh;
8289: return(0);
8290: }
8292: /*@
8293: DMSetFineDM - Set the fine mesh from which this was obtained by refinement
8295: Input Parameters:
8296: + dm - The DM object
8297: - fdm - The fine DM
8299: Level: intermediate
8301: .seealso: DMGetFineDM()
8302: @*/
8303: PetscErrorCode DMSetFineDM(DM dm, DM fdm)
8304: {
8310: PetscObjectReference((PetscObject)fdm);
8311: DMDestroy(&dm->fineMesh);
8312: dm->fineMesh = fdm;
8313: return(0);
8314: }
8316: /*=== DMBoundary code ===*/
8318: PetscErrorCode DMCopyBoundary(DM dm, DM dmNew)
8319: {
8320: PetscInt d;
8324: for (d = 0; d < dm->Nds; ++d) {
8325: PetscDSCopyBoundary(dm->probs[d].ds, PETSC_DETERMINE, NULL, dmNew->probs[d].ds);
8326: }
8327: return(0);
8328: }
8330: /*@C
8331: DMAddBoundary - Add a boundary condition to the model
8333: Collective on dm
8335: Input Parameters:
8336: + dm - The DM, with a PetscDS that matches the problem being constrained
8337: . type - The type of condition, e.g. DM_BC_ESSENTIAL_ANALYTIC/DM_BC_ESSENTIAL_FIELD (Dirichlet), or DM_BC_NATURAL (Neumann)
8338: . name - The BC name
8339: . labelname - The label defining constrained points
8340: . field - The field to constrain
8341: . numcomps - The number of constrained field components (0 will constrain all fields)
8342: . comps - An array of constrained component numbers
8343: . bcFunc - A pointwise function giving boundary values
8344: . bcFunc_t - A pointwise function giving the time deriative of the boundary values, or NULL
8345: . numids - The number of DMLabel ids for constrained points
8346: . ids - An array of ids for constrained points
8347: - ctx - An optional user context for bcFunc
8349: Options Database Keys:
8350: + -bc_<boundary name> <num> - Overrides the boundary ids
8351: - -bc_<boundary name>_comp <num> - Overrides the boundary components
8353: Note:
8354: Both bcFunc abd bcFunc_t will depend on the boundary condition type. If the type if DM_BC_ESSENTIAL, Then the calling sequence is:
8356: $ bcFunc(PetscInt dim, PetscReal time, const PetscReal x[], PetscInt Nc, PetscScalar bcval[])
8358: If the type is DM_BC_ESSENTIAL_FIELD or other _FIELD value, then the calling sequence is:
8360: $ bcFunc(PetscInt dim, PetscInt Nf, PetscInt NfAux,
8361: $ const PetscInt uOff[], const PetscInt uOff_x[], const PetscScalar u[], const PetscScalar u_t[], const PetscScalar u_x[],
8362: $ const PetscInt aOff[], const PetscInt aOff_x[], const PetscScalar a[], const PetscScalar a_t[], const PetscScalar a_x[],
8363: $ PetscReal time, const PetscReal x[], PetscScalar bcval[])
8365: + dim - the spatial dimension
8366: . Nf - the number of fields
8367: . uOff - the offset into u[] and u_t[] for each field
8368: . uOff_x - the offset into u_x[] for each field
8369: . u - each field evaluated at the current point
8370: . u_t - the time derivative of each field evaluated at the current point
8371: . u_x - the gradient of each field evaluated at the current point
8372: . aOff - the offset into a[] and a_t[] for each auxiliary field
8373: . aOff_x - the offset into a_x[] for each auxiliary field
8374: . a - each auxiliary field evaluated at the current point
8375: . a_t - the time derivative of each auxiliary field evaluated at the current point
8376: . a_x - the gradient of auxiliary each field evaluated at the current point
8377: . t - current time
8378: . x - coordinates of the current point
8379: . numConstants - number of constant parameters
8380: . constants - constant parameters
8381: - bcval - output values at the current point
8383: Level: developer
8385: .seealso: DMGetBoundary(), PetscDSAddBoundary()
8386: @*/
8387: PetscErrorCode DMAddBoundary(DM dm, DMBoundaryConditionType type, const char name[], const char labelname[], PetscInt field, PetscInt numcomps, const PetscInt *comps, void (*bcFunc)(void), void (*bcFunc_t)(void), PetscInt numids, const PetscInt *ids, void *ctx)
8388: {
8389: PetscDS ds;
8398: DMGetDS(dm, &ds);
8399: DMCompleteBoundaryLabel_Internal(dm, ds, field, PETSC_MAX_INT, labelname);
8400: PetscDSAddBoundary(ds, type,name, labelname, field, numcomps, comps, bcFunc, bcFunc_t, numids, ids, ctx);
8401: return(0);
8402: }
8404: /*@
8405: DMGetNumBoundary - Get the number of registered BC
8407: Input Parameters:
8408: . dm - The mesh object
8410: Output Parameters:
8411: . numBd - The number of BC
8413: Level: intermediate
8415: .seealso: DMAddBoundary(), DMGetBoundary()
8416: @*/
8417: PetscErrorCode DMGetNumBoundary(DM dm, PetscInt *numBd)
8418: {
8419: PetscDS ds;
8424: DMGetDS(dm, &ds);
8425: PetscDSGetNumBoundary(ds, numBd);
8426: return(0);
8427: }
8429: /*@C
8430: DMGetBoundary - Get a model boundary condition
8432: Input Parameters:
8433: + dm - The mesh object
8434: - bd - The BC number
8436: Output Parameters:
8437: + type - The type of condition, e.g. DM_BC_ESSENTIAL_ANALYTIC/DM_BC_ESSENTIAL_FIELD (Dirichlet), or DM_BC_NATURAL (Neumann)
8438: . name - The BC name
8439: . labelname - The label defining constrained points
8440: . field - The field to constrain
8441: . numcomps - The number of constrained field components
8442: . comps - An array of constrained component numbers
8443: . bcFunc - A pointwise function giving boundary values
8444: . bcFunc_t - A pointwise function giving the time derviative of the boundary values
8445: . numids - The number of DMLabel ids for constrained points
8446: . ids - An array of ids for constrained points
8447: - ctx - An optional user context for bcFunc
8449: Options Database Keys:
8450: + -bc_<boundary name> <num> - Overrides the boundary ids
8451: - -bc_<boundary name>_comp <num> - Overrides the boundary components
8453: Level: developer
8455: .seealso: DMAddBoundary()
8456: @*/
8457: PetscErrorCode DMGetBoundary(DM dm, PetscInt bd, DMBoundaryConditionType *type, const char **name, const char **labelname, PetscInt *field, PetscInt *numcomps, const PetscInt **comps, void (**func)(void), void (**func_t)(void), PetscInt *numids, const PetscInt **ids, void **ctx)
8458: {
8459: PetscDS ds;
8464: DMGetDS(dm, &ds);
8465: PetscDSGetBoundary(ds, bd, type, name, labelname, field, numcomps, comps, func, func_t, numids, ids, ctx);
8466: return(0);
8467: }
8469: static PetscErrorCode DMPopulateBoundary(DM dm)
8470: {
8471: PetscDS ds;
8472: DMBoundary *lastnext;
8473: DSBoundary dsbound;
8477: DMGetDS(dm, &ds);
8478: dsbound = ds->boundary;
8479: if (dm->boundary) {
8480: DMBoundary next = dm->boundary;
8482: /* quick check to see if the PetscDS has changed */
8483: if (next->dsboundary == dsbound) return(0);
8484: /* the PetscDS has changed: tear down and rebuild */
8485: while (next) {
8486: DMBoundary b = next;
8488: next = b->next;
8489: PetscFree(b);
8490: }
8491: dm->boundary = NULL;
8492: }
8494: lastnext = &(dm->boundary);
8495: while (dsbound) {
8496: DMBoundary dmbound;
8498: PetscNew(&dmbound);
8499: dmbound->dsboundary = dsbound;
8500: DMGetLabel(dm, dsbound->labelname, &(dmbound->label));
8501: if (!dmbound->label) {PetscInfo2(dm, "DSBoundary %s wants label %s, which is not in this dm.\n",dsbound->name,dsbound->labelname);}
8502: /* push on the back instead of the front so that it is in the same order as in the PetscDS */
8503: *lastnext = dmbound;
8504: lastnext = &(dmbound->next);
8505: dsbound = dsbound->next;
8506: }
8507: return(0);
8508: }
8510: PetscErrorCode DMIsBoundaryPoint(DM dm, PetscInt point, PetscBool *isBd)
8511: {
8512: DMBoundary b;
8518: *isBd = PETSC_FALSE;
8519: DMPopulateBoundary(dm);
8520: b = dm->boundary;
8521: while (b && !(*isBd)) {
8522: DMLabel label = b->label;
8523: DSBoundary dsb = b->dsboundary;
8525: if (label) {
8526: PetscInt i;
8528: for (i = 0; i < dsb->numids && !(*isBd); ++i) {
8529: DMLabelStratumHasPoint(label, dsb->ids[i], point, isBd);
8530: }
8531: }
8532: b = b->next;
8533: }
8534: return(0);
8535: }
8537: /*@C
8538: DMProjectFunction - This projects the given function into the function space provided, putting the coefficients in a global vector.
8540: Collective on DM
8542: Input Parameters:
8543: + dm - The DM
8544: . time - The time
8545: . funcs - The coordinate functions to evaluate, one per field
8546: . ctxs - Optional array of contexts to pass to each coordinate function. ctxs itself may be null.
8547: - mode - The insertion mode for values
8549: Output Parameter:
8550: . X - vector
8552: Calling sequence of func:
8553: $ func(PetscInt dim, PetscReal time, const PetscReal x[], PetscInt Nf, PetscScalar u[], void *ctx);
8555: + dim - The spatial dimension
8556: . time - The time at which to sample
8557: . x - The coordinates
8558: . Nf - The number of fields
8559: . u - The output field values
8560: - ctx - optional user-defined function context
8562: Level: developer
8564: .seealso: DMProjectFunctionLocal(), DMProjectFunctionLabel(), DMComputeL2Diff()
8565: @*/
8566: PetscErrorCode DMProjectFunction(DM dm, PetscReal time, PetscErrorCode (**funcs)(PetscInt, PetscReal, const PetscReal [], PetscInt, PetscScalar *, void *), void **ctxs, InsertMode mode, Vec X)
8567: {
8568: Vec localX;
8573: DMGetLocalVector(dm, &localX);
8574: DMProjectFunctionLocal(dm, time, funcs, ctxs, mode, localX);
8575: DMLocalToGlobalBegin(dm, localX, mode, X);
8576: DMLocalToGlobalEnd(dm, localX, mode, X);
8577: DMRestoreLocalVector(dm, &localX);
8578: return(0);
8579: }
8581: /*@C
8582: DMProjectFunctionLocal - This projects the given function into the function space provided, putting the coefficients in a local vector.
8584: Not collective
8586: Input Parameters:
8587: + dm - The DM
8588: . time - The time
8589: . funcs - The coordinate functions to evaluate, one per field
8590: . ctxs - Optional array of contexts to pass to each coordinate function. ctxs itself may be null.
8591: - mode - The insertion mode for values
8593: Output Parameter:
8594: . localX - vector
8596: Calling sequence of func:
8597: $ func(PetscInt dim, PetscReal time, const PetscReal x[], PetscInt Nf, PetscScalar u[], void *ctx);
8599: + dim - The spatial dimension
8600: . x - The coordinates
8601: . Nf - The number of fields
8602: . u - The output field values
8603: - ctx - optional user-defined function context
8605: Level: developer
8607: .seealso: DMProjectFunction(), DMProjectFunctionLabel(), DMComputeL2Diff()
8608: @*/
8609: PetscErrorCode DMProjectFunctionLocal(DM dm, PetscReal time, PetscErrorCode (**funcs)(PetscInt, PetscReal, const PetscReal [], PetscInt, PetscScalar *, void *), void **ctxs, InsertMode mode, Vec localX)
8610: {
8616: if (!dm->ops->projectfunctionlocal) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMProjectFunctionLocal",((PetscObject)dm)->type_name);
8617: (dm->ops->projectfunctionlocal) (dm, time, funcs, ctxs, mode, localX);
8618: return(0);
8619: }
8621: /*@C
8622: DMProjectFunctionLabel - This projects the given function into the function space provided, putting the coefficients in a global vector, setting values only for points in the given label.
8624: Collective on DM
8626: Input Parameters:
8627: + dm - The DM
8628: . time - The time
8629: . label - The DMLabel selecting the portion of the mesh for projection
8630: . funcs - The coordinate functions to evaluate, one per field
8631: . ctxs - Optional array of contexts to pass to each coordinate function. ctxs itself may be null.
8632: - mode - The insertion mode for values
8634: Output Parameter:
8635: . X - vector
8637: Calling sequence of func:
8638: $ func(PetscInt dim, PetscReal time, const PetscReal x[], PetscInt Nf, PetscScalar u[], void *ctx);
8640: + dim - The spatial dimension
8641: . x - The coordinates
8642: . Nf - The number of fields
8643: . u - The output field values
8644: - ctx - optional user-defined function context
8646: Level: developer
8648: .seealso: DMProjectFunction(), DMProjectFunctionLocal(), DMProjectFunctionLabelLocal(), DMComputeL2Diff()
8649: @*/
8650: PetscErrorCode DMProjectFunctionLabel(DM dm, PetscReal time, DMLabel label, PetscInt numIds, const PetscInt ids[], PetscInt Nc, const PetscInt comps[], PetscErrorCode (**funcs)(PetscInt, PetscReal, const PetscReal [], PetscInt, PetscScalar *, void *), void **ctxs, InsertMode mode, Vec X)
8651: {
8652: Vec localX;
8657: DMGetLocalVector(dm, &localX);
8658: DMProjectFunctionLabelLocal(dm, time, label, numIds, ids, Nc, comps, funcs, ctxs, mode, localX);
8659: DMLocalToGlobalBegin(dm, localX, mode, X);
8660: DMLocalToGlobalEnd(dm, localX, mode, X);
8661: DMRestoreLocalVector(dm, &localX);
8662: return(0);
8663: }
8665: /*@C
8666: DMProjectFunctionLabelLocal - This projects the given function into the function space provided, putting the coefficients in a local vector, setting values only for points in the given label.
8668: Not collective
8670: Input Parameters:
8671: + dm - The DM
8672: . time - The time
8673: . label - The DMLabel selecting the portion of the mesh for projection
8674: . funcs - The coordinate functions to evaluate, one per field
8675: . ctxs - Optional array of contexts to pass to each coordinate function. ctxs itself may be null.
8676: - mode - The insertion mode for values
8678: Output Parameter:
8679: . localX - vector
8681: Calling sequence of func:
8682: $ func(PetscInt dim, PetscReal time, const PetscReal x[], PetscInt Nf, PetscScalar u[], void *ctx);
8684: + dim - The spatial dimension
8685: . x - The coordinates
8686: . Nf - The number of fields
8687: . u - The output field values
8688: - ctx - optional user-defined function context
8690: Level: developer
8692: .seealso: DMProjectFunction(), DMProjectFunctionLocal(), DMProjectFunctionLabel(), DMComputeL2Diff()
8693: @*/
8694: PetscErrorCode DMProjectFunctionLabelLocal(DM dm, PetscReal time, DMLabel label, PetscInt numIds, const PetscInt ids[], PetscInt Nc, const PetscInt comps[], PetscErrorCode (**funcs)(PetscInt, PetscReal, const PetscReal [], PetscInt, PetscScalar *, void *), void **ctxs, InsertMode mode, Vec localX)
8695: {
8701: if (!dm->ops->projectfunctionlabellocal) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMProjectFunctionLabelLocal",((PetscObject)dm)->type_name);
8702: (dm->ops->projectfunctionlabellocal) (dm, time, label, numIds, ids, Nc, comps, funcs, ctxs, mode, localX);
8703: return(0);
8704: }
8706: /*@C
8707: DMProjectFieldLocal - This projects the given function of the input fields into the function space provided, putting the coefficients in a local vector.
8709: Not collective
8711: Input Parameters:
8712: + dm - The DM
8713: . time - The time
8714: . localU - The input field vector
8715: . funcs - The functions to evaluate, one per field
8716: - mode - The insertion mode for values
8718: Output Parameter:
8719: . localX - The output vector
8721: Calling sequence of func:
8722: $ func(PetscInt dim, PetscInt Nf, PetscInt NfAux,
8723: $ const PetscInt uOff[], const PetscInt uOff_x[], const PetscScalar u[], const PetscScalar u_t[], const PetscScalar u_x[],
8724: $ const PetscInt aOff[], const PetscInt aOff_x[], const PetscScalar a[], const PetscScalar a_t[], const PetscScalar a_x[],
8725: $ PetscReal t, const PetscReal x[], PetscInt numConstants, const PetscScalar constants[], PetscScalar f[]);
8727: + dim - The spatial dimension
8728: . Nf - The number of input fields
8729: . NfAux - The number of input auxiliary fields
8730: . uOff - The offset of each field in u[]
8731: . uOff_x - The offset of each field in u_x[]
8732: . u - The field values at this point in space
8733: . u_t - The field time derivative at this point in space (or NULL)
8734: . u_x - The field derivatives at this point in space
8735: . aOff - The offset of each auxiliary field in u[]
8736: . aOff_x - The offset of each auxiliary field in u_x[]
8737: . a - The auxiliary field values at this point in space
8738: . a_t - The auxiliary field time derivative at this point in space (or NULL)
8739: . a_x - The auxiliary field derivatives at this point in space
8740: . t - The current time
8741: . x - The coordinates of this point
8742: . numConstants - The number of constants
8743: . constants - The value of each constant
8744: - f - The value of the function at this point in space
8746: Note: There are three different DMs that potentially interact in this function. The output DM, dm, specifies the layout of the values calculates by funcs.
8747: The input DM, attached to U, may be different. For example, you can input the solution over the full domain, but output over a piece of the boundary, or
8748: a subdomain. You can also output a different number of fields than the input, with different discretizations. Last the auxiliary DM, attached to the
8749: auxiliary field vector, which is attached to dm, can also be different. It can have a different topology, number of fields, and discretizations.
8751: Level: intermediate
8753: .seealso: DMProjectField(), DMProjectFieldLabelLocal(), DMProjectFunction(), DMComputeL2Diff()
8754: @*/
8755: PetscErrorCode DMProjectFieldLocal(DM dm, PetscReal time, Vec localU,
8756: void (**funcs)(PetscInt, PetscInt, PetscInt,
8757: const PetscInt[], const PetscInt[], const PetscScalar[], const PetscScalar[], const PetscScalar[],
8758: const PetscInt[], const PetscInt[], const PetscScalar[], const PetscScalar[], const PetscScalar[],
8759: PetscReal, const PetscReal[], PetscInt, const PetscScalar[], PetscScalar[]),
8760: InsertMode mode, Vec localX)
8761: {
8768: if (!dm->ops->projectfieldlocal) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMProjectFieldLocal",((PetscObject)dm)->type_name);
8769: (dm->ops->projectfieldlocal) (dm, time, localU, funcs, mode, localX);
8770: return(0);
8771: }
8773: /*@C
8774: DMProjectFieldLabelLocal - This projects the given function of the input fields into the function space provided, putting the coefficients in a local vector, calculating only over the portion of the domain specified by the label.
8776: Not collective
8778: Input Parameters:
8779: + dm - The DM
8780: . time - The time
8781: . label - The DMLabel marking the portion of the domain to output
8782: . numIds - The number of label ids to use
8783: . ids - The label ids to use for marking
8784: . Nc - The number of components to set in the output, or PETSC_DETERMINE for all components
8785: . comps - The components to set in the output, or NULL for all components
8786: . localU - The input field vector
8787: . funcs - The functions to evaluate, one per field
8788: - mode - The insertion mode for values
8790: Output Parameter:
8791: . localX - The output vector
8793: Calling sequence of func:
8794: $ func(PetscInt dim, PetscInt Nf, PetscInt NfAux,
8795: $ const PetscInt uOff[], const PetscInt uOff_x[], const PetscScalar u[], const PetscScalar u_t[], const PetscScalar u_x[],
8796: $ const PetscInt aOff[], const PetscInt aOff_x[], const PetscScalar a[], const PetscScalar a_t[], const PetscScalar a_x[],
8797: $ PetscReal t, const PetscReal x[], PetscInt numConstants, const PetscScalar constants[], PetscScalar f[]);
8799: + dim - The spatial dimension
8800: . Nf - The number of input fields
8801: . NfAux - The number of input auxiliary fields
8802: . uOff - The offset of each field in u[]
8803: . uOff_x - The offset of each field in u_x[]
8804: . u - The field values at this point in space
8805: . u_t - The field time derivative at this point in space (or NULL)
8806: . u_x - The field derivatives at this point in space
8807: . aOff - The offset of each auxiliary field in u[]
8808: . aOff_x - The offset of each auxiliary field in u_x[]
8809: . a - The auxiliary field values at this point in space
8810: . a_t - The auxiliary field time derivative at this point in space (or NULL)
8811: . a_x - The auxiliary field derivatives at this point in space
8812: . t - The current time
8813: . x - The coordinates of this point
8814: . numConstants - The number of constants
8815: . constants - The value of each constant
8816: - f - The value of the function at this point in space
8818: Note: There are three different DMs that potentially interact in this function. The output DM, dm, specifies the layout of the values calculates by funcs.
8819: The input DM, attached to U, may be different. For example, you can input the solution over the full domain, but output over a piece of the boundary, or
8820: a subdomain. You can also output a different number of fields than the input, with different discretizations. Last the auxiliary DM, attached to the
8821: auxiliary field vector, which is attached to dm, can also be different. It can have a different topology, number of fields, and discretizations.
8823: Level: intermediate
8825: .seealso: DMProjectField(), DMProjectFieldLabelLocal(), DMProjectFunction(), DMComputeL2Diff()
8826: @*/
8827: PetscErrorCode DMProjectFieldLabelLocal(DM dm, PetscReal time, DMLabel label, PetscInt numIds, const PetscInt ids[], PetscInt Nc, const PetscInt comps[], Vec localU,
8828: void (**funcs)(PetscInt, PetscInt, PetscInt,
8829: const PetscInt[], const PetscInt[], const PetscScalar[], const PetscScalar[], const PetscScalar[],
8830: const PetscInt[], const PetscInt[], const PetscScalar[], const PetscScalar[], const PetscScalar[],
8831: PetscReal, const PetscReal[], PetscInt, const PetscScalar[], PetscScalar[]),
8832: InsertMode mode, Vec localX)
8833: {
8840: if (!dm->ops->projectfieldlabellocal) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMProjectFieldLabelLocal",((PetscObject)dm)->type_name);
8841: (dm->ops->projectfieldlabellocal)(dm, time, label, numIds, ids, Nc, comps, localU, funcs, mode, localX);
8842: return(0);
8843: }
8845: /*@C
8846: DMProjectBdFieldLabelLocal - This projects the given function of the input fields into the function space provided, putting the coefficients in a local vector, calculating only over the portion of the domain boundary specified by the label.
8848: Not collective
8850: Input Parameters:
8851: + dm - The DM
8852: . time - The time
8853: . label - The DMLabel marking the portion of the domain boundary to output
8854: . numIds - The number of label ids to use
8855: . ids - The label ids to use for marking
8856: . Nc - The number of components to set in the output, or PETSC_DETERMINE for all components
8857: . comps - The components to set in the output, or NULL for all components
8858: . localU - The input field vector
8859: . funcs - The functions to evaluate, one per field
8860: - mode - The insertion mode for values
8862: Output Parameter:
8863: . localX - The output vector
8865: Calling sequence of func:
8866: $ func(PetscInt dim, PetscInt Nf, PetscInt NfAux,
8867: $ const PetscInt uOff[], const PetscInt uOff_x[], const PetscScalar u[], const PetscScalar u_t[], const PetscScalar u_x[],
8868: $ const PetscInt aOff[], const PetscInt aOff_x[], const PetscScalar a[], const PetscScalar a_t[], const PetscScalar a_x[],
8869: $ PetscReal t, const PetscReal x[], PetscInt numConstants, const PetscScalar constants[], PetscScalar f[]);
8871: + dim - The spatial dimension
8872: . Nf - The number of input fields
8873: . NfAux - The number of input auxiliary fields
8874: . uOff - The offset of each field in u[]
8875: . uOff_x - The offset of each field in u_x[]
8876: . u - The field values at this point in space
8877: . u_t - The field time derivative at this point in space (or NULL)
8878: . u_x - The field derivatives at this point in space
8879: . aOff - The offset of each auxiliary field in u[]
8880: . aOff_x - The offset of each auxiliary field in u_x[]
8881: . a - The auxiliary field values at this point in space
8882: . a_t - The auxiliary field time derivative at this point in space (or NULL)
8883: . a_x - The auxiliary field derivatives at this point in space
8884: . t - The current time
8885: . x - The coordinates of this point
8886: . n - The face normal
8887: . numConstants - The number of constants
8888: . constants - The value of each constant
8889: - f - The value of the function at this point in space
8891: Note:
8892: There are three different DMs that potentially interact in this function. The output DM, dm, specifies the layout of the values calculates by funcs.
8893: The input DM, attached to U, may be different. For example, you can input the solution over the full domain, but output over a piece of the boundary, or
8894: a subdomain. You can also output a different number of fields than the input, with different discretizations. Last the auxiliary DM, attached to the
8895: auxiliary field vector, which is attached to dm, can also be different. It can have a different topology, number of fields, and discretizations.
8897: Level: intermediate
8899: .seealso: DMProjectField(), DMProjectFieldLabelLocal(), DMProjectFunction(), DMComputeL2Diff()
8900: @*/
8901: PetscErrorCode DMProjectBdFieldLabelLocal(DM dm, PetscReal time, DMLabel label, PetscInt numIds, const PetscInt ids[], PetscInt Nc, const PetscInt comps[], Vec localU,
8902: void (**funcs)(PetscInt, PetscInt, PetscInt,
8903: const PetscInt[], const PetscInt[], const PetscScalar[], const PetscScalar[], const PetscScalar[],
8904: const PetscInt[], const PetscInt[], const PetscScalar[], const PetscScalar[], const PetscScalar[],
8905: PetscReal, const PetscReal[], const PetscReal[], PetscInt, const PetscScalar[], PetscScalar[]),
8906: InsertMode mode, Vec localX)
8907: {
8914: if (!dm->ops->projectbdfieldlabellocal) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMProjectBdFieldLabelLocal",((PetscObject)dm)->type_name);
8915: (dm->ops->projectbdfieldlabellocal)(dm, time, label, numIds, ids, Nc, comps, localU, funcs, mode, localX);
8916: return(0);
8917: }
8919: /*@C
8920: DMComputeL2Diff - This function computes the L_2 difference between a function u and an FEM interpolant solution u_h.
8922: Input Parameters:
8923: + dm - The DM
8924: . time - The time
8925: . funcs - The functions to evaluate for each field component
8926: . ctxs - Optional array of contexts to pass to each function, or NULL.
8927: - X - The coefficient vector u_h, a global vector
8929: Output Parameter:
8930: . diff - The diff ||u - u_h||_2
8932: Level: developer
8934: .seealso: DMProjectFunction(), DMComputeL2FieldDiff(), DMComputeL2GradientDiff()
8935: @*/
8936: PetscErrorCode DMComputeL2Diff(DM dm, PetscReal time, PetscErrorCode (**funcs)(PetscInt, PetscReal, const PetscReal [], PetscInt, PetscScalar *, void *), void **ctxs, Vec X, PetscReal *diff)
8937: {
8943: if (!dm->ops->computel2diff) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMComputeL2Diff",((PetscObject)dm)->type_name);
8944: (dm->ops->computel2diff)(dm,time,funcs,ctxs,X,diff);
8945: return(0);
8946: }
8948: /*@C
8949: DMComputeL2GradientDiff - This function computes the L_2 difference between the gradient of a function u and an FEM interpolant solution grad u_h.
8951: Collective on dm
8953: Input Parameters:
8954: + dm - The DM
8955: , time - The time
8956: . funcs - The gradient functions to evaluate for each field component
8957: . ctxs - Optional array of contexts to pass to each function, or NULL.
8958: . X - The coefficient vector u_h, a global vector
8959: - n - The vector to project along
8961: Output Parameter:
8962: . diff - The diff ||(grad u - grad u_h) . n||_2
8964: Level: developer
8966: .seealso: DMProjectFunction(), DMComputeL2Diff()
8967: @*/
8968: PetscErrorCode DMComputeL2GradientDiff(DM dm, PetscReal time, PetscErrorCode (**funcs)(PetscInt, PetscReal, const PetscReal [], const PetscReal[], PetscInt, PetscScalar *, void *), void **ctxs, Vec X, const PetscReal n[], PetscReal *diff)
8969: {
8975: if (!dm->ops->computel2gradientdiff) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMComputeL2GradientDiff",((PetscObject)dm)->type_name);
8976: (dm->ops->computel2gradientdiff)(dm,time,funcs,ctxs,X,n,diff);
8977: return(0);
8978: }
8980: /*@C
8981: DMComputeL2FieldDiff - This function computes the L_2 difference between a function u and an FEM interpolant solution u_h, separated into field components.
8983: Collective on dm
8985: Input Parameters:
8986: + dm - The DM
8987: . time - The time
8988: . funcs - The functions to evaluate for each field component
8989: . ctxs - Optional array of contexts to pass to each function, or NULL.
8990: - X - The coefficient vector u_h, a global vector
8992: Output Parameter:
8993: . diff - The array of differences, ||u^f - u^f_h||_2
8995: Level: developer
8997: .seealso: DMProjectFunction(), DMComputeL2FieldDiff(), DMComputeL2GradientDiff()
8998: @*/
8999: PetscErrorCode DMComputeL2FieldDiff(DM dm, PetscReal time, PetscErrorCode (**funcs)(PetscInt, PetscReal, const PetscReal [], PetscInt, PetscScalar *, void *), void **ctxs, Vec X, PetscReal diff[])
9000: {
9006: if (!dm->ops->computel2fielddiff) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMComputeL2FieldDiff",((PetscObject)dm)->type_name);
9007: (dm->ops->computel2fielddiff)(dm,time,funcs,ctxs,X,diff);
9008: return(0);
9009: }
9011: /*@C
9012: DMAdaptLabel - Adapt a dm based on a label with values interpreted as coarsening and refining flags. Specific implementations of DM maybe have
9013: specialized flags, but all implementations should accept flag values DM_ADAPT_DETERMINE, DM_ADAPT_KEEP, DM_ADAPT_REFINE, and DM_ADAPT_COARSEN.
9015: Collective on dm
9017: Input parameters:
9018: + dm - the pre-adaptation DM object
9019: - label - label with the flags
9021: Output parameters:
9022: . dmAdapt - the adapted DM object: may be NULL if an adapted DM could not be produced.
9024: Level: intermediate
9026: .seealso: DMAdaptMetric(), DMCoarsen(), DMRefine()
9027: @*/
9028: PetscErrorCode DMAdaptLabel(DM dm, DMLabel label, DM *dmAdapt)
9029: {
9036: *dmAdapt = NULL;
9037: if (!dm->ops->adaptlabel) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMAdaptLabel",((PetscObject)dm)->type_name);
9038: (dm->ops->adaptlabel)(dm, label, dmAdapt);
9039: if (*dmAdapt) {
9040: (*dmAdapt)->prealloc_only = dm->prealloc_only; /* maybe this should go .... */
9041: PetscFree((*dmAdapt)->vectype);
9042: PetscStrallocpy(dm->vectype,(char**)&(*dmAdapt)->vectype);
9043: PetscFree((*dmAdapt)->mattype);
9044: PetscStrallocpy(dm->mattype,(char**)&(*dmAdapt)->mattype);
9045: }
9046: return(0);
9047: }
9049: /*@C
9050: DMAdaptMetric - Generates a mesh adapted to the specified metric field using the pragmatic library.
9052: Input Parameters:
9053: + dm - The DM object
9054: . metric - The metric to which the mesh is adapted, defined vertex-wise.
9055: - bdLabel - Label for boundary tags, which will be preserved in the output mesh. bdLabel should be NULL if there is no such label, and should be different from "_boundary_".
9057: Output Parameter:
9058: . dmAdapt - Pointer to the DM object containing the adapted mesh
9060: Note: The label in the adapted mesh will be registered under the name of the input DMLabel object
9062: Level: advanced
9064: .seealso: DMAdaptLabel(), DMCoarsen(), DMRefine()
9065: @*/
9066: PetscErrorCode DMAdaptMetric(DM dm, Vec metric, DMLabel bdLabel, DM *dmAdapt)
9067: {
9075: *dmAdapt = NULL;
9076: if (!dm->ops->adaptmetric) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMAdaptMetric",((PetscObject)dm)->type_name);
9077: (dm->ops->adaptmetric)(dm, metric, bdLabel, dmAdapt);
9078: return(0);
9079: }
9081: /*@C
9082: DMGetNeighbors - Gets an array containing the MPI rank of all the processes neighbors
9084: Not Collective
9086: Input Parameter:
9087: . dm - The DM
9089: Output Parameters:
9090: + nranks - the number of neighbours
9091: - ranks - the neighbors ranks
9093: Notes:
9094: Do not free the array, it is freed when the DM is destroyed.
9096: Level: beginner
9098: .seealso: DMDAGetNeighbors(), PetscSFGetRootRanks()
9099: @*/
9100: PetscErrorCode DMGetNeighbors(DM dm,PetscInt *nranks,const PetscMPIInt *ranks[])
9101: {
9106: if (!dm->ops->getneighbors) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_SUP,"DM type %s does not implement DMGetNeighbors",((PetscObject)dm)->type_name);
9107: (dm->ops->getneighbors)(dm,nranks,ranks);
9108: return(0);
9109: }
9111: #include <petsc/private/matimpl.h>
9113: /*
9114: Converts the input vector to a ghosted vector and then calls the standard coloring code.
9115: This has be a different function because it requires DM which is not defined in the Mat library
9116: */
9117: PetscErrorCode MatFDColoringApply_AIJDM(Mat J,MatFDColoring coloring,Vec x1,void *sctx)
9118: {
9122: if (coloring->ctype == IS_COLORING_LOCAL) {
9123: Vec x1local;
9124: DM dm;
9125: MatGetDM(J,&dm);
9126: if (!dm) SETERRQ(PetscObjectComm((PetscObject)J),PETSC_ERR_ARG_INCOMP,"IS_COLORING_LOCAL requires a DM");
9127: DMGetLocalVector(dm,&x1local);
9128: DMGlobalToLocalBegin(dm,x1,INSERT_VALUES,x1local);
9129: DMGlobalToLocalEnd(dm,x1,INSERT_VALUES,x1local);
9130: x1 = x1local;
9131: }
9132: MatFDColoringApply_AIJ(J,coloring,x1,sctx);
9133: if (coloring->ctype == IS_COLORING_LOCAL) {
9134: DM dm;
9135: MatGetDM(J,&dm);
9136: DMRestoreLocalVector(dm,&x1);
9137: }
9138: return(0);
9139: }
9141: /*@
9142: MatFDColoringUseDM - allows a MatFDColoring object to use the DM associated with the matrix to use a IS_COLORING_LOCAL coloring
9144: Input Parameter:
9145: . coloring - the MatFDColoring object
9147: Developer Notes:
9148: this routine exists because the PETSc Mat library does not know about the DM objects
9150: Level: advanced
9152: .seealso: MatFDColoring, MatFDColoringCreate(), ISColoringType
9153: @*/
9154: PetscErrorCode MatFDColoringUseDM(Mat coloring,MatFDColoring fdcoloring)
9155: {
9157: coloring->ops->fdcoloringapply = MatFDColoringApply_AIJDM;
9158: return(0);
9159: }
9161: /*@
9162: DMGetCompatibility - determine if two DMs are compatible
9164: Collective
9166: Input Parameters:
9167: + dm1 - the first DM
9168: - dm2 - the second DM
9170: Output Parameters:
9171: + compatible - whether or not the two DMs are compatible
9172: - set - whether or not the compatible value was set
9174: Notes:
9175: Two DMs are deemed compatible if they represent the same parallel decomposition
9176: of the same topology. This implies that the section (field data) on one
9177: "makes sense" with respect to the topology and parallel decomposition of the other.
9178: Loosely speaking, compatible DMs represent the same domain and parallel
9179: decomposition, but hold different data.
9181: Typically, one would confirm compatibility if intending to simultaneously iterate
9182: over a pair of vectors obtained from different DMs.
9184: For example, two DMDA objects are compatible if they have the same local
9185: and global sizes and the same stencil width. They can have different numbers
9186: of degrees of freedom per node. Thus, one could use the node numbering from
9187: either DM in bounds for a loop over vectors derived from either DM.
9189: Consider the operation of summing data living on a 2-dof DMDA to data living
9190: on a 1-dof DMDA, which should be compatible, as in the following snippet.
9191: .vb
9192: ...
9193: DMGetCompatibility(da1,da2,&compatible,&set);
9194: if (set && compatible) {
9195: DMDAVecGetArrayDOF(da1,vec1,&arr1);
9196: DMDAVecGetArrayDOF(da2,vec2,&arr2);
9197: DMDAGetCorners(da1,&x,&y,NULL,&m,&n,NULL);
9198: for (j=y; j<y+n; ++j) {
9199: for (i=x; i<x+m, ++i) {
9200: arr1[j][i][0] = arr2[j][i][0] + arr2[j][i][1];
9201: }
9202: }
9203: DMDAVecRestoreArrayDOF(da1,vec1,&arr1);
9204: DMDAVecRestoreArrayDOF(da2,vec2,&arr2);
9205: } else {
9206: SETERRQ(PetscObjectComm((PetscObject)da1,PETSC_ERR_ARG_INCOMP,"DMDA objects incompatible");
9207: }
9208: ...
9209: .ve
9211: Checking compatibility might be expensive for a given implementation of DM,
9212: or might be impossible to unambiguously confirm or deny. For this reason,
9213: this function may decline to determine compatibility, and hence users should
9214: always check the "set" output parameter.
9216: A DM is always compatible with itself.
9218: In the current implementation, DMs which live on "unequal" communicators
9219: (MPI_UNEQUAL in the terminology of MPI_Comm_compare()) are always deemed
9220: incompatible.
9222: This function is labeled "Collective," as information about all subdomains
9223: is required on each rank. However, in DM implementations which store all this
9224: information locally, this function may be merely "Logically Collective".
9226: Developer Notes:
9227: Compatibility is assumed to be a symmetric concept; DM A is compatible with DM B
9228: iff B is compatible with A. Thus, this function checks the implementations
9229: of both dm and dmc (if they are of different types), attempting to determine
9230: compatibility. It is left to DM implementers to ensure that symmetry is
9231: preserved. The simplest way to do this is, when implementing type-specific
9232: logic for this function, is to check for existing logic in the implementation
9233: of other DM types and let *set = PETSC_FALSE if found.
9235: Level: advanced
9237: .seealso: DM, DMDACreateCompatibleDMDA(), DMStagCreateCompatibleDMStag()
9238: @*/
9240: PetscErrorCode DMGetCompatibility(DM dm1,DM dm2,PetscBool *compatible,PetscBool *set)
9241: {
9243: PetscMPIInt compareResult;
9244: DMType type,type2;
9245: PetscBool sameType;
9251: /* Declare a DM compatible with itself */
9252: if (dm1 == dm2) {
9253: *set = PETSC_TRUE;
9254: *compatible = PETSC_TRUE;
9255: return(0);
9256: }
9258: /* Declare a DM incompatible with a DM that lives on an "unequal"
9259: communicator. Note that this does not preclude compatibility with
9260: DMs living on "congruent" or "similar" communicators, but this must be
9261: determined by the implementation-specific logic */
9262: MPI_Comm_compare(PetscObjectComm((PetscObject)dm1),PetscObjectComm((PetscObject)dm2),&compareResult);
9263: if (compareResult == MPI_UNEQUAL) {
9264: *set = PETSC_TRUE;
9265: *compatible = PETSC_FALSE;
9266: return(0);
9267: }
9269: /* Pass to the implementation-specific routine, if one exists. */
9270: if (dm1->ops->getcompatibility) {
9271: (*dm1->ops->getcompatibility)(dm1,dm2,compatible,set);
9272: if (*set) return(0);
9273: }
9275: /* If dm1 and dm2 are of different types, then attempt to check compatibility
9276: with an implementation of this function from dm2 */
9277: DMGetType(dm1,&type);
9278: DMGetType(dm2,&type2);
9279: PetscStrcmp(type,type2,&sameType);
9280: if (!sameType && dm2->ops->getcompatibility) {
9281: (*dm2->ops->getcompatibility)(dm2,dm1,compatible,set); /* Note argument order */
9282: } else {
9283: *set = PETSC_FALSE;
9284: }
9285: return(0);
9286: }
9288: /*@C
9289: DMMonitorSet - Sets an ADDITIONAL function that is to be used after a solve to monitor discretization performance.
9291: Logically Collective on DM
9293: Input Parameters:
9294: + DM - the DM
9295: . f - the monitor function
9296: . mctx - [optional] user-defined context for private data for the monitor routine (use NULL if no context is desired)
9297: - monitordestroy - [optional] routine that frees monitor context (may be NULL)
9299: Options Database Keys:
9300: - -dm_monitor_cancel - cancels all monitors that have been hardwired into a code by calls to DMMonitorSet(), but
9301: does not cancel those set via the options database.
9303: Notes:
9304: Several different monitoring routines may be set by calling
9305: DMMonitorSet() multiple times; all will be called in the
9306: order in which they were set.
9308: Fortran Notes:
9309: Only a single monitor function can be set for each DM object
9311: Level: intermediate
9313: .seealso: DMMonitorCancel()
9314: @*/
9315: PetscErrorCode DMMonitorSet(DM dm, PetscErrorCode (*f)(DM, void *), void *mctx, PetscErrorCode (*monitordestroy)(void**))
9316: {
9317: PetscInt m;
9322: for (m = 0; m < dm->numbermonitors; ++m) {
9323: PetscBool identical;
9325: PetscMonitorCompare((PetscErrorCode (*)(void)) f, mctx, monitordestroy, (PetscErrorCode (*)(void)) dm->monitor[m], dm->monitorcontext[m], dm->monitordestroy[m], &identical);
9326: if (identical) return(0);
9327: }
9328: if (dm->numbermonitors >= MAXDMMONITORS) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Too many monitors set");
9329: dm->monitor[dm->numbermonitors] = f;
9330: dm->monitordestroy[dm->numbermonitors] = monitordestroy;
9331: dm->monitorcontext[dm->numbermonitors++] = (void *) mctx;
9332: return(0);
9333: }
9335: /*@
9336: DMMonitorCancel - Clears all the monitor functions for a DM object.
9338: Logically Collective on DM
9340: Input Parameter:
9341: . dm - the DM
9343: Options Database Key:
9344: . -dm_monitor_cancel - cancels all monitors that have been hardwired
9345: into a code by calls to DMonitorSet(), but does not cancel those
9346: set via the options database
9348: Notes:
9349: There is no way to clear one specific monitor from a DM object.
9351: Level: intermediate
9353: .seealso: DMMonitorSet()
9354: @*/
9355: PetscErrorCode DMMonitorCancel(DM dm)
9356: {
9358: PetscInt m;
9362: for (m = 0; m < dm->numbermonitors; ++m) {
9363: if (dm->monitordestroy[m]) {(*dm->monitordestroy[m])(&dm->monitorcontext[m]);}
9364: }
9365: dm->numbermonitors = 0;
9366: return(0);
9367: }
9369: /*@C
9370: DMMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type indicated by the user
9372: Collective on DM
9374: Input Parameters:
9375: + dm - DM object you wish to monitor
9376: . name - the monitor type one is seeking
9377: . help - message indicating what monitoring is done
9378: . manual - manual page for the monitor
9379: . monitor - the monitor function
9380: - monitorsetup - a function that is called once ONLY if the user selected this monitor that may set additional features of the DM or PetscViewer objects
9382: Output Parameter:
9383: . flg - Flag set if the monitor was created
9385: Level: developer
9387: .seealso: PetscOptionsGetViewer(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
9388: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
9389: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
9390: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
9391: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
9392: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
9393: PetscOptionsFList(), PetscOptionsEList()
9394: @*/
9395: PetscErrorCode DMMonitorSetFromOptions(DM dm, const char name[], const char help[], const char manual[], PetscErrorCode (*monitor)(DM, void *), PetscErrorCode (*monitorsetup)(DM, PetscViewerAndFormat *), PetscBool *flg)
9396: {
9397: PetscViewer viewer;
9398: PetscViewerFormat format;
9399: PetscErrorCode ierr;
9403: PetscOptionsGetViewer(PetscObjectComm((PetscObject) dm), ((PetscObject) dm)->options, ((PetscObject) dm)->prefix, name, &viewer, &format, flg);
9404: if (*flg) {
9405: PetscViewerAndFormat *vf;
9407: PetscViewerAndFormatCreate(viewer, format, &vf);
9408: PetscObjectDereference((PetscObject) viewer);
9409: if (monitorsetup) {(*monitorsetup)(dm, vf);}
9410: DMMonitorSet(dm,(PetscErrorCode (*)(DM, void *)) monitor, vf, (PetscErrorCode (*)(void **)) PetscViewerAndFormatDestroy);
9411: }
9412: return(0);
9413: }
9415: /*@
9416: DMMonitor - runs the user provided monitor routines, if they exist
9418: Collective on DM
9420: Input Parameters:
9421: . dm - The DM
9423: Level: developer
9425: .seealso: DMMonitorSet()
9426: @*/
9427: PetscErrorCode DMMonitor(DM dm)
9428: {
9429: PetscInt m;
9433: if (!dm) return(0);
9435: for (m = 0; m < dm->numbermonitors; ++m) {
9436: (*dm->monitor[m])(dm, dm->monitorcontext[m]);
9437: }
9438: return(0);
9439: }
9441: /*@
9442: DMComputeError - Computes the error assuming the user has given exact solution functions
9444: Collective on DM
9446: Input Parameters:
9447: + dm - The DM
9448: . sol - The solution vector
9449: . errors - An array of length Nf, the number of fields, or NULL for no output
9450: - errorVec - A Vec pointer, or NULL for no output
9452: Output Parameters:
9453: + errors - The error in each field
9454: - errorVec - Creates a vector to hold the cellwise error
9456: Note: The exact solutions come from the PetscDS object, and the time comes from DMGetOutputSequenceNumber().
9458: Level: developer
9460: .seealso: DMMonitorSet(), DMGetRegionNumDS(), PetscDSGetExactSolution(), DMGetOutputSequenceNumber()
9461: @*/
9462: PetscErrorCode DMComputeError(DM dm, Vec sol, PetscReal errors[], Vec *errorVec)
9463: {
9464: PetscErrorCode (**exactSol)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *);
9465: void **ctxs;
9466: PetscReal time;
9467: PetscInt Nf, f, Nds, s;
9468: PetscErrorCode ierr;
9471: DMGetNumFields(dm, &Nf);
9472: PetscCalloc2(Nf, &exactSol, Nf, &ctxs);
9473: DMGetNumDS(dm, &Nds);
9474: for (s = 0; s < Nds; ++s) {
9475: PetscDS ds;
9476: DMLabel label;
9477: IS fieldIS;
9478: const PetscInt *fields;
9479: PetscInt dsNf;
9481: DMGetRegionNumDS(dm, s, &label, &fieldIS, &ds);
9482: PetscDSGetNumFields(ds, &dsNf);
9483: if (fieldIS) {ISGetIndices(fieldIS, &fields);}
9484: for (f = 0; f < dsNf; ++f) {
9485: const PetscInt field = fields[f];
9486: PetscDSGetExactSolution(ds, field, &exactSol[field], &ctxs[field]);
9487: }
9488: if (fieldIS) {ISRestoreIndices(fieldIS, &fields);}
9489: }
9490: for (f = 0; f < Nf; ++f) {
9491: if (!exactSol[f]) SETERRQ1(PetscObjectComm((PetscObject) dm), PETSC_ERR_ARG_WRONG, "DS must contain exact solution functions in order to calculate error, missing for field %D", f);
9492: }
9493: DMGetOutputSequenceNumber(dm, NULL, &time);
9494: if (errors) {DMComputeL2FieldDiff(dm, time, exactSol, ctxs, sol, errors);}
9495: if (errorVec) {
9496: DM edm;
9497: DMPolytopeType ct;
9498: PetscBool simplex;
9499: PetscInt dim, cStart, Nf;
9501: DMClone(dm, &edm);
9502: DMGetDimension(edm, &dim);
9503: DMPlexGetHeightStratum(dm, 0, &cStart, NULL);
9504: DMPlexGetCellType(dm, cStart, &ct);
9505: simplex = DMPolytopeTypeGetNumVertices(ct) == DMPolytopeTypeGetDim(ct)+1 ? PETSC_TRUE : PETSC_FALSE;
9506: DMGetNumFields(dm, &Nf);
9507: for (f = 0; f < Nf; ++f) {
9508: PetscFE fe, efe;
9509: PetscQuadrature q;
9510: const char *name;
9512: DMGetField(dm, f, NULL, (PetscObject *) &fe);
9513: PetscFECreateLagrange(PETSC_COMM_SELF, dim, Nf, simplex, 0, PETSC_DETERMINE, &efe);
9514: PetscObjectGetName((PetscObject) fe, &name);
9515: PetscObjectSetName((PetscObject) efe, name);
9516: PetscFEGetQuadrature(fe, &q);
9517: PetscFESetQuadrature(efe, q);
9518: DMSetField(edm, f, NULL, (PetscObject) efe);
9519: PetscFEDestroy(&efe);
9520: }
9521: DMCreateDS(edm);
9523: DMCreateGlobalVector(edm, errorVec);
9524: PetscObjectSetName((PetscObject) *errorVec, "Error");
9525: DMPlexComputeL2DiffVec(dm, time, exactSol, ctxs, sol, *errorVec);
9526: DMDestroy(&edm);
9527: }
9528: PetscFree2(exactSol, ctxs);
9529: return(0);
9530: }