Math::NLopt NLopt is a library for nonlinear local and global optimization, for functions with and without gradient information. It is designed as a simple, unified interface and packaging of several free/open-source nonlinear optimization libraries. Math::NLopt is a Perl binding to NLopt. It uses the Alien::NLopt module to find or install a Perl local instance of the NLopt library. This module provides an interface using native Perl arrays. The main documentation for NLopt may be found at ; this document focuses on the Perl specific implementation, which is more Perlish than the C API (and is very similar to the Python one). API The Perl API uses an object, constructed by the "new" class method, to maintain state. The optimization process is controlled by invoking methods on the object. *In general* results are returned directly from the methods; method parameters are used primarily as input data for the methods (the objective and constraint callbacks more closely follow the C API). The Perl methods are named similarly to the C functions, e.g. nlopt_( opt, ... ); becomes $opt->method( ... ); Where $opt is provided by the "new" class method. As an example, the C API for starting the optimization process is nlopt_result nlopt_optimize(nlopt_opt opt, double *x, double *opt_f); where x is used for both passing in the initial model parameters as well as retrieving their final values. The final value of the optimization function is stored in opt_f. A code specifying the success or failure of the process is returned. The Perl interface (similar to the Python and C++ versions) is \@final = $opt->optimize( \@initial_pars ); $opt_f = $opt->last_optimum_value; $result_code = $opt->last_optimize_result; The Perl API throws exceptions on failures, similar to the behavior of the C++ and Python API's. Where the C API returns error codes, "Math::NLopt" throws objects in similarly named exception classes: Math::NLopt::Exception::Failure Math::NLopt::Exception::OutOfMemory Math::NLopt::Exception::InvalidArgs Math::NLopt::Exception::RoundoffLimited> Math::NLopt::Exception::ForcedStop These all extend the Math::NLopt::Exception class; see it for more information on retrieving messages from the objects. Constants Math::NLopt defines constants for the optimization algorithms, result codes, and utilities. The algorithm constants have the same names as the NLopt constants, and may be imported individually by name or en-masse with the ':algorithms' tag: use Math::NLopt 'NLOPT_LD_MMA'; use Math::NLopt ':algorithms'; Importing result codes is similar: use Math::NLopt 'NLOPT_FORCED_STOP'; use Math::NLopt ':results'; As are the utility subroutines: use Math::NLopt 'algorithm_from_string'; use Math::NLopt ':utils'; Callbacks NLopt handles the optimization of the objective function, relying upon user provided subroutines to calculate the objective function and non-linear constraints (see below for the required calling signature). The callback subroutines are called with a user-provided structure which can be used to pass additional information to the callback (or the subroutines can use closures). Objective Functions Objective functions callbacks are registered via either $opt->set_min_objective( \&func, ?$data ); $opt->set_max_objective( \&func, ?$data ); where $data is an optional structure passed to the callback which can be used for any purpose. The objective function has the signature $value = sub ( \@params, \@gradient, $data ) { ... } It returns the value of the optimization function for the passed set parameters, @params. if \@gradient is not "undef", it must be filled in by the objective function. $data is the structure registered with the callback. It will be "undef" if none was provided. Non-linear Constraints Nonlinear constraint callbacks are registered via either of $opt->add_equality_constraint( \&func, ?$data, ?$tol = 0 ); $opt->add_inequality_constraint( \&func, ?$data, ?$tol = 0 ); where $data is an optional structure passed to the callback which can be used for any purpose, and $tol is a tolerance. Pass "undef" for $data if a tolerance is required but $data is not. The callbacks have the same signature as the objective callbacks. Vector-valued Constraints Vector-valued constraint callbacks are registered via either of $opt->add_equality_mconstraint( \&func, $m, ?$data, ?\@tol ); $opt->add_inequality_mconstraint( \&func, $m, ?$data, ?\@tol ); where $m is the length of the vector, $data is an optional structure passed on to the callback function, and @tol is an optional array of length $m containing the tolerance for each component of the vector Vector valued constraints callbacks have the signature sub ( \@result, \@params, \@gradient, $data ) { ... } The $m length vector of constraints should be stored in "\@result". If "\@gradient" is not "undef", it is a *$n x $m* length array which should be filled by the callback. $data is the optional structure passed to the callback. Preconditioned Objectives These are registered via one of $opt->set_precond_min_objective( \&func, \&precond, ?$data); $opt->set_precond_max_objective( \&func, \&precond, ?$data); "\&func" has the same signature as before (see "Objective Functions"), and $data is as before. The "\&precond" fallback has this signature: sub (\@x, \@v, \@vpre, $data) {...} "\@x", "\@v", and "\@vpre" are arrays of length $n. "\@x", "\@v" are input and "\@vpre" should be filled in by the routine. INSTALLATION This is a Perl module distribution. It should be installed with whichever tool you use to manage your installation of Perl, e.g. any of cpanm . cpan . cpanp -i . Consult http://www.cpan.org/modules/INSTALL.html for further instruction. Should you wish to install this module manually, the procedure is perl Makefile.PL make make test make install COPYRIGHT AND LICENSE This software is Copyright (c) 2024 by Smithsonian Astrophysical Observatory. This is free software, licensed under: The GNU General Public License, Version 3, June 2007