Initial docs in preparation for registration.

.github/workflows/Documentation.yml

@@ -0,0 +1,33 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master # update to match your development branch (master, main, dev, trunk, ...)
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: read
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - uses: julia-actions/cache@v2
+      - name: Install dependencies
+        shell: julia --color=yes --project=docs {0}
+        run: |
+          using Pkg
+          Pkg.develop(PackageSpec(path=pwd()))
+          Pkg.instantiate()
+      - name: Build and deploy
+        run: julia --color=yes --project=docs docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/cleanup-previews.yml

@@ -0,0 +1,34 @@
+# This workflow was based on CliMA/ClimaTimeSteppers.jl (Apache License 2.0).
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+          if [ -d "${preview_dir}" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "documenter@juliadocs.github.io"
+              git rm -rf "${preview_dir}"
+              git commit -m "delete preview"
+              git branch gh-pages-new "$(echo "delete history" | git commit-tree "HEAD^{tree}")"
+              git push --force origin gh-pages-new:gh-pages
+          fi
+        env:
+          preview_dir: previews/PR${{ github.event.number }}

README.md

@@ -1,6 +1,13 @@
 # MPCCModels
 
 [![Build Status](https://github.com/apozharski/MPCCModels.jl/actions/workflows/CI.yml/badge.svg?branch=master)](https://github.com/apozharski/MPCCModels.jl/actions/workflows/CI.yml?query=branch%3Amaster)
+[![docs-stable][docs-stable-img]][docs-stable-url]
+[![docs-dev][docs-dev-img]][docs-dev-url]
+
+[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
+[docs-stable-url]: https://madsuite.org/MPCCModels.jl/stable
+[docs-dev-img]: https://img.shields.io/badge/docs-dev-purple.svg
+[docs-dev-url]: https://madsuite.org/MPCCModels.jl/dev
 
 A julia package built on top of [NLPModels](https://github.com/JuliaSmoothOptimizers/NLPModels.jl/) for providing the functions needed to build solvers for Mathematical Programs with Complementarity Constraints.
 

docs/make.jl

@@ -21,5 +21,5 @@ makedocs(
 deploydocs(
   repo = "github.com/MadNLP/MPCCModels.jl.git",
   push_preview = true,
-  devbranch = "main",
+  devbranch = "master",
 )

docs/src/api.md

@@ -5,64 +5,66 @@ problem in the following format:
 ```math
 \begin{aligned}
 \min \quad & f(x) \\
-& c_L \leq c(x) \leq c_U \\
+& \ell_c \le c(x) \le u_c,\\
+& \ell_G\le G(x) \perp H(x)\ge l_H, \\
 & \ell \leq x \leq u.
 \end{aligned}
 ```
-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)^T``, the Jacobian of ``c`` at the point ``x``;
-- ``\nabla^2 f(x) + \sum_{i=1}^m y_i \nabla^2 c_i(x)``,
-  the Hessian of the Lagrangian function at the point ``(x,y)``.
-
-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;
-- `_coord` means coordinate format;
-- `_dense` means dense format;
-- `prod` means matrix-vector product;
-- `_op` means operator (as in [LinearOperators.jl](https://github.com/JuliaSmoothOptimizers/LinearOperators.jl));
-- `_lin` and `_nln` respectively refer to linear and nonlinear constraints.
-
-Feel free to open an issue to suggest other methods that should apply to all
-NLPModels instances.
+We implement this by wrapping an `AbstractNLPModel` in the form:
+```math
+\begin{aligned}
+\min \quad & f(x) \\
+& c_L \leq c'(x) \leq c_U \\
+& \ell \leq x \leq u,
+\end{aligned}
+```
+along with three vectors `ind_cc1`, `ind_cc2`, and `cc_types`.
+We encode the functions ``G(x)`` and ``H(x)`` via these vectors in the following way.
+The vectors `ind_cc1` and `ind_cc2` correspond to indexes into the vectors ``x`` and ``c'(x)``.
+Which of these vectors are the target of the indexing is determined by the values in `cc_types`:
 
-| Function          | NLPModels function                                                                                                                                                                                   |
-|-------------------|-------------------------------------------|
-| ``f(x)``            | [`obj`](@ref), [`objgrad`](@ref), [`objgrad!`](@ref), [`objcons`](@ref), [`objcons!`](@ref) |
-| ``\nabla f(x)``     | [`grad`](@ref), [`grad!`](@ref), [`objgrad`](@ref), [`objgrad!`](@ref) |
-| ``\nabla^2 f(x)``   | [`hess`](@ref), [`hess_op`](@ref), [`hess_op!`](@ref), [`hess_coord`](@ref), [`hess_coord!`](@ref), [`hess_dense!`](@ref), [`hess_structure`](@ref), [`hess_structure!`](@ref), [`hprod`](@ref), [`hprod!`](@ref) |
-| ``c(x)``            | [`cons_lin`](@ref), [`cons_lin!`](@ref), [`cons_nln`](@ref), [`cons_nln!`](@ref), [`cons`](@ref), [`cons!`](@ref), [`objcons`](@ref), [`objcons!`](@ref) |
-| ``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_dense!`](@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_dense!`](@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)  |
+| `CCType[k]` | ``G_k(x)`` | ``H_k(x)`` |
+|-------------|------------|------------|
+| `VarVar`    | ``x_i``    | ``x_j``    |
+| `VarCon`    | ``x_i``    | ``c'_j(x)`` |
+| `ConVar`    | ``c'_i(x)`` | ``x_j``    |
+| `ConCon`    | ``c'_i(x)`` | ``c'_j(x)`` |
 
-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`.
-You can also specify whether the Jacobian of the constraints and the Hessian of the objective or Lagrangian are sparse using the keyword arguments `sparse_jacobian` and `sparse_hessian`.
+This allows the user maximum flexibility when it comes to modelling the original MPCC.
+For practical algorithms however, we reformulate the problem into the so called "vertical form":
+```math
+\begin{aligned}
+\min \quad & f(x) \\
+& \ell_c \le c(x) \le u_c,\\
+& \ell_G\le x_1 \perp x_2\ge l_H, \\
+& \ell \leq x \leq u,
+\end{aligned}
+```
 
-## [API for NLSModels](@id nls-api)
+where all of the complementarity pairs are lifted to individual variables.
+This is done via the `vertical_form` function.
 
-For the Nonlinear Least Squares models, ``f(x) = \tfrac{1}{2} \Vert F(x)\Vert^2``,
-and these models have additional function to access the residual value
-and its derivatives. Namely,
+In order to develop algorithms for solving MPCCs we define the following api for the `AbstractMPCCModel` type:
 
-- ``J_F(x) = \nabla F(x)^T``
-- ``\nabla^2 F_i(x)``
+| Function                                              | `MPCCModels.jl` function                              | Notes                                         |
+|-------------------------------------------------------|-------------------------------------------------------|-----------------------------------------------|
+| ``G(x)``                                              | `comp_left`                                           | Raw evaluation of ``G(x)``                    |
+| ``G(x)-\ell_G``                                       | `comp_res_left`                                       | Left hand side complementarity residual       |
+| ``\nabla_x G(x)``                                     | `jac_comp_left_structure` and `jac_comp_left_coord`   | Jacobian of left hand side of complementarity |
+| ``H(x)``                                              | `comp_right`                                          |                                               |
+| ``H(x)-\ell_H``                                       | `comp_res_right`                                      | Right hand side complementarity residual      |
+| ``\nabla_x G(x)``                                     | `jac_comp_right_structure` and `jac_comp_right_coord` | Jacobian of left hand side of complementarity |
+| ``\vert\min(G(x)-\ell_G,H(x)-\ell_H)\vert_\infty``    | `comp_residual`                                       |                                               |
+| ``\vert (G(x)-\ell_G)\odot(H(x)-\ell_H)\vert_\infty`` | `comp_residual_product`                               |                                               |
+| ``(G(x)-\ell_G)\dot(H(x)-\ell_H)``                    | `comp_residual_sum`                                   |                                               |
 
-| Function            | function |
-|---------------------|---|
-| ``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) |
+along with overloads for the following `NLPModels.jl` api.
 
-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`.
+| Function                  | `NLPModels.jl` function                    | notes                                                                                                            |
+|---------------------------|--------------------------------------------|------------------------------------------------------------------------------------------------------------------|
+| ``f(x)``                  | `obj`                                      |                                                                                                                  |
+| ``\nabla f(x)``           | `grad`                                     |                                                                                                                  |
+| ``c(x)``                  | `cons`                                     | Note that this includes possible lifted constraints but _not_ those contained in ``G(x)`` or ``H(x)``            |
+| ``\nabla c(x)``           | `jac`, `jac_structure`, and `jac_coord`    | Note that this includes possible lifted constraints but _not_ those contained in ``G(x)`` or ``H(x)``            |
+| ``\nabla^2 L(x,\lambda)`` | `hess`, `hess_structure`, and `hess_coord` | Note that this is not the MPCC lagrangian but the NLP Lagrangian with no contribution from the complementarities |

docs/src/index.md

@@ -1,50 +1,32 @@
 # [MPCCModels.jl documentation](@id Home)
 
-This package provides general guidelines to represent non-linear programming (NLP)
-problems in Julia and a standardized API to evaluate the functions and
-their derivatives. The main objective is to be able to rely on that [API](@ref) when
-designing optimization solvers in Julia.
+This package provides general guidelines to represent Mathematical Programs with Complementarity Constraints (MPCC) problems in Julia and a standardized API to evaluate the functions and their derivatives. 
+The main objective is to be able to rely on that [API](@ref) when designing specialized MPCC solvers in Julia.
 
 ## Introduction
 
-The general form of the optimization problem is
+This package is built for modelling problems of the form
 ```math
 \begin{aligned}
 \min \quad & f(x) \\
-& c_i(x) = c_{E_i}, \quad i \in {\cal E}, \\
-& c_{L_i} \leq c_i(x) \leq c_{U_i}, \quad i \in {\cal I}, \\
+& \ell_c \le c_i(x) \le u_c,\\
+& \ell_G\le G(x) \perp H(x)\ge l_H, \\
 & \ell \leq x \leq u,
 \end{aligned}
 ```
 where ``f:\mathbb{R}^n\rightarrow\mathbb{R}``,
 ``c:\mathbb{R}^n\rightarrow\mathbb{R}^m``,
-``{\cal E}\cup {\cal I} = \{1,2,\dots,m\}``, ``{\cal E}\cap {\cal I} = \emptyset``,
-and
-``c_{E_i}, c_{L_i}, c_{U_i}, \ell_j, u_j \in \mathbb{R}\cup\{\pm\infty\}``
-for ``i = 1,\dots,m`` and ``j = 1,\dots,n``.
-
-For computational reasons, we write
-```math
-\begin{aligned}
-\min \quad & f(x) \\
-& c_L \leq c(x) \leq c_U \\
-& \ell \leq x \leq u,
-\end{aligned}
-```
-defining ``c_{L_i} = c_{U_i} = c_{E_i}`` for all ``i \in {\cal E}``.
-The Lagrangian of this problem is defined as
-```math
-L(x,y,z^L,z^U;\sigma) = \sigma f(x) + c(x)^T y  + \sum_{i=1}^n z_{L_i}(x_i-l_i) + \sum_{i=1}^n z_{U_i}(u_i-x_i),
-```
-where ``\sigma`` is a scaling parameter included for computational reasons.
-Since the final two sums are linear in ``x``, the variables ``z_L`` and ``z_U`` do not appear in the Hessian ``\nabla^2 L(x,y)``.
+``G:\mathbb{R}^n\rightarrow\mathbb{R}^{n_{cc}}``,
+``H:\mathbb{R}^n\rightarrow\mathbb{R}^{n_{cc}}``,
+and ``\ell_a \le a\perp b \ge \ell_b`` means that for each element of the vectors a and b, at least one must be zero.
 
 Optimization problems are represented by an instance/subtype of `AbstractMPCCModel`.
 Such instances are composed of
 
-- an instance of [`MPCCModelMeta`](@ref Attributes), which provides information about the problem,
+- an instance of `MPCCModelMeta`, which provides information about the problem,
   including the number of variables, constraints, bounds on the variables, etc.
-- other data specific to the provenance of the problem.
+  This `MPCCModelMeta` wraps an `AbstractNLPModelMeta` and only updates the necessary fields by overloading the getter api in `NLPModels.jl`.
+- the underlying `AbstractNLPModel` which stores the data necessary to build the MPCC.
 
 ## Install
 
@@ -55,6 +37,7 @@ pkg> add MPCCModels
 
 This will enable the use of the API and the tools described here, and it allows the creation of a manually written model.
 
+
 ## License
 
 This content is released under the [MIT](https://opensource.org/license/mit) License.

docs/src/reference.md

@@ -13,5 +13,6 @@ Pages = ["reference.md"]
 ```
 
 ```@autodocs
-Modules = [NLPModels]
+Modules = [MPCCModels]
+Pages   = ["MPCCModels.jl", "api.jl", "model.jl", "utils.jl", "meta.jl"]
 ```

src/MPCCModels.jl

@@ -3,9 +3,10 @@ using NLPModels, LinearAlgebra, SparseArrays
 
 """
   Abstract type for problems in the form:
-  min f(w)
-  s.t. lbc ≤ c(w) ≤ ubc
-       0 ≤ G(w) ⟂ H(w) ≥ 0
+
+    min f(w)
+    s.t. lbc ≤ c(w) ≤ ubc
+         lbG ≤ G(w) ⟂ H(w) ≥ lbH
 """
 abstract type AbstractMPCCModel{T, VT} end