Add ModelWithQuad and privatize the product functions of QPBlockData (#3053)

* Add ModelWithQuad and privatize the product functions of QPBlockData

Making a first release with public add_constraint_jacobian_product,
add_constraint_jacobian_transpose_product, and
add_hessian_lagrangian_product commits MOI to three new function names.
Instead, rename them _add_... and add ModelWithQuad/EvaluatorWithQuad:
the evaluator implements the standard MOI.AbstractNLPEvaluator
interface (including the product callbacks, composed inner-first so
that store-semantics inner implementations such as ReverseAD do not
clobber the QP contribution), so consumers only rely on existing
generic functions and the QPBlockData internals stay private.

ModelWithQuad routes affine and quadratic objectives and constraints
to a QPBlockData and everything else to an inner model, forwards the
MOI attribute queries of the QP block, and tracks where the objective
lives. EvaluatorWithQuad remaps the variables of the QP block to their
consecutive index in ordered_variables during MOI.initialize (variables
absent from ordered_variables are parameters and keep their index,
with the parameters dictionary aliased so per-solve value syncs are
visible), and MOI.NLPBlockData(evaluator) assembles the combined
constraint bounds.

* Remove the unused nothing-inner support of ModelWithQuad

No solver passes `inner = nothing`: the consumers all wrap an eager inner
`Nonlinear.Model`, so drop the `set_objective(::Nothing, ::Nothing)` hook
and the docstring sentence advertising it. A solver that manages its own
nonlinear storage can still define `set_objective` for its inner type.

* Remove MOI.set for the objective of ModelWithQuad

Nonlinear.set_objective is the single way to set the objective: it does
everything the MOI.set method did, and it also accepts nothing to clear the
objective, which the MOI attribute interface cannot express. The MOI getters
stay since the function API has no counterpart for them.

* Move the variables and the parameter convention into ModelWithQuad

ModelWithQuad now owns a MOI.Utilities.VariablesContainer and implements
MOI.add_variable, guaranteeing variable indices 1:n like
MOI.Utilities.MatrixOfConstraints, so the EvaluatorWithQuad no longer remaps
the QP block. Parameters are added with MOI.add_constrained_variable: their
indices are offset by _PARAMETER_OFFSET (moved here from Ipopt), QPBlockData
is back to the simple offset-based _is_parameter instead of the parameters
dictionary, and its parameters vector aliases the parameter storage of the
inner Nonlinear.Model, so solvers no longer sync parameter values before a
solve.

* Always alias the parameter storage of the inner model

Sharing only when the inner model is a Nonlinear.Model silently left
qp.parameters empty for any other inner model type. Assume instead that the
inner model exposes its parameter values as parameters::Vector{T}, like
Nonlinear.Model does, and always alias it; an inner model without that field
fails loudly at construction.

* Define _is_parameter on the affine and quadratic terms

They belong next to the convention; Ipopt and MadNLP defined them on their
local alias of the function, which pirates it.

* Move the parameter substitution into ModelWithQuad

The substitution of the offset parameter indices by ParameterIndex before
the inner model parses a function is index arithmetic tied to the parameter
convention of the layer, so it belongs here: the generic add_constraint and
set_objective now perform it, and the solvers just forward.

* Use an enum for the objective sink of ModelWithQuad

* Implement NumberOfVariables and ListOfVariableIndices

* Return ListOfVariableIndices in the order of creation

Its docstring requires the order in which the variables were added, with the
parameters interleaved, so ModelWithQuad records that order instead of
appending the parameters after the variables.

* Fail if the inner evaluator does not implement the structure queries

An inner evaluator with constraint rows must support :Jac (and :Hess when
the Hessian is queried), so do not silently skip it in jacobian_structure
and hessian_lagrangian_structure.

* Rely on the store contract of the product callbacks

MOI.eval_constraint_jacobian_transpose_product and
MOI.eval_hessian_lagrangian_product store their result, zeroing the output,
so calling the inner evaluator first makes pre-filling the output redundant.
The Jacobian product only zeroes the rows of the QP block, into which the
block accumulates; the inner evaluator stores its own rows.

* Fix unresolvable references in the documentation

_PARAMETER_OFFSET and _is_parameter are private and not part of any docs
block, so the docstrings of QPBlockData and ModelWithQuad cannot link to
them with @ref.

* Cover all lines of model_with_quad.jl and qp_block_data.jl

Add tests for the gradients of affine and quadratic objectives (affine and
off-diagonal terms), the nonlinear objective gradient, the VariableIndex
objective function type, the ConstraintSet getters and constraint-index
filtering of every bound set, the Hessian and product evaluations of a
parameterized QP block, nonlinear functions mentioning the parameter and the
variable directly, and a parameter-free affine subfunction that the
substitution leaves as is.

* Cover the quadratic parameter substitution

Add nonlinear constraints with quadratic subfunctions, with and without a
parameter, and query ListOfSupportedNonlinearOperators through the layer.
These methods were never compiled by the tests, which local coverage reports
as non-executable lines but codecov reports as uncovered.

Author: blegat

docs/src/submodules/Nonlinear/reference.md

@@ -73,9 +73,8 @@ Nonlinear.ExprGraphOnly
 Nonlinear.SparseReverseMode
 Nonlinear.SymbolicMode
 Nonlinear.QPBlockData
-Nonlinear.add_constraint_jacobian_product
-Nonlinear.add_constraint_jacobian_transpose_product
-Nonlinear.add_hessian_lagrangian_product
+Nonlinear.ModelWithQuad
+Nonlinear.EvaluatorWithQuad
 
 ```
 

src/Nonlinear/Nonlinear.jl

@@ -43,5 +43,6 @@ include("ReverseAD/ReverseAD.jl")
 include("SymbolicAD/SymbolicAD.jl")
 
 include("qp_block_data.jl")
+include("model_with_quad.jl")
 
 end  # module