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