Actual source code: coarsen.c
petsc-3.10.5 2019-03-28
Report Typos and Errors

      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: }