1 #pragma once 2 3 #include <petscsnes.h> 4 5 /* SUBMANSEC = Tao */ 6 7 PETSC_EXTERN PetscErrorCode MatDSFischer(Mat, Vec, Vec, Vec, Vec, PetscReal, Vec, Vec, Vec, Vec, Vec); 8 PETSC_EXTERN PetscErrorCode TaoSoftThreshold(Vec, PetscReal, PetscReal, Vec); 9 10 /*E 11 TaoSubsetType - Type representing the way the `Tao` solvers handle active sets 12 13 Values: 14 + `TAO_SUBSET_SUBVEC` - Tao uses `MatCreateSubMatrix()` and `VecGetSubVector()` 15 . `TAO_SUBSET_MASK` - Matrices are zeroed out corresponding to active set entries 16 - `TAO_SUBSET_MATRIXFREE` - Same as `TAO_SUBSET_MASK` but it can be applied to matrix-free operators 17 18 Options database Key: 19 . -different_hessian - `Tao` will use a copy of the Hessian operator for masking. By default `Tao` will directly alter the Hessian operator. 20 21 Level: intermediate 22 23 .seealso: [](ch_tao), `TaoVecGetSubVec()`, `TaoMatGetSubMat()`, `Tao`, `TaoCreate()`, `TaoDestroy()`, `TaoSetType()`, `TaoType` 24 E*/ 25 typedef enum { 26 TAO_SUBSET_SUBVEC, 27 TAO_SUBSET_MASK, 28 TAO_SUBSET_MATRIXFREE 29 } TaoSubsetType; 30 PETSC_EXTERN const char *const TaoSubsetTypes[]; 31 32 /*S 33 Tao - Abstract PETSc object that manages optimization solvers. 34 35 Level: advanced 36 37 Note: 38 `Tao` is the object, while TAO, which stands for Toolkit for Advanced Optimization, is the software package. 39 40 .seealso: [](doc_taosolve), [](ch_tao), `TaoCreate()`, `TaoDestroy()`, `TaoSetType()`, `TaoType` 41 S*/ 42 typedef struct _p_Tao *Tao; 43 44 /*E 45 TaoADMMUpdateType - Determine the spectral penalty update routine for the Lagrange augmented term for `TAOADMM`. 46 47 Level: advanced 48 49 .seealso: [](ch_tao), `Tao`, `TAOADMM`, `TaoADMMSetUpdateType()` 50 E*/ 51 typedef enum { 52 TAO_ADMM_UPDATE_BASIC, 53 TAO_ADMM_UPDATE_ADAPTIVE, 54 TAO_ADMM_UPDATE_ADAPTIVE_RELAXED 55 } TaoADMMUpdateType; 56 PETSC_EXTERN const char *const TaoADMMUpdateTypes[]; 57 58 /*MC 59 TAO_ADMM_UPDATE_BASIC - Use same spectral penalty set at the beginning. This never performs an update to the penalty 60 61 Level: advanced 62 63 Note: 64 Most basic implementation of `TAOADMM`. Generally slower than adaptive or adaptive relaxed version. 65 66 .seealso: [](ch_tao), `Tao`, `TAOADMM`, `TaoADMMSetUpdateType()`, `TAO_ADMM_UPDATE_ADAPTIVE`, `TAO_ADMM_UPDATE_ADAPTIVE_RELAXED` 67 M*/ 68 69 /*MC 70 TAO_ADMM_UPDATE_ADAPTIVE - Adaptively update the spectral penalty 71 72 Level: advanced 73 74 Note: 75 Adaptively updates spectral penalty of `TAOADMM` by using both steepest descent and minimum gradient. 76 77 .seealso: [](ch_tao), `Tao`, `TAOADMM`, `TaoADMMSetUpdateType()`, `TAO_ADMM_UPDATE_BASIC`, `TAO_ADMM_UPDATE_ADAPTIVE_RELAXED` 78 M*/ 79 80 /*MC 81 ADMM_UPDATE_ADAPTIVE_RELAXED - Adaptively update spectral penalty, and relaxes parameter update 82 83 Level: advanced 84 85 Note: 86 With adaptive spectral penalty update, it also relaxes the `x` vector update by a factor. 87 88 .seealso: [](ch_tao), `Tao`, `TaoADMMSetUpdateType()`, `TAO_ADMM_UPDATE_BASIC`, `TAO_ADMM_UPDATE_ADAPTIVE` 89 M*/ 90 91 /*E 92 TaoADMMRegularizerType - Determine regularizer routine - either user provided or soft threshold for `TAOADMM` 93 94 Level: advanced 95 96 .seealso: [](ch_tao), `Tao`, `TAOADMM`, `TaoADMMSetRegularizerType()` 97 E*/ 98 typedef enum { 99 TAO_ADMM_REGULARIZER_USER, 100 TAO_ADMM_REGULARIZER_SOFT_THRESH 101 } TaoADMMRegularizerType; 102 PETSC_EXTERN const char *const TaoADMMRegularizerTypes[]; 103 104 /*MC 105 TAO_ADMM_REGULARIZER_USER - User provided routines for regularizer part of `TAOADMM` 106 107 Level: advanced 108 109 Note: 110 User needs to provided appropriate routines and type for regularizer solver 111 112 .seealso: [](ch_tao), `Tao`, `TAOADMM`, `TaoADMMSetRegularizerType()`, `TAO_ADMM_REGULARIZER_SOFT_THRESH` 113 M*/ 114 115 /*MC 116 TAO_ADMM_REGULARIZER_SOFT_THRESH - Soft threshold to solve regularizer part of `TAOADMM` 117 118 Level: advanced 119 120 Note: 121 Utilizes built-in SoftThreshold routines 122 123 .seealso: [](ch_tao), `Tao`, `TAOADMM`, `TaoSoftThreshold()`, `TaoADMMSetRegularizerObjectiveAndGradientRoutine()`, 124 `TaoADMMSetRegularizerHessianRoutine()`, `TaoADMMSetRegularizerType()`, `TAO_ADMM_REGULARIZER_USER` 125 M*/ 126 127 /*E 128 TaoALMMType - Determine the augmented Lagrangian formulation used in the `TAOALMM` subproblem. 129 130 Values: 131 + `TAO_ALMM_CLASSIC` - classic augmented Lagrangian definition including slack variables for inequality constraints 132 - `TAO_ALMM_PHR` - Powell-Hestenes-Rockafellar formulation without slack variables, uses pointwise `min()` for inequalities 133 134 Level: advanced 135 136 .seealso: [](ch_tao), `Tao`, `TAOALMM`, `TaoALMMSetType()`, `TaoALMMGetType()` 137 E*/ 138 typedef enum { 139 TAO_ALMM_CLASSIC, 140 TAO_ALMM_PHR 141 } TaoALMMType; 142 PETSC_EXTERN const char *const TaoALMMTypes[]; 143 144 /*E 145 TaoBNCGType - Determine the conjugate gradient update formula used in the `TAOBNCG` algorithm. 146 147 Values: 148 + `TAO_BNCG_GD` - basic gradient descent, no CG update 149 . `TAO_BNCG_PCGD` - preconditioned/scaled gradient descent 150 . `TAO_BNCG_HS` - Hestenes-Stiefel 151 . `TAO_BNCG_FR` - Fletcher-Reeves 152 . `TAO_BNCG_PRP` - Polak-Ribiere-Polyak (PRP) 153 . `TAO_BNCG_PRP_PLUS` - Polak-Ribiere-Polyak "plus" (PRP+) 154 . `TAO_BNCG_DY` - Dai-Yuan 155 . `TAO_BNCG_HZ` - Hager-Zhang (CG_DESCENT 5.3) 156 . `TAO_BNCG_DK` - Dai-Kou (2013) 157 . `TAO_BNCG_KD` - Kou-Dai (2015) 158 . `TAO_BNCG_SSML_BFGS` - Self-Scaling Memoryless BFGS (Perry-Shanno) 159 . `TAO_BNCG_SSML_DFP` - Self-Scaling Memoryless DFP 160 - `TAO_BNCG_SSML_BRDN` - Self-Scaling Memoryless (Symmetric) Broyden 161 162 Level: advanced 163 164 .seealso: `Tao`, `TAOBNCG`, `TaoBNCGSetType()`, `TaoBNCGGetType()` 165 E*/ 166 167 typedef enum { 168 TAO_BNCG_GD, 169 TAO_BNCG_PCGD, 170 TAO_BNCG_HS, 171 TAO_BNCG_FR, 172 TAO_BNCG_PRP, 173 TAO_BNCG_PRP_PLUS, 174 TAO_BNCG_DY, 175 TAO_BNCG_HZ, 176 TAO_BNCG_DK, 177 TAO_BNCG_KD, 178 TAO_BNCG_SSML_BFGS, 179 TAO_BNCG_SSML_DFP, 180 TAO_BNCG_SSML_BRDN 181 } TaoBNCGType; 182 PETSC_EXTERN const char *const TaoBNCGTypes[]; 183 184 /*J 185 TaoType - String with the name of a `Tao` method 186 187 Values: 188 + `TAONLS` - nls Newton's method with line search for unconstrained minimization 189 . `TAONTR` - ntr Newton's method with trust region for unconstrained minimization 190 . `TAONTL` - ntl Newton's method with trust region, line search for unconstrained minimization 191 . `TAOLMVM` - lmvm Limited memory variable metric method for unconstrained minimization 192 . `TAOCG` - cg Nonlinear conjugate gradient method for unconstrained minimization 193 . `TAONM` - nm Nelder-Mead algorithm for derivate-free unconstrained minimization 194 . `TAOTRON` - tron Newton Trust Region method for bound constrained minimization 195 . `TAOGPCG` - gpcg Newton Trust Region method for quadratic bound constrained minimization 196 . `TAOBLMVM` - blmvm Limited memory variable metric method for bound constrained minimization 197 . `TAOLCL` - lcl Linearly constrained Lagrangian method for pde-constrained minimization 198 - `TAOPOUNDERS` - Pounders Model-based algorithm for nonlinear least squares 199 200 Level: beginner 201 202 .seealso: [](doc_taosolve), [](ch_tao), `Tao`, `TaoCreate()`, `TaoSetType()` 203 J*/ 204 typedef const char *TaoType; 205 #define TAOLMVM "lmvm" 206 #define TAONLS "nls" 207 #define TAONTR "ntr" 208 #define TAONTL "ntl" 209 #define TAOCG "cg" 210 #define TAOTRON "tron" 211 #define TAOOWLQN "owlqn" 212 #define TAOBMRM "bmrm" 213 #define TAOBLMVM "blmvm" 214 #define TAOBQNLS "bqnls" 215 #define TAOBNCG "bncg" 216 #define TAOBNLS "bnls" 217 #define TAOBNTR "bntr" 218 #define TAOBNTL "bntl" 219 #define TAOBQNKLS "bqnkls" 220 #define TAOBQNKTR "bqnktr" 221 #define TAOBQNKTL "bqnktl" 222 #define TAOBQPIP "bqpip" 223 #define TAOGPCG "gpcg" 224 #define TAONM "nm" 225 #define TAOPOUNDERS "pounders" 226 #define TAOBRGN "brgn" 227 #define TAOLCL "lcl" 228 #define TAOSSILS "ssils" 229 #define TAOSSFLS "ssfls" 230 #define TAOASILS "asils" 231 #define TAOASFLS "asfls" 232 #define TAOIPM "ipm" 233 #define TAOPDIPM "pdipm" 234 #define TAOSHELL "shell" 235 #define TAOADMM "admm" 236 #define TAOALMM "almm" 237 #define TAOPYTHON "python" 238 #define TAOSNES "snes" 239 240 PETSC_EXTERN PetscClassId TAO_CLASSID; 241 PETSC_EXTERN PetscFunctionList TaoList; 242 243 /*E 244 TaoConvergedReason - reason a `Tao` optimizer was said to have converged or diverged 245 246 Values: 247 + `TAO_CONVERGED_GATOL` - $||g(X)|| < gatol$ 248 . `TAO_CONVERGED_GRTOL` - $||g(X)|| / f(X) < grtol$ 249 . `TAO_CONVERGED_GTTOL` - $||g(X)|| / ||g(X0)|| < gttol$ 250 . `TAO_CONVERGED_STEPTOL` - step size smaller than tolerance 251 . `TAO_CONVERGED_MINF` - $F < F_min$ 252 . `TAO_CONVERGED_USER` - the user indicates the optimization has succeeded 253 . `TAO_DIVERGED_MAXITS` - the maximum number of iterations allowed has been achieved 254 . `TAO_DIVERGED_NAN` - not a number appeared in the computations 255 . `TAO_DIVERGED_MAXFCN` - the maximum number of function evaluations has been computed 256 . `TAO_DIVERGED_LS_FAILURE` - a linesearch failed 257 . `TAO_DIVERGED_TR_REDUCTION` - trust region failure 258 . `TAO_DIVERGED_USER` - the user has indicated the optimization has failed 259 - `TAO_CONTINUE_ITERATING` - the optimization is still running, `TaoSolve()` 260 261 where 262 + X - current solution 263 . X0 - initial guess 264 . f(X) - current function value 265 . f(X*) - true solution (estimated) 266 . g(X) - current gradient 267 . its - current iterate number 268 . maxits - maximum number of iterates 269 . fevals - number of function evaluations 270 - max_funcsals - maximum number of function evaluations 271 272 Level: beginner 273 274 Note: 275 The two most common reasons for divergence are an incorrectly coded or computed gradient or Hessian failure or lack of convergence 276 in the linear system solve (in this case we recommend testing with `-pc_type lu` to eliminate the linear solver as the cause of the problem). 277 278 Developer Note: 279 The names in `KSPConvergedReason`, `SNESConvergedReason`, and `TaoConvergedReason` should be uniformized 280 281 .seealso: [](ch_tao), `Tao`, `TaoSolve()`, `TaoGetConvergedReason()`, `KSPConvergedReason`, `SNESConvergedReason` 282 E*/ 283 typedef enum { /* converged */ 284 TAO_CONVERGED_GATOL = 3, /* ||g(X)|| < gatol */ 285 TAO_CONVERGED_GRTOL = 4, /* ||g(X)|| / f(X) < grtol */ 286 TAO_CONVERGED_GTTOL = 5, /* ||g(X)|| / ||g(X0)|| < gttol */ 287 TAO_CONVERGED_STEPTOL = 6, /* step size small */ 288 TAO_CONVERGED_MINF = 7, /* F < F_min */ 289 TAO_CONVERGED_USER = 8, /* User defined */ 290 /* diverged */ 291 TAO_DIVERGED_MAXITS = -2, 292 TAO_DIVERGED_NAN = -4, 293 TAO_DIVERGED_MAXFCN = -5, 294 TAO_DIVERGED_LS_FAILURE = -6, 295 TAO_DIVERGED_TR_REDUCTION = -7, 296 TAO_DIVERGED_USER = -8, /* User defined */ 297 /* keep going */ 298 TAO_CONTINUE_ITERATING = 0 299 } TaoConvergedReason; 300 301 PETSC_EXTERN const char **TaoConvergedReasons; 302 303 PETSC_EXTERN PetscErrorCode TaoInitializePackage(void); 304 PETSC_EXTERN PetscErrorCode TaoFinalizePackage(void); 305 PETSC_EXTERN PetscErrorCode TaoCreate(MPI_Comm, Tao *); 306 PETSC_EXTERN PetscErrorCode TaoSetFromOptions(Tao); 307 PETSC_EXTERN PetscErrorCode TaoSetUp(Tao); 308 PETSC_EXTERN PetscErrorCode TaoSetType(Tao, TaoType); 309 PETSC_EXTERN PetscErrorCode TaoGetType(Tao, TaoType *); 310 PETSC_EXTERN PetscErrorCode TaoSetApplicationContext(Tao, PetscCtx); 311 PETSC_EXTERN PetscErrorCode TaoGetApplicationContext(Tao, PetscCtxRt); 312 PETSC_EXTERN PetscErrorCode TaoDestroy(Tao *); 313 PETSC_EXTERN PetscErrorCode TaoParametersInitialize(Tao); 314 315 PETSC_EXTERN PetscErrorCode TaoSetOptionsPrefix(Tao, const char[]); 316 PETSC_EXTERN PetscErrorCode TaoView(Tao, PetscViewer); 317 PETSC_EXTERN PetscErrorCode TaoViewFromOptions(Tao, PetscObject, const char[]); 318 319 PETSC_EXTERN PetscErrorCode TaoSolve(Tao); 320 321 PETSC_EXTERN PetscErrorCode TaoRegister(const char[], PetscErrorCode (*)(Tao)); 322 PETSC_EXTERN PetscErrorCode TaoRegisterDestroy(void); 323 324 PETSC_EXTERN PetscErrorCode TaoGetConvergedReason(Tao, TaoConvergedReason *); 325 PETSC_EXTERN PetscErrorCode TaoGetSolutionStatus(Tao, PetscInt *, PetscReal *, PetscReal *, PetscReal *, PetscReal *, TaoConvergedReason *); 326 PETSC_EXTERN PetscErrorCode TaoSetConvergedReason(Tao, TaoConvergedReason); 327 PETSC_EXTERN PetscErrorCode TaoSetSolution(Tao, Vec); 328 PETSC_EXTERN PetscErrorCode TaoGetSolution(Tao, Vec *); 329 330 PETSC_EXTERN PetscErrorCode TaoSetObjective(Tao, PetscErrorCode (*)(Tao, Vec, PetscReal *, PetscCtx), PetscCtx); 331 PETSC_EXTERN PetscErrorCode TaoGetObjective(Tao, PetscErrorCode (**)(Tao, Vec, PetscReal *, PetscCtx), PetscCtxRt); 332 PETSC_EXTERN PetscErrorCode TaoSetGradient(Tao, Vec, PetscErrorCode (*)(Tao, Vec, Vec, PetscCtx), PetscCtx); 333 PETSC_EXTERN PetscErrorCode TaoGetGradient(Tao, Vec *, PetscErrorCode (**)(Tao, Vec, Vec, PetscCtx), PetscCtxRt); 334 PETSC_EXTERN PetscErrorCode TaoSetObjectiveAndGradient(Tao, Vec, PetscErrorCode (*)(Tao, Vec, PetscReal *, Vec, PetscCtx), PetscCtx); 335 PETSC_EXTERN PetscErrorCode TaoGetObjectiveAndGradient(Tao, Vec *, PetscErrorCode (**)(Tao, Vec, PetscReal *, Vec, PetscCtx), PetscCtxRt); 336 PETSC_EXTERN PetscErrorCode TaoSetHessian(Tao, Mat, Mat, PetscErrorCode (*)(Tao, Vec, Mat, Mat, PetscCtx), PetscCtx); 337 PETSC_EXTERN PetscErrorCode TaoGetHessian(Tao, Mat *, Mat *, PetscErrorCode (**)(Tao, Vec, Mat, Mat, PetscCtx), PetscCtxRt); 338 339 PETSC_EXTERN PetscErrorCode TaoSetGradientNorm(Tao, Mat); 340 PETSC_EXTERN PetscErrorCode TaoGetGradientNorm(Tao, Mat *); 341 PETSC_EXTERN PetscErrorCode TaoSetLMVMMatrix(Tao, Mat); 342 PETSC_EXTERN PetscErrorCode TaoGetLMVMMatrix(Tao, Mat *); 343 PETSC_EXTERN PetscErrorCode TaoSetRecycleHistory(Tao, PetscBool); 344 PETSC_EXTERN PetscErrorCode TaoGetRecycleHistory(Tao, PetscBool *); 345 PETSC_EXTERN PetscErrorCode TaoLMVMSetH0(Tao, Mat); 346 PETSC_EXTERN PetscErrorCode TaoLMVMGetH0(Tao, Mat *); 347 PETSC_EXTERN PetscErrorCode TaoLMVMGetH0KSP(Tao, KSP *); 348 PETSC_EXTERN PetscErrorCode TaoLMVMRecycle(Tao, PetscBool); 349 PETSC_EXTERN PetscErrorCode TaoSetResidualRoutine(Tao, Vec, PetscErrorCode (*)(Tao, Vec, Vec, PetscCtx), PetscCtx); 350 PETSC_EXTERN PetscErrorCode TaoSetResidualWeights(Tao, Vec, PetscInt, PetscInt *, PetscInt *, PetscReal *); 351 PETSC_EXTERN PetscErrorCode TaoSetConstraintsRoutine(Tao, Vec, PetscErrorCode (*)(Tao, Vec, Vec, PetscCtx), PetscCtx); 352 PETSC_EXTERN PetscErrorCode TaoSetInequalityConstraintsRoutine(Tao, Vec, PetscErrorCode (*)(Tao, Vec, Vec, PetscCtx), PetscCtx); 353 PETSC_EXTERN PetscErrorCode TaoGetInequalityConstraintsRoutine(Tao, Vec *, PetscErrorCode (**)(Tao, Vec, Vec, PetscCtx), PetscCtxRt); 354 PETSC_EXTERN PetscErrorCode TaoSetEqualityConstraintsRoutine(Tao, Vec, PetscErrorCode (*)(Tao, Vec, Vec, PetscCtx), PetscCtx); 355 PETSC_EXTERN PetscErrorCode TaoGetEqualityConstraintsRoutine(Tao, Vec *, PetscErrorCode (**)(Tao, Vec, Vec, PetscCtx), PetscCtxRt); 356 PETSC_EXTERN PetscErrorCode TaoSetJacobianResidualRoutine(Tao, Mat, Mat, PetscErrorCode (*)(Tao, Vec, Mat, Mat, PetscCtx), PetscCtx); 357 PETSC_EXTERN PetscErrorCode TaoSetJacobianRoutine(Tao, Mat, Mat, PetscErrorCode (*)(Tao, Vec, Mat, Mat, PetscCtx), PetscCtx); 358 PETSC_EXTERN PetscErrorCode TaoSetJacobianStateRoutine(Tao, Mat, Mat, Mat, PetscErrorCode (*)(Tao, Vec, Mat, Mat, Mat, PetscCtx), PetscCtx); 359 PETSC_EXTERN PetscErrorCode TaoSetJacobianDesignRoutine(Tao, Mat, PetscErrorCode (*)(Tao, Vec, Mat, PetscCtx), PetscCtx); 360 PETSC_EXTERN PetscErrorCode TaoSetJacobianInequalityRoutine(Tao, Mat, Mat, PetscErrorCode (*)(Tao, Vec, Mat, Mat, PetscCtx), PetscCtx); 361 PETSC_EXTERN PetscErrorCode TaoGetJacobianInequalityRoutine(Tao, Mat *, Mat *, PetscErrorCode (**)(Tao, Vec, Mat, Mat, PetscCtx), PetscCtxRt); 362 PETSC_EXTERN PetscErrorCode TaoSetJacobianEqualityRoutine(Tao, Mat, Mat, PetscErrorCode (*)(Tao, Vec, Mat, Mat, PetscCtx), PetscCtx); 363 PETSC_EXTERN PetscErrorCode TaoGetJacobianEqualityRoutine(Tao, Mat *, Mat *, PetscErrorCode (**)(Tao, Vec, Mat, Mat, PetscCtx), PetscCtxRt); 364 365 PETSC_EXTERN PetscErrorCode TaoPythonSetType(Tao, const char[]); 366 PETSC_EXTERN PetscErrorCode TaoPythonGetType(Tao, const char *[]); 367 368 PETSC_EXTERN PetscErrorCode TaoShellSetSolve(Tao, PetscErrorCode (*)(Tao)); 369 PETSC_EXTERN PetscErrorCode TaoShellSetContext(Tao, PetscCtx); 370 PETSC_EXTERN PetscErrorCode TaoShellGetContext(Tao, PetscCtxRt); 371 372 PETSC_EXTERN PetscErrorCode TaoSetStateDesignIS(Tao, IS, IS); 373 374 PETSC_EXTERN PetscErrorCode TaoComputeObjective(Tao, Vec, PetscReal *); 375 PETSC_EXTERN PetscErrorCode TaoComputeResidual(Tao, Vec, Vec); 376 PETSC_EXTERN PetscErrorCode TaoTestGradient(Tao, Vec, Vec); 377 PETSC_EXTERN PetscErrorCode TaoComputeGradient(Tao, Vec, Vec); 378 PETSC_EXTERN PetscErrorCode TaoComputeObjectiveAndGradient(Tao, Vec, PetscReal *, Vec); 379 PETSC_EXTERN PetscErrorCode TaoComputeConstraints(Tao, Vec, Vec); 380 PETSC_EXTERN PetscErrorCode TaoComputeInequalityConstraints(Tao, Vec, Vec); 381 PETSC_EXTERN PetscErrorCode TaoComputeEqualityConstraints(Tao, Vec, Vec); 382 PETSC_EXTERN PetscErrorCode TaoDefaultComputeGradient(Tao, Vec, Vec, PetscCtx); 383 PETSC_EXTERN PetscErrorCode TaoIsObjectiveDefined(Tao, PetscBool *); 384 PETSC_EXTERN PetscErrorCode TaoIsGradientDefined(Tao, PetscBool *); 385 PETSC_EXTERN PetscErrorCode TaoIsObjectiveAndGradientDefined(Tao, PetscBool *); 386 387 PETSC_EXTERN PetscErrorCode TaoTestHessian(Tao); 388 PETSC_EXTERN PetscErrorCode TaoComputeHessian(Tao, Vec, Mat, Mat); 389 PETSC_EXTERN PetscErrorCode TaoComputeResidualJacobian(Tao, Vec, Mat, Mat); 390 PETSC_EXTERN PetscErrorCode TaoComputeJacobian(Tao, Vec, Mat, Mat); 391 PETSC_EXTERN PetscErrorCode TaoComputeJacobianState(Tao, Vec, Mat, Mat, Mat); 392 PETSC_EXTERN PetscErrorCode TaoComputeJacobianEquality(Tao, Vec, Mat, Mat); 393 PETSC_EXTERN PetscErrorCode TaoComputeJacobianInequality(Tao, Vec, Mat, Mat); 394 PETSC_EXTERN PetscErrorCode TaoComputeJacobianDesign(Tao, Vec, Mat); 395 396 PETSC_EXTERN PetscErrorCode TaoDefaultComputeHessian(Tao, Vec, Mat, Mat, PetscCtx); 397 PETSC_EXTERN PetscErrorCode TaoDefaultComputeHessianColor(Tao, Vec, Mat, Mat, PetscCtx); 398 PETSC_EXTERN PetscErrorCode TaoDefaultComputeHessianMFFD(Tao, Vec, Mat, Mat, PetscCtx); 399 PETSC_EXTERN PetscErrorCode TaoComputeDualVariables(Tao, Vec, Vec); 400 PETSC_EXTERN PetscErrorCode TaoSetVariableBounds(Tao, Vec, Vec); 401 PETSC_EXTERN PetscErrorCode TaoGetVariableBounds(Tao, Vec *, Vec *); 402 PETSC_EXTERN PetscErrorCode TaoGetDualVariables(Tao, Vec *, Vec *); 403 PETSC_EXTERN PetscErrorCode TaoSetInequalityBounds(Tao, Vec, Vec); 404 PETSC_EXTERN PetscErrorCode TaoGetInequalityBounds(Tao, Vec *, Vec *); 405 PETSC_EXTERN PetscErrorCode TaoSetVariableBoundsRoutine(Tao, PetscErrorCode (*)(Tao, Vec, Vec, PetscCtx), PetscCtx); 406 PETSC_EXTERN PetscErrorCode TaoComputeVariableBounds(Tao); 407 408 PETSC_EXTERN PetscErrorCode TaoGetTolerances(Tao, PetscReal *, PetscReal *, PetscReal *); 409 PETSC_EXTERN PetscErrorCode TaoSetTolerances(Tao, PetscReal, PetscReal, PetscReal); 410 PETSC_EXTERN PetscErrorCode TaoGetConstraintTolerances(Tao, PetscReal *, PetscReal *); 411 PETSC_EXTERN PetscErrorCode TaoSetConstraintTolerances(Tao, PetscReal, PetscReal); 412 PETSC_EXTERN PetscErrorCode TaoSetFunctionLowerBound(Tao, PetscReal); 413 PETSC_EXTERN PetscErrorCode TaoSetInitialTrustRegionRadius(Tao, PetscReal); 414 PETSC_EXTERN PetscErrorCode TaoSetMaximumIterations(Tao, PetscInt); 415 PETSC_EXTERN PetscErrorCode TaoSetMaximumFunctionEvaluations(Tao, PetscInt); 416 PETSC_EXTERN PetscErrorCode TaoGetFunctionLowerBound(Tao, PetscReal *); 417 PETSC_EXTERN PetscErrorCode TaoGetInitialTrustRegionRadius(Tao, PetscReal *); 418 PETSC_EXTERN PetscErrorCode TaoGetCurrentTrustRegionRadius(Tao, PetscReal *); 419 PETSC_EXTERN PetscErrorCode TaoGetMaximumIterations(Tao, PetscInt *); 420 PETSC_EXTERN PetscErrorCode TaoGetCurrentFunctionEvaluations(Tao, PetscInt *); 421 PETSC_EXTERN PetscErrorCode TaoGetMaximumFunctionEvaluations(Tao, PetscInt *); 422 PETSC_EXTERN PetscErrorCode TaoGetIterationNumber(Tao, PetscInt *); 423 PETSC_EXTERN PetscErrorCode TaoSetIterationNumber(Tao, PetscInt); 424 PETSC_EXTERN PetscErrorCode TaoGetTotalIterationNumber(Tao, PetscInt *); 425 PETSC_EXTERN PetscErrorCode TaoSetTotalIterationNumber(Tao, PetscInt); 426 PETSC_EXTERN PetscErrorCode TaoGetResidualNorm(Tao, PetscReal *); 427 428 PETSC_EXTERN PetscErrorCode TaoAppendOptionsPrefix(Tao, const char[]); 429 PETSC_EXTERN PetscErrorCode TaoGetOptionsPrefix(Tao, const char *[]); 430 PETSC_EXTERN PetscErrorCode TaoResetStatistics(Tao); 431 PETSC_EXTERN PetscErrorCode TaoSetUpdate(Tao, PetscErrorCode (*)(Tao, PetscInt, PetscCtx), PetscCtx); 432 433 PETSC_EXTERN PetscErrorCode TaoGetKSP(Tao, KSP *); 434 PETSC_EXTERN PetscErrorCode TaoGetLinearSolveIterations(Tao, PetscInt *); 435 PETSC_EXTERN PetscErrorCode TaoKSPSetUseEW(Tao, PetscBool); 436 437 #include <petsctaolinesearch.h> 438 439 PETSC_EXTERN PetscErrorCode TaoGetLineSearch(Tao, TaoLineSearch *); 440 441 PETSC_EXTERN PetscErrorCode TaoSetConvergenceHistory(Tao, PetscReal *, PetscReal *, PetscReal *, PetscInt *, PetscInt, PetscBool); 442 PETSC_EXTERN PetscErrorCode TaoGetConvergenceHistory(Tao, PetscReal **, PetscReal **, PetscReal **, PetscInt **, PetscInt *); 443 PETSC_EXTERN PetscErrorCode TaoMonitorSet(Tao, PetscErrorCode (*)(Tao, PetscCtx), PetscCtx, PetscCtxDestroyFn *); 444 PETSC_EXTERN PetscErrorCode TaoMonitorSetFromOptions(Tao tao, const char name[], const char help[], const char manual[], PetscErrorCode (*monitor)(Tao, PetscViewerAndFormat *)); 445 PETSC_EXTERN PetscErrorCode TaoMonitorCancel(Tao); 446 PETSC_EXTERN PetscErrorCode TaoMonitorDefault(Tao, PetscViewerAndFormat *); 447 PETSC_EXTERN PetscErrorCode TaoMonitorGlobalization(Tao, PetscViewerAndFormat *); 448 PETSC_EXTERN PetscErrorCode TaoMonitorDefaultShort(Tao, PetscViewerAndFormat *); 449 PETSC_EXTERN PetscErrorCode TaoMonitorConstraintNorm(Tao, PetscViewerAndFormat *); 450 PETSC_EXTERN PetscErrorCode TaoMonitorSolution(Tao, PetscViewerAndFormat *); 451 PETSC_EXTERN PetscErrorCode TaoMonitorResidual(Tao, PetscViewerAndFormat *); 452 PETSC_EXTERN PetscErrorCode TaoMonitorGradient(Tao, PetscViewerAndFormat *); 453 PETSC_EXTERN PetscErrorCode TaoMonitorStep(Tao, PetscViewerAndFormat *); 454 PETSC_EXTERN PetscErrorCode TaoMonitorSolutionDraw(Tao, PetscCtx); 455 PETSC_EXTERN PetscErrorCode TaoMonitorStepDraw(Tao, PetscCtx); 456 PETSC_EXTERN PetscErrorCode TaoMonitorGradientDraw(Tao, PetscCtx); 457 PETSC_EXTERN PetscErrorCode TaoAddLineSearchCounts(Tao); 458 459 PETSC_EXTERN PetscErrorCode TaoDefaultConvergenceTest(Tao, PetscCtx); 460 PETSC_EXTERN PetscErrorCode TaoSetConvergenceTest(Tao, PetscErrorCode (*)(Tao, PetscCtx), PetscCtx); 461 462 PETSC_EXTERN PetscErrorCode TaoLCLSetStateDesignIS(Tao, IS, IS); 463 PETSC_EXTERN PetscErrorCode TaoMonitor(Tao, PetscInt, PetscReal, PetscReal, PetscReal, PetscReal); 464 typedef struct _n_TaoMonitorDrawCtx *TaoMonitorDrawCtx; 465 PETSC_EXTERN PetscErrorCode TaoMonitorDrawCtxCreate(MPI_Comm, const char[], const char[], int, int, int, int, PetscInt, TaoMonitorDrawCtx *); 466 PETSC_EXTERN PetscErrorCode TaoMonitorDrawCtxDestroy(TaoMonitorDrawCtx *); 467 468 /*E 469 TaoBRGNRegularizationType - The regularization added in the `TAOBRGN` solver. 470 471 Values: 472 + TAOBRGN_REGULARIZATION_USER - A user-defined regularizer 473 . TAOBRGN_REGULARIZATION_L2PROX - $\tfrac{1}{2}\|x - x_k\|_2^$, where $x_k$ is the latest solution 474 . TAOBRGN_REGULARIZATION_L2PURE - $\tfrac{1}{2}\|x\|_2^2$ 475 . TAOBRGN_REGULARIZATION_L1DICT - $\|D x\|_1$, where $D$ is a dictionary matrix 476 - TAOBRGN_REGULARIZATION_LM - Levenberg-Marquardt, $\tfrac{1}{2} x^T \mathrm{diag}(J^T J) x$, where $J$ is the Jacobian of the least-squares residual 477 478 Options database Key: 479 . -tao_brgn_regularization_type <user,l2prox,l2pure,l1dict,lm> - one of the above regularization types 480 481 Level: advanced 482 483 Notes: 484 If `TAOBRGN_REGULARIZATION_USER`, the regularizer is set either by calling 485 `TaoBRGNSetRegularizerObjectiveAndGradientRoutine()` and 486 `TaoBRGNSetRegulazerHessianRoutine()` or by calling `TaoBRGNSetRegularizerTerm()`. 487 488 If `TAOBRGN_REGULARIZATION_L1DICT`, the dictionary matrix is set with `TaoBRGNSetDictionaryMatrix()` and the smoothing parameter of the 489 approximate $\ell_1$ norm is set with `TaoBRGNSetL1SmoothEpsilon()`. 490 491 If `TAOBRGN_REGULARIZATION_LM`, the diagonal damping vector $\mathrm{diag}(J^T J)$ can be obtained with `TaoBRGNGetDampingVector()`. 492 493 .seealso: [](ch_tao), `Tao`, `TaoBRGNGetSubsolver()`, `TaoBRGNSetRegularizerWeight()`, `TaoBRGNSetL1SmoothEpsilon()`, `TaoBRGNSetDictionaryMatrix()`, 494 `TaoBRGNSetRegularizerObjectiveAndGradientRoutine()`, `TaoBRGNSetRegularizerHessianRoutine()`, 495 `TaoBRGNGetRegularizationType()`, `TaoBRGNSetRegularizationType()` 496 E*/ 497 typedef enum { 498 TAOBRGN_REGULARIZATION_USER, 499 TAOBRGN_REGULARIZATION_L2PROX, 500 TAOBRGN_REGULARIZATION_L2PURE, 501 TAOBRGN_REGULARIZATION_L1DICT, 502 TAOBRGN_REGULARIZATION_LM, 503 } TaoBRGNRegularizationType; 504 505 PETSC_EXTERN const char *const TaoBRGNRegularizationTypes[]; 506 507 PETSC_EXTERN PetscErrorCode TaoBRGNGetSubsolver(Tao, Tao *); 508 PETSC_EXTERN PetscErrorCode TaoBRGNGetRegularizationType(Tao, TaoBRGNRegularizationType *); 509 PETSC_EXTERN PetscErrorCode TaoBRGNSetRegularizationType(Tao, TaoBRGNRegularizationType); 510 PETSC_EXTERN PetscErrorCode TaoBRGNSetRegularizerObjectiveAndGradientRoutine(Tao, PetscErrorCode (*)(Tao, Vec, PetscReal *, Vec, PetscCtx), PetscCtx); 511 PETSC_EXTERN PetscErrorCode TaoBRGNSetRegularizerHessianRoutine(Tao, Mat, PetscErrorCode (*)(Tao, Vec, Mat, PetscCtx), PetscCtx); 512 PETSC_EXTERN PetscErrorCode TaoBRGNSetRegularizerWeight(Tao, PetscReal); 513 PETSC_EXTERN PetscErrorCode TaoBRGNSetL1SmoothEpsilon(Tao, PetscReal); 514 PETSC_EXTERN PetscErrorCode TaoBRGNSetDictionaryMatrix(Tao, Mat); 515 PETSC_EXTERN PetscErrorCode TaoBRGNGetDampingVector(Tao, Vec *); 516 PETSC_EXTERN PetscErrorCode TaoBNCGSetType(Tao, TaoBNCGType); 517 PETSC_EXTERN PetscErrorCode TaoBNCGGetType(Tao, TaoBNCGType *); 518 519 PETSC_EXTERN PetscErrorCode TaoADMMGetMisfitSubsolver(Tao, Tao *); 520 PETSC_EXTERN PetscErrorCode TaoADMMGetRegularizationSubsolver(Tao, Tao *); 521 PETSC_EXTERN PetscErrorCode TaoADMMGetDualVector(Tao, Vec *); 522 PETSC_EXTERN PetscErrorCode TaoADMMGetSpectralPenalty(Tao, PetscReal *); 523 PETSC_EXTERN PetscErrorCode TaoADMMSetSpectralPenalty(Tao, PetscReal); 524 PETSC_EXTERN PetscErrorCode TaoGetADMMParentTao(Tao, Tao *); 525 PETSC_EXTERN PetscErrorCode TaoADMMSetConstraintVectorRHS(Tao, Vec); 526 PETSC_EXTERN PetscErrorCode TaoADMMSetRegularizerCoefficient(Tao, PetscReal); 527 PETSC_EXTERN PetscErrorCode TaoADMMGetRegularizerCoefficient(Tao, PetscReal *); 528 PETSC_EXTERN PetscErrorCode TaoADMMSetMisfitConstraintJacobian(Tao, Mat, Mat, PetscErrorCode (*)(Tao, Vec, Mat, Mat, PetscCtx), PetscCtx); 529 PETSC_EXTERN PetscErrorCode TaoADMMSetRegularizerConstraintJacobian(Tao, Mat, Mat, PetscErrorCode (*)(Tao, Vec, Mat, Mat, PetscCtx), PetscCtx); 530 PETSC_EXTERN PetscErrorCode TaoADMMSetRegularizerHessianRoutine(Tao, Mat, Mat, PetscErrorCode (*)(Tao, Vec, Mat, Mat, PetscCtx), PetscCtx); 531 PETSC_EXTERN PetscErrorCode TaoADMMSetRegularizerObjectiveAndGradientRoutine(Tao, PetscErrorCode (*)(Tao, Vec, PetscReal *, Vec, PetscCtx), PetscCtx); 532 PETSC_EXTERN PetscErrorCode TaoADMMSetMisfitHessianRoutine(Tao, Mat, Mat, PetscErrorCode (*)(Tao, Vec, Mat, Mat, PetscCtx), PetscCtx); 533 PETSC_EXTERN PetscErrorCode TaoADMMSetMisfitObjectiveAndGradientRoutine(Tao, PetscErrorCode (*)(Tao, Vec, PetscReal *, Vec, PetscCtx), PetscCtx); 534 PETSC_EXTERN PetscErrorCode TaoADMMSetMisfitHessianChangeStatus(Tao, PetscBool); 535 PETSC_EXTERN PetscErrorCode TaoADMMSetRegHessianChangeStatus(Tao, PetscBool); 536 PETSC_EXTERN PetscErrorCode TaoADMMSetMinimumSpectralPenalty(Tao, PetscReal); 537 PETSC_EXTERN PetscErrorCode TaoADMMSetRegularizerType(Tao, TaoADMMRegularizerType); 538 PETSC_EXTERN PetscErrorCode TaoADMMGetRegularizerType(Tao, TaoADMMRegularizerType *); 539 PETSC_EXTERN PetscErrorCode TaoADMMSetUpdateType(Tao, TaoADMMUpdateType); 540 PETSC_EXTERN PetscErrorCode TaoADMMGetUpdateType(Tao, TaoADMMUpdateType *); 541 542 PETSC_EXTERN PetscErrorCode TaoALMMGetType(Tao, TaoALMMType *); 543 PETSC_EXTERN PetscErrorCode TaoALMMSetType(Tao, TaoALMMType); 544 PETSC_EXTERN PetscErrorCode TaoALMMGetSubsolver(Tao, Tao *); 545 PETSC_EXTERN PetscErrorCode TaoALMMSetSubsolver(Tao, Tao); 546 PETSC_EXTERN PetscErrorCode TaoALMMGetMultipliers(Tao, Vec *); 547 PETSC_EXTERN PetscErrorCode TaoALMMSetMultipliers(Tao, Vec); 548 PETSC_EXTERN PetscErrorCode TaoALMMGetPrimalIS(Tao, IS *, IS *); 549 PETSC_EXTERN PetscErrorCode TaoALMMGetDualIS(Tao, IS *, IS *); 550 551 PETSC_EXTERN PetscErrorCode TaoVecGetSubVec(Vec, IS, TaoSubsetType, PetscReal, Vec *); 552 PETSC_EXTERN PetscErrorCode TaoMatGetSubMat(Mat, IS, Vec, TaoSubsetType, Mat *); 553 PETSC_EXTERN PetscErrorCode TaoGradientNorm(Tao, Vec, NormType, PetscReal *); 554 PETSC_EXTERN PetscErrorCode TaoEstimateActiveBounds(Vec, Vec, Vec, Vec, Vec, Vec, PetscReal, PetscReal *, IS *, IS *, IS *, IS *, IS *); 555 PETSC_EXTERN PetscErrorCode TaoBoundStep(Vec, Vec, Vec, IS, IS, IS, PetscReal, Vec); 556 PETSC_EXTERN PetscErrorCode TaoBoundSolution(Vec, Vec, Vec, PetscReal, PetscInt *, Vec); 557 558 PETSC_EXTERN PetscErrorCode MatCreateSubMatrixFree(Mat, IS, IS, Mat *); 559 560 #include <petsctao_deprecations.h> 561