Actual source code: dmget.c

petsc-dev 2014-08-28
Report Typos and Errors
  1: #include <petsc-private/dmimpl.h> /*I "petscdm.h" I*/

  5: /*@
  6:    DMGetLocalVector - Gets a Seq PETSc vector that
  7:    may be used with the DMXXX routines. This vector has spaces for the ghost values.

  9:    Not Collective

 11:    Input Parameter:
 12: .  dm - the distributed array

 14:    Output Parameter:
 15: .  g - the local vector

 17:    Level: beginner

 19:    Note:
 20:    The vector values are NOT initialized and may have garbage in them, so you may need
 21:    to zero them.

 23:    The output parameter, g, is a regular PETSc vector that should be returned with
 24:    DMRestoreLocalVector() DO NOT call VecDestroy() on it.

 26:    VecStride*() operations can be useful when using DM with dof > 1

 28: .keywords: distributed array, create, local, vector

 30: .seealso: DMCreateGlobalVector(), VecDuplicate(), VecDuplicateVecs(),
 31:           DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMGlobalToLocalBegin(),
 32:           DMGlobalToLocalEnd(), DMLocalToGlobalBegin(), DMCreateLocalVector(), DMRestoreLocalVector(),
 33:           VecStrideMax(), VecStrideMin(), VecStrideNorm()
 34: @*/
 35: PetscErrorCode  DMGetLocalVector(DM dm,Vec *g)
 36: {
 37:   PetscErrorCode ierr,i;

 42:   for (i=0; i<DM_MAX_WORK_VECTORS; i++) {
 43:     if (dm->localin[i]) {
 44:       *g             = dm->localin[i];
 45:       dm->localin[i] = NULL;
 46:       goto alldone;
 47:     }
 48:   }
 49:   DMCreateLocalVector(dm,g);

 51: alldone:
 52:   for (i=0; i<DM_MAX_WORK_VECTORS; i++) {
 53:     if (!dm->localout[i]) {
 54:       dm->localout[i] = *g;
 55:       break;
 56:     }
 57:   }
 58:   return(0);
 59: }

 63: /*@
 64:    DMRestoreLocalVector - Returns a Seq PETSc vector that
 65:      obtained from DMGetLocalVector(). Do not use with vector obtained via
 66:      DMCreateLocalVector().

 68:    Not Collective

 70:    Input Parameter:
 71: +  dm - the distributed array
 72: -  g - the local vector

 74:    Level: beginner

 76: .keywords: distributed array, create, local, vector

 78: .seealso: DMCreateGlobalVector(), VecDuplicate(), VecDuplicateVecs(),
 79:           DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMGlobalToLocalBegin(),
 80:           DMGlobalToLocalEnd(), DMLocalToGlobalBegin(), DMCreateLocalVector(), DMGetLocalVector()
 81: @*/
 82: PetscErrorCode  DMRestoreLocalVector(DM dm,Vec *g)
 83: {
 85:   PetscInt       i,j;

 90:   for (j=0; j<DM_MAX_WORK_VECTORS; j++) {
 91:     if (*g == dm->localout[j]) {
 92:       dm->localout[j] = NULL;
 93:       for (i=0; i<DM_MAX_WORK_VECTORS; i++) {
 94:         if (!dm->localin[i]) {
 95:           dm->localin[i] = *g;
 96:           goto alldone;
 97:         }
 98:       }
 99:     }
100:   }
101:   VecDestroy(g);
102: alldone:
103:   return(0);
104: }

108: /*@
109:    DMGetGlobalVector - Gets a MPI PETSc vector that
110:    may be used with the DMXXX routines.

112:    Collective on DM

114:    Input Parameter:
115: .  dm - the distributed array

117:    Output Parameter:
118: .  g - the global vector

120:    Level: beginner

122:    Note:
123:    The vector values are NOT initialized and may have garbage in them, so you may need
124:    to zero them.

126:    The output parameter, g, is a regular PETSc vector that should be returned with
127:    DMRestoreGlobalVector() DO NOT call VecDestroy() on it.

129:    VecStride*() operations can be useful when using DM with dof > 1

131: .keywords: distributed array, create, Global, vector

133: .seealso: DMCreateGlobalVector(), VecDuplicate(), VecDuplicateVecs(),
134:           DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMGlobalToLocalBegin(),
135:           DMGlobalToLocalEnd(), DMLocalToGlobalBegin(), DMCreateLocalVector(), DMRestoreLocalVector()
136:           VecStrideMax(), VecStrideMin(), VecStrideNorm()

138: @*/
139: PetscErrorCode  DMGetGlobalVector(DM dm,Vec *g)
140: {
142:   PetscInt       i;

147:   for (i=0; i<DM_MAX_WORK_VECTORS; i++) {
148:     if (dm->globalin[i]) {
149:       *g              = dm->globalin[i];
150:       dm->globalin[i] = NULL;
151:       goto alldone;
152:     }
153:   }
154:   DMCreateGlobalVector(dm,g);

156: alldone:
157:   for (i=0; i<DM_MAX_WORK_VECTORS; i++) {
158:     if (!dm->globalout[i]) {
159:       dm->globalout[i] = *g;
160:       break;
161:     }
162:   }
163:   return(0);
164: }

168: /*@
169:    DMClearGlobalVectors - Destroys all the global vectors that have been stashed in this DM

171:    Collective on DM

173:    Input Parameter:
174: .  dm - the distributed array

176:    Level: developer

178: .keywords: distributed array, create, Global, vector

180: .seealso: DMCreateGlobalVector(), VecDuplicate(), VecDuplicateVecs(),
181:           DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMGlobalToLocalBegin(),
182:           DMGlobalToLocalEnd(), DMLocalToGlobalBegin(), DMCreateLocalVector(), DMRestoreLocalVector()
183:           VecStrideMax(), VecStrideMin(), VecStrideNorm()

185: @*/
186: PetscErrorCode  DMClearGlobalVectors(DM dm)
187: {
189:   PetscInt       i;

193:   for (i=0; i<DM_MAX_WORK_VECTORS; i++) {
194:     Vec g;
195:     if (dm->globalout[i]) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Clearing DM of global vectors that has a global vector obtained with DMGetGlobalVector()");
196:     g = dm->globalin[i];
197:     dm->globalin[i] = NULL;
198:     VecDestroy(&g);
199:   }
200:   return(0);
201: }

205: /*@
206:    DMRestoreGlobalVector - Returns a Seq PETSc vector that
207:      obtained from DMGetGlobalVector(). Do not use with vector obtained via
208:      DMCreateGlobalVector().

210:    Not Collective

212:    Input Parameter:
213: +  dm - the distributed array
214: -  g - the global vector

216:    Level: beginner

218: .keywords: distributed array, create, global, vector

220: .seealso: DMCreateGlobalVector(), VecDuplicate(), VecDuplicateVecs(),
221:           DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMGlobalToGlobalBegin(),
222:           DMGlobalToGlobalEnd(), DMGlobalToGlobal(), DMCreateLocalVector(), DMGetGlobalVector()
223: @*/
224: PetscErrorCode  DMRestoreGlobalVector(DM dm,Vec *g)
225: {
227:   PetscInt       i,j;

232:   for (j=0; j<DM_MAX_WORK_VECTORS; j++) {
233:     if (*g == dm->globalout[j]) {
234:       dm->globalout[j] = NULL;
235:       for (i=0; i<DM_MAX_WORK_VECTORS; i++) {
236:         if (!dm->globalin[i]) {
237:           dm->globalin[i] = *g;
238:           goto alldone;
239:         }
240:       }
241:     }
242:   }
243:   VecDestroy(g);
244: alldone:
245:   return(0);
246: }

250: /*@C
251:    DMGetNamedGlobalVector - get access to a named, persistent global vector

253:    Collective on DM

255:    Input Arguments:
256: +  dm - DM to hold named vectors
257: -  name - unique name for Vec

259:    Output Arguments:
260: .  X - named Vec

262:    Level: developer

264:    Note: If a Vec with the given name does not exist, it is created.

266: .seealso: DMRestoreNamedGlobalVector()
267: @*/
268: PetscErrorCode DMGetNamedGlobalVector(DM dm,const char *name,Vec *X)
269: {
271:   DMNamedVecLink link;

277:   for (link=dm->namedglobal; link; link=link->next) {
278:     PetscBool match;
279:     PetscStrcmp(name,link->name,&match);
280:     if (match) {
281:       if (link->status != DMVEC_STATUS_IN) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_WRONGSTATE,"Vec name '%s' already checked out",name);
282:       goto found;
283:     }
284:   }

286:   /* Create the Vec */
287:   PetscMalloc(sizeof(*link),&link);
288:   PetscStrallocpy(name,&link->name);
289:   DMCreateGlobalVector(dm,&link->X);
290:   link->next      = dm->namedglobal;
291:   dm->namedglobal = link;

293: found:
294:   *X           = link->X;
295:   link->status = DMVEC_STATUS_OUT;
296:   return(0);
297: }

301: /*@C
302:    DMRestoreNamedGlobalVector - restore access to a named, persistent global vector

304:    Collective on DM

306:    Input Arguments:
307: +  dm - DM on which the vector was gotten
308: .  name - name under which the vector was gotten
309: -  X - Vec to restore

311:    Output Arguments:

313:    Level: developer

315: .seealso: DMGetNamedGlobalVector()
316: @*/
317: PetscErrorCode DMRestoreNamedGlobalVector(DM dm,const char *name,Vec *X)
318: {
320:   DMNamedVecLink link;

327:   for (link=dm->namedglobal; link; link=link->next) {
328:     PetscBool match;
329:     PetscStrcmp(name,link->name,&match);
330:     if (match) {
331:       if (link->status != DMVEC_STATUS_OUT) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_WRONGSTATE,"Vec name '%s' was not checked out",name);
332:       if (link->X != *X) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_INCOMP,"Attempt to restore Vec name '%s', but Vec does not match the cache",name);
333:       link->status = DMVEC_STATUS_IN;
334:       *X           = NULL;
335:       return(0);
336:     }
337:   }
338:   SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_INCOMP,"Could not find Vec name '%s' to restore",name);
339:   return(0);
340: }

344: /*@C
345:    DMGetNamedLocalVector - get access to a named, persistent local vector

347:    Not Collective

349:    Input Arguments:
350: +  dm - DM to hold named vectors
351: -  name - unique name for Vec

353:    Output Arguments:
354: .  X - named Vec

356:    Level: developer

358:    Note: If a Vec with the given name does not exist, it is created.

360: .seealso: DMGetNamedGlobalVector(),DMRestoreNamedLocalVector()
361: @*/
362: PetscErrorCode DMGetNamedLocalVector(DM dm,const char *name,Vec *X)
363: {
365:   DMNamedVecLink link;

371:   for (link=dm->namedlocal; link; link=link->next) {
372:     PetscBool match;
373:     PetscStrcmp(name,link->name,&match);
374:     if (match) {
375:       if (link->status != DMVEC_STATUS_IN) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_WRONGSTATE,"Vec name '%s' already checked out",name);
376:       goto found;
377:     }
378:   }

380:   /* Create the Vec */
381:   PetscMalloc(sizeof(*link),&link);
382:   PetscStrallocpy(name,&link->name);
383:   DMCreateLocalVector(dm,&link->X);
384:   link->next     = dm->namedlocal;
385:   dm->namedlocal = link;

387: found:
388:   *X           = link->X;
389:   link->status = DMVEC_STATUS_OUT;
390:   return(0);
391: }

395: /*@C
396:    DMRestoreNamedLocalVector - restore access to a named, persistent local vector

398:    Not Collective

400:    Input Arguments:
401: +  dm - DM on which the vector was gotten
402: .  name - name under which the vector was gotten
403: -  X - Vec to restore

405:    Output Arguments:

407:    Level: developer

409: .seealso: DMRestoreNamedGlobalVector(),DMGetNamedLocalVector()
410: @*/
411: PetscErrorCode DMRestoreNamedLocalVector(DM dm,const char *name,Vec *X)
412: {
414:   DMNamedVecLink link;

421:   for (link=dm->namedlocal; link; link=link->next) {
422:     PetscBool match;
423:     PetscStrcmp(name,link->name,&match);
424:     if (match) {
425:       if (link->status != DMVEC_STATUS_OUT) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_WRONGSTATE,"Vec name '%s' was not checked out",name);
426:       if (link->X != *X) SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_INCOMP,"Attempt to restore Vec name '%s', but Vec does not match the cache",name);
427:       link->status = DMVEC_STATUS_IN;
428:       *X           = NULL;
429:       return(0);
430:     }
431:   }
432:   SETERRQ1(PetscObjectComm((PetscObject)dm),PETSC_ERR_ARG_INCOMP,"Could not find Vec name '%s' to restore",name);
433:   return(0);
434: }