Actual source code: pmap.c

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

  6: #include <private/vecimpl.h>   /*I  "petscvec.h"   I*/
  9: /*@C
 10:      PetscLayoutCreate - Allocates PetscLayout space and sets the map contents to the default.

 12:     Collective on MPI_Comm

 14:    Input Parameters:
 15: +    comm - the MPI communicator
 16: -    map - pointer to the map

 18:    Level: developer

 20:     Notes: Typical calling sequence
 21:        PetscLayoutCreate(MPI_Comm,PetscLayout *);
 22:        PetscLayoutSetBlockSize(PetscLayout,1);
 23:        PetscLayoutSetSize(PetscLayout,n) or PetscLayoutSetLocalSize(PetscLayout,N);
 24:        PetscLayoutSetUp(PetscLayout);
 25:        PetscLayoutGetSize(PetscLayout,PetscInt *); or PetscLayoutGetLocalSize(PetscLayout,PetscInt *;)
 26:        PetscLayoutDestroy(PetscLayout);

 28:       The PetscLayout object and methods are intended to be used in the PETSc Vec and Mat implementions; it is 
 29:       recommended they not be used in user codes unless you really gain something in their use.

 31:     Fortran Notes: 
 32:       Not available from Fortran

 34: .seealso: PetscLayoutSetLocalSize(), PetscLayoutSetSize(), PetscLayoutGetSize(), PetscLayoutGetLocalSize(), PetscLayout, PetscLayoutDestroy(),
 35:           PetscLayoutGetRange(), PetscLayoutGetRanges(), PetscLayoutSetBlockSize(), PetscLayoutGetBlockSize(), PetscLayoutSetUp()

 37: @*/
 38: PetscErrorCode  PetscLayoutCreate(MPI_Comm comm,PetscLayout *map)
 39: {

 43:   PetscNew(struct _n_PetscLayout,map);
 44:   (*map)->comm   = comm;
 45:   (*map)->bs     = -1;
 46:   (*map)->n      = -1;
 47:   (*map)->N      = -1;
 48:   (*map)->range  = 0;
 49:   (*map)->rstart = 0;
 50:   (*map)->rend   = 0;
 51:   return(0);
 52: }

 54: /*@C
 55:      PetscLayoutDestroy - Frees a map object and frees its range if that exists. 

 57:     Collective on MPI_Comm

 59:    Input Parameters:
 60: .    map - the PetscLayout

 62:    Level: developer

 64:       The PetscLayout object and methods are intended to be used in the PETSc Vec and Mat implementions; it is 
 65:       recommended they not be used in user codes unless you really gain something in their use.

 67:     Fortran Notes: 
 68:       Not available from Fortran

 70: .seealso: PetscLayoutSetLocalSize(), PetscLayoutSetSize(), PetscLayoutGetSize(), PetscLayoutGetLocalSize(), PetscLayout, PetscLayoutCreate(),
 71:           PetscLayoutGetRange(), PetscLayoutGetRanges(), PetscLayoutSetBlockSize(), PetscLayoutGetBlockSize(), PetscLayoutSetUp()

 73: @*/
 76: PetscErrorCode  PetscLayoutDestroy(PetscLayout *map)
 77: {

 81:   if (!*map) return(0);
 82:   if (!(*map)->refcnt--) {
 83:     PetscFree((*map)->range);
 84:     ISLocalToGlobalMappingDestroy(&(*map)->mapping);
 85:     ISLocalToGlobalMappingDestroy(&(*map)->bmapping);
 86:     PetscFree((*map));
 87:   }
 88:   *map = PETSC_NULL;
 89:   return(0);
 90: }

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

 96:     Collective on MPI_Comm

 98:    Input Parameters:
 99: .    map - pointer to the map

101:    Level: developer

103:     Notes: Typical calling sequence
104:        PetscLayoutCreate(MPI_Comm,PetscLayout *);
105:        PetscLayoutSetBlockSize(PetscLayout,1);
106:        PetscLayoutSetSize(PetscLayout,n) or PetscLayoutSetLocalSize(PetscLayout,N); or both
107:        PetscLayoutSetUp(PetscLayout);
108:        PetscLayoutGetSize(PetscLayout,PetscInt *);


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

113:     Fortran Notes: 
114:       Not available from Fortran

116: .seealso: PetscLayoutSetLocalSize(), PetscLayoutSetSize(), PetscLayoutGetSize(), PetscLayoutGetLocalSize(), PetscLayout, PetscLayoutDestroy(),
117:           PetscLayoutGetRange(), PetscLayoutGetRanges(), PetscLayoutSetBlockSize(), PetscLayoutGetBlockSize(), PetscLayoutCreate()

119: @*/
122: PetscErrorCode  PetscLayoutSetUp(PetscLayout map)
123: {
124:   PetscMPIInt    rank,size;
125:   PetscInt       p;

129:   if (map->bs <=0) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"BlockSize not yet set");
130:   if ((map->n >= 0) && (map->N >= 0) && (map->range)) return(0);

132:   MPI_Comm_size(map->comm, &size);
133:   MPI_Comm_rank(map->comm, &rank);
134:   if (map->n > 0) map->n = map->n/map->bs;
135:   if (map->N > 0) map->N = map->N/map->bs;
136:   PetscSplitOwnership(map->comm,&map->n,&map->N);
137:   map->n = map->n*map->bs;
138:   map->N = map->N*map->bs;
139:   if (!map->range) {
140:     PetscMalloc((size+1)*sizeof(PetscInt), &map->range);
141:   }
142:   MPI_Allgather(&map->n, 1, MPIU_INT, map->range+1, 1, MPIU_INT, map->comm);

144:   map->range[0] = 0;
145:   for(p = 2; p <= size; p++) {
146:     map->range[p] += map->range[p-1];
147:   }

149:   map->rstart = map->range[rank];
150:   map->rend   = map->range[rank+1];
151:   return(0);
152: }

156: /*@C

158:     PetscLayoutCopy - creates a new PetscLayout with the same information as a given one. If the PetscLayout already exists it is destroyed first.

160:      Collective on PetscLayout

162:     Input Parameter:
163: .     in - input PetscLayout to be copied

165:     Output Parameter:
166: .     out - the copy

168:    Level: developer

170:     Notes: PetscLayoutSetUp() does not need to be called on the resulting PetscLayout

172:     Developer Note: Unlike all other copy routines this destroys any input object and makes a new one. This routine should be fixed to have a PetscLayoutDuplicate() 
173:       that ONLY creates a new one and a PetscLayoutCopy() that truely copies the data and does not delete the old object.

175: .seealso: PetscLayoutCreate(), PetscLayoutDestroy(), PetscLayoutSetUp(), PetscLayoutReference()

177: @*/
178: PetscErrorCode  PetscLayoutCopy(PetscLayout in,PetscLayout *out)
179: {
180:   PetscMPIInt    size;
182:   MPI_Comm       comm = in->comm;

185:   PetscLayoutDestroy(out);
186:   PetscLayoutCreate(comm,out);
187:   MPI_Comm_size(comm,&size);
188:   PetscMemcpy(*out,in,sizeof(struct _n_PetscLayout));
189:   PetscMalloc((size+1)*sizeof(PetscInt),&(*out)->range);
190:   PetscMemcpy((*out)->range,in->range,(size+1)*sizeof(PetscInt));
191:   (*out)->refcnt = 0;
192:   return(0);
193: }

197: /*@C

199:     PetscLayoutReference - Causes a PETSc Vec or Mat to share a PetscLayout with one that already exists. Used by Vec/MatDuplicate_XXX() 

201:      Collective on PetscLayout

203:     Input Parameter:
204: .     in - input PetscLayout to be copied

206:     Output Parameter:
207: .     out - the reference location

209:    Level: developer

211:     Notes: PetscLayoutSetUp() does not need to be called on the resulting PetscLayout

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

215: .seealso: PetscLayoutCreate(), PetscLayoutDestroy(), PetscLayoutSetUp(), PetscLayoutCopy()

217: @*/
218: PetscErrorCode  PetscLayoutReference(PetscLayout in,PetscLayout *out)
219: {

223:   in->refcnt++;
224:   PetscLayoutDestroy(out);
225:   *out = in;
226:   return(0);
227: }

231: /*@C

233:     PetscLayoutSetISLocalToGlobalMapping - sets a ISLocalGlobalMapping into a PetscLayout

235:      Collective on PetscLayout

237:     Input Parameter:
238: +     in - input PetscLayout
239: -     ltog - the local to global mapping


242:    Level: developer

244:     Notes: PetscLayoutSetUp() does not need to be called on the resulting PetscLayout

246:     If the ltog location already contains a PetscLayout it is destroyed

248: .seealso: PetscLayoutCreate(), PetscLayoutDestroy(), PetscLayoutSetUp(), PetscLayoutCopy(), PetscLayoutSetLocalToGlobalMappingBlock()

250: @*/
251: PetscErrorCode  PetscLayoutSetISLocalToGlobalMapping(PetscLayout in,ISLocalToGlobalMapping ltog)
252: {

256:   PetscObjectReference((PetscObject)ltog);
257:   ISLocalToGlobalMappingDestroy(&in->mapping);
258:   in->mapping = ltog;
259:   return(0);
260: }

264: /*@C

266:     PetscLayoutSetISLocalToGlobalMappingBlock - sets a ISLocalGlobalMapping into a PetscLayout

268:      Collective on PetscLayout

270:     Input Parameter:
271: +     in - input PetscLayout
272: -     ltog - the local to global block mapping


275:    Level: developer

277:     Notes: PetscLayoutSetUp() does not need to be called on the resulting PetscLayout

279:     If the ltog location already contains a PetscLayout it is destroyed

281: .seealso: PetscLayoutCreate(), PetscLayoutDestroy(), PetscLayoutSetUp(), PetscLayoutCopy(), PetscLayoutSetLocalToGlobalMappingBlock()

283: @*/
284: PetscErrorCode  PetscLayoutSetISLocalToGlobalMappingBlock(PetscLayout in,ISLocalToGlobalMapping ltog)
285: {

289:   PetscObjectReference((PetscObject)ltog);
290:   ISLocalToGlobalMappingDestroy(&in->bmapping);
291:   in->bmapping = ltog;
292:   return(0);
293: }

295: /*@C
296:      PetscLayoutSetLocalSize - Sets the local size for a PetscLayout object.

298:     Collective on PetscLayout

300:    Input Parameters:
301: +    map - pointer to the map
302: -    n - the local size

304:    Level: developer

306:     Notes:
307:        Call this after the call to PetscLayoutCreate()

309:     Fortran Notes: 
310:       Not available from Fortran

312: .seealso: PetscLayoutCreate(), PetscLayoutSetSize(), PetscLayoutGetSize(), PetscLayoutGetLocalSize(), PetscLayoutSetUp()
313:           PetscLayoutGetRange(), PetscLayoutGetRanges(), PetscLayoutSetBlockSize(), PetscLayoutGetBlockSize()

315: @*/
318: PetscErrorCode  PetscLayoutSetLocalSize(PetscLayout map,PetscInt n)
319: {
321:   map->n = n;
322:   return(0);
323: }

325: /*@C
326:      PetscLayoutGetLocalSize - Gets the local size for a PetscLayout object.

328:     Not Collective

330:    Input Parameters:
331: .    map - pointer to the map

333:    Output Parameters:
334: .    n - the local size

336:    Level: developer

338:     Notes:
339:        Call this after the call to PetscLayoutSetUp()

341:     Fortran Notes: 
342:       Not available from Fortran

344: .seealso: PetscLayoutCreate(), PetscLayoutSetSize(), PetscLayoutGetSize(), PetscLayoutGetLocalSize(), PetscLayoutSetUp()
345:           PetscLayoutGetRange(), PetscLayoutGetRanges(), PetscLayoutSetBlockSize(), PetscLayoutGetBlockSize()

347: @*/
350: PetscErrorCode  PetscLayoutGetLocalSize(PetscLayout map,PetscInt *n)
351: {
353:   *n = map->n;
354:   return(0);
355: }

357: /*@C
358:      PetscLayoutSetSize - Sets the global size for a PetscLayout object.

360:     Logically Collective on PetscLayout

362:    Input Parameters:
363: +    map - pointer to the map
364: -    n - the global size

366:    Level: developer

368:     Notes:
369:        Call this after the call to PetscLayoutCreate()

371:     Fortran Notes: 
372:       Not available from Fortran

374: .seealso: PetscLayoutCreate(), PetscLayoutSetLocalSize(), PetscLayoutGetLocalSize(), PetscLayoutGetSize(), PetscLayoutSetUp()
375:           PetscLayoutGetRange(), PetscLayoutGetRanges(), PetscLayoutSetBlockSize(), PetscLayoutGetBlockSize()

377: @*/
380: PetscErrorCode  PetscLayoutSetSize(PetscLayout map,PetscInt n)
381: {
383:   map->N = n;
384:   return(0);
385: }

387: /*@C
388:      PetscLayoutGetSize - Gets the global size for a PetscLayout object.

390:     Not Collective

392:    Input Parameters:
393: .    map - pointer to the map

395:    Output Parameters:
396: .    n - the global size

398:    Level: developer

400:     Notes:
401:        Call this after the call to PetscLayoutSetUp()

403:     Fortran Notes: 
404:       Not available from Fortran

406: .seealso: PetscLayoutCreate(), PetscLayoutSetLocalSize(), PetscLayoutGetLocalSize(), PetscLayoutSetSize(), PetscLayoutSetUp()
407:           PetscLayoutGetRange(), PetscLayoutGetRanges(), PetscLayoutSetBlockSize(), PetscLayoutGetBlockSize()

409: @*/
412: PetscErrorCode  PetscLayoutGetSize(PetscLayout map,PetscInt *n)
413: {
415:   *n = map->N;
416:   return(0);
417: }

419: /*@C
420:      PetscLayoutSetBlockSize - Sets the block size for a PetscLayout object.

422:     Logically Collective on PetscLayout

424:    Input Parameters:
425: +    map - pointer to the map
426: -    bs - the size

428:    Level: developer

430:     Notes:
431:        Call this after the call to PetscLayoutCreate()

433:     Fortran Notes: 
434:       Not available from Fortran

436: .seealso: PetscLayoutCreate(), PetscLayoutSetLocalSize(), PetscLayoutGetLocalSize(), PetscLayoutGetBlockSize(),
437:           PetscLayoutGetRange(), PetscLayoutGetRanges(), PetscLayoutSetSize(), PetscLayoutGetSize(), PetscLayoutSetUp()

439: @*/
442: PetscErrorCode  PetscLayoutSetBlockSize(PetscLayout map,PetscInt bs)
443: {
445:   map->bs = bs;
446:   return(0);
447: }

449: /*@C
450:      PetscLayoutGetBlockSize - Gets the block size for a PetscLayout object.

452:     Not Collective

454:    Input Parameters:
455: .    map - pointer to the map

457:    Output Parameters:
458: .    bs - the size

460:    Level: developer

462:     Notes:
463:        Call this after the call to PetscLayoutSetUp()

465:     Fortran Notes: 
466:       Not available from Fortran

468: .seealso: PetscLayoutCreate(), PetscLayoutSetLocalSize(), PetscLayoutGetLocalSize(), PetscLayoutSetSize(), PetscLayoutSetUp()
469:           PetscLayoutGetRange(), PetscLayoutGetRanges(), PetscLayoutSetBlockSize(), PetscLayoutGetSize()

471: @*/
474: PetscErrorCode  PetscLayoutGetBlockSize(PetscLayout map,PetscInt *bs)
475: {
477:   *bs = map->bs;
478:   return(0);
479: }


482: /*@C
483:      PetscLayoutGetRange - gets the range of values owned by this process

485:     Not Collective

487:    Input Parameters:
488: .    map - pointer to the map

490:    Output Parameters:
491: +    rstart - first index owned by this process
492: -    rend - one more than the last index owned by this process

494:    Level: developer

496:     Notes:
497:        Call this after the call to PetscLayoutSetUp()

499:     Fortran Notes: 
500:       Not available from Fortran

502: .seealso: PetscLayoutCreate(), PetscLayoutSetLocalSize(), PetscLayoutGetLocalSize(), PetscLayoutSetSize(),
503:           PetscLayoutGetSize(), PetscLayoutGetRanges(), PetscLayoutSetBlockSize(), PetscLayoutGetSize(), PetscLayoutSetUp()

505: @*/
508: PetscErrorCode  PetscLayoutGetRange(PetscLayout map,PetscInt *rstart,PetscInt *rend)
509: {
511:   if (rstart) *rstart = map->rstart;
512:   if (rend)   *rend   = map->rend;
513:   return(0);
514: }

516: /*@C
517:      PetscLayoutGetRanges - gets the range of values owned by all processes

519:     Not Collective

521:    Input Parameters:
522: .    map - pointer to the map

524:    Output Parameters:
525: .    range - start of each processors range of indices (the final entry is one more then the
526:              last index on the last process)

528:    Level: developer

530:     Notes:
531:        Call this after the call to PetscLayoutSetUp()

533:     Fortran Notes: 
534:       Not available from Fortran

536: .seealso: PetscLayoutCreate(), PetscLayoutSetLocalSize(), PetscLayoutGetLocalSize(), PetscLayoutSetSize(),
537:           PetscLayoutGetSize(), PetscLayoutGetRange(), PetscLayoutSetBlockSize(), PetscLayoutGetSize(), PetscLayoutSetUp()

539: @*/
542: PetscErrorCode  PetscLayoutGetRanges(PetscLayout map,const PetscInt *range[])
543: {
545:   *range = map->range;
546:   return(0);
547: }