diff --git a/README.md b/README.md index 5d64ce6..4921f2e 100644 --- a/README.md +++ b/README.md @@ -4,85 +4,106 @@ [![MINLPTests](https://github.com/jump-dev/AmplNLWriter.jl/workflows/MINLPTests/badge.svg?branch=master)](https://github.com/jump-dev/AmplNLWriter.jl/actions?query=workflow%3AMINLPTests) [![codecov](https://codecov.io/gh/jump-dev/AmplNLWriter.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/jump-dev/AmplNLWriter.jl) -AmplNLWriter.jl is an interface between [MathOptInterface.jl](https://github.com/jump-dev/MathOptInterface.jl) +[AmplNLWriter.jl](https://github.com/jump-dev/AmplNLWriter.jl) is an interface +between [MathOptInterface.jl](https://github.com/jump-dev/MathOptInterface.jl) and [AMPL-enabled solvers](http://ampl.com/products/solvers/all-solvers-for-ampl/). -*Note: this wrapper is maintained by the JuMP community and has no official -connection with the AMPL modeling language or AMPL Optimization Inc.* +## Affiliation + +This wrapper is maintained by the JuMP community and has no official connection +with the AMPL modeling language or AMPL Optimization Inc. ## Installation -Install AmplNLWriter using `Pkg.add`. +Install AmplNLWriter using `Pkg.add`: ```julia import Pkg Pkg.add("AmplNLWriter") ``` -**Note: AmplNLWriter requires Julia 1.6 or later.** - -### Solvers +## Use with JuMP -You also need an AMPL compatible solver. +AmplNLWriter requires an AMPL compatible solver binary to function. -#### Bonmin (https://github.com/coin-or/Bonmin) +Pass a string pointing to any AMPL-compatible solver binary as the first +positional argument to `AmplNLWriter`. -To install Bonmin, use: +For example, if the `bonmin` executable is on the system path, use: ```julia -Pkg.add("Bonmin_jll") +using JuMP, AmplNLWriter +model = Model(() -> AmplNLWriter.Optimizer("bonmin")) ``` -#### Couenne (https://github.com/coin-or/Couenne) - -To install Couenne, use: +If the solver is not on the system path, pass the full path to the solver: ```julia -Pkg.add("Couenne_jll") +using JuMP, AmplNLWriter +model = Model(() -> AmplNLWriter.Optimizer("/Users/Oscar/ampl.macos64/bonmin")) ``` -#### Ipopt (https://github.com/coin-or/Ipopt) +## Precompiled binaries + +To simplify the process of installing solver binaries, a number of Julia +packages provide precompiled binaries that are compatible with AmplNLWriter. +These are generally the name of the solver, followed by `_jll`. For example, +`bomin` is provided by the `Bonmin_jll` package. -To install Ipopt, use: +To call Bonmin via AmplNLWriter.jl, install the `Bonmin_jll` package, then run: ```julia -Pkg.add("Ipopt_jll") +using JuMP, AmplNLWriter, Bonmin_jll +model = Model(() -> AmplNLWriter.Optimizer(Bonmin_jll.amplexe)) ``` -#### SHOT (https://github.com/coin-or/SHOT) +Supported packages include: -To install SHOT, use: -```julia -Pkg.add("SHOT_jll") -``` -**Warning: SHOT_jll uses open-source solvers and fails many of our unit tests. You may want to compile your own binary with commercial solvers.** +| Solver | Julia Package | Executable | +| --------------------------------------------- | ----------------- | --------------------- | +| [Bonmin](https://github.com/coin-or/Bonmin) | `Bonmin_jll.jl` | `Bomin_jll.amplexe` | +| [Couenne](https://github.com/coin-or/Couenne) | `Couenne_jll.jl` | `Couenne_jll.amplexe` | +| [Ipopt](https://github.com/coin-or/Ipopt) | `Ipopt_jll.jl` | `Ipopt_jll.amplexe` | +| [SHOT](https://github.com/coin-or/SHOT) | `SHOT_jll.jl` | `SHOT_jll.amplexe` | +| [KNITRO](https://github.comjump-dev/KNITRO.jl)| `KNITRO.jl` | `KNITRO.amplexe` | -## Usage +## MathOptInterface API -### JLL packages +The AmplNLWriter optimizer supports the following constraints and attributes. -To call Bonmin via AmplNLWriter.jl, use: -```julia -using JuMP, AmplNLWriter, Bonmin_jll -model = Model(() -> AmplNLWriter.Optimizer(Bonmin_jll.amplexe)) +List of supported objective functions: -# or equivalently + * [`MOI.ObjectiveFunction{MOI.ScalarAffineFunction{Float64}}`](@ref) + * [`MOI.ObjectiveFunction{MOI.ScalarQuadraticFunction{Float64}}`](@ref) + * [`MOI.ObjectiveFunction{MOI.VariableIndex}`](@ref) -model = Model() do - AmplNLWriter.Optimizer(Bonmin_jll.amplexe) -end -``` +List of supported variable types: -Replace `Bonmin_jll` with `Couenne_jll`, `Ipopt_jll`, or `SHOT_jll` as appropriate. + * [`MOI.Reals`](@ref) -### Other binaries +List of supported constraint types: -You can also pass a string pointing to an AMPL-compatible solver executable. For -example, if the `bonmin` executable is on the system path, use: -```julia -using JuMP, AmplNLWriter -model = Model(() -> AmplNLWriter.Optimizer("bonmin")) -``` + * [`MOI.ScalarAffineFunction{Float64}`](@ref) in [`MOI.EqualTo{Float64}`](@ref) + * [`MOI.ScalarAffineFunction{Float64}`](@ref) in [`MOI.GreaterThan{Float64}`](@ref) + * [`MOI.ScalarAffineFunction{Float64}`](@ref) in [`MOI.Interval{Float64}`](@ref) + * [`MOI.ScalarAffineFunction{Float64}`](@ref) in [`MOI.LessThan{Float64}`](@ref) + * [`MOI.ScalarQuadraticFunction{Float64}`](@ref) in [`MOI.EqualTo{Float64}`](@ref) + * [`MOI.ScalarQuadraticFunction{Float64}`](@ref) in [`MOI.GreaterThan{Float64}`](@ref) + * [`MOI.ScalarQuadraticFunction{Float64}`](@ref) in [`MOI.Interval{Float64}`](@ref) + * [`MOI.ScalarQuadraticFunction{Float64}`](@ref) in [`MOI.LessThan{Float64}`](@ref) + * [`MOI.VariableIndex`](@ref) in [`MOI.EqualTo{Float64}`](@ref) + * [`MOI.VariableIndex`](@ref) in [`MOI.GreaterThan{Float64}`](@ref) + * [`MOI.VariableIndex`](@ref) in [`MOI.Integer`](@ref) + * [`MOI.VariableIndex`](@ref) in [`MOI.Interval{Float64}`](@ref) + * [`MOI.VariableIndex`](@ref) in [`MOI.LessThan{Float64}`](@ref) + * [`MOI.VariableIndex`](@ref) in [`MOI.ZeroOne`](@ref) -If the solver is not on the path, the full path to the solver will need to be -passed in. +List of supported model attributes: + + * [`MOI.NLPBlock()`](@ref) + * [`MOI.Name()`](@ref) + * [`MOI.ObjectiveSense()`](@ref) + +Note that some solver executables may not support the full list of constraint +types. For example, `Ipopt_jll` does not support `MOI.Integer` or `MOI.ZeroOne` +constraints. ## Options @@ -93,24 +114,30 @@ A list of available options for each solver can be found here: - [Ipopt](https://coin-or.github.io/Ipopt/OPTIONS.html) - [SHOT](https://shotsolver.dev/shot/using-shot/solver-options) -Set an option using `set_optimizer_attribute`. For example, to set the +Set an option using [`set_attribute`](@ref). For example, to set the `"bonmin.nlp_log_level"` option to 0 in Bonmin, use: ```julia -using JuMP, AmplNLWriter, Bonmin_jll +using JuMP +import AmplNLWriter +import Bonmin_jll model = Model(() -> AmplNLWriter.Optimizer(Bonmin_jll.amplexe)) -set_optimizer_attribute(model, "bonmin.nlp_log_level", 0) +set_attribute(model, "bonmin.nlp_log_level", 0) ``` ### opt files -Some of the options need to be specified via an `.opt` file. This file must be -located in the current working directory whenever the model is solved. +Some options need to be specified via an `.opt` file. -The `.opt` file must be named after the name of the solver, e.g. `bonmin.opt`, and -each line must contain an option name and the desired value separated by a space. -For instance, to set the absolute and relative tolerances in Couenne to 1 and -0.05 respectively, the `couenne.opt` is: -``` +This file must be located in the current working directory whenever the model is +solved. + +The `.opt` file must be named after the name of the solver, for example, +`bonmin.opt`, and each line must contain an option name and the desired value, +separated by a space. + +For example, to set the absolute and relative tolerances in Couenne to `1` +and `0.05` respectively, the `couenne.opt` file should contain: +```raw allowable_gap 1 allowable_fraction_gap 0.05 ```