API reference

apn_mojo.exact_complex¶

Use ExactComplex when a calculation needs both exact fractions and i. It stores two Rational parts, so arithmetic on Gaussian rationals stays exact. Converting to Complex rounds each part to a Float.

The complex tutorial includes a runnable example of exact arithmetic, optional square roots, JSON, and conversion. ExactComplex is currently scalar-only: it is not a Batch element type or a supported vmap result.

Exact complex numbers with Rational parts, one declaration per name.

Arithmetic never rounds. Operations are functions, as in the other families: exact_complex.pow_int(z, 10), exact_complex.sqrt_exact(z); +, -, * and / work on ExactComplex values and exact Rational, Integer or literal operands.

Summary¶

Name	Kind	Summary
`add`	function	The exact sum.
`conjugate`	function	The complex conjugate, `re - im i`.
`divide`	function	The exact quotient.
`imag`	function	The imaginary part (numpy's `imag`).
`multiply`	function	The exact product.
`norm_sqr`	function	The squared magnitude, `re2 + im2`, exactly.
`pow_int`	function	The exact power for an integral exponent of any sign.
`real`	function	The real part (numpy's `real`).
`reciprocal`	function	`1 / value`, exactly (numpy's `reciprocal`).
`sqrt_exact`	function	The principal square root, when both parts are rational.
`stable_hash`	function	A 64-bit hash of the value, stable across processes and releases.
`subtract`	function	The exact difference.
`ExactComplex`	struct	A complex number with exact Rational parts, `real + imag i`.

Functions¶

add¶

Source: apn_mojo/exact_complex/math.mojo

def add(left: ExactComplex, right: ExactComplex) raises -> ExactComplex

The exact sum.

Arguments

left (ExactComplex): The first operand.
right (ExactComplex): The second operand.

Returns

ExactComplex: left + right.

Raises

Error: Only on a checked size error.

conjugate¶

Source: apn_mojo/exact_complex/math.mojo

def conjugate(value: ExactComplex) raises -> ExactComplex

The complex conjugate, re - im i.

Arguments

value (ExactComplex): The number.

Returns

ExactComplex: The conjugate.

Raises

Error: Only on a checked size error.

divide¶

Source: apn_mojo/exact_complex/math.mojo

def divide(left: ExactComplex, right: ExactComplex) raises -> ExactComplex

The exact quotient.

Arguments

left (ExactComplex): The dividend.
right (ExactComplex): The divisor, nonzero.

Returns

ExactComplex: left / right.

Raises

Error: division by zero for a zero divisor.

imag¶

Source: apn_mojo/exact_complex/math.mojo

def imag(value: ExactComplex) raises -> Rational

The imaginary part (numpy's imag).

Arguments

value (ExactComplex): The number.

Returns

Rational: The imaginary part.

Raises

Error: Only on a checked size error.

multiply¶

Source: apn_mojo/exact_complex/math.mojo

def multiply(left: ExactComplex, right: ExactComplex) raises -> ExactComplex

The exact product.

Arguments

left (ExactComplex): The first operand.
right (ExactComplex): The second operand.

Returns

ExactComplex: left * right.

Raises

Error: Only on a checked size error.

norm_sqr¶

Source: apn_mojo/exact_complex/math.mojo

def norm_sqr(value: ExactComplex) raises -> Rational

The squared magnitude, re**2 + im**2, exactly.

Arguments

value (ExactComplex): The number.

Returns

Rational: The squared magnitude.

Raises

Error: Only on a checked size error.

pow_int¶

Source: apn_mojo/exact_complex/math.mojo

def pow_int(value: ExactComplex, exponent: Integer) raises -> ExactComplex

The exact power for an integral exponent of any sign.

pow_int(z, 0) is 1, even for z = 0; a negative exponent takes the reciprocal, so 0 to a negative power raises.

Arguments

value (ExactComplex): The base.
exponent (Integer): The exponent.

Returns

ExactComplex: value**exponent.

Raises

Error: division by zero for a zero base and a negative exponent.

real¶

Source: apn_mojo/exact_complex/math.mojo

def real(value: ExactComplex) raises -> Rational

The real part (numpy's real).

Arguments

value (ExactComplex): The number.

Returns

Rational: The real part.

Raises

Error: Only on a checked size error.

reciprocal¶

Source: apn_mojo/exact_complex/math.mojo

def reciprocal(value: ExactComplex) raises -> ExactComplex

1 / value, exactly (numpy's reciprocal).

Arguments

value (ExactComplex): A nonzero number.

Returns

ExactComplex: The exact reciprocal.

Raises

Error: When value is zero.

sqrt_exact¶

Source: apn_mojo/exact_complex/math.mojo

def sqrt_exact(value: ExactComplex) raises -> Optional[ExactComplex]

The principal square root, when both parts are rational.

The principal root has a nonnegative real part, and a nonnegative imaginary part when the real part is 0. Either both parts of the root are rational or neither is, so sqrt_exact(2i) is 1 + i, sqrt_exact(-4) is 2i, and sqrt_exact(i) is None.

Arguments

value (ExactComplex): The number.

Returns

Optional[ExactComplex]: The root, or None when it is not Gaussian-rational.

Raises

Error: Only on a checked size error.

stable_hash¶

Source: apn_mojo/exact_complex/math.mojo

def stable_hash(value: ExactComplex) -> UInt64

A 64-bit hash of the value, stable across processes and releases.

The algorithm is APNH-64: tag 5, then the real part's numerator and denominator and the imaginary part's, each encoded as an Integer. Equal values hash equal.

Arguments

value (ExactComplex): The number.

Returns

UInt64: The hash.

subtract¶

Source: apn_mojo/exact_complex/math.mojo

def subtract(left: ExactComplex, right: ExactComplex) raises -> ExactComplex

The exact difference.

Arguments

left (ExactComplex): The first operand.
right (ExactComplex): The second operand.

Returns

ExactComplex: left - right.

Raises

Error: Only on a checked size error.

Structs¶

ExactComplex¶

Source: apn_mojo/exact_complex/value.mojo

struct ExactComplex(Equatable, Hashable, ImplicitlyCopyable, Writable)

A complex number with exact Rational parts, real + imag i.

Arithmetic is exact: +, -, * and / never round, and division by zero raises. A Rational, Integer or integer literal operand on either side is exact too. There is no implicit conversion from those types, so a package-level function never becomes ambiguous; write ExactComplex(1, 2).

Operation	Contract
`z + w`, `z - w`, `z * w`	Exact
`z / w`	Exact; raises for `w = 0`
`-z`, `+z`	Exact
`==`, `!=`, `hash`	Equal values compare and hash equal

Printing writes ExactComplex(1/2, 3), which the text constructor reads back; JSON holds two canonical Rational records.

Implements

Copyable, Equatable, Hashable, ImplicitlyCopyable, Writable

ExactComplex.init { #ExactComplex.init .api-name }¶

def __init__(
    out self,
    real: Rational = Rational(0),
    imag: Rational = Rational(0),
)

The number real + imag i.

Arguments

real (Rational): The real part.
imag (Rational): The imaginary part.

def __init__(out self, text: String) raises

Parse ExactComplex(re, im) as printing writes it; each part is Rational text such as -3/4.

Arguments

text (String): The text.

Raises

Error: When the text is not in that form or a part is not a fraction.

ExactComplex.from_json¶

def from_json(
    text: String,
    *,
    limits: Optional[ConversionLimits] = None,
) raises -> Self

Read an ExactComplex from its version-1 JSON record.

Arguments

text (String): The JSON record.
limits (Optional[ConversionLimits]): Optional per-call conversion limits; see ConversionLimits.

Returns

Self: The ExactComplex the record holds.

Raises

Error: When the text is not exactly that schema, naming the byte offset, or a part is not a canonical fraction.

ExactComplex.imag¶

def imag(self) -> Rational

The imaginary part.

Returns

Rational: The imaginary part.

ExactComplex.is_real¶

def is_real(self) -> Bool

Whether the imaginary part is zero.

Returns

Bool: True for a real number.

ExactComplex.real¶

def real(self) -> Rational

The real part.

Returns

Rational: The real part.

ExactComplex.to_complex¶

def to_complex(
    self,
    *,
    context: Optional[ComplexContext] = None,
) raises -> Complex

Each part rounded once to a Complex.

Arguments

context (Optional[ComplexContext]): The component formats, rounding modes and traps; by default 128 bits each, to nearest-even.

Returns

Complex: The rounded Complex.

Raises

Error: On a trapped condition.

ExactComplex.to_json¶

def to_json(self, *, limits: Optional[ConversionLimits] = None) raises -> String

Write the version-1 JSON record: two canonical Rational records.

Arguments

limits (Optional[ConversionLimits]): Optional per-call conversion limits; see ConversionLimits.

Returns

String: {"version":1,"family":"exact_complex","real":{...},"imag":{...}}.

Raises

Error: When the output exceeds limits.

ExactComplex.write_to¶

def write_to(self, mut writer: Some[Writer])

Write ExactComplex(re, im), which the text constructor reads.

Arguments

writer (mut Some[Writer]): The destination.

Arithmetic and powers¶

+, -, * and / are exact on ExactComplex values, and on exact Rational, Integer or literal operands on either side; division by zero raises. There is no implicit conversion into ExactComplex, so write ExactComplex(1, 2). pow_int(z, n) takes an exponent of any sign: pow_int(z, 0) is 1, even for z = 0, and a negative exponent takes the reciprocal.

Square roots¶

sqrt_exact(z) returns the principal square root when its parts are rational, and None otherwise: sqrt_exact(2i) is 1 + i, sqrt_exact(3 + 4i) is 2 + i and sqrt_exact(-4) is 2i, while sqrt_exact(-2) and sqrt_exact(i) are None. The principal root has a nonnegative real part, and a nonnegative imaginary part when its real part is 0; either both parts of the root are rational or neither is.

Text, JSON and hashing¶

The text form, such as ExactComplex(1/2, 3), can be read back by the constructor. JSON is a version-1 record with two canonical Rational records, real and imag. Equal values have equal hashes, so you can use an ExactComplex as a Dict key. stable_hash gives the APNH-64 hash, tag 5, which never changes between releases. to_complex rounds each part once to a Complex.

apn_mojo.exact_complex¶

Summary¶

Functions¶

add¶

conjugate¶

divide¶

imag¶

multiply¶

norm_sqr¶

pow_int¶

real¶

reciprocal¶

sqrt_exact¶

stable_hash¶

subtract¶

Structs¶

ExactComplex¶

ExactComplex.__init__ { #ExactComplex.init .api-name }¶

ExactComplex.from_json¶

ExactComplex.imag¶

ExactComplex.is_real¶

ExactComplex.real¶

ExactComplex.to_complex¶

ExactComplex.to_json¶

ExactComplex.write_to¶

Arithmetic and powers¶

Square roots¶

Text, JSON and hashing¶

ExactComplex.init { #ExactComplex.init .api-name }¶