Actual source code: matcoloring.c
petsc-3.10.0 2018-09-12
1: #include <petsc/private/matimpl.h>
3: PetscFunctionList MatColoringList = 0;
4: PetscBool MatColoringRegisterAllCalled = PETSC_FALSE;
5: const char *const MatColoringWeightTypes[] = {"RANDOM","LEXICAL","LF","SL","MatColoringWeightType","MAT_COLORING_WEIGHT_",0};
7: /*@C
8: MatColoringRegister - Adds a new sparse matrix coloring to the matrix package.
10: Not Collective
12: Input Parameters:
13: + sname - name of Coloring (for example MATCOLORINGSL)
14: - function - function pointer that creates the coloring
16: Level: developer
18: Sample usage:
19: .vb
20: MatColoringRegister("my_color",MyColor);
21: .ve
23: Then, your partitioner can be chosen with the procedural interface via
24: $ MatColoringSetType(part,"my_color")
25: or at runtime via the option
26: $ -mat_coloring_type my_color
28: .keywords: matrix, Coloring, register
30: .seealso: MatColoringRegisterDestroy(), MatColoringRegisterAll()
31: @*/
32: PetscErrorCode MatColoringRegister(const char sname[],PetscErrorCode (*function)(MatColoring))
33: {
37: PetscFunctionListAdd(&MatColoringList,sname,function);
38: return(0);
39: }
41: /*@
42: MatColoringCreate - Creates a matrix coloring context.
44: Collective on MatColoring
46: Input Parameters:
47: . comm - MPI communicator
49: Output Parameter:
50: . mcptr - the new MatColoring context
52: Options Database Keys:
53: + -mat_coloring_type - the type of coloring algorithm used
54: . -mat_coloring_maxcolors - the maximum number of relevant colors, all nodes not in a color are in maxcolors+1
55: . -mat_coloring_distance - compute a distance 1,2,... coloring.
56: . -mat_coloring_view - print information about the coloring and the produced index sets
57: . -mat_coloring_test - debugging option that prints all coloring incompatibilities
58: - -mat_is_coloring_test - debugging option that throws an error if MatColoringApply() generates an incorrect iscoloring
60: Level: beginner
62: Notes:
63: A distance one coloring is useful, for example, multi-color SOR. A distance two coloring is for the finite difference computation of Jacobians
64: (see MatFDColoringCreate()).
66: Some coloring types only support distance two colorings
68: .keywords: Coloring, Matrix
70: .seealso: MatColoring, MatColoringApply(), MatFDColoringCreate()
71: @*/
72: PetscErrorCode MatColoringCreate(Mat m,MatColoring *mcptr)
73: {
74: MatColoring mc;
80: *mcptr = NULL;
82: #if !defined(PETSC_USE_DYNAMIC_LIBRARIES)
83: MatInitializePackage();
84: #endif
85: PetscHeaderCreate(mc, MAT_COLORING_CLASSID,"MatColoring","Matrix coloring", "MatColoring",PetscObjectComm((PetscObject)m),MatColoringDestroy, MatColoringView);
86: PetscObjectReference((PetscObject)m);
87: mc->mat = m;
88: mc->dist = 2; /* default to Jacobian computation case */
89: mc->maxcolors = IS_COLORING_MAX;
90: *mcptr = mc;
91: mc->valid = PETSC_FALSE;
92: mc->weight_type = MAT_COLORING_WEIGHT_RANDOM;
93: mc->user_weights = NULL;
94: mc->user_lperm = NULL;
95: return(0);
96: }
99: /*@
100: MatColoringDestroy - Destroys the matrix coloring context
102: Collective on MatColoring
104: Input Parameter:
105: . mc - the MatColoring context
107: Level: beginner
109: .keywords: Coloring, destroy
111: .seealso: MatColoringCreate(), MatColoringApply()
112: @*/
113: PetscErrorCode MatColoringDestroy(MatColoring *mc)
114: {
118: if (--((PetscObject)(*mc))->refct > 0) {*mc = 0; return(0);}
119: MatDestroy(&(*mc)->mat);
120: if ((*mc)->ops->destroy) {(*((*mc)->ops->destroy))(*mc);}
121: if ((*mc)->user_weights) {PetscFree((*mc)->user_weights);}
122: if ((*mc)->user_lperm) {PetscFree((*mc)->user_lperm);}
123: PetscHeaderDestroy(mc);
124: return(0);
125: }
127: /*@C
128: MatColoringSetType - Sets the type of coloring algorithm used
130: Collective on MatColoring
132: Input Parameter:
133: + mc - the MatColoring context
134: - type - the type of coloring
136: Level: beginner
138: Notes:
139: Possible types include the sequential types MATCOLORINGLF,
140: MATCOLORINGSL, and MATCOLORINGID from the MINPACK package as well
141: as a parallel MATCOLORINGMIS algorithm.
143: .keywords: Coloring, type
145: .seealso: MatColoringCreate(), MatColoringApply()
146: @*/
147: PetscErrorCode MatColoringSetType(MatColoring mc,MatColoringType type)
148: {
149: PetscBool match;
150: PetscErrorCode ierr,(*r)(MatColoring);
155: PetscObjectTypeCompare((PetscObject)mc,type,&match);
156: if (match) return(0);
157: PetscFunctionListFind(MatColoringList,type,&r);
158: if (!r) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested MatColoring type %s",type);
159: if (mc->ops->destroy) {
160: (*(mc)->ops->destroy)(mc);
161: mc->ops->destroy = NULL;
162: }
163: mc->ops->apply = 0;
164: mc->ops->view = 0;
165: mc->ops->setfromoptions = 0;
166: mc->ops->destroy = 0;
168: PetscObjectChangeTypeName((PetscObject)mc,type);
169: (*r)(mc);
170: return(0);
171: }
173: /*@
174: MatColoringSetFromOptions - Sets MatColoring options from user parameters
176: Collective on MatColoring
178: Input Parameters:
179: . mc - MatColoring context
181: Options Database Keys:
182: + -mat_coloring_type - the type of coloring algorithm used
183: . -mat_coloring_maxcolors - the maximum number of relevant colors, all nodes not in a color are in maxcolors+1
184: . -mat_coloring_distance - compute a distance 1,2,... coloring.
185: . -mat_coloring_view - print information about the coloring and the produced index sets
187: Level: beginner
189: .keywords: Coloring, Matrix
191: .seealso: MatColoring, MatColoringApply()
192: @*/
193: PetscErrorCode MatColoringSetFromOptions(MatColoring mc)
194: {
195: PetscBool flg;
196: MatColoringType deft = MATCOLORINGSL;
197: char type[256];
199: PetscInt dist,maxcolors;
203: MatColoringGetDistance(mc,&dist);
204: if (dist == 2) deft = MATCOLORINGSL;
205: else deft = MATCOLORINGGREEDY;
206: MatColoringGetMaxColors(mc,&maxcolors);
207: MatColoringRegisterAll();
208: PetscObjectOptionsBegin((PetscObject)mc);
209: if (((PetscObject)mc)->type_name) deft = ((PetscObject)mc)->type_name;
210: PetscOptionsFList("-mat_coloring_type","The coloring method used","MatColoringSetType",MatColoringList,deft,type,256,&flg);
211: if (flg) {
212: MatColoringSetType(mc,type);
213: } else if (!((PetscObject)mc)->type_name) {
214: MatColoringSetType(mc,deft);
215: }
216: PetscOptionsInt("-mat_coloring_distance","Distance of the coloring","MatColoringSetDistance",dist,&dist,&flg);
217: if (flg) {MatColoringSetDistance(mc,dist);}
218: PetscOptionsInt("-mat_coloring_maxcolors","Maximum colors returned at the end. 1 returns an independent set","MatColoringSetMaxColors",maxcolors,&maxcolors,&flg);
219: if (flg) {MatColoringSetMaxColors(mc,maxcolors);}
220: if (mc->ops->setfromoptions) {
221: (*mc->ops->setfromoptions)(PetscOptionsObject,mc);
222: }
223: PetscOptionsBool("-mat_coloring_test","Check that a valid coloring has been produced","",mc->valid,&mc->valid,NULL);
224: PetscOptionsBool("-mat_is_coloring_test","Check that a valid iscoloring has been produced","",mc->valid_iscoloring,&mc->valid_iscoloring,NULL);
225: PetscOptionsEnum("-mat_coloring_weight_type","Sets the type of vertex weighting used","MatColoringSetWeightType",MatColoringWeightTypes,(PetscEnum)mc->weight_type,(PetscEnum*)&mc->weight_type,NULL);
226: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)mc);
227: PetscOptionsEnd();
228: return(0);
229: }
231: /*@
232: MatColoringSetDistance - Sets the distance of the coloring
234: Logically Collective on MatColoring
236: Input Parameter:
237: . mc - the MatColoring context
238: . dist - the distance the coloring should compute
240: Level: beginner
242: Notes:
243: The distance of the coloring denotes the minimum number
244: of edges in the graph induced by the matrix any two vertices
245: of the same color are. Distance-1 colorings are the classical
246: coloring, where no two vertices of the same color are adjacent.
247: distance-2 colorings are useful for the computation of Jacobians.
249: .keywords: Coloring, distance, Jacobian
251: .seealso: MatColoringGetDistance(), MatColoringApply()
252: @*/
253: PetscErrorCode MatColoringSetDistance(MatColoring mc,PetscInt dist)
254: {
257: mc->dist = dist;
258: return(0);
259: }
261: /*@
262: MatColoringGetDistance - Gets the distance of the coloring
264: Logically Collective on MatColoring
266: Input Parameter:
267: . mc - the MatColoring context
269: Output Paramter:
270: . dist - the current distance being used for the coloring.
272: Level: beginner
274: .keywords: Coloring, distance
276: .seealso: MatColoringSetDistance(), MatColoringApply()
277: @*/
278: PetscErrorCode MatColoringGetDistance(MatColoring mc,PetscInt *dist)
279: {
282: if (dist) *dist = mc->dist;
283: return(0);
284: }
286: /*@
287: MatColoringSetMaxColors - Sets the maximum number of colors
289: Logically Collective on MatColoring
291: Input Parameter:
292: + mc - the MatColoring context
293: - maxcolors - the maximum number of colors to produce
295: Level: beginner
297: Notes:
298: This may be used to compute a certain number of
299: independent sets from the graph. For instance, while using
300: MATCOLORINGMIS and maxcolors = 1, one gets out an MIS. Vertices
301: not in a color are set to have color maxcolors+1, which is not
302: a valid color as they may be adjacent.
304: .keywords: Coloring
306: .seealso: MatColoringGetMaxColors(), MatColoringApply()
307: @*/
308: PetscErrorCode MatColoringSetMaxColors(MatColoring mc,PetscInt maxcolors)
309: {
312: mc->maxcolors = maxcolors;
313: return(0);
314: }
316: /*@
317: MatColoringGetMaxColors - Gets the maximum number of colors
319: Logically Collective on MatColoring
321: Input Parameter:
322: . mc - the MatColoring context
324: Output Paramter:
325: . maxcolors - the current maximum number of colors to produce
327: Level: beginner
329: .keywords: Coloring
331: .seealso: MatColoringSetMaxColors(), MatColoringApply()
332: @*/
333: PetscErrorCode MatColoringGetMaxColors(MatColoring mc,PetscInt *maxcolors)
334: {
337: if (maxcolors) *maxcolors = mc->maxcolors;
338: return(0);
339: }
341: /*@
342: MatColoringApply - Apply the coloring to the matrix, producing index
343: sets corresponding to a number of independent sets in the induced
344: graph.
346: Collective on MatColoring
348: Input Parameters:
349: . mc - the MatColoring context
351: Output Parameter:
352: . coloring - the ISColoring instance containing the coloring
354: Level: beginner
356: .keywords: Coloring, Apply
358: .seealso: MatColoring, MatColoringCreate()
359: @*/
360: PetscErrorCode MatColoringApply(MatColoring mc,ISColoring *coloring)
361: {
362: PetscErrorCode ierr;
363: PetscBool flg;
364: PetscViewerFormat format;
365: PetscViewer viewer;
366: PetscInt nc,ncolors;
370: PetscLogEventBegin(MATCOLORING_Apply,mc,0,0,0);
371: (*mc->ops->apply)(mc,coloring);
372: PetscLogEventEnd(MATCOLORING_Apply,mc,0,0,0);
374: /* valid */
375: if (mc->valid) {
376: MatColoringTest(mc,*coloring);
377: }
378: if (mc->valid_iscoloring) {
379: MatISColoringTest(mc->mat,*coloring);
380: }
382: /* view */
383: PetscOptionsGetViewer(PetscObjectComm((PetscObject)mc),((PetscObject)mc)->prefix,"-mat_coloring_view",&viewer,&format,&flg);
384: if (flg && !PetscPreLoadingOn) {
385: PetscViewerPushFormat(viewer,format);
386: MatColoringView(mc,viewer);
387: MatGetSize(mc->mat,NULL,&nc);
388: ISColoringGetIS(*coloring,&ncolors,NULL);
389: PetscViewerASCIIPrintf(viewer," Number of colors %d\n",ncolors);
390: PetscViewerASCIIPrintf(viewer," Number of total columns %d\n",nc);
391: if (nc <= 1000) {ISColoringView(*coloring,viewer);}
392: PetscViewerPopFormat(viewer);
393: PetscViewerDestroy(&viewer);
394: }
395: return(0);
396: }
398: /*@
399: MatColoringView - Output details about the MatColoring.
401: Collective on MatColoring
403: Input Parameters:
404: - mc - the MatColoring context
405: + viewer - the Viewer context
407: Level: beginner
409: .keywords: Coloring, view
411: .seealso: MatColoring, MatColoringApply()
412: @*/
413: PetscErrorCode MatColoringView(MatColoring mc,PetscViewer viewer)
414: {
416: PetscBool iascii;
420: if (!viewer) {
421: PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)mc),&viewer);
422: }
426: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
427: if (iascii) {
428: PetscObjectPrintClassNamePrefixType((PetscObject)mc,viewer);
429: PetscViewerASCIIPrintf(viewer," Weight type: %s\n",MatColoringWeightTypes[mc->weight_type]);
430: if (mc->maxcolors > 0) {
431: PetscViewerASCIIPrintf(viewer," Distance %D, Max. Colors %D\n",mc->dist,mc->maxcolors);
432: } else {
433: PetscViewerASCIIPrintf(viewer," Distance %d\n",mc->dist);
434: }
435: }
436: return(0);
437: }
439: /*@
440: MatColoringSetWeightType - Set the type of weight computation used.
442: Logically collective on MatColoring
444: Input Parameters:
445: - mc - the MatColoring context
446: + wt - the weight type
448: Level: beginner
450: .keywords: Coloring, view
452: .seealso: MatColoring, MatColoringWeightType
453: @*/
454: PetscErrorCode MatColoringSetWeightType(MatColoring mc,MatColoringWeightType wt)
455: {
457: mc->weight_type = wt;
458: return(0);
460: }