# Usage

This sections provides details on how to instantiate and solve a constrained least squares problem with `Enlsip.jl`

As a reminder from Home, problems to solve are of the following form:

\[\begin{aligned} \underset{x}{\min} \quad & \dfrac{1}{2} \|r(x)\|^2 \\ \text{s.t.} \quad & c_i(x) = 0, \quad i =1,\ldots,q \\ & c_j(x) \geq 0, \quad j=q+1,\ldots,\ell, \\ \end{aligned}\]

Note that with this formulation, bounds constraints are not distinguished from general inequality constraints. Though, as shown later in this section, they can be provided as vectors of lower and/or upper bounds, which is more convenient for this type of constraints.

Also, the `Enlsip`

solver works with double precision float numbers (i.e. type `Float64`

).

## Instantiate a model

Solving a problem with Enlsip is organized in two steps.

First, a model of type `CnlsModel`

must be instantiated.

The `CnlsModel`

constructor requires the evaluation functions of residuals, constraints, their associated jacobian matrices and dimensions of the problem.

Although the package enables one to create linear unconstrained least squares, it is recommended to use it to solve nonlinear least squares with general constraints.

The three following positional arguments are mandatory to create a model:

`residuals`

: function that computes the vector of residuals`nb_parameters`

: number of variables`nb_residuals`

: number of residuals

The following keywords arguments are optionnal and deal with constraints and jacobian matrices computations. If the jacobian matrices functions are not provided, they are computed numerically by forward differences within `Enlsip`

.

Argument | Details |
---|---|

`starting_point` | initial solution (can be an infeasbile point) |

`jacobian_residuals` | function computing the jacobian matrix of the residuals |

`eq_constraints` | function computing the equality constraints |

`jacobian_eqcons` | function computing the jacobian matrix of the equality constraints |

`nb_eqcons` | number of equality constraints |

`ineq_constraints` | function computing the inequality constraints |

`jacobian_ineqcons` | function computing the jacobian matrix of the inequality constraints |

`nb_ineqcons` | number of inequality constraints |

`x_low` | vector of lower bounds |

`x_upp` | vector of upper bounds |

## Solving a model

Then, the `Enlsip`

solver can be used by calling the `solve!`

function on a instantiated model.

Missing docstring for `Enlsip.solve!`

. Check Documenter's build log for details.

By default, the algorithm will print some details about the iterations performed through during execution.

Here are some details on how to read and understand the different columns of the output:

Column | Details |
---|---|

`iter` | iteration number |

`objective` | value of the sum of squared residuals (i.e. objective function) at current point |

$\vert\vert$ `active_constraints` $\vert\vert^2$ | value of the sum of squared active constraints at current point |

$\vert\vert$ `p` $\vert\vert$ | norm of the search direction computed at current iteration |

$\alpha$ | value of the steplength computed at current iteration |

`reduction` | reduction in the objective function performed at curret iteration |

Once the `Enlsip`

solver has been called, one can get additional info about the success, or failure, of the algorithm by calling one of the following functions:

Function |
---|

`solution` |

`status` |

`objective_value` |

Missing docstring for `Enlsip.solution`

. Check Documenter's build log for details.

Missing docstring for `Enlsip.status`

. Check Documenter's build log for details.

Missing docstring for `Enlsip.objective_value`

. Check Documenter's build log for details.

## Examples

### Problem 65 from Hock and Schittkowski collection^{}[1]

We show how to implement and solve the following problem:

\[\begin{aligned} \min \quad & (x_1-x_2)^2 + \dfrac{(x_1+x_2-10)^2}{9}+(x_3-5)^2 \\ \text{s.t.} \quad & 48-x_1^2-x_2^2-x_3^2 \geq 0\\ & -4.5\leq x_i \leq 4.5, \quad i=1,2\\ & -5 \leq x_3 \leq 5. \end{aligned}.\]

First, we provide the dimensions of the problems.

```
# Dimensions of the problem
n = 3 # number of parameters
m = 3 # number of residuals
nb_eq = 0 # number of equality constraints
nb_constraints = 7 # number of inequality constraints
```

Then, we define the functions required to compute the residuals, constraints, their respective jacobian matrices and a starting point.

```
# Residuals and jacobian matrix associated
r(x::Vector) = [x[1] - x[2]; (x[1]+x[2]-10.0) / 3.0; x[3]-5.0]
jac_r(x::Vector) = [1. -1. 0;
1/3 1/3 0.;
0. 0. 1.]
# Constraints (one equality and box constraints)
c(x::Vector) = [48.0 - x[1]^2-x[2]^2-x[3]^2] # evaluation function for the equality constraint
jac_c(x::Vector) = [ -2x[1] -2x[2] -2x[3]] # jacobian matrix of the equality constraint
x_l = [-4.5, -4.5, -5.0] # lower bounds
x_u = [4.5, 4.5, 5.0] # upper bounds
# Starting point
x0 = [-5.0, 5.0, 0.0]
```

A `CnlsModel`

can now be instantiated.

```
# Instantiate a model associated with the problem
hs65_model = Enlsip.CnlsModel(r, n, m ;starting_point=x0, ineq_constraints = c,
nb_ineqcons = 1, x_low=x_l, x_upp=x_u, jacobian_residuals=jac_r, jacobian_ineqcons=jac_c)
```

Finally, the `solve!`

function can be called on our model. In this example, we set the `silent`

optionnal argument to `true`

so no output will be printed. See previous Solving a model section for details about what is printed after solving a problem. Other optionnal arguments remain to default values.

`Enlsip.solve!(hs65_model, silent=true)`

Once `Enlsip`

solver has been executed on a problem, one can check if the problem has been successfully solved or not.

`Enlsip.status(hs65_model)`

`:successfully_solved`

One can also get the optimal solution obtained and value of objective function at that point.

`hs65_solution = Enlsip.solution(hs65_model)`

```
3-element Vector{Float64}:
3.650461726852526
3.6504617268525554
4.620417552729356
```

`hs65_objective = Enlsip.objective_value(hs65_model)`

`0.9535288568047827`

- 1W. Hock and K. Schittkowski. Test Examples for Nonlinear Programming Codes, volume 187 of Lecture Notes in Economics and Mathematical Systems. Springer, second edition, 1980.