Python API Reference Manual
explanation practical insight Python API Reference manual 1. Overview
2. A Simple Example
3. API Reference
3.1 Model
3.1.1 Model
3.1.2 model.add_constraint()
3.1.3 model.add_variable()
3.1.4 model.classify_problem()
3.1.5 model.clear()
3.1.6 model.detect_bounds()
3.1.7 model.detect_problem_convexity()
3.1.8 model.get_binary_constraint_names()
3.1.9 model.get_binary_variable_names()
3.1.10 model.get_bound_multipliers()
3.1.11 model.get_constraint_lb()
3.1.12 model.get_constraint_lhs()
3.1.13 model.get_constraint_names()
3.1.14 model.get_constraint_ub()
3.1.15 model.get_constraint_variables()
3.1.16 model.get_continuous_variable_names()
3.1.17 model.get_linear_constraint_names()
3.1.18 model.get_linear_equality_constraint_names()
3.1.19 model.get_linear_variable_names()
3.1.20 model.get_nonlinear_constraint_names()
3.1.21 model.get_nonlinear_equality_constraint_names()
3.1.22 model.get_nonlinear_variable_names()
3.1.23 model.get_objective_function_string()
3.1.24 model.get_problem_type()
3.1.25 model.get_solution_objective_value()
3.1.26 model.get_solution_path()
3.1.27 model.get_solution_vector()
3.1.28 model.get_variable_lb()
3.1.29 model.get_variable_names()
3.1.30 model.get_variable_ub()
3.1.31 model.global_solve()
3.1.32 model.import_model_file()
3.1.33 model.import_solution_file()
3.1.34 model.is_problem_convex()
3.1.35 model.local_solve()
3.1.36 model.num_binary_constraints()
3.1.37 model.num_binary_variables()
3.1.38 model.num_constraints()
3.1.39 model.num_continuous_variables()
3.1.40 model.num_linear_constraints()
3.1.41 model.num_nonlinear_constraints()
3.1.42 model.num_nonlinear_equality_constraints()
3.1.43 model.num_nonlinear_variables()
3.1.44 model.num_variables()
3.1.45 model.print_problem_summary()
3.1.46 model.print_solution_summary()
3.1.47 model.read_options_file()
3.1.48 model.remove_all_constraints()
3.1.49 model.remove_all_variables()
3.1.50 model.remove_constraint()
3.1.51 model.remove_objective()
3.1.52 model.remove_variable()
3.1.53 model.set_objective()
3.1.54 model.set_variable_bounds()
3.1.55 model.set_variable_lb()
3.1.56 model.set_variable_type()
3.1.57 model.set_variable_ub()
3.1.58 model.write_current_solution_to_file()
3.1.59 model.write_problem_to_mod_file()
3.1.60 model.write_problem_to_NL_file()
3.1.61 model.write_problem_to_ALE_file()
3.1.62 model.write_problem_to_MPS_file()
3.1.63 model.write_problem_to_LP_file()
3.1.64 model.maximize()
3.1.65 model.minimize()
3.1.66 model.set()
3.1.67 model.set_option()
3.1.68 print()
1. Overview
The Octeract Python API is a package that allows the Octeract Engine library functions to be accessed from within the Python programming language.
When first familiarising yourself with the API, we recommend using the library interactively with a command shell like IPython3, as the tab completion functionality provided is extremely useful when browsing through the available API calls. The API can also be utilised for writing either small stand-alone scripts or Python libraries within larger scale applications.
When first familiarising yourself with the API, we recommend using the library interactively with a command shell like IPython3, as the tab completion functionality provided is extremely useful when browsing through the available API calls. The API can also be utilised for writing either small stand-alone scripts or Python libraries within larger scale applications.
This manual assumes that you are familiar with the Python programming language, and that you have the appropriate version of the Python distribution installed on your system.
The standard workflow for solving a global optimisation problem using the API involves working with the Octeract Model object.
An optimisation 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
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.
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 will go through building a simple optimisation 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.
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} \quad & x_1-x_2-i_1 \\
\text{subject to} \quad & 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_3-x_4 + b_2 = 0 \\
& x_{12}x_{10}-2.5x_{10}i_1-0.5x_8b_1 \le 0 \\
& x_{12}x_{11}-1.5x_{11}+0.5x_9 \le 0 \\
& b_1 + b_2 \le 1 \\
& x_j \geq 0, j=1,2,\dots,12 \\
& x_{6}\leq 100, x_7\leq 200 \\
& b_1, b_2 \in \{0,1\} \\
& i_1 \in \{0,1,2,3\} \\
\end{aligned}
\end{equation*}
from octeract import *
# Instantiate model
model = Model()
# Add variables to the model
model.add_variable("x1")
model.add_variable("x2")
model.add_variable("x3")
model.add_variable("x4")
model.add_variable("x5")
model.add_variable("x6")
model.add_variable("x7")
model.add_variable("x8")
model.add_variable("x9")
model.add_variable("x10")
model.add_variable("x11")
model.add_variable("x12")
model.add_variable("b1", 0, 1, BIN)
model.add_variable("b2", 0, 1, BIN)
model.add_variable("i1", 0, 3, INT)
# Set the objective
model.set_objective("x1-x2-i1")
# Add constraints
model.add_constraint("x1 - 6*x3 - 16*x4 - 10*x5 = 0")
model.add_constraint("x2 - 9*x6 - 15*x7 = 0")
model.add_constraint("x6 - x8 - x10 = 0")
model.add_constraint("x7 - x9 - x11 = 0")
model.add_constraint("x3 + x4 - x10 - x11 = 0")
model.add_constraint("x5 - x8 - x9 = 0")
model.add_constraint("x12*(x10 + x11) - 3*x3 - x4 + b2 = 0")
model.add_constraint("x12*x10 - 2.5*x10*i1 - 0.5*x8*b1 <= 0")
model.add_constraint("x12*x11 - 1.5*x11 + 0.5*x9 <= 0")
model.add_constraint("b1 + b2 <= 1")
# Set the variable bounds
model.set_variable_lb("x1", 0)
model.set_variable_lb("x2", 0)
model.set_variable_lb("x3", 0)
model.set_variable_lb("x4", 0)
model.set_variable_lb("x5", 0)
model.set_variable_bounds("x6", 0, 100)
model.set_variable_bounds("x7", 0, 200)
model.set_variable_lb("x8", 0)
model.set_variable_lb("x9", 0)
model.set_variable_lb("x10", 0)
model.set_variable_lb("x11", 0)
model.set_variable_lb("x12", 0)
# Solve model to global optimality using 4 cores
model.global_solve(4)
The solver will produce it’s 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 −408.
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 Python is a very flexible language, users will easily be able to integrate their code as part of a larger overall project.
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 Python is a very 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
| Description: | Instantiates an empty model. |
| Arguments: | None |
| Return Type: | None |
| Example Usage: |
|
3.1.2 model.add_constraint()
| Description: | Adds a constraint to the model. |
| Arguments: | constraint string: the function string of the constraint to be added |
| Return Type: | None |
| Example Usage: |
|
3.1.3 model.add_variable()
| 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 or INT) |
| Return Type: | None |
| Example Usage: |
|
3.1.4 model.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: |
|
3.1.5 model.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: |
|
3.1.6 model.detect_bounds()
| Description: | Tries to detect valid variable bounds based on the constraints present in the model. |
| Arguments: | None |
| Return Type: | None |
| Example Usage: |
|
3.1.7 model.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: |
|
3.1.8 model.get_binary_constraint_names()
| Description: | Returns a list of constraint names which only contain binary variables. |
| Arguments: | None |
| Return Type: | A list of constraint names |
| Example Usage: |
|
3.1.9 model.get_binary_variable_names()
| Description: | Returns the binary variables of the model. |
| Arguments: | None |
| Return Type: | A list of variable names |
| Example Usage: |
|
3.1.10 model.get_bound_multipliers()
| Description: | Returns a map of the decision variable names to their bound multipliers at the optimal solution. |
| Arguments: | None |
| Return Type: | Dictionary from String to Double |
| Example Usage: |
|
3.1.11 model.get_constraint_lb()
| Description: | Returns the lower bound of a constraint. |
| Arguments: | constraint name: the name of the constraint |
| Return Type: | Double |
| Example Usage: |
|
3.1.12 model.get_constraint_lhs()
| Description: | Returns the function string (left hand side) of a constraint. |
| Arguments: | constraint name: the name of the constraint |
| Return Type: | String |
| Example Usage: |
|
3.1.13 model.get_constraint_names()
| Description: | Returns all the constraints of the model. |
| Arguments: | None |
| Return Type: | A list of constraint names |
| Example Usage: |
|
3.1.14 model.get_constraint_ub()
| Description: | Returns the upper bound of a constraint. |
| Arguments: | constraint name: the name of the constraint |
| Return Type: | Double |
| Example Usage: |
|
3.1.15 model.get_constraint_variables()
| Description: | Returns all the variables of a constraint. |
| Arguments: | constraint name: the name of the constraint |
| Return Type: | A list of variable names |
| Example Usage: |
|
3.1.16 model.get_continuous_variable_names()
| Description: | Returns the continuous variables of the model. |
| Arguments: | None |
| Return Type: | A list of variable names |
| Example Usage: |
|
3.1.17 model.get_linear_constraint_names()
| Description: | Returns the linear constraints of the model. |
| Arguments: | None |
| Return Type: | A list of constraint names |
| Example Usage: |
|
3.1.18 model.get_linear_equality_constraint_names()
| Description: | Returns the linear equality constraints of the model. |
| Arguments: | None |
| Return Type: | A list of constraint names |
| Example Usage: |
|
3.1.19 model.get_linear_variable_names()
| Description: | Returns the linear variables of the model. |
| Arguments: | None |
| Return Type: | A list of variable names |
| Example Usage: |
|
3.1.20 model.get_nonlinear_constraint_names()
| Description: | Returns the nonlinear constraints of the model. |
| Arguments: | None |
| Return Type: | A list of constraint names |
| Example Usage: |
|
3.1.21 model.get_nonlinear_equality_constraint_names()
| Description: | Returns the nonlinear equality constraints of the model. |
| Arguments: | None |
| Return Type: | A list of constraint names |
| Example Usage: |
|
3.1.22 model.get_nonlinear_variable_names()
| Description: | Returns the nonlinear variables of the model. |
| Arguments: | None |
| Return Type: | A list of variable names |
| Example Usage: |
|
3.1.23 model.get_objective_function_string()
| Description: | Returns the function string of objective. |
| Arguments: | None |
| Return Type: | String |
| Example Usage: |
|
3.1.24 model.get_problem_type()
| Description: | Returns the problem structure (MINLP, NLP, MIQCQP, QCQP, MIQP, QP, MILP, LP). |
| Arguments: | None |
| Return Type: | String |
| Example Usage: |
|
3.1.25 model.get_solution_objective_value()
| Description: | Returns the value of the Objective at the optimal solution. |
| Arguments: | None |
| Return Type: | Double |
| Example Usage: |
|
3.1.26 model.get_solution_path()
| Description: | Returns the path where the solution file will be written to. |
| Arguments: | None |
| Return Type: | String |
| Example Usage: |
|
3.1.27 model.get_solution_vector()
| Description: | Returns a map of the decision variable names to their optimal solution values. |
| Arguments: | None |
| Return Type: | Dictionary from String to Double |
| Example Usage: |
|
3.1.28 model.get_variable_lb()
| Description: | Returns the lower bound of a variable. |
| Arguments: | variable name: the name of the variable |
| Return Type: | Double |
| Example Usage: |
|
3.1.29 model.get_variable_names()
| Description: | Returns all the variables of the model. |
| Arguments: | None |
| Return Type: | A list of variable names |
| Example Usage: |
|
3.1.30 model.get_variable_ub()
| Description: | Returns the upper bound of a variable. |
| Arguments: | variable name: the name of the variable |
| Return Type: | Double |
| Example Usage: |
|
3.1.31 model.global_solve()
| Description: | Solves the model to global optimality. |
| Arguments: | None or the number of cores to solve a problem |
| Return Type: | None |
| Example Usage: |
|
3.1.32 model.import_model_file()
| Description: | Imports a model file, which can be either in ASL format (.nl extension), LP (.lp extension) or MPS (.mps extension). |
| Arguments: | problem file_path: the path to the problem file |
| Return Type: | None |
| Example Usage: |
|
3.1.33 model.import_solution_file()
| 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: |
|
3.1.34 model.is_problem_convex()
| Description: | Returns whether the current model has been detected to be convex. |
| Arguments: | None |
| Return Type: | Boolean |
| Example Usage: |
|
3.1.35 model.local_solve()
| Description: | Solves the model to local optimality. |
| Arguments: | None |
| Return Type: | None |
| Example Usage: |
|
3.1.36 model.num_binary_constraints()
| Description: | Returns the number of constraints which only contain binary variables. |
| Arguments: | None |
| Return Type: | Integer |
| Example Usage: |
|
3.1.37 model.num_binary_variables()
| Description: | Returns the number of binary variables present in the model. |
| Arguments: | None |
| Return Type: | Integer |
| Example Usage: |
|
3.1.38 model.num_constraints()
| Description: | Returns the total number of constraints present in the model. |
| Arguments: | None |
| Return Type: | Integer |
| Example Usage: |
|
3.1.39 model.num_continuous_variables()
| Description: | Returns the number of continuous variables present in the model. |
| Arguments: | None |
| Return Type: | Integer |
| Example Usage: |
|
3.1.40 model.num_linear_constraints()
| Description: | Returns the number of linear constraints present in the model. |
| Arguments: | None |
| Return Type: | Integer |
| Example Usage: |
|
3.1.41 model.num_nonlinear_constraints()
| Description: | Returns the number of nonlinear constraints present in the model. |
| Arguments: | None |
| Return Type: | Integer |
| Example Usage: |
|
3.1.42 model.num_nonlinear_equality_constraints()
| Description: | Returns the number of nonlinear equality constraints present in the model. |
| Arguments: | None |
| Return Type: | Integer |
| Example Usage: |
|
3.1.43 model.num_nonlinear_variables()
| Description: | Returns the number of nonlinear variables present in the model. |
| Arguments: | None |
| Return Type: | Integer |
| Example Usage: |
|
3.1.44 model.num_variables()
| Description: | Returns the total number of variables present in the model. |
| Arguments: | None |
| Return Type: | Integer |
| Example Usage: |
|
3.1.45 model.print_problem_summary()
| Description: | Prints a summary of the loaded or constructed optimization problem onto the console. |
| Arguments: | None |
| Return Type: | None |
| Example Usage: |
|
3.1.46 model.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: |
|
3.1.47 model.read_options_file()
| 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: |
|
3.1.48 model.remove_all_constraints()
| Description: | Removes all constraints from the model. |
| Arguments: | None |
| Return Type: | None |
| Example Usage: |
|
3.1.49 model.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: |
|
3.1.50 model.remove_constraint()
| Description: | Removes a constraint of the model. |
| Arguments: | constraint name: the name of the constraint to be removed |
| Return Type: | None |
| Example Usage: |
|
3.1.51 model.remove_objective()
| Description: | Removes the objective of the model |
| Arguments: | None |
| Return Type: | None |
| Example Usage: |
|
3.1.52 model.remove_variable()
| Description: | Removes a variable of the model. |
| Arguments: | variable_name: the name of the variable to be removed |
| Return Type: | None |
| Example Usage: |
|
3.1.53 model.set_objective()
| 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: |
|
3.1.54 model.set_variable_bounds()
| 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: |
|
3.1.55 model.set_variable_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: |
|
3.1.56 model.set_variable_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: |
|
3.1.57 model.set_variable_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: |
|
3.1.58 model.write_current_solution_to_file()
| 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: |
|
3.1.59 model.write_problem_to_mod_file()
| 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: |
|
3.1.60 model.write_problem_to_NL_file()
| 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: |
|
3.1.61 model.write_problem_to_ALE_file()
| Description: | Writes the current model to an ASL (extension .ale) file. |
| Arguments: | file_path: the path of the .ale file |
| Return Type: | None |
| Example Usage: |
|
3.1.62 model.write_problem_to_MPS_file()
| Description: | Writes the current model to an ASL (extension .mps) file. |
| Arguments: | file_path: the path of the .mps file |
| Return Type: | None |
| Example Usage: |
|
3.1.63 model.write_problem_to_LP_file()
| Description: | Writes the current model to an ASL (extension .lp) file. |
| Arguments: | file_path: the path of the .lp file |
| Return Type: | None |
| Example Usage: |
|
3.1.64 model.maximize()
| Description: | Sets the objective to maximise a given objective function. |
| Arguments: | objective_string: the string of the objective function to be maximised. |
| Return Type: | None |
| Example Usage: |
|
3.1.65 model.minimize()
| Description: | Sets the objective to minimise a given objective function. |
| Arguments: | objective_string: the string of the objective function to be minimised. |
| Return Type: | None |
| Example Usage: |
|
3.1.66 model.set()
| Description: | Adds constraints to the model by setting expression_1: equal (to), greater than (to_at_least) or less than (to_at_most) expression_2 (where expression_2 can be a double); or add bounds to the variable variable_name between double_1 and double_2. |
| Arguments: | expression_1: string with expression, expression_2: string with expression or double, variable_name: string with name of variable, double_1 and double_2: doubles with double_1 \(\leq\) double_2. |
| Return Type: | None |
| Example Usage: |
|
3.1.67 model.set_option()
| Description: | Set the desired option to a custom value |
| Arguments: | option_name: string with the name of the option to set, option_value: string with the value to be assigned to the option option_name. |
| Return Type: | None |
| Example Usage: |
|
3.1.68 print()
| Description: | Prints model to screen |
| Arguments: | The model to print. |
| Return Type: | None |
| Example Usage: |
|
