Struct BigComplex 

pub struct BigComplex { /* private fields */ }

Native arbitrary-precision binary complex number re + im·i.

Both components are BigFloat values. See the module-level documentation for the rationale behind the absence of Hash, Eq, and Ord.

Examples

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

let z = BigComplex::from_f64(3.0, 4.0, 53).expect("finite parts");
// |3 + 4i|^2 = 25.
assert_eq!(z.norm_sqr().to_f64(), 25.0);

Implementations

impl BigComplex

pub fn from_parts(re: BigFloat, im: BigFloat) -> Self

Construct a complex number from its real and imaginary parts.

pub fn new(re: BigFloat, im: BigFloat) -> Self

Construct a complex number from its real and imaginary parts.

Alias of BigComplex::from_parts.

pub fn from_real(re: BigFloat) -> Self

Construct a purely real complex number (im = 0 at re’s precision).

pub fn from_imag(im: BigFloat) -> Self

Construct a purely imaginary complex number (re = 0 at im’s precision).

pub fn zero(prec: u32) -> Self

The additive identity 0 + 0·i at prec bits of precision.

pub fn one(prec: u32, mode: RoundingMode) -> Self

The multiplicative identity 1 + 0·i at prec bits of precision.

pub fn i(prec: u32, mode: RoundingMode) -> Self

The imaginary unit 0 + 1·i at prec bits of precision.

pub fn from_f64(re: f64, im: f64, prec: u32) -> OxiNumResult<Self>

Construct a complex number from a pair of f64 values at prec bits.

Delegates to BigFloat::from_f64 for each component.

Errors

Propagates the OxiNumError returned by BigFloat::from_f64 when a component is NaN or infinite — the native BigFloat rejects those inputs.

Examples

use oxinum_complex::native::BigComplex;
let z = BigComplex::from_f64(1.5, -2.25, 53).expect("finite parts");
assert_eq!(z.re().to_f64(), 1.5);
assert_eq!(z.im().to_f64(), -2.25);

pub fn re(&self) -> &BigFloat

A shared reference to the real part.

pub fn im(&self) -> &BigFloat

A shared reference to the imaginary part.

pub fn real(&self) -> BigFloat

A clone of the real part.

pub fn imag(&self) -> BigFloat

A clone of the imaginary part.

pub fn into_parts(self) -> (BigFloat, BigFloat)

Decompose into the owned (re, im) pair.

pub fn conj(&self) -> Self

The complex conjugate re − im·i.

Examples

use oxinum_complex::native::BigComplex;
let z = BigComplex::from_f64(2.0, 3.0, 53).expect("finite parts");
let c = z.conj();
assert_eq!(c.re().to_f64(), 2.0);
assert_eq!(c.im().to_f64(), -3.0);

pub fn norm_sqr(&self) -> BigFloat

The squared magnitude re² + im² (always real, non-negative).

Examples

use oxinum_complex::native::BigComplex;
let z = BigComplex::from_f64(3.0, 4.0, 53).expect("finite parts");
assert_eq!(z.norm_sqr().to_f64(), 25.0);

pub fn is_zero(&self) -> bool

Returns true if both components are the canonical zero.

impl BigComplex

pub fn checked_div( &self, rhs: &BigComplex, prec: u32, mode: RoundingMode, ) -> OxiNumResult<BigComplex>

Checked complex division self / rhs at prec bits.

This is the public, no-panic division entry point for native complex values (there is deliberately no core::ops::Div impl — see the module docs). The result components are rounded to prec bits with mode.

Errors

Returns OxiNumError::DivByZero if rhs is zero.

Examples

use oxinum_complex::native::{BigComplex, RoundingMode};
// (2 + 0i) / (1 + i) = 1 − i.
let num = BigComplex::from_f64(2.0, 0.0, 80).expect("finite");
let den = BigComplex::from_f64(1.0, 1.0, 80).expect("finite");
let q = num
    .checked_div(&den, 80, RoundingMode::HalfEven)
    .expect("non-zero divisor");
assert!((q.re().to_f64() - 1.0).abs() < 1e-12);
assert!((q.im().to_f64() + 1.0).abs() < 1e-12);

impl BigComplex

pub fn to_f64_parts(&self) -> (f64, f64)

Project to a pair of f64s (re, im) via BigFloat::to_f64.

This is a lossy convenience conversion: each component is rounded to the nearest f64 (and non-finite components map to the corresponding f64::NAN / f64::INFINITY, matching BigFloat::to_f64).

Examples

use oxinum_complex::native::BigComplex;
let z = BigComplex::from_f64(1.5, -2.25, 80).expect("finite");
let (re, im) = z.to_f64_parts();
assert_eq!(re, 1.5);
assert_eq!(im, -2.25);

impl BigComplex

pub fn abs(&self, prec: u32, mode: RoundingMode) -> OxiNumResult<BigFloat>

The magnitude |z| = sqrt(a² + b²) as a real BigFloat at prec bits.

Returns the canonical zero for a zero input (avoiding a sqrt(0) round trip). The squared magnitude is taken from BigComplex::norm_sqr.

Errors

Propagates any error from BigFloat::sqrt (none expected for the non-negative norm_sqr).

Examples

use oxinum_complex::native::{BigComplex, RoundingMode};
let z = BigComplex::from_f64(3.0, 4.0, 80).expect("finite");
let m = z.abs(80, RoundingMode::HalfEven).expect("abs");
assert!((m.to_f64() - 5.0).abs() < 1e-12);

pub fn arg(&self, prec: u32, mode: RoundingMode) -> OxiNumResult<BigFloat>

The argument arg(z) = atan2(b, a) as a real BigFloat at prec bits, the principal value in (−π, π].

Errors

Propagates any error from BigFloat::atan2.

Examples

use oxinum_complex::native::{BigComplex, RoundingMode};
let i = BigComplex::i(80, RoundingMode::HalfEven);
let a = i.arg(80, RoundingMode::HalfEven).expect("arg");
assert!((a.to_f64() - std::f64::consts::FRAC_PI_2).abs() < 1e-12);

pub fn exp(&self, prec: u32, mode: RoundingMode) -> OxiNumResult<BigComplex>

The complex exponential exp(z) = eᵃ·(cos b + i·sin b) at prec bits.

Errors

Propagates errors from BigFloat::exp (e.g. overflow when a is huge) and from the real trig routines.

Examples

use oxinum_complex::native::{BigComplex, RoundingMode};
// exp(iπ) ≈ −1 + 0i  (Euler's identity).
let z = BigComplex::from_f64(0.0, std::f64::consts::PI, 80).expect("finite");
let e = z.exp(80, RoundingMode::HalfEven).expect("exp");
assert!((e.re().to_f64() + 1.0).abs() < 1e-12);
assert!(e.im().to_f64().abs() < 1e-12);

pub fn ln(&self, prec: u32, mode: RoundingMode) -> OxiNumResult<BigComplex>

The principal complex logarithm ln(z) = ½·ln(a² + b²) + i·atan2(b, a) at prec bits.

Errors

• OxiNumError::Domain if z is zero (ln(0) is undefined).
• Propagates errors from BigFloat::ln / BigFloat::atan2.

Examples

use oxinum_complex::native::{BigComplex, RoundingMode};
// ln(−1) ≈ 0 + iπ.
let z = BigComplex::from_f64(-1.0, 0.0, 80).expect("finite");
let l = z.ln(80, RoundingMode::HalfEven).expect("ln");
assert!(l.re().to_f64().abs() < 1e-12);
assert!((l.im().to_f64() - std::f64::consts::PI).abs() < 1e-12);

pub fn sqrt(&self, prec: u32, mode: RoundingMode) -> OxiNumResult<BigComplex>

The principal square root sqrt(z) at prec bits.

Uses re = sqrt((|z| + a)/2), im = sign(b)·sqrt((|z| − a)/2), with the purely-real input handled by an exact axis split and the radicands clamped up to zero before the real sqrt to absorb rounding noise. The branch chosen has re ≥ 0 and matches the IEEE-754 / num-complex principal value.

Errors

Propagates errors from BigFloat::sqrt (none expected: radicands are clamped non-negative).

Examples

use oxinum_complex::native::{BigComplex, RoundingMode};
// sqrt(2i) = 1 + i.
let z = BigComplex::from_f64(0.0, 2.0, 80).expect("finite");
let r = z.sqrt(80, RoundingMode::HalfEven).expect("sqrt");
assert!((r.re().to_f64() - 1.0).abs() < 1e-12);
assert!((r.im().to_f64() - 1.0).abs() < 1e-12);

pub fn pow( &self, w: &BigComplex, prec: u32, mode: RoundingMode, ) -> OxiNumResult<BigComplex>

The complex power z^w = exp(w · ln z) at prec bits.

The zero base is handled by convention: 0^0 = 1 and 0^w = 0 for any other w (avoiding ln(0)).

Errors

Propagates errors from BigComplex::ln / BigComplex::exp.

Examples

use oxinum_complex::native::{BigComplex, RoundingMode};
// i^2 = −1.
let i = BigComplex::i(80, RoundingMode::HalfEven);
let two = BigComplex::from_f64(2.0, 0.0, 80).expect("finite");
let r = i.pow(&two, 80, RoundingMode::HalfEven).expect("pow");
assert!((r.re().to_f64() + 1.0).abs() < 1e-12);
assert!(r.im().to_f64().abs() < 1e-12);

impl BigComplex

pub fn sin(&self, prec: u32, mode: RoundingMode) -> OxiNumResult<BigComplex>

The complex sine sin z = sin a · cosh b + i · cos a · sinh b at prec bits.

Errors

Propagates errors from the real sin/cos/exp routines.

Examples

use oxinum_complex::native::{BigComplex, RoundingMode};
let s = BigComplex::zero(80).sin(80, RoundingMode::HalfEven).expect("sin");
assert!(s.re().to_f64().abs() < 1e-12);
assert!(s.im().to_f64().abs() < 1e-12);

pub fn cos(&self, prec: u32, mode: RoundingMode) -> OxiNumResult<BigComplex>

The complex cosine cos z = cos a · cosh b − i · sin a · sinh b at prec bits.

Errors

Propagates errors from the real sin/cos/exp routines.

Examples

use oxinum_complex::native::{BigComplex, RoundingMode};
let c = BigComplex::zero(80).cos(80, RoundingMode::HalfEven).expect("cos");
assert!((c.re().to_f64() - 1.0).abs() < 1e-12);
assert!(c.im().to_f64().abs() < 1e-12);

pub fn sinh(&self, prec: u32, mode: RoundingMode) -> OxiNumResult<BigComplex>

The complex hyperbolic sine sinh z = sinh a · cos b + i · cosh a · sin b at prec bits.

Errors

Propagates errors from the real sin/cos/exp routines.

pub fn cosh(&self, prec: u32, mode: RoundingMode) -> OxiNumResult<BigComplex>

The complex hyperbolic cosine cosh z = cosh a · cos b + i · sinh a · sin b at prec bits.

Errors

Propagates errors from the real sin/cos/exp routines.

Examples

use oxinum_complex::native::{BigComplex, RoundingMode};
let c = BigComplex::zero(80).cosh(80, RoundingMode::HalfEven).expect("cosh");
assert!((c.re().to_f64() - 1.0).abs() < 1e-12);
assert!(c.im().to_f64().abs() < 1e-12);

pub fn tan(&self, prec: u32, mode: RoundingMode) -> OxiNumResult<BigComplex>

The complex tangent tan z = sin z / cos z at prec bits.

Errors

• OxiNumError::DivByZero at the poles where cos z = 0.
• Propagates errors from the real sin/cos/exp routines.

pub fn tanh(&self, prec: u32, mode: RoundingMode) -> OxiNumResult<BigComplex>

The complex hyperbolic tangent tanh z = sinh z / cosh z at prec bits.

Errors

• OxiNumError::DivByZero at the poles where cosh z = 0.
• Propagates errors from the real sin/cos/exp routines.

Trait Implementations

impl Add<&BigComplex> for &BigComplex

type Output = BigComplex

The resulting type after applying the + operator.

fn add(self, rhs: &BigComplex) -> BigComplex

Performs the + operation.

impl Add<&BigComplex> for BigComplex

type Output = BigComplex

The resulting type after applying the + operator.

fn add(self, rhs: &BigComplex) -> BigComplex

Performs the + operation.

impl Add<BigComplex> for &BigComplex

type Output = BigComplex

The resulting type after applying the + operator.

fn add(self, rhs: BigComplex) -> BigComplex

Performs the + operation.

impl Add for BigComplex

type Output = BigComplex

The resulting type after applying the + operator.

fn add(self, rhs: BigComplex) -> BigComplex

Performs the + operation.

impl AddAssign<&BigComplex> for BigComplex

fn add_assign(&mut self, rhs: &BigComplex)

Performs the += operation.

impl AddAssign for BigComplex

fn add_assign(&mut self, rhs: BigComplex)

Performs the += operation.

impl Clone for BigComplex

fn clone(&self) -> BigComplex

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BigComplex

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Structural debug view exposing the real and imaginary [BigFloat]s.

impl Display for BigComplex

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Format as a + bi (or a - bi when the imaginary part is negative).

Each component is delegated to BigFloat’s Display. The real part keeps its own sign; the imaginary part is shown as a magnitude with an explicit +/- separator chosen from its sign.

Examples

use oxinum_complex::native::BigComplex;
let z = BigComplex::from_f64(1.0, -2.0, 53).expect("finite");
let s = format!("{z}");
assert!(s.contains('-'));
assert!(s.ends_with('i'));

impl From<(BigFloat, BigFloat)> for BigComplex

fn from((re, im): (BigFloat, BigFloat)) -> Self

Build re + im·i from the ordered pair (re, im).

impl From<BigFloat> for BigComplex

fn from(re: BigFloat) -> Self

Place a real BigFloat on the real axis (im = 0 at re’s precision).

impl Mul<&BigComplex> for &BigComplex

type Output = BigComplex

The resulting type after applying the * operator.

fn mul(self, rhs: &BigComplex) -> BigComplex

Performs the * operation.

impl Mul<&BigComplex> for BigComplex

type Output = BigComplex

The resulting type after applying the * operator.

fn mul(self, rhs: &BigComplex) -> BigComplex

Performs the * operation.

impl Mul<BigComplex> for &BigComplex

type Output = BigComplex

The resulting type after applying the * operator.

fn mul(self, rhs: BigComplex) -> BigComplex

Performs the * operation.

impl Mul for BigComplex

type Output = BigComplex

The resulting type after applying the * operator.

fn mul(self, rhs: BigComplex) -> BigComplex

Performs the * operation.

impl MulAssign<&BigComplex> for BigComplex

fn mul_assign(&mut self, rhs: &BigComplex)

Performs the *= operation.

impl MulAssign for BigComplex

fn mul_assign(&mut self, rhs: BigComplex)

Performs the *= operation.

impl Neg for &BigComplex

type Output = BigComplex

The resulting type after applying the - operator.

fn neg(self) -> BigComplex

Performs the unary - operation.

impl Neg for BigComplex

type Output = BigComplex

The resulting type after applying the - operator.

fn neg(self) -> BigComplex

Performs the unary - operation.

impl PartialEq for BigComplex

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Sub<&BigComplex> for &BigComplex

type Output = BigComplex

The resulting type after applying the - operator.

fn sub(self, rhs: &BigComplex) -> BigComplex

Performs the - operation.

impl Sub<&BigComplex> for BigComplex

type Output = BigComplex

The resulting type after applying the - operator.

fn sub(self, rhs: &BigComplex) -> BigComplex

Performs the - operation.

impl Sub<BigComplex> for &BigComplex

type Output = BigComplex

The resulting type after applying the - operator.

fn sub(self, rhs: BigComplex) -> BigComplex

Performs the - operation.

impl Sub for BigComplex

type Output = BigComplex

The resulting type after applying the - operator.

fn sub(self, rhs: BigComplex) -> BigComplex

Performs the - operation.

impl SubAssign<&BigComplex> for BigComplex

fn sub_assign(&mut self, rhs: &BigComplex)

Performs the -= operation.

impl SubAssign for BigComplex

fn sub_assign(&mut self, rhs: BigComplex)

Performs the -= operation.