Nothing
R/005_zzz_R_specific_generics.R
In CVXR: Disciplined Convex Optimization
#####
## DO NOT EDIT THIS FILE!! EDIT THE SOURCE INSTEAD: rsrc_tree/zzz_R_specific/generics.R
#####
## R-SPECIFIC: S7 generics for the CVXR expression interface
##
## These correspond to methods on CVXPY's Expression class and Atom subclasses.
## Naming convention: avoid base R conflicts (e.g., expr_sign instead of sign).
##
## NOTE on additional arguments: S7 generics dispatch on the first argument only.
## Additional arguments (like idx for is_incr) are passed through as extra formals.
## See: https://rconsortium.github.io/S7/articles/generics-methods.html
# -- Expression interface ----------------------------------------------
#' Get the Numeric Value of an Expression
#'
#' Returns the numeric value of a CVXR expression, variable, or constant.
#' For variables, the value is set after solving a problem.
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns A numeric matrix, or \code{NULL} if no value has been set.
#' @export
value <- new_generic("value", "x")
#' Get the Gradient of an Expression
#' @param x An expression object.
#' @param ... Not used.
#' @returns Gradient information.
#' @keywords internal
grad <- new_generic("grad", "x")
#' Per-atom Subgradient Hook (private)
#'
#' R counterpart of CVXPY's `Atom._grad(self, values)`. Returns a list
#' of one Jacobian per argument, shape `(prod(arg.shape), prod(self.shape))`.
#' Called by the chain-rule walker `grad(x)`. The leading dot follows R's
#' private-name convention (cf. `.Machine`, `.libPaths`, `.cvxr_*`); the
#' name maps one-to-one onto CVXPY's `_grad`.
#'
#' @param x An atom expression.
#' @param values A list of numeric values, one per argument.
#' @param ... Reserved for future use; method dispatch ignores it.
#' @returns A list of sparse Jacobians (one per argument).
#' @keywords internal
.grad <- new_generic(".grad", "x",
function(x, values, ...) S7_dispatch())
#' Per-column Subgradient for AxisAtoms (private)
#'
#' R counterpart of CVXPY's `AxisAtom._column_grad(self, value)`.
#' Receives a single column (a 1-D fiber) of the input and returns the
#' gradient of the atom's reduction over that column. Used by
#' `.grad(AxisAtom)`, which walks the input by fibers and assembles
#' the full Jacobian.
#'
#' @param x An axis-atom expression.
#' @param value A numeric vector (the fiber).
#' @param ... Reserved for future use; method dispatch ignores it.
#' @returns A numeric vector of the same length, or `NULL` if the
#' gradient is undefined for this fiber.
#' @keywords internal
.column_grad <- new_generic(".column_grad", "x",
function(x, value, ...) S7_dispatch())
#' Get the Domain Constraints of an Expression
#' @param x An expression object.
#' @param ... Not used.
#' @returns List of constraints defining the domain.
#' @keywords internal
domain <- new_generic("domain", "x")
#' Canonicalize an Expression
#' @param x An expression object.
#' @param ... Not used.
#' @returns List with canonicalized expression and constraints.
#' @keywords internal
canonicalize <- new_generic("canonicalize", "x")
#' Check if an Expression is Constant
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_constant <- new_generic("is_constant", "x")
#' Check if an Expression is Affine
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_affine <- new_generic("is_affine", "x")
#' Check if an Expression is Convex
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_convex <- new_generic("is_convex", "x")
#' Check if an Expression is Concave
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_concave <- new_generic("is_concave", "x")
#' Check if an Expression is DCP-Compliant
#'
#' Tests whether an expression follows the Disciplined Convex Programming
#' (DCP) rules.
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_dcp <- new_generic("is_dcp", "x")
#' Check DPP Compliance
#'
#' Determines whether an expression or problem satisfies the rules of
#' Disciplined Parameterized Programming (DPP). A DPP-compliant problem
#' enables caching the compilation across parameter value changes.
#'
#' @param x An expression, constraint, or problem object.
#' @param context Either \code{"dcp"} (default) or \code{"dgp"}: which
#' discipline to check parameterization against. Mirrors CVXPY's
#' \code{is_dpp(context=...)}.
#' @returns Logical scalar.
#' @export
is_dpp <- new_generic("is_dpp", "x", function(x, context = "dcp") S7_dispatch())
#' Get Atom-Specific Data
#' @param x An expression object.
#' @param ... Not used.
#' @returns List of data.
#' @keywords internal
get_data <- new_generic("get_data", "x")
#' Get the Variables in an Expression
#'
#' @param x An expression or problem object.
#' @param ... Not used.
#' @returns List of \code{\link{Variable}} objects.
#' @export
variables <- new_generic("variables", "x")
#' Get the Parameters in an Expression
#'
#' @param x An expression or problem object.
#' @param ... Not used.
#' @returns List of \code{\link{Parameter}} objects.
#' @export
parameters <- new_generic("parameters", "x")
#' Get the Constants in an Expression
#'
#' @param x An expression or problem object.
#' @param ... Not used.
#' @returns List of \code{\link{Constant}} objects.
#' @export
constants <- new_generic("constants", "x")
#' Get all Parameters of a Problem as a Named List
#'
#' Mirrors CVXPY's \code{Problem.param_dict} property
#' (\code{cvxpy/problems/problem.py:260-264}): returns a named list keyed by
#' each parameter's name, where the value is the \code{\link{Parameter}}
#' object itself.
#'
#' @param x A \code{\link{Problem}} object.
#' @param ... Not used.
#' @returns Named list of \code{\link{Parameter}} objects, keyed by name.
#' @export
param_dict <- new_generic("param_dict", "x")
#' Get all Variables of a Problem as a Named List
#'
#' Mirrors CVXPY's \code{Problem.var_dict} property
#' (\code{cvxpy/problems/problem.py:267-271}): returns a named list keyed by
#' each variable's name, where the value is the \code{\link{Variable}}
#' object itself.
#'
#' @param x A \code{\link{Problem}} object.
#' @param ... Not used.
#' @returns Named list of \code{\link{Variable}} objects, keyed by name.
#' @export
var_dict <- new_generic("var_dict", "x")
#' Get Size Metrics for a Problem
#'
#' Mirrors CVXPY's \code{Problem.size_metrics} property
#' (\code{cvxpy/problems/problem.py:486-490}, class at lines 1690-1752):
#' returns a \code{SizeMetrics} object summarising the problem's scale.
#'
#' @param x A \code{\link{Problem}} object.
#' @param ... Not used.
#' @returns A \code{SizeMetrics} object with seven numeric fields.
#' @export
size_metrics <- new_generic("size_metrics", "x")
#' Get the DCP Sign of an Expression
#'
#' Returns the sign of an expression under DCP analysis. Use this instead
#' of \code{sign()}, which conflicts with the base R function.
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Character string: \code{"POSITIVE"}, \code{"NEGATIVE"},
#' \code{"ZERO"}, or \code{"UNKNOWN"}.
#' @export
expr_sign <- new_generic("expr_sign", "x")
# -- Sign/attribute queries (dispatched on Expression, overridden by Leaf) --
#' Check if Expression is Non-Negative
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_nonneg <- new_generic("is_nonneg", "x")
#' Lower/Upper Bounds of a Leaf
#'
#' Returns the effective `(lower, upper)` bounds of a leaf, combining its
#' `bounds` attribute with sign (`nonneg`/`pos`/`nonpos`/`neg`) and `boolean`
#' attributes. Used by the NLP (DNLP) solve path to form variable bounds.
#'
#' @param x An expression (a [Variable]/leaf, or a composite expression whose
#' bounds are propagated from its arguments).
#' @param ... Passed to methods; currently unused.
#' @returns A list `list(lower, upper)` of two real matrices matching the
#' expression shape (column-major). For leaves these come from explicit bounds
#' and sign attributes; for atoms they are propagated from argument bounds via
#' interval arithmetic (see `bounds_from_args`).
#' @name get_bounds
## CVXPY v1.9.0 feature: get_bounds (abstract on expressions/expression.py:566;
## concrete on expressions/leaf.py:929, atoms/atom.py:130). Introduced for the
## 1.9 DNLP/bounds work; expression-tree propagation is #3080 (Wave 2).
#' @export
get_bounds <- new_generic("get_bounds", "x")
## CVXPY SOURCE: atoms/atom.py:116 (bounds_from_args). Internal: an atom's
## interval bounds computed from its arguments' bounds. Default (Atom method)
## is unbounded; atoms override with the relevant utilities/bounds.R helper.
bounds_from_args <- new_generic("bounds_from_args", "x")
#' Check if Expression is Non-Positive
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_nonpos <- new_generic("is_nonpos", "x")
#' Check if Expression is Zero
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_zero <- new_generic("is_zero", "x")
#' Check if Expression is Positive Semidefinite
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_psd <- new_generic("is_psd", "x")
#' Check if Expression is Negative Semidefinite
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_nsd <- new_generic("is_nsd", "x")
#' Check if Expression is Symmetric
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_symmetric <- new_generic("is_symmetric", "x")
# -- Phase 1: additional generics -------------------------------------
#' Get the Name of an Expression
#' @param x An expression object.
#' @param ... Not used.
#' @returns Character string.
#' @keywords internal
expr_name <- new_generic("expr_name", "x")
#' Get the label of an expression
#'
#' Returns the human-readable label set via [set_label()] (or
#' `label(x) <- ...`), or `NULL` if no label has been set.
#'
#' @param x An Expression object.
#' @returns A length-1 character string, or `NULL`.
#' @seealso [set_label()], [format_labeled()]
#' @export
label <- new_generic("label", "x", function(x) S7_dispatch())
#' Set the label of an expression
#'
#' R replacement form of [set_label()]. `label(x) <- value` stores
#' `value` (coerced to character) in `x`'s internal label slot; setting
#' to `NULL` clears the label. Equivalent to `x <- set_label(x, value)`.
#'
#' @param x An Expression object.
#' @param value A character string, or `NULL` to clear.
#' @returns `x`, invisibly, with the label updated.
#' @seealso [set_label()], [format_labeled()]
#' @export
`label<-` <- new_generic("label<-", "x",
function(x, value) S7_dispatch())
#' Attach a label to an expression
#'
#' CVXPY-parity setter that returns its first argument so calls can be
#' chained (e.g. `sum_squares(x) |> set_label("cost")`). See
#' [format_labeled()] for the pretty-printer that consumes labels.
#'
#' @param x An Expression object.
#' @param value A label (character; coerced via `as.character`).
#' Pass `NULL` to clear an existing label.
#' @returns `x` with the label updated.
#' @seealso [label()], [format_labeled()]
#' @export
set_label <- new_generic("set_label", "x",
function(x, value) S7_dispatch())
#' Pretty-print an expression with labels substituted
#'
#' Recursive analogue of [expr_name()] that substitutes user-supplied
#' labels (see [set_label()]) for sub-expressions wherever they are set,
#' falling back to the structural name on unlabelled nodes. Mirrors
#' CVXPY's `Expression.format_labeled`.
#'
#' @param x An Expression object.
#' @returns A character string.
#' @seealso [set_label()], [label()]
#' @export
format_labeled <- new_generic("format_labeled", "x", function(x) S7_dispatch())
#' Set the Value of a Leaf Expression
#'
#' Assigns a numeric value to a \code{\link{Variable}} or
#' \code{\link{Parameter}}.
#'
#' @param x A leaf expression object.
#' @param value The value to assign.
#' @returns The modified object (invisibly).
#' @export
`value<-` <- new_generic("value<-", "x",
function(x, value) S7_dispatch())
#' Sampling Bounds for NLP Random Restarts
#'
#' Get or set a \code{\link{Variable}}'s \code{sample_bounds} -- a
#' \code{(low, high)} region used to draw random initial points in
#' \code{best_of} NLP solves (\code{\link{psolve}(prob, nlp = TRUE, best_of = n)}).
#' When set, it overrides the variable's value during random initialization;
#' when \code{NULL} (the default) finite variable bounds are used instead.
#' Supply a pair \code{c(low, high)} (scalars broadcast to the variable shape)
#' or a \code{list(low, high)} of per-entry vectors; set \code{NULL} to clear.
#'
#' @param x A \code{\link{Variable}}.
#' @param value A \code{(low, high)} pair, or \code{NULL} to clear.
#' @param ... Not used.
#' @returns \code{sample_bounds(x)} returns the stored \code{list(low, high)}
#' or \code{NULL}; the setter returns the modified variable.
#' @name sample_bounds
#' @export
sample_bounds <- new_generic("sample_bounds", "x")
#' @rdname sample_bounds
#' @export
`sample_bounds<-` <- new_generic("sample_bounds<-", "x",
function(x, value) S7_dispatch())
#' Get the Atoms in an Expression
#' @param x An expression object.
#' @param ... Not used.
#' @returns List of atom objects.
#' @keywords internal
atoms <- new_generic("atoms", "x")
#' Check if Expression is Complex
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_complex <- new_generic("is_complex", "x")
#' Check if Expression is Imaginary
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_imag <- new_generic("is_imag", "x")
#' Project a Value onto the Domain of a Leaf
#' @param x A leaf expression object.
#' @param val The value to project.
#' @param ... Additional arguments.
#' @returns The projected value.
#' @keywords internal
project <- new_generic("project", "x",
function(x, val, ...) S7_dispatch())
#' Check if Expression is Hermitian
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_hermitian <- new_generic("is_hermitian", "x")
#' Check if Expression is Skew-Symmetric
#'
#' Tests whether \code{X + t(X) == 0} (real matrices only).
#' CVXPY SOURCE: expression.py line 470-473
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_skew_symmetric <- new_generic("is_skew_symmetric", "x")
#' Check if Expression is Real
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_real <- new_generic("is_real", "x")
#' Check if Expression is Log-Log Convex
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_log_log_convex <- new_generic("is_log_log_convex", "x")
#' Check if Expression is Log-Log Concave
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_log_log_concave <- new_generic("is_log_log_concave", "x")
#' Check if Expression is Log-Log Affine
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_log_log_affine <- new_generic("is_log_log_affine", "x")
#' Get the Canonical Form
#' @param x A canonicalizable object.
#' @param ... Not used.
#' @returns List with (expression, constraints).
#' @keywords internal
canonical_form <- new_generic("canonical_form", "x")
#' Shallow Copy of an Expression Tree Node
#' @param x A canonicalizable object.
#' @param args Optional replacement args.
#' @param id_objects Optional identity map for deduplication.
#' @returns A copy of the object.
#' @keywords internal
expr_copy <- new_generic("expr_copy", "x",
function(x, args = NULL, id_objects = NULL) S7_dispatch())
#' Deep Copy of an Expression Tree
#' @param x A canonicalizable object.
#' @param id_objects Optional identity map for deduplication.
#' @returns A deep copy of the entire expression tree.
#' @keywords internal
tree_copy <- new_generic("tree_copy", "x",
function(x, id_objects = NULL) S7_dispatch())
# -- Quadratic / piecewise-linear analysis --------------------------
## CVXPY SOURCE: expression.py lines 448-484
## These are needed by the QP solver path (OSQP) for problem classification.
#' Check if an Expression is Quadratic
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_quadratic <- new_generic("is_quadratic", "x")
#' Check if Expression Has a Quadratic Term
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
has_quadratic_term <- new_generic("has_quadratic_term", "x")
#' Check if Expression is Piecewise Linear
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_pwl <- new_generic("is_pwl", "x")
#' Check if Expression is Quadratic or Piecewise Affine
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_qpwa <- new_generic("is_qpwa", "x")
# -- Strictly positive check ---------------------------------------
## CVXPY SOURCE: leaf.py::is_pos -- checks attributes['pos'] on Leaf,
## checks actual value > 0 on Constant.
#' Check if Expression is Strictly Positive
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_pos <- new_generic("is_pos", "x")
# -- Domain hook ---------------------------------------------------
#' Get Atom-Specific Domain Constraints
#' @param x An atom object.
#' @param ... Not used.
#' @returns List of Constraint objects.
#' @keywords internal
atom_domain <- new_generic("atom_domain", "x")
# -- Constraint generics --------------------------------------------
#' Get the Residual of a Constraint
#'
#' Returns the residual of a constraint, measuring how much the constraint
#' is violated or satisfied.
#'
#' @param x A constraint object.
#' @param ... Not used.
#' @returns Numeric array, or \code{NULL} if expression has no value.
#' @export
residual <- new_generic("residual", "x")
#' Get the Violation of a Constraint
#'
#' Returns the scalar violation (distance to feasibility) of a constraint.
#'
#' @param x A constraint object.
#' @param ... Not used.
#' @returns Numeric scalar.
#' @export
violation <- new_generic("violation", "x")
# -- Cone constraint generics --------------------------------------
## CVXPY SOURCE: constraints/cones.py, second_order.py, psd.py, etc.
#' Get the Number of Cones in a Constraint
#' @param x A cone constraint object.
#' @param ... Not used.
#' @returns Integer.
#' @keywords internal
num_cones <- new_generic("num_cones", "x")
#' Get the Sizes of Individual Cones
#' @param x A cone constraint object.
#' @param ... Not used.
#' @returns Integer vector of cone sizes.
#' @keywords internal
cone_sizes <- new_generic("cone_sizes", "x")
#' Get the Total Size of a Constraint
#' @param x A constraint object.
#' @param ... Not used.
#' @returns Integer.
#' @keywords internal
constr_size <- new_generic("constr_size", "x")
#' Get the Dual Cone Constraint
#' @param x A cone constraint object.
#' @param ... Optional arguments.
#' @returns A cone constraint representing the dual cone.
#' @keywords internal
dual_cone <- new_generic("dual_cone", "x",
function(x, ...) S7_dispatch())
#' Get the Dual Residual
#' @param x A cone constraint object.
#' @param ... Not used.
#' @returns Numeric residual.
#' @keywords internal
dual_residual <- new_generic("dual_residual", "x")
#' Check if a Constraint is DGP-Compliant
#' @param x A constraint object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_dgp <- new_generic("is_dgp", "x")
#' Save Dual Variable Values from Solver Output
#' @param x A constraint object.
#' @param val The dual value from the solver.
#' @returns Invisible constraint (side effect: sets dual variable values).
#' @keywords internal
save_dual_value <- new_generic("save_dual_value", "x",
function(x, val) S7_dispatch())
# -- Atom validation -------------------------------------------------
#' Validate Arguments to an Atom
#' @param x An atom object.
#' @param ... Not used.
#' @returns Invisible \code{NULL} (or error if invalid).
#' @keywords internal
validate_arguments <- new_generic("validate_arguments", "x")
# -- Atom hooks --------------------------------------------------------
#' Infer Shape from Arguments
#' @param x An atom object.
#' @param ... Not used.
#' @returns Integer vector of shape dimensions.
#' @keywords internal
shape_from_args <- new_generic("shape_from_args", "x")
#' Infer Sign from Arguments
#' @param x An atom object.
#' @param ... Not used.
#' @returns Character string: sign constant.
#' @keywords internal
sign_from_args <- new_generic("sign_from_args", "x")
#' Check if Atom is Convex
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_atom_convex <- new_generic("is_atom_convex", "x")
#' Check if Atom is Concave
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_atom_concave <- new_generic("is_atom_concave", "x")
#' Check if Atom is Log-Log Convex
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_atom_log_log_convex <- new_generic("is_atom_log_log_convex", "x")
#' Check if Atom is Log-Log Concave
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_atom_log_log_concave <- new_generic("is_atom_log_log_concave", "x")
#' Check if Atom is Increasing in an Argument
#' @param x An atom object.
#' @param idx Integer: argument index (1-based, R convention).
#' @param ... Additional arguments.
#' @returns Logical scalar.
#' @keywords internal
is_incr <- new_generic("is_incr", "x",
function(x, idx, ...) S7_dispatch())
#' Check if Atom is Decreasing in an Argument
#' @param x An atom object.
#' @param idx Integer: argument index (1-based, R convention).
#' @param ... Additional arguments.
#' @returns Logical scalar.
#' @keywords internal
is_decr <- new_generic("is_decr", "x",
function(x, idx, ...) S7_dispatch())
#' Get the Graph Implementation of an Atom
#' @param x An atom object.
#' @param arg_objs List of canonicalized argument LinOps.
#' @param shape Integer vector: target shape.
#' @param data Optional atom-specific data.
#' @param ... Additional arguments.
#' @returns List with (expression, constraints).
#' @keywords internal
graph_implementation <- new_generic("graph_implementation", "x",
function(x, arg_objs, shape, data = NULL, ...) S7_dispatch())
#' Compute the Numeric Value of an Atom
#' @param x An atom object.
#' @param values List of numeric values of the atom's arguments.
#' @param ... Additional arguments.
#' @returns Numeric value.
#' @keywords internal
numeric_value <- new_generic("numeric_value", "x",
function(x, values, ...) S7_dispatch())
# -- DQCP curvature queries ---------------------------------------
## CVXPY SOURCE: expression.py lines 411-429, atom.py lines 288-335
#' Check if Expression is Quasiconvex
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_quasiconvex <- new_generic("is_quasiconvex", "x")
#' Check if Expression is Quasiconcave
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_quasiconcave <- new_generic("is_quasiconcave", "x")
#' Check if Expression is Quasilinear
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_quasilinear <- new_generic("is_quasilinear", "x")
#' Check if Expression is DQCP-Compliant
#'
#' Tests whether an expression follows the Disciplined Quasiconvex
#' Programming (DQCP) rules.
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_dqcp <- new_generic("is_dqcp", "x")
#' Check if Atom is Quasiconvex
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_atom_quasiconvex <- new_generic("is_atom_quasiconvex", "x")
#' Check if Atom is Quasiconcave
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_atom_quasiconcave <- new_generic("is_atom_quasiconcave", "x")
# -- DNLP curvature queries (CVXPY 1.9.0) -------------------------
## CVXPY SOURCE: expression.py:349-405, atom.py:191-298, leaf.py:267-273.
## The disciplined-nonlinear-programming (DNLP) predicate cluster: an
## expression is DNLP if it is "smooth representable" -- convex (or concave)
## after linearizing every smooth subexpression. is_smooth / is_atom_smooth /
## is_linearizable_* are the supporting predicates; is_dnlp is the user-facing
## one (parallels is_dcp / is_dqcp / is_dgp).
#' Check if an Expression is Smooth
#'
#' Smooth = constant, or both linearizable-convex and linearizable-concave.
#' Mirrors CVXPY's \code{Expression.is_smooth()}.
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @seealso \code{\link{is_dnlp}}, \code{\link{is_linearizable_convex}},
#' \code{\link{is_linearizable_concave}}
#' @export
is_smooth <- new_generic("is_smooth", "x")
#' Check if an Atom is Smooth
#'
#' Atom-level hook (default FALSE); smooth atoms (e.g. trig/hyperbolic)
#' override this to TRUE. Mirrors CVXPY's \code{Atom.is_atom_smooth()}.
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @seealso \code{\link{is_smooth}}
#' @export
is_atom_smooth <- new_generic("is_atom_smooth", "x")
#' Check if an Expression is Linearizable-Convex
#'
#' Convex after linearizing all smooth subexpressions (DNLP composition rule).
#' Mirrors CVXPY's \code{Expression.is_linearizable_convex()}.
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @seealso \code{\link{is_dnlp}}, \code{\link{is_linearizable_concave}}
#' @export
is_linearizable_convex <- new_generic("is_linearizable_convex", "x")
#' Check if an Expression is Linearizable-Concave
#'
#' Concave after linearizing all smooth subexpressions (DNLP composition rule).
#' Mirrors CVXPY's \code{Expression.is_linearizable_concave()}.
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @seealso \code{\link{is_dnlp}}, \code{\link{is_linearizable_convex}}
#' @export
is_linearizable_concave <- new_generic("is_linearizable_concave", "x")
#' Check if an Expression or Problem is DNLP-Compliant
#'
#' Tests whether the object follows the Disciplined Nonlinear Programming
#' (DNLP) rules: smooth representable, i.e. linearizable-convex or
#' linearizable-concave.
#'
#' @param x An expression, objective, constraint, or \code{\link{Problem}}.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_dnlp <- new_generic("is_dnlp", "x")
# -- Problem classification ---------------------------------------
#' Check if a Problem is a Quadratic Program
#'
#' @param x A \code{\link{Problem}} object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_qp <- new_generic("is_qp", "x")
#' Check if a Problem is a Linear Program
#'
#' @param x A \code{\link{Problem}} object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_lp <- new_generic("is_lp", "x")
# -- Reduction interface ------------------------------------------
#' Check if a Reduction Accepts a Problem
#' @param x A Reduction object.
#' @param problem A Problem object.
#' @param ... Additional arguments.
#' @returns Logical scalar.
#' @keywords internal
reduction_accepts <- new_generic("reduction_accepts", "x",
function(x, problem, ...) S7_dispatch())
#' Apply a Reduction to a Problem
#' @param x A Reduction object.
#' @param problem A Problem object.
#' @param ... Additional arguments.
#' @returns List with (new_problem, inverse_data).
#' @keywords internal
reduction_apply <- new_generic("reduction_apply", "x",
function(x, problem, ...) S7_dispatch())
#' Invert a Solution through a Reduction
#' @param x A Reduction object.
#' @param solution A solution object.
#' @param inverse_data Inverse data from apply.
#' @param ... Additional arguments.
#' @returns A solution to the original problem.
#' @keywords internal
reduction_invert <- new_generic("reduction_invert", "x",
function(x, solution, inverse_data, ...) S7_dispatch())
#' Update Parameters for DPP Fast Path
#' @param x A Reduction object.
#' @param problem A Problem object.
#' @param ... Additional arguments.
#' @returns NULL (called for side effects).
#' @keywords internal
update_parameters <- new_generic("update_parameters", "x",
function(x, problem, ...) S7_dispatch())
# -- Solver interface -----------------------------------------------
#' Get Solver Name
#' @param x A Solver object.
#' @param ... Not used.
#' @returns Character string with solver name.
#' @keywords internal
solver_name <- new_generic("solver_name", "x")
#' Does Solver Support Quadratic Objectives?
#'
#' CVXPY v1.8.2: controls whether the conic path keeps the quadratic
#' objective as a P matrix or decomposes it into cones.
#' @param x A solver object.
#' @returns Logical scalar.
#' @keywords internal
supports_quad_obj <- new_generic("supports_quad_obj", "x")
#' Solve via Raw Data
#'
#' Calls the solver on pre-compiled problem data (step 2 of the
#' decomposed solve pipeline). Dispatches on \code{x}: when \code{x}
#' is a \code{SolvingChain}, delegates to the terminal solver with
#' proper cache management.
#'
#' @param x A \code{SolvingChain} (preferred) or \code{Solver} object.
#' @param data Named list of solver data from \code{\link{problem_data}()}.
#' @param warm_start Logical; use warm-start if supported.
#' @param verbose Logical; print solver output.
#' @param solver_opts Named list of solver-specific options.
#' @param ... Additional arguments forwarded to the method (e.g.
#' \code{problem} for the \code{SolvingChain} method, \code{solver_cache}
#' for the \code{Solver} method).
#' @returns Solver-specific result (a named list).
#'
#' @seealso \code{\link{problem_data}}, \code{\link{problem_unpack_results}}
#' @export
solve_via_data <- new_generic("solve_via_data", "x",
function(x, data, warm_start = FALSE, verbose = FALSE, solver_opts = list(), ...) S7_dispatch())
#' Get Problem Data for a Solver
#'
#' Returns the problem data that would be passed to a specific solver,
#' along with the reduction chain and inverse data for solution retrieval.
#'
#' @param x A \code{\link{Problem}} object.
#' @param solver Character string naming solver, or \code{NULL} for
#' automatic selection.
#' @param gp Logical; if \code{TRUE}, parse the problem as a geometric program.
#' @param enforce_dpp Logical; if \code{TRUE}, raise an error when a
#' parametrized problem is not DPP instead of compiling it as non-DPP.
#' @param ignore_dpp Logical; if \code{TRUE}, treat a DPP problem as non-DPP
#' (skip the DPP fast path).
#' @param ... Additional solver options.
#' @returns A list with components \code{data}, \code{chain}, and
#' \code{inverse_data}.
#' @export
problem_data <- new_generic("problem_data", "x",
function(x, solver = NULL, gp = FALSE, enforce_dpp = FALSE, ignore_dpp = FALSE, ...)
S7_dispatch())
#' Get Problem Data for a Solver (deprecated)
#'
#' `r lifecycle::badge("deprecated")`
#'
#' Use \code{\link{problem_data}} instead.
#'
#' @param x A \code{\link{Problem}} object.
#' @param solver Character string naming solver, or \code{NULL} for
#' automatic selection.
#' @param gp Logical; if \code{TRUE}, parse the problem as a geometric program.
#' @param enforce_dpp Logical; if \code{TRUE}, raise an error when a
#' parametrized problem is not DPP instead of compiling it as non-DPP.
#' @param ignore_dpp Logical; if \code{TRUE}, treat a DPP problem as non-DPP
#' (skip the DPP fast path).
#' @param ... Additional solver options.
#' @returns A list with components \code{data}, \code{chain}, and
#' \code{inverse_data}.
#' @seealso \code{\link{problem_data}}
#' @export
get_problem_data <- new_generic("get_problem_data", "x",
function(x, solver = NULL, gp = FALSE, enforce_dpp = FALSE, ignore_dpp = FALSE, ...)
S7_dispatch())
Try the CVXR package in your browser
Any scripts or data that you put into this service are public.
CVXR documentation built on Aug. 24, 2026, 9:10 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
#####
## DO NOT EDIT THIS FILE!! EDIT THE SOURCE INSTEAD: rsrc_tree/zzz_R_specific/generics.R
#####
## R-SPECIFIC: S7 generics for the CVXR expression interface
##
## These correspond to methods on CVXPY's Expression class and Atom subclasses.
## Naming convention: avoid base R conflicts (e.g., expr_sign instead of sign).
##
## NOTE on additional arguments: S7 generics dispatch on the first argument only.
## Additional arguments (like idx for is_incr) are passed through as extra formals.
## See: https://rconsortium.github.io/S7/articles/generics-methods.html
# -- Expression interface ----------------------------------------------
#' Get the Numeric Value of an Expression
#'
#' Returns the numeric value of a CVXR expression, variable, or constant.
#' For variables, the value is set after solving a problem.
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns A numeric matrix, or \code{NULL} if no value has been set.
#' @export
value <- new_generic("value", "x")
#' Get the Gradient of an Expression
#' @param x An expression object.
#' @param ... Not used.
#' @returns Gradient information.
#' @keywords internal
grad <- new_generic("grad", "x")
#' Per-atom Subgradient Hook (private)
#'
#' R counterpart of CVXPY's `Atom._grad(self, values)`. Returns a list
#' of one Jacobian per argument, shape `(prod(arg.shape), prod(self.shape))`.
#' Called by the chain-rule walker `grad(x)`. The leading dot follows R's
#' private-name convention (cf. `.Machine`, `.libPaths`, `.cvxr_*`); the
#' name maps one-to-one onto CVXPY's `_grad`.
#'
#' @param x An atom expression.
#' @param values A list of numeric values, one per argument.
#' @param ... Reserved for future use; method dispatch ignores it.
#' @returns A list of sparse Jacobians (one per argument).
#' @keywords internal
.grad <- new_generic(".grad", "x",
function(x, values, ...) S7_dispatch())
#' Per-column Subgradient for AxisAtoms (private)
#'
#' R counterpart of CVXPY's `AxisAtom._column_grad(self, value)`.
#' Receives a single column (a 1-D fiber) of the input and returns the
#' gradient of the atom's reduction over that column. Used by
#' `.grad(AxisAtom)`, which walks the input by fibers and assembles
#' the full Jacobian.
#'
#' @param x An axis-atom expression.
#' @param value A numeric vector (the fiber).
#' @param ... Reserved for future use; method dispatch ignores it.
#' @returns A numeric vector of the same length, or `NULL` if the
#' gradient is undefined for this fiber.
#' @keywords internal
.column_grad <- new_generic(".column_grad", "x",
function(x, value, ...) S7_dispatch())
#' Get the Domain Constraints of an Expression
#' @param x An expression object.
#' @param ... Not used.
#' @returns List of constraints defining the domain.
#' @keywords internal
domain <- new_generic("domain", "x")
#' Canonicalize an Expression
#' @param x An expression object.
#' @param ... Not used.
#' @returns List with canonicalized expression and constraints.
#' @keywords internal
canonicalize <- new_generic("canonicalize", "x")
#' Check if an Expression is Constant
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_constant <- new_generic("is_constant", "x")
#' Check if an Expression is Affine
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_affine <- new_generic("is_affine", "x")
#' Check if an Expression is Convex
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_convex <- new_generic("is_convex", "x")
#' Check if an Expression is Concave
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_concave <- new_generic("is_concave", "x")
#' Check if an Expression is DCP-Compliant
#'
#' Tests whether an expression follows the Disciplined Convex Programming
#' (DCP) rules.
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_dcp <- new_generic("is_dcp", "x")
#' Check DPP Compliance
#'
#' Determines whether an expression or problem satisfies the rules of
#' Disciplined Parameterized Programming (DPP). A DPP-compliant problem
#' enables caching the compilation across parameter value changes.
#'
#' @param x An expression, constraint, or problem object.
#' @param context Either \code{"dcp"} (default) or \code{"dgp"}: which
#' discipline to check parameterization against. Mirrors CVXPY's
#' \code{is_dpp(context=...)}.
#' @returns Logical scalar.
#' @export
is_dpp <- new_generic("is_dpp", "x", function(x, context = "dcp") S7_dispatch())
#' Get Atom-Specific Data
#' @param x An expression object.
#' @param ... Not used.
#' @returns List of data.
#' @keywords internal
get_data <- new_generic("get_data", "x")
#' Get the Variables in an Expression
#'
#' @param x An expression or problem object.
#' @param ... Not used.
#' @returns List of \code{\link{Variable}} objects.
#' @export
variables <- new_generic("variables", "x")
#' Get the Parameters in an Expression
#'
#' @param x An expression or problem object.
#' @param ... Not used.
#' @returns List of \code{\link{Parameter}} objects.
#' @export
parameters <- new_generic("parameters", "x")
#' Get the Constants in an Expression
#'
#' @param x An expression or problem object.
#' @param ... Not used.
#' @returns List of \code{\link{Constant}} objects.
#' @export
constants <- new_generic("constants", "x")
#' Get all Parameters of a Problem as a Named List
#'
#' Mirrors CVXPY's \code{Problem.param_dict} property
#' (\code{cvxpy/problems/problem.py:260-264}): returns a named list keyed by
#' each parameter's name, where the value is the \code{\link{Parameter}}
#' object itself.
#'
#' @param x A \code{\link{Problem}} object.
#' @param ... Not used.
#' @returns Named list of \code{\link{Parameter}} objects, keyed by name.
#' @export
param_dict <- new_generic("param_dict", "x")
#' Get all Variables of a Problem as a Named List
#'
#' Mirrors CVXPY's \code{Problem.var_dict} property
#' (\code{cvxpy/problems/problem.py:267-271}): returns a named list keyed by
#' each variable's name, where the value is the \code{\link{Variable}}
#' object itself.
#'
#' @param x A \code{\link{Problem}} object.
#' @param ... Not used.
#' @returns Named list of \code{\link{Variable}} objects, keyed by name.
#' @export
var_dict <- new_generic("var_dict", "x")
#' Get Size Metrics for a Problem
#'
#' Mirrors CVXPY's \code{Problem.size_metrics} property
#' (\code{cvxpy/problems/problem.py:486-490}, class at lines 1690-1752):
#' returns a \code{SizeMetrics} object summarising the problem's scale.
#'
#' @param x A \code{\link{Problem}} object.
#' @param ... Not used.
#' @returns A \code{SizeMetrics} object with seven numeric fields.
#' @export
size_metrics <- new_generic("size_metrics", "x")
#' Get the DCP Sign of an Expression
#'
#' Returns the sign of an expression under DCP analysis. Use this instead
#' of \code{sign()}, which conflicts with the base R function.
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Character string: \code{"POSITIVE"}, \code{"NEGATIVE"},
#' \code{"ZERO"}, or \code{"UNKNOWN"}.
#' @export
expr_sign <- new_generic("expr_sign", "x")
# -- Sign/attribute queries (dispatched on Expression, overridden by Leaf) --
#' Check if Expression is Non-Negative
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_nonneg <- new_generic("is_nonneg", "x")
#' Lower/Upper Bounds of a Leaf
#'
#' Returns the effective `(lower, upper)` bounds of a leaf, combining its
#' `bounds` attribute with sign (`nonneg`/`pos`/`nonpos`/`neg`) and `boolean`
#' attributes. Used by the NLP (DNLP) solve path to form variable bounds.
#'
#' @param x An expression (a [Variable]/leaf, or a composite expression whose
#' bounds are propagated from its arguments).
#' @param ... Passed to methods; currently unused.
#' @returns A list `list(lower, upper)` of two real matrices matching the
#' expression shape (column-major). For leaves these come from explicit bounds
#' and sign attributes; for atoms they are propagated from argument bounds via
#' interval arithmetic (see `bounds_from_args`).
#' @name get_bounds
## CVXPY v1.9.0 feature: get_bounds (abstract on expressions/expression.py:566;
## concrete on expressions/leaf.py:929, atoms/atom.py:130). Introduced for the
## 1.9 DNLP/bounds work; expression-tree propagation is #3080 (Wave 2).
#' @export
get_bounds <- new_generic("get_bounds", "x")
## CVXPY SOURCE: atoms/atom.py:116 (bounds_from_args). Internal: an atom's
## interval bounds computed from its arguments' bounds. Default (Atom method)
## is unbounded; atoms override with the relevant utilities/bounds.R helper.
bounds_from_args <- new_generic("bounds_from_args", "x")
#' Check if Expression is Non-Positive
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_nonpos <- new_generic("is_nonpos", "x")
#' Check if Expression is Zero
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_zero <- new_generic("is_zero", "x")
#' Check if Expression is Positive Semidefinite
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_psd <- new_generic("is_psd", "x")
#' Check if Expression is Negative Semidefinite
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_nsd <- new_generic("is_nsd", "x")
#' Check if Expression is Symmetric
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_symmetric <- new_generic("is_symmetric", "x")
# -- Phase 1: additional generics -------------------------------------
#' Get the Name of an Expression
#' @param x An expression object.
#' @param ... Not used.
#' @returns Character string.
#' @keywords internal
expr_name <- new_generic("expr_name", "x")
#' Get the label of an expression
#'
#' Returns the human-readable label set via [set_label()] (or
#' `label(x) <- ...`), or `NULL` if no label has been set.
#'
#' @param x An Expression object.
#' @returns A length-1 character string, or `NULL`.
#' @seealso [set_label()], [format_labeled()]
#' @export
label <- new_generic("label", "x", function(x) S7_dispatch())
#' Set the label of an expression
#'
#' R replacement form of [set_label()]. `label(x) <- value` stores
#' `value` (coerced to character) in `x`'s internal label slot; setting
#' to `NULL` clears the label. Equivalent to `x <- set_label(x, value)`.
#'
#' @param x An Expression object.
#' @param value A character string, or `NULL` to clear.
#' @returns `x`, invisibly, with the label updated.
#' @seealso [set_label()], [format_labeled()]
#' @export
`label<-` <- new_generic("label<-", "x",
function(x, value) S7_dispatch())
#' Attach a label to an expression
#'
#' CVXPY-parity setter that returns its first argument so calls can be
#' chained (e.g. `sum_squares(x) |> set_label("cost")`). See
#' [format_labeled()] for the pretty-printer that consumes labels.
#'
#' @param x An Expression object.
#' @param value A label (character; coerced via `as.character`).
#' Pass `NULL` to clear an existing label.
#' @returns `x` with the label updated.
#' @seealso [label()], [format_labeled()]
#' @export
set_label <- new_generic("set_label", "x",
function(x, value) S7_dispatch())
#' Pretty-print an expression with labels substituted
#'
#' Recursive analogue of [expr_name()] that substitutes user-supplied
#' labels (see [set_label()]) for sub-expressions wherever they are set,
#' falling back to the structural name on unlabelled nodes. Mirrors
#' CVXPY's `Expression.format_labeled`.
#'
#' @param x An Expression object.
#' @returns A character string.
#' @seealso [set_label()], [label()]
#' @export
format_labeled <- new_generic("format_labeled", "x", function(x) S7_dispatch())
#' Set the Value of a Leaf Expression
#'
#' Assigns a numeric value to a \code{\link{Variable}} or
#' \code{\link{Parameter}}.
#'
#' @param x A leaf expression object.
#' @param value The value to assign.
#' @returns The modified object (invisibly).
#' @export
`value<-` <- new_generic("value<-", "x",
function(x, value) S7_dispatch())
#' Sampling Bounds for NLP Random Restarts
#'
#' Get or set a \code{\link{Variable}}'s \code{sample_bounds} -- a
#' \code{(low, high)} region used to draw random initial points in
#' \code{best_of} NLP solves (\code{\link{psolve}(prob, nlp = TRUE, best_of = n)}).
#' When set, it overrides the variable's value during random initialization;
#' when \code{NULL} (the default) finite variable bounds are used instead.
#' Supply a pair \code{c(low, high)} (scalars broadcast to the variable shape)
#' or a \code{list(low, high)} of per-entry vectors; set \code{NULL} to clear.
#'
#' @param x A \code{\link{Variable}}.
#' @param value A \code{(low, high)} pair, or \code{NULL} to clear.
#' @param ... Not used.
#' @returns \code{sample_bounds(x)} returns the stored \code{list(low, high)}
#' or \code{NULL}; the setter returns the modified variable.
#' @name sample_bounds
#' @export
sample_bounds <- new_generic("sample_bounds", "x")
#' @rdname sample_bounds
#' @export
`sample_bounds<-` <- new_generic("sample_bounds<-", "x",
function(x, value) S7_dispatch())
#' Get the Atoms in an Expression
#' @param x An expression object.
#' @param ... Not used.
#' @returns List of atom objects.
#' @keywords internal
atoms <- new_generic("atoms", "x")
#' Check if Expression is Complex
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_complex <- new_generic("is_complex", "x")
#' Check if Expression is Imaginary
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_imag <- new_generic("is_imag", "x")
#' Project a Value onto the Domain of a Leaf
#' @param x A leaf expression object.
#' @param val The value to project.
#' @param ... Additional arguments.
#' @returns The projected value.
#' @keywords internal
project <- new_generic("project", "x",
function(x, val, ...) S7_dispatch())
#' Check if Expression is Hermitian
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_hermitian <- new_generic("is_hermitian", "x")
#' Check if Expression is Skew-Symmetric
#'
#' Tests whether \code{X + t(X) == 0} (real matrices only).
#' CVXPY SOURCE: expression.py line 470-473
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_skew_symmetric <- new_generic("is_skew_symmetric", "x")
#' Check if Expression is Real
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_real <- new_generic("is_real", "x")
#' Check if Expression is Log-Log Convex
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_log_log_convex <- new_generic("is_log_log_convex", "x")
#' Check if Expression is Log-Log Concave
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_log_log_concave <- new_generic("is_log_log_concave", "x")
#' Check if Expression is Log-Log Affine
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_log_log_affine <- new_generic("is_log_log_affine", "x")
#' Get the Canonical Form
#' @param x A canonicalizable object.
#' @param ... Not used.
#' @returns List with (expression, constraints).
#' @keywords internal
canonical_form <- new_generic("canonical_form", "x")
#' Shallow Copy of an Expression Tree Node
#' @param x A canonicalizable object.
#' @param args Optional replacement args.
#' @param id_objects Optional identity map for deduplication.
#' @returns A copy of the object.
#' @keywords internal
expr_copy <- new_generic("expr_copy", "x",
function(x, args = NULL, id_objects = NULL) S7_dispatch())
#' Deep Copy of an Expression Tree
#' @param x A canonicalizable object.
#' @param id_objects Optional identity map for deduplication.
#' @returns A deep copy of the entire expression tree.
#' @keywords internal
tree_copy <- new_generic("tree_copy", "x",
function(x, id_objects = NULL) S7_dispatch())
# -- Quadratic / piecewise-linear analysis --------------------------
## CVXPY SOURCE: expression.py lines 448-484
## These are needed by the QP solver path (OSQP) for problem classification.
#' Check if an Expression is Quadratic
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_quadratic <- new_generic("is_quadratic", "x")
#' Check if Expression Has a Quadratic Term
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
has_quadratic_term <- new_generic("has_quadratic_term", "x")
#' Check if Expression is Piecewise Linear
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_pwl <- new_generic("is_pwl", "x")
#' Check if Expression is Quadratic or Piecewise Affine
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_qpwa <- new_generic("is_qpwa", "x")
# -- Strictly positive check ---------------------------------------
## CVXPY SOURCE: leaf.py::is_pos -- checks attributes['pos'] on Leaf,
## checks actual value > 0 on Constant.
#' Check if Expression is Strictly Positive
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_pos <- new_generic("is_pos", "x")
# -- Domain hook ---------------------------------------------------
#' Get Atom-Specific Domain Constraints
#' @param x An atom object.
#' @param ... Not used.
#' @returns List of Constraint objects.
#' @keywords internal
atom_domain <- new_generic("atom_domain", "x")
# -- Constraint generics --------------------------------------------
#' Get the Residual of a Constraint
#'
#' Returns the residual of a constraint, measuring how much the constraint
#' is violated or satisfied.
#'
#' @param x A constraint object.
#' @param ... Not used.
#' @returns Numeric array, or \code{NULL} if expression has no value.
#' @export
residual <- new_generic("residual", "x")
#' Get the Violation of a Constraint
#'
#' Returns the scalar violation (distance to feasibility) of a constraint.
#'
#' @param x A constraint object.
#' @param ... Not used.
#' @returns Numeric scalar.
#' @export
violation <- new_generic("violation", "x")
# -- Cone constraint generics --------------------------------------
## CVXPY SOURCE: constraints/cones.py, second_order.py, psd.py, etc.
#' Get the Number of Cones in a Constraint
#' @param x A cone constraint object.
#' @param ... Not used.
#' @returns Integer.
#' @keywords internal
num_cones <- new_generic("num_cones", "x")
#' Get the Sizes of Individual Cones
#' @param x A cone constraint object.
#' @param ... Not used.
#' @returns Integer vector of cone sizes.
#' @keywords internal
cone_sizes <- new_generic("cone_sizes", "x")
#' Get the Total Size of a Constraint
#' @param x A constraint object.
#' @param ... Not used.
#' @returns Integer.
#' @keywords internal
constr_size <- new_generic("constr_size", "x")
#' Get the Dual Cone Constraint
#' @param x A cone constraint object.
#' @param ... Optional arguments.
#' @returns A cone constraint representing the dual cone.
#' @keywords internal
dual_cone <- new_generic("dual_cone", "x",
function(x, ...) S7_dispatch())
#' Get the Dual Residual
#' @param x A cone constraint object.
#' @param ... Not used.
#' @returns Numeric residual.
#' @keywords internal
dual_residual <- new_generic("dual_residual", "x")
#' Check if a Constraint is DGP-Compliant
#' @param x A constraint object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_dgp <- new_generic("is_dgp", "x")
#' Save Dual Variable Values from Solver Output
#' @param x A constraint object.
#' @param val The dual value from the solver.
#' @returns Invisible constraint (side effect: sets dual variable values).
#' @keywords internal
save_dual_value <- new_generic("save_dual_value", "x",
function(x, val) S7_dispatch())
# -- Atom validation -------------------------------------------------
#' Validate Arguments to an Atom
#' @param x An atom object.
#' @param ... Not used.
#' @returns Invisible \code{NULL} (or error if invalid).
#' @keywords internal
validate_arguments <- new_generic("validate_arguments", "x")
# -- Atom hooks --------------------------------------------------------
#' Infer Shape from Arguments
#' @param x An atom object.
#' @param ... Not used.
#' @returns Integer vector of shape dimensions.
#' @keywords internal
shape_from_args <- new_generic("shape_from_args", "x")
#' Infer Sign from Arguments
#' @param x An atom object.
#' @param ... Not used.
#' @returns Character string: sign constant.
#' @keywords internal
sign_from_args <- new_generic("sign_from_args", "x")
#' Check if Atom is Convex
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_atom_convex <- new_generic("is_atom_convex", "x")
#' Check if Atom is Concave
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_atom_concave <- new_generic("is_atom_concave", "x")
#' Check if Atom is Log-Log Convex
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_atom_log_log_convex <- new_generic("is_atom_log_log_convex", "x")
#' Check if Atom is Log-Log Concave
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_atom_log_log_concave <- new_generic("is_atom_log_log_concave", "x")
#' Check if Atom is Increasing in an Argument
#' @param x An atom object.
#' @param idx Integer: argument index (1-based, R convention).
#' @param ... Additional arguments.
#' @returns Logical scalar.
#' @keywords internal
is_incr <- new_generic("is_incr", "x",
function(x, idx, ...) S7_dispatch())
#' Check if Atom is Decreasing in an Argument
#' @param x An atom object.
#' @param idx Integer: argument index (1-based, R convention).
#' @param ... Additional arguments.
#' @returns Logical scalar.
#' @keywords internal
is_decr <- new_generic("is_decr", "x",
function(x, idx, ...) S7_dispatch())
#' Get the Graph Implementation of an Atom
#' @param x An atom object.
#' @param arg_objs List of canonicalized argument LinOps.
#' @param shape Integer vector: target shape.
#' @param data Optional atom-specific data.
#' @param ... Additional arguments.
#' @returns List with (expression, constraints).
#' @keywords internal
graph_implementation <- new_generic("graph_implementation", "x",
function(x, arg_objs, shape, data = NULL, ...) S7_dispatch())
#' Compute the Numeric Value of an Atom
#' @param x An atom object.
#' @param values List of numeric values of the atom's arguments.
#' @param ... Additional arguments.
#' @returns Numeric value.
#' @keywords internal
numeric_value <- new_generic("numeric_value", "x",
function(x, values, ...) S7_dispatch())
# -- DQCP curvature queries ---------------------------------------
## CVXPY SOURCE: expression.py lines 411-429, atom.py lines 288-335
#' Check if Expression is Quasiconvex
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_quasiconvex <- new_generic("is_quasiconvex", "x")
#' Check if Expression is Quasiconcave
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_quasiconcave <- new_generic("is_quasiconcave", "x")
#' Check if Expression is Quasilinear
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_quasilinear <- new_generic("is_quasilinear", "x")
#' Check if Expression is DQCP-Compliant
#'
#' Tests whether an expression follows the Disciplined Quasiconvex
#' Programming (DQCP) rules.
#'
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_dqcp <- new_generic("is_dqcp", "x")
#' Check if Atom is Quasiconvex
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_atom_quasiconvex <- new_generic("is_atom_quasiconvex", "x")
#' Check if Atom is Quasiconcave
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @keywords internal
is_atom_quasiconcave <- new_generic("is_atom_quasiconcave", "x")
# -- DNLP curvature queries (CVXPY 1.9.0) -------------------------
## CVXPY SOURCE: expression.py:349-405, atom.py:191-298, leaf.py:267-273.
## The disciplined-nonlinear-programming (DNLP) predicate cluster: an
## expression is DNLP if it is "smooth representable" -- convex (or concave)
## after linearizing every smooth subexpression. is_smooth / is_atom_smooth /
## is_linearizable_* are the supporting predicates; is_dnlp is the user-facing
## one (parallels is_dcp / is_dqcp / is_dgp).
#' Check if an Expression is Smooth
#'
#' Smooth = constant, or both linearizable-convex and linearizable-concave.
#' Mirrors CVXPY's \code{Expression.is_smooth()}.
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @seealso \code{\link{is_dnlp}}, \code{\link{is_linearizable_convex}},
#' \code{\link{is_linearizable_concave}}
#' @export
is_smooth <- new_generic("is_smooth", "x")
#' Check if an Atom is Smooth
#'
#' Atom-level hook (default FALSE); smooth atoms (e.g. trig/hyperbolic)
#' override this to TRUE. Mirrors CVXPY's \code{Atom.is_atom_smooth()}.
#' @param x An atom object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @seealso \code{\link{is_smooth}}
#' @export
is_atom_smooth <- new_generic("is_atom_smooth", "x")
#' Check if an Expression is Linearizable-Convex
#'
#' Convex after linearizing all smooth subexpressions (DNLP composition rule).
#' Mirrors CVXPY's \code{Expression.is_linearizable_convex()}.
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @seealso \code{\link{is_dnlp}}, \code{\link{is_linearizable_concave}}
#' @export
is_linearizable_convex <- new_generic("is_linearizable_convex", "x")
#' Check if an Expression is Linearizable-Concave
#'
#' Concave after linearizing all smooth subexpressions (DNLP composition rule).
#' Mirrors CVXPY's \code{Expression.is_linearizable_concave()}.
#' @param x An expression object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @seealso \code{\link{is_dnlp}}, \code{\link{is_linearizable_convex}}
#' @export
is_linearizable_concave <- new_generic("is_linearizable_concave", "x")
#' Check if an Expression or Problem is DNLP-Compliant
#'
#' Tests whether the object follows the Disciplined Nonlinear Programming
#' (DNLP) rules: smooth representable, i.e. linearizable-convex or
#' linearizable-concave.
#'
#' @param x An expression, objective, constraint, or \code{\link{Problem}}.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_dnlp <- new_generic("is_dnlp", "x")
# -- Problem classification ---------------------------------------
#' Check if a Problem is a Quadratic Program
#'
#' @param x A \code{\link{Problem}} object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_qp <- new_generic("is_qp", "x")
#' Check if a Problem is a Linear Program
#'
#' @param x A \code{\link{Problem}} object.
#' @param ... Not used.
#' @returns Logical scalar.
#' @export
is_lp <- new_generic("is_lp", "x")
# -- Reduction interface ------------------------------------------
#' Check if a Reduction Accepts a Problem
#' @param x A Reduction object.
#' @param problem A Problem object.
#' @param ... Additional arguments.
#' @returns Logical scalar.
#' @keywords internal
reduction_accepts <- new_generic("reduction_accepts", "x",
function(x, problem, ...) S7_dispatch())
#' Apply a Reduction to a Problem
#' @param x A Reduction object.
#' @param problem A Problem object.
#' @param ... Additional arguments.
#' @returns List with (new_problem, inverse_data).
#' @keywords internal
reduction_apply <- new_generic("reduction_apply", "x",
function(x, problem, ...) S7_dispatch())
#' Invert a Solution through a Reduction
#' @param x A Reduction object.
#' @param solution A solution object.
#' @param inverse_data Inverse data from apply.
#' @param ... Additional arguments.
#' @returns A solution to the original problem.
#' @keywords internal
reduction_invert <- new_generic("reduction_invert", "x",
function(x, solution, inverse_data, ...) S7_dispatch())
#' Update Parameters for DPP Fast Path
#' @param x A Reduction object.
#' @param problem A Problem object.
#' @param ... Additional arguments.
#' @returns NULL (called for side effects).
#' @keywords internal
update_parameters <- new_generic("update_parameters", "x",
function(x, problem, ...) S7_dispatch())
# -- Solver interface -----------------------------------------------
#' Get Solver Name
#' @param x A Solver object.
#' @param ... Not used.
#' @returns Character string with solver name.
#' @keywords internal
solver_name <- new_generic("solver_name", "x")
#' Does Solver Support Quadratic Objectives?
#'
#' CVXPY v1.8.2: controls whether the conic path keeps the quadratic
#' objective as a P matrix or decomposes it into cones.
#' @param x A solver object.
#' @returns Logical scalar.
#' @keywords internal
supports_quad_obj <- new_generic("supports_quad_obj", "x")
#' Solve via Raw Data
#'
#' Calls the solver on pre-compiled problem data (step 2 of the
#' decomposed solve pipeline). Dispatches on \code{x}: when \code{x}
#' is a \code{SolvingChain}, delegates to the terminal solver with
#' proper cache management.
#'
#' @param x A \code{SolvingChain} (preferred) or \code{Solver} object.
#' @param data Named list of solver data from \code{\link{problem_data}()}.
#' @param warm_start Logical; use warm-start if supported.
#' @param verbose Logical; print solver output.
#' @param solver_opts Named list of solver-specific options.
#' @param ... Additional arguments forwarded to the method (e.g.
#' \code{problem} for the \code{SolvingChain} method, \code{solver_cache}
#' for the \code{Solver} method).
#' @returns Solver-specific result (a named list).
#'
#' @seealso \code{\link{problem_data}}, \code{\link{problem_unpack_results}}
#' @export
solve_via_data <- new_generic("solve_via_data", "x",
function(x, data, warm_start = FALSE, verbose = FALSE, solver_opts = list(), ...) S7_dispatch())
#' Get Problem Data for a Solver
#'
#' Returns the problem data that would be passed to a specific solver,
#' along with the reduction chain and inverse data for solution retrieval.
#'
#' @param x A \code{\link{Problem}} object.
#' @param solver Character string naming solver, or \code{NULL} for
#' automatic selection.
#' @param gp Logical; if \code{TRUE}, parse the problem as a geometric program.
#' @param enforce_dpp Logical; if \code{TRUE}, raise an error when a
#' parametrized problem is not DPP instead of compiling it as non-DPP.
#' @param ignore_dpp Logical; if \code{TRUE}, treat a DPP problem as non-DPP
#' (skip the DPP fast path).
#' @param ... Additional solver options.
#' @returns A list with components \code{data}, \code{chain}, and
#' \code{inverse_data}.
#' @export
problem_data <- new_generic("problem_data", "x",
function(x, solver = NULL, gp = FALSE, enforce_dpp = FALSE, ignore_dpp = FALSE, ...)
S7_dispatch())
#' Get Problem Data for a Solver (deprecated)
#'
#' `r lifecycle::badge("deprecated")`
#'
#' Use \code{\link{problem_data}} instead.
#'
#' @param x A \code{\link{Problem}} object.
#' @param solver Character string naming solver, or \code{NULL} for
#' automatic selection.
#' @param gp Logical; if \code{TRUE}, parse the problem as a geometric program.
#' @param enforce_dpp Logical; if \code{TRUE}, raise an error when a
#' parametrized problem is not DPP instead of compiling it as non-DPP.
#' @param ignore_dpp Logical; if \code{TRUE}, treat a DPP problem as non-DPP
#' (skip the DPP fast path).
#' @param ... Additional solver options.
#' @returns A list with components \code{data}, \code{chain}, and
#' \code{inverse_data}.
#' @seealso \code{\link{problem_data}}
#' @export
get_problem_data <- new_generic("get_problem_data", "x",
function(x, solver = NULL, gp = FALSE, enforce_dpp = FALSE, ignore_dpp = FALSE, ...)
S7_dispatch())
Try the CVXR package in your browser
Any scripts or data that you put into this service are public.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.