1: #include <petsc-private/taoimpl.h> /*I "petsctao.h" I*/
5: /*@C
6: TaoSetHessianRoutine - Sets the function to compute the Hessian as well as the location to store the matrix.
8: Logically collective on Tao
10: Input Parameters:
11: + tao - the Tao context
12: . H - Matrix used for the hessian
13: . Hpre - Matrix that will be used operated on by preconditioner, can be same as H
14: . hess - Hessian evaluation routine
15: - ctx - [optional] user-defined context for private data for the
16: Hessian evaluation routine (may be NULL)
18: Calling sequence of hess:
19: $ hess (Tao tao,Vec x,Mat *H,Mat *Hpre,MatStructure *flag,void *ctx);
21: + tao - the Tao context
22: . x - input vector
23: . H - Hessian matrix
24: . Hpre - preconditioner matrix, usually the same as H
25: . flag - flag indicating information about the preconditioner matrix
26: structure (see below)
27: - ctx - [optional] user-defined Hessian context
30: Notes:
32: The function hess() takes Mat * as the matrix arguments rather than Mat.
33: This allows the Hessian evaluation routine to replace A and/or B with a
34: completely new new matrix structure (not just different matrix elements)
35: when appropriate, for instance, if the nonzero structure is changing
36: throughout the global iterations.
38: The flag can be used to eliminate unnecessary work in the preconditioner
39: during the repeated solution of linear systems of the same size. The
40: available options are
41: $ SAME_PRECONDITIONER -
42: $ Hpre is identical during successive linear solves.
43: $ This option is intended for folks who are using
44: $ different Amat and Pmat matrices and want to reuse the
45: $ same preconditioner matrix. For example, this option
46: $ saves work by not recomputing incomplete factorization
47: $ for ILU/ICC preconditioners.
48: $ SAME_NONZERO_PATTERN -
49: $ Hpre has the same nonzero structure during
50: $ successive linear solves.
51: $ DIFFERENT_NONZERO_PATTERN -
52: $ Hpre does not have the same nonzero structure.
54: Caution:
55: If you specify SAME_NONZERO_PATTERN, the software believes your assertion
56: and does not check the structure of the matrix. If you erroneously
57: claim that the structure is the same when it actually is not, the new
58: preconditioner will not function correctly. Thus, use this optimization
59: feature carefully!
61: If in doubt about whether your preconditioner matrix has changed
62: structure or not, use the flag DIFFERENT_NONZERO_PATTERN.
64: Level: beginner
66: @*/
67: PetscErrorCodeTaoSetHessianRoutine(Tao tao, Mat H, Mat Hpre, PetscErrorCode (*func)(Tao, Vec, Mat*, Mat *, MatStructure *, void*), void *ctx) 68: {
73: if (H) {
76: }
77: if (Hpre) {
80: }
81: if (ctx) {
82: tao->user_hessP = ctx;
83: }
84: if (func) {
85: tao->ops->computehessian = func;
86: }
87: if (H) {
88: PetscObjectReference((PetscObject)H);
89: MatDestroy(&tao->hessian);
90: tao->hessian = H;
91: }
92: if (Hpre) {
93: PetscObjectReference((PetscObject)Hpre);
94: MatDestroy(&tao->hessian_pre);
95: tao->hessian_pre = Hpre;
96: }
97: return(0);
98: }
102: /*@C
103: TaoComputeHessian - Computes the Hessian matrix that has been
104: set with TaoSetHessianRoutine().
106: Collective on Tao
108: Input Parameters:
109: + solver - the Tao solver context
110: - xx - input vector
112: Output Parameters:
113: + H - Hessian matrix
114: . Hpre - Preconditioning matrix
115: - flag - flag indicating matrix structure (SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN, or SAME_PRECONDITIONER)
117: Notes:
118: Most users should not need to explicitly call this routine, as it
119: is used internally within the minimization solvers.
121: TaoComputeHessian() is typically used within minimization
122: implementations, so most users would not generally call this routine
123: themselves.
125: Level: developer
127: .seealso: TaoComputeObjective(), TaoComputeObjectiveAndGradient(), TaoSetHessian()
129: @*/
130: PetscErrorCodeTaoComputeHessian(Tao tao, Vec X, Mat *H, Mat *Hpre, MatStructure *flg)131: {
140: if (!tao->ops->computehessian) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call TaoSetHessian() first");
141: *flg = DIFFERENT_NONZERO_PATTERN;
142: ++tao->nhess;
143: PetscLogEventBegin(Tao_HessianEval,tao,X,*H,*Hpre);
144: PetscStackPush("Tao user Hessian function");
145: (*tao->ops->computehessian)(tao,X,H,Hpre,flg,tao->user_hessP);
146: PetscStackPop;
147: PetscLogEventEnd(Tao_HessianEval,tao,X,*H,*Hpre);
148: return(0);
149: }
153: /*@C
154: TaoComputeJacobian - Computes the Jacobian matrix that has been
155: set with TaoSetJacobianRoutine().
157: Collective on Tao
159: Input Parameters:
160: + solver - the Tao solver context
161: - xx - input vector
163: Output Parameters:
164: + H - Jacobian matrix
165: . Hpre - Preconditioning matrix
166: - flag - flag indicating matrix structure (SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN, or SAME_PRECONDITIONER)
168: Notes:
169: Most users should not need to explicitly call this routine, as it
170: is used internally within the minimization solvers.
172: TaoComputeJacobian() is typically used within minimization
173: implementations, so most users would not generally call this routine
174: themselves.
176: Level: developer
178: .seealso: TaoComputeObjective(), TaoComputeObjectiveAndGradient(), TaoSetJacobian()
180: @*/
181: PetscErrorCodeTaoComputeJacobian(Tao tao, Vec X, Mat *J, Mat *Jpre, MatStructure *flg)182: {
191: if (!tao->ops->computejacobian) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call TaoSetJacobian() first");
192: *flg = DIFFERENT_NONZERO_PATTERN;
193: ++tao->njac;
194: PetscLogEventBegin(Tao_JacobianEval,tao,X,*J,*Jpre);
195: PetscStackPush("Tao user Jacobian function");
196: (*tao->ops->computejacobian)(tao,X,J,Jpre,flg,tao->user_jacP);
197: PetscStackPop;
198: PetscLogEventEnd(Tao_JacobianEval,tao,X,*J,*Jpre);
199: return(0);
200: }
204: /*@C
205: TaoComputeJacobianState - Computes the Jacobian matrix that has been
206: set with TaoSetJacobianStateRoutine().
208: Collective on Tao
210: Input Parameters:
211: + solver - the Tao solver context
212: - xx - input vector
214: Output Parameters:
215: + H - Jacobian matrix
216: . Hpre - Preconditioning matrix
217: - flag - flag indicating matrix structure (SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN, or SAME_PRECONDITIONER)
219: Notes:
220: Most users should not need to explicitly call this routine, as it
221: is used internally within the minimization solvers.
223: TaoComputeJacobianState() is typically used within minimization
224: implementations, so most users would not generally call this routine
225: themselves.
227: Level: developer
229: .seealso: TaoComputeObjective(), TaoComputeObjectiveAndGradient(), TaoSetJacobianStateRoutine(), TaoComputeJacobianDesign(), TaoSetStateDesignIS()
231: @*/
232: PetscErrorCodeTaoComputeJacobianState(Tao tao, Vec X, Mat *J, Mat *Jpre, Mat *Jinv, MatStructure *flg)233: {
242: if (!tao->ops->computejacobianstate) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call TaoSetJacobianState() first");
243: *flg = DIFFERENT_NONZERO_PATTERN;
244: ++tao->njac_state;
245: PetscLogEventBegin(Tao_JacobianEval,tao,X,*J,*Jpre);
246: PetscStackPush("Tao user Jacobian(state) function");
247: (*tao->ops->computejacobianstate)(tao,X,J,Jpre,Jinv,flg,tao->user_jac_stateP);
248: PetscStackPop;
249: PetscLogEventEnd(Tao_JacobianEval,tao,X,*J,*Jpre);
250: return(0);
251: }
255: /*@C
256: TaoComputeJacobianDesign - Computes the Jacobian matrix that has been
257: set with TaoSetJacobianDesignRoutine().
259: Collective on Tao
261: Input Parameters:
262: + solver - the Tao solver context
263: - xx - input vector
265: Output Parameters:
266: . H - Jacobian matrix
268: Notes:
269: Most users should not need to explicitly call this routine, as it
270: is used internally within the minimization solvers.
272: TaoComputeJacobianDesign() is typically used within minimization
273: implementations, so most users would not generally call this routine
274: themselves.
276: Level: developer
278: .seealso: TaoComputeObjective(), TaoComputeObjectiveAndGradient(), TaoSetJacobianDesignRoutine(), TaoComputeJacobianDesign(), TaoSetStateDesignIS()
280: @*/
281: PetscErrorCodeTaoComputeJacobianDesign(Tao tao, Vec X, Mat *J)282: {
290: if (!tao->ops->computejacobiandesign) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call TaoSetJacobianDesign() first");
291: ++tao->njac_design;
292: PetscLogEventBegin(Tao_JacobianEval,tao,X,*J,NULL);
293: PetscStackPush("Tao user Jacobian(design) function");
294: (*tao->ops->computejacobiandesign)(tao,X,J,tao->user_jac_designP);
295: PetscStackPop;
296: PetscLogEventEnd(Tao_JacobianEval,tao,X,*J,NULL);
297: return(0);
298: }
302: /*@C
303: TaoSetJacobianRoutine - Sets the function to compute the Jacobian as well as the location to store the matrix.
305: Logically collective on Tao
307: Input Parameters:
308: + tao - the Tao context
309: . J - Matrix used for the jacobian
310: . Jpre - Matrix that will be used operated on by preconditioner, can be same as J
311: . jac - Jacobian evaluation routine
312: - ctx - [optional] user-defined context for private data for the
313: Jacobian evaluation routine (may be NULL)
315: Calling sequence of jac:
316: $ jac (Tao tao,Vec x,Mat *J,Mat *Jpre,MatStructure *flag,void *ctx);
318: + tao - the Tao context
319: . x - input vector
320: . J - Jacobian matrix
321: . Jpre - preconditioner matrix, usually the same as J
322: . flag - flag indicating information about the preconditioner matrix
323: structure (see below)
324: - ctx - [optional] user-defined Jacobian context
326: Notes:
328: The function jac() takes Mat * as the matrix arguments rather than Mat.
329: This allows the Jacobian evaluation routine to replace A and/or B with a
330: completely new new matrix structure (not just different matrix elements)
331: when appropriate, for instance, if the nonzero structure is changing
332: throughout the global iterations.
334: The flag can be used to eliminate unnecessary work in the preconditioner
335: during the repeated solution of linear systems of the same size. The
336: available options are
337: $ SAME_PRECONDITIONER -
338: $ Jpre is identical during successive linear solves.
339: $ This option is intended for folks who are using
340: $ different Amat and Pmat matrices and want to reuse the
341: $ same preconditioner matrix. For example, this option
342: $ saves work by not recomputing incomplete factorization
343: $ for ILU/ICC preconditioners.
344: $ SAME_NONZERO_PATTERN -
345: $ Jpre has the same nonzero structure during
346: $ successive linear solves.
347: $ DIFFERENT_NONZERO_PATTERN -
348: $ Jpre does not have the same nonzero structure.
350: Caution:
351: If you specify SAME_NONZERO_PATTERN, the software believes your assertion
352: and does not check the structure of the matrix. If you erroneously
353: claim that the structure is the same when it actually is not, the new
354: preconditioner will not function correctly. Thus, use this optimization
355: feature carefully!
357: If in doubt about whether your preconditioner matrix has changed
358: structure or not, use the flag DIFFERENT_NONZERO_PATTERN.
360: Level: intermediate
362: @*/
363: PetscErrorCodeTaoSetJacobianRoutine(Tao tao, Mat J, Mat Jpre, PetscErrorCode (*func)(Tao, Vec, Mat*, Mat *, MatStructure *, void*), void *ctx)364: {
368: if (J) {
371: }
372: if (Jpre) {
375: }
376: if (ctx) {
377: tao->user_jacP = ctx;
378: }
379: if (func) {
380: tao->ops->computejacobian = func;
381: }
382: if (J) {
383: PetscObjectReference((PetscObject)J);
384: MatDestroy(&tao->jacobian);
385: tao->jacobian = J;
386: }
387: if (Jpre) {
388: PetscObjectReference((PetscObject)Jpre);
389: MatDestroy(&tao->jacobian_pre);
390: tao->jacobian_pre=Jpre;
391: }
392: return(0);
393: }
397: /*@C
398: TaoSetJacobianStateRoutine - Sets the function to compute the Jacobian
399: (and its inverse) of the constraint function with respect to the state variables.
400: Used only for pde-constrained optimization.
402: Logically collective on Tao
404: Input Parameters:
405: + tao - the Tao context
406: . J - Matrix used for the jacobian
407: . Jpre - Matrix that will be used operated on by PETSc preconditioner, can be same as J. Only used if Jinv is NULL
408: . Jinv - [optional] Matrix used to apply the inverse of the state jacobian. Use NULL to default to PETSc KSP solvers to apply the inverse.
409: . jac - Jacobian evaluation routine
410: - ctx - [optional] user-defined context for private data for the
411: Jacobian evaluation routine (may be NULL)
413: Calling sequence of jac:
414: $ jac (Tao tao,Vec x,Mat *J,Mat *Jpre,MatStructure *flag,void *ctx);
416: + tao - the Tao context
417: . x - input vector
418: . J - Jacobian matrix
419: . Jpre - preconditioner matrix, usually the same as J
420: . Jinv - inverse of J
421: . flag - flag indicating information about the preconditioner matrix
422: structure (see below)
423: - ctx - [optional] user-defined Jacobian context
426: Notes:
427: Because of the structure of the jacobian matrix,
428: It may be more efficient for a pde-constrained application to provide
429: its own Jinv matrix.
431: The function jac() takes Mat * as the matrix arguments rather than Mat.
432: This allows the Jacobian evaluation routine to replace A and/or B with a
433: completely new new maitrix structure (not just different matrix elements)
434: when appropriate, for instance, if the nonzero structure is changing
435: throughout the global iterations.
437: The flag can be used to eliminate unnecessary work in the preconditioner
438: during the repeated solution of linear systems of the same size. The
439: available options are
440: $ SAME_PRECONDITIONER -
441: $ Jpre is identical during successive linear solves.
442: $ This option is intended for folks who are using
443: $ different Amat and Pmat matrices and want to reuse the
444: $ same preconditioner matrix. For example, this option
445: $ saves work by not recomputing incomplete factorization
446: $ for ILU/ICC preconditioners.
447: $ SAME_NONZERO_PATTERN -
448: $ Jpre has the same nonzero structure during
449: $ successive linear solves.
450: $ DIFFERENT_NONZERO_PATTERN -
451: $ Jpre does not have the same nonzero structure.
453: Caution:
454: If you specify SAME_NONZERO_PATTERN, the software believes your assertion
455: and does not check the structure of the matrix. If you erroneously
456: claim that the structure is the same when it actually is not, the new
457: preconditioner will not function correctly. Thus, use this optimization
458: feature carefully!
460: If in doubt about whether your preconditioner matrix has changed
461: structure or not, use the flag DIFFERENT_NONZERO_PATTERN.
463: Level: intermediate
464: .seealse: TaoComputeJacobianState(), TaoSetJacobianDesignRoutine(), TaoSetStateDesignIS()
465: @*/
466: PetscErrorCodeTaoSetJacobianStateRoutine(Tao tao, Mat J, Mat Jpre, Mat Jinv, PetscErrorCode (*func)(Tao, Vec, Mat*, Mat *, Mat *, MatStructure *, void*), void *ctx)467: {
471: if (J) {
474: }
475: if (Jpre) {
478: }
479: if (Jinv) {
482: }
483: if (ctx) {
484: tao->user_jac_stateP = ctx;
485: }
486: if (func) {
487: tao->ops->computejacobianstate = func;
488: }
489: if (J) {
490: PetscObjectReference((PetscObject)J);
491: MatDestroy(&tao->jacobian_state);
492: tao->jacobian_state = J;
493: }
494: if (Jpre) {
495: PetscObjectReference((PetscObject)Jpre);
496: MatDestroy(&tao->jacobian_state_pre);
497: tao->jacobian_state_pre=Jpre;
498: }
499: if (Jinv) {
500: PetscObjectReference((PetscObject)Jinv);
501: MatDestroy(&tao->jacobian_state_inv);
502: tao->jacobian_state_inv=Jinv;
503: }
504: return(0);
505: }
509: /*@C
510: TaoSetJacobianDesignRoutine - Sets the function to compute the Jacobian of
511: the constraint function with respect to the design variables. Used only for
512: pde-constrained optimization.
514: Logically collective on Tao
516: Input Parameters:
517: + tao - the Tao context
518: . J - Matrix used for the jacobian
519: . jac - Jacobian evaluation routine
520: - ctx - [optional] user-defined context for private data for the
521: Jacobian evaluation routine (may be NULL)
523: Calling sequence of jac:
524: $ jac (Tao tao,Vec x,Mat *J,void *ctx);
526: + tao - the Tao context
527: . x - input vector
528: . J - Jacobian matrix
529: - ctx - [optional] user-defined Jacobian context
532: Notes:
534: The function jac() takes Mat * as the matrix arguments rather than Mat.
535: This allows the Jacobian evaluation routine to replace A and/or B with a
536: completely new new matrix structure (not just different matrix elements)
537: when appropriate, for instance, if the nonzero structure is changing
538: throughout the global iterations.
540: Level: intermediate
541: .seealso: TaoComputeJacobianDesign(), TaoSetJacobianStateRoutine(), TaoSetStateDesignIS()
542: @*/
543: PetscErrorCodeTaoSetJacobianDesignRoutine(Tao tao, Mat J, PetscErrorCode (*func)(Tao, Vec, Mat*, void*), void *ctx)544: {
549: if (J) {
552: }
553: if (ctx) {
554: tao->user_jac_designP = ctx;
555: }
556: if (func) {
557: tao->ops->computejacobiandesign = func;
558: }
559: if (J) {
560: PetscObjectReference((PetscObject)J);
561: MatDestroy(&tao->jacobian_design);
562: tao->jacobian_design = J;
563: }
564: return(0);
565: }
569: /*@
570: TaoSetStateDesignIS - Indicate to the Tao which variables in the
571: solution vector are state variables and which are design. Only applies to
572: pde-constrained optimization.
574: Logically Collective on Tao
576: Input Parameters:
577: + tao - The Tao context
578: . s_is - the index set corresponding to the state variables
579: - d_is - the index set corresponding to the design variables
581: Level: intermediate
583: .seealso: TaoSetJacobianStateRoutine(), TaoSetJacobianDesignRoutine()
584: @*/
585: PetscErrorCodeTaoSetStateDesignIS(Tao tao, IS s_is, IS d_is)586: {
590: PetscObjectReference((PetscObject)s_is);
591: ISDestroy(&tao->state_is);
592: tao->state_is = s_is;
593: PetscObjectReference((PetscObject)(d_is));
594: ISDestroy(&tao->design_is);
595: tao->design_is = d_is;
596: return(0);
597: }
601: /*@C
602: TaoComputeJacobianEquality - Computes the Jacobian matrix that has been
603: set with TaoSetJacobianEqualityRoutine().
605: Collective on Tao
607: Input Parameters:
608: + solver - the Tao solver context
609: - xx - input vector
611: Output Parameters:
612: + H - Jacobian matrix
613: . Hpre - Preconditioning matrix
614: - flag - flag indicating matrix structure (SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN, or SAME_PRECONDITIONER)
616: Notes:
617: Most users should not need to explicitly call this routine, as it
618: is used internally within the minimization solvers.
620: Level: developer
622: .seealso: TaoComputeObjective(), TaoComputeObjectiveAndGradient(), TaoSetJacobianStateRoutine(), TaoComputeJacobianDesign(), TaoSetStateDesignIS()
624: @*/
625: PetscErrorCodeTaoComputeJacobianEquality(Tao tao, Vec X, Mat *J, Mat *Jpre, MatStructure *flg)626: {
635: if (!tao->ops->computejacobianequality) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call TaoSetJacobianEquality() first");
636: *flg = DIFFERENT_NONZERO_PATTERN;
637: ++tao->njac_equality;
638: PetscLogEventBegin(Tao_JacobianEval,tao,X,*J,*Jpre);
639: PetscStackPush("Tao user Jacobian(equality) function");
640: (*tao->ops->computejacobianequality)(tao,X,J,Jpre,flg,tao->user_jac_equalityP);
641: PetscStackPop;
642: PetscLogEventEnd(Tao_JacobianEval,tao,X,*J,*Jpre);
643: return(0);
644: }
648: /*@C
649: TaoComputeJacobianInequality - Computes the Jacobian matrix that has been
650: set with TaoSetJacobianInequalityRoutine().
652: Collective on Tao
654: Input Parameters:
655: + solver - the Tao solver context
656: - xx - input vector
658: Output Parameters:
659: + H - Jacobian matrix
660: . Hpre - Preconditioning matrix
661: - flag - flag indicating matrix structure (SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN, or SAME_PRECONDITIONER)
663: Notes:
664: Most users should not need to explicitly call this routine, as it
665: is used internally within the minimization solvers.
667: Level: developer
669: .seealso: TaoComputeObjective(), TaoComputeObjectiveAndGradient(), TaoSetJacobianStateRoutine(), TaoComputeJacobianDesign(), TaoSetStateDesignIS()
671: @*/
672: PetscErrorCodeTaoComputeJacobianInequality(Tao tao, Vec X, Mat *J, Mat *Jpre, MatStructure *flg)673: {
682: if (!tao->ops->computejacobianinequality) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call TaoSetJacobianInequality() first");
683: *flg = DIFFERENT_NONZERO_PATTERN;
684: ++tao->njac_inequality;
685: PetscLogEventBegin(Tao_JacobianEval,tao,X,*J,*Jpre);
686: PetscStackPush("Tao user Jacobian(inequality) function");
687: (*tao->ops->computejacobianinequality)(tao,X,J,Jpre,flg,tao->user_jac_inequalityP);
688: PetscStackPop;
689: PetscLogEventEnd(Tao_JacobianEval,tao,X,*J,*Jpre);
690: return(0);
691: }
695: /*@C
696: TaoSetJacobianEqualityRoutine - Sets the function to compute the Jacobian
697: (and its inverse) of the constraint function with respect to the equality variables.
698: Used only for pde-constrained optimization.
700: Logically collective on Tao
702: Input Parameters:
703: + tao - the Tao context
704: . J - Matrix used for the jacobian
705: . Jpre - Matrix that will be used operated on by PETSc preconditioner, can be same as J.
706: . jac - Jacobian evaluation routine
707: - ctx - [optional] user-defined context for private data for the
708: Jacobian evaluation routine (may be NULL)
710: Calling sequence of jac:
711: $ jac (Tao tao,Vec x,Mat *J,Mat *Jpre,MatStructure *flag,void *ctx);
713: + tao - the Tao context
714: . x - input vector
715: . J - Jacobian matrix
716: . Jpre - preconditioner matrix, usually the same as J
717: . flag - flag indicating information about the preconditioner matrix
718: structure (see below)
719: - ctx - [optional] user-defined Jacobian context
721: Notes:
722: Because of the structure of the jacobian matrix,
723: It may be more efficient for a pde-constrained application to provide
724: its own Jinv matrix.
726: The function jac() takes Mat * as the matrix arguments rather than Mat.
727: This allows the Jacobian evaluation routine to replace A and/or B with a
728: completely new new maitrix structure (not just different matrix elements)
729: when appropriate, for instance, if the nonzero structure is changing
730: throughout the global iterations.
732: The flag can be used to eliminate unnecessary work in the preconditioner
733: during the repeated solution of linear systems of the same size. The
734: available options are
735: $ SAME_PRECONDITIONER -
736: $ Jpre is identical during successive linear solves.
737: $ This option is intended for folks who are using
738: $ different Amat and Pmat matrices and want to reuse the
739: $ same preconditioner matrix. For example, this option
740: $ saves work by not recomputing incomplete factorization
741: $ for ILU/ICC preconditioners.
742: $ SAME_NONZERO_PATTERN -
743: $ Jpre has the same nonzero structure during
744: $ successive linear solves.
745: $ DIFFERENT_NONZERO_PATTERN -
746: $ Jpre does not have the same nonzero structure.
748: Caution:
749: If you specify SAME_NONZERO_PATTERN, the software believes your assertion
750: and does not check the structure of the matrix. If you erroneously
751: claim that the structure is the same when it actually is not, the new
752: preconditioner will not function correctly. Thus, use this optimization
753: feature carefully!
755: If in doubt about whether your preconditioner matrix has changed
756: structure or not, use the flag DIFFERENT_NONZERO_PATTERN.
758: Level: intermediate
759: .seealse: TaoComputeJacobianEquality(), TaoSetJacobianDesignRoutine(), TaoSetEqualityDesignIS()
760: @*/
761: PetscErrorCodeTaoSetJacobianEqualityRoutine(Tao tao, Mat J, Mat Jpre, PetscErrorCode (*func)(Tao, Vec, Mat*, Mat *, MatStructure *, void*), void *ctx)762: {
767: if (J) {
770: }
771: if (Jpre) {
774: }
775: if (ctx) {
776: tao->user_jac_equalityP = ctx;
777: }
778: if (func) {
779: tao->ops->computejacobianequality = func;
780: }
781: if (J) {
782: PetscObjectReference((PetscObject)J);
783: MatDestroy(&tao->jacobian_equality);
784: tao->jacobian_equality = J;
785: }
786: if (Jpre) {
787: PetscObjectReference((PetscObject)Jpre);
788: MatDestroy(&tao->jacobian_equality_pre);
789: tao->jacobian_equality_pre=Jpre;
790: }
791: return(0);
792: }
796: /*@C
797: TaoSetJacobianInequalityRoutine - Sets the function to compute the Jacobian
798: (and its inverse) of the constraint function with respect to the inequality variables.
799: Used only for pde-constrained optimization.
801: Logically collective on Tao
803: Input Parameters:
804: + tao - the Tao context
805: . J - Matrix used for the jacobian
806: . Jpre - Matrix that will be used operated on by PETSc preconditioner, can be same as J.
807: . jac - Jacobian evaluation routine
808: - ctx - [optional] user-defined context for private data for the
809: Jacobian evaluation routine (may be NULL)
811: Calling sequence of jac:
812: $ jac (Tao tao,Vec x,Mat *J,Mat *Jpre,MatStructure *flag,void *ctx);
814: + tao - the Tao context
815: . x - input vector
816: . J - Jacobian matrix
817: . Jpre - preconditioner matrix, usually the same as J
818: . flag - flag indicating information about the preconditioner matrix
819: structure (see below)
820: - ctx - [optional] user-defined Jacobian context
823: Notes:
824: Because of the structure of the jacobian matrix,
825: It may be more efficient for a pde-constrained application to provide
826: its own Jinv matrix.
828: The function jac() takes Mat * as the matrix arguments rather than Mat.
829: This allows the Jacobian evaluation routine to replace A and/or B with a
830: completely new new maitrix structure (not just different matrix elements)
831: when appropriate, for instance, if the nonzero structure is changing
832: throughout the global iterations.
834: The flag can be used to eliminate unnecessary work in the preconditioner
835: during the repeated solution of linear systems of the same size. The
836: available options are
837: $ SAME_PRECONDITIONER -
838: $ Jpre is identical during successive linear solves.
839: $ This option is intended for folks who are using
840: $ different Amat and Pmat matrices and want to reuse the
841: $ same preconditioner matrix. For example, this option
842: $ saves work by not recomputing incomplete factorization
843: $ for ILU/ICC preconditioners.
844: $ SAME_NONZERO_PATTERN -
845: $ Jpre has the same nonzero structure during
846: $ successive linear solves.
847: $ DIFFERENT_NONZERO_PATTERN -
848: $ Jpre does not have the same nonzero structure.
850: Caution:
851: If you specify SAME_NONZERO_PATTERN, the software believes your assertion
852: and does not check the structure of the matrix. If you erroneously
853: claim that the structure is the same when it actually is not, the new
854: preconditioner will not function correctly. Thus, use this optimization
855: feature carefully!
857: If in doubt about whether your preconditioner matrix has changed
858: structure or not, use the flag DIFFERENT_NONZERO_PATTERN.
860: Level: intermediate
861: .seealse: TaoComputeJacobianInequality(), TaoSetJacobianDesignRoutine(), TaoSetInequalityDesignIS()
862: @*/
863: PetscErrorCodeTaoSetJacobianInequalityRoutine(Tao tao, Mat J, Mat Jpre, PetscErrorCode (*func)(Tao, Vec, Mat*, Mat *, MatStructure *, void*), void *ctx)864: {
868: if (J) {
871: }
872: if (Jpre) {
875: }
876: if (ctx) {
877: tao->user_jac_inequalityP = ctx;
878: }
879: if (func) {
880: tao->ops->computejacobianinequality = func;
881: }
882: if (J) {
883: PetscObjectReference((PetscObject)J);
884: MatDestroy(&tao->jacobian_inequality);
885: tao->jacobian_inequality = J;
886: }
887: if (Jpre) {
888: PetscObjectReference((PetscObject)Jpre);
889: MatDestroy(&tao->jacobian_inequality_pre);
890: tao->jacobian_inequality_pre=Jpre;
891: }
892: return(0);
893: }