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`. Thus 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`, 32 regardless of the type. 33 34 Not Collective 35 36 Input Parameter: 37 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. Thus must be 38 cast with a (`PetscObject`), for example, 39 `PetscObjectGetComm`((`PetscObject`)mat,&comm); 40 41 Output Parameter: 42 . comm - the MPI communicator 43 44 Level: advanced 45 46 .seealso: `PetscObject`, `PetscObjectComm()` 47 @*/ 48 PetscErrorCode PetscObjectGetComm(PetscObject obj, MPI_Comm *comm) 49 { 50 PetscFunctionBegin; 51 PetscValidHeader(obj, 1); 52 PetscAssertPointer(comm, 2); 53 *comm = obj->comm; 54 PetscFunctionReturn(PETSC_SUCCESS); 55 } 56 57 /*@ 58 PetscObjectGetTabLevel - Gets the number of tabs that `PETSCVIEWERASCII` output for that object uses 59 60 Not Collective 61 62 Input Parameter: 63 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. Thus must be 64 cast with a (`PetscObject`), for example, 65 `PetscObjectGetTabLevel`((`PetscObject`)mat,&tab); 66 67 Output Parameter: 68 . tab - the number of tabs 69 70 Level: developer 71 72 Note: 73 This is used to manage the output from options that are embedded in other objects. For example 74 the `KSP` object inside a `SNES` object. By indenting each lower level further the hierarchy of objects 75 is very clear. 76 77 .seealso: `PetscObjectIncrementTabLevel()`, `PetscObjectSetTabLevel()`, `PETSCVIEWERASCII`, `PetscObject` 78 @*/ 79 PetscErrorCode PetscObjectGetTabLevel(PetscObject obj, PetscInt *tab) 80 { 81 PetscFunctionBegin; 82 PetscValidHeader(obj, 1); 83 PetscAssertPointer(tab, 2); 84 *tab = obj->tablevel; 85 PetscFunctionReturn(PETSC_SUCCESS); 86 } 87 88 /*@ 89 PetscObjectSetTabLevel - Sets the number of tabs that `PETSCVIEWERASCII` output for that object uses 90 91 Not Collective 92 93 Input Parameters: 94 + obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. Thus must be 95 cast with a (`PetscObject`), for example, 96 `PetscObjectSetTabLevel`((`PetscObject`)mat,tab; 97 - tab - the number of tabs 98 99 Level: developer 100 101 Notes: 102 this is used to manage the output from options that are embedded in other objects. For example 103 the `KSP` object inside a `SNES` object. By indenting each lower level further the hierarchy of objects 104 is very clear. 105 106 `PetscObjectIncrementTabLevel()` is the preferred API 107 108 .seealso: `PetscObjectIncrementTabLevel()`, `PetscObjectGetTabLevel()` 109 @*/ 110 PetscErrorCode PetscObjectSetTabLevel(PetscObject obj, PetscInt tab) 111 { 112 PetscFunctionBegin; 113 PetscValidHeader(obj, 1); 114 obj->tablevel = tab; 115 PetscFunctionReturn(PETSC_SUCCESS); 116 } 117 118 /*@ 119 PetscObjectIncrementTabLevel - Increments the number of tabs that `PETSCVIEWERASCII` output for that object use based on 120 the tablevel of another object. This should be called immediately after the object is created. 121 122 Not Collective 123 124 Input Parameters: 125 + obj - any PETSc object where we are changing the tab 126 . oldobj - the object providing the tab, optional pass `NULL` to use 0 as the previous tablevel for `obj` 127 - tab - the increment that is added to the old objects tab 128 129 Level: developer 130 131 Note: 132 this is used to manage the output from options that are embedded in other objects. For example 133 the `KSP` object inside a `SNES` object. By indenting each lower level further the hierarchy of objects 134 is very clear. 135 136 .seealso: `PETSCVIEWERASCII`, `PetscObjectSetTabLevel()`, `PetscObjectGetTabLevel()` 137 @*/ 138 PetscErrorCode PetscObjectIncrementTabLevel(PetscObject obj, PetscObject oldobj, PetscInt tab) 139 { 140 PetscFunctionBegin; 141 PetscValidHeader(obj, 1); 142 if (oldobj) PetscValidHeader(oldobj, 2); 143 obj->tablevel = (oldobj ? oldobj->tablevel : 0) + tab; 144 PetscFunctionReturn(PETSC_SUCCESS); 145 } 146