OptimLib

Watch Star Fork

OptimLib is a lightweight C++ library of numerical optimization methods for nonlinear functions.

---

Features

• A C++11 library of local and global optimization algorithms, as well as root finding techniques.
• Derivative-free optimization using advanced, parallelized metaheuristics.
• Constrained optimization routines can handle simple box constraints, as well as systems of nonlinear constraints.
• Built on the Armadillo C++ linear algebra library for fast and efficient matrix-based computation.
• OpenMP-accelerated algorithms for parallel computation.
• Straightforward linking with parallelized BLAS libraries, such as OpenBLAS.
• Available as a header-only library, or in shared library format.
• Released under a permissive, non-GPL license.
• The source code is available on GitHub.

Author: Keith O'Hara

---

Contents

• Algorithms and General Syntax
• Installation Method 1: Shared Library
• Installation Method 2: Header-only Library
• R Compatibility
• Examples

---

Algorithms and General Syntax

Available Algorithms:

• Broyden's Method (for root finding)
• Newton's method, BFGS, and L-BFGS
• Gradient descent: basic, momentum, Adam, AdaMax, Nadam, NadaMax, and more
• Nonlinear Conjugate Gradient
• Nelder-Mead
• Differential Evolution (DE)
• Particle Swarm Optimization (PSO)

---

OptimLib functions have the following generic form:

algorithm_name(<initial and final values>, <objective function>, <objective function data>);

The inputs, in order, are:

• A writable vector of initial values to define the starting point of the algorithm. In the event of successful completion, the initial values will be overwritten by the solution vector.
• The 'objective function' is the user-defined function to be minimized (or zeroed-out in the case of root finding methods).
• The final input is optional: it is any object that contains additional parameters necessary to evaluate the objective function.

For example, the BFGS algorithm is called using

bool bfgs(arma::vec& init_out_vals, std::function<double (const arma::vec& vals_inp, arma::vec* grad_out, void* opt_data)> opt_objfn, void* opt_data);

---

Installation Method 1: Shared Library

The library can be installed on Unix-alike systems via the standard ./configure && make method:

# clone optim
git clone -b master --single-branch https://github.com/kthohr/optim ./optim
# build and install
cd ./optim
./configure -i "/usr/local" -p
make
make install

The last line will install OptimLib into /usr/local

Configuration options: (see ./configure -h)

Primary
• -h print help
• -i install path; default: the build directory
          example: -i "/usr/local"
• -m specify the BLAS and Lapack libraries to link against;
          examples: -m "-lopenblas" or -m "-framework Accelerate"
• -o compiler optimization options;
          default: -O3 -march=native -ffp-contract=fast -flto -DARMA_NO_DEBUG
• -p enable OpenMP parallelization features (recommended)
Secondary
• -c a coverage build (used with Codecov)
• -d a 'development' build
• -g a debugging build (optimization flags set to -O0 -g)
Special
• --header-only-version generate a header-only version of OptimLib (see below)

---

Armadillo

OptimLib is built on the Armadillo C++ linear algebra library. The configure script will search for Armadillo files in the standard locations: /usr/include, /usr/local/include, /opt/include, /opt/local/include. If the Armadillo header files are installed elsewhere, set the following environment variable before running configure:

export ARMA_INCLUDE_PATH=/path/to/armadillo

Otherwise the build script will proceed to download any required files from the Armadillo GitLab repository.

---

Installation Method 2: Header-only Library

The library is also available in header-only format (i.e., without compiling a shared library). Simply run configure with the --header-only-version option:

./configure --header-only-version

This will create a new directory header_only_version that contains a header-only copy of OptimLib.

---

R Compatibility

To use OptimLib with an R package, first generate a header-only version of the library (see above). Then add the compiler definition USE_RCPP_ARMADILLO before including the OptimLib files:

#define USE_RCPP_ARMADILLO
#include "optim.hpp"

Or you can set this preprocessor directive during compilation:

g++ ... -DUSE_RCPP_ARMADILLO ...

---

Examples

Examples can be found on the reference page for each algorithm.

---