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 21*b4025f61SBarry 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*b4025f61SBarry Smith `PetscViewerFlush()` is run automatically at the begining of `PetscViewerGetSubViewer()` and with `PetscViewerRestoreSubViewer()` 30*b4025f61SBarry 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 35*b4025f61SBarry Smith Must be called by all MPI processes that share `viewer`, for processes that are not of interest you can pass 36*b4025f61SBarry Smith `PETSC_COMM_SELF`. 37*b4025f61SBarry 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 53*b4025f61SBarry Smith Complex use of this functionality with `PETSCVIEWERASCII` can result in output in unexpected order. This seems unavoidable. 54*b4025f61SBarry 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 79*b4025f61SBarry Smith Notes: 80fcc3cf91SStefano Zampini Automatically runs `PetscViewerFlush()` on `outviewer` 81fe8fb074SBarry Smith 82*b4025f61SBarry Smith Must be called by all MPI processes that share `viewer`, for processes that are not of interest you can pass 83*b4025f61SBarry Smith `PETSC_COMM_SELF`. 84*b4025f61SBarry 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