Actual source code: taosolver_hj.c

petsc-dev 2014-02-02
Report Typos and Errors
  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: PetscErrorCode TaoSetHessianRoutine(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: PetscErrorCode TaoComputeHessian(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: PetscErrorCode TaoComputeJacobian(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: PetscErrorCode TaoComputeJacobianState(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: PetscErrorCode TaoComputeJacobianDesign(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: PetscErrorCode TaoSetJacobianRoutine(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: PetscErrorCode TaoSetJacobianStateRoutine(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: PetscErrorCode TaoSetJacobianDesignRoutine(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: PetscErrorCode TaoSetStateDesignIS(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: PetscErrorCode TaoComputeJacobianEquality(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: PetscErrorCode TaoComputeJacobianInequality(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: PetscErrorCode TaoSetJacobianEqualityRoutine(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: PetscErrorCode TaoSetJacobianInequalityRoutine(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: }