Skip to content

api.md

Latest commit

 

History

History
68 lines (54 loc) · 5.18 KB

api.md

File metadata and controls

68 lines (54 loc) · 5.18 KB
Raw

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;
  • _dense means dense 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.

Function NLPModels 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_dense!, 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_dense!, 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_dense!, hess_structure, hess_structure!, hprod, hprod!, jth_hprod, jth_hprod!, jth_hess, jth_hess_coord, jth_hess_coord!, ghjvprod, ghjvprod!

If only a subset of the functions listed above is implemented, you can indicate which ones are not available when creating the NLPModelMeta, using the keyword arguments grad_available, jac_available, hess_available, jprod_available, jtprod_available, and hprod_available. You can also specify whether the Jacobian of the constraints and the Hessian of the objective or Lagrangian are sparse using the keyword arguments sparse_jacobian and sparse_hessian.

[API for NLSModels](@id nls-api)

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)
Function function
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, jth_hess_residual_coord, jth_hess_residual_coord!, hprod_residual, hprod_residual!, hess_op_residual, hess_op_residual!

If only a subset of the functions listed above is implemented, you can indicate which ones are not available when creating the NLSMeta, using the keyword arguments jac_residual_available, hess_residual_available, jprod_residual_available, jtprod_residual_available, and hprod_residual_available.