diff --git a/README.md b/README.md index 1368a61b..3557944b 100644 --- a/README.md +++ b/README.md @@ -84,40 +84,46 @@ The complete list of methods that an interface may implement can be found in the `NLPModelMeta` objects have the following attributes (with `S <: AbstractVector`): -Attribute | Type | Notes -------------|--------------------|------------------------------------ -`nvar` | `Int ` | number of variables -`x0 ` | `S` | initial guess -`lvar` | `S` | vector of lower bounds -`uvar` | `S` | vector of upper bounds -`ifix` | `Vector{Int}` | indices of fixed variables -`ilow` | `Vector{Int}` | indices of variables with lower bound only -`iupp` | `Vector{Int}` | indices of variables with upper bound only -`irng` | `Vector{Int}` | indices of variables with lower and upper bound (range) -`ifree` | `Vector{Int}` | indices of free variables -`iinf` | `Vector{Int}` | indices of visibly infeasible bounds -`ncon` | `Int ` | total number of general constraints -`nlin ` | `Int ` | number of linear constraints -`nnln` | `Int ` | number of nonlinear general constraints -`y0 ` | `S` | initial Lagrange multipliers -`lcon` | `S` | vector of constraint lower bounds -`ucon` | `S` | vector of constraint upper bounds -`lin ` | `Vector{Int}` | indices of linear constraints -`nln` | `Vector{Int}` | indices of nonlinear constraints -`jfix` | `Vector{Int}` | indices of equality constraints -`jlow` | `Vector{Int}` | indices of constraints of the form c(x) ≥ cl -`jupp` | `Vector{Int}` | indices of constraints of the form c(x) ≤ cu -`jrng` | `Vector{Int}` | indices of constraints of the form cl ≤ c(x) ≤ cu -`jfree` | `Vector{Int}` | indices of "free" constraints (there shouldn't be any) -`jinf` | `Vector{Int}` | indices of the visibly infeasible constraints -`nnzo` | `Int ` | number of nonzeros in the gradient -`nnzh` | `Int ` | number of nonzeros in the sparse Hessian -`nnzj` | `Int ` | number of nonzeros in the sparse Jacobian -`lin_nnzj` | `Int ` | number of nonzeros in the linear part of sparse Jacobian -`nln_nnzj` | `Int ` | number of nonzeros in the nonlinear part of sparse Jacobian -`minimize` | `Bool ` | true if `optimize == minimize` -`islp` | `Bool ` | true if the problem is a linear program -`name` | `String` | problem name +Attribute | Type | Notes +-------------------|---------------|------------------------------------ +`nvar` | `Int` | number of variables +`x0 ` | `S` | initial guess +`lvar` | `S` | vector of lower bounds +`uvar` | `S` | vector of upper bounds +`ifix` | `Vector{Int}` | indices of fixed variables +`ilow` | `Vector{Int}` | indices of variables with lower bound only +`iupp` | `Vector{Int}` | indices of variables with upper bound only +`irng` | `Vector{Int}` | indices of variables with lower and upper bound (range) +`ifree` | `Vector{Int}` | indices of free variables +`iinf` | `Vector{Int}` | indices of visibly infeasible bounds +`ncon` | `Int` | total number of general constraints +`nlin ` | `Int` | number of linear constraints +`nnln` | `Int` | number of nonlinear general constraints +`y0 ` | `S` | initial Lagrange multipliers +`lcon` | `S` | vector of constraint lower bounds +`ucon` | `S` | vector of constraint upper bounds +`lin ` | `Vector{Int}` | indices of linear constraints +`nln` | `Vector{Int}` | indices of nonlinear constraints +`jfix` | `Vector{Int}` | indices of equality constraints +`jlow` | `Vector{Int}` | indices of constraints of the form c(x) ≥ cl +`jupp` | `Vector{Int}` | indices of constraints of the form c(x) ≤ cu +`jrng` | `Vector{Int}` | indices of constraints of the form cl ≤ c(x) ≤ cu +`jfree` | `Vector{Int}` | indices of "free" constraints (there shouldn't be any) +`jinf` | `Vector{Int}` | indices of the visibly infeasible constraints +`nnzo` | `Int` | number of nonzeros in the gradient +`nnzj` | `Int` | number of nonzeros in the sparse Jacobian +`lin_nnzj` | `Int` | number of nonzeros in the sparse linear constraints Jacobian +`nln_nnzj` | `Int` | number of nonzeros in the sparse nonlinear constraints Jacobian +`nnzh` | `Int` | number of nonzeros in the lower triangular part of the sparse Hessian of the Lagrangian +`minimize` | `Bool` | true if `optimize == minimize` +`islp` | `Bool` | true if the problem is a linear program +`name` | `String` | problem name +`grad_available` | `Bool` | true if the gradient of the objective is available +`jac_available` | `Bool` | true if the sparse Jacobian of the constraints is available +`hess_available` | `Bool` | true if the sparse Hessian of the Lagrangian is available +`jprod_available` | `Bool` | true if the Jacobian-vector product `J * v` is available +`jtprod_available` | `Bool` | true if the transpose Jacobian-vector product `J' * v` is available +`hprod_available` | `Bool` | true if the Hessian-vector product of the Lagrangian `H * v` is available # Bug reports and discussions diff --git a/docs/src/api.md b/docs/src/api.md index f0c28e92..c7424fb8 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -45,6 +45,9 @@ NLPModels instances. | ``J(x)`` | [`jac_lin`](@ref), [`jac_nln`](@ref), [`jac`](@ref), [`jac_lin_op`](@ref), [`jac_lin_op!`](@ref), [`jac_nln_op`](@ref), [`jac_nln_op!`](@ref),[`jac_op`](@ref), [`jac_op!`](@ref), [`jac_lin_coord`](@ref), [`jac_lin_coord!`](@ref), [`jac_nln_coord`](@ref), [`jac_nln_coord!`](@ref), [`jac_coord`](@ref), [`jac_coord!`](@ref), [`jac_lin_structure`](@ref), [`jac_lin_structure!`](@ref), [`jac_nln_structure`](@ref), [`jac_nln_structure!`](@ref), [`jac_structure`](@ref), [`jprod_lin`](@ref), [`jprod_lin!`](@ref), [`jprod_nln`](@ref), [`jprod_nln!`](@ref), [`jprod`](@ref), [`jprod!`](@ref), [`jtprod_lin`](@ref), [`jtprod_lin!`](@ref), [`jtprod_nln`](@ref), [`jtprod_nln!`](@ref), [`jtprod`](@ref), [`jtprod!`](@ref) | | ``\nabla^2 L(x,y)`` | [`hess`](@ref), [`hess_op`](@ref), [`hess_coord`](@ref), [`hess_coord!`](@ref), [`hess_structure`](@ref), [`hess_structure!`](@ref), [`hprod`](@ref), [`hprod!`](@ref), [`jth_hprod`](@ref), [`jth_hprod!`](@ref), [`jth_hess`](@ref), [`jth_hess_coord`](@ref), [`jth_hess_coord!`](@ref), [`ghjvprod`](@ref), [`ghjvprod!`](@ref) | +If only a subset of the functions listed above is implemented, you can indicate which ones are not available when creating the [`NLPModelMeta`](@ref), using the keyword arguments +`grad_available`, `jac_available`, `hess_available`, `jprod_available`, `jtprod_available`, and `hprod_available`. + ## [API for NLSModels](@id nls-api) For the Nonlinear Least Squares models, ``f(x) = \tfrac{1}{2} \Vert F(x)\Vert^2``, @@ -59,3 +62,5 @@ and its derivatives. Namely, | ``F(x)`` | [`residual`](@ref), [`residual!`](@ref) | | ``J_F(x)`` | [`jac_residual`](@ref), [`jac_coord_residual`](@ref), [`jac_coord_residual!`](@ref), [`jac_structure_residual`](@ref), [`jac_structure_residual!`](@ref), [`jprod_residual`](@ref), [`jprod_residual!`](@ref), [`jtprod_residual`](@ref), [`jtprod_residual!`](@ref), [`jac_op_residual`](@ref), [`jac_op_residual!`](@ref) | | ``\nabla^2 F_i(x)`` | [`hess_residual`](@ref), [`hess_coord_residual`](@ref), [`hess_coord_residual!`](@ref), [`hess_structure_residual`](@ref), [`hess_structure_residual!`](@ref), [`jth_hess_residual`](@ref), [`jth_hess_residual_coord`](@ref), [`jth_hess_residual_coord!`](@ref), [`hprod_residual`](@ref), [`hprod_residual!`](@ref), [`hess_op_residual`](@ref), [`hess_op_residual!`](@ref) | + +If only a subset of the functions listed above is implemented, you can indicate which ones are not available when creating the [`NLSMeta`](@ref), using the keyword arguments `jac_residual_available`, `hess_residual_available`, `jprod_residual_available`, `jtprod_residual_available`, and `hprod_residual_available`. diff --git a/docs/src/guidelines.md b/docs/src/guidelines.md index 7ef1a7cb..b5e42634 100644 --- a/docs/src/guidelines.md +++ b/docs/src/guidelines.md @@ -82,6 +82,15 @@ The indices of linear and nonlinear constraints are respectively available in `n If your model uses only linear (resp. nonlinear) constraints, then it suffices to implement the `*_lin` (resp. `*_nln`) functions. Alternatively, one could implement only the functions without the suffixes `_nln!` (e.g., only `cons!`), but this might run into errors with tools differentiating linear and nonlinear constraints. +## [Availability of the API](@id availability-api) + +If only a subset of the functions listed above is implemented, you can indicate which ones are not available when creating the [`NLPModelMeta`](@ref), using the keyword arguments +`grad_available`, `jac_available`, `hess_available`, `jprod_available`, `jtprod_available`, and `hprod_available`. + +By default, `grad_available`, `hess_available`, and `hprod_available` are set to `true`. +For constrained problems (`ncon > 0`), the fields `jac_available`, `jprod_available`, and `jtprod_available` are also set to `true`. +For unconstrained problems (`ncon == 0`), they default to `false`. + ## [Expected behaviour](@id expected-behaviour) The following is a non-exhaustive list of expected behaviour for methods. diff --git a/docs/src/index.md b/docs/src/index.md index 7f5b1bcf..c5c4f123 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -79,40 +79,46 @@ See the [Models](@ref), the [Tools](@ref tools-section), or the [API](@ref). `NLPModelMeta` objects have the following attributes (with `S <: AbstractVector`): -Attribute | Type | Notes -------------|--------------------|------------------------------------ -`nvar` | `Int ` | number of variables -`x0 ` | `S` | initial guess -`lvar` | `S` | vector of lower bounds -`uvar` | `S` | vector of upper bounds -`ifix` | `Vector{Int}` | indices of fixed variables -`ilow` | `Vector{Int}` | indices of variables with lower bound only -`iupp` | `Vector{Int}` | indices of variables with upper bound only -`irng` | `Vector{Int}` | indices of variables with lower and upper bound (range) -`ifree` | `Vector{Int}` | indices of free variables -`iinf` | `Vector{Int}` | indices of visibly infeasible bounds -`ncon` | `Int ` | total number of general constraints -`nlin ` | `Int ` | number of linear constraints -`nnln` | `Int ` | number of nonlinear general constraints -`y0 ` | `S` | initial Lagrange multipliers -`lcon` | `S` | vector of constraint lower bounds -`ucon` | `S` | vector of constraint upper bounds -`lin ` | `Vector{Int}` | indices of linear constraints -`nln` | `Vector{Int}` | indices of nonlinear constraints -`jfix` | `Vector{Int}` | indices of equality constraints -`jlow` | `Vector{Int}` | indices of constraints of the form c(x) ≥ cl -`jupp` | `Vector{Int}` | indices of constraints of the form c(x) ≤ cu -`jrng` | `Vector{Int}` | indices of constraints of the form cl ≤ c(x) ≤ cu -`jfree` | `Vector{Int}` | indices of "free" constraints (there shouldn't be any) -`jinf` | `Vector{Int}` | indices of the visibly infeasible constraints -`nnzo` | `Int ` | number of nonzeros in the gradient -`nnzj` | `Int ` | number of nonzeros in the sparse Jacobian -`lin_nnzj` | `Int ` | number of nonzeros in the sparse linear constraints Jacobian -`nln_nnzj` | `Int ` | number of nonzeros in the sparse nonlinear constraints Jacobian -`nnzh` | `Int ` | number of nonzeros in the lower triangular part of the sparse Hessian of the Lagrangian -`minimize` | `Bool ` | true if `optimize == minimize` -`islp` | `Bool ` | true if the problem is a linear program -`name` | `String` | problem name +Attribute | Type | Notes +-------------------|---------------|------------------------------------ +`nvar` | `Int` | number of variables +`x0 ` | `S` | initial guess +`lvar` | `S` | vector of lower bounds +`uvar` | `S` | vector of upper bounds +`ifix` | `Vector{Int}` | indices of fixed variables +`ilow` | `Vector{Int}` | indices of variables with lower bound only +`iupp` | `Vector{Int}` | indices of variables with upper bound only +`irng` | `Vector{Int}` | indices of variables with lower and upper bound (range) +`ifree` | `Vector{Int}` | indices of free variables +`iinf` | `Vector{Int}` | indices of visibly infeasible bounds +`ncon` | `Int` | total number of general constraints +`nlin ` | `Int` | number of linear constraints +`nnln` | `Int` | number of nonlinear general constraints +`y0 ` | `S` | initial Lagrange multipliers +`lcon` | `S` | vector of constraint lower bounds +`ucon` | `S` | vector of constraint upper bounds +`lin ` | `Vector{Int}` | indices of linear constraints +`nln` | `Vector{Int}` | indices of nonlinear constraints +`jfix` | `Vector{Int}` | indices of equality constraints +`jlow` | `Vector{Int}` | indices of constraints of the form c(x) ≥ cl +`jupp` | `Vector{Int}` | indices of constraints of the form c(x) ≤ cu +`jrng` | `Vector{Int}` | indices of constraints of the form cl ≤ c(x) ≤ cu +`jfree` | `Vector{Int}` | indices of "free" constraints (there shouldn't be any) +`jinf` | `Vector{Int}` | indices of the visibly infeasible constraints +`nnzo` | `Int` | number of nonzeros in the gradient +`nnzj` | `Int` | number of nonzeros in the sparse Jacobian +`lin_nnzj` | `Int` | number of nonzeros in the sparse linear constraints Jacobian +`nln_nnzj` | `Int` | number of nonzeros in the sparse nonlinear constraints Jacobian +`nnzh` | `Int` | number of nonzeros in the lower triangular part of the sparse Hessian of the Lagrangian +`minimize` | `Bool` | true if `optimize == minimize` +`islp` | `Bool` | true if the problem is a linear program +`name` | `String` | problem name +`grad_available` | `Bool` | true if the gradient of the objective is available +`jac_available` | `Bool` | true if the sparse Jacobian of the constraints is available +`hess_available` | `Bool` | true if the sparse Hessian of the Lagrangian is available +`jprod_available` | `Bool` | true if the Jacobian-vector product `J * v` is available +`jtprod_available` | `Bool` | true if the transpose Jacobian-vector product `J' * v` is available +`hprod_available` | `Bool` | true if the Hessian-vector product of the Lagrangian `H * v` is available ## License diff --git a/src/nlp/api.jl b/src/nlp/api.jl index 94784ded..cd1efeb9 100644 --- a/src/nlp/api.jl +++ b/src/nlp/api.jl @@ -24,6 +24,7 @@ function obj end g = grad(nlp, x) Evaluate ``∇f(x)``, the gradient of the objective function at `x`. +This function is only available if `nlp.meta.grad_available` is set to `true`. """ function grad(nlp::AbstractNLPModel{T, S}, x::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x @@ -35,6 +36,7 @@ end g = grad!(nlp, x, g) Evaluate ``∇f(x)``, the gradient of the objective function at `x` in place. +This function is only available if `nlp.meta.grad_available` is set to `true`. """ function grad! end @@ -151,6 +153,7 @@ end f, g = objgrad(nlp, x) Evaluate ``f(x)`` and ``∇f(x)`` at `x`. +This function is only available if `nlp.meta.grad_available` is set to `true`. """ function objgrad(nlp::AbstractNLPModel{T, S}, x::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x @@ -161,8 +164,8 @@ end """ f, g = objgrad!(nlp, x, g) -Evaluate ``f(x)`` and ``∇f(x)`` at `x`. `g` is overwritten with the -value of ``∇f(x)``. +Evaluate ``f(x)`` and ``∇f(x)`` at `x`. `g` is overwritten with the value of ``∇f(x)``. +This function is only available if `nlp.meta.grad_available` is set to `true`. """ function objgrad!(nlp::AbstractNLPModel, x::AbstractVector, g::AbstractVector) @lencheck nlp.meta.nvar x g @@ -175,6 +178,7 @@ end (rows,cols) = jac_structure(nlp) Return the structure of the constraints Jacobian in sparse coordinate format. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_structure(nlp::AbstractNLPModel) rows = Vector{Int}(undef, nlp.meta.nnzj) @@ -186,6 +190,7 @@ end jac_structure!(nlp, rows, cols) Return the structure of the constraints Jacobian in sparse coordinate format in place. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_structure!( nlp::AbstractNLPModel, @@ -222,6 +227,7 @@ end (rows,cols) = jac_lin_structure(nlp) Return the structure of the linear constraints Jacobian in sparse coordinate format. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_lin_structure(nlp::AbstractNLPModel) rows = Vector{Int}(undef, nlp.meta.lin_nnzj) @@ -233,6 +239,7 @@ end jac_lin_structure!(nlp, rows, cols) Return the structure of the linear constraints Jacobian in sparse coordinate format in place. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_lin_structure! end @@ -240,6 +247,7 @@ function jac_lin_structure! end (rows,cols) = jac_nln_structure(nlp) Return the structure of the nonlinear constraints Jacobian in sparse coordinate format. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_nln_structure(nlp::AbstractNLPModel) rows = Vector{Int}(undef, nlp.meta.nln_nnzj) @@ -251,14 +259,15 @@ end jac_nln_structure!(nlp, rows, cols) Return the structure of the nonlinear constraints Jacobian in sparse coordinate format in place. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_nln_structure! end """ vals = jac_coord!(nlp, x, vals) -Evaluate ``J(x)``, the constraints Jacobian at `x` in sparse coordinate format, -rewriting `vals`. +Evaluate ``J(x)``, the constraints Jacobian at `x` in sparse coordinate format, rewriting `vals`. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_coord!(nlp::AbstractNLPModel, x::AbstractVector, vals::AbstractVector) @lencheck nlp.meta.nvar x @@ -287,6 +296,7 @@ end vals = jac_coord(nlp, x) Evaluate ``J(x)``, the constraints Jacobian at `x` in sparse coordinate format. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_coord(nlp::AbstractNLPModel{T, S}, x::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x @@ -298,6 +308,7 @@ end Jx = jac(nlp, x) Evaluate ``J(x)``, the constraints Jacobian at `x` as a sparse matrix. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac(nlp::AbstractNLPModel, x::AbstractVector) @lencheck nlp.meta.nvar x @@ -309,8 +320,8 @@ end """ vals = jac_lin_coord!(nlp, x, vals) -Evaluate ``J(x)``, the linear constraints Jacobian at `x` in sparse coordinate format, -overwriting `vals`. +Evaluate ``J(x)``, the linear constraints Jacobian at `x` in sparse coordinate format, overwriting `vals`. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_lin_coord! end @@ -318,6 +329,7 @@ function jac_lin_coord! end vals = jac_lin_coord(nlp, x) Evaluate ``J(x)``, the linear constraints Jacobian at `x` in sparse coordinate format. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_lin_coord(nlp::AbstractNLPModel{T, S}, x::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x @@ -329,6 +341,7 @@ end Jx = jac_lin(nlp, x) Evaluate ``J(x)``, the linear constraints Jacobian at `x` as a sparse matrix. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_lin(nlp::AbstractNLPModel, x::AbstractVector) @lencheck nlp.meta.nvar x @@ -340,8 +353,8 @@ end """ vals = jac_nln_coord!(nlp, x, vals) -Evaluate ``J(x)``, the nonlinear constraints Jacobian at `x` in sparse coordinate format, -overwriting `vals`. +Evaluate ``J(x)``, the nonlinear constraints Jacobian at `x` in sparse coordinate format, overwriting `vals`. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_nln_coord! end @@ -349,6 +362,7 @@ function jac_nln_coord! end vals = jac_nln_coord(nlp, x) Evaluate ``J(x)``, the nonlinear constraints Jacobian at `x` in sparse coordinate format. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_nln_coord(nlp::AbstractNLPModel{T, S}, x::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x @@ -360,6 +374,7 @@ end Jx = jac_nln(nlp, x) Evaluate ``J(x)``, the nonlinear constraints Jacobian at `x` as a sparse matrix. +This function is only available if `nlp.meta.jac_available` is set to `true`. """ function jac_nln(nlp::AbstractNLPModel, x::AbstractVector) @lencheck nlp.meta.nvar x @@ -372,6 +387,7 @@ end Jv = jprod(nlp, x, v) Evaluate ``J(x)v``, the Jacobian-vector product at `x`. +This function is only available if `nlp.meta.jprod_available` is set to `true`. """ function jprod(nlp::AbstractNLPModel{T, S}, x::AbstractVector, v::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x v @@ -383,6 +399,7 @@ end Jv = jprod!(nlp, x, v, Jv) Evaluate ``J(x)v``, the Jacobian-vector product at `x` in place. +This function is only available if `nlp.meta.jprod_available` is set to `true`. """ function jprod!(nlp::AbstractNLPModel, x::AbstractVector, v::AbstractVector, Jv::AbstractVector) @lencheck nlp.meta.nvar x v @@ -408,8 +425,8 @@ end """ Jv = jprod!(nlp, rows, cols, vals, v, Jv) -Evaluate ``J(x)v``, the Jacobian-vector product, where the Jacobian is given by -`(rows, cols, vals)` in triplet format. +Evaluate ``J(x)v``, the Jacobian-vector product, where the Jacobian is given by `(rows, cols, vals)` in triplet format. +This function is only available if `nlp.meta.jprod_available` is set to `true`. """ function jprod!( nlp::AbstractNLPModel, @@ -430,6 +447,7 @@ end Jv = jprod_lin(nlp, x, v) Evaluate ``J(x)v``, the linear Jacobian-vector product at `x`. +This function is only available if `nlp.meta.jprod_available` is set to `true`. """ function jprod_lin(nlp::AbstractNLPModel{T, S}, x::AbstractVector, v::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x v @@ -441,14 +459,15 @@ end Jv = jprod_lin!(nlp, x, v, Jv) Evaluate ``J(x)v``, the linear Jacobian-vector product at `x` in place. +This function is only available if `nlp.meta.jprod_available` is set to `true`. """ function jprod_lin! end """ Jv = jprod_lin!(nlp, rows, cols, vals, v, Jv) -Evaluate ``J(x)v``, the linear Jacobian-vector product, where the Jacobian is given by -`(rows, cols, vals)` in triplet format. +Evaluate ``J(x)v``, the linear Jacobian-vector product, where the Jacobian is given by `(rows, cols, vals)` in triplet format. +This function is only available if `nlp.meta.jprod_available` is set to `true`. """ function jprod_lin!( nlp::AbstractNLPModel, @@ -469,6 +488,7 @@ end Jv = jprod_nln(nlp, x, v) Evaluate ``J(x)v``, the nonlinear Jacobian-vector product at `x`. +This function is only available if `nlp.meta.jprod_available` is set to `true`. """ function jprod_nln(nlp::AbstractNLPModel{T, S}, x::AbstractVector, v::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x v @@ -480,14 +500,15 @@ end Jv = jprod_nln!(nlp, x, v, Jv) Evaluate ``J(x)v``, the nonlinear Jacobian-vector product at `x` in place. +This function is only available if `nlp.meta.jprod_available` is set to `true`. """ function jprod_nln! end """ Jv = jprod_nln!(nlp, rows, cols, vals, v, Jv) -Evaluate ``J(x)v``, the nonlinear Jacobian-vector product, where the Jacobian is given by -`(rows, cols, vals)` in triplet format. +Evaluate ``J(x)v``, the nonlinear Jacobian-vector product, where the Jacobian is given by `(rows, cols, vals)` in triplet format. +This function is only available if `nlp.meta.jprod_available` is set to `true`. """ function jprod_nln!( nlp::AbstractNLPModel, @@ -508,6 +529,7 @@ end Jtv = jtprod(nlp, x, v) Evaluate ``J(x)^Tv``, the transposed-Jacobian-vector product at `x`. +This function is only available if `nlp.meta.jtprod_available` is set to `true`. """ function jtprod(nlp::AbstractNLPModel{T, S}, x::AbstractVector, v::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x @@ -521,6 +543,7 @@ end Evaluate ``J(x)^Tv``, the transposed-Jacobian-vector product at `x` in place. If the problem has linear and nonlinear constraints, this function allocates. +This function is only available if `nlp.meta.jtprod_available` is set to `true`. """ function jtprod!(nlp::AbstractNLPModel, x::AbstractVector, v::AbstractVector, Jtv::AbstractVector) @lencheck nlp.meta.nvar x Jtv @@ -549,6 +572,7 @@ end Evaluate ``J(x)^Tv``, the transposed-Jacobian-vector product, where the Jacobian is given by `(rows, cols, vals)` in triplet format. +This function is only available if `nlp.meta.jtprod_available` is set to `true`. """ function jtprod!( nlp::AbstractNLPModel, @@ -569,6 +593,7 @@ end Jtv = jtprod_lin(nlp, x, v) Evaluate ``J(x)^Tv``, the linear transposed-Jacobian-vector product at `x`. +This function is only available if `nlp.meta.jtprod_available` is set to `true`. """ function jtprod_lin(nlp::AbstractNLPModel{T, S}, x::AbstractVector, v::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x @@ -581,6 +606,7 @@ end Jtv = jtprod_lin!(nlp, x, v, Jtv) Evaluate ``J(x)^Tv``, the linear transposed-Jacobian-vector product at `x` in place. +This function is only available if `nlp.meta.jtprod_available` is set to `true`. """ function jtprod_lin! end @@ -589,6 +615,7 @@ function jtprod_lin! end Evaluate ``J(x)^Tv``, the linear transposed-Jacobian-vector product, where the Jacobian is given by `(rows, cols, vals)` in triplet format. +This function is only available if `nlp.meta.jtprod_available` is set to `true`. """ function jtprod_lin!( nlp::AbstractNLPModel, @@ -609,6 +636,7 @@ end Jtv = jtprod_nln(nlp, x, v) Evaluate ``J(x)^Tv``, the nonlinear transposed-Jacobian-vector product at `x`. +This function is only available if `nlp.meta.jtprod_available` is set to `true`. """ function jtprod_nln(nlp::AbstractNLPModel{T, S}, x::AbstractVector, v::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x @@ -621,6 +649,7 @@ end Jtv = jtprod_nln!(nlp, x, v, Jtv) Evaluate ``J(x)^Tv``, the nonlinear transposed-Jacobian-vector product at `x` in place. +This function is only available if `nlp.meta.jtprod_available` is set to `true`. """ function jtprod_nln! end @@ -629,6 +658,7 @@ function jtprod_nln! end Evaluate ``J(x)^Tv``, the nonlinear transposed-Jacobian-vector product, where the Jacobian is given by `(rows, cols, vals)` in triplet format. +This function is only available if `nlp.meta.jtprod_available` is set to `true`. """ function jtprod_nln!( nlp::AbstractNLPModel, @@ -649,8 +679,8 @@ end 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`. +The resulting object may be used as if it were a matrix, e.g., `J * v` or `J' * v`. +This function is only available if both `nlp.meta.jprod_available` and `nlp.meta.jtprod_available` are set to `true`. """ function jac_op(nlp::AbstractNLPModel{T, S}, x::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x @@ -663,9 +693,9 @@ end 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. +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. +This function is only available if both `nlp.meta.jprod_available` and `nlp.meta.jtprod_available` are set to `true`. """ function jac_op!( nlp::AbstractNLPModel{T, S}, @@ -702,6 +732,7 @@ end Return the Jacobian given by `(rows, cols, vals)` 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. +This function is only available if both `nlp.meta.jprod_available` and `nlp.meta.jtprod_available` are set to `true`. """ function jac_op!( nlp::AbstractNLPModel{T, S}, @@ -739,8 +770,8 @@ end J = jac_lin_op(nlp, x) Return the linear 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 resulting object may be used as if it were a matrix, e.g., `J * v` or `J' * v`. +This function is only available if both `nlp.meta.jprod_available` and `nlp.meta.jtprod_available` are set to `true`. """ function jac_lin_op(nlp::AbstractNLPModel{T, S}, x::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x @@ -753,9 +784,9 @@ end J = jac_lin_op!(nlp, x, Jv, Jtv) Return the linear 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. +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. +This function is only available if both `nlp.meta.jprod_available` and `nlp.meta.jtprod_available` are set to `true`. """ function jac_lin_op!( nlp::AbstractNLPModel{T, S}, @@ -792,6 +823,7 @@ end Return the linear Jacobian given by `(rows, cols, vals)` 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. +This function is only available if both `nlp.meta.jprod_available` and `nlp.meta.jtprod_available` are set to `true`. """ function jac_lin_op!( nlp::AbstractNLPModel{T, S}, @@ -829,8 +861,8 @@ end J = jac_nln_op(nlp, x) Return the nonlinear 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 resulting object may be used as if it were a matrix, e.g., `J * v` or `J' * v`. +This function is only available if both `nlp.meta.jprod_available` and `nlp.meta.jtprod_available` are set to `true`. """ function jac_nln_op(nlp::AbstractNLPModel{T, S}, x::AbstractVector) where {T, S} @lencheck nlp.meta.nvar x @@ -843,9 +875,9 @@ end J = jac_nln_op!(nlp, x, Jv, Jtv) Return the nonlinear 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. +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. +This function is only available if both `nlp.meta.jprod_available` and `nlp.meta.jtprod_available` are set to `true`. """ function jac_nln_op!( nlp::AbstractNLPModel{T, S}, @@ -882,6 +914,7 @@ end Return the nonlinear Jacobian given by `(rows, cols, vals)` 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. +This function is only available if both `nlp.meta.jprod_available` and `nlp.meta.jtprod_available` are set to `true`. """ function jac_nln_op!( nlp::AbstractNLPModel{T, S}, @@ -1003,6 +1036,7 @@ function ghjvprod! end (rows,cols) = hess_structure(nlp) Return the structure of the Lagrangian Hessian in sparse coordinate format. +This function is only available if `nlp.meta.hess_available` is set to `true`. """ function hess_structure(nlp::AbstractNLPModel) rows = Vector{Int}(undef, nlp.meta.nnzh) @@ -1014,6 +1048,7 @@ end hess_structure!(nlp, rows, cols) Return the structure of the Lagrangian Hessian in sparse coordinate format in place. +This function is only available if `nlp.meta.hess_available` is set to `true`. """ function hess_structure! end @@ -1024,6 +1059,7 @@ Evaluate the objective Hessian at `x` in sparse coordinate format, with objective function scaled by `obj_weight`, i.e., $(OBJECTIVE_HESSIAN), overwriting `vals`. Only the lower triangle is returned. +This function is only available if `nlp.meta.hess_available` is set to `true`. """ function hess_coord!( nlp::AbstractNLPModel{T, S}, @@ -1044,6 +1080,7 @@ Evaluate the Lagrangian Hessian at `(x,y)` in sparse coordinate format, with objective function scaled by `obj_weight`, i.e., $(LAGRANGIAN_HESSIAN), overwriting `vals`. Only the lower triangle is returned. +This function is only available if `nlp.meta.hess_available` is set to `true`. """ function hess_coord! end @@ -1052,9 +1089,9 @@ function hess_coord! end Evaluate the objective Hessian at `x` in sparse coordinate format, with objective function scaled by `obj_weight`, i.e., - $(OBJECTIVE_HESSIAN). Only the lower triangle is returned. +This function is only available if `nlp.meta.hess_available` is set to `true`. """ function hess_coord( nlp::AbstractNLPModel{T, S}, @@ -1071,9 +1108,9 @@ end Evaluate the Lagrangian Hessian at `(x,y)` in sparse coordinate format, with objective function scaled by `obj_weight`, i.e., - $(LAGRANGIAN_HESSIAN). Only the lower triangle is returned. +This function is only available if `nlp.meta.hess_available` is set to `true`. """ function hess_coord( nlp::AbstractNLPModel{T, S}, @@ -1092,9 +1129,9 @@ end Evaluate the objective Hessian at `x` as a sparse matrix, with objective function scaled by `obj_weight`, i.e., - $(OBJECTIVE_HESSIAN). A `Symmetric` object wrapping the lower triangle is returned. +This function is only available if `nlp.meta.hess_available` is set to `true`. """ function hess( nlp::AbstractNLPModel{T, S}, @@ -1112,9 +1149,9 @@ end Evaluate the Lagrangian Hessian at `(x,y)` as a sparse matrix, with objective function scaled by `obj_weight`, i.e., - $(LAGRANGIAN_HESSIAN). A `Symmetric` object wrapping the lower triangle is returned. +This function is only available if `nlp.meta.hess_available` is set to `true`. """ function hess( nlp::AbstractNLPModel{T, S}, @@ -1135,6 +1172,7 @@ end Evaluate the product of the objective Hessian at `x` with the vector `v`, with objective function scaled by `obj_weight`, where the objective Hessian is $(OBJECTIVE_HESSIAN). +This function is only available if `nlp.meta.hprod_available` is set to `true`. """ function hprod( nlp::AbstractNLPModel{T, S}, @@ -1153,6 +1191,7 @@ end Evaluate the product of the Lagrangian Hessian at `(x,y)` with the vector `v`, with objective function scaled by `obj_weight`, where the Lagrangian Hessian is $(LAGRANGIAN_HESSIAN). +This function is only available if `nlp.meta.hprod_available` is set to `true`. """ function hprod( nlp::AbstractNLPModel{T, S}, @@ -1173,6 +1212,7 @@ end Evaluate the product of the objective Hessian at `x` with the vector `v` in place, with objective function scaled by `obj_weight`, where the objective Hessian is $(OBJECTIVE_HESSIAN). +This function is only available if `nlp.meta.hprod_available` is set to `true`. """ function hprod!( nlp::AbstractNLPModel{T, S}, @@ -1191,6 +1231,7 @@ end Evaluate the product of the objective or Lagrangian Hessian given by `(rows, cols, vals)` in triplet format with the vector `v` in place. Only one triangle of the Hessian should be given. +This function is only available if `nlp.meta.hprod_available` is set to `true`. """ function hprod!( nlp::AbstractNLPModel, @@ -1212,6 +1253,7 @@ end Evaluate the product of the Lagrangian Hessian at `(x,y)` with the vector `v` in place, with objective function scaled by `obj_weight`, where the Lagrangian Hessian is $(LAGRANGIAN_HESSIAN). +This function is only available if `nlp.meta.hprod_available` is set to `true`. """ function hprod! end @@ -1222,6 +1264,7 @@ Return the objective Hessian at `x` 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 $(OBJECTIVE_HESSIAN). +This function is only available if `nlp.meta.hprod_available` is set to `true`. """ function hess_op( nlp::AbstractNLPModel{T, S}, @@ -1240,6 +1283,7 @@ 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 $(LAGRANGIAN_HESSIAN). +This function is only available if `nlp.meta.hprod_available` is set to `true`. """ function hess_op( nlp::AbstractNLPModel{T, S}, @@ -1262,6 +1306,7 @@ 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 $(OBJECTIVE_HESSIAN). +This function is only available if `nlp.meta.hprod_available` is set to `true`. """ function hess_op!( nlp::AbstractNLPModel{T, S}, @@ -1288,9 +1333,10 @@ end Return the Hessian given by `(rows, cols, vals)` 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 +The vector `Hv` is used as preallocated storage for the operation. +The linear operator H represents $(OBJECTIVE_HESSIAN). +This function is only available if `nlp.meta.hprod_available` is set to `true`. """ function hess_op!( nlp::AbstractNLPModel{T, S}, @@ -1322,6 +1368,7 @@ 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 $(LAGRANGIAN_HESSIAN). +This function is only available if `nlp.meta.hprod_available` is set to `true`. """ function hess_op!( nlp::AbstractNLPModel{T, S}, diff --git a/src/nlp/meta.jl b/src/nlp/meta.jl index ab3d0ea4..884d0922 100644 --- a/src/nlp/meta.jl +++ b/src/nlp/meta.jl @@ -51,6 +51,12 @@ The following keyword arguments are accepted: - `minimize`: true if optimize == minimize - `islp`: true if the problem is a linear program - `name`: problem name +- `grad_available`: indicates whether the gradient of the objective is available +- `jac_available`: indicates whether the sparse Jacobian of the constraints is available +- `hess_available`: indicates whether the sparse Hessian of the Lagrangian is available +- `jprod_available`: indicates whether the Jacobian-vector product `J * v` is available +- `jtprod_available`: indicates whether the transpose Jacobian-vector product `J' * v` is available +- `hprod_available`: indicates whether the Hessian-vector product of the Lagrangian `H * v` is available `NLPModelMeta` also contains the following attributes, which are computed from the variables above: - `nvar`: number of variables @@ -114,6 +120,13 @@ struct NLPModelMeta{T, S} <: AbstractNLPModelMeta{T, S} minimize::Bool islp::Bool name::String + + grad_available::Bool + jac_available::Bool + hess_available::Bool + jprod_available::Bool + jtprod_available::Bool + hprod_available::Bool end function NLPModelMeta{T, S}( @@ -134,9 +147,15 @@ function NLPModelMeta{T, S}( nln_nnzj = nnzj - lin_nnzj, nnzh = nvar * (nvar + 1) / 2, lin = Int[], - minimize = true, - islp = false, + minimize::Bool = true, + islp::Bool = false, name = "Generic", + grad_available::Bool = true, + jac_available::Bool = (ncon > 0), + hess_available::Bool = true, + jprod_available::Bool = (ncon > 0), + jtprod_available::Bool = (ncon > 0), + hprod_available::Bool = true, ) where {T, S} if (nvar < 1) || (ncon < 0) error("Nonsensical dimensions") @@ -213,6 +232,12 @@ function NLPModelMeta{T, S}( minimize, islp, name, + grad_available, + jac_available, + hess_available, + jprod_available, + jtprod_available, + hprod_available, ) end @@ -238,9 +263,15 @@ function NLPModelMeta( nln_nnzj = meta.nln_nnzj, nnzh = meta.nnzh, lin = meta.lin, - minimize = meta.minimize, - islp = meta.islp, + minimize::Bool = meta.minimize, + islp::Bool = meta.islp, name = meta.name, + grad_available::Bool = meta.grad_available, + jac_available::Bool = meta.jac_available, + hess_available::Bool = meta.hess_available, + jprod_available::Bool = meta.jprod_available, + jtprod_available::Bool = meta.jtprod_available, + hprod_available::Bool = meta.hprod_available, ) where {T, S} NLPModelMeta{T, S}( nvar, @@ -263,6 +294,12 @@ function NLPModelMeta( minimize = minimize, islp = islp, name = name, + grad_available = grad_available, + jac_available = jac_available, + hess_available = hess_available, + jprod_available = jprod_available, + jtprod_available = jtprod_available, + hprod_available = hprod_available, ) end diff --git a/src/nls/api.jl b/src/nls/api.jl index 6cf0ee0c..a21f2f93 100644 --- a/src/nls/api.jl +++ b/src/nls/api.jl @@ -28,6 +28,7 @@ function residual! end Jx = jac_residual(nls, x) Computes ``J(x)``, the Jacobian of the residual at x. +This function is only available if `nls_meta(nls).jac_residual_available` is set to `true`. """ function jac_residual(nls::AbstractNLSModel, x::AbstractVector) @lencheck nls.meta.nvar x @@ -40,6 +41,7 @@ end (rows,cols) = jac_structure_residual!(nls, rows, cols) Returns the structure of the constraint's Jacobian in sparse coordinate format in place. +This function is only available if `nls_meta(nls).jac_residual_available` is set to `true`. """ function jac_structure_residual! end @@ -47,6 +49,7 @@ function jac_structure_residual! end (rows,cols) = jac_structure_residual(nls) Returns the structure of the constraint's Jacobian in sparse coordinate format. +This function is only available if `nls_meta(nls).jac_residual_available` is set to `true`. """ function jac_structure_residual(nls::AbstractNLSModel) rows = Vector{Int}(undef, nls.nls_meta.nnzj) @@ -59,6 +62,7 @@ end Computes the Jacobian of the residual at `x` in sparse coordinate format, rewriting `vals`. `rows` and `cols` are not rewritten. +This function is only available if `nls_meta(nls).jac_residual_available` is set to `true`. """ function jac_coord_residual! end @@ -66,6 +70,7 @@ function jac_coord_residual! end (rows,cols,vals) = jac_coord_residual(nls, x) Computes the Jacobian of the residual at `x` in sparse coordinate format. +This function is only available if `nls_meta(nls).jac_residual_available` is set to `true`. """ function jac_coord_residual(nls::AbstractNLSModel{T, S}, x::AbstractVector) where {T, S} @lencheck nls.meta.nvar x @@ -77,6 +82,7 @@ end 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``. +This function is only available if `nls_meta(nls).jprod_residual_available` is set to `true`. """ function jprod_residual( nls::AbstractNLSModel{T, S}, @@ -91,7 +97,8 @@ end """ 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`. +Computes the product of the Jacobian of the residual at x and a vector, i.e., ``J(x)v``, storing it in `Jv`. +This function is only available if `nls_meta(nls).jprod_residual_available` is set to `true`. """ function jprod_residual! end @@ -99,7 +106,8 @@ function jprod_residual! end Jv = jprod_residual!(nls, rows, cols, vals, v, Jv) Computes the product of the Jacobian of the residual given by `(rows, cols, vals)` -and a vector, i.e., ``J(x)v``, storing it in `Jv`. +and a vector, i.e., ``J(x)v``, storing it in `Jv`. +This function is only available if `nls_meta(nls).jprod_residual_available` is set to `true`. """ function jprod_residual!( nls::AbstractNLSModel, @@ -119,7 +127,8 @@ end """ 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)^Tv``. +Computes the product of the transpose of the Jacobian of the residual at x and a vector, i.e., ``J(x)^Tv``. +This function is only available if `nls_meta(nls).jtprod_residual_available` is set to `true`. """ function jtprod_residual( nls::AbstractNLSModel{T, S}, @@ -135,7 +144,8 @@ end """ 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)^Tv``, storing it in `Jtv`. +Computes the product of the transpose of the Jacobian of the residual at x and a vector, i.e., ``J(x)^Tv``, storing it in `Jtv`. +This function is only available if `nls_meta(nls).jtprod_residual_available` is set to `true`. """ function jtprod_residual! end @@ -143,7 +153,8 @@ function jtprod_residual! end Jtv = jtprod_residual!(nls, rows, cols, vals, v, Jtv) Computes the product of the transpose of the Jacobian of the residual given by `(rows, cols, vals)` -and a vector, i.e., ``J(x)^Tv``, storing it in `Jv`. +and a vector, i.e., ``J(x)^Tv``, storing it in `Jv`. +This function is only available if `nls_meta(nls).jtprod_residual_available` is set to `true`. """ function jtprod_residual!( nls::AbstractNLSModel, @@ -164,6 +175,7 @@ end Jx = jac_op_residual(nls, x) Computes ``J(x)``, the Jacobian of the residual at x, in linear operator form. +This function is only available if both `nls_meta(nls).jprod_residual_available` and `nls_meta(nls).jtprod_residual_available` are set to `true`. """ function jac_op_residual(nls::AbstractNLSModel{T, S}, x::AbstractVector) where {T, S} @lencheck nls.meta.nvar x @@ -177,6 +189,7 @@ end 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. +This function is only available if both `nls_meta(nls).jprod_residual_available` and `nls_meta(nls).jtprod_residual_available` are set to `true`. """ function jac_op_residual!( nls::AbstractNLSModel{T, S}, @@ -220,6 +233,7 @@ end Computes ``J(x)``, the Jacobian of the residual given by `(rows, cols, vals)`, in linear operator form. The vectors `Jv` and `Jtv` are used as preallocated storage for the operations. +This function is only available if both `nls_meta(nls).jprod_residual_available` and `nls_meta(nls).jtprod_residual_available` are set to `true`. """ function jac_op_residual!( nls::AbstractNLSModel{T, S}, @@ -264,9 +278,9 @@ end """ H = hess_residual(nls, x, v) -Computes the linear combination of the Hessians of the residuals at `x` with coefficients -`v`. +Computes the linear combination of the Hessians of the residuals at `x` with coefficients `v`. A `Symmetric` object wrapping the lower triangle is returned. +This function is only available if `nls_meta(nls).hess_residual_available` is set to `true`. """ function hess_residual(nls::AbstractNLSModel, x::AbstractVector, v::AbstractVector) @lencheck nls.meta.nvar x @@ -280,6 +294,7 @@ end (rows,cols) = hess_structure_residual(nls) Returns the structure of the residual Hessian. +This function is only available if `nls_meta(nls).hess_residual_available` is set to `true`. """ function hess_structure_residual(nls::AbstractNLSModel) rows = Vector{Int}(undef, nls.nls_meta.nnzh) @@ -291,6 +306,7 @@ end hess_structure_residual!(nls, rows, cols) Returns the structure of the residual Hessian in place. +This function is only available if `nls_meta(nls).hess_residual_available` is set to `true`. """ function hess_structure_residual! end @@ -299,6 +315,7 @@ function hess_structure_residual! end Computes the linear combination of the Hessians of the residuals at `x` with coefficients `v` in sparse coordinate format, rewriting `vals`. +This function is only available if `nls_meta(nls).hess_residual_available` is set to `true`. """ function hess_coord_residual! end @@ -307,6 +324,7 @@ function hess_coord_residual! end Computes the linear combination of the Hessians of the residuals at `x` with coefficients `v` in sparse coordinate format. +This function is only available if `nls_meta(nls).hess_residual_available` is set to `true`. """ function hess_coord_residual( nls::AbstractNLSModel{T, S}, @@ -374,6 +392,7 @@ end Hiv = hprod_residual(nls, x, i, v) Computes the product of the Hessian of the i-th residual at x, times the vector v. +This function is only available if `nls_meta(nls).hprod_residual_available` is set to `true`. """ function hprod_residual( nls::AbstractNLSModel{T, S}, @@ -391,6 +410,7 @@ end 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. +This function is only available if `nls_meta(nls).hprod_residual_available` is set to `true`. """ function hprod_residual! end @@ -410,6 +430,7 @@ end 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. +This function is only available if `nls_meta(nls).hprod_residual_available` is set to `true`. """ function hess_op_residual!( nls::AbstractNLSModel{T, S}, @@ -483,6 +504,7 @@ end Evaluate `∇f(x)`, the gradient of the objective function of `nls::AbstractNLSModel` at `x` in place. `Fx` is overwritten with the value of the residual `F(x)`. If `recompute` is `true`, then `Fx` is updated with the residual at `x`. +This function is only available if `nls_meta(nls).jtprod_residual_available` is set to `true`. """ function grad!( nls::AbstractNLSModel, @@ -510,6 +532,7 @@ end Evaluate f(x) and ∇f(x) of `nls::AbstractNLSModel` at `x`. `Fx` is overwritten with the value of the residual `F(x)`. If `recompute` is `true`, then `Fx` is updated with the residual at `x`. +This function is only available if `nls_meta(nls).jtprod_residual_available` is set to `true`. """ function objgrad!( nls::AbstractNLSModel, diff --git a/src/nls/meta.jl b/src/nls/meta.jl index 5862cc09..ac0aa320 100644 --- a/src/nls/meta.jl +++ b/src/nls/meta.jl @@ -15,6 +15,11 @@ The following keyword arguments are accepted: - `nnzj`: number of elements needed to store the nonzeros of the Jacobian of the residual - `nnzh`: number of elements needed to store the nonzeros of the sum of Hessians of the residuals - `lin`: indices of linear residuals +- `jac_residual_available`: indicates whether the sparse Jacobian of the residuals is available +- `hess_residual_available`: indicates whether the sum of the sparse Hessians of the residuals is available +- `jprod_residual_available`: indicates whether the Jacobian-vector product for the residuals is available +- `jtprod_residual_available`: indicates whether the transpose Jacobian-vector product for the residuals is available +- `hprod_residual_available`: indicates whether the Hessian-vector product for each residual is available `NLSMeta` also contains the following attributes, which are computed from the variables above: - `nequ`: size of the residual @@ -35,6 +40,12 @@ struct NLSMeta{T, S} lin::Vector{Int} # List of linear residuals nlin::Int # = length(lin) + jac_residual_available::Bool + hess_residual_available::Bool + jprod_residual_available::Bool + jtprod_residual_available::Bool + hprod_residual_available::Bool + function NLSMeta{T, S}( nequ::Int, nvar::Int; @@ -42,6 +53,11 @@ struct NLSMeta{T, S} nnzj = nequ * nvar, nnzh = div(nvar * (nvar + 1), 2), lin = Int[], + jac_residual_available::Bool = true, + hess_residual_available::Bool = true, + jprod_residual_available::Bool = true, + jtprod_residual_available::Bool = true, + hprod_residual_available::Bool = true, ) where {T, S} nnzj = max(0, nnzj) nnzh = max(0, nnzh) @@ -50,7 +66,10 @@ struct NLSMeta{T, S} nlin = length(lin) nnln = length(nln) - return new{T, S}(nequ, nvar, x0, nnzj, nnzh, nln, nnln, lin, nlin) + return new{T, S}(nequ, nvar, x0, nnzj, nnzh, nln, nnln, lin, nlin, + jac_residual_available, hess_residual_available, + jprod_residual_available, jtprod_residual_available, + hprod_residual_available) end end