3 releases (breaking)
0.5.0 | Jan 29, 2021 |
---|---|
0.4.0 | May 27, 2020 |
0.3.0 | Dec 10, 2018 |
#670 in Science
130KB
2.5K
SLoC
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
Dependencies
~1.5MB
~39K SLoC