Actual source code: dmget.c

petsc-master 2015-04-24
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:   *g = NULL;
104:   return(0);
105: }

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

113:    Collective on DM

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

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

121:    Level: beginner

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

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

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

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

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

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

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

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

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

172:    Collective on DM

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

177:    Level: developer

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

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

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

194:   for (i=0; i<DM_MAX_WORK_VECTORS; i++) {
195:     Vec g;
196:     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()");
197:     g = dm->globalin[i];
198:     dm->globalin[i] = NULL;
199:     VecDestroy(&g);
200:   }
201:   return(0);
202: }

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

211:    Not Collective

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

217:    Level: beginner

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

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

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

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

255:    Collective on DM

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

261:    Output Arguments:
262: .  X - named Vec

264:    Level: developer

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

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

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

288:   /* Create the Vec */
289:   PetscNew(&link);
290:   PetscStrallocpy(name,&link->name);
291:   DMCreateGlobalVector(dm,&link->X);
292:   link->next      = dm->namedglobal;
293:   dm->namedglobal = link;

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

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

306:    Collective on DM

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

313:    Output Arguments:

315:    Level: developer

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

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

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

349:    Not Collective

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

355:    Output Arguments:
356: .  X - named Vec

358:    Level: developer

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

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

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

382:   /* Create the Vec */
383:   PetscNew(&link);
384:   PetscStrallocpy(name,&link->name);
385:   DMCreateLocalVector(dm,&link->X);
386:   link->next     = dm->namedlocal;
387:   dm->namedlocal = link;

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

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

400:    Not Collective

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

407:    Output Arguments:

409:    Level: developer

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

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