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