R/122_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

# ===================================================================
# 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) {
    expr <- as_expr(expr)
    if (is.null(constr_id)) constr_id <- next_expr_id()
    shape <- expr@shape
    dvars <- list(Variable(shape))
    new_object(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 64-65

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

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

## is_dgp: zero constraint cannot be DGP
## CVXPY SOURCE: zero.py lines 61-62
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) {
    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 109-110
    dvars <- list(Variable(shape))
    new_object(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
    )
  }
)

# -- constr_expr override -----------------------------------------
## Equality's expression is lhs - rhs, not args[[1]].

# -- expr_name ----------------------------------------------------
## CVXPY SOURCE: zero.py line 126-127

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

# -- is_dcp -------------------------------------------------------
## CVXPY SOURCE: zero.py lines 129-134
## 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 144-145

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

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

## is_dgp: both sides must be log-log affine
## CVXPY SOURCE: zero.py lines 136-142
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.