Descent

A non-linear constrained optimisation (mathematical programming) modelling library with first and second order automatic differentiation / source-code symbolic differentiation. Currently has an interface to the non-linear solver Ipopt.

Dependencies

Ipopt (or Bonmin) must be separately installed before attempting to build as descent_ipopt links to the libipopt.so shared library.

It has only been tested on linux, but presumably would also work on macos, and potentially on windows in the right environment.

For use in your own crate, add the following to your own Cargo.toml file:

[dependencies]
descent = "0.3"
descent_ipopt = "0.3"
descent_macro = "0.3" # for optional but recommended expr! procedural macro use

Example

The following code shows how to solve the following simple problem in IPOPT: min 2 y s.t. y >= x * x - x, x in [-10, 10].

use descent::model::Model;
use descent_ipopt::IpoptModel;

let mut m = IpoptModel::new();

let x = m.add_var(-10.0, 10.0, 0.0);
let y = m.add_var(std::f64::NEG_INFINITY, std::f64::INFINITY, 0.0);
m.set_obj(2.0 * y);
m.add_con(y - x * x + x, 0.0, std::f64::INFINITY);

let (stat, sol) = m.solve();

A full example of this with additional details is provided under descent_ipopt/examples/simple.rs, which can be built and run as follows:

cargo build --release --example simple
./target/release/examples/simple

Code optimizations are important, so be sure to turn them on or use the release build option when testing your code for performance.

Modelling

The operators +, -, *, .powi(i32), .sin(), and .cos() are supported in mathematical expressions. Expressions can be generated either via operator overloading or with a procedural macro (requires nightly rust).

Automatic Differentiation via Operator Overloading

Expressions can be dynamically generated with maximum flexibility using operator overloading. This is the approach adopted in the example provided above.

Source-Code Transformation via Procedural Macro

If nightly rust is available, then a procedural macro can be used to "statically" generate functions for evaluating the expression and calculating its first and second derivatives. This provides a huge performance increase over the dynamic operator overloading and AD approach. The above example using the procedural macro expression generation approach looks like the following:

#![feature(proc_macro_hygiene)]

use descent::model::Model;
use descent_ipopt::IpoptModel;
use descent_macro::expr;

let mut m = IpoptModel::new();

let x = m.add_var(-10.0, 10.0, 0.0);
let y = m.add_var(std::f64::NEG_INFINITY, std::f64::INFINITY, 0.0);
m.set_obj(expr!(2.0 * y; y));
m.add_con(expr!(y - x * x + x; x, y), 0.0, std::f64::INFINITY);

let (stat, sol) = m.solve();

A more complete example can be found in descent_ipopt/examples/problem_macro.rs.

Parameterization

The library allows parameterisation of values and easy solver warmstarting to enable quick model adjustments and resolving.

TODO

• Clean up the hastily written procedural macro.
• Integrate with ipopt-sys crate and possibly ipopt crate instead of using / maintaining own bindings.
• Bonmin bindings (enabling MINLP).

License

Apache-2.0 or MIT