Actual source code: coarsen.c
petsc-3.11.4 2019-09-28
2: #include <petsc/private/matimpl.h>
4: /* Logging support */
5: PetscClassId MAT_COARSEN_CLASSID;
7: PetscFunctionList MatCoarsenList = 0;
8: PetscBool MatCoarsenRegisterAllCalled = PETSC_FALSE;
10: /*@C
11: MatCoarsenRegister - Adds a new sparse matrix coarsening algorithm to the matrix package.
13: Logically Collective
15: Input Parameters:
16: + sname - name of coarsen (for example MATCOARSENMIS)
17: - function - function pointer that creates the coarsen type
19: Level: developer
21: Sample usage:
22: .vb
23: MatCoarsenRegister("my_agg",MyAggCreate);
24: .ve
26: Then, your aggregator can be chosen with the procedural interface via
27: $ MatCoarsenSetType(agg,"my_agg")
28: or at runtime via the option
29: $ -mat_coarsen_type my_agg
31: .keywords: matrix, coarsen, register
33: .seealso: MatCoarsenRegisterDestroy(), MatCoarsenRegisterAll()
34: @*/
35: PetscErrorCode MatCoarsenRegister(const char sname[],PetscErrorCode (*function)(MatCoarsen))
36: {
40: MatInitializePackage();
41: PetscFunctionListAdd(&MatCoarsenList,sname,function);
42: return(0);
43: }
45: /*@C
46: MatCoarsenGetType - Gets the Coarsen method type and name (as a string)
47: from the coarsen context.
49: Not collective
51: Input Parameter:
52: . coarsen - the coarsen context
54: Output Parameter:
55: . type - coarsener type
57: Level: advanced
59: Not Collective
61: .keywords: Coarsen, get, method, name, type
63: .seealso: MatCoarsenCreate(), MatCoarsenType, MatCoarsenSetType()
64: @*/
65: PetscErrorCode MatCoarsenGetType(MatCoarsen coarsen,MatCoarsenType *type)
66: {
70: *type = ((PetscObject)coarsen)->type_name;
71: return(0);
72: }
74: /*@
75: MatCoarsenApply - Gets a coarsen for a matrix.
77: Collective on MatCoarsen
79: Input Parameter:
80: . coarsen - the coarsen
82: Options Database Keys:
83: To specify the coarsen through the options database, use one of
84: the following
85: $ -mat_coarsen_type mis
86: To see the coarsen result
87: $ -mat_coarsen_view
89: Level: advanced
91: Notes:
92: Use MatCoarsenGetData() to access the results of the coarsening
94: The user can define additional coarsens; see MatCoarsenRegister().
96: .keywords: matrix, get, coarsen
98: .seealso: MatCoarsenRegister(), MatCoarsenCreate(),
99: MatCoarsenDestroy(), MatCoarsenSetAdjacency(), ISCoarsenToNumbering(),
100: ISCoarsenCount(), MatCoarsenGetData()
101: @*/
102: PetscErrorCode MatCoarsenApply(MatCoarsen coarser)
103: {
109: if (!coarser->graph->assembled) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
110: if (coarser->graph->factortype) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
111: if (!coarser->ops->apply) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"Must set type with MatCoarsenSetFromOptions() or MatCoarsenSetType()");
112: PetscLogEventBegin(MAT_Coarsen,coarser,0,0,0);
113: (*coarser->ops->apply)(coarser);
114: PetscLogEventEnd(MAT_Coarsen,coarser,0,0,0);
115: return(0);
116: }
118: /*@
119: MatCoarsenSetAdjacency - Sets the adjacency graph (matrix) of the thing to be coarsened.
121: Collective on MatCoarsen and Mat
123: Input Parameters:
124: + agg - the coarsen context
125: - adj - the adjacency matrix
127: Level: advanced
129: .keywords: Coarsen, adjacency
131: .seealso: MatCoarsenCreate(), MatCoarsenApply()
132: @*/
133: PetscErrorCode MatCoarsenSetAdjacency(MatCoarsen agg, Mat adj)
134: {
138: agg->graph = adj;
139: return(0);
140: }
142: /*@
143: MatCoarsenSetStrictAggs - WHAT IS THIS?
145: Logically Collective on MatCoarsen
147: Input Parameters:
148: + agg - the coarsen context
149: - str - the adjacency matrix
151: Level: advanced
153: .keywords: Coarsen, adjacency
155: .seealso: MatCoarsenCreate()
156: @*/
157: PetscErrorCode MatCoarsenSetStrictAggs(MatCoarsen agg, PetscBool str)
158: {
161: agg->strict_aggs = str;
162: return(0);
163: }
165: /*@
166: MatCoarsenDestroy - Destroys the coarsen context.
168: Collective on MatCoarsen
170: Input Parameters:
171: . agg - the coarsen context
173: Level: advanced
175: .keywords: Coarsen, destroy, context
177: .seealso: MatCoarsenCreate()
178: @*/
179: PetscErrorCode MatCoarsenDestroy(MatCoarsen *agg)
180: {
184: if (!*agg) return(0);
186: if (--((PetscObject)(*agg))->refct > 0) {*agg = 0; return(0);}
188: if ((*agg)->ops->destroy) {
189: (*(*agg)->ops->destroy)((*agg));
190: }
192: if ((*agg)->agg_lists) {
193: PetscCDDestroy((*agg)->agg_lists);
194: }
196: PetscHeaderDestroy(agg);
197: return(0);
198: }
200: /*@
201: MatCoarsenCreate - Creates a coarsen context.
203: Collective on MPI_Comm
205: Input Parameter:
206: . comm - MPI communicator
208: Output Parameter:
209: . newcrs - location to put the context
211: Level: advanced
213: .keywords: Coarsen, create, context
215: .seealso: MatCoarsenSetType(), MatCoarsenApply(), MatCoarsenDestroy(),
216: MatCoarsenSetAdjacency(), MatCoarsenGetData()
218: @*/
219: PetscErrorCode MatCoarsenCreate(MPI_Comm comm, MatCoarsen *newcrs)
220: {
221: MatCoarsen agg;
225: *newcrs = 0;
227: MatInitializePackage();
228: PetscHeaderCreate(agg, MAT_COARSEN_CLASSID,"MatCoarsen","Matrix/graph coarsen", "MatCoarsen", comm, MatCoarsenDestroy, MatCoarsenView);
230: *newcrs = agg;
231: return(0);
232: }
234: /*@C
235: MatCoarsenView - Prints the coarsen data structure.
237: Collective on MatCoarsen
239: Input Parameters:
240: . agg - the coarsen context
241: . viewer - optional visualization context
243: Level: advanced
245: Note:
246: The available visualization contexts include
247: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
248: - PETSC_VIEWER_STDOUT_WORLD - synchronized standard
249: output where only the first processor opens
250: the file. All other processors send their
251: data to the first processor to print.
253: The user can open alternative visualization contexts with
254: . PetscViewerASCIIOpen() - output to a specified file
256: .keywords: Coarsen, view
258: .seealso: PetscViewerASCIIOpen()
259: @*/
260: PetscErrorCode MatCoarsenView(MatCoarsen agg,PetscViewer viewer)
261: {
263: PetscBool iascii;
267: if (!viewer) {
268: PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)agg),&viewer);
269: }
273: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
274: PetscObjectPrintClassNamePrefixType((PetscObject)agg,viewer);
275: if (agg->ops->view) {
276: PetscViewerASCIIPushTab(viewer);
277: (*agg->ops->view)(agg,viewer);
278: PetscViewerASCIIPopTab(viewer);
279: }
280: return(0);
281: }
283: /*@C
284: MatCoarsenSetType - Sets the type of aggregator to use
286: Collective on MatCoarsen
288: Input Parameter:
289: + coarser - the coarsen context.
290: - type - a known coarsening method
292: Options Database Command:
293: $ -mat_coarsen_type <type>
294: $ Use -help for a list of available methods
295: $ (for instance, mis)
297: Level: advanced
299: .keywords: coarsen, set, method, type
301: .seealso: MatCoarsenCreate(), MatCoarsenApply(), MatCoarsenType, MatCoarsenGetType()
303: @*/
304: PetscErrorCode MatCoarsenSetType(MatCoarsen coarser, MatCoarsenType type)
305: {
306: PetscErrorCode ierr,(*r)(MatCoarsen);
307: PetscBool match;
313: PetscObjectTypeCompare((PetscObject)coarser,type,&match);
314: if (match) return(0);
316: if (coarser->setupcalled) {
317: (*coarser->ops->destroy)(coarser);
319: coarser->ops->destroy = NULL;
320: coarser->subctx = 0;
321: coarser->setupcalled = 0;
322: }
324: PetscFunctionListFind(MatCoarsenList,type,&r);
326: if (!r) SETERRQ1(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown coarsen type %s",type);
328: coarser->ops->destroy = (PetscErrorCode (*)(MatCoarsen)) 0;
329: coarser->ops->view = (PetscErrorCode (*)(MatCoarsen,PetscViewer)) 0;
331: (*r)(coarser);
333: PetscFree(((PetscObject)coarser)->type_name);
334: PetscStrallocpy(type,&((PetscObject)coarser)->type_name);
335: return(0);
336: }
338: /*@C
339: MatCoarsenSetGreedyOrdering - Sets the ordering of the vertices to use with a greedy coarsening method
341: Logically Collective on Coarsen
343: Input Parameters:
344: + coarser - the coarsen context
345: - perm - vertex ordering of (greedy) algorithm
347: Level: advanced
349: Notes:
350: The IS weights is freed by PETSc, so user has given this to us
352: .keywords: Coarsen
354: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
355: @*/
356: PetscErrorCode MatCoarsenSetGreedyOrdering(MatCoarsen coarser, const IS perm)
357: {
360: coarser->perm = perm;
361: return(0);
362: }
364: /*@C
365: MatCoarsenGetData - Gets the weights for vertices for a coarsen.
367: Logically Collective on Coarsen
369: Input Parameter:
370: . coarser - the coarsen context
372: Output Parameter:
373: . llist - linked list of aggregates
375: Level: advanced
377: .keywords: Coarsen
379: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
380: @*/
381: PetscErrorCode MatCoarsenGetData(MatCoarsen coarser, PetscCoarsenData **llist)
382: {
385: if (!coarser->agg_lists) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"No linked list - generate it or call ApplyCoarsen");
386: *llist = coarser->agg_lists;
387: coarser->agg_lists = 0; /* giving up ownership */
388: return(0);
389: }
391: /*@
392: MatCoarsenSetFromOptions - Sets various coarsen options from the
393: options database.
395: Collective on MatCoarsen
397: Input Parameter:
398: . coarser - the coarsen context.
400: Options Database Command:
401: $ -mat_coarsen_type <type>
402: $ Use -help for a list of available methods
403: $ (for instance, mis)
405: Level: advanced
407: .keywords: coarsen, set, method, type
408: @*/
409: PetscErrorCode MatCoarsenSetFromOptions(MatCoarsen coarser)
410: {
412: PetscBool flag;
413: char type[256];
414: const char *def;
417: PetscObjectOptionsBegin((PetscObject)coarser);
418: if (!((PetscObject)coarser)->type_name) {
419: def = MATCOARSENMIS;
420: } else {
421: def = ((PetscObject)coarser)->type_name;
422: }
424: PetscOptionsFList("-mat_coarsen_type","Type of aggregator","MatCoarsenSetType",MatCoarsenList,def,type,256,&flag);
425: if (flag) {
426: MatCoarsenSetType(coarser,type);
427: }
428: /*
429: Set the type if it was never set.
430: */
431: if (!((PetscObject)coarser)->type_name) {
432: MatCoarsenSetType(coarser,def);
433: }
435: if (coarser->ops->setfromoptions) {
436: (*coarser->ops->setfromoptions)(PetscOptionsObject,coarser);
437: }
438: PetscOptionsEnd();
439: MatCoarsenViewFromOptions(coarser,NULL,"-mat_coarsen_view");
440: return(0);
441: }