ComplexFloat

Symbolica documentation for getting started, symbolic expressions, numerical evaluation, pattern matching, and APIs in Python and Rust.

ComplexFloat

ComplexFloat()

An immutable complex number with arbitrary-precision Float components.

Notes

Each component tracks its own precision. The precision property reports the minimum; real.precision and imag.precision expose each component.

Arithmetic accepts Float, ComplexFloat, int, float, complex and Decimal operands. Use the constructor to convert strings or (real, imag) pairs. Accuracy tracking may change component precision. Values are immutable and unhashable. Equality is supported; ordering comparisons raise TypeError. abs(z) and norm() return a real Float. Elementary functions use the principal complex branch; signed zero selects the side of a branch cut where applicable.

Use complex(z) for a native complex value, as_tuple() for Float components, or to_decimal_tuple() for Decimal components. Decimal conversion is exact by default and independent of the global decimal context.

Examples

from symbolica import ComplexFloat, Float
z = ComplexFloat("3", "4", decimal_digits=60)
z.as_tuple() == (Float(3), Float(4))
True
abs(z) == Float(5)
True
str(z.conjugate())
'(3-4j)'
ComplexFloat("1.25-2.5j").to_decimal_tuple()
(Decimal('1.25'), Decimal('-2.5'))
ComplexFloat.i(precision=200) ** 2 == -1
True

Attributes

Name	Description
imag	The imaginary component as a Float, preserving its own precision.
precision	The minimum component precision in bits
real	The real component as a Float, preserving its own precision.

imag

ComplexFloat.imag: Float

Related type: Float

The imaginary component as a Float, preserving its own precision.

precision

ComplexFloat.precision: int

The minimum component precision in bits. Read-only; inspect real.precision and imag.precision individually.

real

ComplexFloat.real: Float

Related type: Float

The real component as a Float, preserving its own precision.

Methods

Name	Description
__abs__	Return the magnitude as a real Float.
__add__	Return self + other with accuracy tracking; complex operands produce ComplexFloat.
__bool__	Return False for zero and True otherwise, including NaN.
__complex__	Convert both components to native binary64 floats, potentially losing precision or overflowing to infinity.
__copy__	Return a copy preserving the value and component precisions.
__deepcopy__	Return a copy preserving the value and component precisions.
__eq__	Compare numeric values exactly across compatible scalar types; NaN is unequal to every value.
__format__	Format with a Decimal-style specification, applied separately to complex components
__mul__	Return self * other with accuracy tracking; complex operands produce ComplexFloat.
__ne__	Return the negation of numeric equality, including True for NaN.
__neg__	Return the additive inverse.
__new__	Construct an immutable complex number from scalars or a complex value.
__pos__	Return a copy of this value.
__pow__	Raise to an integer, real or complex numeric exponent
__radd__	Return other + self with accuracy tracking; complex operands produce ComplexFloat.
__repr__	Return a constructor expression that preserves the value and its precision.
__rmul__	Return other * self with accuracy tracking; complex operands produce ComplexFloat.
__rsub__	Return other - self with accuracy tracking; complex operands produce ComplexFloat.
__rtruediv__	Return other / self with accuracy tracking; complex operands produce ComplexFloat
__str__	Return a decimal display using significant digits appropriate to the precision.
__sub__	Return self - other with accuracy tracking; complex operands produce ComplexFloat.
__truediv__	Return self / other with accuracy tracking; complex operands produce ComplexFloat
_repr_html_	Return HTML with the same significant digits as str(self).
_repr_latex_	Return LaTeX preserving each component’s displayed precision, using i for the imaginary unit.
_repr_pretty_	Write the same significant digits as str(self) to a notebook pretty printer.
acos	Return the principal complex inverse cosine; signed zero selects the side of a real-axis branch cut.
acosh	Return the principal complex inverse hyperbolic cosine.
as_tuple	Return (real, imag) as two Float values, preserving their individual precisions.
asin	Return the principal complex inverse sine; signed zero selects the side of a real-axis branch cut.
asinh	Return the principal complex inverse hyperbolic sine.
atan	Return the principal complex inverse tangent.
atan2	Return atan(self/x) for complex arguments; two real arguments use the usual quadrant-aware atan2
atanh	Return the principal complex inverse hyperbolic tangent.
conj	Alias for conjugate().
conjugate	Return the complex conjugate, negating the imaginary component.
cos	Return the cosine, with the argument in radians.
cosh	Return the hyperbolic cosine with accuracy tracking.
csch	Return the reciprocal hyperbolic sine, retaining accuracy near zero and at infinity.
e	Construct Euler’s number e with precision in bits or decimal_digits (default: 53 bits)
euler	Construct the Euler-Mascheroni constant with precision in bits or decimal_digits (default: 53 bits)
euler_gamma	Alias for euler(), the Euler-Mascheroni constant; precision defaults to 53 bits.
exp	Return the exponential e**self with accuracy tracking.
fixed_precision	Return False: arithmetic dynamically tracks precision for these scalar types.
from_i64	Convert a signed 64-bit integer at this value’s precision
from_ratio	Construct numerator / denominator from two Python integers
from_rational	Convert numerator / denominator at this value’s precision
from_usize	Convert a nonnegative platform-sized integer at this value’s precision
get_epsilon	Return 2**(-precision) as a native float
get_precision	Return the working precision in bits; alias for the precision property.
hypot	Return sqrt(abs(self)2 + abs(other)2) as a real Float, using scaled arithmetic.
i	Construct the imaginary unit 0+1j with precision in bits or decimal_digits (default: 53 bits).
inv	Return 1/self
is_finite	Return True only when both components are finite.
is_fully_zero	Return whether the value is exactly zero in every component.
is_nan	Return True if either component is NaN.
is_one	Return whether the value equals one (1+0j for ComplexFloat).
is_zero	Return whether the value is zero; signed zero also counts as zero.
ln	Return the principal complex natural logarithm
log	Alias for ln(), the principal natural logarithm (base e).
log1p	Return the principal log(1+self), retaining small increments and signed-zero branch cuts.
mul_add	Return self*a+b with accuracy tracking, rounding the multiplication and addition separately.
nan	Return NaN at this value’s precision; both complex components become NaN.
neg	Return the additive inverse, equivalent to -self.
new_one	Construct one with precision in bits or decimal_digits (default: 53 bits)
new_zero	Construct zero with precision in bits or decimal_digits (default: 53 bits)
norm	Return the magnitude as a real Float, equivalent to abs(self).
one	Return one at this value’s precision, preserving component precisions.
phi	Construct the golden ratio (1+sqrt(5))/2 with precision in bits or decimal_digits (default: 53 bits)
pi	Construct pi with precision in bits or decimal_digits (default: 53 bits)
pow	Raise to an unsigned 64-bit integer exponent
powf	Raise to a real or complex numeric exponent on the principal branch
sample_unit	Sample uniformly from [0, 1) using the full working precision
sech	Return the reciprocal hyperbolic cosine without overflowing an intermediate cosh.
set_from	Return a new value converted from other, with precision inferred as in the constructor.
sin	Return the sine, with the argument in radians.
sinh	Return the hyperbolic sine with accuracy tracking.
sqrt	Return the principal complex square root; signed zero distinguishes the sides of the negative-real branch cut.
tan	Return the tangent, with the argument in radians.
tanh	Return the hyperbolic tangent with accuracy tracking.
to_decimal_tuple	Return (real, imag) as Decimal values
with_precision	Return a copy with both components rounded to the requested precision in bits or decimal_digits
zero	Return zero at this value’s precision, preserving component precisions.

__abs__

ComplexFloat.__abs__() -> Float

Related type: Float

Return the magnitude as a real Float.

__add__

ComplexFloat.__add__(other: ComplexFloat | Float | int | float | complex | Decimal) -> ComplexFloat

Related type: Float

Return self + other with accuracy tracking; complex operands produce ComplexFloat.

Parameters

• other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

__bool__

ComplexFloat.__bool__() -> bool

Return False for zero and True otherwise, including NaN.

__complex__

ComplexFloat.__complex__() -> complex

Convert both components to native binary64 floats, potentially losing precision or overflowing to infinity.

__copy__

ComplexFloat.__copy__() -> ComplexFloat

Return a copy preserving the value and component precisions.

__deepcopy__

ComplexFloat.__deepcopy__(memo: Any) -> ComplexFloat

Return a copy preserving the value and component precisions.

Parameters

• memo (dict) Memo dictionary supplied by copy.deepcopy.

__eq__

ComplexFloat.__eq__(other: object) -> bool

Compare numeric values exactly across compatible scalar types; NaN is unequal to every value.

Parameters

• other (object) Value to compare numerically. Compatible numeric types compare by value; unsupported types are not equal.

__format__

ComplexFloat.__format__(spec: str) -> str

Format with a Decimal-style specification, applied separately to complex components. An empty specification uses str(self).

Parameters

• spec (str) Decimal-style format specification, such as “.12f”. An empty string uses str(self). Applied to both components.

__mul__

ComplexFloat.__mul__(other: ComplexFloat | Float | int | float | complex | Decimal) -> ComplexFloat

Related type: Float

Return self * other with accuracy tracking; complex operands produce ComplexFloat.

Parameters

• other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

__ne__

ComplexFloat.__ne__(other: object) -> bool

Return the negation of numeric equality, including True for NaN.

Parameters

• other (object) Value to compare numerically. Compatible numeric types compare by value; unsupported types are not equal.

__neg__

ComplexFloat.__neg__() -> ComplexFloat

Return the additive inverse.

__new__

ComplexFloat.__new__(
    real: ComplexFloat | Float | int | float | complex | str | Decimal | tuple[Float | int | float | str | Decimal, Float | int | float | str | Decimal] | None = None,
    imag: Float | int | float | str | Decimal | None = None,
    *,
    precision: int | None = None,
    decimal_digits: int | None = None,
) -> ComplexFloat

Related type: Float

Construct an immutable complex number from scalars or a complex value.

Parameters

• real (ComplexFloat, Float, int, float, complex, str, Decimal, tuple, optional) Real component when imag is supplied. Otherwise, accepts a real scalar, a complete complex value, a (real, imag) pair, or a string such as “1.25-2.5j”, “(1+2i)” or “-j”. Omitted or None means zero.
• imag (Float, int, float, str, Decimal, optional) Imaginary component. When supplied, real must also be a real scalar.
• precision (int, optional) Working precision of both components in bits; exclusive with decimal_digits.
• decimal_digits (int, optional) Decimal working precision for both components, converted to ceil(decimal_digits * log2(10)) bits.

Notes

Without a precision option, existing components retain their precision; native complex components use 53 bits. Other components follow Float’s precision inference. precision reports the minimum component precision; real.precision and imag.precision expose the individual values. Invalid inputs raise TypeError, ValueError or OverflowError, as for Float.

__pos__

ComplexFloat.__pos__() -> ComplexFloat

Return a copy of this value.

__pow__

ComplexFloat.__pow__(
    exponent: Float | int | float | Decimal | ComplexFloat | complex,
    modulo: None = None,
) -> ComplexFloat

Related type: Float

Raise to an integer, real or complex numeric exponent. Integer powers support negative exponents; other powers use the principal branch. Modular powers are unsupported.

Parameters

• exponent (Float, ComplexFloat, int, float, complex or Decimal) Numeric exponent. Use ** for signed integer powers. Non-integer powers use the principal complex branch.
• modulo (None, optional) Must be None. Three-argument modular exponentiation is unsupported.

__radd__

ComplexFloat.__radd__(other: ComplexFloat | Float | int | float | complex | Decimal) -> ComplexFloat

Related type: Float

Return other + self with accuracy tracking; complex operands produce ComplexFloat.

Parameters

• other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

__repr__

ComplexFloat.__repr__() -> str

Return a constructor expression that preserves the value and its precision.

__rmul__

ComplexFloat.__rmul__(other: ComplexFloat | Float | int | float | complex | Decimal) -> ComplexFloat

Related type: Float

Return other * self with accuracy tracking; complex operands produce ComplexFloat.

Parameters

• other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

__rsub__

ComplexFloat.__rsub__(other: ComplexFloat | Float | int | float | complex | Decimal) -> ComplexFloat

Related type: Float

Return other - self with accuracy tracking; complex operands produce ComplexFloat.

Parameters

• other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

__rtruediv__

ComplexFloat.__rtruediv__(other: ComplexFloat | Float | int | float | complex | Decimal) -> ComplexFloat

Related type: Float

Return other / self with accuracy tracking; complex operands produce ComplexFloat. A zero divisor raises ZeroDivisionError.

Parameters

• other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

__str__

ComplexFloat.__str__() -> str

Return a decimal display using significant digits appropriate to the precision.

__sub__

ComplexFloat.__sub__(other: ComplexFloat | Float | int | float | complex | Decimal) -> ComplexFloat

Related type: Float

Return self - other with accuracy tracking; complex operands produce ComplexFloat.

Parameters

• other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

__truediv__

ComplexFloat.__truediv__(other: ComplexFloat | Float | int | float | complex | Decimal) -> ComplexFloat

Related type: Float

Return self / other with accuracy tracking; complex operands produce ComplexFloat. A zero divisor raises ZeroDivisionError.

Parameters

• other (Float, ComplexFloat, int, float, complex or Decimal) Numeric operand. Existing arbitrary-precision scalars retain their precision; native numbers are converted at the receiver’s precision.

_repr_html_

ComplexFloat._repr_html_() -> str

Return HTML with the same significant digits as str(self).

_repr_latex_

ComplexFloat._repr_latex_() -> str

Return LaTeX preserving each component’s displayed precision, using i for the imaginary unit.

_repr_pretty_

ComplexFloat._repr_pretty_(pretty: Any, cycle: bool) -> None

Write the same significant digits as str(self) to a notebook pretty printer.

Parameters

• pretty (object) Pretty printer providing a text(string) method.
• cycle (bool) Whether the printer detected a reference cycle; prints … if True.

acos

ComplexFloat.acos() -> ComplexFloat

Return the principal complex inverse cosine; signed zero selects the side of a real-axis branch cut.

acosh

ComplexFloat.acosh() -> ComplexFloat

Return the principal complex inverse hyperbolic cosine.

as_tuple

ComplexFloat.as_tuple() -> tuple[Float, Float]

Related type: Float

Return (real, imag) as two Float values, preserving their individual precisions.

asin

ComplexFloat.asin() -> ComplexFloat

Return the principal complex inverse sine; signed zero selects the side of a real-axis branch cut.

asinh

ComplexFloat.asinh() -> ComplexFloat

Return the principal complex inverse hyperbolic sine.

atan

ComplexFloat.atan() -> ComplexFloat

Return the principal complex inverse tangent.

atan2

ComplexFloat.atan2(x: Float | int | float | Decimal | ComplexFloat | complex) -> ComplexFloat

Related type: Float

Return atan(self/x) for complex arguments; two real arguments use the usual quadrant-aware atan2. A zero complex denominator raises ZeroDivisionError.

Parameters

• x (Float, ComplexFloat, int, float, complex or Decimal) Horizontal coordinate; self is the vertical coordinate in atan2(self, x). For non-real arguments, this is the divisor in atan(self/x).

atanh

ComplexFloat.atanh() -> ComplexFloat

Return the principal complex inverse hyperbolic tangent.

conj

ComplexFloat.conj() -> ComplexFloat

Alias for conjugate().

conjugate

ComplexFloat.conjugate() -> ComplexFloat

Return the complex conjugate, negating the imaginary component.

cos

ComplexFloat.cos() -> ComplexFloat

Return the cosine, with the argument in radians.

cosh

ComplexFloat.cosh() -> ComplexFloat

Return the hyperbolic cosine with accuracy tracking.

csch

ComplexFloat.csch() -> ComplexFloat

Return the reciprocal hyperbolic sine, retaining accuracy near zero and at infinity.

e

ComplexFloat.e(*, precision: int | None = None, decimal_digits: int | None = None) -> ComplexFloat

Construct Euler’s number e with precision in bits or decimal_digits (default: 53 bits). Complex results have zero imaginary part.

Parameters

• precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits. Applies to both components.
• decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits. Applies to both components.

euler

ComplexFloat.euler(
    *,
    precision: int | None = None,
    decimal_digits: int | None = None,
) -> ComplexFloat

Construct the Euler-Mascheroni constant with precision in bits or decimal_digits (default: 53 bits). Complex results have zero imaginary part.

Parameters

• precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits. Applies to both components.
• decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits. Applies to both components.

euler_gamma

ComplexFloat.euler_gamma(
    *,
    precision: int | None = None,
    decimal_digits: int | None = None,
) -> ComplexFloat

Alias for euler(), the Euler-Mascheroni constant; precision defaults to 53 bits.

Parameters

• precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits. Applies to both components.
• decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits. Applies to both components.

exp

ComplexFloat.exp() -> ComplexFloat

Return the exponential e**self with accuracy tracking.

fixed_precision

ComplexFloat.fixed_precision() -> bool

Return False: arithmetic dynamically tracks precision for these scalar types.

from_i64

ComplexFloat.from_i64(value: int) -> ComplexFloat

Convert a signed 64-bit integer at this value’s precision. Out-of-range inputs raise OverflowError.

Parameters

• value (int) Integer in [-263, 263-1] to convert.

from_ratio

ComplexFloat.from_ratio(
    numerator: int,
    denominator: int,
    *,
    precision: int | None = None,
    decimal_digits: int | None = None,
) -> ComplexFloat

Construct numerator / denominator from two Python integers.

Specify precision in bits or decimal_digits, never both; the default is 53 bits. The rational is rounded directly without conversion through a native float. A zero denominator raises ZeroDivisionError.

Parameters

• numerator (int) Numerator of the rational value; accepts arbitrary-sized Python integers.
• denominator (int) Nonzero denominator of the rational value; either sign is accepted.
• precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits. Applies to both components.
• decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits. Applies to both components.

Examples

Float.from_ratio(1, 8, precision=100).to_decimal()
Decimal('0.125')

from_rational

ComplexFloat.from_rational(numerator: int, denominator: int) -> ComplexFloat

Convert numerator / denominator at this value’s precision. Both inputs must be Python integers; zero denominator raises ZeroDivisionError.

Parameters

• numerator (int) Numerator of the rational value; accepts arbitrary-sized Python integers.
• denominator (int) Nonzero denominator of the rational value; either sign is accepted.

from_usize

ComplexFloat.from_usize(value: int) -> ComplexFloat

Convert a nonnegative platform-sized integer at this value’s precision. Out-of-range inputs raise OverflowError.

Parameters

• value (int) Integer in [0, 2**pointer_bits-1] to convert.

get_epsilon

ComplexFloat.get_epsilon() -> float

Return 2**(-precision) as a native float. Very high precision can underflow to zero.

get_precision

ComplexFloat.get_precision() -> int

Return the working precision in bits; alias for the precision property.

hypot

ComplexFloat.hypot(other: Float | int | float | Decimal | ComplexFloat | complex) -> Float

Related type: Float

Return sqrt(abs(self)2 + abs(other)2) as a real Float, using scaled arithmetic.

Parameters

• other (Float, int, float, Decimal, ComplexFloat, complex) Second coordinate. Native numbers use this value’s precision; existing arbitrary-precision scalars retain their precision.

i

ComplexFloat.i(*, precision: int | None = None, decimal_digits: int | None = None) -> ComplexFloat

Construct the imaginary unit 0+1j with precision in bits or decimal_digits (default: 53 bits).

Parameters

• precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits. Applies to both components.
• decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits. Applies to both components.

inv

ComplexFloat.inv() -> ComplexFloat

Return 1/self. Zero raises ZeroDivisionError.

is_finite

ComplexFloat.is_finite() -> bool

Return True only when both components are finite.

is_fully_zero

ComplexFloat.is_fully_zero() -> bool

Return whether the value is exactly zero in every component.

is_nan

ComplexFloat.is_nan() -> bool

Return True if either component is NaN.

is_one

ComplexFloat.is_one() -> bool

Return whether the value equals one (1+0j for ComplexFloat).

is_zero

ComplexFloat.is_zero() -> bool

Return whether the value is zero; signed zero also counts as zero.

ln

ComplexFloat.ln() -> ComplexFloat

Return the principal complex natural logarithm. Its imaginary part is the argument in [-pi, pi].

log

ComplexFloat.log() -> ComplexFloat

Alias for ln(), the principal natural logarithm (base e).

log1p

ComplexFloat.log1p() -> ComplexFloat

Return the principal log(1+self), retaining small increments and signed-zero branch cuts.

mul_add

ComplexFloat.mul_add(
    a: Float | int | float | Decimal | ComplexFloat | complex,
    b: Float | int | float | Decimal | ComplexFloat | complex,
) -> ComplexFloat

Related type: Float

Return self*a+b with accuracy tracking, rounding the multiplication and addition separately.

Parameters

• a (Float, ComplexFloat, int, float, complex or Decimal) Multiplier in self*a+b.
• b (Float, ComplexFloat, int, float, complex or Decimal) Addend in self*a+b.

nan

ComplexFloat.nan() -> ComplexFloat

Return NaN at this value’s precision; both complex components become NaN.

neg

ComplexFloat.neg() -> ComplexFloat

Return the additive inverse, equivalent to -self.

new_one

ComplexFloat.new_one(
    *,
    precision: int | None = None,
    decimal_digits: int | None = None,
) -> ComplexFloat

Construct one with precision in bits or decimal_digits (default: 53 bits). Use one() to retain instance precision.

Parameters

• precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits. Applies to both components.
• decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits. Applies to both components.

new_zero

ComplexFloat.new_zero(
    *,
    precision: int | None = None,
    decimal_digits: int | None = None,
) -> ComplexFloat

Construct zero with precision in bits or decimal_digits (default: 53 bits). Use zero() to retain instance precision.

Parameters

• precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits. Applies to both components.
• decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits. Applies to both components.

norm

ComplexFloat.norm() -> Float

Related type: Float

Return the magnitude as a real Float, equivalent to abs(self).

one

ComplexFloat.one() -> ComplexFloat

Return one at this value’s precision, preserving component precisions.

phi

ComplexFloat.phi(*, precision: int | None = None, decimal_digits: int | None = None) -> ComplexFloat

Construct the golden ratio (1+sqrt(5))/2 with precision in bits or decimal_digits (default: 53 bits). Complex results have zero imaginary part.

Parameters

• precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits. Applies to both components.
• decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits. Applies to both components.

pi

ComplexFloat.pi(*, precision: int | None = None, decimal_digits: int | None = None) -> ComplexFloat

Construct pi with precision in bits or decimal_digits (default: 53 bits). Complex results have zero imaginary part.

Parameters

• precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. If neither option is supplied, use 53 bits. Applies to both components.
• decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. If neither option is supplied, use 53 bits. Applies to both components.

pow

ComplexFloat.pow(exponent: int) -> ComplexFloat

Raise to an unsigned 64-bit integer exponent. Negative or out-of-range exponents raise OverflowError; use ** for signed integer powers.

Parameters

• exponent (int) Unsigned exponent in [0, 2**64-1]; zero returns one, including for a zero base.

powf

ComplexFloat.powf(exponent: Float | int | float | Decimal | ComplexFloat | complex) -> ComplexFloat

Related type: Float

Raise to a real or complex numeric exponent on the principal branch. Zero to a negative-real or non-real exponent raises ZeroDivisionError.

Parameters

• exponent (Float, ComplexFloat, int, float, complex or Decimal) Numeric exponent. Use ** for signed integer powers. Non-integer powers use the principal complex branch.

sample_unit

ComplexFloat.sample_unit(rng: Any = None) -> ComplexFloat

Sample uniformly from [0, 1) using the full working precision.

rng must supply getrandbits(bits); omitted or None uses Python’s random module. Pass random.Random(seed) for reproducibility. Complex samples have zero imaginary part and preserve the receiver’s component precisions.

Parameters

• rng (object, optional) Random generator with a getrandbits(bits) method returning an integer in [0, 2**bits). Omitted or None uses Python’s random module; use random.Random(seed) for reproducible samples.

sech

ComplexFloat.sech() -> ComplexFloat

Return the reciprocal hyperbolic cosine without overflowing an intermediate cosh.

set_from

ComplexFloat.set_from(other: ComplexFloat | Float | int | float | str | Decimal | complex | tuple[Float | int | float | str | Decimal, Float | int | float | str | Decimal]) -> ComplexFloat

Related type: Float

Return a new value converted from other, with precision inferred as in the constructor.

Parameters

• other (Float, ComplexFloat, int, float, complex, str, Decimal or tuple) Value to copy or convert using constructor precision inference. A tuple supplies (real, imag).

sin

ComplexFloat.sin() -> ComplexFloat

Return the sine, with the argument in radians.

sinh

ComplexFloat.sinh() -> ComplexFloat

Return the hyperbolic sine with accuracy tracking.

sqrt

ComplexFloat.sqrt() -> ComplexFloat

Return the principal complex square root; signed zero distinguishes the sides of the negative-real branch cut.

tan

ComplexFloat.tan() -> ComplexFloat

Return the tangent, with the argument in radians.

tanh

ComplexFloat.tanh() -> ComplexFloat

Return the hyperbolic tangent with accuracy tracking.

to_decimal_tuple

ComplexFloat.to_decimal_tuple(digits: int | None = None) -> tuple[Decimal, Decimal]

Return (real, imag) as Decimal values.

Conversion of each stored component is exact when digits is omitted. A positive digits value rounds each component to that many significant decimal digits, using round-half-even. Conversion is independent of Python’s global decimal context and preserves signed zero and special values.

Parameters

• digits (int, optional) Positive number of significant decimal digits per converted value. Omitted or None converts the stored binary value exactly; otherwise round half-even.

Examples

ComplexFloat("1.25", "-2.5").to_decimal_tuple()
(Decimal('1.25'), Decimal('-2.5'))

with_precision

ComplexFloat.with_precision(
    *,
    precision: int | None = None,
    decimal_digits: int | None = None,
) -> ComplexFloat

Return a copy with both components rounded to the requested precision in bits or decimal_digits. Specify exactly one option; invalid options raise ValueError or OverflowError. Increasing precision cannot recover lost digits.

Parameters

• precision (int, optional) Positive working precision in bits. Mutually exclusive with decimal_digits. Exactly one precision option is required. Applies to both components.
• decimal_digits (int, optional) Positive decimal working precision, converted to ceil(decimal_digits * log2(10)) bits. Mutually exclusive with precision. Exactly one precision option is required. Applies to both components.

zero

ComplexFloat.zero() -> ComplexFloat

Return zero at this value’s precision, preserving component precisions.