Roll out complex contract validation

[shinaoka]

Summary

Adds first-class interleaved complex number support (Complex<f32> / Complex<f64>) to CubeCL with centralized contract validation, so backends without positive complex support fail up front rather than through missing lowering paths.

This has been rebased onto current upstream/main; the earlier expm1 prerequisite is already merged through #1301 and is no longer part of this PR's unique diff.

The Complex Contract

Split into three traits:

• ComplexCore: +, -, *, /, unary -, conj, real_val, imag_val
• ComplexCompare: ==, !=
• ComplexMath: abs, exp, log, sin, cos, sqrt, tanh, powf

Explicitly rejected by the validator: ordering comparisons, min / max / clamp, remainder / modulo, bitwise ops, log1p / expm1 / is_nan / is_inf, fma, and scalar ABI shortcuts.

Why Interleaved

For scientific computing, signal processing, and linear algebra workloads, complex numbers need to behave as a single tensor element type, not an ad hoc pair of real tensors. Interleaved ((re, im) contiguous per element) is the right fit because:

• matches num_complex::Complex<f32> / Complex<f64> on the Rust side
• maps naturally to CUDA's cuComplex / cuDoubleComplex ABI
• fits downstream linalg / FFT integrations where complex values are consumed as single elements

Backend Status

• CUDA: positive C32 / C64 ComplexCore + ComplexCompare + ComplexMath via cuComplex.h.
• CPU / WGPU / HIP: validation-only. ComplexUsage capability defaults to the empty set, so unsupported combinations are reported at the frontend rather than through missing codegen. Positive implementations for these backends are intentional follow-up PRs.
• SPIR-V / Metal / HIP dialect lowering: complex element types are rejected explicitly where positive lowering is not implemented.

Included Regression Fix

This also fixes a pre-existing cubecl-macros return-position regression where Block::to_tokens bypassed the Expand machinery when the return position was comptime-foldable to a constant. Coverage is kernel_if_literal_u32 in runtime_tests/branch.rs, kept independent from complex types.

Out of Scope

• Positive CPU / WGPU / HIP complex implementations
• SPIR-V complex lowering
• Vector<Complex<T>, N> and related vectorized complex paths
• Dynamic complex scalar ABI
• fma on complex

Validation

Locally verified with:

• cargo +stable fmt --all --check
• cargo +stable check --tests -p cubecl-core -p cubecl-cuda -p cubecl-cpu -p cubecl-wgpu -p cubecl-hip
• cargo +stable xtask check format
• cargo +stable xtask check lint
• cargo +stable xtask check typos
• cargo +stable test -p cubecl-cpu complex_validation -- --nocapture
• cargo +stable test -p cubecl-wgpu complex_validation -- --nocapture
• cargo +stable test -p cubecl-cuda complex_ -- --nocapture

Attempted but blocked by local HIP link environment:

• cargo +stable test -p cubecl-hip complex_validation -- --nocapture
• Failure was unresolved HIP runtime symbols such as hipStreamWaitEvent, hipEventDestroy, and hiprtcCreateProgram.

[skewballfox]

@shinaoka could you merge the changes from main?

[skewballfox]

@shinaoka could you rebase on main again. #1369 was merged this morning which should make it possible to run cargo xtask validate was trying to run some of the test locally but that was a blocker last friday

[shinaoka]

OK, I will rebase this PR on origin/main once PR #1301 is merged.

[shinaoka]

Done!

[shinaoka]

We are dogfooding the complex-number feature with

• https://github.com/tensor4all/tenferro-rs
• https://github.com/tensor4all/tensor4all-rs

[shinaoka]

@skewballfox

How can I help you?

[skewballfox]

I'm not a reviewer, I was just going to test it locally since CI wasn't running. That being said, I requested a review on the discord. Should be getting a review pass in the next couple of days, the devs/maintainers have a lot going on right now afk.