fold conj, real, imag on the symbolic imaginary unit

Add three `@match` arms in `Base.real`, `Base.conj`, `Base.imag` for
`BasicSymbolic` that match `Sym(:im; type = Number)` structurally and
fold to `0`, `-im`, and `1` respectively.

`Symbolics.IM` is defined as a `Sym{VartypeT}(:im; type = Number)` and
used as a stand-in for `1im` to keep expressions inside `BasicSymbolic{<:Real}`
algebra (where multiplying by a Julia `Complex` literal would otherwise
materialise an opaque `complex(re, im)` `Term`). Until now those three
operations on `IM` produced opaque `conj(im)` / `real(im)` / `imag(im)`
wrappers that `simplify` could not reduce, so downstream code that
algebraically conjugates `IM`-bearing expressions (e.g. SQA's
`qadjoint` / `inner_adjoint`) had to special-case `IM` themselves.

Matching is structural (name + symtype) rather than by identity, so no
new dependency on Symbolics is introduced. A same-named sym with a
non-`Number` symtype is left alone (test case).

Author: oameye

src/methods.jl

@@ -479,6 +479,9 @@ function Base.real(s::BasicSymbolic{T}) where {T}
     @match s begin
         BSImpl.Const(; val) => Const{T}(real(val))
         BSImpl.Term(; f, args) && if f === complex && length(args) == 2 end => args[1]
+        # The symbolic imaginary unit (`Symbolics.IM`) is `Sym{T}(:im; type = Number)`.
+        # `real(im) == 0`. Matching structurally avoids a Symbolics-side dependency.
+        BSImpl.Sym(; name) && if name === :im && symtype(s) === Number end => zero_of_vartype(T)
         _ => Term{T}(real, ArgsT{T}((s,)); type = Real)
     end
 end
@@ -490,6 +493,10 @@ function Base.conj(s::BasicSymbolic{T}) where {T}
         BSImpl.Term(; f, args, type, shape) && if f === complex && length(args) == 2 end => begin
             BSImpl.Term{T}(f, ArgsT{T}(args[1], -args[2]); type, shape)
         end
+        # `conj(im) = -im`. Lets `simplify` and the downstream `qadjoint` /
+        # `inner_adjoint` helpers (in SecondQuantizedAlgebra.jl) fold cleanly
+        # through expressions that use `Symbolics.IM` to avoid `Complex{Num}`.
+        BSImpl.Sym(; name) && if name === :im && symtype(s) === Number end => -s
         _ => Term{T}(conj, ArgsT{T}((s,)); type = symtype(s), shape = shape(s))
     end
 end
@@ -498,6 +505,8 @@ function Base.imag(s::BasicSymbolic{T}) where {T}
     @match s begin
         BSImpl.Const(; val) => Const{T}(imag(val))
         BSImpl.Term(; f, args) && if f === complex && length(args) == 2 end => args[2]
+        # `imag(im) == 1`.
+        BSImpl.Sym(; name) && if name === :im && symtype(s) === Number end => one_of_vartype(T)
         _ => Term{T}(imag, ArgsT{T}((s,)); type = Real)
     end
 end

test/rulesets.jl

@@ -59,6 +59,19 @@ end
     @test unwrap_const(simplify(Term{SymReal}(zero, [a]))) == 0
     @test unwrap_const(simplify(Term{SymReal}(zero, [b + 1]))) == 0
     @test unwrap_const(simplify(Term{SymReal}(zero, [x + 2]))) == 0
+
+    # Symbolic imaginary unit (matches `Symbolics.IM = Sym(:im; type = Number)`).
+    # Without these fold rules, `conj(im)`/`real(im)`/`imag(im)` stay wrapped
+    # and downstream simplification can never reduce expressions that use
+    # `IM` to avoid `Complex{Num}` materialisation.
+    let IM = SymbolicUtils.Sym{SymReal}(:im; type = Number)
+        @eqtest conj(IM) == -IM
+        @test unwrap_const(real(IM)) == 0
+        @test unwrap_const(imag(IM)) == 1
+        # A same-named sym with a non-Number symtype is unaffected.
+        not_im = SymbolicUtils.Sym{SymReal}(:im; type = Real)
+        @eqtest conj(not_im) == not_im
+    end
 end
 
 @testset "LiteralReal" begin