Actual source code: pmap.c

      1: /*
      2:    This file contains routines for basic map object implementation.
      3: */

      5: #include <petsc/private/isimpl.h>

      7: /*@
      8:   PetscLayoutCreate - Allocates `PetscLayout` object

     10:   Collective

     12:   Input Parameter:
     13: . comm - the MPI communicator

     15:   Output Parameter:
     16: . map - the new `PetscLayout`

     18:   Level: advanced

     20:   Notes:
     21:   Typical calling sequence
     22: .vb
     23:        PetscLayoutCreate(MPI_Comm,PetscLayout *);
     24:        PetscLayoutSetBlockSize(PetscLayout,bs);
     25:        PetscLayoutSetSize(PetscLayout,N); // or PetscLayoutSetLocalSize(PetscLayout,n);
     26:        PetscLayoutSetUp(PetscLayout);
     27: .ve
     28:   Alternatively,
     29: .vb
     30:       PetscLayoutCreateFromSizes(comm,n,N,bs,&layout);
     31: .ve

     33:   Optionally use any of the following
     34: .vb
     35:   PetscLayoutGetSize(PetscLayout,PetscInt *);
     36:   PetscLayoutGetLocalSize(PetscLayout,PetscInt *);
     37:   PetscLayoutGetRange(PetscLayout,PetscInt *rstart,PetscInt *rend);
     38:   PetscLayoutGetRanges(PetscLayout,const PetscInt *range[]);
     39:   PetscLayoutDestroy(PetscLayout*);
     40: .ve

     42:   The `PetscLayout` object and methods are intended to be used in the PETSc `Vec` and `Mat` implementations; it is often not needed in
     43:   user codes unless you really gain something in their use.

     45: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutSetLocalSize()`, `PetscLayoutSetSize()`, `PetscLayoutGetSize()`, `PetscLayoutGetLocalSize()`,
     46:           `PetscLayout`, `PetscLayoutDestroy()`,
     47:           `PetscLayoutGetRange()`, `PetscLayoutGetRanges()`, `PetscLayoutSetBlockSize()`, `PetscLayoutGetBlockSize()`, `PetscLayoutSetUp()`,
     48:           `PetscLayoutCreateFromSizes()`
     49: @*/
     50: PetscErrorCode PetscLayoutCreate(MPI_Comm comm, PetscLayout *map)
     51: {
     52:   PetscFunctionBegin;
     53:   PetscCall(PetscNew(map));
     54:   PetscCallMPI(MPI_Comm_size(comm, &(*map)->size));
     55:   (*map)->comm        = comm;
     56:   (*map)->bs          = 1;
     57:   (*map)->n           = -1;
     58:   (*map)->N           = -1;
     59:   (*map)->range       = NULL;
     60:   (*map)->range_alloc = PETSC_TRUE;
     61:   (*map)->rstart      = 0;
     62:   (*map)->rend        = 0;
     63:   (*map)->setupcalled = PETSC_FALSE;
     64:   (*map)->oldn        = -1;
     65:   (*map)->oldN        = -1;
     66:   (*map)->oldbs       = -1;
     67:   PetscFunctionReturn(PETSC_SUCCESS);
     68: }

     70: /*@
     71:   PetscLayoutCreateFromSizes - Allocates `PetscLayout` object and sets the layout sizes, and sets the layout up.

     73:   Collective

     75:   Input Parameters:
     76: + comm - the MPI communicator
     77: . n    - the local size (or `PETSC_DECIDE`)
     78: . N    - the global size (or `PETSC_DECIDE`)
     79: - bs   - the block size (or `PETSC_DECIDE`)

     81:   Output Parameter:
     82: . map - the new `PetscLayout`

     84:   Level: advanced

     86:   Note:
     87: .vb
     88:   PetscLayoutCreateFromSizes(comm, n, N, bs, &layout);
     89: .ve
     90:   is a shorthand for
     91: .vb
     92:   PetscLayoutCreate(comm, &layout);
     93:   PetscLayoutSetLocalSize(layout, n);
     94:   PetscLayoutSetSize(layout, N);
     95:   PetscLayoutSetBlockSize(layout, bs);
     96:   PetscLayoutSetUp(layout);
     97: .ve

     99: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutSetLocalSize()`, `PetscLayoutSetSize()`, `PetscLayoutGetSize()`, `PetscLayoutGetLocalSize()`, `PetscLayout`, `PetscLayoutDestroy()`,
    100:           `PetscLayoutGetRange()`, `PetscLayoutGetRanges()`, `PetscLayoutSetBlockSize()`, `PetscLayoutGetBlockSize()`, `PetscLayoutSetUp()`, `PetscLayoutCreateFromRanges()`
    101: @*/
    102: PetscErrorCode PetscLayoutCreateFromSizes(MPI_Comm comm, PetscInt n, PetscInt N, PetscInt bs, PetscLayout *map)
    103: {
    104:   PetscFunctionBegin;
    105:   PetscCall(PetscLayoutCreate(comm, map));
    106:   PetscCall(PetscLayoutSetLocalSize(*map, n));
    107:   PetscCall(PetscLayoutSetSize(*map, N));
    108:   PetscCall(PetscLayoutSetBlockSize(*map, bs));
    109:   PetscCall(PetscLayoutSetUp(*map));
    110:   PetscFunctionReturn(PETSC_SUCCESS);
    111: }

    113: /*@
    114:   PetscLayoutDestroy - Frees a `PetscLayout` object and frees its range if that exists.

    116:   Collective

    118:   Input Parameter:
    119: . map - the `PetscLayout`

    121:   Level: developer

    123: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutSetLocalSize()`, `PetscLayoutSetSize()`, `PetscLayoutGetSize()`, `PetscLayoutGetLocalSize()`,
    124:           `PetscLayout`, `PetscLayoutCreate()`,
    125:           `PetscLayoutGetRange()`, `PetscLayoutGetRanges()`, `PetscLayoutSetBlockSize()`, `PetscLayoutGetBlockSize()`, `PetscLayoutSetUp()`
    126: @*/
    127: PetscErrorCode PetscLayoutDestroy(PetscLayout *map)
    128: {
    129:   PetscFunctionBegin;
    130:   if (!*map) PetscFunctionReturn(PETSC_SUCCESS);
    131:   if (!(*map)->refcnt--) {
    132:     if ((*map)->range_alloc) PetscCall(PetscFree((*map)->range));
    133:     PetscCall(ISLocalToGlobalMappingDestroy(&(*map)->mapping));
    134:     PetscCall(PetscFree(*map));
    135:   }
    136:   *map = NULL;
    137:   PetscFunctionReturn(PETSC_SUCCESS);
    138: }

    140: /*@
    141:   PetscLayoutCreateFromRanges - Creates a new `PetscLayout` with the given ownership ranges and sets it up.

    143:   Collective

    145:   Input Parameters:
    146: + comm  - the MPI communicator
    147: . range - the array of ownership ranges for each rank with length commsize+1
    148: . mode  - the copy mode for range
    149: - bs    - the block size (or `PETSC_DECIDE`)

    151:   Output Parameter:
    152: . newmap - the new `PetscLayout`

    154:   Level: developer

    156: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutSetLocalSize()`, `PetscLayoutSetSize()`, `PetscLayoutGetSize()`,
    157:           `PetscLayoutGetLocalSize()`, `PetscLayout`, `PetscLayoutDestroy()`,
    158:           `PetscLayoutGetRange()`, `PetscLayoutGetRanges()`, `PetscLayoutSetBlockSize()`, `PetscLayoutGetBlockSize()`, `PetscLayoutSetUp()`, `PetscLayoutCreateFromSizes()`
    159: @*/
    160: PetscErrorCode PetscLayoutCreateFromRanges(MPI_Comm comm, const PetscInt range[], PetscCopyMode mode, PetscInt bs, PetscLayout *newmap)
    161: {
    162:   PetscLayout map;
    163:   PetscMPIInt rank;

    165:   PetscFunctionBegin;
    166:   PetscCallMPI(MPI_Comm_rank(comm, &rank));
    167:   PetscCall(PetscLayoutCreate(comm, &map));
    168:   PetscCall(PetscLayoutSetBlockSize(map, bs));
    169:   switch (mode) {
    170:   case PETSC_COPY_VALUES:
    171:     PetscCall(PetscMalloc1(map->size + 1, &map->range));
    172:     PetscCall(PetscArraycpy(map->range, range, map->size + 1));
    173:     break;
    174:   case PETSC_USE_POINTER:
    175:     map->range_alloc = PETSC_FALSE; /* fall through */
    176:   case PETSC_OWN_POINTER:
    177:     map->range = (PetscInt *)range;
    178:     break;
    179:   default:
    180:     SETERRQ(PETSC_COMM_SELF, PETSC_ERR_PLIB, "Received invalid PetscCopyMode somehow");
    181:   }
    182:   map->rstart = map->range[rank];
    183:   map->rend   = map->range[rank + 1];
    184:   map->n      = map->rend - map->rstart;
    185:   map->N      = map->range[map->size];
    186:   if (PetscDefined(USE_DEBUG)) { /* just check that n, N and bs are consistent */
    187:     PetscInt tmp;
    188:     PetscCallMPI(MPIU_Allreduce(&map->n, &tmp, 1, MPIU_INT, MPI_SUM, map->comm));
    189:     PetscCheck(tmp == map->N, PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "Sum of local lengths %" PetscInt_FMT " does not equal global length %" PetscInt_FMT ", my local length %" PetscInt_FMT ". The provided PetscLayout is wrong.", tmp, map->N, map->n);
    190:     PetscCheck(map->n % map->bs == 0, PETSC_COMM_SELF, PETSC_ERR_PLIB, "Local size %" PetscInt_FMT " must be divisible by blocksize %" PetscInt_FMT, map->n, map->bs);
    191:     PetscCheck(map->N % map->bs == 0, map->comm, PETSC_ERR_PLIB, "Global size %" PetscInt_FMT " must be divisible by blocksize %" PetscInt_FMT, map->N, map->bs);
    192:   }
    193:   /* lock the layout */
    194:   map->setupcalled = PETSC_TRUE;
    195:   map->oldn        = map->n;
    196:   map->oldN        = map->N;
    197:   map->oldbs       = map->bs;
    198:   *newmap          = map;
    199:   PetscFunctionReturn(PETSC_SUCCESS);
    200: }

    202: /*@
    203:   PetscLayoutSetUp - given a map where you have set either the global or local
    204:   size sets up the map so that it may be used.

    206:   Collective

    208:   Input Parameter:
    209: . map - pointer to the map

    211:   Level: developer

    213:   Notes:
    214:   Typical calling sequence
    215: .vb
    216:   PetscLayoutCreate(MPI_Comm,PetscLayout *);
    217:   PetscLayoutSetBlockSize(PetscLayout,1);
    218:   PetscLayoutSetSize(PetscLayout,n) or PetscLayoutSetLocalSize(PetscLayout,N); or both
    219:   PetscLayoutSetUp(PetscLayout);
    220:   PetscLayoutGetSize(PetscLayout,PetscInt *);
    221: .ve

    223:   If range exists, and local size is not set, everything gets computed from the range.

    225:   If the local size, global size are already set and range exists then this does nothing.

    227: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutSetLocalSize()`, `PetscLayoutSetSize()`, `PetscLayoutGetSize()`, `PetscLayoutGetLocalSize()`,
    228:           `PetscLayout`, `PetscLayoutDestroy()`,
    229:           `PetscLayoutGetRange()`, `PetscLayoutGetRanges()`, `PetscLayoutSetBlockSize()`, `PetscLayoutGetBlockSize()`, `PetscLayoutCreate()`, `PetscSplitOwnership()`
    230: @*/
    231: PetscErrorCode PetscLayoutSetUp(PetscLayout map)
    232: {
    233:   PetscMPIInt rank;
    234:   PetscInt    p;

    236:   PetscFunctionBegin;
    237:   PetscCheck(!map->setupcalled || !(map->n != map->oldn || map->N != map->oldN), map->comm, PETSC_ERR_ARG_WRONGSTATE, "Layout is already setup with (local=%" PetscInt_FMT ",global=%" PetscInt_FMT "), cannot call setup again with (local=%" PetscInt_FMT ",global=%" PetscInt_FMT ")",
    238:              map->oldn, map->oldN, map->n, map->N);
    239:   if (map->setupcalled) PetscFunctionReturn(PETSC_SUCCESS);

    241:   PetscCheck(map->n < 0 || map->n % map->bs == 0, PETSC_COMM_SELF, PETSC_ERR_PLIB, "Local size %" PetscInt_FMT " must be divisible by blocksize %" PetscInt_FMT, map->n, map->bs);
    242:   PetscCheck(map->N < 0 || map->N % map->bs == 0, map->comm, PETSC_ERR_PLIB, "Global size %" PetscInt_FMT " must be divisible by blocksize %" PetscInt_FMT, map->N, map->bs);

    244:   PetscCallMPI(MPI_Comm_rank(map->comm, &rank));
    245:   if (map->n > 0) map->n = map->n / map->bs;
    246:   if (map->N > 0) map->N = map->N / map->bs;
    247:   PetscCall(PetscSplitOwnership(map->comm, &map->n, &map->N));
    248:   map->n = map->n * map->bs;
    249:   map->N = map->N * map->bs;
    250:   if (!map->range) PetscCall(PetscMalloc1(map->size + 1, &map->range));
    251:   PetscCallMPI(MPI_Allgather(&map->n, 1, MPIU_INT, map->range + 1, 1, MPIU_INT, map->comm));

    253:   map->range[0] = 0;
    254:   for (p = 2; p <= map->size; p++) map->range[p] += map->range[p - 1];

    256:   map->rstart = map->range[rank];
    257:   map->rend   = map->range[rank + 1];

    259:   /* lock the layout */
    260:   map->setupcalled = PETSC_TRUE;
    261:   map->oldn        = map->n;
    262:   map->oldN        = map->N;
    263:   map->oldbs       = map->bs;
    264:   PetscFunctionReturn(PETSC_SUCCESS);
    265: }

    267: /*@
    268:   PetscLayoutDuplicate - creates a new `PetscLayout` with the same information as a given one. If the `PetscLayout` already exists it is destroyed first.

    270:   Collective

    272:   Input Parameter:
    273: . in - input `PetscLayout` to be duplicated

    275:   Output Parameter:
    276: . out - the copy

    278:   Level: developer

    280:   Note:
    281:   `PetscLayoutSetUp()` does not need to be called on the resulting `PetscLayout`

    283: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutDestroy()`, `PetscLayoutSetUp()`, `PetscLayoutReference()`
    284: @*/
    285: PetscErrorCode PetscLayoutDuplicate(PetscLayout in, PetscLayout *out)
    286: {
    287:   MPI_Comm comm = in->comm;

    289:   PetscFunctionBegin;
    290:   PetscCall(PetscLayoutDestroy(out));
    291:   PetscCall(PetscLayoutCreate(comm, out));
    292:   PetscCall(PetscMemcpy(*out, in, sizeof(struct _n_PetscLayout)));
    293:   if (in->range) {
    294:     PetscCall(PetscMalloc1((*out)->size + 1, &(*out)->range));
    295:     PetscCall(PetscArraycpy((*out)->range, in->range, (*out)->size + 1));
    296:   }
    297:   (*out)->refcnt = 0;
    298:   PetscFunctionReturn(PETSC_SUCCESS);
    299: }

    301: /*@
    302:   PetscLayoutReference - Causes a PETSc `Vec` or `Mat` to share a `PetscLayout` with one that already exists.

    304:   Collective

    306:   Input Parameter:
    307: . in - input `PetscLayout` to be copied

    309:   Output Parameter:
    310: . out - the reference location

    312:   Level: developer

    314:   Notes:
    315:   `PetscLayoutSetUp()` does not need to be called on the resulting `PetscLayout`

    317:   If the out location already contains a `PetscLayout` it is destroyed

    319: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutDestroy()`, `PetscLayoutSetUp()`, `PetscLayoutDuplicate()`
    320: @*/
    321: PetscErrorCode PetscLayoutReference(PetscLayout in, PetscLayout *out)
    322: {
    323:   PetscFunctionBegin;
    324:   in->refcnt++;
    325:   PetscCall(PetscLayoutDestroy(out));
    326:   *out = in;
    327:   PetscFunctionReturn(PETSC_SUCCESS);
    328: }

    330: /*@
    331:   PetscLayoutSetISLocalToGlobalMapping - sets a `ISLocalGlobalMapping` into a `PetscLayout`

    333:   Collective

    335:   Input Parameters:
    336: + in   - input `PetscLayout`
    337: - ltog - the local to global mapping

    339:   Level: developer

    341:   Notes:
    342:   `PetscLayoutSetUp()` does not need to be called on the resulting `PetscLayout`

    344:   If the `PetscLayout` already contains a `ISLocalGlobalMapping` it is destroyed

    346: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutDestroy()`, `PetscLayoutSetUp()`, `PetscLayoutDuplicate()`
    347: @*/
    348: PetscErrorCode PetscLayoutSetISLocalToGlobalMapping(PetscLayout in, ISLocalToGlobalMapping ltog)
    349: {
    350:   PetscFunctionBegin;
    351:   if (ltog) {
    352:     PetscInt bs;

    354:     PetscCall(ISLocalToGlobalMappingGetBlockSize(ltog, &bs));
    355:     PetscCheck(in->bs == 1 || bs == 1 || in->bs == bs, in->comm, PETSC_ERR_PLIB, "Blocksize of layout %" PetscInt_FMT " must match that of mapping %" PetscInt_FMT " (or the latter must be 1)", in->bs, bs);
    356:   }
    357:   PetscCall(PetscObjectReference((PetscObject)ltog));
    358:   PetscCall(ISLocalToGlobalMappingDestroy(&in->mapping));
    359:   in->mapping = ltog;
    360:   PetscFunctionReturn(PETSC_SUCCESS);
    361: }

    363: /*@
    364:   PetscLayoutSetLocalSize - Sets the local size for a `PetscLayout` object.

    366:   Collective

    368:   Input Parameters:
    369: + map - pointer to the map
    370: - n   - the local size, pass `PETSC_DECIDE` (the default) to have this value determined by the global size set with `PetscLayoutSetSize()`

    372:   Level: developer

    374: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutSetSize()`, `PetscLayoutGetSize()`, `PetscLayoutGetLocalSize()`, `PetscLayoutSetUp()`
    375:           `PetscLayoutGetRange()`, `PetscLayoutGetRanges()`, `PetscLayoutSetBlockSize()`, `PetscLayoutGetBlockSize()`
    376: @*/
    377: PetscErrorCode PetscLayoutSetLocalSize(PetscLayout map, PetscInt n)
    378: {
    379:   PetscFunctionBegin;
    380:   PetscCheck(n % map->bs == 0, map->comm, PETSC_ERR_ARG_INCOMP, "Local size %" PetscInt_FMT " not compatible with block size %" PetscInt_FMT, n, map->bs);
    381:   map->n = n;
    382:   PetscFunctionReturn(PETSC_SUCCESS);
    383: }

    385: /*@
    386:   PetscLayoutGetLocalSize - Gets the local size for a `PetscLayout` object.

    388:   Not Collective

    390:   Input Parameter:
    391: . map - pointer to the map

    393:   Output Parameter:
    394: . n - the local size

    396:   Level: developer

    398:   Note:
    399:   Call this after the call to `PetscLayoutSetUp()`

    401: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutSetSize()`, `PetscLayoutGetSize()`, `PetscLayoutSetUp()`
    402:           `PetscLayoutGetRange()`, `PetscLayoutGetRanges()`, `PetscLayoutSetBlockSize()`, `PetscLayoutGetBlockSize()`
    403: @*/
    404: PetscErrorCode PetscLayoutGetLocalSize(PetscLayout map, PetscInt *n)
    405: {
    406:   PetscFunctionBegin;
    407:   *n = map->n;
    408:   PetscFunctionReturn(PETSC_SUCCESS);
    409: }

    411: /*@
    412:   PetscLayoutSetSize - Sets the global size for a `PetscLayout` object.

    414:   Logically Collective

    416:   Input Parameters:
    417: + map - pointer to the map
    418: - n   - the global size, use `PETSC_DETERMINE` (the default) to have this value computed as the sum of the local sizes set with `PetscLayoutSetLocalSize()`

    420:   Level: developer

    422: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutSetLocalSize()`, `PetscLayoutGetLocalSize()`, `PetscLayoutGetSize()`, `PetscLayoutSetUp()`
    423:           `PetscLayoutGetRange()`, `PetscLayoutGetRanges()`, `PetscLayoutSetBlockSize()`, `PetscLayoutGetBlockSize()`
    424: @*/
    425: PetscErrorCode PetscLayoutSetSize(PetscLayout map, PetscInt n)
    426: {
    427:   PetscFunctionBegin;
    428:   map->N = n;
    429:   PetscFunctionReturn(PETSC_SUCCESS);
    430: }

    432: /*@
    433:   PetscLayoutGetSize - Gets the global size for a `PetscLayout` object.

    435:   Not Collective

    437:   Input Parameter:
    438: . map - pointer to the map

    440:   Output Parameter:
    441: . n - the global size

    443:   Level: developer

    445:   Note:
    446:   Call this after the call to `PetscLayoutSetUp()`

    448: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutSetLocalSize()`, `PetscLayoutGetLocalSize()`, `PetscLayoutSetSize()`, `PetscLayoutSetUp()`
    449:           `PetscLayoutGetRange()`, `PetscLayoutGetRanges()`, `PetscLayoutSetBlockSize()`, `PetscLayoutGetBlockSize()`
    450: @*/
    451: PetscErrorCode PetscLayoutGetSize(PetscLayout map, PetscInt *n)
    452: {
    453:   PetscFunctionBegin;
    454:   *n = map->N;
    455:   PetscFunctionReturn(PETSC_SUCCESS);
    456: }

    458: /*@
    459:   PetscLayoutSetBlockSize - Sets the block size for a `PetscLayout` object.

    461:   Logically Collective

    463:   Input Parameters:
    464: + map - pointer to the map
    465: - bs  - the size

    467:   Level: developer

    469: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutSetLocalSize()`, `PetscLayoutGetLocalSize()`, `PetscLayoutGetBlockSize()`,
    470:           `PetscLayoutGetRange()`, `PetscLayoutGetRanges()`, `PetscLayoutSetSize()`, `PetscLayoutGetSize()`, `PetscLayoutSetUp()`
    471: @*/
    472: PetscErrorCode PetscLayoutSetBlockSize(PetscLayout map, PetscInt bs)
    473: {
    474:   PetscFunctionBegin;
    475:   PetscCheck(bs > 0, PETSC_COMM_SELF, PETSC_ERR_ARG_INCOMP, "Block size %" PetscInt_FMT " must be positive", bs);
    476:   PetscCheck(map->n <= 0 || (map->n % bs) == 0, PETSC_COMM_SELF, PETSC_ERR_ARG_INCOMP, "Local size %" PetscInt_FMT " not compatible with block size %" PetscInt_FMT, map->n, bs);
    477:   if (map->mapping) {
    478:     PetscInt obs;

    480:     PetscCall(ISLocalToGlobalMappingGetBlockSize(map->mapping, &obs));
    481:     if (obs > 1) PetscCall(ISLocalToGlobalMappingSetBlockSize(map->mapping, bs));
    482:   }
    483:   map->bs = bs;
    484:   PetscFunctionReturn(PETSC_SUCCESS);
    485: }

    487: /*@
    488:   PetscLayoutGetBlockSize - Gets the block size for a `PetscLayout` object.

    490:   Not Collective

    492:   Input Parameter:
    493: . map - pointer to the map

    495:   Output Parameter:
    496: . bs - the size

    498:   Level: developer

    500:   Notes:
    501:   Call this after the call to `PetscLayoutSetUp()`

    503: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutSetLocalSize()`, `PetscLayoutGetLocalSize()`, `PetscLayoutSetSize()`, `PetscLayoutSetUp()`
    504:           `PetscLayoutGetRange()`, `PetscLayoutGetRanges()`, `PetscLayoutSetBlockSize()`, `PetscLayoutGetSize()`
    505: @*/
    506: PetscErrorCode PetscLayoutGetBlockSize(PetscLayout map, PetscInt *bs)
    507: {
    508:   PetscFunctionBegin;
    509:   *bs = map->bs;
    510:   PetscFunctionReturn(PETSC_SUCCESS);
    511: }

    513: /*@
    514:   PetscLayoutGetRange - gets the range of values owned by this process

    516:   Not Collective

    518:   Input Parameter:
    519: . map - pointer to the map

    521:   Output Parameters:
    522: + rstart - first index owned by this process
    523: - rend   - one more than the last index owned by this process

    525:   Level: developer

    527:   Note:
    528:   Call this after the call to `PetscLayoutSetUp()`

    530: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutSetLocalSize()`, `PetscLayoutGetLocalSize()`, `PetscLayoutSetSize()`,
    531:           `PetscLayoutGetSize()`, `PetscLayoutGetRanges()`, `PetscLayoutSetBlockSize()`, `PetscLayoutSetUp()`
    532: @*/
    533: PetscErrorCode PetscLayoutGetRange(PetscLayout map, PetscInt *rstart, PetscInt *rend)
    534: {
    535:   PetscFunctionBegin;
    536:   if (rstart) *rstart = map->rstart;
    537:   if (rend) *rend = map->rend;
    538:   PetscFunctionReturn(PETSC_SUCCESS);
    539: }

    541: /*@C
    542:   PetscLayoutGetRanges - gets the ranges of values owned by all processes

    544:   Not Collective

    546:   Input Parameter:
    547: . map - pointer to the map

    549:   Output Parameter:
    550: . range - start of each processors range of indices (the final entry is one more than the
    551:           last index on the last process). The length of the array is one more than the number of processes in the MPI
    552:           communicator owned by `map`

    554:   Level: developer

    556:   Note:
    557:   Call this after the call to `PetscLayoutSetUp()`

    559:   Fortran Notes:
    560: .vb
    561:   PetscInt, pointer :: range(:)
    562: .ve

    564:   Call `PetscLayoutRestoreRanges()` when no longer needed.

    566: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutSetLocalSize()`, `PetscLayoutGetLocalSize()`, `PetscLayoutSetSize()`,
    567:           `PetscLayoutGetSize()`, `PetscLayoutGetRange()`, `PetscLayoutSetBlockSize()`, `PetscLayoutSetUp()`
    568: @*/
    569: PetscErrorCode PetscLayoutGetRanges(PetscLayout map, const PetscInt *range[])
    570: {
    571:   PetscFunctionBegin;
    572:   *range = map->range;
    573:   PetscFunctionReturn(PETSC_SUCCESS);
    574: }

    576: /*@
    577:   PetscLayoutCompare - Compares two layouts

    579:   Not Collective

    581:   Input Parameters:
    582: + mapa - pointer to the first map
    583: - mapb - pointer to the second map

    585:   Output Parameter:
    586: . congruent - `PETSC_TRUE` if the two layouts are congruent, `PETSC_FALSE` otherwise

    588:   Level: beginner

    590: .seealso: [PetscLayout](sec_matlayout), `PetscLayoutCreate()`, `PetscLayoutSetLocalSize()`, `PetscLayoutGetLocalSize()`, `PetscLayoutGetBlockSize()`,
    591:           `PetscLayoutGetRange()`, `PetscLayoutGetRanges()`, `PetscLayoutSetSize()`, `PetscLayoutGetSize()`, `PetscLayoutSetUp()`
    592: @*/
    593: PetscErrorCode PetscLayoutCompare(PetscLayout mapa, PetscLayout mapb, PetscBool *congruent)
    594: {
    595:   PetscFunctionBegin;
    596:   *congruent = PETSC_FALSE;
    597:   if (mapa->N == mapb->N && mapa->range && mapb->range && mapa->size == mapb->size) PetscCall(PetscArraycmp(mapa->range, mapb->range, mapa->size + 1, congruent));
    598:   PetscFunctionReturn(PETSC_SUCCESS);
    599: }

    601: /*@
    602:   PetscLayoutFindOwner - Find the owning MPI process for a global index

    604:   Not Collective; No Fortran Support

    606:   Input Parameters:
    607: + map - the layout
    608: - idx - global index to find the owner of

    610:   Output Parameter:
    611: . owner - the owning rank

    613:   Level: developer

    615: .seealso: `PetscLayout`, `PetscLayoutFindOwnerIndex()`
    616: @*/
    617: PetscErrorCode PetscLayoutFindOwner(PetscLayout map, PetscInt idx, PetscMPIInt *owner)
    618: {
    619:   PetscMPIInt lo = 0, hi, t;

    621:   PetscFunctionBegin;
    622:   *owner = -1; /* GCC erroneously issues warning about possibly uninitialized use when error condition */
    623:   PetscAssert((map->n >= 0) && (map->N >= 0) && (map->range), PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE, "PetscLayoutSetUp() must be called first");
    624:   PetscAssert(idx >= 0 && idx <= map->N, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Index %" PetscInt_FMT " is out of range", idx);
    625:   hi = map->size;
    626:   while (hi - lo > 1) {
    627:     t = lo + (hi - lo) / 2;
    628:     if (idx < map->range[t]) hi = t;
    629:     else lo = t;
    630:   }
    631:   *owner = lo;
    632:   PetscFunctionReturn(PETSC_SUCCESS);
    633: }

    635: /*@
    636:   PetscLayoutFindOwnerIndex - Find the owning MPI process and the local index on that process for a global index

    638:   Not Collective; No Fortran Support

    640:   Input Parameters:
    641: + map - the layout
    642: - idx - global index to find the owner of

    644:   Output Parameters:
    645: + owner - the owning rank
    646: - lidx  - local index used by the owner for `idx`

    648:   Level: developer

    650: .seealso: `PetscLayout`, `PetscLayoutFindOwner()`
    651: @*/
    652: PetscErrorCode PetscLayoutFindOwnerIndex(PetscLayout map, PetscInt idx, PetscMPIInt *owner, PetscInt *lidx)
    653: {
    654:   PetscMPIInt lo = 0, hi, t;

    656:   PetscFunctionBegin;
    657:   PetscAssert((map->n >= 0) && (map->N >= 0) && (map->range), PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE, "PetscLayoutSetUp() must be called first");
    658:   PetscAssert(idx >= 0 && idx <= map->N, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Index %" PetscInt_FMT " is out of range", idx);
    659:   hi = map->size;
    660:   while (hi - lo > 1) {
    661:     t = lo + (hi - lo) / 2;
    662:     if (idx < map->range[t]) hi = t;
    663:     else lo = t;
    664:   }
    665:   if (owner) *owner = lo;
    666:   if (lidx) *lidx = idx - map->range[lo];
    667:   PetscFunctionReturn(PETSC_SUCCESS);
    668: }