Reference

AbstractCnlsModel

Abstract type for CnlsModel structure.

CnlsModel{T} where {T<:AbstractFloat}

Structure modeling an instance of a constrainted nonlinear least squares problem.

This structure contains the following attributes:

* `residuals` : function that computes the vector of residuals

* `nb_parameters::Int` : number of variables

* `nb_residuals::Int` : number of residuals

* `stating_point::Vector{T}` : initial solution

* `jacobian_residuals` : function that computes the jacobian matrix of the residuals

* `eq_constraints` : function that computes the vector of equality constraints

* `jacobian_eqcons` : function that computes the jacobian matrix of the equality constraints

* `nb_eqcons` : number of equality constraints

* `ineq_constraints` : function that computes the vector of inequality constraints

* `jacobian_ineqcons` : function that computes the jacobian matrix of the inequality constraints

* `nb_ineqcons::Int` : number of inequality constraints

* `x_low::Vector{T}` and `x_upp::Vector{T}` : respectively vectors of lower and upper bounds

* `status_code::Int` : integer indicating the solving status of the model

model = CnlsModel(residuals, nb_parameters, nb_residuals)

Constructor for CnlsModel.

• Positional arguments

  • residuals : function that computes the vector of residuals
  • nb_parameters : number of variables
  • nb_residuals : number of residuals

• Keywords arguments :

  • stating_point::Vector{T} : initial solution (default is a vector of zeros of appropriate dimension)
  • jacobian_residuals : function that computes the jacobian matrix of the residuals. If not passed as argument, it is computed numericcaly by forward differences
  • eq_constraints : function that computes the vector of equality constraints
  • jacobian_eqcons : function that computes the jacobian matrix of the equality constraints. If not passed as argument, it is computed numericcaly by forward differences
  • nb_eqcons::Int : number of equality constraints
  • ineq_constraints : function that computes the vector of inequality constraints
  • jacobian_ineqcons : function that computes the jacobian matrix of the inequality constraints. If not passed as argument, it is computed numericcaly by forward differences
  • nb_ineqcons::Int : number of inequality constraints
  • x_low::Vector{T} and x_upp::Vector{T} : respectively vectors of lower and upper bounds

bounds_constraints_values(model)

Returns the vector of box constraints values at the solution xₛ of model (if they are any).

If xₗ and xᵤ are respectively the vectors of lower and upper bounds, it will return [xₛ-xₗ; xᵤ-xₛ].

constraints_values(model)

Computes values of all the constraints in model at the solution.

The vector returned is the concatenation of equalities, inequalities and box constraints (in that order).

For instance, let xₛ be the solution found. If functions h, g compute equality and inequality constraints and xₗ, xᵤ are vectors of lower and lower bounds, it will return [h(xₛ); g(xₛ); xₛ-xₗ; xᵤ-xₛ].

If one wants to compute each type of constraints seperately, see equality_constraints_values, inequality_constraints_values and bounds_constraints_values.

equality_constraints_values(model)

Returns the vector of equality constraints values at the solution of model (if they are any).

inequality_constraints_values(model)

Returns the vector of inequality constraints values at the solution of model (if they are any).

print_cnls_model(model,io)

One can call this function to print information about an instance model (see CnlsModel).

If model has just been instantiated but not solved, it will print general information about the model, such as the dimensions of the residuals, parameters and constraints.

After calling the solve! method, the output will be enhanced with details about the iterations performed during the execution of the algorithm.

The following info are also printed:

• number of iterations

• total number of function and Jacobian matrix evaluations for both residuals and contraints

• solving time in seconds

• value of the objective function found by the algorithm

• termination status (see status)

solution(model)

Once the given model has been solved, this function returns the optimal solution, or last solution obtained if no convergence, as a Vector of approriate dimension.

solve!(model{T})

Once a CnlsModel has been instantiated, this function solves the optimzation problem associated by using the method implemented in the Enlsip solver.

Options:

• silent::Bool

  • Set to false if one wants the algorithm to print details about the iterations and termination of the solver

  • Default is true, i.e. by default, there is no output. If one wants to print those information afert solving, the print_cnls_model method

  can be called

• max_iter::Int

  • Maximum number of iterations allowed

  • Default is 100

• scaling::Bool

  • Set to true if one wants the algorithm to work with a constraints jacobian matrix whose rows are scaled (i.e. all constraints gradients vectors are scaled)

  • Default is false

• time_limit::T

  • Maximum elapsed time (i.e. wall time)

  • Default is 1000

Tolerances:

• abs_tol::T

  • Absolute tolerance for small residuals

  • Default is eps(T)

• rel_tol::T

  • Relative tolerance used to measure first order criticality and consistency

  • Default is sqrt(eps(T))

• c_tol::T

  • Tolerance used to measure feasability of the constraints

  • Default is sqrt(eps(T))

• x_tol::T

  • Tolerance used to measure the distance between two consecutive iterates

  • Default is sqrt(eps(T))

status(model)

This functions returns a Symbol that gives brief information on the solving status of model.

If a model has been instantiated but the solver has not been called yet, it will return :unsolved.

Once the solver has been called and if a first order stationary point satisfying the convergence criteria has been computed, it will return :found_first_order_stationary_point.

If the algorithm met an abnormall termination criteria, it will return one of the following:

• :failed : the algorithm encoutered a numerical error that triggered termination

• :maximum_iterations_exceeded : a solution could not be reached within the maximum number of iterations

• :time_limit_exceeded : the algorithm stopped because solving time exceeded the time limit

sum_sq_residuals(model)

Once the given model has been solved, returns the value of the objective function, i.e. sum of squared residuals functions, computed at the optimal solution. If no convergence, this value is computed at the last solution obtained.

total_nb_constraints(model)

Returns the total number of constraints, i.e. equalities, inequalities and bounds, of the given model.

See also: CnlsModel.