C++ Reference Manual

Octeract Engine v1.06.10
Copyright (c) Octeract Ltd, 2017-2020
June 12, 2020

Table Of Contents

1. Overview

The Octeract C++ API is a package that allows the Octeract Engine library functions to be accessed from within the C++ programming language. The API can also be utilised for writing either small stand-alone programs or C++ libraries within larger scale applications.

This manual assumes that you are familiar with the C++ programming language. The standard workflow for solving a global optimization problem using the API involves working with the Octeract Model object. An optimization problem can be built by using Model functions to add/remove variables, set the objective, and add/remove constraints. Once the Model has been built, the global_solve() function can be invoked, which sends the problem to the Octeract engine. As soon as the problem is solved to global optimality, a solution file is written, automatically read by the API and stored as an object in memory. The properties of the solution object (e.g. the optimal objective value and values of the decision variables) can then be accessed by the user and manipulated or fed in as data as part of a larger program.

2. A Simple Example

In this section, we show how to build a simple optimization problem using the C++ API based on the Haverly Pooling problem (a quadratically constrained problem). The current version of the API primarily uses a string-based interface, meaning the majority of the set() and add() methods will take strings as arguments. Future versions will have operator overloaded expression type objects that the user can manipulate directly without having to use quotation marks.

\begin{equation} \begin{aligned} & {\text{minimize}} & & x_1 – x_2 \\ & \text{subject to} & & x_1 – 6x_3 – 16x_4 – 10x_5 = 0 \\ &&& x_2 – 9x_6 – 15x_7 = 0 \\ &&& x_6 – x_8 – x_10 = 0 \\ &&& x_7 – x_9 – x_11 = 0 \\ &&& x_3 + x_4 – x_10 – x_11 = 0 \\ &&& x_5 – x_8 – x_9 = 0 \\&&& x_{12}(x_{10}+x_{11}) – 3x_2 – x_4 = 0 \\ &&& x_{12}x_{10} – 2.5x_{10} – 0.5x_8 \leq 0 \\ &&& x_{12}x_{11} – 1.5x_{11} + 0.5x_9 \leq 0 \ \end{aligned} \end{equation}


#include "octeract.h"

int main() {
    // Instantiate model
    auto m = octeract::Model();
    // Set the objective and add the constraints
    m.set_objective("x1-x2"); 
    m.add_constraint("x1 - 6*x3 - 16*x4 - 10*x5 = 0");
    m.add_constraint("x2 - 9*x6 - 15*x7 = 0");
    m.add_constraint("x6 - x8 - x10 = 0");
    m.add_constraint("x7 - x9 - x11 = 0");
    m.add_constraint("x3 + x4 - x10 - x11 = 0");
    m.add_constraint("x5 - x8 - x9 = 0");
    m.add_constraint("x12*(x10 + x11) - 3*x3 - x4 = 0");
    m.add_constraint("x12*x10 - 2.5*x10 - 0.5*x8 <= 0");
    m.add_constraint("x12*x11 - 1.5*x11 + 0.5*x9 <= 0");
    // Set the variable bounds
    m.set_variable_lb("x1", 0);
    m.set_variable_lb("x2", 0);
    m.set_variable_lb("x3", 0);
    m.set_variable_lb("x4", 0);
    m.set_variable_lb("x5", 0);
    m.set_variable_bounds("x6", 0, 100);
    m.set_variable_bounds("x7", 0, 200);
    m.set_variable_lb("x8", 0);
    m.set_variable_lb("x9", 0);
    m.set_variable_lb("x10", 0);
    m.set_variable_lb("x11", 0);
    m.set_variable_lb("x12", 0);
    // Solve to model to global optimality using 4 cores
    m.global_solve(4);
    return 0; 
}

The solver will produce its own real-time output so you will know when the solving process is done and the global solution is found, which in this case is -400.

The majority of the available methods have intuitive names, and you can use the tab completion functionality of your IDE or command shell, to see a list of the available methods. Since C++ is a very powerful and flexible language, users will easily be able to integrate their code as part of a larger overall project.

3. API Reference

This section provides a comprehensive list of all the API methods. Each subsection contains a brief description of the method, the arguments the function takes as input, the Return type, and example usages.

3.1 Model

3.1.1 Model()

Model()

Description:
Instantiates an empty model.
Arguments:
None
Return type:
None
Example usage:
auto m = Model()

3.1.2 Model.add constraint()

Model::add_constraint()

add_constraint(const std::string& constraint string)
Description:
Adds a constraint to the model.
Arguments:
constraint_string: the function string of the constraint to be added
Return type:
None
Example usage:
model.add_constraint("x1 + sin(x2*x3) = 2")

3.1.3 Model.add variable()

Model::add_variable()

add variable(const std::string& variable name, double lb=-OCT INFTY,
double ub=OCT INFTY, VarType variable type=CONT)
Description:
Adds a variable to the model
Arguments:
variable_name: the name of the variable to be added
lb: the lower bound of the variable
ub: the upper bound of the variable
variable type: the variable_type (CONT or BIN)
Return type:
None
Example usage:
model.add_variable("x1")
model.add_variable("x1", -1)
model.add_variable("x1", -10, 10)
model.add_variable("x1", 0, 1, BIN)

3.1.4 Model.classify problem()

Model::classify_problem()

classify_problem()
Description:
Detects the problem structure (MINLP, NLP, MIQCQP, QCQP, MIQP, QP, MILP, LP) of the current model.
Arguments:
None
Return type:
String
Example usage:
model.classify_problem()

3.1.5 Model.clear()

Model::clear()

clear()
Description:
Clears the model - removes the objective, all variables, all constraints and any settings the user might have
specified.
Arguments:
None
Return type:
None
Example usage:
model.clear()

3.1.6 Model.detect bounds()

Model::detect_bounds()

detect_bounds()
Description:
Tries to detect valid variable bounds based on the constraints present in the model.
Arguments:
None
Return type:
None
Example usage:
model.detect_bounds()

3.1.7 Model.detect problem convexity()

Model::detect_problem_convexity()

detect_problem_convexity()
Description:
Tries to determine whether the current model is convex using various techniques. If the problem is proven to
be convex, the function returns true, otherwise it returns false.
Arguments:
None
Return type:
Boolean
Example usage:
model.detect_problem_convexity()

3.1.8 Model.get binary constraint names()

Model::get_binary_constraint_names()

get_binary_constraint_names()
Description:
Returns a vector of constraint names which only contain binary variables.
Arguments:
None
Return type:
Vector of strings
Example usage:
model.get_binary_constraint_names()

3.1.9 Model.get binary variable names()

Model.get_binary_variable_names()

get_binary_variable_names()
Description:
Returns the binary variables of the model.
Arguments:
None
Return type:
Vector of strings
Example usage:
model.get_binary_variable_names()

3.1.10 Model.get bound multipliers()

Model::get_bound_multipliers()

get_bound_multipliers()
Description:
Returns a map of the decision variable names to their bound multipliers at the optimal solution.
Arguments:
None
Return type:
Unordered map from string to double
Example usage:
model.get_bound_multipliers()

3.1.11 Model.get constraint lb()

Model::get_constraint_lb()

get_constraint_lb(const std::string& constraint name)
Description:
Returns the lower bound of a constraint.
Arguments:
constraint_name: the name of the constraint
Return type:
Double
Example usage:
model.get_constraint_lb("c1")

3.1.12 Model.get constraint lhs()

Model::get_constraint_lhs()

get_constraint_lhs(const std::string& constraint name)
Description:
Returns the function string (left hand side) of a constraint.
Arguments:
constraint_name: the name of the constraint
Return type:
String
Example usage:
model.get_constraint_lhs("c1")

3.1.13 Model.get constraint multipliers()

Model::get_constraint_multipliers()

get_constraint_multipliers()
Description:
Returns a map of the constraint names to their Lagrange multipliers at the optimal solution.
Arguments:
None
Return type:
Unordered map from String to Double
Example usage:
model.get_constraint_multipliers()

3.1.14 Model.get constraint names()

Model::get_constraint_names()

get_constraint_names()
Description:
Returns all the constraints of the model.
Arguments:
None
Return type:
Vector of strings
Example usage:
model.get_constraint_names()

3.1.15 Model.get constraint ub()

Model::get_constraint_ub()

get_constraint_ub(const std::string& constraint name)
Description:
Returns the upper bound of a constraint.
Arguments:
constraint name: the name of the constraint
Return type:
Double
Example usage:
model.get_constraint_ub("c1")

3.1.16 Model.get constraint variables()

Model::get_constraint_variables()

get_constraint_variables(const std::string& constraint name)
Description:
Returns all the variables of a constraint.
Arguments:
constraint_name: the name of the constraint
Return type:
Vector of strings
Example usage:
model.get_constraint_variables("c1")

3.1.17 Model.get continuous variable names()

Model::get_continuous_variable_names()

get_continuous_variable_names()
Description:
Returns the continuous variables of the model.
Arguments:
None
Return type:
Vector of strings
Example usage:
model.get_continuous_variable_names()

3.1.18 Model.get linear constraint names()

Model::get_linear_constraint_names()

get_linear_constraint_names()
Description:
Returns the linear constraints of the model.
Arguments:
None
Return type:
Vector of strings
Example usage:
model.get_linear_constraint_names()

3.1.19 Model.get linear equality constraint names()

Model::get_linear_equality_constraint_names()

get_linear_equality_constraint_names()
Description:
Returns the linear equality constraints of the model.
Arguments:
None
Return type:
Vector of strings
Example usage:
model.get_linear_equality_constraint_names()

Model::get_linear_variable_names()

3.1.20 Model.get linear variable names()

get_linear_variable_names()
Description:
Returns the linear variables of the model.
Arguments:
None
Return type:
Vector of strings
Example usage:
model.get_linear_variable_names()

3.1.21 Model.get nonlinear constraint names()

Model::get_nonlinear_constraint_names()

get_nonlinear_constraint_names()
Description:
Returns the nonlinear constraints of the model.
Arguments:
None
Return type:
Vector of strings
Example usage:
model.get_nonlinear_constraint_names()

3.1.22 Model.get nonlinear equality constraint names()

Model::get_nonlinear_equality_constraint_names()

get_nonlinear_equality_constraint_names()
Description:
Returns the nonlinear equality constraints of the model.
Arguments:
None
Return type:
Vector of strings
Example usage:
model.get_nonlinear_equality_constraint_names()

3.1.23 Model.get nonlinear variable names()

Model::get_nonlinear_variable_names()

get_nonlinear_variable_names()
Description:
Returns the nonlinear variables of the model.
Arguments:
None
Return type:
Vector of strings
Example usage:
model.get_continuous_nonlinear_names()

3.1.24 Model.get objective function string()

Model::get_objective_function_string()

get_objective_function_string()
Description:
Returns the function string of objective.
Arguments:
None
Return type:
String
Example usage:
model.get_objective_function_string()

3.1.25 Model.get problem type()

Model::get_problem_type()

get_problem_type()
Description:
Returns the problem structure (MINLP, NLP, MIQCQP, QCQP, MIQP, QP, MILP, LP).
Arguments:
None
Return type:
String
Example usage:
model.get_problem_type()

3.1.26 Model.get solution objective value()

Model::get_solution_objective_value()

get_solution_objective_value()
Description:
Returns the value of the Objective at the optimal solution.
Arguments:
None
Return type:
Double
Example usage:
model.get_solution_objective_value()

3.1.27 Model.get solution path()

Model::get_solution_path()

get_solution_path()
Description:
Returns the path where the solution file will be written to.
Arguments:
None
Return type:
String
Example usage:
model.get_solution_path()

3.1.28 Model.get solution vector()

Model::get_solution_vector()

get_solution_vector()
Description:
Returns a map of the decision variable names to their optimal solution values.
Arguments:
None
Return type:
Unordered map from String to Double
Example usage:
model.get_solution_vector()

3.1.29 Model.get variable lb()

Model::get_variable_lb()

get_variable_lb(const std::string& variable name)
Description:
Returns the lower bound of a variable.
Arguments:
variable_name: the name of the variable
Return type:
Double
Example usage:
model.get_variable_lb("x1")

3.1.30 Model.get variable names()

Model::get_variable_names()

get_variable_names()
Description:
Returns all the variables of the model.
Arguments:
None
Return type:
Vector of strings
Example usage:
model.get_variable_names()

3.1.31 Model.get variable ub()

Model::get_variable_ub()

get_variable_ub(const std::string& variable name)
Description:
Returns the upper bound of a variable.
Arguments:
variable_name: the name of the variable
Return type:
Double
Example usage:
model.get_variable_ub("x1")

3.1.32 Model.global solve()

Model::global_solve()

global_solve()
Description:
Solves the model to global optimality.
Arguments:
None
Return type:
None
Example usage:
model.global_solve()

3.1.33 Model.import model file()

Model::import_model_file()

import_model_file(const std::string& problem file path)
Description:
Imports a model file, which can be either in ASL format (.nl extension) or AMPL format (.mod extension).
Arguments:
problem_file_path: the path to the problem file
Return type:
None
Example usage:
model.import_model_file("myProblem.nl")

3.1.34 Model.import solution file()

Model::import_solution_file()

import_solution_file(const std::string& solution file path)
Description:
Imports an Octeract solution file (.octsol extension) and stores the solution data in memory.
Arguments:
problem_file_path: the path to the problem file
Return type:
None
Example usage:
model.import_solution_file("myProblem.octsol")

3.1.35 Model.is problem convex()

Model::is_problem_convex()

Description:
Returns whether the current model has been detected to be convex.
Arguments:
None
Return type:
Boolean
Example usage:
model.is_problem_convex()

3.1.36 Model.local solve()

Model::local_solve()

local_solve()
Description:
Solves the model to local optimality.
Arguments:
None
Return type:
None
Example usage:
model.local_solve()

3.1.37 Model.num binary constraints()

Model::num_binary_constraints()

num_binary_constraints()
Description:
Returns the number of constraints which only contain binary variables.
Arguments:
None
Return type:
Integer
Example usage:
model.num_binary_constraints()

3.1.38 Model.num binary variables()

Model::num_binary_variables()

num_binary_variables()
Description:
Returns the number of binary variables present in the model.
Arguments:
None
Return type:
Integer
Example usage:
model.num_binary_variables()

3.1.39 Model.num constraints()

Model::num_constraints()

num_constraints()
Description:
Returns the total number of constraints present in the model.
Arguments:
None
Return type:
Integer
Example usage:
model.num_constraints()

3.1.40 Model.num continuous variables()

Model::num_continuous_variables()

num_continuous_variables()
Description:
Returns the number of continuous variables present in the model.
Arguments:
None
Return type:
Integer
Example usage:
model.num_continuous_variables()

3.1.41 Model.num linear constraints()

Model::num_linear_constraints()

num_linear_constraints()
Description:
Returns the number of linear constraints present in the model.
Arguments:
None
Return type:
Integer
Example usage:
model.num_linear_constraints()

3.1.42 Model.num nonlinear constraints() .

Model::num_nonlinear_constraints()

num_nonlinear_constraints()
Description:
Returns the number of nonlinear constraints present in the model.
Arguments:
None
Return type:
Integer
Example usage:
model.num_nonlinear_constraints()

3.1.43 Model.num nonlinear equality constraints()

Model::num_nonlinear_equality_constraints()

num_nonlinear_equality_constraints()
Description:
Returns the number of nonlinear equality constraints present in the model.
Arguments:
None
Return type:
Integer
Example usage:
model.num_nonlinear_equality_constraints()

3.1.44 Model.num nonlinear variables()

Model::num_nonlinear_variables()

num_nonlinear_variables()
Description:
Returns the number of nonlinear variables present in the model.
Arguments:
None
Return type:
Integer
Example usage:
model.num_nonlinear_variables()

3.1.45 Model.num variables()

Model::num_variables()

num_variables()
Description:
Returns the total number of variables present in the model.
Arguments:
None
Return type:
Integer
Example usage:
model.num_variables()

3.1.46 Model.print problem summary()

Model::print_problem_summary()

print_problem_summary()
Description:
Prints a summary of the loaded or constructed optimization problem onto the console.
Arguments:
None
Return type:
None
Example usage:
model.print_problem_summary()

3.1.47 Model.print solution summary()

Model::print_solution_summary()

print_solution_summary()
Description:
Prints a summary of the solution obtained from a local solve or global solve call.
Arguments:
None
Return type:
None
Example usage:
model.print_solution_summary()

3.1.48 Model.read options file()

Model::read_options_file()

read_options_file(const std::string& options file path)
Description:
Loads an options file, which will be read by the solver.
Arguments:
options_file_path: the path to the options file
Return type:
None
Example usage:
model.read_options_file("octeract.opt")

3.1.49 Model.remove all constraints()

Model::remove_all_constraints()

remove_all_constraints()
Description:
Removes all constraints from the model.
Arguments:
None
Return type:
None
Example usage:
model.remove_all_constraints()

3.1.50 Model.remove all variables()

Model::remove_all_variables()

remove_all_variables()
Description:
Removes all variables from the model. This effectively clears the model, as no objective or constraints can
exist in the model without the presence of variables.
Arguments:
None
Return type:
None
Example usage:
model.remove_all_variables()

3.1.51 Model.remove constraint()

Model::remove_constraint()

remove_constraint(const std::string& constraint name)
Description:
Removes a constraint of the model.
Arguments:
constraint_name: the name of the constraint to be removed
Return type:
None
Example usage:
model.remove_constraint("c1")

3.1.52 Model.remove objective()

Model::remove_objective()

remove_objective()
Description:
Removes the objective of the model
Arguments:
None
Return type:
None
Example usage:
model.remove_objective()

3.1.53 Model.remove variable()

Model::remove_variable()

remove_variable(const std::string& variable name)
Description:
Removes a variable of the model.
Arguments:
variable name: the name of the variable to be removed
Return type:
None
Example usage:
model.remove_variable("x1")

3.1.54 Model.set objective()

Model::set_objective()

set_objective(const std::string& objective string, ObjSense sense=MINIMIZE)
Description:
Sets the objective of the model
Arguments:
objective_string: the function string of the objective
sense: the objective sense (MINIMIZE or MAXIMIZE)
Return type:
None
Example usage:
model.set_objective("x1log(x1) + x1x2")
model.set_objective("x1*x2 + log(x3)", MAXIMIZE)

3.1.55 Model.set solver timeout()

Model::set_solver_timeout()

set_solver_timeout(double timeout)
Description:
Sets a timeout for the solver.
Arguments:
timeout: the timeout in seconds
Return type:
None
Example usage:
model.set_solver_timeout(10)

3.1.56 Model.set variable bounds()

Model::set_variable_bounds()

set_variable_bounds(const std::string& variable_name, double lb, double ub)
Description:
Sets the bounds of a variable.
Arguments:
variable_name: the name of the variable
lb: the lower bound of the variable
ub: the upper bound of the variable
Return type:
None
Example usage:
model.set_variable_bounds("x1", -10, 10)

3.1.57 Model.set variable lb()

Model::set_variable_lb()

set_variable_lb(const std::string& variable_name, double lb)
Description:
Sets the lower bound of a variable.
Arguments:
variable_name: the name of the variable
lb: the lower bound of the variable
Return type:
None
Example usage:
model.set_variable_lb("x1", 2)

3.1.58 Model.set variable type()

Model::set_variable_type()

set_variable_type(const std::string& variable name, VarType type)
Description:
Sets the type of a variable.
Arguments:
variable_name: the name of the variable
type: the type of the variable
Return type:
None
Example usage:
model.set_variable_type("x1", CONT)
model.set_variable_type("x1", BIN)

3.1.59 Model.set variable ub()

Model::set_variable_ub()

set_variable_ub(const std::string& variable_name, double ub)
Description:
Sets the upper bound of a variable.
Arguments:
variable name: the name of the variable
ub: the upper bound of the variable
Return type:
None
Example usage:
model.set_variable_ub("x1", 100)

3.1.60 Model.write current solution to file()

Model::write_current_solution_to_file()

write_current_solution_to_file(const std::string& file_path)
Description:
Writes the current solution (if any) to a file (Octeract solution format with a .octsol extension).
Arguments:
file_path: the path of the solution file
Return type:
None
Example usage:
model.write_current_solution_to_file("myProblem.octsol")

3.1.61 Model.write problem to mod file()

Model::write_problem_to_mod_file()

write_problem_to_mod_file(const std::string& file_path)
Description:
Writes the current model to an AMPL (extension .mod) file.
Arguments:
file_path: the path of the .mod file
Return type:
None
Example usage:
model.write_problem_to_mod_file("myProblem.mod")

3.1.62 Model.write problem to NL file()

Model::write_problem_to_NL_file()

write_problem_to_NL_file(const std::string& file_path)
Description:
Writes the current model to an ASL (extension .nl) file.
Arguments:
file_path: the path of the .nl file
Return type:
None
Example usage:
model.write_problem_to_NL_file("myProblem.nl")

%d bloggers like this: