Skip to content

Commit a25871c

Browse files
amontoisonamontoison
committed
Add availability flags in NLPModelMeta and NLSMeta
1 parent 15f0239 commit a25871c

File tree

8 files changed

+267
-115
lines changed

8 files changed

+267
-115
lines changed

‎README.md‎

Lines changed: 40 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -84,40 +84,46 @@ The complete list of methods that an interface may implement can be found in the
8484

8585
`NLPModelMeta` objects have the following attributes (with `S <: AbstractVector`):
8686

87-
Attribute | Type | Notes
88-
------------|--------------------|------------------------------------
89-
`nvar` | `Int ` | number of variables
90-
`x0 ` | `S` | initial guess
91-
`lvar` | `S` | vector of lower bounds
92-
`uvar` | `S` | vector of upper bounds
93-
`ifix` | `Vector{Int}` | indices of fixed variables
94-
`ilow` | `Vector{Int}` | indices of variables with lower bound only
95-
`iupp` | `Vector{Int}` | indices of variables with upper bound only
96-
`irng` | `Vector{Int}` | indices of variables with lower and upper bound (range)
97-
`ifree` | `Vector{Int}` | indices of free variables
98-
`iinf` | `Vector{Int}` | indices of visibly infeasible bounds
99-
`ncon` | `Int ` | total number of general constraints
100-
`nlin ` | `Int ` | number of linear constraints
101-
`nnln` | `Int ` | number of nonlinear general constraints
102-
`y0 ` | `S` | initial Lagrange multipliers
103-
`lcon` | `S` | vector of constraint lower bounds
104-
`ucon` | `S` | vector of constraint upper bounds
105-
`lin ` | `Vector{Int}` | indices of linear constraints
106-
`nln` | `Vector{Int}` | indices of nonlinear constraints
107-
`jfix` | `Vector{Int}` | indices of equality constraints
108-
`jlow` | `Vector{Int}` | indices of constraints of the form c(x) ≥ cl
109-
`jupp` | `Vector{Int}` | indices of constraints of the form c(x) ≤ cu
110-
`jrng` | `Vector{Int}` | indices of constraints of the form cl ≤ c(x) ≤ cu
111-
`jfree` | `Vector{Int}` | indices of "free" constraints (there shouldn't be any)
112-
`jinf` | `Vector{Int}` | indices of the visibly infeasible constraints
113-
`nnzo` | `Int ` | number of nonzeros in the gradient
114-
`nnzh` | `Int ` | number of nonzeros in the sparse Hessian
115-
`nnzj` | `Int ` | number of nonzeros in the sparse Jacobian
116-
`lin_nnzj` | `Int ` | number of nonzeros in the linear part of sparse Jacobian
117-
`nln_nnzj` | `Int ` | number of nonzeros in the nonlinear part of sparse Jacobian
118-
`minimize` | `Bool ` | true if `optimize == minimize`
119-
`islp` | `Bool ` | true if the problem is a linear program
120-
`name` | `String` | problem name
87+
Attribute | Type | Notes
88+
-------------------|---------------|------------------------------------
89+
`nvar` | `Int` | number of variables
90+
`x0 ` | `S` | initial guess
91+
`lvar` | `S` | vector of lower bounds
92+
`uvar` | `S` | vector of upper bounds
93+
`ifix` | `Vector{Int}` | indices of fixed variables
94+
`ilow` | `Vector{Int}` | indices of variables with lower bound only
95+
`iupp` | `Vector{Int}` | indices of variables with upper bound only
96+
`irng` | `Vector{Int}` | indices of variables with lower and upper bound (range)
97+
`ifree` | `Vector{Int}` | indices of free variables
98+
`iinf` | `Vector{Int}` | indices of visibly infeasible bounds
99+
`ncon` | `Int` | total number of general constraints
100+
`nlin ` | `Int` | number of linear constraints
101+
`nnln` | `Int` | number of nonlinear general constraints
102+
`y0 ` | `S` | initial Lagrange multipliers
103+
`lcon` | `S` | vector of constraint lower bounds
104+
`ucon` | `S` | vector of constraint upper bounds
105+
`lin ` | `Vector{Int}` | indices of linear constraints
106+
`nln` | `Vector{Int}` | indices of nonlinear constraints
107+
`jfix` | `Vector{Int}` | indices of equality constraints
108+
`jlow` | `Vector{Int}` | indices of constraints of the form c(x) ≥ cl
109+
`jupp` | `Vector{Int}` | indices of constraints of the form c(x) ≤ cu
110+
`jrng` | `Vector{Int}` | indices of constraints of the form cl ≤ c(x) ≤ cu
111+
`jfree` | `Vector{Int}` | indices of "free" constraints (there shouldn't be any)
112+
`jinf` | `Vector{Int}` | indices of the visibly infeasible constraints
113+
`nnzo` | `Int` | number of nonzeros in the gradient
114+
`nnzj` | `Int` | number of nonzeros in the sparse Jacobian
115+
`lin_nnzj` | `Int` | number of nonzeros in the sparse linear constraints Jacobian
116+
`nln_nnzj` | `Int` | number of nonzeros in the sparse nonlinear constraints Jacobian
117+
`nnzh` | `Int` | number of nonzeros in the lower triangular part of the sparse Hessian of the Lagrangian
118+
`minimize` | `Bool` | true if `optimize == minimize`
119+
`islp` | `Bool` | true if the problem is a linear program
120+
`name` | `String` | problem name
121+
`grad_available` | `Bool` | true if the gradient of the objective is available
122+
`jac_available` | `Bool` | true if the sparse Jacobian of the constraints is available
123+
`hess_available` | `Bool` | true if the sparse Hessian of the Lagrangian is available
124+
`jprod_available` | `Bool` | true if the Jacobian-vector product `J * v` is available
125+
`jtprod_available` | `Bool` | true if the transpose Jacobian-vector product `J' * v` is available
126+
`hprod_available` | `Bool` | true if the Hessian-vector product of the Lagrangian `H * v` is available
121127

122128
# Bug reports and discussions
123129

‎docs/src/api.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,9 @@ NLPModels instances.
4545
| ``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) |
4646
| ``\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) |
4747

48+
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
49+
`grad_available`, `jac_available`, `hess_available`, `jprod_available`, `jtprod_available`, and `hprod_available`.
50+
4851
## [API for NLSModels](@id nls-api)
4952

5053
For the Nonlinear Least Squares models, ``f(x) = \tfrac{1}{2} \Vert F(x)\Vert^2``,
@@ -59,3 +62,5 @@ and its derivatives. Namely,
5962
| ``F(x)`` | [`residual`](@ref), [`residual!`](@ref) |
6063
| ``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) |
6164
| ``\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) |
65+
66+
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`.

‎docs/src/guidelines.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,15 @@ The indices of linear and nonlinear constraints are respectively available in `n
8282
If your model uses only linear (resp. nonlinear) constraints, then it suffices to implement the `*_lin` (resp. `*_nln`) functions.
8383
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.
8484

85+
## [Availability of the API](@id availability-api)
86+
87+
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
88+
`grad_available`, `jac_available`, `hess_available`, `jprod_available`, `jtprod_available`, and `hprod_available`.
89+
90+
By default, `grad_available`, `hess_available`, and `hprod_available` are set to `true`.
91+
For constrained problems (`ncon > 0`), the fields `jac_available`, `jprod_available`, and `jtprod_available` are also set to `true`.
92+
For unconstrained problems (`ncon == 0`), they default to `false`.
93+
8594
## [Expected behaviour](@id expected-behaviour)
8695

8796
The following is a non-exhaustive list of expected behaviour for methods.

‎docs/src/index.md‎

Lines changed: 40 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -79,40 +79,46 @@ See the [Models](@ref), the [Tools](@ref tools-section), or the [API](@ref).
7979

8080
`NLPModelMeta` objects have the following attributes (with `S <: AbstractVector`):
8181

82-
Attribute | Type | Notes
83-
------------|--------------------|------------------------------------
84-
`nvar` | `Int ` | number of variables
85-
`x0 ` | `S` | initial guess
86-
`lvar` | `S` | vector of lower bounds
87-
`uvar` | `S` | vector of upper bounds
88-
`ifix` | `Vector{Int}` | indices of fixed variables
89-
`ilow` | `Vector{Int}` | indices of variables with lower bound only
90-
`iupp` | `Vector{Int}` | indices of variables with upper bound only
91-
`irng` | `Vector{Int}` | indices of variables with lower and upper bound (range)
92-
`ifree` | `Vector{Int}` | indices of free variables
93-
`iinf` | `Vector{Int}` | indices of visibly infeasible bounds
94-
`ncon` | `Int ` | total number of general constraints
95-
`nlin ` | `Int ` | number of linear constraints
96-
`nnln` | `Int ` | number of nonlinear general constraints
97-
`y0 ` | `S` | initial Lagrange multipliers
98-
`lcon` | `S` | vector of constraint lower bounds
99-
`ucon` | `S` | vector of constraint upper bounds
100-
`lin ` | `Vector{Int}` | indices of linear constraints
101-
`nln` | `Vector{Int}` | indices of nonlinear constraints
102-
`jfix` | `Vector{Int}` | indices of equality constraints
103-
`jlow` | `Vector{Int}` | indices of constraints of the form c(x) ≥ cl
104-
`jupp` | `Vector{Int}` | indices of constraints of the form c(x) ≤ cu
105-
`jrng` | `Vector{Int}` | indices of constraints of the form cl ≤ c(x) ≤ cu
106-
`jfree` | `Vector{Int}` | indices of "free" constraints (there shouldn't be any)
107-
`jinf` | `Vector{Int}` | indices of the visibly infeasible constraints
108-
`nnzo` | `Int ` | number of nonzeros in the gradient
109-
`nnzj` | `Int ` | number of nonzeros in the sparse Jacobian
110-
`lin_nnzj` | `Int ` | number of nonzeros in the sparse linear constraints Jacobian
111-
`nln_nnzj` | `Int ` | number of nonzeros in the sparse nonlinear constraints Jacobian
112-
`nnzh` | `Int ` | number of nonzeros in the lower triangular part of the sparse Hessian of the Lagrangian
113-
`minimize` | `Bool ` | true if `optimize == minimize`
114-
`islp` | `Bool ` | true if the problem is a linear program
115-
`name` | `String` | problem name
82+
Attribute | Type | Notes
83+
-------------------|---------------|------------------------------------
84+
`nvar` | `Int` | number of variables
85+
`x0 ` | `S` | initial guess
86+
`lvar` | `S` | vector of lower bounds
87+
`uvar` | `S` | vector of upper bounds
88+
`ifix` | `Vector{Int}` | indices of fixed variables
89+
`ilow` | `Vector{Int}` | indices of variables with lower bound only
90+
`iupp` | `Vector{Int}` | indices of variables with upper bound only
91+
`irng` | `Vector{Int}` | indices of variables with lower and upper bound (range)
92+
`ifree` | `Vector{Int}` | indices of free variables
93+
`iinf` | `Vector{Int}` | indices of visibly infeasible bounds
94+
`ncon` | `Int` | total number of general constraints
95+
`nlin ` | `Int` | number of linear constraints
96+
`nnln` | `Int` | number of nonlinear general constraints
97+
`y0 ` | `S` | initial Lagrange multipliers
98+
`lcon` | `S` | vector of constraint lower bounds
99+
`ucon` | `S` | vector of constraint upper bounds
100+
`lin ` | `Vector{Int}` | indices of linear constraints
101+
`nln` | `Vector{Int}` | indices of nonlinear constraints
102+
`jfix` | `Vector{Int}` | indices of equality constraints
103+
`jlow` | `Vector{Int}` | indices of constraints of the form c(x) ≥ cl
104+
`jupp` | `Vector{Int}` | indices of constraints of the form c(x) ≤ cu
105+
`jrng` | `Vector{Int}` | indices of constraints of the form cl ≤ c(x) ≤ cu
106+
`jfree` | `Vector{Int}` | indices of "free" constraints (there shouldn't be any)
107+
`jinf` | `Vector{Int}` | indices of the visibly infeasible constraints
108+
`nnzo` | `Int` | number of nonzeros in the gradient
109+
`nnzj` | `Int` | number of nonzeros in the sparse Jacobian
110+
`lin_nnzj` | `Int` | number of nonzeros in the sparse linear constraints Jacobian
111+
`nln_nnzj` | `Int` | number of nonzeros in the sparse nonlinear constraints Jacobian
112+
`nnzh` | `Int` | number of nonzeros in the lower triangular part of the sparse Hessian of the Lagrangian
113+
`minimize` | `Bool` | true if `optimize == minimize`
114+
`islp` | `Bool` | true if the problem is a linear program
115+
`name` | `String` | problem name
116+
`grad_available` | `Bool` | true if the gradient of the objective is available
117+
`jac_available` | `Bool` | true if the sparse Jacobian of the constraints is available
118+
`hess_available` | `Bool` | true if the sparse Hessian of the Lagrangian is available
119+
`jprod_available` | `Bool` | true if the Jacobian-vector product `J * v` is available
120+
`jtprod_available` | `Bool` | true if the transpose Jacobian-vector product `J' * v` is available
121+
`hprod_available` | `Bool` | true if the Hessian-vector product of the Lagrangian `H * v` is available
116122

117123
## License
118124

0 commit comments

Comments
 (0)