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: 19fcc3cf91SStefano 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 21b4025f61SBarry Smith all printed before the output from the second viewer. 22a62913d3SBarry Smith 23811af0c4SBarry Smith Call `PetscViewerRestoreSubViewer()` to destroy this `PetscViewer`, NOT `PetscViewerDestroy()` 245c6c1daeSBarry Smith 255c6c1daeSBarry Smith This is most commonly used to view a sequential object that is part of a 26811af0c4SBarry Smith parallel object. For example `PCView()` on a `PCBJACOBI` could use this to obtain a 27811af0c4SBarry Smith `PetscViewer` that is used with the sequential `KSP` on one block of the preconditioner. 285c6c1daeSBarry Smith 29*d8b4a066SPierre Jolivet `PetscViewerFlush()` is run automatically at the beginning of `PetscViewerGetSubViewer()` and with `PetscViewerRestoreSubViewer()` 30b4025f61SBarry Smith for `PETSCVIEWERASCII` 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 35b4025f61SBarry Smith Must be called by all MPI processes that share `viewer`, for processes that are not of interest you can pass 36b4025f61SBarry Smith `PETSC_COMM_SELF`. 37b4025f61SBarry Smith 38fe8fb074SBarry Smith For `PETSCVIEWERASCII` the viewers behavior is as follows\: 39fe8fb074SBarry Smith .vb 40fe8fb074SBarry Smith Recursive calls are allowed 41fe8fb074SBarry Smith A call to `PetscViewerASCIIPrintf()` on a subviewer results in output for the first MPI process in the `outviewer` only 42fe8fb074SBarry Smith Calls to `PetscViewerASCIIPrintf()` and `PetscViewerASCIISynchronizedPrintf()` are immediately passed up through all 43fe8fb074SBarry Smith the parent viewers to the higher most parent with `PetscViewerASCIISynchronizedPrintf()` where they are immediately 44fe8fb074SBarry Smith printed on the first MPI process or stashed on the other processes. 45fe8fb074SBarry Smith At the higher most `PetscViewerRestoreSubViewer()` the viewer is automatically flushed with `PetscViewerFlush()` 46fe8fb074SBarry Smith .ve 47fe8fb074SBarry Smith 48e5afcf28SBarry Smith Developer Notes: 49c410d8ccSBarry Smith There is currently incomplete error checking to ensure the user does not use the original viewer between the 50811af0c4SBarry Smith the calls to `PetscViewerGetSubViewer()` and `PetscViewerRestoreSubViewer()`. If the user does there 51e5afcf28SBarry Smith could be errors in the viewing that go undetected or crash the code. 52e5afcf28SBarry Smith 53b4025f61SBarry Smith Complex use of this functionality with `PETSCVIEWERASCII` can result in output in unexpected order. This seems unavoidable. 54b4025f61SBarry Smith 55fe8fb074SBarry Smith .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, 56fe8fb074SBarry Smith `PetscViewerFlush()`, `PetscViewerRestoreSubViewer()` 575c6c1daeSBarry Smith @*/ 58d71ae5a4SJacob Faibussowitsch PetscErrorCode PetscViewerGetSubViewer(PetscViewer viewer, MPI_Comm comm, PetscViewer *outviewer) 59d71ae5a4SJacob Faibussowitsch { 605c6c1daeSBarry Smith PetscFunctionBegin; 615c6c1daeSBarry Smith PetscValidHeaderSpecific(viewer, PETSC_VIEWER_CLASSID, 1); 624f572ea9SToby Isaac PetscAssertPointer(outviewer, 3); 63dbbe0bcdSBarry Smith PetscUseTypeMethod(viewer, getsubviewer, comm, outviewer); 643ba16761SJacob Faibussowitsch PetscFunctionReturn(PETSC_SUCCESS); 655c6c1daeSBarry Smith } 665c6c1daeSBarry Smith 67b3fa1ec5SBarry Smith /*@C 68c410d8ccSBarry Smith PetscViewerRestoreSubViewer - Restores a `PetscViewer` obtained with `PetscViewerGetSubViewer()`. 695c6c1daeSBarry Smith 70c3339decSBarry Smith Collective 715c6c1daeSBarry Smith 725c6c1daeSBarry Smith Input Parameters: 73811af0c4SBarry Smith + viewer - the `PetscViewer` that was reproduced 7410450e9eSJacob Faibussowitsch . comm - the sub communicator 75c410d8ccSBarry Smith - outviewer - the subviewer to be returned 765c6c1daeSBarry Smith 775c6c1daeSBarry Smith Level: advanced 785c6c1daeSBarry Smith 79b4025f61SBarry Smith Notes: 80fcc3cf91SStefano Zampini Automatically runs `PetscViewerFlush()` on `outviewer` 81fe8fb074SBarry Smith 82b4025f61SBarry Smith Must be called by all MPI processes that share `viewer`, for processes that are not of interest you can pass 83b4025f61SBarry Smith `PETSC_COMM_SELF`. 84b4025f61SBarry Smith 85fe8fb074SBarry Smith .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, `PetscViewerGetSubViewer()`, 86fe8fb074SBarry Smith `PetscViewerFlush()` 875c6c1daeSBarry Smith @*/ 88d71ae5a4SJacob Faibussowitsch PetscErrorCode PetscViewerRestoreSubViewer(PetscViewer viewer, MPI_Comm comm, PetscViewer *outviewer) 89d71ae5a4SJacob Faibussowitsch { 905c6c1daeSBarry Smith PetscFunctionBegin; 915c6c1daeSBarry Smith PetscValidHeaderSpecific(viewer, PETSC_VIEWER_CLASSID, 1); 92ffc4695bSBarry Smith 93dbbe0bcdSBarry Smith PetscUseTypeMethod(viewer, restoresubviewer, comm, outviewer); 943ba16761SJacob Faibussowitsch PetscFunctionReturn(PETSC_SUCCESS); 955c6c1daeSBarry Smith } 96