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 PetscObjectGetOptions - Gets the options database used by the object. Call immediately after creating the object. 9 10 Collective on PetscObject 11 12 Input Parameter: 13 . obj - any PETSc object, for example a Vec, Mat or KSP. 14 15 Output Parameter: 16 . options - the options database 17 18 Notes: 19 if this is not called the object will use the default options database 20 21 Level: advanced 22 23 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 24 `PetscObjectGetOptionsPrefix()`, `PetscObjectSetOptions()` 25 26 @*/ 27 PetscErrorCode PetscObjectGetOptions(PetscObject obj,PetscOptions *options) 28 { 29 PetscFunctionBegin; 30 PetscValidHeader(obj,1); 31 *options = obj->options; 32 PetscFunctionReturn(0); 33 } 34 35 /*@C 36 PetscObjectSetOptions - Sets the options database used by the object. Call immediately after creating the object. 37 38 Collective on PetscObject 39 40 Input Parameters: 41 + obj - any PETSc object, for example a Vec, Mat or KSP. 42 - options - the options database, use NULL for default 43 44 Notes: 45 if this is not called the object will use the default options database 46 47 Level: advanced 48 49 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 50 `PetscObjectGetOptionsPrefix()`, `PetscObjectGetOptions()` 51 52 @*/ 53 PetscErrorCode PetscObjectSetOptions(PetscObject obj,PetscOptions options) 54 { 55 PetscFunctionBegin; 56 PetscValidHeader(obj,1); 57 obj->options = options; 58 PetscFunctionReturn(0); 59 } 60 61 /*@C 62 PetscObjectSetOptionsPrefix - Sets the prefix used for searching for all 63 options of PetscObjectType in the database. 64 65 Collective on Object 66 67 Input Parameters: 68 + obj - any PETSc object, for example a Vec, Mat or KSP. 69 - prefix - the prefix string to prepend to option requests of the object. 70 71 Notes: 72 A hyphen (-) must NOT be given at the beginning of the prefix name. 73 The first character of all runtime options is AUTOMATICALLY the 74 hyphen. 75 76 Level: advanced 77 78 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 79 `PetscObjectGetOptionsPrefix()`, `TSSetOptionsPrefix()`, `SNESSetOptionsPrefix()`, `KSPSetOptionsPrefix()` 80 81 @*/ 82 PetscErrorCode PetscObjectSetOptionsPrefix(PetscObject obj,const char prefix[]) 83 { 84 PetscFunctionBegin; 85 PetscValidHeader(obj,1); 86 if (prefix) { 87 PetscValidCharPointer(prefix,2); 88 PetscCheck(prefix[0] != '-',PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hyphen"); 89 if (prefix != obj->prefix) { 90 PetscCall(PetscFree(obj->prefix)); 91 PetscCall(PetscStrallocpy(prefix,&obj->prefix)); 92 } 93 } else PetscCall(PetscFree(obj->prefix)); 94 PetscFunctionReturn(0); 95 } 96 97 /*@C 98 PetscObjectAppendOptionsPrefix - Sets the prefix used for searching for all 99 options of PetscObjectType in the database. 100 101 Input Parameters: 102 + obj - any PETSc object, for example a Vec, Mat or KSP. 103 - prefix - the prefix string to prepend to option requests of the object. 104 105 Notes: 106 A hyphen (-) must NOT be given at the beginning of the prefix name. 107 The first character of all runtime options is AUTOMATICALLY the 108 hyphen. 109 110 Level: advanced 111 112 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 113 `PetscObjectGetOptionsPrefix()`, `TSAppendOptionsPrefix()`, `SNESAppendOptionsPrefix()`, `KSPAppendOptionsPrefix()` 114 115 @*/ 116 PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject obj,const char prefix[]) 117 { 118 char *buf = obj->prefix; 119 size_t len1,len2; 120 121 PetscFunctionBegin; 122 PetscValidHeader(obj,1); 123 if (!prefix) PetscFunctionReturn(0); 124 if (!buf) { 125 PetscCall(PetscObjectSetOptionsPrefix(obj,prefix)); 126 PetscFunctionReturn(0); 127 } 128 PetscCheck(prefix[0] != '-',PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hyphen"); 129 130 PetscCall(PetscStrlen(prefix,&len1)); 131 PetscCall(PetscStrlen(buf,&len2)); 132 PetscCall(PetscMalloc1(1+len1+len2,&obj->prefix)); 133 PetscCall(PetscStrcpy(obj->prefix,buf)); 134 PetscCall(PetscStrcat(obj->prefix,prefix)); 135 PetscCall(PetscFree(buf)); 136 PetscFunctionReturn(0); 137 } 138 139 /*@C 140 PetscObjectGetOptionsPrefix - Gets the prefix of the PetscObject. 141 142 Input Parameters: 143 . obj - any PETSc object, for example a Vec, Mat or KSP. 144 145 Output Parameters: 146 . prefix - pointer to the prefix string used is returned 147 148 Level: advanced 149 150 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 151 `TSGetOptionsPrefix()`, `SNESGetOptionsPrefix()`, `KSPGetOptionsPrefix()` 152 153 @*/ 154 PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject obj,const char *prefix[]) 155 { 156 PetscFunctionBegin; 157 PetscValidHeader(obj,1); 158 PetscValidPointer(prefix,2); 159 *prefix = obj->prefix; 160 PetscFunctionReturn(0); 161 } 162 163 /*@C 164 PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for all 165 options of PetscObjectType in the database. 166 167 Input Parameters: 168 + obj - any PETSc object, for example a Vec, Mat or KSP. 169 - prefix - the prefix string to prepend to option requests of the object. 170 171 Notes: 172 A hyphen (-) must NOT be given at the beginning of the prefix name. 173 The first character of all runtime options is AUTOMATICALLY the 174 hyphen. 175 176 Level: advanced 177 178 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, 179 `PetscObjectGetOptionsPrefix()` 180 181 @*/ 182 PetscErrorCode PetscObjectPrependOptionsPrefix(PetscObject obj,const char prefix[]) 183 { 184 char *buf; 185 size_t len1,len2; 186 187 PetscFunctionBegin; 188 PetscValidHeader(obj,1); 189 buf = obj->prefix; 190 if (!prefix) PetscFunctionReturn(0); 191 if (!buf) { 192 PetscCall(PetscObjectSetOptionsPrefix(obj,prefix)); 193 PetscFunctionReturn(0); 194 } 195 PetscCheck(prefix[0] != '-',PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Options prefix should not begin with a hyphen"); 196 197 PetscCall(PetscStrlen(prefix,&len1)); 198 PetscCall(PetscStrlen(buf,&len2)); 199 PetscCall(PetscMalloc1(1+len1+len2,&obj->prefix)); 200 PetscCall(PetscStrcpy(obj->prefix,prefix)); 201 PetscCall(PetscStrcat(obj->prefix,buf)); 202 PetscCall(PetscFree(buf)); 203 PetscFunctionReturn(0); 204 } 205