Parametric AD API

docs/make.jl

@@ -17,6 +17,7 @@ makedocs(
     "Tools" => "tools.md",
     "API" => "api.md",
     "Batch API" => "batch_api.md",
+    "Parametric API" => "param_api.md",
     "Internals" => "internals.md",
     "Reference" => "reference.md",
   ],

docs/src/param_api.md

@@ -0,0 +1,165 @@
+# Parametric API
+
+This section documents the optional parametric API of `NLPModels.jl`.
+The parametric API provides derivatives of the problem data with respect to parameters `p`, for problems of the form
+
+```math
+\begin{aligned}
+\min \quad & f(x, p) \\
+& c_L(p) \leq c(x, p) \leq c_U(p) \\
+& \ell(p) \leq x \leq u(p).
+\end{aligned}
+```
+
+The main use-case is implicit differentation of KKT conditions, where the forming the RHS requires evaluating the derivatives of the problem data with respect to parameters.
+
+Note that `p` does not appear as an explicit argument to any of the functions below.
+Implementations are responsible for storing the current parameter values internally (e.g., as a field of the model struct) and reading them when evaluating the functions.
+
+---
+
+## Parameter access
+
+NLPModels provides a common interface for setting and getting the current parameter values:
+
+| Function | Signature |
+|:--------:|:---------:|
+| `get_param_values`  | `p = get_param_values(nlp)` |
+| `set_param_values!` | `set_param_values!(nlp, p)` |
+
+---
+
+## Objective gradient wrt parameters
+
+Evaluate ``\nabla_p f(x, p)``, the gradient of the objective with respect to the parameters at the current `x`:
+
+| Function | Signature |
+|:--------:|:---------:|
+| `grad_param`  | `g = grad_param(nlp, x)` |
+| `grad_param!` | `g = grad_param!(nlp, x, g)` |
+
+---
+
+## Sparse constraint Jacobian wrt parameters
+
+Evaluate ``J_p(x) = \nabla_p c(x, p)^T``, the Jacobian of the constraints with respect to the parameters:
+
+| Function | Signature |
+|:--------:|:---------:|
+| `jac_param_structure`  | `(rows, cols) = jac_param_structure(nlp)` |
+| `jac_param_structure!` | `(rows, cols) = jac_param_structure!(nlp, rows, cols)` |
+| `jac_param_coord`  | `vals = jac_param_coord(nlp, x)` |
+| `jac_param_coord!` | `vals = jac_param_coord!(nlp, x, vals)` |
+
+---
+
+## Constraint Jacobian-vector products wrt parameters
+
+Evaluate products with ``J_p(x)`` and ``J_p(x)^T`` without forming the matrix explicitly:
+
+| Function | Signature |
+|:--------:|:---------:|
+| `jpprod`  | `Jv = jpprod(nlp, x, v)` |
+| `jpprod!` | `Jv = jpprod!(nlp, x, v, Jv)` |
+| `jptprod`  | `Jtv = jptprod(nlp, x, v)` |
+| `jptprod!` | `Jtv = jptprod!(nlp, x, v, Jtv)` |
+
+---
+
+## Sparse variable-parameter Hessian of the Lagrangian
+
+Evaluate ``\nabla^2_{xp} L(x, y, p)``, the mixed variable-parameter Hessian of the Lagrangian.
+When `y` is omitted, only the objective contribution should be included (i.e., `y = 0`):
+
+| Function | Signature |
+|:--------:|:---------:|
+| `hess_param_structure`  | `(rows, cols) = hess_param_structure(nlp)` |
+| `hess_param_structure!` | `(rows, cols) = hess_param_structure!(nlp, rows, cols)` |
+| `hess_param_coord`  | `vals = hess_param_coord(nlp, x; obj_weight)` |
+| `hess_param_coord`  | `vals = hess_param_coord(nlp, x, y; obj_weight)` |
+| `hess_param_coord!` | `vals = hess_param_coord!(nlp, x, vals; obj_weight)` |
+| `hess_param_coord!` | `vals = hess_param_coord!(nlp, x, y, vals; obj_weight)` |
+
+---
+
+## Variable-parameter Hessian-vector products
+
+Evaluate products with ``\nabla^2_{xp} L(x, y, p)`` and its transpose.
+When `y` is omitted, only the objective contribution should be included (i.e., `y = 0`):
+
+| Function | Signature |
+|:--------:|:---------:|
+| `hpprod`  | `Hv = hpprod(nlp, x, v; obj_weight)` |
+| `hpprod`  | `Hv = hpprod(nlp, x, y, v; obj_weight)` |
+| `hpprod!` | `Hv = hpprod!(nlp, x, v, Hv; obj_weight)` |
+| `hpprod!` | `Hv = hpprod!(nlp, x, y, v, Hv; obj_weight)` |
+| `hptprod`  | `Htv = hptprod(nlp, x, y, v; obj_weight)` |
+| `hptprod!` | `Htv = hptprod!(nlp, x, y, v, Htv; obj_weight)` |
+
+---
+
+## Sparse constraint lower-bound Jacobian wrt parameters
+
+Evaluate ``\nabla_p c_L(p)``, the Jacobian of the constraint lower bounds with respect to the parameters:
+
+| Function | Signature |
+|:--------:|:---------:|
+| `lcon_jac_param_structure`  | `(rows, cols) = lcon_jac_param_structure(nlp)` |
+| `lcon_jac_param_structure!` | `(rows, cols) = lcon_jac_param_structure!(nlp, rows, cols)` |
+| `lcon_jac_param_coord`  | `vals = lcon_jac_param_coord(nlp)` |
+| `lcon_jac_param_coord!` | `vals = lcon_jac_param_coord!(nlp, vals)` |
+| `lcon_jpprod`  | `Jv = lcon_jpprod(nlp, v)` |
+| `lcon_jpprod!` | `Jv = lcon_jpprod!(nlp, v, Jv)` |
+| `lcon_jptprod`  | `Jtv = lcon_jptprod(nlp, v)` |
+| `lcon_jptprod!` | `Jtv = lcon_jptprod!(nlp, v, Jtv)` |
+
+---
+
+## Sparse constraint upper-bound Jacobian wrt parameters
+
+Evaluate ``\nabla_p c_U(p)``, the Jacobian of the constraint upper bounds with respect to the parameters:
+
+| Function | Signature |
+|:--------:|:---------:|
+| `ucon_jac_param_structure`  | `(rows, cols) = ucon_jac_param_structure(nlp)` |
+| `ucon_jac_param_structure!` | `(rows, cols) = ucon_jac_param_structure!(nlp, rows, cols)` |
+| `ucon_jac_param_coord`  | `vals = ucon_jac_param_coord(nlp)` |
+| `ucon_jac_param_coord!` | `vals = ucon_jac_param_coord!(nlp, vals)` |
+| `ucon_jpprod`  | `Jv = ucon_jpprod(nlp, v)` |
+| `ucon_jpprod!` | `Jv = ucon_jpprod!(nlp, v, Jv)` |
+| `ucon_jptprod`  | `Jtv = ucon_jptprod(nlp, v)` |
+| `ucon_jptprod!` | `Jtv = ucon_jptprod!(nlp, v, Jtv)` |
+
+---
+
+## Sparse variable lower-bound Jacobian wrt parameters
+
+Evaluate ``\nabla_p \ell(p)``, the Jacobian of the variable lower bounds with respect to the parameters:
+
+| Function | Signature |
+|:--------:|:---------:|
+| `lvar_jac_param_structure`  | `(rows, cols) = lvar_jac_param_structure(nlp)` |
+| `lvar_jac_param_structure!` | `(rows, cols) = lvar_jac_param_structure!(nlp, rows, cols)` |
+| `lvar_jac_param_coord`  | `vals = lvar_jac_param_coord(nlp)` |
+| `lvar_jac_param_coord!` | `vals = lvar_jac_param_coord!(nlp, vals)` |
+| `lvar_jpprod`  | `Jv = lvar_jpprod(nlp, v)` |
+| `lvar_jpprod!` | `Jv = lvar_jpprod!(nlp, v, Jv)` |
+| `lvar_jptprod`  | `Jtv = lvar_jptprod(nlp, v)` |
+| `lvar_jptprod!` | `Jtv = lvar_jptprod!(nlp, v, Jtv)` |
+
+---
+
+## Sparse variable upper-bound Jacobian wrt parameters
+
+Evaluate ``\nabla_p u(p)``, the Jacobian of the variable upper bounds with respect to the parameters:
+
+| Function | Signature |
+|:--------:|:---------:|
+| `uvar_jac_param_structure`  | `(rows, cols) = uvar_jac_param_structure(nlp)` |
+| `uvar_jac_param_structure!` | `(rows, cols) = uvar_jac_param_structure!(nlp, rows, cols)` |
+| `uvar_jac_param_coord`  | `vals = uvar_jac_param_coord(nlp)` |
+| `uvar_jac_param_coord!` | `vals = uvar_jac_param_coord!(nlp, vals)` |
+| `uvar_jpprod`  | `Jv = uvar_jpprod(nlp, v)` |
+| `uvar_jpprod!` | `Jv = uvar_jpprod!(nlp, v, Jv)` |
+| `uvar_jptprod`  | `Jtv = uvar_jptprod(nlp, v)` |
+| `uvar_jptprod!` | `Jtv = uvar_jptprod!(nlp, v, Jtv)` |

src/NLPModels.jl

@@ -44,4 +44,6 @@ end
 include("nlp/batch_api.jl")
 include("nlp/batch_meta.jl")
 
+include("nlp/param_api.jl")
+
 end # module

src/nlp/meta.jl

@@ -140,6 +140,35 @@ struct NLPModelMeta{T, S} <: AbstractNLPModelMeta{T, S}
   jprod_available::Bool
   jtprod_available::Bool
   hprod_available::Bool
+
+  # Parametric fields
+  nparam::Int
+  nnzjp::Int
+  nnzhp::Int
+  nnzgp::Int
+  nnzjplcon::Int
+  nnzjpucon::Int
+  nnzjplvar::Int
+  nnzjpuvar::Int
+  grad_param_available::Bool
+  jac_param_available::Bool
+  hess_param_available::Bool
+  jpprod_available::Bool
+  jptprod_available::Bool
+  hpprod_available::Bool
+  hptprod_available::Bool
+  lcon_jac_available::Bool
+  ucon_jac_available::Bool
+  lvar_jac_available::Bool
+  uvar_jac_available::Bool
+  lcon_jpprod_available::Bool
+  ucon_jpprod_available::Bool
+  lvar_jpprod_available::Bool
+  uvar_jpprod_available::Bool
+  lcon_jptprod_available::Bool
+  ucon_jptprod_available::Bool
+  lvar_jptprod_available::Bool
+  uvar_jptprod_available::Bool
 end
 
 function NLPModelMeta{T, S}(
@@ -173,8 +202,37 @@ function NLPModelMeta{T, S}(
   jprod_available::Bool = (ncon > 0),
   jtprod_available::Bool = (ncon > 0),
   hprod_available::Bool = true,
+  # Parametric fields
+  nparam::Int = 0,
+  nnzjp::Int = 0,
+  nnzhp::Int = 0,
+  nnzgp::Int = 0,
+  nnzjplcon::Int = 0,
+  nnzjpucon::Int = 0,
+  nnzjplvar::Int = 0,
+  nnzjpuvar::Int = 0,
+  grad_param_available::Bool = false,
+  jac_param_available::Bool = false,
+  hess_param_available::Bool = false,
+  jpprod_available::Bool = false,
+  jptprod_available::Bool = false,
+  hpprod_available::Bool = false,
+  hptprod_available::Bool = false,
+  lcon_jac_available::Bool = false,
+  ucon_jac_available::Bool = false,
+  lvar_jac_available::Bool = false,
+  uvar_jac_available::Bool = false,
+  lcon_jpprod_available::Bool = false,
+  ucon_jpprod_available::Bool = false,
+  lvar_jpprod_available::Bool = false,
+  uvar_jpprod_available::Bool = false,
+  lcon_jptprod_available::Bool = false,
+  ucon_jptprod_available::Bool = false,
+  lvar_jptprod_available::Bool = false,
+  uvar_jptprod_available::Bool = false,
 ) where {T, S}
-  if (nvar < 1) || (ncon < 0) || (nnzj < 0) || (nnzh < 0)
+  if (nvar < 1) || (ncon < 0) || (nnzj < 0) || (nnzh < 0) || (nparam < 0) || (nnzjp < 0) || (nnzhp < 0) || (nnzgp < 0) ||
+     (nnzjplcon < 0) || (nnzjpucon < 0) || (nnzjplvar < 0) || (nnzjpuvar < 0)
     error("Nonsensical dimensions")
   end
 
@@ -265,6 +323,33 @@ function NLPModelMeta{T, S}(
     jprod_available,
     jtprod_available,
     hprod_available,
+    nparam,
+    nnzjp,
+    nnzhp,
+    nnzgp,
+    nnzjplcon,
+    nnzjpucon,
+    nnzjplvar,
+    nnzjpuvar,
+    grad_param_available,
+    jac_param_available,
+    hess_param_available,
+    jpprod_available,
+    jptprod_available,
+    hpprod_available,
+    hptprod_available,
+    lcon_jac_available,
+    ucon_jac_available,
+    lvar_jac_available,
+    uvar_jac_available,
+    lcon_jpprod_available,
+    ucon_jpprod_available,
+    lvar_jpprod_available,
+    uvar_jpprod_available,
+    lcon_jptprod_available,
+    ucon_jptprod_available,
+    lvar_jptprod_available,
+    uvar_jptprod_available,
   )
 end