oxinum-complex — Arbitrary-precision complex numbers for OxiNum

oxinum-complex is the complex-number layer of the OxiNum arbitrary-precision numeric tower. It provides [CBig], a complex value whose real and imaginary parts are each a DBig (decimal arbitrary-precision float re-exported from oxinum-float), together with precision-aware transcendental functions — abs, arg, exp, ln, sqrt, pow — and the full complex trigonometric / hyperbolic family — sin, cos, tan, sinh, cosh, tanh. Every transcendental takes an explicit decimal-precision argument and returns an OxiNumResult, surfacing domain and precision problems as recoverable errors rather than panics. The principal branches match IEEE-754 / num-complex conventions (sqrt(-1) = +i, ln imaginary part in (-π, π], 0^0 = 1).

A parallel ground-up, Pure Rust binary-base complex lives in the native module — a [BigComplex] built directly on oxinum-float's native binary BigFloat with explicit rounding-mode control. The crate is #![forbid(unsafe_code)] and free of GMP/MPFR or other C/C++/Fortran dependencies.

Note on Hash, Eq, and Ord. The complex field has no order compatible with its ring structure, so no Ord / PartialOrd is provided — sort on a derived scalar (magnitude or the lexicographic (re, im) pair) instead. CBig is built from DBig, which deliberately omits Hash/Eq (distinct representations can compare equal across precisions, mirroring f32/f64), so CBig inherits the same constraints. A component-wise PartialEq is provided.

Installation

[dependencies]
oxinum-complex = "0.1.0"

# Optional capabilities:
oxinum-complex = { version = "0.1.0", features = ["serde", "num-traits"] }

Quick Start

use oxinum_complex::CBig;
use oxinum_float::compute_pi;

// |3 + 4i| = 5  (via the exact squared magnitude, then the real sqrt).
let z = CBig::from((3i64, 4i64));      // integer parts are exact (unlimited precision)
assert_eq!(z.norm_sqr().to_string(), "25");
let m = z.abs(30)?;
assert!(m.to_string().starts_with('5'));

// (1 + i)² = 2i, via the Mul operator.
let one_plus_i = CBig::from_f64(1.0, 1.0)?;
let sq = &one_plus_i * &one_plus_i;
assert_eq!(sq.re().to_string(), "0");
assert_eq!(sq.im().to_string(), "2");

// exp(iπ) ≈ −1  (Euler's identity); build π with oxinum-float.
let i_pi = CBig::from_parts(oxinum_complex::DBig::from(0u32), compute_pi(50));
let e = i_pi.exp(40)?;
let (re, im) = e.to_f64_parts();
assert!((re + 1.0).abs() < 1e-12 && im.abs() < 1e-12);

// sqrt(2i) = 1 + i  (principal branch).
let two_i = CBig::from((0i64, 2i64));
let r = two_i.sqrt(40)?;
let (rre, rim) = r.to_f64_parts();
assert!((rre - 1.0).abs() < 1e-12 && (rim - 1.0).abs() < 1e-12);

// Transcendentals return Results for domain errors.
assert!(CBig::zero().ln(30).is_err()); // ln(0) is undefined
# Ok::<(), oxinum_complex::OxiNumError>(())

API Overview

Type aliases & core re-exports

Constructors

Accessors & algebra (no precision argument)

Operators

Add, Sub, Mul, Div, and Neg are implemented for all four owned/borrowed combinations, with the matching AddAssign / SubAssign / MulAssign / DivAssign. PartialEq (component-wise), Default (= zero), and Display ("a + bi" / "a - bi") are also provided.

Transcendental functions

Each takes a precision: usize of significant decimal digits and returns an OxiNumResult. Internals run at a guard precision (precision + 10) to absorb rounding noise.

Trigonometric & hyperbolic functions

Each takes a precision: usize and returns OxiNumResult<CBig>, assembled component-wise from the real sin/cos/sinh/cosh of oxinum-float.

native module

A ground-up Pure Rust binary-base (b = 2) complex, built on oxinum_float::native::BigFloat, intentionally not re-exported at the crate root (to avoid clashing with the decimal-backed CBig). Access it as oxinum_complex::native::*.

The numeric API mirrors CBig (from_parts/from_real/from_imag/zero/one/i/from_f64, re/im/real/imag/into_parts/conj/norm_sqr/is_zero/to_f64_parts, plus abs/arg/exp/ln/sqrt/pow and sin/cos/tan/sinh/cosh/tanh), with these differences:

• numeric methods take an explicit (prec: u32, mode: RoundingMode) pair;
• the hyperbolics are derived internally from exp (the native BigFloat exposes no hyperbolic primitives);
• division is exposed only as checked_div(&self, &BigComplex, prec, mode) -> OxiNumResult<BigComplex> — there is no Div operator and no Default, since both would need a baked-in precision / rounding mode. Add/Sub/Mul/Neg and the *Assign traits are provided as usual.

use oxinum_complex::native::{BigComplex, RoundingMode};

// sqrt(2i) = 1 + i at 80 bits, banker's rounding.
let two_i = BigComplex::from_f64(0.0, 2.0, 80)?;
let r = two_i.sqrt(80, RoundingMode::HalfEven)?;
assert!((r.re().to_f64() - 1.0).abs() < 1e-12);
assert!((r.im().to_f64() - 1.0).abs() < 1e-12);
# Ok::<(), oxinum_complex::OxiNumError>(())

Feature Flags

Cross-references

• oxinum-core — shared traits, errors, and RoundingMode.
• oxinum-float — arbitrary-precision floats / decimals (the real-component backbone).
• oxinum-rational — exact rationals.
• oxinum — the façade re-exporting the complex types.

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)