Actual source code: matcoloring.c
petsc-dev 2014-02-02
1: #include <petsc-private/matimpl.h> /*I "petscmat.h" I*/
3: PetscFunctionList MatColoringList = 0;
4: PetscBool MatColoringRegisterAllCalled = PETSC_FALSE;
6: PETSC_EXTERN PetscErrorCode MatColoringTestValid(MatColoring,ISColoring);
10: /*@C
11: MatColoringRegister - Adds a new sparse matrix coloring to the matrix package.
13: Not Collective
15: Input Parameters:
16: + sname - name of Coloring (for example MATCOLORINGSL)
17: - function - function pointer that creates the coloring
19: Level: developer
21: Sample usage:
22: .vb
23: MatColoringRegister("my_color",MyColor);
24: .ve
26: Then, your partitioner can be chosen with the procedural interface via
27: $ MatColoringSetType(part,"my_color")
28: or at runtime via the option
29: $ -mat_coloring_type my_color
31: .keywords: matrix, Coloring, register
33: .seealso: MatColoringRegisterDestroy(), MatColoringRegisterAll()
34: @*/
35: PetscErrorCode MatColoringRegister(const char sname[],PetscErrorCode (*function)(MatColoring))
36: {
40: PetscFunctionListAdd(&MatColoringList,sname,function);
41: return(0);
42: }
46: /*@C
47: MatColoringCreate - Creates a matrix coloring context.
49: Collective on MatColoring
51: Input Parameters:
52: . comm - MPI communicator
54: Output Parameter:
55: . mcptr - the new MatColoring context
57: Options Database Keys:
58: + -mat_coloring_type - the type of coloring algorithm used
59: . -mat_coloring_maxcolors - the maximum number of relevant colors, all nodes not in a color are in maxcolors+1
60: . -mat_coloring_distance - compute a distance 1,2,... coloring.
61: . -mat_coloring_view - print information about the coloring and the produced index sets
62: - -mat_coloring_valid - debugging option that prints all coloring incompatibilities
64: Level: beginner
66: .keywords: Coloring, Matrix
68: .seealso: MatColoring, MatColoringApply()
69: @*/
70: PetscErrorCode MatColoringCreate(Mat m,MatColoring *mcptr)
71: {
72: MatColoring mc;
76: *mcptr = 0;
78: #if !defined(PETSC_USE_DYNAMIC_LIBRARIES)
79: MatInitializePackage();
80: #endif
81: PetscHeaderCreate(mc,_p_MatColoring, struct _MatColoringOps, MAT_COLORING_CLASSID,"MatColoring","Matrix coloring",
82: "MatColoring",PetscObjectComm((PetscObject)m),MatColoringDestroy, MatColoringView);
83: PetscObjectReference((PetscObject)m);
84: mc->mat = m;
85: mc->dist = 2; /* default to Jacobian computation case */
86: mc->maxcolors = 0; /* no maximum */
87: *mcptr = mc;
88: mc->valid = PETSC_FALSE;
89: return(0);
90: }
95: /*@C
96: MatColoringDestroy - Destroys the matrix coloring context
98: Collective on MatColoring
100: Input Parameter:
101: . mc - the MatColoring context
103: Level: beginner
105: .keywords: Coloring, destroy
107: .seealso: MatColoringCreate(), MatColoringApply()
108: @*/
109: PetscErrorCode MatColoringDestroy(MatColoring *mc)
110: {
114: if (--((PetscObject)(*mc))->refct > 0) {*mc = 0; return(0);}
115: MatDestroy(&(*mc)->mat);
116: if ((*mc)->ops->destroy) {(*((*mc)->ops->destroy))(*mc);}
117: PetscHeaderDestroy(mc);
118: return(0);
119: }
123: /*@C
124: MatColoringSetType - Sets the type of coloring algorithm used
126: Collective on MatColoring
128: Input Parameter:
129: + mc - the MatColoring context
130: - type - the type of coloring
132: Level: beginner
134: Notes: Possible types include the sequential types MATCOLORINGLF,
135: MATCOLORINGSL, and MATCOLORINGID from the MINPACK package as well
136: as a parallel MATCOLORINGMIS algorithm.
138: .keywords: Coloring, type
140: .seealso: MatColoringCreate(), MatColoringApply()
141: @*/
142: PetscErrorCode MatColoringSetType(MatColoring mc,MatColoringType type)
143: {
144: PetscBool match;
145: PetscErrorCode ierr,(*r)(MatColoring);
150: PetscObjectTypeCompare((PetscObject)mc,type,&match);
151: if (match) return(0);
152: PetscFunctionListFind(MatColoringList,type,&r);
153: if (!r) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested MatColoring type %s",type);
154: if (mc->ops->destroy) {
155: (*(mc)->ops->destroy)(mc);
156: mc->ops->destroy = NULL;
157: }
158: mc->ops->apply = 0;
159: mc->ops->view = 0;
160: mc->ops->setfromoptions = 0;
161: mc->ops->destroy = 0;
163: PetscObjectChangeTypeName((PetscObject)mc,type);
164: (*r)(mc);
165: return(0);
166: }
170: /*@
171: MatColoringSetFromOptions - Sets MatColoring options from user parameters
173: Collective on MatColoring
175: Input Parameters:
176: . mc - MatColoring context
178: Options Database Keys:
179: + -mat_coloring_type - the type of coloring algorithm used
180: . -mat_coloring_maxcolors - the maximum number of relevant colors, all nodes not in a color are in maxcolors+1
181: . -mat_coloring_distance - compute a distance 1,2,... coloring.
182: . -mat_coloring_view - print information about the coloring and the produced index sets
184: Level: beginner
186: .keywords: Coloring, Matrix
188: .seealso: MatColoring, MatColoringApply()
189: @*/
190: PetscErrorCode MatColoringSetFromOptions(MatColoring mc)
191: {
192: PetscBool flg;
193: MatColoringType deft = MATCOLORINGSL;
194: char type[256];
196: PetscInt dist,maxcolors;
201: MatColoringGetDistance(mc,&dist);
202: MatColoringGetMaxColors(mc,&maxcolors);
203: if (!MatColoringRegisterAllCalled) {MatColoringRegisterAll();}
204: PetscObjectOptionsBegin((PetscObject)mc);
205: if (((PetscObject)mc)->type_name) deft = ((PetscObject)mc)->type_name;
206: PetscOptionsFList("-mat_coloring_type","The coloring method used","MatColoringSetType",MatColoringList,deft,type,256,&flg);
207: if (flg) {
208: MatColoringSetType(mc,type);
209: } else if (!((PetscObject)mc)->type_name) {
210: MatColoringSetType(mc,deft);
211: }
212: PetscOptionsInt("-mat_coloring_distance","Distance of the coloring","MatColoringSetDistance",dist,&dist,&flg);
213: if (flg) {MatColoringSetDistance(mc,dist);}
214: PetscOptionsInt("-mat_coloring_maxcolors","Maximum colors returned at the end. 1 returns an independent set","MatColoringSetMaxColors",maxcolors,&maxcolors,&flg);
215: if (flg) {MatColoringSetMaxColors(mc,maxcolors);}
216: if (mc->ops->setfromoptions) {
217: (*mc->ops->setfromoptions)(mc);
218: }
219: PetscOptionsBool("-mat_coloring_valid","Check that a valid coloring has been produced","",mc->valid,&mc->valid,NULL);
220: PetscObjectProcessOptionsHandlers((PetscObject)mc);
221: PetscOptionsEnd();
222: return(0);
223: }
227: /*@
228: MatColoringSetDistance - Sets the distance of the coloring
230: Logically Collective on MatColoring
232: Input Parameter:
233: . mc - the MatColoring context
234: . dist - the distance the coloring should compute
236: Level: beginner
238: Notes: The distance of the coloring denotes the minimum number
239: of edges in the graph induced by the matrix any two vertices
240: of the same color are. Distance-1 colorings are the classical
241: coloring, where no two vertices of the same color are adjacent.
242: distance-2 colorings are useful for the computation of Jacobians.
244: .keywords: Coloring, distance, Jacobian
246: .seealso: MatColoringGetDistance(), MatColoringApply()
247: @*/
248: PetscErrorCode MatColoringSetDistance(MatColoring mc,PetscInt dist)
249: {
252: mc->dist = dist;
253: return(0);
254: }
258: /*@
259: MatColoringGetDistance - Gets the distance of the coloring
261: Logically Collective on MatColoring
263: Input Parameter:
264: . mc - the MatColoring context
266: Output Paramter:
267: . dist - the current distance being used for the coloring.
269: Level: beginner
271: .keywords: Coloring, distance
273: .seealso: MatColoringSetDistance(), MatColoringApply()
274: @*/
275: PetscErrorCode MatColoringGetDistance(MatColoring mc,PetscInt *dist)
276: {
279: if (dist) *dist = mc->dist;
280: return(0);
281: }
285: /*@
286: MatColoringSetMaxColors - Sets the maximum number of colors
288: Logically Collective on MatColoring
290: Input Parameter:
291: + mc - the MatColoring context
292: - maxcolors - the maximum number of colors to produce
294: Level: beginner
296: Notes: This may be used to compute a certain number of
297: independent sets from the graph. For instance, while using
298: MATCOLORINGMIS and maxcolors = 1, one gets out an MIS. Vertices
299: not in a color are set to have color maxcolors+1, which is not
300: a valid color as they may be adjacent.
302: .keywords: Coloring
304: .seealso: MatColoringGetMaxColors(), MatColoringApply()
305: @*/
306: PetscErrorCode MatColoringSetMaxColors(MatColoring mc,PetscInt maxcolors)
307: {
310: mc->maxcolors = maxcolors;
311: return(0);
312: }
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: }
343: /*@
344: MatColoringApply - Apply the coloring to the matrix, producing index
345: sets corresponding to a number of independent sets in the induced
346: graph.
348: Collective on MatColoring
350: Input Parameters:
351: . mc - the MatColoring context
353: Output Parameter:
354: . coloring - the ISColoring instance containing the coloring
356: Level: beginner
358: .keywords: Coloring, Apply
360: .seealso: MatColoring, MatColoringCreate()
361: @*/
362: PetscErrorCode MatColoringApply(MatColoring mc,ISColoring *coloring)
363: {
364: PetscErrorCode ierr;
365: PetscBool flg;
366: PetscViewerFormat format;
367: PetscViewer viewer;
368: PetscInt nc,ncolors;
372: PetscLogEventBegin(Mat_Coloring_Apply,mc,0,0,0);
373: (*mc->ops->apply)(mc,coloring);
374: PetscLogEventEnd(Mat_Coloring_Apply,mc,0,0,0);
375: /* valid */
376: if (mc->valid) {
377: MatColoringTestValid(mc,*coloring);
378: }
379: /* view */
380: PetscOptionsGetViewer(PetscObjectComm((PetscObject)mc),((PetscObject)mc)->prefix,"-mat_coloring_view",&viewer,&format,&flg);
381: if (flg && !PetscPreLoadingOn) {
382: PetscViewerPushFormat(viewer,format);
383: MatColoringView(mc,viewer);
384: MatGetSize(mc->mat,NULL,&nc);
385: ISColoringGetIS(*coloring,&ncolors,NULL);
386: PetscPrintf(PetscObjectComm((PetscObject)mc)," Number of colors %d\n",ncolors);
387: PetscPrintf(PetscObjectComm((PetscObject)mc)," Number of total columns %d\n",nc);
388: if (nc <= 1000) {ISColoringView(*coloring,viewer);}
389: PetscViewerPopFormat(viewer);
390: PetscViewerDestroy(&viewer);
391: }
392: return(0);
393: }
397: /*@
398: MatColoringView - Output details about the MatColoring.
400: Collective on MatColoring
402: Input Parameters:
403: - mc - the MatColoring context
404: + viewer - the Viewer context
406: Level: beginner
408: .keywords: Coloring, view
410: .seealso: MatColoring, MatColoringApply()
411: @*/
412: PetscErrorCode MatColoringView(MatColoring mc,PetscViewer viewer)
413: {
415: PetscBool iascii;
419: if (!viewer) {
420: PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)mc),&viewer);
421: }
425: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
426: if (iascii) {
427: PetscObjectPrintClassNamePrefixType((PetscObject)mc,viewer);
428: if (mc->maxcolors > 0) {
429: PetscViewerASCIIPrintf(viewer," Distance %d, Max. Colors %d\n",mc->dist,mc->maxcolors);
430: } else {
431: PetscViewerASCIIPrintf(viewer," Distance %d\n",mc->dist);
432: }
433: }
434: return(0);
435: }