1 /* 2 Provides utility routines for manulating any type of PETSc object. 3 */ 4 #include <petsc/private/petscimpl.h> /*I "petscsys.h" I*/ 5 6 /*@C 7 PetscObjectComm - Gets the MPI communicator for any `PetscObject` regardless of the type. 8 9 Not Collective 10 11 Input Parameter: 12 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. It must be 13 cast with a (`PetscObject`), for example, `PetscObjectComm`((`PetscObject`)mat,...); 14 15 Level: advanced 16 17 Note: 18 Returns the MPI communicator or `MPI_COMM_NULL` if `obj` is not valid. 19 20 This is one of the rare PETSc routines that does not return an error code. Use `PetscObjectGetComm()` 21 when appropriate for error handling. 22 23 .seealso: `PetscObject`, `PetscObjectGetComm()` 24 @*/ 25 MPI_Comm PetscObjectComm(PetscObject obj) 26 { 27 return obj ? obj->comm : MPI_COMM_NULL; 28 } 29 30 /*@C 31 PetscObjectGetComm - Gets the MPI communicator for any `PetscObject` regardless of the type. 32 33 Not Collective 34 35 Input Parameter: 36 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. It must be cast with a (`PetscObject`), for example, 37 `PetscObjectGetComm`((`PetscObject`)mat,&comm); 38 39 Output Parameter: 40 . comm - the MPI communicator 41 42 Level: advanced 43 44 .seealso: `PetscObject`, `PetscObjectComm()` 45 @*/ 46 PetscErrorCode PetscObjectGetComm(PetscObject obj, MPI_Comm *comm) 47 { 48 PetscFunctionBegin; 49 PetscValidHeader(obj, 1); 50 PetscAssertPointer(comm, 2); 51 *comm = obj->comm; 52 PetscFunctionReturn(PETSC_SUCCESS); 53 } 54 55 /*@ 56 PetscObjectGetTabLevel - Gets the number of tabs that `PETSCVIEWERASCII` output for that object uses 57 58 Not Collective 59 60 Input Parameter: 61 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. It must be cast with a (`PetscObject`), for example, 62 `PetscObjectGetTabLevel`((`PetscObject`)mat,&tab); 63 64 Output Parameter: 65 . tab - the number of tabs 66 67 Level: developer 68 69 Note: 70 This is used to manage the output from options that are embedded in other objects. For example 71 the `KSP` object inside a `SNES` object. By indenting each lower level further the hierarchy of objects 72 is clear. 73 74 .seealso: `PetscObjectIncrementTabLevel()`, `PetscObjectSetTabLevel()`, `PETSCVIEWERASCII`, `PetscObject` 75 @*/ 76 PetscErrorCode PetscObjectGetTabLevel(PetscObject obj, PetscInt *tab) 77 { 78 PetscFunctionBegin; 79 PetscValidHeader(obj, 1); 80 PetscAssertPointer(tab, 2); 81 *tab = obj->tablevel; 82 PetscFunctionReturn(PETSC_SUCCESS); 83 } 84 85 /*@ 86 PetscObjectSetTabLevel - Sets the number of tabs that `PETSCVIEWERASCII` output for that object uses 87 88 Not Collective 89 90 Input Parameters: 91 + obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. It must be cast with a (`PetscObject`), for example, 92 `PetscObjectSetTabLevel`((`PetscObject`)mat,tab; 93 - tab - the number of tabs 94 95 Level: developer 96 97 Notes: 98 this is used to manage the output from options that are embedded in other objects. For example 99 the `KSP` object inside a `SNES` object. By indenting each lower level further the hierarchy of objects 100 is clear. 101 102 `PetscObjectIncrementTabLevel()` is the preferred API 103 104 .seealso: `PetscObjectIncrementTabLevel()`, `PetscObjectGetTabLevel()` 105 @*/ 106 PetscErrorCode PetscObjectSetTabLevel(PetscObject obj, PetscInt tab) 107 { 108 PetscFunctionBegin; 109 PetscValidHeader(obj, 1); 110 obj->tablevel = tab; 111 PetscFunctionReturn(PETSC_SUCCESS); 112 } 113 114 /*@ 115 PetscObjectIncrementTabLevel - Increments the number of tabs that `PETSCVIEWERASCII` output for that object use based on 116 the tablevel of another object. This should be called immediately after the object is created. 117 118 Not Collective 119 120 Input Parameters: 121 + obj - any PETSc object where we are changing the tab 122 . oldobj - the object providing the tab, optional pass `NULL` to use 0 as the previous tablevel for `obj` 123 - tab - the increment that is added to the old objects tab 124 125 Level: developer 126 127 Note: 128 this is used to manage the output from options that are embedded in other objects. For example 129 the `KSP` object inside a `SNES` object. By indenting each lower level further the hierarchy of objects 130 is clear. 131 132 .seealso: `PETSCVIEWERASCII`, `PetscObjectSetTabLevel()`, `PetscObjectGetTabLevel()` 133 @*/ 134 PetscErrorCode PetscObjectIncrementTabLevel(PetscObject obj, PetscObject oldobj, PetscInt tab) 135 { 136 PetscFunctionBegin; 137 PetscValidHeader(obj, 1); 138 if (oldobj) PetscValidHeader(oldobj, 2); 139 obj->tablevel = (oldobj ? oldobj->tablevel : 0) + tab; 140 PetscFunctionReturn(PETSC_SUCCESS); 141 } 142