# CaNNOLeS.jl tutorial

CaNNOLeS is a solver for equality-constrained nonlinear least-squares problems, i.e., optimization problems of the form

$\min \frac{1}{2}\|F(x)\|^2_2 \quad \text{s.to} \quad c(x) = 0.$

It uses other JuliaSmoothOptimizers packages for development. In particular, NLPModels.jl is used for defining the problem, and SolverCore for the output. It also uses HSL.jl's MA57 as main solver, but you can pass linsolve=:ldlfactorizations to use LDLFactorizations.jl.

## Fine-tune CaNNOLeS

CaNNOLeS.jl exports the function cannoles:

cannoles(nlp :: AbstractNLPModel; kwargs...)

Find below a list of the main options of cannoles.

### Tolerances on the problem

ParametersTypeDefaultDescription
atolAbstractFloat√eps(eltype(x))absolute tolerance
rtolAbstractFloat√eps(eltype(x))relative tolerance: the algorithm uses ϵtol := atol + rtol * ‖∇F(x⁰)ᵀF(x⁰) - ∇c(x⁰)ᵀλ⁰‖
FatolAbstractFloat√eps(eltype(x))absolute tolerance on the residual
FrtolAbstractFloat√eps(eltype(x))relative tolerance on the residual, the algorithm stops when ‖F(xᵏ)‖ ≤ Fatol + Frtol * ‖F(x⁰)‖ and ‖c(xᵏ)‖∞ ≤ √ϵtol
unbounded_thresholdAbstractFloat-1e5below this threshold the problem is unbounded
max_evalInteger100000maximum number of evaluations computed by neval_residual(nls) + neval_cons(nls)
max_iterInteger-1maximum number of iterations
max_timeAbstractFloat30.0maximum number of seconds
max_innerInteger10000maximum number of inner iterations (return stalled if this limit is reached)
verboseInteger0if > 0, display iteration details every verbose iteration

### Algorithmic parameters

ParametersTypeDefaultDescription
xAbstractVectornls.meta.x0initial guess
λAbstractVectornls.meta.y0initial guess for the Lagrange mutlipliers
useinitialmultiplierBoolfalseif true use λ for the initial stopping tests
methodSymbol:Newtonmethod to compute direction, :Newton, :LM, :Newton_noFHess, or :Newton_vanishing
linsolveSymbol:ma57solver use to compute the factorization: :ma57, :ma97, :ldlfactorizations
verboseInt0if > 0, display iteration details every verbose iteration
checksmallresidualBooltrueif true, stop whenever $$\|F(x)\|^2_2 \leq$$ ϵtol and $$\|c(x)\|_\infty \leq$$ √ϵtol
alwaysacceptextrapolationBoolfalseif true, run even if the extrapolation step fails
δdecRealeltype(x)(0.1)reducing factor on the parameter δ

## Examples

using CaNNOLeS, ADNLPModels

# Rosenbrock
nls = ADNLSModel(x -> [x[1] - 1; 10 * (x[2] - x[1]^2)], [-1.2; 1.0], 2)
stats = cannoles(nls, rtol = 1e-5, x = ones(2))
"Execution stats: first-order stationary"
# Constrained
stats = cannoles(nls, max_time = 10., linsolve = :ldlfactorizations)
"Execution stats: first-order stationary"