Actual source code: coarsen.c
2: #include <petsc/private/matimpl.h>
4: /* Logging support */
5: PetscClassId MAT_COARSEN_CLASSID;
7: PetscFunctionList MatCoarsenList = NULL;
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: .seealso: `MatCoarsen`, `MatCoarsenType`, `MatCoarsenSetType()`, `MatCoarsenCreate()`, `MatCoarsenRegisterDestroy()`, `MatCoarsenRegisterAll()`
32: @*/
33: PetscErrorCode MatCoarsenRegister(const char sname[], PetscErrorCode (*function)(MatCoarsen))
34: {
35: MatInitializePackage();
36: PetscFunctionListAdd(&MatCoarsenList, sname, function);
37: return 0;
38: }
40: /*@C
41: MatCoarsenGetType - Gets the Coarsen method type and name (as a string)
42: from the coarsen context.
44: Not collective
46: Input Parameter:
47: . coarsen - the coarsen context
49: Output Parameter:
50: . type - coarsener type
52: Level: advanced
54: Not Collective
56: .seealso: `MatCoarsen`, `MatCoarsenCreate()`, `MatCoarsenType`, `MatCoarsenSetType()`, `MatCoarsenRegister()`
57: @*/
58: PetscErrorCode MatCoarsenGetType(MatCoarsen coarsen, MatCoarsenType *type)
59: {
62: *type = ((PetscObject)coarsen)->type_name;
63: return 0;
64: }
66: /*@
67: MatCoarsenApply - Gets a coarsen for a matrix.
69: Collective on coarser
71: Input Parameter:
72: . coarsen - the coarsen
74: Options Database Keys:
75: To specify the coarsen through the options database, use one of
76: the following
77: $ -mat_coarsen_type mis|hem|misk
78: To see the coarsen result
79: $ -mat_coarsen_view
81: Level: advanced
83: Notes:
84: Use `MatCoarsenGetData()` to access the results of the coarsening
86: The user can define additional coarsens; see `MatCoarsenRegister()`.
88: .seealso: `MatCoarsen`, `MatCoarseSetFromOptions()`, `MatCoarsenSetType()`, `MatCoarsenRegister()`, `MatCoarsenCreate()`,
89: `MatCoarsenDestroy()`, `MatCoarsenSetAdjacency()`
90: `MatCoarsenGetData()`
91: @*/
92: PetscErrorCode MatCoarsenApply(MatCoarsen coarser)
93: {
98: PetscLogEventBegin(MAT_Coarsen, coarser, 0, 0, 0);
99: PetscUseTypeMethod(coarser, apply);
100: PetscLogEventEnd(MAT_Coarsen, coarser, 0, 0, 0);
101: return 0;
102: }
104: /*@
105: MatCoarsenSetAdjacency - Sets the adjacency graph (matrix) of the thing to be coarsened.
107: Collective on agg
109: Input Parameters:
110: + agg - the coarsen context
111: - adj - the adjacency matrix
113: Level: advanced
115: .seealso: `MatCoarsen`, `MatCoarsenSetFromOptions()`, `Mat`, `MatCoarsenCreate()`, `MatCoarsenApply()`
116: @*/
117: PetscErrorCode MatCoarsenSetAdjacency(MatCoarsen agg, Mat adj)
118: {
121: agg->graph = adj;
122: return 0;
123: }
125: /*@
126: MatCoarsenSetStrictAggs - Set whether to keep strict (non overlapping) aggregates in the linked list of aggregates for a coarsen context
128: Logically Collective on agg
130: Input Parameters:
131: + agg - the coarsen context
132: - str - `PETSC_TRUE` keep strict aggregates, `PETSC_FALSE` allow overlap
133: Level: advanced
135: .seealso: `MatCoarsen`, `MatCoarsenCreate()`, `MatCoarsenSetFromOptions()`
136: @*/
137: PetscErrorCode MatCoarsenSetStrictAggs(MatCoarsen agg, PetscBool str)
138: {
140: agg->strict_aggs = str;
141: return 0;
142: }
144: /*@
145: MatCoarsenDestroy - Destroys the coarsen context.
147: Collective on agg
149: Input Parameters:
150: . agg - the coarsen context
152: Level: advanced
154: .seealso: `MatCoarsen`, `MatCoarsenCreate()`
155: @*/
156: PetscErrorCode MatCoarsenDestroy(MatCoarsen *agg)
157: {
158: if (!*agg) return 0;
160: if (--((PetscObject)(*agg))->refct > 0) {
161: *agg = NULL;
162: return 0;
163: }
165: if ((*agg)->ops->destroy) (*(*agg)->ops->destroy)((*agg));
167: if ((*agg)->agg_lists) PetscCDDestroy((*agg)->agg_lists);
169: PetscHeaderDestroy(agg);
170: return 0;
171: }
173: /*@
174: MatCoarsenCreate - Creates a coarsen context.
176: Collective
178: Input Parameter:
179: . comm - MPI communicator
181: Output Parameter:
182: . newcrs - location to put the context
184: Level: advanced
186: .seealso: `MatCoarsen`, `MatCoarsenSetType()`, `MatCoarsenApply()`, `MatCoarsenDestroy()`,
187: `MatCoarsenSetAdjacency()`, `MatCoarsenGetData()`
189: @*/
190: PetscErrorCode MatCoarsenCreate(MPI_Comm comm, MatCoarsen *newcrs)
191: {
192: MatCoarsen agg;
194: *newcrs = NULL;
196: MatInitializePackage();
197: PetscHeaderCreate(agg, MAT_COARSEN_CLASSID, "MatCoarsen", "Matrix/graph coarsen", "MatCoarsen", comm, MatCoarsenDestroy, MatCoarsenView);
199: *newcrs = agg;
200: return 0;
201: }
203: /*@C
204: MatCoarsenViewFromOptions - View the coarsener from the options database
206: Collective on A
208: Input Parameters:
209: + A - the coarsen context
210: . obj - Optional object that provides the prefix for the option name
211: - name - command line option (usually `-mat_coarsen_view`)
213: Options Database:
214: . -mat_coarsen_view [viewertype]:... - the viewer and its options
216: Note:
217: .vb
218: If no value is provided ascii:stdout is used
219: ascii[:[filename][:[format][:append]]] defaults to stdout - format can be one of ascii_info, ascii_info_detail, or ascii_matlab,
220: for example ascii::ascii_info prints just the information about the object not all details
221: unless :append is given filename opens in write mode, overwriting what was already there
222: binary[:[filename][:[format][:append]]] defaults to the file binaryoutput
223: draw[:drawtype[:filename]] for example, draw:tikz, draw:tikz:figure.tex or draw:x
224: socket[:port] defaults to the standard output port
225: saws[:communicatorname] publishes object to the Scientific Application Webserver (SAWs)
226: .ve
228: Level: intermediate
230: .seealso: `MatCoarsen`, `MatCoarsenView`, `PetscObjectViewFromOptions()`, `MatCoarsenCreate()`
231: @*/
232: PetscErrorCode MatCoarsenViewFromOptions(MatCoarsen A, PetscObject obj, const char name[])
233: {
235: PetscObjectViewFromOptions((PetscObject)A, obj, name);
236: return 0;
237: }
239: /*@C
240: MatCoarsenView - Prints the coarsen data structure.
242: Collective on agg
244: Input Parameters:
245: + agg - the coarsen context
246: - viewer - optional visualization context
248: For viewing the options database see `MatCoarsenViewFromOptions()`
250: Level: advanced
252: .seealso: `MatCoarsen`, `PetscViewer`, `PetscViewerASCIIOpen()`, `MatCoarsenViewFromOptions`
253: @*/
254: PetscErrorCode MatCoarsenView(MatCoarsen agg, PetscViewer viewer)
255: {
256: PetscBool iascii;
259: if (!viewer) PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)agg), &viewer);
263: PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWERASCII, &iascii);
264: PetscObjectPrintClassNamePrefixType((PetscObject)agg, viewer);
265: if (agg->ops->view) {
266: PetscViewerASCIIPushTab(viewer);
267: PetscUseTypeMethod(agg, view, viewer);
268: PetscViewerASCIIPopTab(viewer);
269: }
270: return 0;
271: }
273: /*@C
274: MatCoarsenSetType - Sets the type of aggregator to use
276: Collective on coarser
278: Input Parameters:
279: + coarser - the coarsen context.
280: - type - a known coarsening method
282: Options Database Command:
283: $ -mat_coarsen_type <type>
284: $ Use -help for a list of available methods
285: $ (for instance, misk)
287: Level: advanced
289: .seealso: `MatCoarsen`, `MatCoarsenCreate()`, `MatCoarsenApply()`, `MatCoarsenType`, `MatCoarsenGetType()`
290: @*/
291: PetscErrorCode MatCoarsenSetType(MatCoarsen coarser, MatCoarsenType type)
292: {
293: PetscBool match;
294: PetscErrorCode (*r)(MatCoarsen);
299: PetscObjectTypeCompare((PetscObject)coarser, type, &match);
300: if (match) return 0;
302: PetscTryTypeMethod(coarser, destroy);
303: coarser->ops->destroy = NULL;
304: PetscMemzero(coarser->ops, sizeof(struct _MatCoarsenOps));
306: PetscFunctionListFind(MatCoarsenList, type, &r);
308: (*r)(coarser);
310: PetscFree(((PetscObject)coarser)->type_name);
311: PetscStrallocpy(type, &((PetscObject)coarser)->type_name);
312: return 0;
313: }
315: /*@C
316: MatCoarsenSetGreedyOrdering - Sets the ordering of the vertices to use with a greedy coarsening method
318: Logically Collective on coarser
320: Input Parameters:
321: + coarser - the coarsen context
322: - perm - vertex ordering of (greedy) algorithm
324: Level: advanced
326: Note:
327: The `IS` weights is freed by PETSc, the user should not destroy it or change it after this call
329: .seealso: `MatCoarsen`, `MatCoarsenType`, `MatCoarsenCreate()`, `MatCoarsenSetType()`
330: @*/
331: PetscErrorCode MatCoarsenSetGreedyOrdering(MatCoarsen coarser, const IS perm)
332: {
334: coarser->perm = perm;
335: return 0;
336: }
338: /*@C
339: MatCoarsenGetData - Gets the weights for vertices for a coarsener.
341: Logically Collective on coarser
343: Input Parameter:
344: . coarser - the coarsen context
346: Output Parameter:
347: . llist - linked list of aggregates
349: Level: advanced
351: .seealso: `MatCoarsen`, `MatCoarsenApply()`, `MatCoarsenCreate()`, `MatCoarsenSetType()`
352: @*/
353: PetscErrorCode MatCoarsenGetData(MatCoarsen coarser, PetscCoarsenData **llist)
354: {
357: *llist = coarser->agg_lists;
358: coarser->agg_lists = NULL; /* giving up ownership */
359: return 0;
360: }
362: /*@
363: MatCoarsenSetFromOptions - Sets various coarsen options from the options database.
365: Collective on coarser
367: Input Parameter:
368: . coarser - the coarsen context.
370: Options Database Command:
371: $ -mat_coarsen_type <type>
372: $ Use -help for a list of available methods
373: $ (for instance, mis)
375: Level: advanced
377: Note:
378: Set the `MatCoarsenType` to `MATCOARSENMISK` if has not been set previously
380: .seealso: `MatCoarsen`, `MatCoarsenType`, `MatCoarsenApply()`, `MatCoarsenCreate()`, `MatCoarsenSetType()`
381: @*/
382: PetscErrorCode MatCoarsenSetFromOptions(MatCoarsen coarser)
383: {
384: PetscBool flag;
385: char type[256];
386: const char *def;
388: PetscObjectOptionsBegin((PetscObject)coarser);
389: if (!((PetscObject)coarser)->type_name) {
390: def = MATCOARSENMISK;
391: } else {
392: def = ((PetscObject)coarser)->type_name;
393: }
395: PetscOptionsFList("-mat_coarsen_type", "Type of aggregator", "MatCoarsenSetType", MatCoarsenList, def, type, 256, &flag);
396: if (flag) MatCoarsenSetType(coarser, type);
397: /*
398: Set the type if it was never set.
399: */
400: if (!((PetscObject)coarser)->type_name) MatCoarsenSetType(coarser, def);
402: PetscTryTypeMethod(coarser, setfromoptions, PetscOptionsObject);
403: PetscOptionsEnd();
405: return 0;
406: }