1af0996ceSBarry Smith #include <petsc/private/viewerimpl.h> /*I "petscviewer.h" I*/ 25c6c1daeSBarry Smith 3b3fa1ec5SBarry Smith /*@C 4811af0c4SBarry Smith PetscViewerGetSubViewer - Creates a new `PetscViewer` (same type as the old) 5c410d8ccSBarry Smith that lives on a subcommunicator of the original viewer's communicator 65c6c1daeSBarry Smith 7c3339decSBarry Smith Collective 85c6c1daeSBarry Smith 910450e9eSJacob Faibussowitsch Input Parameters: 1010450e9eSJacob Faibussowitsch + viewer - the `PetscViewer` to be reproduced 1110450e9eSJacob Faibussowitsch - comm - the sub communicator to use 125c6c1daeSBarry Smith 135c6c1daeSBarry Smith Output Parameter: 14811af0c4SBarry Smith . outviewer - new `PetscViewer` 155c6c1daeSBarry Smith 165c6c1daeSBarry Smith Level: advanced 175c6c1daeSBarry Smith 1895452b02SPatrick Sanan Notes: 19a62913d3SBarry Smith The output of the subviewers is synchronized against the original viewer. For example, if a 20c410d8ccSBarry Smith viewer on two MPI processes is decomposed into two subviewers, the output from the first viewer is 21811af0c4SBarry Smith all printed before the output from the second viewer. You must call `PetscViewerFlush()` after 22811af0c4SBarry Smith the call to `PetscViewerRestoreSubViewer()`. 23a62913d3SBarry Smith 24811af0c4SBarry Smith Call `PetscViewerRestoreSubViewer()` to destroy this `PetscViewer`, NOT `PetscViewerDestroy()` 255c6c1daeSBarry Smith 265c6c1daeSBarry Smith This is most commonly used to view a sequential object that is part of a 27811af0c4SBarry Smith parallel object. For example `PCView()` on a `PCBJACOBI` could use this to obtain a 28811af0c4SBarry Smith `PetscViewer` that is used with the sequential `KSP` on one block of the preconditioner. 295c6c1daeSBarry Smith 30*fe8fb074SBarry Smith `PetscViewerFlush()` is run automatically with `PetscViewerRestoreSubViewer()` 31e5afcf28SBarry Smith 32c410d8ccSBarry Smith `PETSCVIEWERDRAW` and `PETSCVIEWERBINARY` only support returning a singleton viewer on MPI rank 0, 33c410d8ccSBarry Smith all other ranks will return a `NULL` viewer 34e5afcf28SBarry Smith 35*fe8fb074SBarry Smith For `PETSCVIEWERASCII` the viewers behavior is as follows\: 36*fe8fb074SBarry Smith .vb 37*fe8fb074SBarry Smith Recursive calls are allowed 38*fe8fb074SBarry Smith A call to `PetscViewerASCIIPrintf()` on a subviewer results in output for the first MPI process in the `outviewer` only 39*fe8fb074SBarry Smith Calls to `PetscViewerASCIIPrintf()` and `PetscViewerASCIISynchronizedPrintf()` are immediately passed up through all 40*fe8fb074SBarry Smith the parent viewers to the higher most parent with `PetscViewerASCIISynchronizedPrintf()` where they are immediately 41*fe8fb074SBarry Smith printed on the first MPI process or stashed on the other processes. 42*fe8fb074SBarry Smith At the higher most `PetscViewerRestoreSubViewer()` the viewer is automatically flushed with `PetscViewerFlush()` 43*fe8fb074SBarry Smith .ve 44*fe8fb074SBarry Smith 45e5afcf28SBarry Smith Developer Notes: 46c410d8ccSBarry Smith There is currently incomplete error checking to ensure the user does not use the original viewer between the 47811af0c4SBarry Smith the calls to `PetscViewerGetSubViewer()` and `PetscViewerRestoreSubViewer()`. If the user does there 48e5afcf28SBarry Smith could be errors in the viewing that go undetected or crash the code. 49e5afcf28SBarry Smith 50*fe8fb074SBarry Smith .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, 51*fe8fb074SBarry Smith `PetscViewerFlush()`, `PetscViewerRestoreSubViewer()` 525c6c1daeSBarry Smith @*/ 53d71ae5a4SJacob Faibussowitsch PetscErrorCode PetscViewerGetSubViewer(PetscViewer viewer, MPI_Comm comm, PetscViewer *outviewer) 54d71ae5a4SJacob Faibussowitsch { 555c6c1daeSBarry Smith PetscFunctionBegin; 565c6c1daeSBarry Smith PetscValidHeaderSpecific(viewer, PETSC_VIEWER_CLASSID, 1); 574f572ea9SToby Isaac PetscAssertPointer(outviewer, 3); 58dbbe0bcdSBarry Smith PetscUseTypeMethod(viewer, getsubviewer, comm, outviewer); 593ba16761SJacob Faibussowitsch PetscFunctionReturn(PETSC_SUCCESS); 605c6c1daeSBarry Smith } 615c6c1daeSBarry Smith 62b3fa1ec5SBarry Smith /*@C 63c410d8ccSBarry Smith PetscViewerRestoreSubViewer - Restores a `PetscViewer` obtained with `PetscViewerGetSubViewer()`. 645c6c1daeSBarry Smith 65c3339decSBarry Smith Collective 665c6c1daeSBarry Smith 675c6c1daeSBarry Smith Input Parameters: 68811af0c4SBarry Smith + viewer - the `PetscViewer` that was reproduced 6910450e9eSJacob Faibussowitsch . comm - the sub communicator 70c410d8ccSBarry Smith - outviewer - the subviewer to be returned 715c6c1daeSBarry Smith 725c6c1daeSBarry Smith Level: advanced 735c6c1daeSBarry Smith 74*fe8fb074SBarry Smith Note: 75*fe8fb074SBarry Smith Automatically runs `PetscViewerFlush()` on the outter viewer 76*fe8fb074SBarry Smith 77*fe8fb074SBarry Smith .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, `PetscViewerGetSubViewer()`, 78*fe8fb074SBarry Smith `PetscViewerFlush()` 795c6c1daeSBarry Smith @*/ 80d71ae5a4SJacob Faibussowitsch PetscErrorCode PetscViewerRestoreSubViewer(PetscViewer viewer, MPI_Comm comm, PetscViewer *outviewer) 81d71ae5a4SJacob Faibussowitsch { 825c6c1daeSBarry Smith PetscFunctionBegin; 835c6c1daeSBarry Smith PetscValidHeaderSpecific(viewer, PETSC_VIEWER_CLASSID, 1); 84ffc4695bSBarry Smith 85dbbe0bcdSBarry Smith PetscUseTypeMethod(viewer, restoresubviewer, comm, outviewer); 863ba16761SJacob Faibussowitsch PetscFunctionReturn(PETSC_SUCCESS); 875c6c1daeSBarry Smith } 88