apn_mojo.complex_ball¶

ComplexBall pairs two real balls to describe a rectangle in the complex plane. Each operation encloses its result for every point in the input rectangles. The Ball arithmetic chapter explains the design.

The interval tutorial shows construction, magnitude bounds, branch cuts, and certified conversion to Complex in a runnable example.

Complex balls: rectangles of two real balls, one declaration per name.

Every function returns a complex ball that contains the exact result for every point of its input rectangles. On a branch cut a point takes its counter-clockwise continuous value; a rectangle that crosses a cut gets a result covering both sides. A context= (BallContext) sets the result precision.

Summary¶

Functions¶

abs¶

Source: apn_mojo/complex_ball/math.mojo

def abs(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the magnitudes.

Computed from bounds of the parts' magnitudes, hypot of the lower bounds rounded down and of the upper bounds rounded up, never from a square root of a sum that may reach below 0.

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

Ball: A ball containing every magnitude.

Raises

Error: Only on an invalid precision or a checked size error.

acos¶

Source: apn_mojo/complex_ball/elementary.mojo

def acos(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the principal arccosine, pi/2 - asin z.

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value; on the cuts the counter-clockwise continuous value.

Raises

Error: Only on an invalid precision or a checked size error.

acosh¶

Source: apn_mojo/complex_ball/elementary.mojo

def acosh(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the principal inverse hyperbolic cosine, log(z + sqrt(z + 1) sqrt(z - 1)).

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value; on the cut (-inf, 1) the counter-clockwise continuous value.

Raises

Error: Only on an invalid precision or a checked size error.

add¶

Source: apn_mojo/complex_ball/math.mojo

def add(
    left: ComplexBall,
    right: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of left + right.

Arguments

• left (ComplexBall): The first operand.
• right (ComplexBall): The second operand.
• context (Optional[BallContext]): The result precision; by default the operands' largest.

Returns

ComplexBall: A ball containing every sum.

Raises

Error: Only on an invalid precision or a checked size error.

angle¶

Source: apn_mojo/complex_ball/math.mojo

def angle(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the arguments, in [-pi, pi].

A point of the negative real axis takes pi, its counter-clockwise continuous value; a rectangle that crosses the axis covers both sides, so its result is [0 +/- pi]; one that contains 0 is indeterminate.

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

Ball: A ball containing every argument.

Raises

Error: Only on an invalid precision or a checked size error.

asin¶

Source: apn_mojo/complex_ball/elementary.mojo

def asin(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the principal arcsine, -i log(iz + sqrt(1 - z**2)).

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value; on the cuts (-inf, -1) and (1, inf) the counter-clockwise continuous value.

Raises

Error: Only on an invalid precision or a checked size error.

asinh¶

Source: apn_mojo/complex_ball/elementary.mojo

def asinh(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the principal inverse hyperbolic sine, log(z + sqrt(z**2 + 1)).

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value; on the cuts of the imaginary axis the counter-clockwise continuous value.

Raises

Error: Only on an invalid precision or a checked size error.

atan¶

Source: apn_mojo/complex_ball/elementary.mojo

def atan(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the principal arctangent, (i/2)(log(1 - iz) - log(1 + iz)).

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value; indeterminate at +-i; on the cuts of the imaginary axis the counter-clockwise continuous value.

Raises

Error: Only on an invalid precision or a checked size error.

atanh¶

Source: apn_mojo/complex_ball/elementary.mojo

def atanh(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the principal inverse hyperbolic tangent, (log(1 + z) - log(1 - z)) / 2.

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value; indeterminate at +-1; on the cuts the counter-clockwise continuous value.

Raises

Error: Only on an invalid precision or a checked size error.

conjugate¶

Source: apn_mojo/complex_ball/math.mojo

def conjugate(value: ComplexBall) raises -> ComplexBall

The ball of the conjugates, re - im i.

Arguments

• value (ComplexBall): The ball.

Returns

ComplexBall: The conjugate rectangle.

Raises

Error: Only on a checked size error.

contains¶

Source: apn_mojo/complex_ball/sets.mojo

def contains(ball: ComplexBall, value: ComplexBall) raises -> Bool

Whether ball's rectangle contains value's.

An exact point is a complex ball too: ComplexBall(z) of a Complex or an ExactComplex.

Arguments

• ball (ComplexBall): The containing ball.
• value (ComplexBall): The contained ball.

Returns

Bool: True when both parts contain the other's.

Raises

Error: Only on a checked size error.

contains_zero¶

Source: apn_mojo/complex_ball/sets.mojo

def contains_zero(ball: ComplexBall) raises -> Bool

Whether the rectangle contains 0.

Arguments

• ball (ComplexBall): The ball.

Returns

Bool: True when both parts contain 0.

Raises

Error: Only on a checked size error.

cos¶

Source: apn_mojo/complex_ball/elementary.mojo

def cos(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the cosine, cos x cosh y - i sin x sinh y.

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value.

Raises

Error: Only on an invalid precision or a checked size error.

cosh¶

Source: apn_mojo/complex_ball/elementary.mojo

def cosh(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the hyperbolic cosine, cosh x cos y + i sinh x sin y.

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value.

Raises

Error: Only on an invalid precision or a checked size error.

divide¶

Source: apn_mojo/complex_ball/math.mojo

def divide(
    left: ComplexBall,
    right: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of left / right.

Arguments

• left (ComplexBall): The dividend.
• right (ComplexBall): The divisor.
• context (Optional[BallContext]): The result precision; by default the operands' largest.

Returns

ComplexBall: A ball containing every quotient; indeterminate when the divisor's rectangle contains 0.

Raises

Error: Only on an invalid precision or a checked size error.

exp¶

Source: apn_mojo/complex_ball/elementary.mojo

def exp(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the exponential, e**x (cos y + i sin y).

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value.

Raises

Error: Only on an invalid precision or a checked size error.

imag¶

Source: apn_mojo/complex_ball/math.mojo

def imag(value: ComplexBall) raises -> Ball

The ball of the imaginary parts (numpy's imag).

Arguments

• value (ComplexBall): The complex ball.

Returns

Ball: The imaginary ball.

Raises

Error: Only on a checked size error.

intersection¶

Source: apn_mojo/complex_ball/sets.mojo

def intersection(a: ComplexBall, b: ComplexBall) raises -> Optional[ComplexBall]

The least complex ball containing the common points, if any.

Arguments

• a (ComplexBall): The first ball.
• b (ComplexBall): The second ball.

Returns

Optional[ComplexBall]: The intersection, part by part, or None when the rectangles are disjoint.

Raises

Error: Only on a checked size error.

log¶

Source: apn_mojo/complex_ball/elementary.mojo

def log(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the principal logarithm, log|z| + i arg z.

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value; the negative real axis takes imaginary part pi; indeterminate when the rectangle contains 0.

Raises

Error: Only on an invalid precision or a checked size error.

multiply¶

Source: apn_mojo/complex_ball/math.mojo

def multiply(
    left: ComplexBall,
    right: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of left * right.

Arguments

• left (ComplexBall): The first operand.
• right (ComplexBall): The second operand.
• context (Optional[BallContext]): The result precision; by default the operands' largest.

Returns

ComplexBall: A ball containing every product.

Raises

Error: Only on an invalid precision or a checked size error.

overlaps¶

Source: apn_mojo/complex_ball/sets.mojo

def overlaps(a: ComplexBall, b: ComplexBall) raises -> Bool

Whether two rectangles share a point.

Arguments

• a (ComplexBall): The first ball.
• b (ComplexBall): The second ball.

Returns

Bool: True when both pairs of parts overlap.

Raises

Error: Only on a checked size error.

pow¶

Source: apn_mojo/complex_ball/elementary.mojo

def pow(
    base: ComplexBall,
    exponent: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of base**exponent, exp(exponent log base).

An exact integer exponent gives an integer power; an exact 0 base gives 0 for an exponent whose real part is certainly positive.

Arguments

• base (ComplexBall): The base.
• exponent (ComplexBall): The exponent.
• context (Optional[BallContext]): The result precision; by default the operands' largest.

Returns

ComplexBall: A ball containing every power; indeterminate where the power is undefined, as for 0 to a power with real part at most 0.

Raises

Error: Only on an invalid precision or a checked size error.

pow_int¶

Source: apn_mojo/complex_ball/math.mojo

def pow_int(
    value: ComplexBall,
    exponent: Integer,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of value**exponent for an integer exponent.

Arguments

• value (ComplexBall): The base.
• exponent (Integer): Any integer; a negative one takes the reciprocal.
• context (Optional[BallContext]): The result precision; by default the base's.

Returns

ComplexBall: A ball containing every power; value**0 is exactly 1, and a negative power of a rectangle containing 0 is indeterminate.

Raises

Error: Only on an invalid precision or a checked size error.

real¶

Source: apn_mojo/complex_ball/math.mojo

def real(value: ComplexBall) raises -> Ball

The ball of the real parts (numpy's real).

Arguments

• value (ComplexBall): The complex ball.

Returns

Ball: The real ball.

Raises

Error: Only on a checked size error.

reciprocal¶

Source: apn_mojo/complex_ball/math.mojo

def reciprocal(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The complex ball of 1 / value (numpy's reciprocal).

Arguments

• value (ComplexBall): The complex ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A complex ball containing every reciprocal; indeterminate when the operand contains 0.

Raises

Error: Only on an invalid precision or a checked size error.

sin¶

Source: apn_mojo/complex_ball/elementary.mojo

def sin(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the sine, sin x cosh y + i cos x sinh y.

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value.

Raises

Error: Only on an invalid precision or a checked size error.

sinh¶

Source: apn_mojo/complex_ball/elementary.mojo

def sinh(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the hyperbolic sine, sinh x cos y + i cosh x sin y.

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value.

Raises

Error: Only on an invalid precision or a checked size error.

sqrt¶

Source: apn_mojo/complex_ball/elementary.mojo

def sqrt(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the principal square root, with real part at least 0.

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every root; the negative real axis takes the root with a positive imaginary part.

Raises

Error: Only on an invalid precision or a checked size error.

stable_hash¶

Source: apn_mojo/complex_ball/math.mojo

def stable_hash(value: ComplexBall) raises -> UInt64

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

The algorithm is APNH-64: tag 7, then the real and imaginary balls, each encoded as for a Ball without its tag.

Arguments

• value (ComplexBall): The ball.

Returns

UInt64: The hash.

Raises

Error: Never in practice.

subtract¶

Source: apn_mojo/complex_ball/math.mojo

def subtract(
    left: ComplexBall,
    right: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of left - right.

Arguments

• left (ComplexBall): The first operand.
• right (ComplexBall): The second operand.
• context (Optional[BallContext]): The result precision; by default the operands' largest.

Returns

ComplexBall: A ball containing every difference.

Raises

Error: Only on an invalid precision or a checked size error.

tan¶

Source: apn_mojo/complex_ball/elementary.mojo

def tan(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the tangent, (sin 2x + i sinh 2y) / (cos 2x + cosh 2y).

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value; indeterminate when the rectangle may contain a pole.

Raises

Error: Only on an invalid precision or a checked size error.

tanh¶

Source: apn_mojo/complex_ball/elementary.mojo

def tanh(
    value: ComplexBall,
    *,
    context: Optional[BallContext] = None,
) raises -> ComplexBall

The ball of the hyperbolic tangent, (sinh 2x + i sin 2y) / (cosh 2x + cos 2y).

Arguments

• value (ComplexBall): The ball.
• context (Optional[BallContext]): The result precision; by default the ball's.

Returns

ComplexBall: A ball containing every value; indeterminate when the rectangle may contain a pole.

Raises

Error: Only on an invalid precision or a checked size error.

to_complex_if_certain¶

Source: apn_mojo/complex_ball/sets.mojo

def to_complex_if_certain(
    ball: ComplexBall,
    *,
    context: Optional[ComplexContext] = None,
) raises -> Optional[Complex]

The Complex that every point of the rectangle rounds to, when there is one: each part rounded in its own context.

Arguments

• ball (ComplexBall): The ball.
• context (Optional[ComplexContext]): The component formats, rounding modes and traps; by default each part's midpoint format, rounded to nearest-even.

Returns

Optional[Complex]: The Complex, or None when either part's ends round differently.

Raises

Error: On a trapped condition of either part.

union¶

Source: apn_mojo/complex_ball/sets.mojo

def union(a: ComplexBall, b: ComplexBall) raises -> ComplexBall

The least complex ball containing both rectangles.

Arguments

• a (ComplexBall): The first ball.
• b (ComplexBall): The second ball.

Returns

ComplexBall: The hull, part by part.

Raises

Error: Only on a checked size error.

Structs¶

ComplexBall¶

Source: apn_mojo/complex_ball/value.mojo

struct ComplexBall(ImplicitlyCopyable, Writable, _BatchElement)

A complex ball: the rectangle real x imag of two real balls.

A complex ball function returns a ball that contains the exact result for every point of its input rectangle. On a branch cut, a point takes the value of counter-clockwise continuity: the side a counter-clockwise circuit around the cut's finite branch point leaves. A rectangle that crosses a cut gets a result covering both sides. A function undefined somewhere in its input (log 0, division by a rectangle containing 0) is indeterminate.

Implements

Copyable, ImplicitlyCopyable, Writable, _BatchElement, _MapArgument

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

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

The rectangle of two real balls, or of exact numbers.

Arguments

• real (_BallArgument): The real part.
• imag (_BallArgument): The imaginary part.

Raises

Error: Only on a checked size error.

def __init__(
    out self,
    value: Complex,
    *,
    precision: Optional[Int] = None,
) raises

The exact ball of a Complex, or its parts rounded to precision.

Arguments

• value (Complex): The Complex; infinite or NaN parts raise.
• precision (Optional[Int]): The midpoint precision, in bits.

Raises

Error: For an infinite or NaN part.

def __init__(
    out self,
    value: ExactComplex,
    *,
    precision: Optional[Int] = None,
) raises

The ball of an ExactComplex: exact for binary fractions, otherwise rounded with a radius covering the error.

Arguments

• value (ExactComplex): The ExactComplex.
• precision (Optional[Int]): The midpoint precision, in bits.

Raises

Error: Only on a checked size error.

ComplexBall.from_json¶

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

Read a ComplexBall from its version-1 JSON record, without rounding.

Arguments

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

Returns

Self: The ComplexBall the record holds.

Raises

Error: When the text is not exactly that schema in canonical form.

ComplexBall.imag¶

def imag(self) -> Ball

The imaginary part.

Returns

Ball: The imaginary ball.

ComplexBall.is_exact¶

def is_exact(self) -> Bool

Whether both parts are exact.

Returns

Bool: True for an exact ball.

ComplexBall.is_finite¶

def is_finite(self) -> Bool

Whether both parts are finite.

Returns

Bool: True for a bounded rectangle.

ComplexBall.is_indeterminate¶

def is_indeterminate(self) -> Bool

Whether either part is indeterminate.

Returns

Bool: True for a ball without information.

ComplexBall.precision¶

def precision(self) -> Int

The larger midpoint precision of the two parts.

Returns

Int: The precision in bits.

ComplexBall.real¶

def real(self) -> Ball

The real part.

Returns

Ball: The real ball.

ComplexBall.same_representation¶

def same_representation(self, other: Self) -> Bool

Whether both parts have the same representation.

Arguments

• other (Self): The other ball.

Returns

Bool: True when the midpoints, radii and kinds agree.

ComplexBall.to_json¶

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

Write the version-1 JSON record: two complete Ball records.

Arguments

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

Returns

String: Compact canonical JSON.

Raises

Error: When the output exceeds limits.

ComplexBall.write_to¶

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

Write ComplexBall(real, imag) with both balls in midpoint-radius notation.

Arguments

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

Values and arithmetic¶

ComplexBall(real, imag) takes two balls or exact values, and the imaginary part defaults to 0. ComplexBall(z) of a finite Complex is exact; with precision=p each part is rounded to p bits, with a radius covering the error. ComplexBall of an ExactComplex is exact when both parts are binary fractions and otherwise encloses each part the same way. There is no implicit conversion into ComplexBall.

+, -, * and / follow the real ball formulas part by part; add, subtract, multiply and divide take a BallContext for the result precision. Dividing by a rectangle that contains 0 gives an indeterminate ball. conjugate negates the imaginary part exactly, and pow_int takes an Integer exponent of either sign. abs returns a real ball containing the modulus of every point, and angle one containing the argument: [0 +/- pi] for a rectangle that meets the negative real axis, where the argument jumps, and indeterminate for one that contains 0.

Elementary functions¶

exp, log, sqrt, pow, sin, cos, tan, sinh, cosh, tanh, asin, acos, atan, asinh, acosh and atanh return a rectangle that contains the function's value at every point of the input. The context sets the result precision, by default the input's.

A rectangle on a branch cut takes the counter-clockwise continuous value there, as the Complex functions do: log of an exact -2 has imaginary part pi, and sqrt(-2) is i sqrt 2. A rectangle that crosses a cut covers the values on both sides, since the function jumps there: log of a rectangle around -2 has an imaginary part from -pi to pi. A rectangle that contains a singularity gives an indeterminate ball: 0 for log, 1 and -1 for atanh, i and -i for atan, and a pole for tan.

Sets and conversion¶

contains, contains_zero and overlaps compare the exact endpoints of both parts. union returns the smallest rectangle containing both inputs. intersection returns their common rectangle, or None if they are disjoint. to_complex_if_certain(ball, context=c) returns the Complex that every point of the rectangle rounds to, part by part, or None when the parts' ends round differently.

Text, hashing and batches¶

The text form is ComplexBall(real, imag), with each part in the notation of apn_mojo.ball. same_representation compares stored midpoints and radii, and stable_hash gives the APNH-64 hash, tag 7, which never changes between releases. Batch[ComplexBall] holds complex balls, and vmap maps the functions over it. lift adds broadcasting, outer products, and ordered folds to binary functions, forwarding BallContext to each call. Scalar JSON uses a version-1 record containing two complete Ball records, real and imag. Saving and restoring it preserves the representation exactly.

ComplexBall batches also support NumPy-style elementwise functions and cumsum and cumprod. Use lift for other folds; arithmetic operators and batch JSON are not available.