API

As stated in the Home page, we consider the nonlinear optimization problem in the following format:

\[\begin{aligned} \min \quad & f(x) \\ & c_L \leq c(x) \leq c_U \\ & \ell \leq x \leq u. \end{aligned}\]

To develop an optimization algorithm, we are usually worried not only with $f(x)$ and $c(x)$, but also with their derivatives. Namely,

  • $\nabla f(x)$, the gradient of $f$ at the point $x$;
  • $\nabla^2 f(x)$, the Hessian of $f$ at the point $x$;
  • $J(x) = \nabla c(x)^T$, the Jacobian of $c$ at the point $x$;
  • $\nabla^2 f(x) + \sum_{i=1}^m y_i \nabla^2 c_i(x)$, the Hessian of the Lagrangian function at the point $(x,y)$.

There are many ways to access some of these values, so here is a little reference guide.

Reference guide

The following naming should be easy enough to follow. If not, click on the link and go to the description.

  • ! means inplace;
  • _coord means coordinate format;
  • prod means matrix-vector product;
  • _op means operator (as in LinearOperators.jl);
  • _lin and _nln respectively refer to linear and nonlinear constraints.

Feel free to open an issue to suggest other methods that should apply to all NLPModels instances.

FunctionNLPModels function
$f(x)$obj, objgrad, objgrad!, objcons, objcons!
$\nabla f(x)$grad, grad!, objgrad, objgrad!
$\nabla^2 f(x)$hess, hess_op, hess_op!, hess_coord, hess_coord, hess_structure, hess_structure!, hprod, hprod!
$c(x)$cons_lin, cons_lin!, cons_nln, cons_nln!, cons, cons!, objcons, objcons!
$J(x)$jac_lin, jac_nln, jac, jac_lin_op, jac_lin_op!, jac_nln_op, jac_nln_op!,jac_op, jac_op!, jac_lin_coord, jac_lin_coord!, jac_nln_coord, jac_nln_coord!, jac_coord, jac_coord!, jac_lin_structure, jac_lin_structure!, jac_nln_structure, jac_nln_structure!, jac_structure, jprod_lin, jprod_lin!, jprod_nln, jprod_nln!, jprod, jprod!, jtprod_lin, jtprod_lin!, jtprod_nln, jtprod_nln!, jtprod, jtprod!
$\nabla^2 L(x,y)$hess, hess_op, hess_coord, hess_coord!, hess_structure, hess_structure!, hprod, hprod!, jth_hprod, jth_hprod!, jth_hess, jth_hess_coord, jth_hess_coord!, ghjvprod, ghjvprod!

API for NLSModels

For the Nonlinear Least Squares models, $f(x) = \tfrac{1}{2} \Vert F(x)\Vert^2$, and these models have additional function to access the residual value and its derivatives. Namely,

  • $J_F(x) = \nabla F(x)^T$
  • $\nabla^2 F_i(x)$
Functionfunction
$F(x)$residual, residual!
$J_F(x)$jac_residual, jac_coord_residual, jac_coord_residual!, jac_structure_residual, jac_structure_residual!, jprod_residual, jprod_residual!, jtprod_residual, jtprod_residual!, jac_op_residual, jac_op_residual!
$\nabla^2 F_i(x)$hess_residual, hess_coord_residual, hess_coord_residual!, hess_structure_residual, hess_structure_residual!, jth_hess_residual, hprod_residual, hprod_residual!, hess_op_residual, hess_op_residual!