R/132_constraints_zero.R

In CVXR: Disciplined Convex Optimization

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

## CVXPY SOURCE: constraints/zero.py
## Zero (x == 0) and Equality (x == y) constraints
##
## CVXPY 1.9 parity notes:
##  - DNLP predicates mirror zero.py:61 and zero.py:140: Zero and Equality are
##    DNLP exactly when their constrained expression is smooth-representable.

# ===================================================================
# Zero -- constraint of the form x == 0
# ===================================================================

#' Create a Zero Constraint
#'
#' Constrains an expression to equal zero elementwise: \eqn{x = 0}.
#'
#' @param expr A CVXR expression.
#' @param constr_id Optional integer constraint ID.
#' @returns A \code{Zero} constraint object.
#' @seealso \code{\link{Equality}}, \code{\link{NonPos}}, \code{\link{NonNeg}}
#' @export
Zero <- new_class("Zero", parent = Constraint, package = "CVXR",
  constructor = function(expr, constr_id = NULL) {
    if (FALSE) new_object(S7_object())  ## S7 static-check guard
    expr <- as_expr(expr)
    if (is.null(constr_id)) constr_id <- next_expr_id()
    shape <- expr@shape
    dvars <- list(Variable(shape))
    .fast_new(Zero, S7_object(),
      id    = as.integer(constr_id),
      .cache = new.env(parent = emptyenv()),
      args  = list(expr),
      dual_variables = dvars,
      shape = shape,
      .label = ""
    )
  }
)

# -- expr_name ----------------------------------------------------
## CVXPY SOURCE: zero.py line 51-52

method(expr_name, Zero) <- function(x) {
  sprintf("%s == 0", expr_name(x@args[[1L]]))
}

# -- is_dcp -------------------------------------------------------
## CVXPY SOURCE: zero.py lines 54-59
## A zero constraint is DCP if its argument is affine.

method(is_dcp, Zero) <- function(x) is_affine(x@args[[1L]])

# -- is_dqcp ------------------------------------------------------
## CVXPY SOURCE: zero.py lines 68-69

method(is_dqcp, Zero) <- function(x) is_dcp(x)

# -- is_dnlp ------------------------------------------------------
## A zero constraint is DNLP if its argument is smooth representable.
## CVXPY SOURCE: zero.py lines 61-63
method(is_dnlp, Zero) <- function(x) is_smooth(x@args[[1L]])

# -- residual -----------------------------------------------------
## CVXPY SOURCE: zero.py lines 71-81
## Returns abs(expr.value) or NULL.

## is_dgp: zero constraint cannot be DGP
## CVXPY SOURCE: zero.py lines 65-66
method(is_dgp, Zero) <- function(x) FALSE

method(residual, Zero) <- function(x) {
  val <- value(x@args[[1L]])
  if (is.null(val)) return(NULL)
  abs(val)
}


# ===================================================================
# Equality -- constraint of the form x == y
# ===================================================================

#' Create an Equality Constraint
#'
#' Constrains two expressions to be equal elementwise: \eqn{lhs = rhs}.
#' Typically created via the \code{==} operator on CVXR expressions.
#'
#' @param lhs A CVXR expression (left-hand side).
#' @param rhs A CVXR expression (right-hand side).
#' @param constr_id Optional integer constraint ID.
#' @returns An \code{Equality} constraint object.
#' @seealso \code{\link{Zero}}, \code{\link{Inequality}}
#' @export
Equality <- new_class("Equality", parent = Constraint, package = "CVXR",
  properties = list(
    .expr = new_property(class = class_any, default = NULL)
  ),
  constructor = function(lhs, rhs, constr_id = NULL) {
    if (FALSE) new_object(S7_object())  ## S7 static-check guard
    lhs <- as_expr(lhs)
    rhs <- as_expr(rhs)
    expr_diff <- lhs - rhs  ## Uses Phase 2D operator dispatch
    if (is.null(constr_id)) constr_id <- next_expr_id()
    shape <- expr_diff@shape
    ## Dual variables based on expr shape (not args)
    ## CVXPY SOURCE: zero.py lines 113-114
    dvars <- list(Variable(shape))
    .fast_new(Equality, S7_object(),
      id    = as.integer(constr_id),
      .cache = new.env(parent = emptyenv()),
      args  = list(lhs, rhs),
      dual_variables = dvars,
      shape = shape,
      .label = "",
      .expr = expr_diff
    )
  }
)

# -- expr ---------------------------------------------------------
## CVXPY SOURCE: zero.py lines 116-118. Equality's expression is lhs - rhs,
## not args[[1]]; constr_expr() in constraints/constraint.R returns `.expr`
## for this class (no separate method, see the note there).

# -- expr_name ----------------------------------------------------
## CVXPY SOURCE: zero.py line 130-131

method(expr_name, Equality) <- function(x) {
  sprintf("%s == %s", expr_name(x@args[[1L]]), expr_name(x@args[[2L]]))
}

# -- constr_size --------------------------------------------------
## CVXPY SOURCE: zero.py lines 120-128 -- shape and size are those of the
## constrained expression lhs - rhs, not of args[0]; the base method
## (constraint.R, prod(args[[1]]@shape)) answered 1 for `0 == x` (claims
## audit C0308, 1.9.2.9158).  `shape` is already expr_diff@shape.

method(constr_size, Equality) <- function(x) prod(x@shape)

# -- is_dcp -------------------------------------------------------
## CVXPY SOURCE: zero.py lines 133-138
## An equality constraint is DCP if (lhs - rhs) is affine.

method(is_dcp, Equality) <- function(x) is_affine(x@.expr)

# -- is_dqcp ------------------------------------------------------
## CVXPY SOURCE: zero.py lines 152-153

method(is_dqcp, Equality) <- function(x) is_dcp(x)

# -- is_dnlp ------------------------------------------------------
## An equality constraint is DNLP if (lhs - rhs) is smooth representable.
## CVXPY SOURCE: zero.py lines 140-142
method(is_dnlp, Equality) <- function(x) is_smooth(x@.expr)

# -- residual -----------------------------------------------------
## CVXPY SOURCE: zero.py lines 155-165
## Returns abs(expr.value) or NULL where expr = lhs - rhs.

## is_dgp: both sides must be log-log affine
## CVXPY SOURCE: zero.py lines 144-150
method(is_dgp, Equality) <- function(x) {
  is_log_log_affine(x@args[[1L]]) && is_log_log_affine(x@args[[2L]])
}

method(residual, Equality) <- function(x) {
  val <- value(x@.expr)
  if (is.null(val)) return(NULL)
  abs(val)
}

# -- expr_copy: special handling for Equality ---------------------
## Equality(lhs, rhs, constr_id) -- default expr_copy works via
## do.call(Equality, c(list(lhs, rhs), list(id))).
## No override needed.