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):

Attribute	Type	Notes
`nvar`	`Int`	number of variables
`x0`	`S`	initial guess
`lvar`	`S`	vector of lower bounds
`uvar`	`S`	vector of upper bounds
`ifix`	`Vector{Int}`	indices of fixed variables
`ilow`	`Vector{Int}`	indices of variables with lower bound only
`iupp`	`Vector{Int}`	indices of variables with upper bound only
`irng`	`Vector{Int}`	indices of variables with lower and upper bound (range)
`ifree`	`Vector{Int}`	indices of free variables
`iinf`	`Vector{Int}`	indices of visibly infeasible bounds
`ncon`	`Int`	total number of general constraints
`nlin`	`Int`	number of linear constraints
`nnln`	`Int`	number of nonlinear general constraints
`y0`	`S`	initial Lagrange multipliers
`lcon`	`S`	vector of constraint lower bounds
`ucon`	`S`	vector of constraint upper bounds
`lin`	`Vector{Int}`	indices of linear constraints
`nln`	`Vector{Int}`	indices of nonlinear constraints
`jfix`	`Vector{Int}`	indices of equality constraints
`jlow`	`Vector{Int}`	indices of constraints of the form c(x) ≥ cl
`jupp`	`Vector{Int}`	indices of constraints of the form c(x) ≤ cu
`jrng`	`Vector{Int}`	indices of constraints of the form cl ≤ c(x) ≤ cu
`jfree`	`Vector{Int}`	indices of "free" constraints (there shouldn't be any)
`jinf`	`Vector{Int}`	indices of the visibly infeasible constraints
`nnzo`	`Int`	number of nonzeros in the gradient
`nnzj`	`Int`	number of nonzeros in the sparse Jacobian
`lin_nnzj`	`Int`	number of nonzeros in the sparse linear constraints Jacobian
`nln_nnzj`	`Int`	number of nonzeros in the sparse nonlinear constraints Jacobian
`nnzh`	`Int`	number of nonzeros in the sparse Hessian
`minimize`	`Bool`	true if `optimize == minimize`
`islp`	`Bool`	true if the problem is a linear program
`name`	`String`	problem 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.