35. Complementarity

Constraints in the form of nonlinear equations have the form C(X) = 0 where . These constraints should be specified in a routine, written by the user, that evaluates C(X). The routine that evaluates the constraint equations should have the form:

   int EqualityConstraints(TAO_APPLICATION,Vec,Vec,void*); 
The first argument of this routine is a TAO application object. The second argument is the variable vector at which the constraint function should be evaluated. The third argument is the vector of function values C, and the fourth argument is a pointer to a user-defined context. This routine and the user-defined context should be set in the TAO solver with the command
   TaoAppSetConstraintRoutine(TAO_APPLICATION, 
                               int (*)(TAO_APPLICATION,Vec,Vec,void*), 
                               void*); 
In this function, first argument is the TAO application, the second argument is vector in which to store the function values, and the third argument is a pointer to a user-defined context that will be passed back to the user.

The Jacobian of the function C is the matrix in such that each column contains the partial derivatives of f with respect to one variable. The evaluation of the Jacobian of f should be performed in a routine of the form

   int J(TAO_APPLICATION,Vec,Mat*,Mat*,MatStructure*,void*); 
In this function, the second argument is the variable vector at which to evaluate the Jacobian matrix, the third argument is the Jacobian matrix, and the sixth argument is a pointer to a user-defined context. This routine should be specified using
   TaoAppSetJacobianRoutine(TAO_APPLICATION,Mat, 
                int (*)(TAO_APPLICATION,Vec,Mat*,Mat*, MatStructure*,void*),  
                void*); 
The first argument is the TAO application, the second argument is the matrix in which the information can be stored, the third argument is the function pointer, and the fourth argument is an optional user-defined context. The Jacobian matrix should be created in a way such that the product of it and the variable vector can be put in the constraint vector.

For solvers that evaluate the Jacobian, the matrices used to store the Jacobian should be set using

   TaoAppSetJacobianMat(TAO_APPLICATION,Mat,Mat); 
The first argument is the TAO application, the second argument is the Jacobian matrix, and the third argument is the preconditioning matrix. In most applications, these two matrices will be the same structure.