Actual source code: petsctaoterm.h
1: #pragma once
3: #include <petscmat.h>
4: #include <petsctaotypes.h>
6: /* MANSEC = Tao */
7: /* SUBMANSEC = TaoTerm */
9: /*S
10: TaoTerm - Abstract PETSc object that manages individual terms whose sum forms the objective function of optimization solvers.
12: Level: beginner
14: Note:
15: User can combine a user-defined `TaoTerm` using `TaoTermCreateShell()` and built-in `TaoTerm` to define the objective function.
17: .seealso: [](ch_tao), [](sec_tao_term),
18: `TaoTermCreate()`,
19: `TaoTermSetType()`,
20: `TaoTermSetFromOptions()`,
21: `TaoTermView()`,
22: `TaoTermComputeObjective()`,
23: `TaoTermComputeGradient()`,
24: `TaoTermComputeObjectiveAndGradient()`,
25: `TaoTermComputeHessian()`,
26: `TaoTermDestroy()`,
27: `TaoTermCreateShell()`,
28: `Tao`,
29: `TaoAddTerm()`
30: S*/
31: typedef struct _p_TaoTerm *TaoTerm;
33: /*J
34: TaoTermType - String with the name of a `TaoTerm` method
36: Values:
37: + `TAOTERMSHELL` - uses user-provided callback functions, see `TaoTermCreateShell()`
38: . `TAOTERMSUM` - a sum of multiple other `TaoTerm`s
39: . `TAOTERMHALFL2SQUARED` - $\tfrac{1}{2}\|x - p\|_2^2$
40: . `TAOTERML1` - $\|x - p\|_1$
41: . `TAOTERMQUADRATIC` - a quadratic form $\tfrac{1}{2}(x - p)^T A (x - p)$
42: - `TAOTERMCALLBACKS` - uses the callback functions set in `TaoSetObjective()`, `TaoSetGradient()`, etc.
44: Level: intermediate
46: .seealso: [](ch_tao), [](sec_tao_term), `TaoTerm`, `TaoTermCreate()`, `TaoTermSetType()`, `TaoTermCreateShell()`
47: J*/
48: typedef const char *TaoTermType;
49: #define TAOTERMCALLBACKS "callbacks"
50: #define TAOTERMSHELL "shell"
51: #define TAOTERMSUM "sum"
52: #define TAOTERMHALFL2SQUARED "halfl2squared"
53: #define TAOTERML1 "l1"
54: #define TAOTERMQUADRATIC "quadratic"
56: PETSC_EXTERN PetscErrorCode TaoTermRegister(const char[], PetscErrorCode (*)(TaoTerm));
58: PETSC_EXTERN PetscClassId TAOTERM_CLASSID;
59: PETSC_EXTERN PetscFunctionList TaoTermList;
61: PETSC_EXTERN PetscErrorCode TaoTermCreate(MPI_Comm, TaoTerm *);
62: PETSC_EXTERN PetscErrorCode TaoTermDestroy(TaoTerm *);
63: PETSC_EXTERN PetscErrorCode TaoTermView(TaoTerm, PetscViewer);
64: PETSC_EXTERN PetscErrorCode TaoTermSetUp(TaoTerm);
65: PETSC_EXTERN PetscErrorCode TaoTermGetType(TaoTerm, TaoTermType *);
66: PETSC_EXTERN PetscErrorCode TaoTermSetType(TaoTerm, TaoTermType);
67: PETSC_EXTERN PetscErrorCode TaoTermSetFromOptions(TaoTerm);
69: /*E
70: TaoTermParametersMode - Ways a `TaoTerm` can accept parameter vectors in `TaoTermComputeObjective()` and related functions
72: Values:
73: + `TAOTERM_PARAMETERS_OPTIONAL` - the term has default parameters that will be used if parameters are omitted
74: . `TAOTERM_PARAMETERS_NONE` - the term is not parametric, passing parameters is an error
75: - `TAOTERM_PARAMETERS_REQUIRED` - the term requires parameters, omitting parameters is an error
77: Level: intermediate
79: Note:
80: Each `TaoTerm` represents a parametric real-valued function $f(x; p)$, where $x$ is the
81: solution variable (the optimization variable) and $p$ is a parameter vector of fixed data
82: that is not optimized over. The solution space (the vector space of $x$) and the parameter
83: space (the vector space of $p$) are set independently; see `TaoTermSetSolutionSizes()` and
84: `TaoTermSetParametersSizes()`.
86: .seealso: [](sec_tao_term), `TaoTerm`, `TaoTermGetParametersMode()`, `TaoTermSetParametersMode()`
87: E*/
88: typedef enum {
89: TAOTERM_PARAMETERS_OPTIONAL,
90: TAOTERM_PARAMETERS_NONE,
91: TAOTERM_PARAMETERS_REQUIRED
92: } TaoTermParametersMode;
93: PETSC_EXTERN const char *const TaoTermParametersModes[];
95: /*E
96: TaoTermMask - Determine which evaluation operations are masked; that is, skipped (not used) by Tao when computing the objective function or its derivatives for a particular `TaoTerm`.
98: Values:
99: + `TAOTERM_MASK_NONE` - do not mask any evaluation routines
100: . `TAOTERM_MASK_OBJECTIVE` - override the term's objective function and return 0 instead
101: . `TAOTERM_MASK_GRADIENT` - override the term's gradient and return a zero vector instead
102: - `TAOTERM_MASK_HESSIAN` - override the term's Hessian and return a zero matrix instead
104: Level: advanced
106: .seealso: [](sec_tao_term), `TaoTerm`, `TaoTermSumSetTermMask()`, `TaoTermSumGetTermMask()`
107: E*/
108: typedef enum {
109: TAOTERM_MASK_NONE = 0, /* 0x0 */
110: TAOTERM_MASK_OBJECTIVE = 1, /* 0x1 */
111: TAOTERM_MASK_GRADIENT = 2, /* 0x2 */
112: TAOTERM_MASK_HESSIAN = 4 /* 0x4 */
113: } TaoTermMask;
115: PETSC_EXTERN PetscErrorCode TaoTermSetParametersMode(TaoTerm, TaoTermParametersMode);
116: PETSC_EXTERN PetscErrorCode TaoTermGetParametersMode(TaoTerm, TaoTermParametersMode *);
118: /*E
119: TaoTermDuplicateOption - Aspects to preserve when duplicating a `TaoTerm`
121: Values:
122: + `TAOTERM_DUPLICATE_SIZEONLY` - duplicates size of the solution space only; user must set appropriate `TaoTermType`
123: - `TAOTERM_DUPLICATE_TYPE` - `TaoTermType` preserved
125: Level: intermediate
127: .seealso: `TaoTerm`, `TaoTermDuplicate()`
128: E*/
129: typedef enum {
130: TAOTERM_DUPLICATE_SIZEONLY,
131: TAOTERM_DUPLICATE_TYPE
132: } TaoTermDuplicateOption;
134: PETSC_EXTERN PetscErrorCode TaoTermDuplicate(TaoTerm, TaoTermDuplicateOption, TaoTerm *);
136: PETSC_EXTERN PetscErrorCode TaoTermSetSolutionSizes(TaoTerm, PetscInt, PetscInt, PetscInt);
137: PETSC_EXTERN PetscErrorCode TaoTermGetSolutionSizes(TaoTerm, PetscInt *, PetscInt *, PetscInt *);
138: PETSC_EXTERN PetscErrorCode TaoTermSetSolutionTemplate(TaoTerm, Vec);
139: PETSC_EXTERN PetscErrorCode TaoTermSetParametersSizes(TaoTerm, PetscInt, PetscInt, PetscInt);
140: PETSC_EXTERN PetscErrorCode TaoTermGetParametersSizes(TaoTerm, PetscInt *, PetscInt *, PetscInt *);
141: PETSC_EXTERN PetscErrorCode TaoTermSetParametersTemplate(TaoTerm, Vec);
142: PETSC_EXTERN PetscErrorCode TaoTermSetSolutionVecType(TaoTerm, VecType);
143: PETSC_EXTERN PetscErrorCode TaoTermSetParametersVecType(TaoTerm, VecType);
144: PETSC_EXTERN PetscErrorCode TaoTermGetSolutionVecType(TaoTerm, VecType *);
145: PETSC_EXTERN PetscErrorCode TaoTermGetParametersVecType(TaoTerm, VecType *);
146: PETSC_EXTERN PetscErrorCode TaoTermSetSolutionLayout(TaoTerm, PetscLayout);
147: PETSC_EXTERN PetscErrorCode TaoTermSetParametersLayout(TaoTerm, PetscLayout);
148: PETSC_EXTERN PetscErrorCode TaoTermGetSolutionLayout(TaoTerm, PetscLayout *);
149: PETSC_EXTERN PetscErrorCode TaoTermGetParametersLayout(TaoTerm, PetscLayout *);
150: PETSC_EXTERN PetscErrorCode TaoTermCreateSolutionVec(TaoTerm, Vec *);
151: PETSC_EXTERN PetscErrorCode TaoTermCreateParametersVec(TaoTerm, Vec *);
152: PETSC_EXTERN PetscErrorCode TaoTermCreateHessianMatrices(TaoTerm, Mat *, Mat *);
153: PETSC_EXTERN PetscErrorCode TaoTermCreateHessianMatricesDefault(TaoTerm, Mat *, Mat *);
154: PETSC_EXTERN PetscErrorCode TaoTermSetCreateHessianMode(TaoTerm, PetscBool, MatType, MatType);
155: PETSC_EXTERN PetscErrorCode TaoTermGetCreateHessianMode(TaoTerm, PetscBool *, MatType *, MatType *);
157: /*S
158: TaoTermObjectiveFn - A prototype of a `TaoTerm` function that would be passed to `TaoTermShellSetObjective()`
160: Calling Sequence:
161: + term - a `TaoTerm`
162: . x - the solution vector
163: . params - the parameters vector (for some `TaoTerm` this may be `NULL`, see `TaoTermGetParametersMode()`)
164: - value - output, the value of the term
166: Level: intermediate
168: .seealso: [](sec_tao_term),
169: `TaoTerm`,
170: `TAOTERMSHELL`,
171: `TaoTermShellSetObjective()`,
172: `TaoTermObjectiveAndGradientFn`,
173: `TaoTermGradientFn`,
174: `TaoTermHessianFn`
175: S*/
176: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(TaoTermObjectiveFn)(TaoTerm term, Vec x, Vec params, PetscReal *value);
178: /*S
179: TaoTermObjectiveAndGradientFn - A prototype of a `TaoTerm` function that would be passed to `TaoTermShellSetObjectiveAndGradient()`
181: Calling Sequence:
182: + term - a `TaoTerm`
183: . x - the solution vector
184: . params - the parameters vector (for some `TaoTerm` this may be `NULL`, see `TaoTermGetParametersMode()`)
185: . value - output, the value of the term
186: - g - output, the gradient of the term
188: Level: intermediate
190: .seealso: [](sec_tao_term),
191: `TaoTerm`,
192: `TAOTERMSHELL`,
193: `TaoTermShellSetObjectiveAndGradient()`,
194: `TaoTermObjectiveFn`,
195: `TaoTermGradientFn`,
196: `TaoTermHessianFn`
197: S*/
198: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(TaoTermObjectiveAndGradientFn)(TaoTerm term, Vec x, Vec params, PetscReal *value, Vec g);
200: /*S
201: TaoTermGradientFn - A prototype of a `TaoTerm` function that would be passed to `TaoTermShellSetGradient()`
203: Calling Sequence:
204: + term - a `TaoTerm`
205: . x - the solution vector
206: . params - the parameters vector (for some `TaoTerm` this may be `NULL`, see `TaoTermGetParametersMode()`)
207: - g - output, the gradient of the term
209: Level: intermediate
211: .seealso: [](sec_tao_term),
212: `TaoTerm`,
213: `TAOTERMSHELL`,
214: `TaoTermShellSetGradient()`,
215: `TaoTermObjectiveFn`,
216: `TaoTermObjectiveAndGradientFn`,
217: `TaoTermHessianFn`
218: S*/
219: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(TaoTermGradientFn)(TaoTerm term, Vec x, Vec params, Vec g);
221: /*S
222: TaoTermHessianFn - A prototype of a `TaoTerm` function that would be passed to `TaoTermShellSetHessian()`
224: Calling Sequence:
225: + term - a `TaoTerm`
226: . x - the solution vector
227: . params - the parameters vector (for some `TaoTerm` this may be `NULL`, see `TaoTermGetParametersMode()`)
228: . H - (optional) output, the Hessian of `term`
229: - Hpre - (optional) output, the approximation of `H` from which a preconditioner may be built
231: Level: intermediate
233: .seealso: [](sec_tao_term),
234: `TaoTerm`,
235: `TAOTERMSHELL`,
236: `TaoTermShellSetHessian()`,
237: `TaoTermObjectiveFn`,
238: `TaoTermObjectiveAndGradientFn`,
239: `TaoTermGradientFn`
240: S*/
241: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(TaoTermHessianFn)(TaoTerm term, Vec x, Vec params, Mat H, Mat Hpre);
243: PETSC_EXTERN PetscErrorCode TaoTermComputeObjective(TaoTerm, Vec, Vec, PetscReal *);
244: PETSC_EXTERN PetscErrorCode TaoTermComputeGradient(TaoTerm, Vec, Vec, Vec);
245: PETSC_EXTERN PetscErrorCode TaoTermComputeObjectiveAndGradient(TaoTerm, Vec, Vec, PetscReal *, Vec);
246: PETSC_EXTERN PetscErrorCode TaoTermComputeHessian(TaoTerm, Vec, Vec, Mat, Mat);
248: PETSC_EXTERN PetscErrorCode TaoTermCreateShell(MPI_Comm, PetscCtx, PetscCtxDestroyFn *, TaoTerm *);
249: PETSC_EXTERN PetscErrorCode TaoTermShellSetContext(TaoTerm, PetscCtx);
250: PETSC_EXTERN PetscErrorCode TaoTermShellGetContext(TaoTerm, PetscCtxRt);
251: PETSC_EXTERN PetscErrorCode TaoTermShellSetContextDestroy(TaoTerm, PetscCtxDestroyFn *);
252: PETSC_EXTERN PetscErrorCode TaoTermShellSetObjective(TaoTerm, TaoTermObjectiveFn *);
253: PETSC_EXTERN PetscErrorCode TaoTermShellSetGradient(TaoTerm, TaoTermGradientFn *);
254: PETSC_EXTERN PetscErrorCode TaoTermShellSetObjectiveAndGradient(TaoTerm, TaoTermObjectiveAndGradientFn *);
255: PETSC_EXTERN PetscErrorCode TaoTermShellSetHessian(TaoTerm, TaoTermHessianFn *);
256: PETSC_EXTERN PetscErrorCode TaoTermShellSetView(TaoTerm, PetscErrorCode (*)(TaoTerm, PetscViewer));
257: PETSC_EXTERN PetscErrorCode TaoTermShellSetCreateSolutionVec(TaoTerm, PetscErrorCode (*)(TaoTerm, Vec *));
258: PETSC_EXTERN PetscErrorCode TaoTermShellSetCreateParametersVec(TaoTerm, PetscErrorCode (*)(TaoTerm, Vec *));
259: PETSC_EXTERN PetscErrorCode TaoTermShellSetCreateHessianMatrices(TaoTerm, PetscErrorCode (*)(TaoTerm, Mat *, Mat *));
260: PETSC_EXTERN PetscErrorCode TaoTermShellSetIsComputeHessianFDPossible(TaoTerm, PetscBool3);
262: PETSC_EXTERN PetscErrorCode TaoTermSumSetNumberTerms(TaoTerm, PetscInt);
263: PETSC_EXTERN PetscErrorCode TaoTermSumGetNumberTerms(TaoTerm, PetscInt *);
264: PETSC_EXTERN PetscErrorCode TaoTermSumSetTerm(TaoTerm, PetscInt, const char[], PetscReal, TaoTerm, Mat);
265: PETSC_EXTERN PetscErrorCode TaoTermSumGetTerm(TaoTerm, PetscInt, const char **, PetscReal *, TaoTerm *, Mat *);
266: PETSC_EXTERN PetscErrorCode TaoTermSumAddTerm(TaoTerm, const char[], PetscReal, TaoTerm, Mat, PetscInt *);
267: PETSC_EXTERN PetscErrorCode TaoTermSumParametersPack(TaoTerm, Vec[], Vec *);
268: PETSC_EXTERN PetscErrorCode TaoTermSumParametersUnpack(TaoTerm, Vec *, Vec[]);
269: PETSC_EXTERN PetscErrorCode VecNestGetTaoTermSumParameters(Vec, PetscInt, Vec *);
270: PETSC_EXTERN PetscErrorCode TaoTermSumGetTermHessianMatrices(TaoTerm, PetscInt, Mat *, Mat *, Mat *, Mat *);
271: PETSC_EXTERN PetscErrorCode TaoTermSumSetTermHessianMatrices(TaoTerm, PetscInt, Mat, Mat, Mat, Mat);
272: PETSC_EXTERN PetscErrorCode TaoTermSumGetTermMask(TaoTerm, PetscInt, TaoTermMask *);
273: PETSC_EXTERN PetscErrorCode TaoTermSumSetTermMask(TaoTerm, PetscInt, TaoTermMask);
274: PETSC_EXTERN PetscErrorCode TaoTermSumGetLastTermObjectives(TaoTerm, const PetscReal *[]);
276: PETSC_EXTERN PetscErrorCode TaoTermCreateHalfL2Squared(MPI_Comm, PetscInt, PetscInt, TaoTerm *);
278: PETSC_EXTERN PetscErrorCode TaoTermCreateL1(MPI_Comm, PetscInt, PetscInt, PetscReal, TaoTerm *);
279: PETSC_EXTERN PetscErrorCode TaoTermL1SetEpsilon(TaoTerm, PetscReal);
280: PETSC_EXTERN PetscErrorCode TaoTermL1GetEpsilon(TaoTerm, PetscReal *);
282: PETSC_EXTERN PetscErrorCode TaoTermCreateQuadratic(Mat, TaoTerm *);
283: PETSC_EXTERN PetscErrorCode TaoTermQuadraticGetMat(TaoTerm, Mat *);
284: PETSC_EXTERN PetscErrorCode TaoTermQuadraticSetMat(TaoTerm, Mat);
286: PETSC_EXTERN PetscErrorCode TaoTermIsObjectiveDefined(TaoTerm, PetscBool *);
287: PETSC_EXTERN PetscErrorCode TaoTermIsGradientDefined(TaoTerm, PetscBool *);
288: PETSC_EXTERN PetscErrorCode TaoTermIsObjectiveAndGradientDefined(TaoTerm, PetscBool *);
289: PETSC_EXTERN PetscErrorCode TaoTermIsHessianDefined(TaoTerm, PetscBool *);
290: PETSC_EXTERN PetscErrorCode TaoTermIsCreateHessianMatricesDefined(TaoTerm, PetscBool *);
291: PETSC_EXTERN PetscErrorCode TaoTermIsComputeHessianFDPossible(TaoTerm, PetscBool3 *);
293: PETSC_EXTERN PetscErrorCode TaoTermGetFDDelta(TaoTerm, PetscReal *);
294: PETSC_EXTERN PetscErrorCode TaoTermSetFDDelta(TaoTerm, PetscReal);
295: PETSC_EXTERN PetscErrorCode TaoTermComputeGradientFD(TaoTerm, Vec, Vec, Vec);
296: PETSC_EXTERN PetscErrorCode TaoTermComputeGradientSetUseFD(TaoTerm, PetscBool);
297: PETSC_EXTERN PetscErrorCode TaoTermComputeGradientGetUseFD(TaoTerm, PetscBool *);
298: PETSC_EXTERN PetscErrorCode TaoTermComputeHessianFD(TaoTerm, Vec, Vec, Mat, Mat);
299: PETSC_EXTERN PetscErrorCode TaoTermComputeHessianSetUseFD(TaoTerm, PetscBool);
300: PETSC_EXTERN PetscErrorCode TaoTermComputeHessianGetUseFD(TaoTerm, PetscBool *);
301: PETSC_EXTERN PetscErrorCode TaoTermCreateHessianMFFD(TaoTerm, Mat *);
302: PETSC_EXTERN PetscErrorCode TaoTermComputeHessianMFFD(TaoTerm, Vec, Vec, Mat, Mat);