API
As stated in the Home page, we consider the nonlinear optimization problem in the following format:
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)$, the Jacobian of $c$ at the point $x$;
- $\nabla^2 f(x) + \sum_{i=1}^m \lambda_i \nabla^2 c_i(x)$, the Hessian of the Lagrangian function at the point $(x,\lambda)$.
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;_coordmeans coordinate format;prodmeans matrix-vector product;_opmeans operator (as in LinearOperators.jl).
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, hprod, hprod! |
| $c(x)$ | cons, cons!, objcons, objcons! |
| $J(x)$ | jac, jac_op, jac_op!, jac_coord, jprod, jprod!, jtprod, jtprod! |
| $\nabla^2 L(x,y)$ | hess, hess_op, hess_coord, hprod, hprod! |
API for NLSModels
For the Nonlinear Least Squares models, $f(x) = \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)$
- $\nabla^2 F_i(x)$
| Function | function |
|---|---|
| $F(x)$ | residual, residual! |
| $J_F(x)$ | jac_residual, jac_coord_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, jth_hess_residual, hprod_residual, hprod_residual!, hess_op_residual, hess_op_residual! |
AbstractNLPModel functions
NLPModels.obj — Function.f = obj(nlp, x)
Evaluate $f(x)$, the objective function of nlp at x.
NLPModels.grad — Function.g = grad(nlp, x)
Evaluate $\nabla f(x)$, the gradient of the objective function at x.
NLPModels.grad! — Function.g = grad!(nlp, x, g)
Evaluate $\nabla f(x)$, the gradient of the objective function at x in place.
NLPModels.objgrad — Function.f, g = objgrad(nlp, x)
Evaluate $f(x)$ and $\nabla f(x)$ at x.
NLPModels.objgrad! — Function.f, g = objgrad!(nlp, x, g)
Evaluate $f(x)$ and $\nabla f(x)$ at x. g is overwritten with the value of $\nabla f(x)$.
NLPModels.cons — Function.c = cons(nlp, x)
Evaluate $c(x)$, the constraints at x.
NLPModels.cons! — Function.c = cons!(nlp, x, c)
Evaluate $c(x)$, the constraints at x in place.
NLPModels.objcons — Function.f, c = objcons(nlp, x)
Evaluate $f(x)$ and $c(x)$ at x.
NLPModels.objcons! — Function.f = objcons!(nlp, x, c)
Evaluate $f(x)$ and $c(x)$ at x. c is overwritten with the value of $c(x)$.
NLPModels.jac_coord — Function.(rows,cols,vals) = jac_coord(nlp, x)
Evaluate $\nabla c(x)$, the constraint's Jacobian at x in sparse coordinate format.
NLPModels.jac — Function.Jx = jac(nlp, x)
Evaluate $\nabla c(x)$, the constraint's Jacobian at x as a sparse matrix.
NLPModels.jac_op — Function.J = jac_op(nlp, x)
Return the Jacobian at x as a linear operator. The resulting object may be used as if it were a matrix, e.g., J * v or J' * v.
NLPModels.jac_op! — Function.J = jac_op!(nlp, x, Jv, Jtv)
Return the Jacobian at x as a linear operator. The resulting object may be used as if it were a matrix, e.g., J * v or J' * v. The values Jv and Jtv are used as preallocated storage for the operations.
NLPModels.jprod — Function.Jv = jprod(nlp, x, v)
Evaluate $\nabla c(x)v$, the Jacobian-vector product at x.
NLPModels.jprod! — Function.Jv = jprod!(nlp, x, v, Jv)
Evaluate $\nabla c(x)v$, the Jacobian-vector product at x in place.
NLPModels.jtprod — Function.Jtv = jtprod(nlp, x, v, Jtv)
Evaluate $\nabla c(x)^Tv$, the transposed-Jacobian-vector product at x.
NLPModels.jtprod! — Function.Jtv = jtprod!(nlp, x, v, Jtv)
Evaluate $\nabla c(x)^Tv$, the transposed-Jacobian-vector product at x in place.
NLPModels.hess_coord — Function.(rows,cols,vals) = hess_coord(nlp, x; obj_weight=1.0, y=zeros)
Evaluate the Lagrangian Hessian at (x,y) in sparse coordinate format, with objective function scaled by obj_weight, i.e.,
\[ \nabla^2L(x,y) = \sigma * \nabla^2 f(x) + \sum{i=1}^m yi\nabla^2 c_i(x), \]
with σ = obj_weight. Only the lower triangle is returned.
NLPModels.hess — Function.Hx = hess(nlp, x; obj_weight=1.0, y=zeros)
Evaluate the Lagrangian Hessian at (x,y) as a sparse matrix, with objective function scaled by obj_weight, i.e.,
\[ \nabla^2L(x,y) = \sigma * \nabla^2 f(x) + \sum{i=1}^m yi\nabla^2 c_i(x), \]
with σ = obj_weight. Only the lower triangle is returned.
NLPModels.hess_op — Function.H = hess_op(nlp, x; obj_weight=1.0, y=zeros)
Return the Lagrangian Hessian at (x,y) with objective function scaled by obj_weight as a linear operator. The resulting object may be used as if it were a matrix, e.g., H * v. The linear operator H represents
\[ \nabla^2L(x,y) = \sigma * \nabla^2 f(x) + \sum{i=1}^m yi\nabla^2 c_i(x), \]
with σ = obj_weight.
NLPModels.hess_op! — Function.H = hess_op!(nlp, x, Hv; obj_weight=1.0, y=zeros)
Return the Lagrangian Hessian at (x,y) with objective function scaled by obj_weight as a linear operator, and storing the result on Hv. The resulting object may be used as if it were a matrix, e.g., w = H * v. The vector Hv is used as preallocated storage for the operation. The linear operator H represents
\[ \nabla^2L(x,y) = \sigma * \nabla^2 f(x) + \sum{i=1}^m yi\nabla^2 c_i(x), \]
with σ = obj_weight.
NLPModels.hprod — Function.Hv = hprod(nlp, x, v; obj_weight=1.0, y=zeros)
Evaluate the product of the Lagrangian Hessian at (x,y) with the vector v, with objective function scaled by obj_weight, i.e.,
\[ \nabla^2L(x,y) = \sigma * \nabla^2 f(x) + \sum{i=1}^m yi\nabla^2 c_i(x), \]
with σ = obj_weight.
NLPModels.hprod! — Function.Hv = hprod!(nlp, x, v, Hv; obj_weight=1.0, y=zeros)
Evaluate the product of the Lagrangian Hessian at (x,y) with the vector v in place, with objective function scaled by obj_weight, i.e.,
\[ \nabla^2L(x,y) = \sigma * \nabla^2 f(x) + \sum{i=1}^m yi\nabla^2 c_i(x), \]
with σ = obj_weight.
LinearOperators.reset! — Function.reset!(counters)
Reset evaluation counters
`reset!(nlp)
Reset evaluation count in nlp
Base.print — Function.print(io, meta)Prints meta information - x0, nvar, ncon, etc.
AbstractNLSModel
NLPModels.residual — Function.Fx = residual(nls, x)Computes F(x), the residual at x.
NLPModels.residual! — Function.Fx = residual!(nls, x, Fx)Computes F(x), the residual at x.
NLPModels.jac_residual — Function.Jx = jac_residual(nls, x)Computes J(x), the Jacobian of the residual at x.
NLPModels.jac_coord_residual — Function.(rows,cols,vals) = jac_coord_residual(nls, x)Computes the Jacobian of the residual at x in sparse coordinate format.
NLPModels.jprod_residual — Function.Jv = jprod_residual(nls, x, v)Computes the product of the Jacobian of the residual at x and a vector, i.e., J(x)*v.
NLPModels.jprod_residual! — Function.Jv = jprod_residual!(nls, x, v, Jv)Computes the product of the Jacobian of the residual at x and a vector, i.e., J(x)*v, storing it in Jv.
NLPModels.jtprod_residual — Function.Jtv = jtprod_residual(nls, x, v)Computes the product of the transpose of the Jacobian of the residual at x and a vector, i.e., J(x)'*v.
NLPModels.jtprod_residual! — Function.Jtv = jtprod_residual!(nls, x, v, Jtv)Computes the product of the transpose of the Jacobian of the residual at x and a vector, i.e., J(x)'*v, storing it in Jtv.
NLPModels.jac_op_residual — Function.Jx = jac_op_residual(nls, x)Computes J(x), the Jacobian of the residual at x, in linear operator form.
NLPModels.jac_op_residual! — Function.Jx = jac_op_residual!(nls, x, Jv, Jtv)Computes J(x), the Jacobian of the residual at x, in linear operator form. The vectors Jv and Jtv are used as preallocated storage for the operations.
NLPModels.hess_residual — Function.H = hess_residual(nls, x, v)Computes the linear combination of the Hessians of the residuals at x with coefficients v.
NLPModels.hess_coord_residual — Function.(rows,cols,vals) = hess_coord_residual(nls, x, v)Computes the linear combination of the Hessians of the residuals at x with coefficients v in sparse coordinate format.
NLPModels.jth_hess_residual — Function.Hj = jth_hess_residual(nls, x, j)Computes the Hessian of the j-th residual at x.
NLPModels.hprod_residual — Function.Hiv = hprod_residual(nls, x, i, v)Computes the product of the Hessian of the i-th residual at x, times the vector v.
NLPModels.hprod_residual! — Function.Hiv = hprod_residual!(nls, x, i, v, Hiv)Computes the product of the Hessian of the i-th residual at x, times the vector v, and stores it in vector Hiv.
NLPModels.hess_op_residual — Function.Hop = hess_op_residual(nls, x, i)Computes the Hessian of the i-th residual at x, in linear operator form.
NLPModels.hess_op_residual! — Function.Hop = hess_op_residual!(nls, x, i, Hiv)Computes the Hessian of the i-th residual at x, in linear operator form. The vector Hiv is used as preallocated storage for the operation.
Derivative Checker
NLPModels.gradient_check — Function.Check the first derivatives of the objective at x against centered finite differences.
This function returns a dictionary indexed by components of the gradient for which the relative error exceeds rtol.
NLPModels.jacobian_check — Function.Check the first derivatives of the constraints at x against centered finite differences.
This function returns a dictionary indexed by (j, i) tuples such that the relative error in the i-th partial derivative of the j-th constraint exceeds rtol.
NLPModels.hessian_check — Function.Check the second derivatives of the objective and each constraints at x against centered finite differences. This check does not rely on exactness of the first derivatives, only on objective and constraint values.
The sgn arguments refers to the formulation of the Lagrangian in the problem. It should have a positive value if the Lagrangian is formulated as
L(x,y) = f(x) + ∑ yⱼ cⱼ(x)e.g., as in JuMPNLPModels, and a negative value if the Lagrangian is formulated as
L(x,y) = f(x) - ∑ yⱼ cⱼ(x)e.g., as in AmplModels. Only the sign of sgn is important.
This function returns a dictionary indexed by functions. The 0-th function is the objective while the k-th function (for k > 0) is the k-th constraint. The values of the dictionary are dictionaries indexed by tuples (i, j) such that the relative error in the second derivative ∂²fₖ/∂xᵢ∂xⱼ exceeds rtol.
NLPModels.hessian_check_from_grad — Function.Check the second derivatives of the objective and each constraints at x against centered finite differences. This check assumes exactness of the first derivatives.
The sgn arguments refers to the formulation of the Lagrangian in the problem. It should have a positive value if the Lagrangian is formulated as
L(x,y) = f(x) + ∑ yⱼ cⱼ(x)e.g., as in JuMPNLPModels, and a negative value if the Lagrangian is formulated as
L(x,y) = f(x) - ∑ yⱼ cⱼ(x)e.g., as in AmplModels. Only the sign of sgn is important.
This function returns a dictionary indexed by functions. The 0-th function is the objective while the k-th function (for k > 0) is the k-th constraint. The values of the dictionary are dictionaries indexed by tuples (i, j) such that the relative error in the second derivative ∂²fₖ/∂xᵢ∂xⱼ exceeds rtol.
Internal
NLPModels.increment! — Function.increment!(nlp, s)
Increment counter s of problem nlp.