Interface to Clarabel solver implemented in Rust.

Description

Clarabel is a versatile interior point solver for convex programs using a new homogeneous embedding. It solves solves linear programs (LPs), quadratic programs (QPs), second-order cone programs (SOCPs), and problems with exponential and power cone constraints. For quadratic objectives, unlike interior point solvers based on the standard homogeneous self-dual embedding (HSDE) model, Clarabel handles quadratic objective without requiring any epigraphical reformulation of its objective function. It can therefore be significantly faster than other HSDE-based solvers for problems with quadratic objective functions. Infeasible problems are detected using a homogeneous embedding technique. See https://clarabel.org/stable/.

Author(s)

Balasubramanian Narasimhan, Paul Goulart, Yuwen Chen

See Also

Useful links:

• https://oxfordcontrol.github.io/clarabel-r/

• Report bugs at https://github.com/oxfordcontrol/clarabel-r/issues

Interface to 'Clarabel', an interior point conic solver

Description

Clarabel solves linear programs (LPs), quadratic programs (QPs), second-order cone programs (SOCPs) and semidefinite programs (SDPs). It also solves problems with exponential and power cone constraints. The specific problem solved is:

Minimize

\frac{1}{2}x^TPx + q^Tx

subject to

Ax + s = b

s \in K

where x \in R^n, s \in R^m, P = P^T and nonnegative-definite, q \in R^n, A \in R^{m\times n}, and b \in R^m. The set K is a composition of convex cones.

Usage

clarabel(A, b, q, P = NULL, cones, control = list(), strict_cone_order = TRUE)

Arguments

Details

The order of the rows in matrix A has to correspond to the order given in the table “Cone Parameters”, which means means rows corresponding to primal zero cones should be first, rows corresponding to non-negative cones second, rows corresponding to second-order cone third, rows corresponding to positive semidefinite cones fourth, rows corresponding to exponential cones fifth and rows corresponding to power cones at last.

When the parameter strict_cone_order is FALSE, one can specify the cones in any order and even repeat them in the order they appear in the A matrix. See below.

Clarabel can solve

1. linear programs (LPs)

2. second-order cone programs (SOCPs)

3. exponential cone programs (ECPs)

4. power cone programs (PCPs)

5. problems with any combination of cones, defined by the parameters listed in “Cone Parameters” below

Cone Parameters

The table below shows the cone parameter specifications. Mathematical definitions are in the vignette.

When the parameter strict_cone_order is FALSE, one can specify the cones in the order they appear in the A matrix. The cones argument in such a case should be a named list with names matching ⁠^z*⁠ indicating primal zero cones, ⁠^l*⁠ indicating linear cones, and so on. For example, either of the following would be valid: list(z = 2L, l = 2L, q = 2L, z = 3L, q = 3L), or, list(z1 = 2L, l1 = 2L, q1 = 2L, zb = 3L, qx = 3L), indicating a zero cone of size 2, followed by a linear cone of size 2, followed by a second-order cone of size 2, followed by a zero cone of size 3, and finally a second-order cone of size 3. Generalized power cones parameters have to specified as named lists, e.g., list(z = 2L, gp1 = list(a = c(0.3, 0.7), n = 3L), gp2 = list(a = c(0.5, 0.5), n = 1L)).

Note that when strict_cone_order = FALSE, types of cone parameters such as integers, reals have to be explicit since the parameters are directly passed to the Rust interface with no sanity checks.!

Value

named list of solution vectors x, y, s and information about run

See Also

clarabel_control()

Examples

A <- matrix(c(1, 1), ncol = 1)
b <- c(1, 1)
obj <- 1
cone <- list(z = 2L)
control <- clarabel_control(tol_gap_rel = 1e-7, tol_gap_abs = 1e-7, max_iter = 100)
clarabel(A = A, b = b, q = obj, cones = cone, control = control)

Control parameters with default values and types in parenthesis

Description

Control parameters with default values and types in parenthesis

Usage

clarabel_control(
  max_iter = 200L,
  time_limit = Inf,
  verbose = TRUE,
  max_step_fraction = 0.99,
  tol_gap_abs = 1e-08,
  tol_gap_rel = 1e-08,
  tol_feas = 1e-08,
  tol_infeas_abs = 1e-08,
  tol_infeas_rel = 1e-08,
  tol_ktratio = 1e-06,
  reduced_tol_gap_abs = 5e-05,
  reduced_tol_gap_rel = 5e-05,
  reduced_tol_feas = 1e-04,
  reduced_tol_infeas_abs = 5e-05,
  reduced_tol_infeas_rel = 5e-05,
  reduced_tol_ktratio = 1e-04,
  equilibrate_enable = TRUE,
  equilibrate_max_iter = 10L,
  equilibrate_min_scaling = 1e-04,
  equilibrate_max_scaling = 10000,
  linesearch_backtrack_step = 0.8,
  min_switch_step_length = 0.1,
  min_terminate_step_length = 1e-04,
  max_threads = 0L,
  direct_kkt_solver = TRUE,
  direct_solve_method = c("qdldl", "mkl", "cholmod"),
  static_regularization_enable = TRUE,
  static_regularization_constant = 1e-08,
  static_regularization_proportional = .Machine$double.eps * .Machine$double.eps,
  dynamic_regularization_enable = TRUE,
  dynamic_regularization_eps = 1e-13,
  dynamic_regularization_delta = 2e-07,
  iterative_refinement_enable = TRUE,
  iterative_refinement_reltol = 1e-13,
  iterative_refinement_abstol = 1e-12,
  iterative_refinement_max_iter = 10L,
  iterative_refinement_stop_ratio = 5,
  presolve_enable = TRUE,
  chordal_decomposition_enable = FALSE,
  chordal_decomposition_merge_method = c("none", "parent_child", "clique_graph"),
  chordal_decomposition_compact = FALSE,
  chordal_decomposition_complete_dual = FALSE
)

Arguments

Value

a list containing the control parameters.

Return the solver status description as a named character vector

Description

Return the solver status description as a named character vector

Usage

solver_status_descriptions()

Value

a named list of solver status descriptions, in order of status codes returned by the solver

Examples

solver_status_descriptions()[2] ## for solved problem
solver_status_descriptions()[8] ## for max iterations limit reached