R/015_settings.R

In CVXR: Disciplined Convex Optimization

#####
## DO NOT EDIT THIS FILE!! EDIT THE SOURCE INSTEAD: rsrc_tree/settings.R
#####

## CVXPY SOURCE: cvxpy/settings.py
## CVXPY 1.9 parity notes:
## CVXR exposes the solver/status/data constants used by the R solver
## interfaces. Solver-name coverage includes the 1.9 NLP additions
## UNO/IPOPT/KNITRO/COPT (settings.py:76,103-105); Python-only solver names
## without R interfaces remain intentionally absent.
## Global settings and constants for CVXR

# -- Solver names ------------------------------------------------------

#' Solver Name Constants
#'
#' Character string constants identifying the available solvers.
#'
#' @name solver-constants
#' @returns A character string.
NULL

#' @rdname solver-constants
#' @export
SCS_SOLVER <- "SCS"
#' @rdname solver-constants
#' @export
OSQP_SOLVER <- "OSQP"
#' @rdname solver-constants
#' @export
CLARABEL_SOLVER <- "CLARABEL"
#' @rdname solver-constants
#' @export
DIFFCP_SOLVER <- "DIFFCP"
#' @rdname solver-constants
#' @export
HIGHS_SOLVER <- "HIGHS"
#' @rdname solver-constants
#' @export
MOSEK_SOLVER <- "MOSEK"
#' @rdname solver-constants
#' @export
GUROBI_SOLVER <- "GUROBI"
#' @rdname solver-constants
#' @export
GLPK_SOLVER <- "GLPK"
#' @rdname solver-constants
#' @export
GLPK_MI_SOLVER <- "GLPK_MI"
#' @rdname solver-constants
#' @export
ECOS_SOLVER <- "ECOS"
#' @rdname solver-constants
#' @export
ECOS_BB_SOLVER <- "ECOS_BB"
#' @rdname solver-constants
#' @export
CPLEX_SOLVER <- "CPLEX"
#' @rdname solver-constants
#' @export
CVXOPT_SOLVER <- "CVXOPT"
#' @rdname solver-constants
#' @export
PIQP_SOLVER <- "PIQP"
#' @rdname solver-constants
#' @export
SCIP_SOLVER <- "SCIP"
#' @rdname solver-constants
#' @export
XPRESS_SOLVER <- "XPRESS"

## CVXPY v1.9.0: NLP solver name constants (settings.py:76,103-105).
#' @rdname solver-constants
#' @export
IPOPT_SOLVER <- "IPOPT"
#' @rdname solver-constants
#' @export
KNITRO_SOLVER <- "KNITRO"
#' @rdname solver-constants
#' @export
UNO_SOLVER <- "UNO"
#' @rdname solver-constants
#' @export
COPT_SOLVER <- "COPT"

# -- DCP curvature strings --------------------------------------------

AFFINE <- "AFFINE"
CONVEX <- "CONVEX"
CONCAVE <- "CONCAVE"
UNKNOWN_CURVATURE <- "UNKNOWN"

# -- Sign strings -----------------------------------------------------

ZERO_SIGN <- "ZERO"
NONNEG_SIGN <- "NONNEGATIVE"
NONPOS_SIGN <- "NONPOSITIVE"
UNKNOWN_SIGN <- "UNKNOWN"

# -- Status strings ---------------------------------------------------

#' Solution Status Constants
#'
#' Character string constants representing the possible solution statuses
#' returned by \code{\link{problem_status}}.
#'
#' @name status-constants
#' @returns A character string.
#' @seealso \code{\link{status}}, \code{\link{psolve}}
NULL

#' @rdname status-constants
#' @export
OPTIMAL <- "optimal"
#' @rdname status-constants
#' @export
INFEASIBLE <- "infeasible"
#' @rdname status-constants
#' @export
UNBOUNDED <- "unbounded"
#' @rdname status-constants
#' @export
SOLVER_ERROR <- "solver_error"
#' @rdname status-constants
#' @export
OPTIMAL_INACCURATE <- "optimal_inaccurate"
#' @rdname status-constants
#' @export
INFEASIBLE_INACCURATE <- "infeasible_inaccurate"
#' @rdname status-constants
#' @export
UNBOUNDED_INACCURATE <- "unbounded_inaccurate"

# -- Default-solver policy --------------------------------------------
## CVXPY SOURCE: settings.py:114-123 (CVXPY 1.9.2, PR #3352).
## Upstream: an internal feature flag, read from the environment ONCE at
## import time, that decides whether the default-solver policy tries
## commercial solvers before the open-source ones.

## Mirrors `_env_var_to_bool`: anything but 0/false/no/off (case- and
## whitespace-insensitive) is TRUE; an unset variable takes `default`.
.env_var_to_bool <- function(name, default) {
  value <- Sys.getenv(name, unset = NA_character_)
  if (is.na(value)) return(default)
  !(tolower(trimws(value)) %in% c("0", "false", "no", "off"))
}

## Whether the default-solver policy tries commercial solvers first.
##
## DELIBERATE R ADAPTATION: upstream freezes this into a module constant at
## import. CVXR reads it on each call and also honors an R option, because a
## constant fixed at load time is not settable in an R session -- upstream's
## own tests have to monkey-patch the module attribute to exercise it. The
## option wins when set; otherwise the environment variable; otherwise TRUE,
## which is upstream's default and CVXR's previous unconditional behavior.
##
##   options(CVXR.default_to_commercial_solvers = FALSE)
##   Sys.setenv(CVXR_DEFAULT_TO_COMMERCIAL_SOLVERS = "0")
.default_to_commercial_solvers <- function() {
  opt <- getOption("CVXR.default_to_commercial_solvers", default = NULL)
  if (!is.null(opt)) return(isTRUE(opt))
  .env_var_to_bool("CVXR_DEFAULT_TO_COMMERCIAL_SOLVERS", TRUE)
}

# -- Numerical tolerances ---------------------------------------------

EIGVAL_TOL <- 1e-10
PSD_NSD_PROJECTION_TOL <- 1e-8
SPARSE_NNZFRAC <- 0.1  # below this fraction, treat as sparse
ATOM_EVAL_TOL <- 1e-4   # tolerance for atom numeric evaluation (CVXPY settings.py)

# -- Naming prefixes ------------------------------------------------
## CVXPY SOURCE: settings.py lines 37-38

VAR_PREFIX <- "var"
PARAM_PREFIX <- "param"

# -- Curvature string (extra) ---------------------------------------
## CVXPY SOURCE: settings.py line 173

CONSTANT_CURV <- "CONSTANT"

# -- Projection tolerances ------------------------------------------
## CVXPY SOURCE: settings.py lines 204-206

GENERAL_PROJECTION_TOL <- 1e-10
SPARSE_PROJECTION_TOL <- 1e-10

# -- Constraint type IDs ------------------------------------------
## CVXPY SOURCE: settings.py line 125
## EQ, LEQ, SOC, SOC_EW, PSD, EXP, BOOL, INT = range(8)

CONSTR_ID_EQ     <- 0L
CONSTR_ID_LEQ    <- 1L
CONSTR_ID_SOC    <- 2L
CONSTR_ID_SOC_EW <- 3L
CONSTR_ID_PSD    <- 4L
CONSTR_ID_EXP    <- 5L
CONSTR_ID_BOOL   <- 6L
CONSTR_ID_INT    <- 7L

# -- Cone dimension keys ------------------------------------------
## CVXPY SOURCE: settings.py lines 133-137

EQ_DIM  <- "f"
LEQ_DIM <- "l"
SOC_DIM <- "q"
PSD_DIM <- "s"
EXP_DIM <- "ep"

# -- Status groups ------------------------------------------------
## CVXPY SOURCE: settings.py lines 58-68

#' @rdname status-constants
#' @export
USER_LIMIT <- "user_limit"
#' @rdname status-constants
#' @export
INFEASIBLE_OR_UNBOUNDED <- "infeasible_or_unbounded"
SOLUTION_PRESENT <- c(OPTIMAL, OPTIMAL_INACCURATE, USER_LIMIT)
INF_OR_UNB <- c(INFEASIBLE, INFEASIBLE_INACCURATE,
                 UNBOUNDED, UNBOUNDED_INACCURATE,
                 INFEASIBLE_OR_UNBOUNDED)
INACCURATE_STATUS <- c(OPTIMAL_INACCURATE, INFEASIBLE_INACCURATE,
                        UNBOUNDED_INACCURATE, USER_LIMIT)
ERROR_STATUS <- c(SOLVER_ERROR)

# -- ECOS exit code -> CVXR status --------------------------------
## CVXPY SOURCE: ecos_conif.py lines 45-57

ECOS_STATUS_MAP <- list(
  "0"  = OPTIMAL,
  "1"  = INFEASIBLE,
  "2"  = UNBOUNDED,
  "10" = OPTIMAL_INACCURATE,
  "11" = INFEASIBLE_INACCURATE,
  "12" = UNBOUNDED_INACCURATE,
  "-1" = USER_LIMIT,
  "-2" = SOLVER_ERROR,
  "-3" = SOLVER_ERROR,
  "-4" = SOLVER_ERROR,
  "-7" = SOLVER_ERROR
)

# -- SCIP status -> CVXR status ----------------------------------
## CVXPY SOURCE: scip_conif.py STATUS_MAP

SCIP_STATUS_MAP <- list(
  "optimal"          = OPTIMAL,
  "timelimit"        = OPTIMAL_INACCURATE,
  "gaplimit"         = OPTIMAL_INACCURATE,
  "nodelimit"        = OPTIMAL_INACCURATE,
  "totalnodelimit"   = OPTIMAL_INACCURATE,
  "bestsollimit"     = USER_LIMIT,
  "infeasible"       = INFEASIBLE,
  "unbounded"        = UNBOUNDED,
  "inforunbd"        = INFEASIBLE_OR_UNBOUNDED,
  "userinterrupt"    = SOLVER_ERROR,
  "memlimit"         = SOLVER_ERROR,
  "sollimit"         = SOLVER_ERROR,
  "stallnodelimit"   = SOLVER_ERROR,
  "restartlimit"     = SOLVER_ERROR,
  "unknown"          = SOLVER_ERROR
)

# -- Solver data keys --------------------------------------------
## CVXPY SOURCE: settings.py lines 159-168
## Use SD_ prefix to avoid R namespace collisions (bare A, B, C shadow base R)

SD_C      <- "c"            # objective vector
SD_OFFSET <- "offset"       # objective constant
SD_P      <- "P"            # quadratic objective matrix
SD_A      <- "A"            # constraint matrix
SD_B      <- "b"            # constraint vector
SD_DIMS   <- "dims"         # cone dimensions
SD_PARAM_PROB <- "param_prob"  # parameterized problem
SD_BOOL_IDX   <- "bool_idx"   # boolean variable indices
SD_INT_IDX    <- "int_idx"    # integer variable indices

# -- Result keys -------------------------------------------------
## CVXPY SOURCE: settings.py lines 147-156

RK_STATUS      <- "status"
RK_VALUE       <- "value"
RK_OBJ_OFFSET  <- "obj_offset"
RK_PRIMAL      <- "primal"
RK_EQ_DUAL     <- "eq_dual"
RK_INEQ_DUAL   <- "ineq_dual"
RK_SOLVE_TIME  <- "solve_time"
RK_SETUP_TIME  <- "setup_time"
RK_NUM_ITERS   <- "num_iters"
RK_EXTRA_STATS <- "solver_specific_stats"

# -- Bounds keys -------------------------------------------------
## CVXPY SOURCE: settings.py lines 143-144

LOWER_BOUNDS <- "lower_bounds"
UPPER_BOUNDS <- "upper_bounds"

# -- Standard solver parameter mappings ----------------------------
## Maps standard CVXR parameter names (reltol, abstol, feastol, num_iter)
## to solver-native parameter names. The `value` fields are the solver's
## own defaults recorded for REFERENCE at mapping-writing time; nothing
## applies them (an unset parameter gets the solver's current default).
## Consumed by .build_solver_params() (zzz_R_specific/solver_opts.R).

## Private store -- exposed via solver_default_param() (read-only).
.SOLVER_DEFAULT_PARAM <- list(
  CLARABEL = list(
    reltol   = list(name = "tol_gap_rel", value = 1e-8),
    abstol   = list(name = "tol_gap_abs", value = 1e-8),
    feastol  = list(name = "tol_feas",    value = 1e-8),
    num_iter = list(name = "max_iter",    value = 200L)
  ),
  OSQP = list(
    reltol   = list(name = "eps_rel",      value = 1e-5),
    abstol   = list(name = "eps_abs",      value = 1e-5),
    feastol  = list(name = "eps_prim_inf", value = 1e-4),
    num_iter = list(name = "max_iter",     value = 10000L)
  ),
  SCS = list(
    reltol   = list(name = "eps_rel",  value = 1e-5),
    abstol   = list(name = "eps_abs",  value = 1e-5),
    num_iter = list(name = "max_iters", value = 2500L)
  ),
  HIGHS = list(
    feastol  = list(name = "primal_feasibility_tolerance", value = 1e-7),
    num_iter = list(name = "simplex_iteration_limit", value = 2147483647L)
  ),
  ## MOSEK names are MSK_*-prefixed so mosek_conif.R can route them into
  ## Rmosek's problem$dparam/$iparam by prefix. The old num_iter mapping
  ## ("num_iter") named nothing Rmosek recognizes -- a no-op since birth.
  ## abstol stays unmapped: MOSEK's only absolute-gap tolerance
  ## (MSK_DPAR_MIO_TOL_ABS_GAP) is MIP-only, and wiring a generic knob to
  ## a narrower one is worse than the (now-warned) absence.
  MOSEK = list(
    feastol  = list(name = "MSK_DPAR_INTPNT_CO_TOL_PFEAS",   value = 1e-8),
    reltol   = list(name = "MSK_DPAR_INTPNT_CO_TOL_REL_GAP", value = 1e-8),
    num_iter = list(name = "MSK_IPAR_INTPNT_MAX_ITERATIONS", value = 400L)
  ),
  GUROBI = list(
    feastol  = list(name = "FeasibilityTol",  value = 1e-6),
    num_iter = list(name = "IterationLimit",  value = 10000L)
  ),
  ECOS = list(
    reltol   = list(name = "RELTOL",  value = 1e-8),
    abstol   = list(name = "ABSTOL",  value = 1e-8),
    feastol  = list(name = "FEASTOL", value = 1e-8),
    num_iter = list(name = "MAXIT",   value = 100L)
  ),
  ECOS_BB = list(
    reltol   = list(name = "RELTOL",       value = 1e-3),
    abstol   = list(name = "ABSTOL",       value = 1e-6),
    feastol  = list(name = "FEASTOL",      value = 1e-6),
    num_iter = list(name = "MI_MAX_ITERS", value = 1000L)
  ),
  CPLEX = list(
    num_iter = list(name = "itlim", value = 10000L)
  ),
  CVXOPT = list(
    abstol   = list(name = "abstol",   value = 1e-6),
    reltol   = list(name = "reltol",   value = 1e-6),
    feastol  = list(name = "feastol",  value = 1e-6),
    num_iter = list(name = "maxiters", value = 100L)
  ),
  PIQP = list(
    reltol   = list(name = "eps_rel", value = 1e-9),
    abstol   = list(name = "eps_abs", value = 1e-8),
    num_iter = list(name = "max_iter", value = 250L)
  ),
  SCIP = list(
    feastol  = list(name = "numerics/feastol", value = 1e-6),
    num_iter = list(name = "lp/iterlim",       value = 2147483647L)
  ),
  XPRESS = list(
    feastol  = list(name = "FEASTOL",      value = 1e-6),
    reltol   = list(name = "BARGAPTARGET", value = 1e-9),
    num_iter = list(name = "LPITERLIMIT",  value = 2147483647L)
  )
  ## GLPK, GLPK_MI: no standard parameter mappings
)

#' Standard Solver Parameter Mappings
#'
#' Returns a named list mapping standard CVXR parameter names (\code{reltol},
#' \code{abstol}, \code{feastol}, \code{num_iter}) to solver-specific
#' parameter names. Used internally by \code{\link{psolve}} to translate
#' standard parameters into solver-native names. A standard parameter with
#' no entry for the chosen solver does not reach that solver;
#' \code{\link{psolve}} warns when that happens.
#'
#' @return A named list keyed by solver name (e.g. \code{"CLARABEL"},
#'   \code{"OSQP"}). Each element is a list of standard parameter mappings,
#'   where each mapping has \code{name} (the solver-native parameter name
#'   the standard name translates to) and \code{value} (the solver's own
#'   default for that parameter, recorded for reference when the mapping
#'   was written; CVXR does not apply these values -- when you do not set
#'   a parameter, the solver uses its own current default).
#' @seealso \code{\link{psolve}}
#' @export
solver_default_param <- function() .SOLVER_DEFAULT_PARAM

## The translation itself lives in .build_solver_params()
## (zzz_R_specific/solver_opts.R), the single path from solver_opts to a
## flat native-parameter list. An earlier duplicate, .apply_std_params(),
## implemented the same rule minus the unmapped-parameter warning and had
## no production callers; it was deleted rather than left to drift.