Optimization Engines

1.Ipopt (Interior Point Optimizer) version 3.13.2

2.NLopt (NonLinear Optimizer) version 2.6.2

3.SNOPT (Sparse Nonlinear OPTimizer) version 7.7

Support for Ipopt and NLopt is built-in to FreeFlyer and requires no additional configuration on the part of the user, although the user has the option to provide their own shared library file for these engines if desired (in the form of a .dll file for Windows, or .so file for Linux). To use SNOPT, a user must have access to their own SNOPT license and provide the path to their SNOPT library when loading the optimization engine.

Each engine has its own specific set of configuration options, return codes/strings, and standard output behavior. Users should refer to the documentation for each third party library for more information regarding interpretation of output and return codes/strings.

Report opt.ThirdPartyLibraryName;

Report opt.ReturnCode;

Report opt.ReturnString;

Report opt.EngineOutput;

Note: NLopt does not generate any standard output, so the EngineOutput StringArray and LastGeneratedEngineOutput String properties on the Optimizer object will always be empty when the NLopt engine is selected.

Ipopt (Interior Point Optimizer) is an open source software package for large-scale nonlinear optimization that finds solutions that are locally optimal, which are often but not always globally optimal solutions. Ipopt version 3.13.2 comes included with FreeFlyer and does not require any additional setup, but can also be compiled with optimized linear algebra libraries that are hardware specific. Third party documentation for Ipopt is available online.

Dependencies

No additional dependencies are required to use the built-in version of Ipopt that is included with FreeFlyer. Refer to third party documentation for information on building customized Ipopt libraries separately from FreeFlyer.

Load Ipopt Engine

An Ipopt engine can be loaded into an Optimizer object using any of the following overloads to the Optimizer.LoadEngine() method. Ipopt is the default optimization engine in FreeFlyer and will be loaded when this method is called with no arguments.

Optimizer opt;

// Load built-in Ipopt engine

opt.LoadEngine();

// Load built-in Ipopt engine

opt.LoadEngine(0);

// Load Ipopt engine from a user-specified library (provide full file path)

opt.LoadEngine(0, "\libipopt.dll"); // Windows

opt.LoadEngine(0, "/libipopt.so"); // Linux

// Load Ipopt engine that has been configured through an IpoptOptions object

opt.LoadEngine(ipoptOptions);

IpoptOptions

The IpoptOptions object provides access to Ipopt-specific configuration parameters. These options can be configured entirely separately from the Optimizer object, then applied to the problem by loading in the IpoptOptions object when calling the Optimizer.LoadEngine() method. To set a user-provided library file in this configuration, set the IpoptOptions.SharedLibraryFilename property to point to the file.

IpoptOptions ipoptOptions;

ipoptOptions.SharedLibraryFilename = "\libipopt.dll";

A set of Ipopt options can be loaded from a file by setting the IpoptOptions.OptionsFilename property, which corresponds to the "option_file_name" option in native Ipopt. Refer to third party Ipopt documentation for more information on the required options file format.

There are a number of properties on the IpoptOptions object in FreeFlyer that correspond to native Ipopt options (for example, the IpoptOptions.Tolerance property corresponds to the "tol" option in native Ipopt); see the IpoptOptions Object page for a full list of all properties. All options in the Ipopt engine are identified by a string keyword, and their values can be of type Integer, Number, or String. Any of these can be configured from the IpoptOptions object in FreeFlyer through the AddIntOption(), AddNumOption(), and AddStrOption() methods. Refer to third party Ipopt documentation for information about all available options.

ipoptOptions.Tolerance = 1e-6; // Relative convergence tolerance

ipoptOptions.AddIntOption("max_iter", 5000); // Example Integer option

ipoptOptions.AddNumOption("max_cpu_time", 1000000); // Example Number option

ipoptOptions.AddStrOption("print_timing_statistics", "yes"); // Example String option

When all the desired options have been configured, the IpoptOptions object can be loaded into the Optimizer with the Optimizer.LoadEngine() method:

NLopt (NonLinear Optimizer) is an open source library for large-scale nonlinear optimization. NLopt version 2.6.2 comes included with FreeFlyer and does not require any additional setup, but can also be downloaded and installed separately. Third party documentation for NLopt is available online.

Dependencies

No additional dependencies are required to use the built-in version of NLopt that is included with FreeFlyer. Refer to third party documentation for information on using NLopt separately from FreeFlyer.

Load NLopt Engine

A NLopt engine can be loaded into an Optimizer object using any of the following overloads to the Optimizer.LoadEngine() method:

Optimizer opt;

// Load built-in NLopt engine

opt.LoadEngine(2);

// Load NLopt engine from a user-specified library (provide full file path)

opt.LoadEngine(2, "\nlopt.dll"); // Windows

opt.LoadEngine(2, "/libnlopt.so"); // Linux

// Load NLopt engine that has been configured through a NloptOptions object

opt.LoadEngine(nloptOptions);

NloptOptions

The NloptOptions object provides access to NLopt-specific configuration parameters. These options can be configured entirely separately from the Optimizer object, then applied to the problem by loading in the NLoptOptions object when calling the Optimizer.LoadEngine() method. To set a user-provided library file in this configuration, set the NloptOptions.SharedLibraryFilename property to point to the file.

NloptOptions nloptOptions;

nloptOptions.SharedLibraryFilename = "\nlopt.dll";

The properties on the NloptOptions object provide direct access from FreeFlyer to NLopt-specific configuration parameters such as the algorithm to use for the process; see the NloptOptions Object page for a full list of all properties. Refer to third party NLopt documentation for more information about each option, including details on the different algorithm choices.

When all the desired options have been configured, the NloptOptions object can be loaded into the Optimizer with the Optimizer.LoadEngine() method:

Note: NLopt supports global optimization, meaning that it can utilize algorithms to find the globally best solution even in the presence of multiple local optima. When using a global optimization algorithm, the NloptOptions.RelativeObjectiveTolerance property should be set to 0. See third party NLopt documentation for more information about global optimization algorithms.

SNOPT (Sparse Nonlinear OPTimizer) is a general-purpose system for constrained optimization suitable for large-scale linear, quadratic, and nonlinear programs. SNOPT finds solutions that are locally optimal, which are often but not always globally optimal solutions. SNOPT is developed, licensed, and distributed by Stanford University, and is not built in to FreeFlyer or available from a.i. solutions, Inc. Third party documentation for SNOPT is available online.

Dependencies

Users must provide their own SNOPT license and shared library file in order to use a SNOPT engine with FreeFlyer's Optimizer object, which is verified compatible with SNOPT version 7.7. Stanford offers a pre-built version of the SNOPT library, as well as the option for the user to build SNOPT themselves. The following dependencies are known to be required for the Stanford-built SNOPT v7.7:

Windows

•Intel Fortran Compiler 2018, Update 4

Linux

•libgfortran4

If errors occur when trying to load the SNOPT engine into the FreeFlyer Optimizer object, first confirm that all required dependencies are present. Note that dependencies beyond those listed here may be required if using a SNOPT library that was not pre-built by Stanford; if this is the case, consult third party SNOPT documentation and support for troubleshooting steps.

Load SNOPT Engine

A SNOPT engine can be loaded into an Optimizer object using any of the following overloads to the Optimizer.LoadEngine() method:

Optimizer opt;

// Load SNOPT engine from a user-specified library (provide full file path)

opt.LoadEngine(1, "\snopt7.dll"); // Windows

opt.LoadEngine(1, "/libsnopt7.so"); // Linux

// Load SNOPT engine that has been configured through a SnoptOptions object

opt.LoadEngine(snoptOptions);

SnoptOptions

The SnoptOptions object provides access to SNOPT-specific configuration parameters. These options can be configured entirely separately from the Optimizer object, then applied to the problem by loading in the SnoptOptions object when calling the Optimizer.LoadEngine() method. To set a user-provided library file in this configuration, set the SnoptOptions.SharedLibraryFilename property to point to the file.

SnoptOptions snoptOptions;

snoptOptions.SharedLibraryFilename = "\snopt7.dll";

A set of SNOPT options can be loaded from a SPECS file by setting the SnoptOptions.SpecFilename property. Refer to third party SNOPT documentation for more information on the required SPECS file format.

There are a number of properties on the SnoptOptions object in FreeFlyer that correspond to native SNOPT parameters (for example, the SnoptOptions.FunctionPrecision property corresponds to the "Function precision" parameter in native SNOPT); see the SnoptOptions Object page for a full list of all properties. All parameters in the SNOPT engine are identified by a string keyword, and their values can be of type Integer or Real Number. Any of these can be configured from the SnoptOptions object in FreeFlyer through the SetParameter(), SetIntParameter(), and SetRealParameter() methods. Refer to third party SNOPT documentation for information about all available options.

snoptOptions.FunctionPrecision = 5e-11; // Set accuracy for computing non-linear functions

snoptOptions.SetParameter("Maximize"); // Example parameter keyword (specifies direction of optimization)

snoptOptions.SetIntParameter("Major iterations limit", 1000); // Example Integer option

snoptOptions.SetRealParameter("Major feasibility tolerance", 1e-6); // Example Real Number option

When all the desired options have been configured, the SnoptOptions object can be loaded into the Optimizer with the Optimizer.LoadEngine() method:

Optimization Engines

Dependencies

Load Ipopt Engine

IpoptOptions

Dependencies

Load NLopt Engine

NloptOptions

Dependencies

Load SNOPT Engine

SnoptOptions

See Also