Update

docs/make.jl

@@ -107,6 +107,7 @@ Documenter.makedocs(
         "Manual" => [
             "manual/types.md",
             "manual/operations.md",
+            "manual/atoms.md",
             "Complex-domain Optimization" => "manual/complex-domain_optimization.md",
             "manual/solvers.md",
             "manual/advanced.md",
@@ -116,7 +117,6 @@ Documenter.makedocs(
             "developer/contributing.md",
             "developer/credits.md",
         ],
-        "atoms.md",
         "reference.md",
         "release_notes.md",
     ],

docs/src/atoms.md → docs/src/manual/atoms.md

@@ -1,5 +1,9 @@
 # Atoms
 
+Convex.jl supports the following functions. These functions may be composed
+according to the [DCP](http://dcp.stanford.edu) composition rules to form new
+convex, concave, or affine expressions.
+
 ## `+`
 ```@docs
 Base.:+(::Convex.AbstractExpr, ::Convex.AbstractExpr)
@@ -71,6 +75,16 @@ Convex.geomean(::Convex.AbstractExpr...)
 Convex.hinge_loss(::Convex.AbstractExpr)
 ```
 
+## `huber`
+```@docs
+Convex.huber(::Convex.AbstractExpr, ::Real)
+```
+
+## `imag`
+```@docs
+Base.imag(::Convex.AbstractExpr)
+```
+
 ## `log`
 ```@docs
 Base.log(::Convex.AbstractExpr)
@@ -86,6 +100,11 @@ Convex.logdet(::Convex.AbstractExpr)
 Convex.logisticloss(::Convex.AbstractExpr)
 ```
 
+## `log_perspective`
+```@docs
+Convex.log_perspective(::Convex.AbstractExpr, ::Convex.AbstractExpr)
+```
+
 ## `logsumexp`
 ```@docs
 Convex.logsumexp(::Convex.AbstractExpr)
@@ -126,6 +145,16 @@ Convex.norm2(::Convex.AbstractExpr)
 Convex.pos(::Convex.AbstractExpr)
 ```
 
+## `real`
+```@docs
+Base.real(::Convex.AbstractExpr)
+```
+
+## `relative_entropy`
+```@docs
+Convex.relative_entropy(::Convex.AbstractExpr, ::Convex.AbstractExpr)
+```
+
 ## `rootdet`
 ```@docs
 Convex.rootdet(::Convex.AbstractExpr)

src/atoms/HuberAtom.jl

@@ -48,5 +48,3 @@ function new_conic_form!(context::Context, x::HuberAtom)
     add_constraint!(context, c == s + n)
     return conic_form!(context, square(s) + 2 * x.M * abs(n))
 end
-
-huber(x::AbstractExpr, M::Real = 1.0) = HuberAtom(x, M)

src/atoms/ImaginaryAtom.jl

@@ -24,9 +24,3 @@ function new_conic_form!(context::Context{T}, x::ImaginaryAtom) where {T}
     obj = conic_form!(context, only(AbstractTrees.children(x)))
     return operate(imag, T, sign(x), obj)
 end
-
-Base.imag(x::AbstractExpr) = ImaginaryAtom(x)
-
-Base.imag(x::ComplexConstant) = x.imag_constant
-
-Base.imag(x::Constant) = Constant(zero(x.value))

src/atoms/RealAtom.jl

@@ -29,9 +29,3 @@ function new_conic_form!(context::Context{T}, x::RealAtom) where {T}
     obj = conic_form!(context, only(AbstractTrees.children(x)))
     return operate(real, T, sign(x), obj)
 end
-
-Base.real(x::AbstractExpr) = RealAtom(x)
-
-Base.real(x::ComplexConstant) = x.real_constant
-
-Base.real(x::Constant) = x

src/atoms/RelativeEntropyAtom.jl

@@ -49,8 +49,3 @@ function new_conic_form!(context::Context{T}, e::RelativeEntropyAtom) where {T}
     add_constraint!(context, GenericConstraint{MOI.RelativeEntropyCone}(f))
     return conic_form!(context, u)
 end
-
-relative_entropy(x::AbstractExpr, y::AbstractExpr) = RelativeEntropyAtom(x, y)
-
-# y*log(x/y)
-log_perspective(x::AbstractExpr, y::AbstractExpr) = -relative_entropy(y, x)

src/supported_operations.jl

@@ -498,6 +498,76 @@ julia> size(atom)
 """
 hinge_loss(x::AbstractExpr) = pos(1 - x)
 
+"""
+    huber(x::AbstractExpr, M::Real = 1.0)
+
+The epigraph of the Huber loss function:
+\$\\begin{cases}x^2 & |x| \\le M\\2M|x| - M^2 & otherwise\\end{cases}\$.
+where \$M \\ge 1\$.
+
+## Examples
+
+Applies to a single expression:
+
+```jldoctest; filter=r"id: [0-9]+…[0-9]+"
+julia> x = Variable();
+
+julia> huber(x, 2.5)
+huber (convex; positive)
+└─ real variable (id: 973…369)
+```
+
+And element-wise to a matrix of expressions:
+
+```jldoctest; filter=r"id: [0-9]+…[0-9]+"
+julia> x = Variable(3);
+
+julia> atom = huber(x)
+huber (convex; positive)
+└─ 3-element real variable (id: 896…728)
+
+julia> size(atom)
+(3, 1)
+```
+"""
+huber(x::AbstractExpr, M::Real = 1.0) = HuberAtom(x, M)
+
+"""
+    Base.imag(x::Convex.AbstractExpr)
+
+Return the imaginary component of `x`.
+
+## Examples
+
+Applies to a single expression:
+
+```jldoctest; filter=r"id: [0-9]+…[0-9]+"
+julia> x = ComplexVariable();
+
+julia> imag(x)
+imag (affine; real)
+└─ complex variable (id: 407…692)
+```
+
+And element-wise to a matrix of expressions:
+
+```jldoctest; filter=r"id: [0-9]+…[0-9]+"
+julia> x = ComplexVariable(3);
+
+julia> atom = imag(x)
+imag (affine; real)
+└─ 3-element complex variable (id: 435…057)
+
+julia> size(atom)
+(3, 1)
+```
+"""
+Base.imag(x::AbstractExpr) = ImaginaryAtom(x)
+
+Base.imag(x::ComplexConstant) = x.imag_constant
+
+Base.imag(x::Constant) = Constant(zero(x.value))
+
 """
     Base.log(x::Convex.AbstractExpr)
 
@@ -530,6 +600,47 @@ julia> size(atom)
 """
 Base.log(x::AbstractExpr) = LogAtom(x)
 
+"""
+    log_perspective(x::Convex.AbstractExpr, y::Convex.AbstractExpr)
+
+The hypograph the perspective of of the log function:
+\$\\sum y_i*\\log \\frac{x_i}{y_i}\$.
+
+## Examples
+
+Applies to a single expression:
+
+```jldoctest; filter=r"id: [0-9]+…[0-9]+"
+julia> x = Variable();
+
+julia> y = Variable();
+
+julia> log_perspective(x, y)
+Convex.NegateAtom (concave; real)
+└─ relative_entropy (convex; real)
+   ├─ real variable (id: 136…971)
+   └─ real variable (id: 131…344)
+```
+
+And to a matrix of expressions:
+
+```jldoctest; filter=r"id: [0-9]+…[0-9]+"
+julia> x = Variable(3);
+
+julia> y = Variable(3);
+
+julia> atom = log_perspective(x, y)
+Convex.NegateAtom (concave; real)
+└─ relative_entropy (convex; real)
+   ├─ 3-element real variable (id: 854…248)
+   └─ 3-element real variable (id: 111…174)
+
+julia> size(atom)
+(1, 1)
+```
+"""
+log_perspective(x::AbstractExpr, y::AbstractExpr) = -relative_entropy(y, x)
+
 """
     LinearAlgebra.logdet(X::Convex.AbstractExpr)
 
@@ -871,6 +982,81 @@ julia> size(atom)
 """
 pos(x::AbstractExpr) = max(x, 0)
 
+"""
+    Base.real(x::Convex.AbstractExpr)
+
+Return the real component of `x`.
+
+## Examples
+
+Applies to a single expression:
+
+```jldoctest; filter=r"id: [0-9]+…[0-9]+"
+julia> x = ComplexVariable();
+
+julia> real(x)
+real (affine; real)
+└─ complex variable (id: 407…692)
+```
+
+And element-wise to a matrix of expressions:
+
+```jldoctest; filter=r"id: [0-9]+…[0-9]+"
+julia> x = ComplexVariable(3);
+
+julia> atom = real(x)
+real (affine; real)
+└─ 3-element complex variable (id: 435…057)
+
+julia> size(atom)
+(3, 1)
+```
+"""
+Base.real(x::AbstractExpr) = RealAtom(x)
+
+Base.real(x::ComplexConstant) = x.real_constant
+
+Base.real(x::Constant) = x
+
+"""
+    relative_entropy(x::Convex.AbstractExpr, y::Convex.AbstractExpr)
+
+The epigraph of \$\\sum y_i*\\log \\frac{x_i}{y_i}\$.
+
+## Examples
+
+Applies to a single expression:
+
+```jldoctest; filter=r"id: [0-9]+…[0-9]+"
+julia> x = Variable();
+
+julia> y = Variable();
+
+julia> relative_entropy(x, y)
+relative_entropy (convex; real)
+├─ real variable (id: 124…372)
+└─ real variable (id: 409…346)
+```
+
+And element-wise to a matrix of expressions:
+
+```jldoctest; filter=r"id: [0-9]+…[0-9]+"
+julia> x = Variable(3);
+
+julia> y = Variable(3);
+
+julia> atom = relative_entropy(x, y)
+julia> atom = relative_entropy(x, y)
+relative_entropy (convex; real)
+├─ 3-element real variable (id: 906…671)
+└─ 3-element real variable (id: 118…912)
+
+julia> size(atom)
+(1, 1)
+```
+"""
+relative_entropy(x::AbstractExpr, y::AbstractExpr) = RelativeEntropyAtom(x, y)
+
 """
     Convex.rootdet(X::Convex.AbstractExpr)