# oxinum-complex TODO
## Status
Complex-number layer of OxiNum, delivered for the 0.1.0 release. Provides `CBig` (decimal-backed complex, each part a `DBig` from `oxinum-float`) and a ground-up native binary `native::BigComplex` (built on `oxinum_float::native::BigFloat`). Both carry full algebra (`Add`/`Sub`/`Mul`/`Div`/`Neg` + `*Assign`, conjugate, squared magnitude), the transcendental set (`abs`, `arg`, `exp`, `ln`, `sqrt`, `pow`) and the complex trigonometric / hyperbolic family (`sin`, `cos`, `tan`, `sinh`, `cosh`, `tanh`) at configurable precision, plus `serde` and `num-traits` (`Zero`/`One`) integration. Principal branches follow IEEE-754 / `num-complex` conventions (`sqrt(-1) = +i`, `ln` imaginary part in `(−π, π]`, `0^0 = 1`). Pure Rust, `#![forbid(unsafe_code)]`, GMP/MPFR-free. ~173 tests (unit + integration + proptest).
## Decimal `CBig` (delivered)
- [x] `CBig` type: `(re, im)` pair of `DBig`; `new`/`from_parts`/`from_real`/`from_imag`/`zero`/`one`/`i`/`from_f64`
- [x] Accessors `re`/`im`/`real`/`imag`/`into_parts`/`conj`/`norm_sqr`/`is_zero`/`is_real`/`is_imaginary`/`to_f64_parts`
- [x] `From<(DBig, DBig)>`, `From<DBig>`, `From<&DBig>`, `From<(i64, i64)>`, `From<i64>` — integer conversions are **exact** (unlimited `DBig` precision, so `norm_sqr` / `pow` keep full precision)
- [x] `Add`/`Sub`/`Mul`/`Div`/`Neg` for all four owned/borrowed variants + `AddAssign`/`SubAssign`/`MulAssign`/`DivAssign`
- [x] `Div` operator panics on a zero divisor (workspace convention); `checked_div` returns `OxiNumError::DivByZero`
- [x] `PartialEq` (component-wise), `Default` (= `zero`), `Display` (`"a + bi"` / `"a - bi"`), `Debug`
- [x] `abs` / `arg` (`atan2`, principal value in `(−π, π]`)
- [x] `exp` = `eᵃ·(cos b + i·sin b)`; `ln` = `½·ln(a²+b²) + i·atan2(b,a)` (`ln(0)` → `Domain`)
- [x] `sqrt` principal branch (`re ≥ 0`, `sqrt(-1) = +i`, radicands clamped non-negative); validated `sqrt(2i) = 1+i`
- [x] `pow` = `exp(w · ln z)` with `0^0 = 1`, `0^w = 0`
- [x] `sin`/`cos`/`tan`/`sinh`/`cosh`/`tanh` assembled component-wise; `tan`/`tanh` via `checked_div` (`DivByZero` at poles)
## Native `BigComplex` (delivered)
- [x] `BigComplex` type: `(re, im)` pair of native binary `BigFloat`; full constructor / accessor surface mirroring `CBig`
- [x] `RoundingMode` re-exported at `oxinum_complex::native::RoundingMode`
- [x] `Add`/`Sub`/`Mul`/`Neg` (four variants) + `*Assign`; `PartialEq` component-wise
- [x] `checked_div(&self, &BigComplex, prec, mode)` — no `Div` operator and no `Default` (both need a baked-in precision/mode)
- [x] `abs`/`arg`/`exp`/`ln`/`sqrt`/`pow` taking `(prec: u32, mode: RoundingMode)`
- [x] `sin`/`cos`/`tan`/`sinh`/`cosh`/`tanh`; hyperbolics derived internally from `exp` (`sinh = (eˣ−e⁻ˣ)/2`, etc.)
- [x] `tanh` real-axis fast path (`b == 0`) routes through the scalar helper to avoid spurious imaginary rounding
## Feature integrations (delivered)
- [x] `serde::Serialize` / `Deserialize` for `CBig` and `BigComplex` (flat `(re, im)` repr) behind `serde`
- [x] `num_traits::{Zero, One}` for `CBig` and `BigComplex` behind `num-traits`; `Num`/`Signed`/`Float` deliberately omitted (complex is unordered / unsigned), documented rather than stubbed
## Testing (delivered)
- [x] Hand-computed algebra: `(1+2i)(3+4i) = −5+10i`, `i² = −1`, `(1+i)² = 2i`, division round-trips
- [x] `checked_div` by zero → `DivByZero`; `Div` operator by zero panics (`#[should_panic]`)
- [x] `norm_sqr` exactness for integer parts incl. `i64::MAX` (regression against precision collapse)
- [x] Euler's identity `exp(iπ) ≈ −1`; `ln(−1) = iπ`; `ln(0)` → `Domain`
- [x] `sqrt(−1) = +i`, `sqrt(2i) = 1+i`, `sqrt(4) = 2`; `pow(i, 2) = −1`, `0^0 = 1`, `0^w = 0`
- [x] `|3+4i| = 5`, `arg(i) = π/2`
- [x] Pythagorean identities `sin²z + cos²z ≈ 1`, `cosh²z − sinh²z ≈ 1`; `tan` matches a known reference value
- [x] `serde` JSON round-trip for `CBig` and `BigComplex`
- [x] proptest coverage (algebra / identities for both `CBig` and `BigComplex`)
- [x] Criterion benchmark (`complex_transcendental`) for the transcendental hot paths
## Future / possible work
- [ ] Inverse complex trig: `asin` / `acos` / `atan` (and `asinh` / `acosh` / `atanh`)
- [ ] Polar helpers: `from_polar(r, θ)` and `to_polar() -> (DBig, DBig)` (magnitude + argument)
- [ ] Additional `num-complex`-style interop (e.g. an optional `num_complex::Complex<T>` bridge / `Complex` trait surface)
- [ ] Scalar mixed-mode ops (`CBig × DBig`, `CBig × i64`) without first wrapping the scalar
- [ ] More conversions (`From<num_complex::Complex64>`, `TryInto<(f64, f64)>` with overflow detection)
- [ ] Native `BigComplex` `serde`/`num-traits` parity audit and expanded proptest coverage (more random magnitudes, cross-validation of `CBig` vs `BigComplex`)
- [ ] `powi` / `powf` integer / real fast paths avoiding the full `exp(w·ln z)` round trip
- [ ] Verify compatibility with SciRS2 `ArbitraryComplex` consumer requirements