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