NLPModels.jl documentation

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 when designing optimization solvers in Julia.

Introduction

The general form of the optimization problem is

\[\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 \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

\[\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

\[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)$.

Optimization problems are represented by an instance/subtype of AbstractNLPModel. Such instances are composed of

  • an instance of NLPModelMeta, 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.

Nonlinear Least Squares

A special subtype of AbstractNLPModel is AbstractNLSModel, i.e., Nonlinear Least Squares models. In these problems, the function $f(x)$ is given by $\tfrac{1}{2}\Vert F(x)\Vert^2$, where $F$ is referred as the residual function. The individual value of $F$, as well as of its derivatives, is also available.

Tools

There are a few tools to use on NLPModels, for instance to query whether the problem is constrained or not, and to get the number of function evaluations. See Tools.

Install

Install NLPModels.jl with the following command.

pkg> add NLPModels

This will enable the use of the API and the tools described here, and it allows the creation of a manually written model. Look into Models for more information on that subject, and on a list of packages implementing ready-to-use models.

Usage

See the Models, the Tools, or the API.

Attributes

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

AttributeTypeNotes
nvarIntnumber of variables
x0Sinitial guess
lvarSvector of lower bounds
uvarSvector of upper bounds
ifixVector{Int}indices of fixed variables
ilowVector{Int}indices of variables with lower bound only
iuppVector{Int}indices of variables with upper bound only
irngVector{Int}indices of variables with lower and upper bound (range)
ifreeVector{Int}indices of free variables
iinfVector{Int}indices of visibly infeasible bounds
nconInttotal number of general constraints
nlinIntnumber of linear constraints
nnlnIntnumber of nonlinear general constraints
y0Sinitial Lagrange multipliers
lconSvector of constraint lower bounds
uconSvector of constraint upper bounds
linVector{Int}indices of linear constraints
nlnVector{Int}indices of nonlinear constraints
jfixVector{Int}indices of equality constraints
jlowVector{Int}indices of constraints of the form c(x) ≥ cl
juppVector{Int}indices of constraints of the form c(x) ≤ cu
jrngVector{Int}indices of constraints of the form cl ≤ c(x) ≤ cu
jfreeVector{Int}indices of "free" constraints (there shouldn't be any)
jinfVector{Int}indices of the visibly infeasible constraints
nnzoIntnumber of nonzeros in the gradient
nnzjIntnumber of nonzeros in the sparse Jacobian
lin_nnzjIntnumber of nonzeros in the sparse linear constraints Jacobian
nln_nnzjIntnumber of nonzeros in the sparse nonlinear constraints Jacobian
nnzhIntnumber of nonzeros in the sparse Hessian
minimizeBooltrue if optimize == minimize
islpBooltrue if the problem is a linear program
nameStringproblem name

License

This content is released under the MPL2.0 License.

Bug reports and discussions

If you think you found a bug, feel free to open an issue. Focused suggestions and requests can also be opened as issues. Before opening a pull request, start an issue or a discussion on the topic, please.

If you want to ask a question not suited for a bug report, feel free to start a discussion here. This forum is for general discussion about this repository and the JuliaSmoothOptimizers, so questions about any of our packages are welcome.

Contents