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: 19*fcc3cf91SStefano Zampini 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 21*fcc3cf91SStefano Zampini all printed before the output from the second viewer. You must call `PetscViewerFlush()` on 22*fcc3cf91SStefano Zampini `viewer` after 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*fcc3cf91SStefano Zampini `PetscViewerFlush()` on the subviewer 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 35fe8fb074SBarry Smith For `PETSCVIEWERASCII` the viewers behavior is as follows\: 36fe8fb074SBarry Smith .vb 37fe8fb074SBarry Smith Recursive calls are allowed 38fe8fb074SBarry Smith A call to `PetscViewerASCIIPrintf()` on a subviewer results in output for the first MPI process in the `outviewer` only 39fe8fb074SBarry Smith Calls to `PetscViewerASCIIPrintf()` and `PetscViewerASCIISynchronizedPrintf()` are immediately passed up through all 40fe8fb074SBarry Smith the parent viewers to the higher most parent with `PetscViewerASCIISynchronizedPrintf()` where they are immediately 41fe8fb074SBarry Smith printed on the first MPI process or stashed on the other processes. 42fe8fb074SBarry Smith At the higher most `PetscViewerRestoreSubViewer()` the viewer is automatically flushed with `PetscViewerFlush()` 43fe8fb074SBarry Smith .ve 44fe8fb074SBarry 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 50fe8fb074SBarry Smith .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, 51fe8fb074SBarry 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 74fe8fb074SBarry Smith Note: 75*fcc3cf91SStefano Zampini Automatically runs `PetscViewerFlush()` on `outviewer` 76fe8fb074SBarry Smith 77fe8fb074SBarry Smith .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, `PetscViewerGetSubViewer()`, 78fe8fb074SBarry 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