cuOpt Convex Optimization C API Reference#

This section contains the cuOpt convex optimization C API reference. For MIP-specific functions and callbacks, see cuOpt MIP C API Reference.

Integer and Floating-Point Types#

cuOpt may be built with 32 or 64 bit integer and floating-point types. The C API uses a typedef for floating point and integer types to abstract the size of these types.

typedef int32_t cuopt_int_t#: The type of the integer number used by the solver. Use cuOptGetIntSize to get the size of the integer type.

typedef float cuopt_float_t#: The type of the floating point number used by the solver. Use cuOptGetFloatSize to get the number of bytes in the floating point type.

You may use the following functions to determine the number of bytes used to represent these types in your build

int8_t cuOptGetIntSize()#

Get the size of the integer type used by the library.

Returns:: The size of the integer type in bytes.

int8_t cuOptGetFloatSize()#

Get the size of the float type.

Returns:: The size in bytes of the float type.

Version Information#

You may use the following function to get the version of the cuOpt library

cuopt_int_t cuOptGetVersion( cuopt_int_t *version_major, cuopt_int_t *version_minor, cuopt_int_t *version_patch )#

Get the version of the library.

Parameters:

version_major – [out] - A pointer to a cuopt_int_t that will contain the major version number.
version_minor – [out] - A pointer to a cuopt_int_t that will contain the minor version number.
version_patch – [out] - A pointer to a cuopt_int_t that will contain the patch version number.

Returns:

A status code indicating success or failure.

Status Codes#

Every function in the C API returns a status code that indicates success or failure. The following status codes are defined

CUOPT_SUCCESS#

CUOPT_INVALID_ARGUMENT#

CUOPT_MPS_FILE_ERROR#

CUOPT_MPS_PARSE_ERROR#

CUOPT_VALIDATION_ERROR#

CUOPT_OUT_OF_MEMORY#

CUOPT_RUNTIME_ERROR#

Optimization Problem#

An optimization problem is represented via a cuOptOptimizationProblem

typedef void *cuOptOptimizationProblem#: A cuOptOptimizationProblem object contains a representation of an LP, MIP, QP, or QCQP. It is created by cuOptCreateProblem, cuOptCreateRangedProblem, or the quadratic create functions. Quadratic objectives and quadratic objectives and constraints may be set via cuOptSetQuadraticObjective and added via cuOptAddQuadraticConstraint. It is passed to cuOptSolve and destroyed with cuOptDestroyProblem.

Optimization problems can be created, loaded, or written via the following functions:

cuopt_int_t cuOptReadProblem( const char *filename, cuOptOptimizationProblem *problem_ptr )#

Read an optimization problem from an MPS, QPS, or LP file.

The file format is dispatched on the filename extension (case-insensitive):

”.lp”, “.lp.gz”, “.lp.bz2” → LP parser
”.mps”, “.mps.gz”, “.mps.bz2”, “.qps”, “.qps.gz”, “.qps.bz2” → MPS parser
anything else (including no extension) is rejected.

Parameters:

filename – [in] - The path to the MPS, QPS, or LP file. Must be a non-null, non-empty C string.
problem_ptr – [out] - A non-null pointer to a cuOptOptimizationProblem. On output the problem will be created and initialized with the data from the input file.

Returns:

A status code indicating success or failure. Returns CUOPT_INVALID_ARGUMENT if filename is null or empty, or if problem_ptr is null.

cuopt_int_t cuOptWriteProblem( cuOptOptimizationProblem problem, const char *filename, cuopt_int_t format )#

Write an optimization problem to a file.

Parameters:

problem – [in] - The optimization problem to write.
filename – [in] - The path to the output file.
format – [in] - The file format to use. Currently only CUOPT_FILE_FORMAT_MPS is supported.

Returns:

A status code indicating success or failure. Returns CUOPT_INVALID_ARGUMENT if an unsupported format is specified.

cuopt_int_t cuOptCreateProblem( cuopt_int_t num_constraints, cuopt_int_t num_variables, cuopt_int_t objective_sense, cuopt_float_t objective_offset, const cuopt_float_t *objective_coefficients, const cuopt_int_t *constraint_matrix_row_offsets, const cuopt_int_t *constraint_matrix_column_indices, const cuopt_float_t *constraint_matrix_coefficent_values, const char *constraint_sense, const cuopt_float_t *rhs, const cuopt_float_t *lower_bounds, const cuopt_float_t *upper_bounds, const char *variable_types, cuOptOptimizationProblem *problem_ptr )#

Create an optimization problem of the form.

*                minimize/maximize  c^T x + offset
*                  subject to       A x {=, <=, >=} b
*                                   l <= x <= u
*                                   x_i integer for some i
*

Parameters:

num_constraints – [in] The number of constraints
num_variables – [in] The number of variables
objective_sense – [in] The objective sense (CUOPT_MINIMIZE for minimization or CUOPT_MAXIMIZE for maximization)
objective_offset – [in] An offset to add to the linear objective
objective_coefficients – [in] A pointer to an array of type cuopt_float_t of size num_variables containing the coefficients of the linear objective
constraint_matrix_row_offsets – [in] A pointer to an array of type cuopt_int_t of size num_constraints + 1. constraint_matrix_row_offsets[i] is the index of the first non-zero element of the i-th constraint in constraint_matrix_column_indices and constraint_matrix_coefficent_values. This is part of the compressed sparse row representation of the constraint matrix
constraint_matrix_column_indices – [in] A pointer to an array of type cuopt_int_t of size constraint_matrix_row_offsets[num_constraints] containing the column indices of the non-zero elements of the constraint matrix. This is part of the compressed sparse row representation of the constraint matrix
constraint_matrix_coefficent_values – [in] A pointer to an array of type cuopt_float_t of size constraint_matrix_row_offsets[num_constraints] containing the values of the non-zero elements of the constraint matrix. This is part of the compressed sparse row representation of the constraint matrix
constraint_sense – [in] A pointer to an array of type char of size num_constraints containing the sense of the constraints (CUOPT_LESS_THAN, CUOPT_GREATER_THAN, or CUOPT_EQUAL)
rhs – [in] A pointer to an array of type cuopt_float_t of size num_constraints containing the right-hand side of the constraints
lower_bounds – [in] A pointer to an array of type cuopt_float_t of size num_variables containing the lower bounds of the variables
upper_bounds – [in] A pointer to an array of type cuopt_float_t of size num_variables containing the upper bounds of the variables
variable_types – [in] A pointer to an array of type char of size num_variables containing the types of the variables (CUOPT_CONTINUOUS, CUOPT_INTEGER, or CUOPT_SEMI_CONTINUOUS)
problem_ptr – [out] Pointer to store the created optimization problem

Returns:

CUOPT_SUCCESS if successful, CUOPT_ERROR otherwise

cuopt_int_t cuOptCreateRangedProblem( cuopt_int_t num_constraints, cuopt_int_t num_variables, cuopt_int_t objective_sense, cuopt_float_t objective_offset, const cuopt_float_t *objective_coefficients, const cuopt_int_t *constraint_matrix_row_offsets, const cuopt_int_t *constraint_matrix_column_indices, const cuopt_float_t *constraint_matrix_coefficients, const cuopt_float_t *constraint_lower_bounds, const cuopt_float_t *constraint_upper_bounds, const cuopt_float_t *variable_lower_bounds, const cuopt_float_t *variable_upper_bounds, const char *variable_types, cuOptOptimizationProblem *problem_ptr )#

Create an optimization problem of the form *.

*                minimize/maximize  c^T x + offset
*                  subject to       bl <= A*x <= bu
*                                   l <= x <= u
*                                   x_i integer for some i
*

Parameters:

num_constraints – [in] - The number of constraints.
num_variables – [in] - The number of variables.
objective_sense – [in] - The objective sense (CUOPT_MINIMIZE for minimization or CUOPT_MAXIMIZE for maximization)
objective_offset – [in] - An offset to add to the linear objective.
objective_coefficients – [in] - A pointer to an array of type cuopt_float_t of size num_variables containing the coefficients of the linear objective.
constraint_matrix_row_offsets – [in] - A pointer to an array of type cuopt_int_t of size num_constraints + 1. constraint_matrix_row_offsets[i] is the index of the first non-zero element of the i-th constraint in constraint_matrix_column_indices and constraint_matrix_coefficients.
constraint_matrix_column_indices – [in] - A pointer to an array of type cuopt_int_t of size constraint_matrix_row_offsets[num_constraints] containing the column indices of the non-zero elements of the constraint matrix.
constraint_matrix_coefficients – [in] - A pointer to an array of type cuopt_float_t of size constraint_matrix_row_offsets[num_constraints] containing the values of the non-zero elements of the constraint matrix.
constraint_lower_bounds – [in] - A pointer to an array of type cuopt_float_t of size num_constraints containing the lower bounds of the constraints.
constraint_upper_bounds – [in] - A pointer to an array of type cuopt_float_t of size num_constraints containing the upper bounds of the constraints.
variable_lower_bounds – [in] - A pointer to an array of type cuopt_float_t of size num_variables containing the lower bounds of the variables.
variable_upper_bounds – [in] - A pointer to an array of type cuopt_float_t of size num_variables containing the upper bounds of the variables.
variable_types – [in] - A pointer to an array of type char of size num_variables containing the types of the variables (CUOPT_CONTINUOUS, CUOPT_INTEGER, or CUOPT_SEMI_CONTINUOUS).
problem_ptr – [out] - A pointer to a cuOptOptimizationProblem. On output the problem will be created and initialized with the provided data.

Returns:

A status code indicating success or failure.

Note

cuOptCreateQuadraticProblem and cuOptCreateQuadraticRangedProblem are deprecated. Prefer cuOptCreateProblem or cuOptCreateRangedProblem followed by cuOptSetQuadraticObjective.

For problems with quadratic objectives, first create a problem, and then use

cuopt_int_t cuOptSetQuadraticObjective( cuOptOptimizationProblem problem, cuopt_int_t num_entries, const cuopt_int_t *row_index, const cuopt_int_t *col_index, const cuopt_float_t *coeff )#

Set the quadratic objective term x^T Q x on an existing problem.

The matrix Q is specified in coordinate (triplet) format. This function may be called after cuOptCreateProblem or cuOptCreateRangedProblem to build a QP or QCQP model without using cuOptCreateQuadraticProblem or cuOptCreateQuadraticRangedProblem. Each call replaces any previously set quadratic objective. Duplicate (row, col) indices in the triplet arrays are summed.

Parameters:

problem – [in] The optimization problem created by cuOptCreateProblem or cuOptCreateRangedProblem.
num_entries – [in] Number of non-zero entries in Q.
row_index – [in] Array of length num_entries with row indices (0-based).
col_index – [in] Array of length num_entries with column indices (0-based).
coeff – [in] Array of length num_entries with matrix coefficients.

Returns:

A status code indicating success or failure.

For problems with quadratic constraints, first create a problem, and then use

cuopt_int_t cuOptAddQuadraticConstraint( cuOptOptimizationProblem problem, cuopt_int_t quad_num_entries, const cuopt_int_t *row_index, const cuopt_int_t *col_index, const cuopt_float_t *coeff, cuopt_int_t num_lin_entries, const cuopt_int_t *linear_index, const cuopt_float_t *linear_coeff, char sense, cuopt_float_t rhs )#

Add a quadratic constraint x^T Q x + d^T x {<=, >=} rhs to an existing problem.

The quadratic matrix Q is specified in coordinate (triplet) format. The linear term d is specified by parallel arrays of variable indices and coefficients. This function may be called after cuOptCreateProblem or cuOptCreateRangedProblem to build a QCQP model. Each call appends one quadratic constraint.

Parameters:

problem – [in] The optimization problem created by cuOptCreateProblem or cuOptCreateRangedProblem.
quad_num_entries – [in] Number of non-zero entries in the quadratic part.
row_index – [in] Array of length quad_num_entries with row indices (0-based).
col_index – [in] Array of length quad_num_entries with column indices (0-based).
coeff – [in] Array of length quad_num_entries with quadratic matrix coefficients.
num_lin_entries – [in] Number of non-zero entries in the linear part.
linear_index – [in] Array of length num_lin_entries with variable indices (0-based).
linear_coeff – [in] Array of length num_lin_entries with linear coefficients.
sense – [in] Constraint sense: CUOPT_LESS_THAN (‘L’) for <= or CUOPT_GREATER_THAN (‘G’) for >=.
rhs – [in] Right-hand side of the constraint.

Returns:

A status code indicating success or failure.

Note

Support for quadratic constraints is currently in beta. cuOptAddQuadraticConstraint supports three types of quadratic constraints: - Convex quadratic constraints of the form x^T Q x + d^T x <= alpha where H=(Q+Q^T)/2 is a symmetric positive semidefinite matrix. Q need not be symmetric. - Second-order cone constraints of the form sum_{i=1}^n x_i^2 <= x_0, x_0 >= 0 - Rotated second-order cone constraints of the form sum_{i=2}^n x_i^2 - 0. 5 * x_0 * x_1 - 0. 5 * x_1 * x_0 <= 0, x_0 >= 0, x_1 >= 0

For the rotated second-order cone constraints, cuOpt expects the quadratic matrix to be symmetric. Only CUOPT_LESS_THAN and CUOPT_GREATER_THAN sense is supported; equality constraints are not supported.

A optimization problem must be destroyed with the following function

void cuOptDestroyProblem(cuOptOptimizationProblem *problem_ptr)#

Destroy an optimization problem.

Parameters:

problem_ptr – [inout] - A pointer to a cuOptOptimizationProblem. On output the problem will be destroyed, and the pointer will be set to NULL.

Certain constants are needed to define an optimization problem. These constants are described below.

Objective Sense Constants#

These constants are used to define the objective sense in the cuOptCreateProblem() and cuOptCreateRangedProblem() functions.

CUOPT_MINIMIZE#

CUOPT_MAXIMIZE#

Constraint Sense Constants#

These constants are used to define the constraint sense in the cuOptCreateProblem() and cuOptCreateRangedProblem() functions.

CUOPT_LESS_THAN#

CUOPT_GREATER_THAN#

CUOPT_EQUAL#

Variable Type Constants#

These constants are used to define the the variable type in the cuOptCreateProblem() and cuOptCreateRangedProblem() functions.

CUOPT_CONTINUOUS#

CUOPT_INTEGER#

CUOPT_SEMI_CONTINUOUS#

Infinity Constant#

This constant may be used to represent infinity in the cuOptCreateProblem() and cuOptCreateRangedProblem() functions.

CUOPT_INFINITY#

File Format Constants#

These constants are used to specify the output file format in cuOptWriteProblem().

CUOPT_FILE_FORMAT_MPS#

Querying an Optimization Problem#

The following functions may be used to get information about an cuOptimizationProblem

cuopt_int_t cuOptGetNumConstraints( cuOptOptimizationProblem problem, cuopt_int_t *num_constraints_ptr )#

Get the number of constraints of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
num_constraints_ptr – [out] - A pointer to a cuopt_int_t that will contain the number of constraints on output.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetNumVariables( cuOptOptimizationProblem problem, cuopt_int_t *num_variables_ptr )#

Get the number of variables of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
num_variables_ptr – [out] - A pointer to a cuopt_int_t that will contain the number of variables on output.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetObjectiveSense( cuOptOptimizationProblem problem, cuopt_int_t *objective_sense_ptr )#

Get the objective sense of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
objective_sense_ptr – [out] - A pointer to a cuopt_int_t that on output will contain the objective sense.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetObjectiveOffset( cuOptOptimizationProblem problem, cuopt_float_t *objective_offset_ptr )#

Get the objective offset of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
objective_offset_ptr – [out] - A pointer to a cuopt_float_t that on output will contain the objective offset.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetObjectiveCoefficients( cuOptOptimizationProblem problem, cuopt_float_t *objective_coefficients_ptr )#

Get the objective coefficients of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
objective_coefficients_ptr – [out] - A pointer to an array of type cuopt_float_t of size num_variables that on output will contain the objective coefficients.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetNumNonZeros( cuOptOptimizationProblem problem, cuopt_int_t *num_non_zeros_ptr )#

Get the number of non-zero elements in the constraint matrix of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
num_non_zeros_ptr – [out] - A pointer to a cuopt_int_t that on output will contain the number of non-zeros in the constraint matrix.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetConstraintMatrix( cuOptOptimizationProblem problem, cuopt_int_t *constraint_matrix_row_offsets_ptr, cuopt_int_t *constraint_matrix_column_indices_ptr, cuopt_float_t *constraint_matrix_coefficients_ptr )#

Get the constraint matrix of an optimization problem in compressed sparse row format.

Parameters:

problem – [in] - The optimization problem.
constraint_matrix_row_offsets_ptr – [out] - A pointer to an array of type cuopt_int_t of size num_constraints + 1 that on output will contain the row offsets of the constraint matrix.
constraint_matrix_column_indices_ptr – [out] - A pointer to an array of type cuopt_int_t of size equal to the number of nonzeros that on output will contain the column indices of the non-zero entries of the constraint matrix.
constraint_matrix_coefficients_ptr – [out] - A pointer to an array of type cuopt_float_t of size equal to the number of nonzeros that on output will contain the coefficients of the non-zero entries of the constraint matrix.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetConstraintSense( cuOptOptimizationProblem problem, char *constraint_sense_ptr )#

Get the constraint sense of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
constraint_sense_ptr – [out] - A pointer to an array of type char of size num_constraints that on output will contain the sense of the constraints.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetConstraintRightHandSide( cuOptOptimizationProblem problem, cuopt_float_t *rhs_ptr )#

Get the right-hand side of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
rhs_ptr – [out] - A pointer to an array of type cuopt_float_t of size num_constraints that on output will contain the right-hand side of the constraints.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetConstraintLowerBounds( cuOptOptimizationProblem problem, cuopt_float_t *lower_bounds_ptr )#

Get the lower bounds of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
lower_bounds_ptr – [out] - A pointer to an array of type cuopt_float_t of size num_constraints that on output will contain the lower bounds of the constraints.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetConstraintUpperBounds( cuOptOptimizationProblem problem, cuopt_float_t *upper_bounds_ptr )#

Get the upper bounds of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
upper_bounds_ptr – [out] - A pointer to an array of type cuopt_float_t of size num_constraints that on output will contain the upper bounds of the constraints.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetVariableLowerBounds( cuOptOptimizationProblem problem, cuopt_float_t *lower_bounds_ptr )#

Get the lower bounds of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
lower_bounds_ptr – [out] - A pointer to an array of type cuopt_float_t of size num_variables that on output will contain the lower bounds of the variables.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetVariableUpperBounds( cuOptOptimizationProblem problem, cuopt_float_t *upper_bounds_ptr )#

Get the upper bounds of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
upper_bounds_ptr – [out] - A pointer to an array of type cuopt_float_t of size num_variables that on output will contain the upper bounds of the variables.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetVariableTypes( cuOptOptimizationProblem problem, char *variable_types_ptr )#

Get the variable types of an optimization problem.

Parameters:

problem – [in] - The optimization problem.
variable_types_ptr – [out] - A pointer to an array of type char of size num_variables that on output will contain the types of the variables (CUOPT_CONTINUOUS, CUOPT_INTEGER, or CUOPT_SEMI_CONTINUOUS).

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptIsMIP( cuOptOptimizationProblem problem, cuopt_int_t *is_mip_ptr )#

Check if an optimization problem is a mixed integer programming problem.

Parameters:

problem – [in] - The optimization problem.
is_mip_ptr – [out] - A pointer to a cuopt_int_t that on output will be 0 if the problem contains only continuous variables, or 1 if the problem contains integer variables.

Returns:

A status code indicating success or failure.

Solver Settings#

Settings are used to configure the LP/MIP solvers. All settings are stored in a cuOptSolverSettings object.

typedef void *cuOptSolverSettings#: A cuOptSolverSettings object contains parameter settings and other information for an LP or MIP solve. It is created by cuOptCreateSolverSettings. It is passed to cuOptSolve. It should be destroyed using cuOptDestroySolverSettings.

A cuOptSolverSettings object is created with cuOptCreateSolverSettings

cuopt_int_t cuOptCreateSolverSettings( cuOptSolverSettings *settings_ptr )#

Create a solver settings object.

Parameters:

settings_ptr – [out] - A pointer to a cuOptSolverSettings object. On output the solver settings will be created and initialized.

Returns:

A status code indicating success or failure.

When you are done with a solve you should destroy a cuOptSolverSettings object with

void cuOptDestroySolverSettings(cuOptSolverSettings *settings_ptr)#

Destroy a solver settings object.

Parameters:

settings_ptr – [inout] - A pointer to a cuOptSolverSettings object. On output the solver settings will be destroyed and the pointer will be set to NULL.

Setting Parameters#

The following functions are used to set and get parameters. You can find more details on the available parameters in the Convex Optimization Settings section.

cuopt_int_t cuOptSetParameter( cuOptSolverSettings settings, const char *parameter_name, const char *parameter_value )#

Set a parameter of a solver settings object.

Parameters:

settings – [in] - The solver settings object.
parameter_name – [in] - The name of the parameter to set.
parameter_value – [in] - The value of the parameter to set.

cuopt_int_t cuOptGetParameter( cuOptSolverSettings settings, const char *parameter_name, cuopt_int_t parameter_value_size, char *parameter_value )#

Get a parameter of a solver settings object.

Parameters:

settings – [in] - The solver settings object.
parameter_name – [in] - The name of the parameter to get.
parameter_value_size – [in] - The size of the parameter value buffer.
parameter_value – [out] - A pointer to an array of characters that on output will contain the value of the parameter.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptSetIntegerParameter( cuOptSolverSettings settings, const char *parameter_name, cuopt_int_t parameter_value )#

Set an integer parameter of a solver settings object.

Parameters:

settings – [in] - The solver settings object.
parameter_name – [in] - The name of the parameter to set.
parameter_value – [in] - The value of the parameter to set.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetIntegerParameter( cuOptSolverSettings settings, const char *parameter_name, cuopt_int_t *parameter_value )#

Get an integer parameter of a solver settings object.

Parameters:

settings – [in] - The solver settings object.
parameter_name – [in] - The name of the parameter to get.
parameter_value – [out] - A pointer to a cuopt_int_t that on output will contain the value of the parameter.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptSetFloatParameter( cuOptSolverSettings settings, const char *parameter_name, cuopt_float_t parameter_value )#

Set a float parameter of a solver settings object.

Parameters:

settings – [in] - The solver settings object.
parameter_name – [in] - The name of the parameter to set.
parameter_value – [in] - The value of the parameter to set.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetFloatParameter( cuOptSolverSettings settings, const char *parameter_name, cuopt_float_t *parameter_value )#

Get a float parameter of a solver settings object.

Parameters:

settings – [in] - The solver settings object.
parameter_name – [in] - The name of the parameter to get.
parameter_value – [out] - A pointer to a cuopt_float_t that on output will contain the value of the parameter.

Returns:

A status code indicating success or failure.

Parameter Constants#

These constants are used as parameter names in the cuOptSetParameter(), cuOptGetParameter(), and similar functions. For more details on the available parameters, see the Convex Optimization Settings and MIP Settings sections.

CUOPT_ABSOLUTE_DUAL_TOLERANCE#

CUOPT_RELATIVE_DUAL_TOLERANCE#

CUOPT_ABSOLUTE_PRIMAL_TOLERANCE#

CUOPT_RELATIVE_PRIMAL_TOLERANCE#

CUOPT_ABSOLUTE_GAP_TOLERANCE#

CUOPT_RELATIVE_GAP_TOLERANCE#

CUOPT_INFEASIBILITY_DETECTION#

CUOPT_STRICT_INFEASIBILITY#

CUOPT_PRIMAL_INFEASIBLE_TOLERANCE#

CUOPT_DUAL_INFEASIBLE_TOLERANCE#

CUOPT_ITERATION_LIMIT#

CUOPT_TIME_LIMIT#

CUOPT_PDLP_SOLVER_MODE#

CUOPT_METHOD#

CUOPT_PER_CONSTRAINT_RESIDUAL#

CUOPT_SAVE_BEST_PRIMAL_SO_FAR#

CUOPT_FIRST_PRIMAL_FEASIBLE#

CUOPT_LOG_FILE#

CUOPT_PRESOLVE#

CUOPT_LOG_TO_CONSOLE#

CUOPT_CROSSOVER#

CUOPT_FOLDING#

CUOPT_AUGMENTED#

CUOPT_DUALIZE#

CUOPT_ORDERING#

CUOPT_ELIMINATE_DENSE_COLUMNS#

CUOPT_CUDSS_DETERMINISTIC#

CUOPT_BARRIER_DUAL_INITIAL_POINT#

CUOPT_BARRIER_ITERATIVE_REFINEMENT#

CUOPT_BARRIER_STEP_SCALE#

CUOPT_DUAL_POSTSOLVE#

CUOPT_SOLUTION_FILE#

CUOPT_NUM_CPU_THREADS#

CUOPT_NUM_GPUS#

CUOPT_USER_PROBLEM_FILE#

CUOPT_PDLP_PRECISION#

PDLP Solver Mode Constants#

These constants are used to configure CUOPT_PDLP_SOLVER_MODE via cuOptSetIntegerParameter().

CUOPT_PDLP_SOLVER_MODE_STABLE1#

CUOPT_PDLP_SOLVER_MODE_STABLE2#

CUOPT_PDLP_SOLVER_MODE_STABLE3#

CUOPT_PDLP_SOLVER_MODE_METHODICAL1#

CUOPT_PDLP_SOLVER_MODE_FAST1#

PDLP Precision Constants#

These constants are used to configure CUOPT_PDLP_PRECISION via cuOptSetIntegerParameter().

CUOPT_PDLP_DEFAULT_PRECISION#

CUOPT_PDLP_SINGLE_PRECISION#

CUOPT_PDLP_DOUBLE_PRECISION#

CUOPT_PDLP_MIXED_PRECISION#

Method Constants#

These constants are used to configure CUOPT_METHOD via cuOptSetIntegerParameter().

CUOPT_METHOD_CONCURRENT#

CUOPT_METHOD_PDLP#

CUOPT_METHOD_DUAL_SIMPLEX#

CUOPT_METHOD_BARRIER#

CUOPT_METHOD_UNSET#

Warm Start#

For LP problems solved with PDLP, primal and dual warm start vectors may be provided:

cuopt_int_t cuOptSetInitialPrimalSolution( cuOptSolverSettings settings, const cuopt_float_t *primal_solution, cuopt_int_t num_variables )#

Set the initial primal solution for an LP solve.

Note

This function is only supported for PDLP.

Note

All pointer arguments (primal_solution) refer to host memory.

Parameters:

settings – [in] - The solver settings object.
primal_solution – [in] - A pointer to an array of type cuopt_float_t of size num_variables containing the initial primal values.
num_variables – [in] - The number of variables (size of the primal_solution array).

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptSetInitialDualSolution( cuOptSolverSettings settings, const cuopt_float_t *dual_solution, cuopt_int_t num_constraints )#

Set the initial dual solution for an LP solve.

Note

This function is only supported for PDLP.

Note

All pointer arguments (dual_solution) refer to host memory.

Parameters:

settings – [in] - The solver settings object.
dual_solution – [in] - A pointer to an array of type cuopt_float_t of size num_constraints containing the initial dual values.
num_constraints – [in] - The number of constraints (size of the dual_solution array).

Returns:

A status code indicating success or failure.

Note

For MIP warm start (MIP starts), see cuOpt MIP C API Reference.

Solving an LP or MIP#

LP and MIP solves are performed by calling the cuOptSolve function

cuopt_int_t cuOptSolve( cuOptOptimizationProblem problem, cuOptSolverSettings settings, cuOptSolution *solution_ptr )#

Solve an optimization problem.

Parameters:

problem – [in] - The optimization problem.
settings – [in] - The solver settings.
solution_ptr – [out] - A pointer to a cuOptSolution object. On output the solution will be created.

Returns:

A status code indicating success or failure.

Solution#

The output of a solve is a cuOptSolution object.

typedef void *cuOptSolution#: A cuOptSolution object contains the solution to an LP or MIP. It is created by cuOptSolve. It should be destroyed using cuOptDestroySolution.

The following functions may be used to access information from a cuOptSolution

cuopt_int_t cuOptGetTerminationStatus( cuOptSolution solution, cuopt_int_t *termination_status_ptr )#

Get the termination reason of an optimization problem.

Parameters:

solution – [in] - The solution object.
termination_reason_ptr – [out] - A pointer to a cuopt_int_t that on output will contain the termination reason.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetErrorStatus( cuOptSolution solution, cuopt_int_t *error_status_ptr )#

cuopt_int_t cuOptGetErrorString( cuOptSolution solution, char *error_string_ptr, cuopt_int_t error_string_size )#

cuopt_int_t cuOptGetPrimalSolution( cuOptSolution solution, cuopt_float_t *solution_values )#

cuopt_int_t cuOptGetObjectiveValue( cuOptSolution solution, cuopt_float_t *objective_value_ptr )#

Get the objective value of an optimization problem.

Parameters:

solution – [in] - The solution object.
objective_value_ptr – [inout] - A pointer to a cuopt_float_t that will contain the objective value.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetSolveTime( cuOptSolution solution, cuopt_float_t *solve_time_ptr )#

Get the solve time of an optimization problem.

Parameters:

solution – [in] - The solution object.
solve_time_ptr – [inout] - A pointer to a cuopt_float_t that will contain the solve time.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetMIPGap( cuOptSolution solution, cuopt_float_t *mip_gap_ptr )#

Get the relative MIP gap of an optimization problem.

Parameters:

solution – [in] - The solution object.
mip_gap_ptr – [inout] - A pointer to a cuopt_float_t that will contain the relative MIP gap.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetSolutionBound( cuOptSolution solution, cuopt_float_t *solution_bound_ptr )#

Get the solution bound of an optimization problem.

Parameters:

solution – [in] - The solution object.
solution_bound_ptr – [inout] - A pointer to a cuopt_float_t that will contain the solution bound.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetDualSolution( cuOptSolution solution, cuopt_float_t *dual_solution_ptr )#

Get the dual solution of an optimization problem.

Parameters:

solution – [in] - The solution object.
dual_solution_ptr – [inout] - A pointer to an array of type cuopt_float_t of size num_constraints that will contain the dual solution.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetDualObjectiveValue( cuOptSolution solution, cuopt_float_t *dual_objective_value_ptr )#

Get the dual objective value of an optimization problem.

Parameters:

solution – [in] - The solution object.
dual_objective_value_ptr – [inout] - A pointer to a cuopt_float_t that will contain the dual objective value.

Returns:

A status code indicating success or failure.

cuopt_int_t cuOptGetReducedCosts( cuOptSolution solution, cuopt_float_t *reduced_cost_ptr )#

Get the reduced costs of an optimization problem.

Parameters:

solution – [in] - The solution object.
reduced_cost_ptr – [inout] - A pointer to an array of type cuopt_float_t of size num_variables that will contain the reduced cost.

Returns:

A status code indicating success or failure.

When you are finished with a cuOptSolution object you should destory it with

void cuOptDestroySolution(cuOptSolution *solution_ptr)#

Destroy a solution object.

Parameters:

solution_ptr – [inout] - A pointer to a cuOptSolution object. On output the solution will be destroyed and the pointer will be set to NULL.

Termination Status Constants#

These constants define the termination status received from the cuOptGetTerminationStatus() function.

CUOPT_TERMINATION_STATUS_NO_TERMINATION#

CUOPT_TERMINATION_STATUS_OPTIMAL#

CUOPT_TERMINATION_STATUS_INFEASIBLE#

CUOPT_TERMINATION_STATUS_UNBOUNDED#

CUOPT_TERMINATION_STATUS_ITERATION_LIMIT#

CUOPT_TERMINATION_STATUS_TIME_LIMIT#

CUOPT_TERMINATION_STATUS_NUMERICAL_ERROR#

CUOPT_TERMINATION_STATUS_PRIMAL_FEASIBLE#

CUOPT_TERMINATION_STATUS_FEASIBLE_FOUND#

CUOPT_TERMINATION_STATUS_CONCURRENT_LIMIT#

CUOPT_TERMINATION_STATUS_WORK_LIMIT#

CUOPT_TERMINATION_STATUS_UNBOUNDED_OR_INFEASIBLE#

cuOpt Convex Optimization C API Reference#

Integer and Floating-Point Types#

Version Information#

Status Codes#

Optimization Problem#

Objective Sense Constants#

Constraint Sense Constants#

Variable Type Constants#

Infinity Constant#

File Format Constants#

Querying an Optimization Problem#

Solver Settings#

Setting Parameters#

Parameter Constants#

PDLP Solver Mode Constants#

PDLP Precision Constants#

Method Constants#

Barrier Iterative Refinement Constants#

Warm Start#

Solving an LP or MIP#

Solution#

Termination Status Constants#