Using module nlsolv

The nlsolv module makes it possible to export a problem in the .nl file format, solve it using an external solver supporting this format, and retrieve solution values back into the Mosel model. To use this module the following line must be included in the header of the Mosel model file:

 uses 'nlsolv'

Using alternative solvers through nlsolv does not require any additional C coding, after installing a suitable solver executable the Mosel model merely needs to be configured via a couple of parameter settings.

This section explains how to setup nlsolv for various solvers and it also provides a documentation of the parameters and subroutines defined by this module.

For the handling of nonlinear expressions / constraints (type nlctr) the module nlsolv uses the functionality provided by the module mmnl that forms part of the standard Mosel distribution. All other functionality defined by mmnl, such as its subroutines for handling initial values, is equally available in models using nlsolv.

The module nlsolv supports the definition of multiple problems—it extends the definition of the type mpproblem.

Example: using nlsolv for Nonlinear Programming

The following example that calculates the shape of a hanging chain with N chainlinks and fixed endpoints is the same model as in Section Mosel model using myqxprs. Since nlsolv does not include any solver, the parameter NL_solver needs to be set to the (external) solver that is to be used. This may be any nonlinear solver supporting the .nl format and providing the functionality required by the particular model. If the name of the executable is different from the name of the solver prefix, its name needs to be specified via the parameter NL_solverpath as shown in this example for Xpress Optimizer.—Please note that the NL interface for Xpress only supports LP, MIP, and QCQP.

Other features shown by this model are the setting of initial values for decision variables and the retrieval of solution information at the end of the solver run—these functionalities are provided by the module mmnl that is included by nlsolv (see Chapter mmnl of the Mosel Language Reference Manual for the full documentation of mmnl).

model "catenary - NL version"
 uses "nlsolv"

 parameters
   SOLVER="xpress"
   SOLVERPATH="amplxpress"
   SOLVEROPTIONS=""

   N = 100                       ! Number of chainlinks
   L = 1                         ! Difference in x-coordinates of endlinks
   H = 2*L/N                     ! Length of each link
 end-parameters

 declarations
   RN = 0..N
   x: array(RN) of mpvar         ! x-coordinates of endpoints of chainlinks
   y: array(RN) of mpvar         ! y-coordinates of endpoints of chainlinks
   PotentialEnergy: linctr       ! Objective function
   Link: array(range) of nlctr   ! Constraints
 end-declarations

 forall(i in RN) x(i) is_free
 forall(i in RN) y(i) is_free

! Objective: minimise the potential energy
 PotentialEnergy:= sum(j in 1..N) (y(j-1)+y(j))/2

! Bounds: positions of endpoints
 x(0) = 0; y(0) = 0; x(N) = L; y(N) = 0

! Constraints: positions of chainlinks
 forall(j in 1..N)
   Link(j):= (x(j)-x(j-1))^2+(y(j)-y(j-1))^2 <= H^2

! Setting start values
 forall(j in RN) setinitval(x(j), j*L/N)
 forall(j in RN) setinitval(y(j), 0)

! Configuration of the solver
 setparam("nl_verbose", true)
 setparam("nl_solver", SOLVER)
 if SOLVERPATH<>"" then
   setparam("nl_solverpath", SOLVERPATH)
 end-if
 if SOLVEROPTIONS<>"" then
   setparam("nl_options", SOLVEROPTIONS)
 end-if

! Solve the problem
 minimise(PotentialEnergy)

! Solution reporting
 if getprobstat<>NL_OPT and getprobstat<>NL_UNF then
   writeln("No solution available. Solver status: ", getparam("NL_STATUS"))
 else
   writeln("Solution: ", getobjval)
   forall(j in RN)
     writeln(strfmt(getsol(x(j)),10,5), " ", strfmt(getsol(y(j)),10,5))
 end-if

end-model

Configuring a solver

The Xpress executable used by the example above is contained in the Xpress distribution. For other solvers please follow these steps:

1. Download a solver executable working with the NL format
   • for example: http://ampl.com/products/solvers/open-source
2. Make sure the solver executable is on the PATH
   • for example, same location as amplxpress[.exe]
     (bin subdirectory of Xpress installation)
   • alternatively, specify NL_SOLVERPATH
3. Configure your model to use the solver:
   • NL_SOLVER always needs to be set
   • use NL_SOLVERPATH if
     • the solver executable is not on the path, or
     • the executable name is different from the solver prefix in NL_SOLVER, or
     • the executable requires additional options (define a batch script)
   • optional: define specific solver settings in NL_OPTIONS

Here are some configuration examples for nlsolv controls under Windows:

• Xpress Optimizer (LP, MIP, QCQP)

  setparam("NL_SOLVER", "xpress")
  setparam("NL_SOLVERPATH", "amplxpress.exe")

• Knitro (requires a separate license, NLP)

  setparam("NL_SOLVER", "knitro")
  setparam("NL_SOLVERPATH", "knitroampl.exe")

• Cplex (requires a separate license, LP, MIP, QCQP)

  setparam("NL_SOLVER", "cplex")
  setparam("NL_SOLVERPATH", "cplexamp.exe")

• ipopt (NLP)

  setparam("NL_SOLVER", "ipopt")

• cbc (NLP)

  setparam("NL_SOLVER", "cbc")
  setparam("NL_SOLVERPATH", "cbc.bat")         ! Contents:    cbc %3 -AMPL

Control parameters

Via the getparam function and the setparam procedure it is possible to access the following control parameters of module nlsolv (the reader is reminded that parameters may be spelled with lower or upper case letters or a mix of both):

Procedures and functions

The following list gives an overview of all other functions and procedures defined by nlsolv for which we give detailed descriptions later.