CUTEst.jl documentation

This package provides an interface to CUTEst, the Constrained and Unconstrained Testing Environment with safe threads for nonlinear optimization.

This package uses NLPModels.jl, but it also provides direct access to the CUTEst functions.

CUTEst brief history

CUTEst has been around for a while. It started as CUTE, then evolved into CUTEr, CUTEr2, and finally CUTEst. The original project can be used independently of Julia.

CUTEst works by decoding a .SIF file into other files and objects so that a user can compile and link them to their code. It also offers the option to perform these steps for you, in which case you need to send some code to its folder and request the compilation.

CUTEst provides about 100 methods to access the objective and constraint functions, as well as their derivatives in many different formats. It also offers access to the problem's information, such as the number of variables, constraints, the initial point, bounds, and so on.

Prerequisites

On all platforms except Windows, you'll need to install gfortran. On Windows, everything is installed for you thanks to Julia artifacts.

On Ubuntu, you can do this with:

sudo apt-get install gfortran

On Arch Linux, use:

sudo pacman -S gfortran

On macOS, use Homebrew:

brew install gfortran

Installation

The following command should automatically download and install CUTEst and its dependencies.

julia> ]
pkg> add CUTEst

Usage

You can check an Introduction to CUTEst.jl on our site.

The simplest way to use CUTEst is through the interface provided by NLPModels.jl.

using CUTEst, NLPModels

nlp = CUTEstModel{Float64}("ROSENBR")
println("x0 = $(nlp.meta.x0)")
println("fx = $( obj(nlp, nlp.meta.x0) )")
println("gx = $( grad(nlp, nlp.meta.x0) )")
println("Hx = $( hess(nlp, nlp.meta.x0) )")

x0 = [-1.2, 1.0]
fx = 24.199999999999996
gx = [-215.59999999999997, -87.99999999999999]
Hx = [1330.0 480.0; 480.0 200.0]

Check the NLPModels API for details.

You can pass parameters to sifdecoder by providing additional arguments to CUTEstModel. For instance, to change NH for the model CHAIN, use:

using CUTEst

for nh in 50:50:200
  nlp = CUTEstModel{Float64}("CHAIN", "-param", "NH=$nh")
  println("nh = $nh, nnzh = $(nlp.meta.nnzh)")
  finalize(nlp)
end

nh = 50, nnzh = 153
nh = 100, nnzh = 303
nh = 150, nnzh = 1203
nh = 200, nnzh = 603

Each call to CUTEstModel creates an independent model. You do not need to call finalize(nlp) manually: the finalizer in CUTEst.jl handles unloading the shared library automatically when the model is garbage-collected.

The finalizer is automatic, but when creating multiple models with the same problem name in the same process, you must finalize explicitly to avoid conflicts.

Working with CUTEst directly

We have also implemented functions to allow direct access to CUTEst functions through a core API, which serves as a wrapper for CUTEst. For more information, see the section on the core interface.