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);