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

      2: /*
      3:      Provides the interface functions for vector operations that do NOT have PetscScalar/PetscReal in the signature
      4:    These are the vector functions the user calls.
      5: */
      6:  #include <petsc/private/vecimpl.h>

      8: /* Logging support */
      9: PetscClassId  VEC_CLASSID;
     10: PetscLogEvent VEC_View, VEC_Max, VEC_Min, VEC_Dot, VEC_MDot, VEC_TDot;
     11: PetscLogEvent VEC_Norm, VEC_Normalize, VEC_Scale, VEC_Copy, VEC_Set, VEC_AXPY, VEC_AYPX, VEC_WAXPY;
     12: PetscLogEvent VEC_MTDot, VEC_MAXPY, VEC_Swap, VEC_AssemblyBegin, VEC_ScatterBegin, VEC_ScatterEnd;
     13: PetscLogEvent VEC_AssemblyEnd, VEC_PointwiseMult, VEC_SetValues, VEC_Load;
     14: PetscLogEvent VEC_SetRandom, VEC_ReduceArithmetic, VEC_ReduceCommunication,VEC_ReduceBegin,VEC_ReduceEnd,VEC_Ops;
     15: PetscLogEvent VEC_DotNorm2, VEC_AXPBYPCZ;
     16: PetscLogEvent VEC_ViennaCLCopyFromGPU, VEC_ViennaCLCopyToGPU;
     17: PetscLogEvent VEC_CUDACopyFromGPU, VEC_CUDACopyToGPU;
     18: PetscLogEvent VEC_CUDACopyFromGPUSome, VEC_CUDACopyToGPUSome;

     20: /*@
     21:    VecStashGetInfo - Gets how many values are currently in the vector stash, i.e. need
     22:        to be communicated to other processors during the VecAssemblyBegin/End() process

     24:     Not collective

     26:    Input Parameter:
     27: .   vec - the vector

     29:    Output Parameters:
     30: +   nstash   - the size of the stash
     31: .   reallocs - the number of additional mallocs incurred.
     32: .   bnstash   - the size of the block stash
     33: -   breallocs - the number of additional mallocs incurred.in the block stash

     35:    Level: advanced

     37: .seealso: VecAssemblyBegin(), VecAssemblyEnd(), Vec, VecStashSetInitialSize(), VecStashView()

     39: @*/
     40: PetscErrorCode  VecStashGetInfo(Vec vec,PetscInt *nstash,PetscInt *reallocs,PetscInt *bnstash,PetscInt *breallocs)
     41: {

     45:   VecStashGetInfo_Private(&vec->stash,nstash,reallocs);
     46:   VecStashGetInfo_Private(&vec->bstash,bnstash,breallocs);
     47:   return(0);
     48: }

     50: /*@
     51:    VecSetLocalToGlobalMapping - Sets a local numbering to global numbering used
     52:    by the routine VecSetValuesLocal() to allow users to insert vector entries
     53:    using a local (per-processor) numbering.

     55:    Logically Collective on Vec

     57:    Input Parameters:
     58: +  x - vector
     59: -  mapping - mapping created with ISLocalToGlobalMappingCreate() or ISLocalToGlobalMappingCreateIS()

     61:    Notes:
     62:    All vectors obtained with VecDuplicate() from this vector inherit the same mapping.

     64:    Level: intermediate

     66:    Concepts: vector^setting values with local numbering

     68: seealso:  VecAssemblyBegin(), VecAssemblyEnd(), VecSetValues(), VecSetValuesLocal(),
     69:            VecSetLocalToGlobalMapping(), VecSetValuesBlockedLocal()
     70: @*/
     71: PetscErrorCode  VecSetLocalToGlobalMapping(Vec x,ISLocalToGlobalMapping mapping)
     72: {

     79:   if (x->ops->setlocaltoglobalmapping) {
     80:     (*x->ops->setlocaltoglobalmapping)(x,mapping);
     81:   } else {
     82:     PetscLayoutSetISLocalToGlobalMapping(x->map,mapping);
     83:   }
     84:   return(0);
     85: }

     87: /*@
     88:    VecGetLocalToGlobalMapping - Gets the local-to-global numbering set by VecSetLocalToGlobalMapping()

     90:    Not Collective

     92:    Input Parameter:
     93: .  X - the vector

     95:    Output Parameter:
     96: .  mapping - the mapping

     98:    Level: advanced

    100:    Concepts: vectors^local to global mapping
    101:    Concepts: local to global mapping^for vectors

    103: .seealso:  VecSetValuesLocal()
    104: @*/
    105: PetscErrorCode VecGetLocalToGlobalMapping(Vec X,ISLocalToGlobalMapping *mapping)
    106: {
    111:   *mapping = X->map->mapping;
    112:   return(0);
    113: }

    115: /*@
    116:    VecAssemblyBegin - Begins assembling the vector.  This routine should
    117:    be called after completing all calls to VecSetValues().

    119:    Collective on Vec

    121:    Input Parameter:
    122: .  vec - the vector

    124:    Level: beginner

    126:    Concepts: assembly^vectors

    128: .seealso: VecAssemblyEnd(), VecSetValues()
    129: @*/
    130: PetscErrorCode  VecAssemblyBegin(Vec vec)
    131: {

    137:   VecStashViewFromOptions(vec,NULL,"-vec_view_stash");
    138:   PetscLogEventBegin(VEC_AssemblyBegin,vec,0,0,0);
    139:   if (vec->ops->assemblybegin) {
    140:     (*vec->ops->assemblybegin)(vec);
    141:   }
    142:   PetscLogEventEnd(VEC_AssemblyBegin,vec,0,0,0);
    143:   PetscObjectStateIncrease((PetscObject)vec);
    144:   return(0);
    145: }

    147: /*@
    148:    VecAssemblyEnd - Completes assembling the vector.  This routine should
    149:    be called after VecAssemblyBegin().

    151:    Collective on Vec

    153:    Input Parameter:
    154: .  vec - the vector

    156:    Options Database Keys:
    157: +  -vec_view - Prints vector in ASCII format
    158: .  -vec_view ::ascii_matlab - Prints vector in ASCII MATLAB format to stdout
    159: .  -vec_view matlab:filename - Prints vector in MATLAB format to matlaboutput.mat
    160: .  -vec_view draw - Activates vector viewing using drawing tools
    161: .  -display <name> - Sets display name (default is host)
    162: .  -draw_pause <sec> - Sets number of seconds to pause after display
    163: -  -vec_view socket - Activates vector viewing using a socket

    165:    Level: beginner

    167: .seealso: VecAssemblyBegin(), VecSetValues()
    168: @*/
    169: PetscErrorCode  VecAssemblyEnd(Vec vec)
    170: {

    175:   PetscLogEventBegin(VEC_AssemblyEnd,vec,0,0,0);
    177:   if (vec->ops->assemblyend) {
    178:     (*vec->ops->assemblyend)(vec);
    179:   }
    180:   PetscLogEventEnd(VEC_AssemblyEnd,vec,0,0,0);
    181:   VecViewFromOptions(vec,NULL,"-vec_view");
    182:   return(0);
    183: }

    185: /*@
    186:    VecPointwiseMax - Computes the componentwise maximum w_i = max(x_i, y_i).

    188:    Logically Collective on Vec

    190:    Input Parameters:
    191: .  x, y  - the vectors

    193:    Output Parameter:
    194: .  w - the result

    196:    Level: advanced

    198:    Notes:
    199:     any subset of the x, y, and w may be the same vector.
    200:           For complex numbers compares only the real part

    202:    Concepts: vector^pointwise multiply

    204: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
    205: @*/
    206: PetscErrorCode  VecPointwiseMax(Vec w,Vec x,Vec y)
    207: {

    219:   VecCheckSameSize(w,1,x,2);
    220:   VecCheckSameSize(w,1,y,3);
    221:   (*w->ops->pointwisemax)(w,x,y);
    222:   PetscObjectStateIncrease((PetscObject)w);
    223:   return(0);
    224: }

    227: /*@
    228:    VecPointwiseMin - Computes the componentwise minimum w_i = min(x_i, y_i).

    230:    Logically Collective on Vec

    232:    Input Parameters:
    233: .  x, y  - the vectors

    235:    Output Parameter:
    236: .  w - the result

    238:    Level: advanced

    240:    Notes:
    241:     any subset of the x, y, and w may be the same vector.
    242:           For complex numbers compares only the real part

    244:    Concepts: vector^pointwise multiply

    246: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
    247: @*/
    248: PetscErrorCode  VecPointwiseMin(Vec w,Vec x,Vec y)
    249: {

    261:   VecCheckSameSize(w,1,x,2);
    262:   VecCheckSameSize(w,1,y,3);
    263:   (*w->ops->pointwisemin)(w,x,y);
    264:   PetscObjectStateIncrease((PetscObject)w);
    265:   return(0);
    266: }

    268: /*@
    269:    VecPointwiseMaxAbs - Computes the componentwise maximum of the absolute values w_i = max(abs(x_i), abs(y_i)).

    271:    Logically Collective on Vec

    273:    Input Parameters:
    274: .  x, y  - the vectors

    276:    Output Parameter:
    277: .  w - the result

    279:    Level: advanced

    281:    Notes:
    282:     any subset of the x, y, and w may be the same vector.

    284:    Concepts: vector^pointwise multiply

    286: .seealso: VecPointwiseDivide(), VecPointwiseMult(), VecPointwiseMin(), VecPointwiseMax(), VecMaxPointwiseDivide()
    287: @*/
    288: PetscErrorCode  VecPointwiseMaxAbs(Vec w,Vec x,Vec y)
    289: {

    301:   VecCheckSameSize(w,1,x,2);
    302:   VecCheckSameSize(w,1,y,3);
    303:   (*w->ops->pointwisemaxabs)(w,x,y);
    304:   PetscObjectStateIncrease((PetscObject)w);
    305:   return(0);
    306: }

    308: /*@
    309:    VecPointwiseDivide - Computes the componentwise division w = x/y.

    311:    Logically Collective on Vec

    313:    Input Parameters:
    314: .  x, y  - the vectors

    316:    Output Parameter:
    317: .  w - the result

    319:    Level: advanced

    321:    Notes:
    322:     any subset of the x, y, and w may be the same vector.

    324:    Concepts: vector^pointwise divide

    326: .seealso: VecPointwiseMult(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
    327: @*/
    328: PetscErrorCode  VecPointwiseDivide(Vec w,Vec x,Vec y)
    329: {

    341:   VecCheckSameSize(w,1,x,2);
    342:   VecCheckSameSize(w,1,y,3);
    343:   (*w->ops->pointwisedivide)(w,x,y);
    344:   PetscObjectStateIncrease((PetscObject)w);
    345:   return(0);
    346: }

    349: /*@
    350:    VecDuplicate - Creates a new vector of the same type as an existing vector.

    352:    Collective on Vec

    354:    Input Parameters:
    355: .  v - a vector to mimic

    357:    Output Parameter:
    358: .  newv - location to put new vector

    360:    Notes:
    361:    VecDuplicate() DOES NOT COPY the vector entries, but rather allocates storage
    362:    for the new vector.  Use VecCopy() to copy a vector.

    364:    Use VecDestroy() to free the space. Use VecDuplicateVecs() to get several
    365:    vectors.

    367:    Level: beginner

    369: .seealso: VecDestroy(), VecDuplicateVecs(), VecCreate(), VecCopy()
    370: @*/
    371: PetscErrorCode  VecDuplicate(Vec v,Vec *newv)
    372: {

    379:   (*v->ops->duplicate)(v,newv);
    380:   PetscObjectStateIncrease((PetscObject)*newv);
    381:   return(0);
    382: }

    384: /*@
    385:    VecDestroy - Destroys a vector.

    387:    Collective on Vec

    389:    Input Parameters:
    390: .  v  - the vector

    392:    Level: beginner

    394: .seealso: VecDuplicate(), VecDestroyVecs()
    395: @*/
    396: PetscErrorCode  VecDestroy(Vec *v)
    397: {

    401:   if (!*v) return(0);
    403:   if (--((PetscObject)(*v))->refct > 0) {*v = 0; return(0);}

    405:   PetscObjectSAWsViewOff((PetscObject)*v);
    406:   /* destroy the internal part */
    407:   if ((*v)->ops->destroy) {
    408:     (*(*v)->ops->destroy)(*v);
    409:   }
    410:   /* destroy the external/common part */
    411:   PetscLayoutDestroy(&(*v)->map);
    412:   PetscHeaderDestroy(v);
    413:   return(0);
    414: }

    416: /*@C
    417:    VecDuplicateVecs - Creates several vectors of the same type as an existing vector.

    419:    Collective on Vec

    421:    Input Parameters:
    422: +  m - the number of vectors to obtain
    423: -  v - a vector to mimic

    425:    Output Parameter:
    426: .  V - location to put pointer to array of vectors

    428:    Notes:
    429:    Use VecDestroyVecs() to free the space. Use VecDuplicate() to form a single
    430:    vector.

    432:    Fortran Note:
    433:    The Fortran interface is slightly different from that given below, it
    434:    requires one to pass in V a Vec (integer) array of size at least m.
    435:    See the Fortran chapter of the users manual and petsc/src/vec/vec/examples for details.

    437:    Level: intermediate

    439: .seealso:  VecDestroyVecs(), VecDuplicate(), VecCreate(), VecDuplicateVecsF90()
    440: @*/
    441: PetscErrorCode  VecDuplicateVecs(Vec v,PetscInt m,Vec *V[])
    442: {

    449:   (*v->ops->duplicatevecs)(v,m,V);
    450:   return(0);
    451: }

    453: /*@C
    454:    VecDestroyVecs - Frees a block of vectors obtained with VecDuplicateVecs().

    456:    Collective on Vec

    458:    Input Parameters:
    459: +  vv - pointer to pointer to array of vector pointers, if NULL no vectors are destroyed
    460: -  m - the number of vectors previously obtained, if zero no vectors are destroyed

    462:    Fortran Note:
    463:    The Fortran interface is slightly different from that given below.
    464:    See the Fortran chapter of the users manual

    466:    Level: intermediate

    468: .seealso: VecDuplicateVecs(), VecDestroyVecsf90()
    469: @*/
    470: PetscErrorCode  VecDestroyVecs(PetscInt m,Vec *vv[])
    471: {

    476:   if (m < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Trying to destroy negative number of vectors %D",m);
    477:   if (!m || !*vv) {*vv  = NULL; return(0);}
    480:   (*(**vv)->ops->destroyvecs)(m,*vv);
    481:   *vv  = NULL;
    482:   return(0);
    483: }

    485: /*@C
    486:    VecView - Views a vector object.

    488:    Collective on Vec

    490:    Input Parameters:
    491: +  vec - the vector
    492: -  viewer - an optional visualization context

    494:    Notes:
    495:    The available visualization contexts include
    496: +     PETSC_VIEWER_STDOUT_SELF - for sequential vectors
    497: .     PETSC_VIEWER_STDOUT_WORLD - for parallel vectors created on PETSC_COMM_WORLD
    498: -     PETSC_VIEWER_STDOUT_(comm) - for parallel vectors created on MPI communicator comm

    500:    You can change the format the vector is printed using the
    501:    option PetscViewerPushFormat().

    503:    The user can open alternative visualization contexts with
    504: +    PetscViewerASCIIOpen() - Outputs vector to a specified file
    505: .    PetscViewerBinaryOpen() - Outputs vector in binary to a
    506:          specified file; corresponding input uses VecLoad()
    507: .    PetscViewerDrawOpen() - Outputs vector to an X window display
    508: -    PetscViewerSocketOpen() - Outputs vector to Socket viewer

    510:    The user can call PetscViewerPushFormat() to specify the output
    511:    format of ASCII printed objects (when using PETSC_VIEWER_STDOUT_SELF,
    512:    PETSC_VIEWER_STDOUT_WORLD and PetscViewerASCIIOpen).  Available formats include
    513: +    PETSC_VIEWER_DEFAULT - default, prints vector contents
    514: .    PETSC_VIEWER_ASCII_MATLAB - prints vector contents in MATLAB format
    515: .    PETSC_VIEWER_ASCII_INDEX - prints vector contents, including indices of vector elements
    516: -    PETSC_VIEWER_ASCII_COMMON - prints vector contents, using a
    517:          format common among all vector types

    519:    Notes:
    520:     You can pass any number of vector objects, or other PETSc objects to the same viewer.

    522:    Notes for binary viewer: If you pass multiply vectors to a binary viewer you can read them back in in the same order
    523: $     with VecLoad().
    524: $
    525: $    If the blocksize of the vector is greater than one then you must provide a unique prefix to
    526: $    the vector with PetscObjectSetOptionsPrefix((PetscObject)vec,"uniqueprefix"); BEFORE calling VecView() on the
    527: $    vector to be stored and then set that same unique prefix on the vector that you pass to VecLoad(). The blocksize
    528: $    information is stored in an ASCII file with the same name as the binary file plus a ".info" appended to the
    529: $    filename. If you copy the binary file, make sure you copy the associated .info file with it.

    531:    Notes for HDF5 Viewer: the name of the Vec (given with PetscObjectSetName() is the name that is used
    532: $    for the object in the HDF5 file. If you wish to store the same vector to the HDF5 viewer (with different values,
    533: $    obviously) several times, you must change its name each time before calling the VecView(). The name you use
    534: $    here should equal the name that you use in the Vec object that you use with VecLoad().

    536:    See the manual page for VecLoad() on the exact format the binary viewer stores
    537:    the values in the file.

    539:    Level: beginner

    541:    Concepts: vector^printing
    542:    Concepts: vector^saving to disk

    544: .seealso: PetscViewerASCIIOpen(), PetscViewerDrawOpen(), PetscDrawLGCreate(),
    545:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), VecLoad(), PetscViewerCreate(),
    546:           PetscRealView(), PetscScalarView(), PetscIntView()
    547: @*/
    548: PetscErrorCode  VecView(Vec vec,PetscViewer viewer)
    549: {
    550:   PetscErrorCode    ierr;
    551:   PetscBool         iascii;
    552:   PetscViewerFormat format;
    553:   PetscMPIInt       size;

    558:   if (!viewer) {
    559:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)vec),&viewer);
    560:   }
    562:   PetscViewerGetFormat(viewer,&format);
    563:   MPI_Comm_size(PetscObjectComm((PetscObject)vec),&size);
    564:   if (size == 1 && format == PETSC_VIEWER_LOAD_BALANCE) return(0);

    566:   if (vec->stash.n || vec->bstash.n) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call VecAssemblyBegin/End() before viewing this vector");

    568:   PetscLogEventBegin(VEC_View,vec,viewer,0,0);
    569:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
    570:   if (iascii) {
    571:     PetscInt rows,bs;

    573:     PetscObjectPrintClassNamePrefixType((PetscObject)vec,viewer);
    574:     if (format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
    575:       PetscViewerASCIIPushTab(viewer);
    576:       VecGetSize(vec,&rows);
    577:       VecGetBlockSize(vec,&bs);
    578:       if (bs != 1) {
    579:         PetscViewerASCIIPrintf(viewer,"length=%D, bs=%D\n",rows,bs);
    580:       } else {
    581:         PetscViewerASCIIPrintf(viewer,"length=%D\n",rows);
    582:       }
    583:       PetscViewerASCIIPopTab(viewer);
    584:     }
    585:   }
    586:   VecLockPush(vec);
    587:   if ((format == PETSC_VIEWER_NATIVE || format == PETSC_VIEWER_LOAD_BALANCE) && vec->ops->viewnative) {
    588:     (*vec->ops->viewnative)(vec,viewer);
    589:   } else {
    590:     (*vec->ops->view)(vec,viewer);
    591:   }
    592:   VecLockPop(vec);
    593:   PetscLogEventEnd(VEC_View,vec,viewer,0,0);
    594:   return(0);
    595: }

    597: #if defined(PETSC_USE_DEBUG)
    598: #include <../src/sys/totalview/tv_data_display.h>
    599: PETSC_UNUSED static int TV_display_type(const struct _p_Vec *v)
    600: {
    601:   const PetscScalar *values;
    602:   char              type[32];
    603:   PetscErrorCode    ierr;

    606:   TV_add_row("Local rows", "int", &v->map->n);
    607:   TV_add_row("Global rows", "int", &v->map->N);
    608:   TV_add_row("Typename", TV_ascii_string_type, ((PetscObject)v)->type_name);
    609:   VecGetArrayRead((Vec)v,&values);
    610:   PetscSNPrintf(type,32,"double[%d]",v->map->n);
    611:   TV_add_row("values",type, values);
    612:   VecRestoreArrayRead((Vec)v,&values);
    613:   return TV_format_OK;
    614: }
    615: #endif

    617: /*@
    618:    VecGetSize - Returns the global number of elements of the vector.

    620:    Not Collective

    622:    Input Parameter:
    623: .  x - the vector

    625:    Output Parameters:
    626: .  size - the global length of the vector

    628:    Level: beginner

    630:    Concepts: vector^local size

    632: .seealso: VecGetLocalSize()
    633: @*/
    634: PetscErrorCode  VecGetSize(Vec x,PetscInt *size)
    635: {

    642:   (*x->ops->getsize)(x,size);
    643:   return(0);
    644: }

    646: /*@
    647:    VecGetLocalSize - Returns the number of elements of the vector stored
    648:    in local memory. This routine may be implementation dependent, so use
    649:    with care.

    651:    Not Collective

    653:    Input Parameter:
    654: .  x - the vector

    656:    Output Parameter:
    657: .  size - the length of the local piece of the vector

    659:    Level: beginner

    661:    Concepts: vector^size

    663: .seealso: VecGetSize()
    664: @*/
    665: PetscErrorCode  VecGetLocalSize(Vec x,PetscInt *size)
    666: {

    673:   (*x->ops->getlocalsize)(x,size);
    674:   return(0);
    675: }

    677: /*@C
    678:    VecGetOwnershipRange - Returns the range of indices owned by
    679:    this processor, assuming that the vectors are laid out with the
    680:    first n1 elements on the first processor, next n2 elements on the
    681:    second, etc.  For certain parallel layouts this range may not be
    682:    well defined.

    684:    Not Collective

    686:    Input Parameter:
    687: .  x - the vector

    689:    Output Parameters:
    690: +  low - the first local element, pass in NULL if not interested
    691: -  high - one more than the last local element, pass in NULL if not interested

    693:    Note:
    694:    The high argument is one more than the last element stored locally.

    696:    Fortran: NULL_INTEGER should be used instead of NULL

    698:    Level: beginner

    700:    Concepts: ownership^of vectors
    701:    Concepts: vector^ownership of elements

    703: .seealso:   MatGetOwnershipRange(), MatGetOwnershipRanges(), VecGetOwnershipRanges()
    704: @*/
    705: PetscErrorCode  VecGetOwnershipRange(Vec x,PetscInt *low,PetscInt *high)
    706: {
    712:   if (low)  *low  = x->map->rstart;
    713:   if (high) *high = x->map->rend;
    714:   return(0);
    715: }

    717: /*@C
    718:    VecGetOwnershipRanges - Returns the range of indices owned by EACH processor,
    719:    assuming that the vectors are laid out with the
    720:    first n1 elements on the first processor, next n2 elements on the
    721:    second, etc.  For certain parallel layouts this range may not be
    722:    well defined.

    724:    Not Collective

    726:    Input Parameter:
    727: .  x - the vector

    729:    Output Parameters:
    730: .  range - array of length size+1 with the start and end+1 for each process

    732:    Note:
    733:    The high argument is one more than the last element stored locally.

    735:    Fortran: You must PASS in an array of length size+1

    737:    Level: beginner

    739:    Concepts: ownership^of vectors
    740:    Concepts: vector^ownership of elements

    742: .seealso:   MatGetOwnershipRange(), MatGetOwnershipRanges(), VecGetOwnershipRange()
    743: @*/
    744: PetscErrorCode  VecGetOwnershipRanges(Vec x,const PetscInt *ranges[])
    745: {

    751:   PetscLayoutGetRanges(x->map,ranges);
    752:   return(0);
    753: }

    755: /*@
    756:    VecSetOption - Sets an option for controling a vector's behavior.

    758:    Collective on Vec

    760:    Input Parameter:
    761: +  x - the vector
    762: .  op - the option
    763: -  flag - turn the option on or off

    765:    Supported Options:
    766: +     VEC_IGNORE_OFF_PROC_ENTRIES, which causes VecSetValues() to ignore
    767:           entries destined to be stored on a separate processor. This can be used
    768:           to eliminate the global reduction in the VecAssemblyXXXX() if you know
    769:           that you have only used VecSetValues() to set local elements
    770: .     VEC_IGNORE_NEGATIVE_INDICES, which means you can pass negative indices
    771:           in ix in calls to VecSetValues() or VecGetValues(). These rows are simply
    772:           ignored.
    773: -     VEC_SUBSET_OFF_PROC_ENTRIES, which causes VecAssemblyBegin() to assume that the off-process
    774:           entries will always be a subset (possibly equal) of the off-process entries set on the
    775:           first assembly.  This reuses the communication pattern, thus avoiding a global reduction.
    776:           Subsequent assemblies setting off-process values should use the same InsertMode as the
    777:           first assembly.

    779:    Developer Note:
    780:    The InsertMode restriction could be removed by packing the stash messages out of place.

    782:    Level: intermediate

    784: @*/
    785: PetscErrorCode  VecSetOption(Vec x,VecOption op,PetscBool flag)
    786: {

    792:   if (x->ops->setoption) {
    793:     (*x->ops->setoption)(x,op,flag);
    794:   }
    795:   return(0);
    796: }

    798: /* Default routines for obtaining and releasing; */
    799: /* may be used by any implementation */
    800: PetscErrorCode VecDuplicateVecs_Default(Vec w,PetscInt m,Vec *V[])
    801: {
    803:   PetscInt       i;

    808:   if (m <= 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"m must be > 0: m = %D",m);
    809:   PetscMalloc1(m,V);
    810:   for (i=0; i<m; i++) {VecDuplicate(w,*V+i);}
    811:   return(0);
    812: }

    814: PetscErrorCode VecDestroyVecs_Default(PetscInt m,Vec v[])
    815: {
    817:   PetscInt       i;

    821:   for (i=0; i<m; i++) {VecDestroy(&v[i]);}
    822:   PetscFree(v);
    823:   return(0);
    824: }

    826: /*@
    827:    VecResetArray - Resets a vector to use its default memory. Call this
    828:    after the use of VecPlaceArray().

    830:    Not Collective

    832:    Input Parameters:
    833: .  vec - the vector

    835:    Level: developer

    837: .seealso: VecGetArray(), VecRestoreArray(), VecReplaceArray(), VecPlaceArray()

    839: @*/
    840: PetscErrorCode  VecResetArray(Vec vec)
    841: {

    847:   if (vec->ops->resetarray) {
    848:     (*vec->ops->resetarray)(vec);
    849:   } else SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SUP,"Cannot reset array in this type of vector");
    850:   PetscObjectStateIncrease((PetscObject)vec);
    851:   return(0);
    852: }

    854: /*@C
    855:   VecLoad - Loads a vector that has been stored in binary or HDF5 format
    856:   with VecView().

    858:   Collective on PetscViewer

    860:   Input Parameters:
    861: + newvec - the newly loaded vector, this needs to have been created with VecCreate() or
    862:            some related function before a call to VecLoad().
    863: - viewer - binary file viewer, obtained from PetscViewerBinaryOpen() or
    864:            HDF5 file viewer, obtained from PetscViewerHDF5Open()

    866:    Level: intermediate

    868:   Notes:
    869:   Defaults to the standard Seq or MPI Vec, if you want some other type of Vec call VecSetFromOptions()
    870:   before calling this.

    872:   The input file must contain the full global vector, as
    873:   written by the routine VecView().

    875:   If the type or size of newvec is not set before a call to VecLoad, PETSc
    876:   sets the type and the local and global sizes. If type and/or
    877:   sizes are already set, then the same are used.

    879:   If using binary and the blocksize of the vector is greater than one then you must provide a unique prefix to
    880:   the vector with PetscObjectSetOptionsPrefix((PetscObject)vec,"uniqueprefix"); BEFORE calling VecView() on the
    881:   vector to be stored and then set that same unique prefix on the vector that you pass to VecLoad(). The blocksize
    882:   information is stored in an ASCII file with the same name as the binary file plus a ".info" appended to the
    883:   filename. If you copy the binary file, make sure you copy the associated .info file with it.

    885:   If using HDF5, you must assign the Vec the same name as was used in the Vec
    886:   that was stored in the file using PetscObjectSetName(). Otherwise you will
    887:   get the error message: "Cannot H5DOpen2() with Vec name NAMEOFOBJECT"

    889:   Notes for advanced users:
    890:   Most users should not need to know the details of the binary storage
    891:   format, since VecLoad() and VecView() completely hide these details.
    892:   But for anyone who's interested, the standard binary vector storage
    893:   format is
    894: .vb
    895:      int    VEC_FILE_CLASSID
    896:      int    number of rows
    897:      PetscScalar *values of all entries
    898: .ve

    900:    In addition, PETSc automatically does the byte swapping for
    901: machines that store the bytes reversed, e.g.  DEC alpha, freebsd,
    902: linux, Windows and the paragon; thus if you write your own binary
    903: read/write routines you have to swap the bytes; see PetscBinaryRead()
    904: and PetscBinaryWrite() to see how this may be done.

    906:   Concepts: vector^loading from file

    908: .seealso: PetscViewerBinaryOpen(), VecView(), MatLoad(), VecLoad()
    909: @*/
    910: PetscErrorCode  VecLoad(Vec newvec, PetscViewer viewer)
    911: {
    912:   PetscErrorCode    ierr;
    913:   PetscBool         isbinary,ishdf5,isadios,isadios2;
    914:   PetscViewerFormat format;

    919:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERBINARY,&isbinary);
    920:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERHDF5,&ishdf5);
    921:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERADIOS,&isadios);
    922:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERADIOS,&isadios2);
    923:   if (!isbinary && !ishdf5 && !isadios && !isadios2) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid viewer; open viewer with PetscViewerBinaryOpen()");

    925:   PetscLogEventBegin(VEC_Load,viewer,0,0,0);
    926:   if (!((PetscObject)newvec)->type_name && !newvec->ops->create) {
    927:     VecSetType(newvec, VECSTANDARD);
    928:   }
    929:   PetscViewerGetFormat(viewer,&format);
    930:   if (format == PETSC_VIEWER_NATIVE && newvec->ops->loadnative) {
    931:     (*newvec->ops->loadnative)(newvec,viewer);
    932:   } else {
    933:     (*newvec->ops->load)(newvec,viewer);
    934:   }
    935:   PetscLogEventEnd(VEC_Load,viewer,0,0,0);
    936:   return(0);
    937: }

    940: /*@
    941:    VecReciprocal - Replaces each component of a vector by its reciprocal.

    943:    Logically Collective on Vec

    945:    Input Parameter:
    946: .  vec - the vector

    948:    Output Parameter:
    949: .  vec - the vector reciprocal

    951:    Level: intermediate

    953:    Concepts: vector^reciprocal

    955: .seealso: VecLog(), VecExp(), VecSqrtAbs()

    957: @*/
    958: PetscErrorCode  VecReciprocal(Vec vec)
    959: {

    965:   if (vec->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
    966:   if (!vec->ops->reciprocal) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SUP,"Vector does not support reciprocal operation");
    967:   (*vec->ops->reciprocal)(vec);
    968:   PetscObjectStateIncrease((PetscObject)vec);
    969:   return(0);
    970: }

    972: /*@C
    973:     VecSetOperation - Allows user to set a vector operation.

    975:    Logically Collective on Vec

    977:     Input Parameters:
    978: +   vec - the vector
    979: .   op - the name of the operation
    980: -   f - the function that provides the operation.

    982:    Level: advanced

    984:     Usage:
    985: $      PetscErrorCode userview(Vec,PetscViewer);
    986: $      VecCreateMPI(comm,m,M,&x);
    987: $      VecSetOperation(x,VECOP_VIEW,(void(*)(void))userview);

    989:     Notes:
    990:     See the file include/petscvec.h for a complete list of matrix
    991:     operations, which all have the form VECOP_<OPERATION>, where
    992:     <OPERATION> is the name (in all capital letters) of the
    993:     user interface routine (e.g., VecView() -> VECOP_VIEW).

    995:     This function is not currently available from Fortran.

    997: .keywords: vector, set, operation

    999: .seealso: VecCreate(), MatShellSetOperation()
    1000: @*/
    1001: PetscErrorCode VecSetOperation(Vec vec,VecOperation op, void (*f)(void))
    1002: {
    1005:   if (op == VECOP_VIEW && !vec->ops->viewnative) {
    1006:     vec->ops->viewnative = vec->ops->view;
    1007:   } else if (op == VECOP_LOAD && !vec->ops->loadnative) {
    1008:     vec->ops->loadnative = vec->ops->load;
    1009:   }
    1010:   (((void(**)(void))vec->ops)[(int)op]) = f;
    1011:   return(0);
    1012: }

    1015: /*@
    1016:    VecStashSetInitialSize - sets the sizes of the vec-stash, that is
    1017:    used during the assembly process to store values that belong to
    1018:    other processors.

    1020:    Not Collective, different processes can have different size stashes

    1022:    Input Parameters:
    1023: +  vec   - the vector
    1024: .  size  - the initial size of the stash.
    1025: -  bsize - the initial size of the block-stash(if used).

    1027:    Options Database Keys:
    1028: +   -vecstash_initial_size <size> or <size0,size1,...sizep-1>
    1029: -   -vecstash_block_initial_size <bsize> or <bsize0,bsize1,...bsizep-1>

    1031:    Level: intermediate

    1033:    Notes:
    1034:      The block-stash is used for values set with VecSetValuesBlocked() while
    1035:      the stash is used for values set with VecSetValues()

    1037:      Run with the option -info and look for output of the form
    1038:      VecAssemblyBegin_MPIXXX:Stash has MM entries, uses nn mallocs.
    1039:      to determine the appropriate value, MM, to use for size and
    1040:      VecAssemblyBegin_MPIXXX:Block-Stash has BMM entries, uses nn mallocs.
    1041:      to determine the value, BMM to use for bsize

    1043:    Concepts: vector^stash
    1044:    Concepts: stash^vector

    1046: .seealso: VecSetBlockSize(), VecSetValues(), VecSetValuesBlocked(), VecStashView()

    1048: @*/
    1049: PetscErrorCode  VecStashSetInitialSize(Vec vec,PetscInt size,PetscInt bsize)
    1050: {

    1055:   VecStashSetInitialSize_Private(&vec->stash,size);
    1056:   VecStashSetInitialSize_Private(&vec->bstash,bsize);
    1057:   return(0);
    1058: }

    1060: /*@
    1061:    VecConjugate - Conjugates a vector.

    1063:    Logically Collective on Vec

    1065:    Input Parameters:
    1066: .  x - the vector

    1068:    Level: intermediate

    1070:    Concepts: vector^conjugate

    1072: @*/
    1073: PetscErrorCode  VecConjugate(Vec x)
    1074: {
    1075: #if defined(PETSC_USE_COMPLEX)

    1081:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
    1082:   (*x->ops->conjugate)(x);
    1083:   /* we need to copy norms here */
    1084:   PetscObjectStateIncrease((PetscObject)x);
    1085:   return(0);
    1086: #else
    1087:   return(0);
    1088: #endif
    1089: }

    1091: /*@
    1092:    VecPointwiseMult - Computes the componentwise multiplication w = x*y.

    1094:    Logically Collective on Vec

    1096:    Input Parameters:
    1097: .  x, y  - the vectors

    1099:    Output Parameter:
    1100: .  w - the result

    1102:    Level: advanced

    1104:    Notes:
    1105:     any subset of the x, y, and w may be the same vector.

    1107:    Concepts: vector^pointwise multiply

    1109: .seealso: VecPointwiseDivide(), VecPointwiseMax(), VecPointwiseMin(), VecPointwiseMaxAbs(), VecMaxPointwiseDivide()
    1110: @*/
    1111: PetscErrorCode  VecPointwiseMult(Vec w, Vec x,Vec y)
    1112: {

    1124:   VecCheckSameSize(w,1,x,2);
    1125:   VecCheckSameSize(w,2,y,3);
    1126:   PetscLogEventBegin(VEC_PointwiseMult,x,y,w,0);
    1127:   (*w->ops->pointwisemult)(w,x,y);
    1128:   PetscLogEventEnd(VEC_PointwiseMult,x,y,w,0);
    1129:   PetscObjectStateIncrease((PetscObject)w);
    1130:   return(0);
    1131: }

    1133: /*@
    1134:    VecSetRandom - Sets all components of a vector to random numbers.

    1136:    Logically Collective on Vec

    1138:    Input Parameters:
    1139: +  x  - the vector
    1140: -  rctx - the random number context, formed by PetscRandomCreate(), or NULL and
    1141:           it will create one internally.

    1143:    Output Parameter:
    1144: .  x  - the vector

    1146:    Example of Usage:
    1147: .vb
    1148:      PetscRandomCreate(PETSC_COMM_WORLD,&rctx);
    1149:      VecSetRandom(x,rctx);
    1150:      PetscRandomDestroy(rctx);
    1151: .ve

    1153:    Level: intermediate

    1155:    Concepts: vector^setting to random
    1156:    Concepts: random^vector

    1158: .seealso: VecSet(), VecSetValues(), PetscRandomCreate(), PetscRandomDestroy()
    1159: @*/
    1160: PetscErrorCode  VecSetRandom(Vec x,PetscRandom rctx)
    1161: {
    1163:   PetscRandom    randObj = NULL;

    1169:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");

    1171:   if (!rctx) {
    1172:     MPI_Comm comm;
    1173:     PetscObjectGetComm((PetscObject)x,&comm);
    1174:     PetscRandomCreate(comm,&randObj);
    1175:     PetscRandomSetFromOptions(randObj);
    1176:     rctx = randObj;
    1177:   }

    1179:   PetscLogEventBegin(VEC_SetRandom,x,rctx,0,0);
    1180:   (*x->ops->setrandom)(x,rctx);
    1181:   PetscLogEventEnd(VEC_SetRandom,x,rctx,0,0);

    1183:   PetscRandomDestroy(&randObj);
    1184:   PetscObjectStateIncrease((PetscObject)x);
    1185:   return(0);
    1186: }

    1188: /*@
    1189:   VecZeroEntries - puts a 0.0 in each element of a vector

    1191:   Logically Collective on Vec

    1193:   Input Parameter:
    1194: . vec - The vector

    1196:   Level: beginner

    1198:   Developer Note: This routine does not need to exist since the exact functionality is obtained with
    1199:      VecSet(vec,0);  I guess someone added it to mirror the functionality of MatZeroEntries() but Mat is nothing
    1200:      like a Vec (one is an operator and one is an element of a vector space, yeah yeah dual blah blah blah) so
    1201:      this routine should not exist.

    1203: .keywords: Vec, set, options, database
    1204: .seealso: VecCreate(),  VecSetOptionsPrefix(), VecSet(), VecSetValues()
    1205: @*/
    1206: PetscErrorCode  VecZeroEntries(Vec vec)
    1207: {

    1211:   VecSet(vec,0);
    1212:   return(0);
    1213: }

    1215: /*
    1216:   VecSetTypeFromOptions_Private - Sets the type of vector from user options. Defaults to a PETSc sequential vector on one
    1217:   processor and a PETSc MPI vector on more than one processor.

    1219:   Collective on Vec

    1221:   Input Parameter:
    1222: . vec - The vector

    1224:   Level: intermediate

    1226: .keywords: Vec, set, options, database, type
    1227: .seealso: VecSetFromOptions(), VecSetType()
    1228: */
    1229: static PetscErrorCode VecSetTypeFromOptions_Private(PetscOptionItems *PetscOptionsObject,Vec vec)
    1230: {
    1231:   PetscBool      opt;
    1232:   VecType        defaultType;
    1233:   char           typeName[256];
    1234:   PetscMPIInt    size;

    1238:   if (((PetscObject)vec)->type_name) defaultType = ((PetscObject)vec)->type_name;
    1239:   else {
    1240:     MPI_Comm_size(PetscObjectComm((PetscObject)vec), &size);
    1241:     if (size > 1) defaultType = VECMPI;
    1242:     else defaultType = VECSEQ;
    1243:   }

    1245:   VecRegisterAll();
    1246:   PetscOptionsFList("-vec_type","Vector type","VecSetType",VecList,defaultType,typeName,256,&opt);
    1247:   if (opt) {
    1248:     VecSetType(vec, typeName);
    1249:   } else {
    1250:     VecSetType(vec, defaultType);
    1251:   }
    1252:   return(0);
    1253: }

    1255: /*@
    1256:   VecSetFromOptions - Configures the vector from the options database.

    1258:   Collective on Vec

    1260:   Input Parameter:
    1261: . vec - The vector

    1263:   Notes:
    1264:     To see all options, run your program with the -help option, or consult the users manual.
    1265:           Must be called after VecCreate() but before the vector is used.

    1267:   Level: beginner

    1269:   Concepts: vectors^setting options
    1270:   Concepts: vectors^setting type

    1272: .keywords: Vec, set, options, database
    1273: .seealso: VecCreate(), VecSetOptionsPrefix()
    1274: @*/
    1275: PetscErrorCode  VecSetFromOptions(Vec vec)
    1276: {

    1282:   PetscObjectOptionsBegin((PetscObject)vec);
    1283:   /* Handle vector type options */
    1284:   VecSetTypeFromOptions_Private(PetscOptionsObject,vec);

    1286:   /* Handle specific vector options */
    1287:   if (vec->ops->setfromoptions) {
    1288:     (*vec->ops->setfromoptions)(PetscOptionsObject,vec);
    1289:   }

    1291:   /* process any options handlers added with PetscObjectAddOptionsHandler() */
    1292:   PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)vec);
    1293:   PetscOptionsEnd();
    1294:   return(0);
    1295: }

    1297: /*@
    1298:   VecSetSizes - Sets the local and global sizes, and checks to determine compatibility

    1300:   Collective on Vec

    1302:   Input Parameters:
    1303: + v - the vector
    1304: . n - the local size (or PETSC_DECIDE to have it set)
    1305: - N - the global size (or PETSC_DECIDE)

    1307:   Notes:
    1308:   n and N cannot be both PETSC_DECIDE
    1309:   If one processor calls this with N of PETSC_DECIDE then all processors must, otherwise the program will hang.

    1311:   Level: intermediate

    1313: .seealso: VecGetSize(), PetscSplitOwnership()
    1314: @*/
    1315: PetscErrorCode  VecSetSizes(Vec v, PetscInt n, PetscInt N)
    1316: {

    1322:   if (N >= 0 && n > N) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Local size %D cannot be larger than global size %D",n,N);
    1323:   if ((v->map->n >= 0 || v->map->N >= 0) && (v->map->n != n || v->map->N != N)) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_SUP,"Cannot change/reset vector sizes to %D local %D global after previously setting them to %D local %D global",n,N,v->map->n,v->map->N);
    1324:   v->map->n = n;
    1325:   v->map->N = N;
    1326:   if (v->ops->create) {
    1327:     (*v->ops->create)(v);
    1328:     v->ops->create = 0;
    1329:   }
    1330:   return(0);
    1331: }

    1333: /*@
    1334:    VecSetBlockSize - Sets the blocksize for future calls to VecSetValuesBlocked()
    1335:    and VecSetValuesBlockedLocal().

    1337:    Logically Collective on Vec

    1339:    Input Parameter:
    1340: +  v - the vector
    1341: -  bs - the blocksize

    1343:    Notes:
    1344:    All vectors obtained by VecDuplicate() inherit the same blocksize.

    1346:    Level: advanced

    1348: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMapping(), VecGetBlockSize()

    1350:   Concepts: block size^vectors
    1351: @*/
    1352: PetscErrorCode  VecSetBlockSize(Vec v,PetscInt bs)
    1353: {

    1358:   if (bs < 0 || bs == v->map->bs) return(0);
    1360:   PetscLayoutSetBlockSize(v->map,bs);
    1361:   v->bstash.bs = bs; /* use the same blocksize for the vec's block-stash */
    1362:   return(0);
    1363: }

    1365: /*@
    1366:    VecGetBlockSize - Gets the blocksize for the vector, i.e. what is used for VecSetValuesBlocked()
    1367:    and VecSetValuesBlockedLocal().

    1369:    Not Collective

    1371:    Input Parameter:
    1372: .  v - the vector

    1374:    Output Parameter:
    1375: .  bs - the blocksize

    1377:    Notes:
    1378:    All vectors obtained by VecDuplicate() inherit the same blocksize.

    1380:    Level: advanced

    1382: .seealso: VecSetValuesBlocked(), VecSetLocalToGlobalMapping(), VecSetBlockSize()

    1384:    Concepts: vector^block size
    1385:    Concepts: block^vector

    1387: @*/
    1388: PetscErrorCode  VecGetBlockSize(Vec v,PetscInt *bs)
    1389: {

    1395:   PetscLayoutGetBlockSize(v->map,bs);
    1396:   return(0);
    1397: }

    1399: /*@C
    1400:    VecSetOptionsPrefix - Sets the prefix used for searching for all
    1401:    Vec options in the database.

    1403:    Logically Collective on Vec

    1405:    Input Parameter:
    1406: +  v - the Vec context
    1407: -  prefix - the prefix to prepend to all option names

    1409:    Notes:
    1410:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    1411:    The first character of all runtime options is AUTOMATICALLY the hyphen.

    1413:    Level: advanced

    1415: .keywords: Vec, set, options, prefix, database

    1417: .seealso: VecSetFromOptions()
    1418: @*/
    1419: PetscErrorCode  VecSetOptionsPrefix(Vec v,const char prefix[])
    1420: {

    1425:   PetscObjectSetOptionsPrefix((PetscObject)v,prefix);
    1426:   return(0);
    1427: }

    1429: /*@C
    1430:    VecAppendOptionsPrefix - Appends to the prefix used for searching for all
    1431:    Vec options in the database.

    1433:    Logically Collective on Vec

    1435:    Input Parameters:
    1436: +  v - the Vec context
    1437: -  prefix - the prefix to prepend to all option names

    1439:    Notes:
    1440:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    1441:    The first character of all runtime options is AUTOMATICALLY the hyphen.

    1443:    Level: advanced

    1445: .keywords: Vec, append, options, prefix, database

    1447: .seealso: VecGetOptionsPrefix()
    1448: @*/
    1449: PetscErrorCode  VecAppendOptionsPrefix(Vec v,const char prefix[])
    1450: {

    1455:   PetscObjectAppendOptionsPrefix((PetscObject)v,prefix);
    1456:   return(0);
    1457: }

    1459: /*@C
    1460:    VecGetOptionsPrefix - Sets the prefix used for searching for all
    1461:    Vec options in the database.

    1463:    Not Collective

    1465:    Input Parameter:
    1466: .  v - the Vec context

    1468:    Output Parameter:
    1469: .  prefix - pointer to the prefix string used

    1471:    Notes:
    1472:     On the fortran side, the user should pass in a string 'prefix' of
    1473:    sufficient length to hold the prefix.

    1475:    Level: advanced

    1477: .keywords: Vec, get, options, prefix, database

    1479: .seealso: VecAppendOptionsPrefix()
    1480: @*/
    1481: PetscErrorCode  VecGetOptionsPrefix(Vec v,const char *prefix[])
    1482: {

    1487:   PetscObjectGetOptionsPrefix((PetscObject)v,prefix);
    1488:   return(0);
    1489: }

    1491: /*@
    1492:    VecSetUp - Sets up the internal vector data structures for the later use.

    1494:    Collective on Vec

    1496:    Input Parameters:
    1497: .  v - the Vec context

    1499:    Notes:
    1500:    For basic use of the Vec classes the user need not explicitly call
    1501:    VecSetUp(), since these actions will happen automatically.

    1503:    Level: advanced

    1505: .keywords: Vec, setup

    1507: .seealso: VecCreate(), VecDestroy()
    1508: @*/
    1509: PetscErrorCode  VecSetUp(Vec v)
    1510: {
    1511:   PetscMPIInt    size;

    1516:   if (!((PetscObject)v)->type_name) {
    1517:     MPI_Comm_size(PetscObjectComm((PetscObject)v), &size);
    1518:     if (size == 1) {
    1519:       VecSetType(v, VECSEQ);
    1520:     } else {
    1521:       VecSetType(v, VECMPI);
    1522:     }
    1523:   }
    1524:   return(0);
    1525: }

    1527: /*
    1528:     These currently expose the PetscScalar/PetscReal in updating the
    1529:     cached norm. If we push those down into the implementation these
    1530:     will become independent of PetscScalar/PetscReal
    1531: */

    1533: /*@
    1534:    VecCopy - Copies a vector. y <- x

    1536:    Logically Collective on Vec

    1538:    Input Parameter:
    1539: .  x - the vector

    1541:    Output Parameter:
    1542: .  y - the copy

    1544:    Notes:
    1545:    For default parallel PETSc vectors, both x and y must be distributed in
    1546:    the same manner; local copies are done.

    1548:    Developer Notes:
    1550:    of the vectors to be sequential and one to be parallel so long as both have the same
    1551:    local sizes. This is used in some internal functions in PETSc.

    1553:    Level: beginner

    1555: .seealso: VecDuplicate()
    1556: @*/
    1557: PetscErrorCode  VecCopy(Vec x,Vec y)
    1558: {
    1559:   PetscBool      flgs[4];
    1560:   PetscReal      norms[4] = {0.0,0.0,0.0,0.0};
    1562:   PetscInt       i;

    1569:   if (x == y) return(0);
    1570:   VecCheckSameLocalSize(x,1,y,2);
    1571:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
    1572:   VecLocked(y,2);

    1574: #if !defined(PETSC_USE_MIXED_PRECISION)
    1575:   for (i=0; i<4; i++) {
    1576:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],norms[i],flgs[i]);
    1577:   }
    1578: #endif

    1580:   PetscLogEventBegin(VEC_Copy,x,y,0,0);
    1581: #if defined(PETSC_USE_MIXED_PRECISION)
    1582:   extern PetscErrorCode VecGetArray(Vec,double**);
    1583:   extern PetscErrorCode VecRestoreArray(Vec,double**);
    1584:   extern PetscErrorCode VecGetArray(Vec,float**);
    1585:   extern PetscErrorCode VecRestoreArray(Vec,float**);
    1586:   extern PetscErrorCode VecGetArrayRead(Vec,const double**);
    1587:   extern PetscErrorCode VecRestoreArrayRead(Vec,const double**);
    1588:   extern PetscErrorCode VecGetArrayRead(Vec,const float**);
    1589:   extern PetscErrorCode VecRestoreArrayRead(Vec,const float**);
    1590:   if ((((PetscObject)x)->precision == PETSC_PRECISION_SINGLE) && (((PetscObject)y)->precision == PETSC_PRECISION_DOUBLE)) {
    1591:     PetscInt    i,n;
    1592:     const float *xx;
    1593:     double      *yy;
    1594:     VecGetArrayRead(x,&xx);
    1595:     VecGetArray(y,&yy);
    1596:     VecGetLocalSize(x,&n);
    1597:     for (i=0; i<n; i++) yy[i] = xx[i];
    1598:     VecRestoreArrayRead(x,&xx);
    1599:     VecRestoreArray(y,&yy);
    1600:   } else if ((((PetscObject)x)->precision == PETSC_PRECISION_DOUBLE) && (((PetscObject)y)->precision == PETSC_PRECISION_SINGLE)) {
    1601:     PetscInt     i,n;
    1602:     float        *yy;
    1603:     const double *xx;
    1604:     VecGetArrayRead(x,&xx);
    1605:     VecGetArray(y,&yy);
    1606:     VecGetLocalSize(x,&n);
    1607:     for (i=0; i<n; i++) yy[i] = (float) xx[i];
    1608:     VecRestoreArrayRead(x,&xx);
    1609:     VecRestoreArray(y,&yy);
    1610:   } else {
    1611:     (*x->ops->copy)(x,y);
    1612:   }
    1613: #else
    1614:   (*x->ops->copy)(x,y);
    1615: #endif

    1617:   PetscObjectStateIncrease((PetscObject)y);
    1618: #if !defined(PETSC_USE_MIXED_PRECISION)
    1619:   for (i=0; i<4; i++) {
    1620:     if (flgs[i]) {
    1621:       PetscObjectComposedDataSetReal((PetscObject)y,NormIds[i],norms[i]);
    1622:     }
    1623:   }
    1624: #endif

    1626:   PetscLogEventEnd(VEC_Copy,x,y,0,0);
    1627:   return(0);
    1628: }

    1630: /*@
    1631:    VecSwap - Swaps the vectors x and y.

    1633:    Logically Collective on Vec

    1635:    Input Parameters:
    1636: .  x, y  - the vectors

    1638:    Level: advanced

    1640:    Concepts: vector^swapping values

    1642: @*/
    1643: PetscErrorCode  VecSwap(Vec x,Vec y)
    1644: {
    1645:   PetscReal      normxs[4]={0.0,0.0,0.0,0.0},normys[4]={0.0,0.0,0.0,0.0};
    1646:   PetscBool      flgxs[4],flgys[4];
    1648:   PetscInt       i;

    1656:   VecCheckSameSize(x,1,y,2);
    1657:   if (x->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");
    1658:   if (y->stash.insertmode != NOT_SET_VALUES) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled vector");

    1660:   PetscLogEventBegin(VEC_Swap,x,y,0,0);
    1661:   for (i=0; i<4; i++) {
    1662:     PetscObjectComposedDataGetReal((PetscObject)x,NormIds[i],normxs[i],flgxs[i]);
    1663:     PetscObjectComposedDataGetReal((PetscObject)y,NormIds[i],normys[i],flgys[i]);
    1664:   }
    1665:   (*x->ops->swap)(x,y);
    1666:   PetscObjectStateIncrease((PetscObject)x);
    1667:   PetscObjectStateIncrease((PetscObject)y);
    1668:   for (i=0; i<4; i++) {
    1669:     if (flgxs[i]) {
    1670:       PetscObjectComposedDataSetReal((PetscObject)y,NormIds[i],normxs[i]);
    1671:     }
    1672:     if (flgys[i]) {
    1673:       PetscObjectComposedDataSetReal((PetscObject)x,NormIds[i],normys[i]);
    1674:     }
    1675:   }
    1676:   PetscLogEventEnd(VEC_Swap,x,y,0,0);
    1677:   return(0);
    1678: }

    1680: /*
    1681:   VecStashViewFromOptions - Processes command line options to determine if/how an VecStash object is to be viewed.

    1683:   Collective on VecStash

    1685:   Input Parameters:
    1686: + obj   - the VecStash object
    1687: . bobj - optional other object that provides the prefix
    1688: - optionname - option to activate viewing

    1690:   Level: intermediate

    1692:   Developer Note: This cannot use PetscObjectViewFromOptions() because it takes a Vec as an argument but does not use VecView

    1694: */
    1695: PetscErrorCode VecStashViewFromOptions(Vec obj,PetscObject bobj,const char optionname[])
    1696: {
    1697:   PetscErrorCode    ierr;
    1698:   PetscViewer       viewer;
    1699:   PetscBool         flg;
    1700:   PetscViewerFormat format;
    1701:   char              *prefix;

    1704:   prefix = bobj ? bobj->prefix : ((PetscObject)obj)->prefix;
    1705:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)obj),prefix,optionname,&viewer,&format,&flg);
    1706:   if (flg) {
    1707:     PetscViewerPushFormat(viewer,format);
    1708:     VecStashView(obj,viewer);
    1709:     PetscViewerPopFormat(viewer);
    1710:     PetscViewerDestroy(&viewer);
    1711:   }
    1712:   return(0);
    1713: }

    1715: /*@
    1716:    VecStashView - Prints the entries in the vector stash and block stash.

    1718:    Collective on Vec

    1720:    Input Parameters:
    1721: +  v - the vector
    1722: -  viewer - the viewer

    1724:    Level: advanced

    1726:    Concepts: vector^stash
    1727:    Concepts: stash^vector

    1729: .seealso: VecSetBlockSize(), VecSetValues(), VecSetValuesBlocked()

    1731: @*/
    1732: PetscErrorCode  VecStashView(Vec v,PetscViewer viewer)
    1733: {
    1735:   PetscMPIInt    rank;
    1736:   PetscInt       i,j;
    1737:   PetscBool      match;
    1738:   VecStash       *s;
    1739:   PetscScalar    val;

    1746:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&match);
    1747:   if (!match) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Stash viewer only works with ASCII viewer not %s\n",((PetscObject)v)->type_name);
    1748:   PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
    1749:   MPI_Comm_rank(PetscObjectComm((PetscObject)v),&rank);
    1750:   s    = &v->bstash;

    1752:   /* print block stash */
    1753:   PetscViewerASCIIPushSynchronized(viewer);
    1754:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector Block stash size %D block size %D\n",rank,s->n,s->bs);
    1755:   for (i=0; i<s->n; i++) {
    1756:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D ",rank,s->idx[i]);
    1757:     for (j=0; j<s->bs; j++) {
    1758:       val = s->array[i*s->bs+j];
    1759: #if defined(PETSC_USE_COMPLEX)
    1760:       PetscViewerASCIISynchronizedPrintf(viewer,"(%18.16e %18.16e) ",PetscRealPart(val),PetscImaginaryPart(val));
    1761: #else
    1762:       PetscViewerASCIISynchronizedPrintf(viewer,"%18.16e ",val);
    1763: #endif
    1764:     }
    1765:     PetscViewerASCIISynchronizedPrintf(viewer,"\n");
    1766:   }
    1767:   PetscViewerFlush(viewer);

    1769:   s = &v->stash;

    1771:   /* print basic stash */
    1772:   PetscViewerASCIISynchronizedPrintf(viewer,"[%d]Vector stash size %D\n",rank,s->n);
    1773:   for (i=0; i<s->n; i++) {
    1774:     val = s->array[i];
    1775: #if defined(PETSC_USE_COMPLEX)
    1776:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D (%18.16e %18.16e) ",rank,s->idx[i],PetscRealPart(val),PetscImaginaryPart(val));
    1777: #else
    1778:     PetscViewerASCIISynchronizedPrintf(viewer,"[%d] Element %D %18.16e\n",rank,s->idx[i],val);
    1779: #endif
    1780:   }
    1781:   PetscViewerFlush(viewer);
    1782:   PetscViewerASCIIPopSynchronized(viewer);
    1783:   PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
    1784:   return(0);
    1785: }

    1787: PetscErrorCode PetscOptionsGetVec(PetscOptions options,const char prefix[],const char key[],Vec v,PetscBool *set)
    1788: {
    1789:   PetscInt       i,N,rstart,rend;
    1791:   PetscScalar    *xx;
    1792:   PetscReal      *xreal;
    1793:   PetscBool      iset;

    1796:   VecGetOwnershipRange(v,&rstart,&rend);
    1797:   VecGetSize(v,&N);
    1798:   PetscCalloc1(N,&xreal);
    1799:   PetscOptionsGetRealArray(options,prefix,key,xreal,&N,&iset);
    1800:   if (iset) {
    1801:     VecGetArray(v,&xx);
    1802:     for (i=rstart; i<rend; i++) xx[i-rstart] = xreal[i];
    1803:     VecRestoreArray(v,&xx);
    1804:   }
    1805:   PetscFree(xreal);
    1806:   if (set) *set = iset;
    1807:   return(0);
    1808: }

    1810: /*@
    1811:    VecGetLayout - get PetscLayout describing vector layout

    1813:    Not Collective

    1815:    Input Arguments:
    1816: .  x - the vector

    1818:    Output Arguments:
    1819: .  map - the layout

    1821:    Level: developer

    1823: .seealso: VecGetSizes(), VecGetOwnershipRange(), VecGetOwnershipRanges()
    1824: @*/
    1825: PetscErrorCode VecGetLayout(Vec x,PetscLayout *map)
    1826: {

    1830:   *map = x->map;
    1831:   return(0);
    1832: }

    1834: /*@
    1835:    VecSetLayout - set PetscLayout describing vector layout

    1837:    Not Collective

    1839:    Input Arguments:
    1840: +  x - the vector
    1841: -  map - the layout

    1843:    Notes:
    1844:    It is normally only valid to replace the layout with a layout known to be equivalent.

    1846:    Level: developer

    1848: .seealso: VecGetLayout(), VecGetSizes(), VecGetOwnershipRange(), VecGetOwnershipRanges()
    1849: @*/
    1850: PetscErrorCode VecSetLayout(Vec x,PetscLayout map)
    1851: {

    1856:   PetscLayoutReference(map,&x->map);
    1857:   return(0);
    1858: }

    1860: PetscErrorCode VecSetInf(Vec xin)
    1861: {
    1862:   PetscInt       i,n = xin->map->n;
    1863:   PetscScalar    *xx;
    1864:   PetscScalar    zero=0.0,one=1.0,inf=one/zero;

    1868:   VecGetArray(xin,&xx);
    1869:   for (i=0; i<n; i++) xx[i] = inf;
    1870:   VecRestoreArray(xin,&xx);
    1871:   return(0);
    1872: }