15c6c1daeSBarry Smith 2af0996ceSBarry Smith #include <petsc/private/viewerimpl.h> /*I "petscviewer.h" I*/ 35c6c1daeSBarry Smith 4b3fa1ec5SBarry Smith /*@C 5811af0c4SBarry Smith PetscViewerGetSubViewer - Creates a new `PetscViewer` (same type as the old) 6c410d8ccSBarry Smith that lives on a subcommunicator of the original viewer's communicator 75c6c1daeSBarry Smith 8c3339decSBarry Smith Collective 95c6c1daeSBarry Smith 10*10450e9eSJacob Faibussowitsch Input Parameters: 11*10450e9eSJacob Faibussowitsch + viewer - the `PetscViewer` to be reproduced 12*10450e9eSJacob Faibussowitsch - comm - the sub communicator to use 135c6c1daeSBarry Smith 145c6c1daeSBarry Smith Output Parameter: 15811af0c4SBarry Smith . outviewer - new `PetscViewer` 165c6c1daeSBarry Smith 175c6c1daeSBarry Smith Level: advanced 185c6c1daeSBarry Smith 1995452b02SPatrick Sanan Notes: 20a62913d3SBarry Smith The output of the subviewers is synchronized against the original viewer. For example, if a 21c410d8ccSBarry Smith viewer on two MPI processes is decomposed into two subviewers, the output from the first viewer is 22811af0c4SBarry Smith all printed before the output from the second viewer. You must call `PetscViewerFlush()` after 23811af0c4SBarry Smith the call to `PetscViewerRestoreSubViewer()`. 24a62913d3SBarry Smith 25811af0c4SBarry Smith Call `PetscViewerRestoreSubViewer()` to destroy this `PetscViewer`, NOT `PetscViewerDestroy()` 265c6c1daeSBarry Smith 275c6c1daeSBarry Smith This is most commonly used to view a sequential object that is part of a 28811af0c4SBarry Smith parallel object. For example `PCView()` on a `PCBJACOBI` could use this to obtain a 29811af0c4SBarry Smith `PetscViewer` that is used with the sequential `KSP` on one block of the preconditioner. 305c6c1daeSBarry Smith 31811af0c4SBarry Smith Between the calls to `PetscViewerGetSubViewer()` and `PetscViewerRestoreSubViewer()` the original 32e5afcf28SBarry Smith viewer should not be used 33e5afcf28SBarry Smith 34c410d8ccSBarry Smith `PETSCVIEWERDRAW` and `PETSCVIEWERBINARY` only support returning a singleton viewer on MPI rank 0, 35c410d8ccSBarry Smith all other ranks will return a `NULL` viewer 36e5afcf28SBarry Smith 37e5afcf28SBarry Smith Developer Notes: 38c410d8ccSBarry Smith There is currently incomplete error checking to ensure the user does not use the original viewer between the 39811af0c4SBarry Smith the calls to `PetscViewerGetSubViewer()` and `PetscViewerRestoreSubViewer()`. If the user does there 40e5afcf28SBarry Smith could be errors in the viewing that go undetected or crash the code. 41e5afcf28SBarry Smith 42811af0c4SBarry Smith It would be nice if the call to `PetscViewerFlush()` was not required and was handled by 43811af0c4SBarry Smith `PetscViewerRestoreSubViewer()` 44a62913d3SBarry Smith 45c410d8ccSBarry Smith .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, `PetscViewerRestoreSubViewer()` 465c6c1daeSBarry Smith @*/ 47d71ae5a4SJacob Faibussowitsch PetscErrorCode PetscViewerGetSubViewer(PetscViewer viewer, MPI_Comm comm, PetscViewer *outviewer) 48d71ae5a4SJacob Faibussowitsch { 495c6c1daeSBarry Smith PetscFunctionBegin; 505c6c1daeSBarry Smith PetscValidHeaderSpecific(viewer, PETSC_VIEWER_CLASSID, 1); 51064a246eSJacob Faibussowitsch PetscValidPointer(outviewer, 3); 52dbbe0bcdSBarry Smith PetscUseTypeMethod(viewer, getsubviewer, comm, outviewer); 533ba16761SJacob Faibussowitsch PetscFunctionReturn(PETSC_SUCCESS); 545c6c1daeSBarry Smith } 555c6c1daeSBarry Smith 56b3fa1ec5SBarry Smith /*@C 57c410d8ccSBarry Smith PetscViewerRestoreSubViewer - Restores a `PetscViewer` obtained with `PetscViewerGetSubViewer()`. 585c6c1daeSBarry Smith 59c3339decSBarry Smith Collective 605c6c1daeSBarry Smith 615c6c1daeSBarry Smith Input Parameters: 62811af0c4SBarry Smith + viewer - the `PetscViewer` that was reproduced 63*10450e9eSJacob Faibussowitsch . comm - the sub communicator 64c410d8ccSBarry Smith - outviewer - the subviewer to be returned 655c6c1daeSBarry Smith 665c6c1daeSBarry Smith Level: advanced 675c6c1daeSBarry Smith 68c410d8ccSBarry Smith .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, `PetscViewerGetSubViewer()` 695c6c1daeSBarry Smith @*/ 70d71ae5a4SJacob Faibussowitsch PetscErrorCode PetscViewerRestoreSubViewer(PetscViewer viewer, MPI_Comm comm, PetscViewer *outviewer) 71d71ae5a4SJacob Faibussowitsch { 725c6c1daeSBarry Smith PetscFunctionBegin; 735c6c1daeSBarry Smith PetscValidHeaderSpecific(viewer, PETSC_VIEWER_CLASSID, 1); 74ffc4695bSBarry Smith 75dbbe0bcdSBarry Smith PetscUseTypeMethod(viewer, restoresubviewer, comm, outviewer); 763ba16761SJacob Faibussowitsch PetscFunctionReturn(PETSC_SUCCESS); 775c6c1daeSBarry Smith } 78