Math kernel generation

oracq.infrastructure.mathfunc.numeric

Fixed-point real/complex math decomposition and per-path propagated numeric status.

oracq.infrastructure.mathfunc.numeric.BOUNDS = {'acos': (-1.0, 1.0), 'acosh': (1.0, 4.0), 'asin': (-1.0, 1.0), 'asinh': (-4.0, 4.0), 'atan': (-1.0, 1.0), 'atanh': (-0.75, 0.75), 'cos': (-3.141592653589793, 3.141592653589793), 'cosh': (-2.0, 2.0), 'exp': (-2.0, 2.0), 'log': (0.25, 4.0), 'log10': (0.25, 4.0), 'sin': (-3.141592653589793, 3.141592653589793), 'sinh': (-2.0, 2.0), 'tan': (-1.0, 1.0), 'tanh': (-2.0, 2.0)}

Default Chebyshev approximation intervals for each math kernel, mapping function names to (lower bound, upper bound).

class oracq.infrastructure.mathfunc.numeric.MathConfig(degree=6, intervals=())

Bases: object

Math kernel generation configuration: polynomial degree and overridable approximation intervals.

Variables:

• degree (int) – Chebyshev polynomial degree, in the range 1..32.

• intervals (tuple[tuple[str, float, float], ...]) – Each entry is (function name, lower bound, upper bound), overriding the approximation interval of the named math kernel; kernels not listed use the default interval from BOUNDS.

Raises:

ValidationError – The degree is outside 1..32, or an interval references an unknown function, is duplicated, contains non-finite values, or has a lower bound not below the upper bound.

degree = 6

intervals = ()

bounds(kind)

Query the approximation interval of a named math kernel.

Parameters:

kind – Math function name, such as sin or exp.

Returns:

(lower bound, upper bound); the override entry in intervals wins, otherwise the default interval is used.

Return type:

tuple

Raises:

KeyError – The name is neither in intervals nor in BOUNDS.

class oracq.infrastructure.mathfunc.numeric.Numeric(kind, parts, status)

Bases: object

Generation-time circuit representation of a math value.

Variables:

• kind (str) – Value kind: real, complex or bool.

• parts (tuple[oracq.infrastructure.ir.Ref, ...]) – Tuple of register references carrying the value; complex uses (real part, imaginary part), others are unary.

• status (oracq.infrastructure.ir.Ref) – Reference to the 2-bit status register; bit 0 aggregates domain failures, bit 1 aggregates range/word-length overflows.

kind

parts

status

oracq.infrastructure.mathfunc.numeric.logic_operation(kind, width=1)

Construct the boolean network of a bitwise logic/select operation.

Parameters:

• kind – Operation name: not, flag, range_flag, and, or, xor or select.

• width – Input register bit width.

Returns:

The interface is a, b as needed and select, with output out;

flag and range_flag copy the condition bit into output bit 0 and bit 1 respectively.

Return type:

Operation

class oracq.infrastructure.mathfunc.numeric.NumericEmitter(builder, fmt, config)

Bases: object

Expands MIR numeric operations into fixed-point reversible circuits on a Builder.

Performs fixed-point arithmetic, bitwise logic and math kernel calls through Numeric values, tracks status bits per value, and at the end copies outputs and uncomputes all temporary registers.

Parameters:

• builder – The target circuit Builder.

• fmt – The fixed-point format FixedFormat; currently required to be signed.

• config – The math kernel generation configuration MathConfig.

Raises:

ValidationError – fmt is not a signed fixed-point format.

b

fmt

config

counter

constants

zero_status

local(width=None)

Allocate one math temporary register.

Parameters:

width – Bit width; the full width of the fixed-point format is used when omitted.

Returns:

The newly allocated register reference, named with an increasing number after the math_tmp_ prefix.

Return type:

Ref

invoke(op, arguments)

Copy overlapping read-only arguments to satisfy the alias-free RIR call ABI.

Parameters:

• op – The implemented operation to call.

• arguments – Mapping from formal parameter register names to actual argument views; read-only views that overlap each other are temporarily copied and uncomputed after the call.

logic(kind, *refs, select=None)

Invoke a bitwise logic/select network and return the result register.

Parameters:

• kind – Operation name, see logic_operation.

• refs – Register references participating in the operation; binary operations take the first two.

• select – The condition bit reference for the select operation.

Returns:

The new register reference holding the operation result.

Return type:

Ref

flags(*refs)

Merge several 2-bit status registers.

The all-zero zero_status does not participate in the merge; with no other input, zero_status itself is returned.

Parameters:

refs – Status register references.

Returns:

The status register reference obtained by bitwise-OR of the inputs.

Return type:

Ref

constant(value, kind=None)

Freeze a generation-time value into a circuit constant and cache it.

Complex values are split into two real constants with merged status; a real value beyond the representable magnitude of the format sets the range overflow bit. Identical (kind, value) pairs are encoded once.

Parameters:

• value – A bool, int, float or complex constant.

• kind – Explicit value kind; inferred from the Python type when omitted.

Returns:

The circuit representation of the constant.

Return type:

Numeric

as_complex(value)

Promote a real value to the complex representation.

Parameters:

value – A Numeric of real kind.

Returns:

The complex value with the imaginary part bound to constant 0, reusing the original status.

Return type:

Numeric

Raises:

ValidationError – The input is bool; implicit conversion to complex is not allowed.

component(value, index)

Extract the real or imaginary component of a complex value.

Parameters:

• value – A Numeric of real or complex kind.

• index – 0 selects the real part, 1 the imaginary part.

Returns:

The real component; taking the imaginary part of a real input returns constant 0.

Return type:

Numeric

arithmetic(kind, *values)

Invoke a fixed-point arithmetic network for a unary or binary operation.

Parameters:

• kind – Arithmetic name, such as add, sub, mul, div, sqrt, lt, eq.

• values – The Numeric operands of the operation.

Returns:

Comparisons yield bool, the rest real; the status merges the operand statuses with the newly produced flag bits.

Return type:

Numeric

unary(kind, value)

Expand a unary numeric operation.

real/imag extract complex components, not inverts bitwise, conj negates the imaginary part, and complex abs decomposes into a square-sum square root; the remaining arithmetic on complex inputs is decomposed per component and reassembled.

Parameters:

• kind – Operation name: real, imag, not, conj, abs, neg, or a fixed-point unary arithmetic name.

• value – The operand Numeric.

Returns:

The operation result.

Return type:

Numeric

complex(re, im)

Assemble a complex value from two real values.

Parameters:

• re – The real component.

• im – The imaginary component.

Returns:

The complex value whose status merges the two component statuses.

Return type:

Numeric

Raises:

ValidationError – Either component is not real.

binary(kind, a, b)

Expand the fixed-point and complex decompositions of a binary operation.

Boolean logic goes through the bitwise network, real values through fixed-point arithmetic; complex values decompose into real-component operations by algebraic identities, with division normalized by the squared modulus of the denominator.

Parameters:

• kind – Operation name: and, or, eq, add, sub, mul or div.

• a – Left operand Numeric.

• b – Right operand Numeric.

Returns:

The operation result.

Return type:

Numeric

Raises:

ValidationError – The complex decomposition hits an unknown operation name.

choose(test, yes, no)

Select between the circuit values of two branches bitwise by a boolean condition.

Branches mixing real and complex are first uniformly promoted to complex; the selection also applies to the status bits.

Parameters:

• test – The condition value of bool kind.

• yes – The branch value chosen when the condition is true.

• no – The branch value chosen when the condition is false.

Returns:

The result with the condition status merged with the selected branch status.

Return type:

Numeric

add_flag(value, test, *, domain=False)

Merge one condition bit into the status of a value.

Parameters:

• value – The value to flag; its parts stay unchanged, only the status is updated.

• test – The bool condition value.

• domain – When True the condition enters status bit 0 for domain failure, otherwise bit 1 for range overflow.

Returns:

The new value with the bit merged into its status.

Return type:

Numeric

kernel(name, value)

Invoke an elementary math kernel and merge its status flag.

Parameters:

• name – Math function name, such as sin, exp or log.

• value – The real input value.

Returns:

The real output value of the kernel, with status merging the input status and the kernel flag.

Return type:

Numeric

atan2(y, x)

Decompose the two-argument arctangent via magnitude ratio and quadrant selection.

Calls the atan kernel with the smaller of |x| and |y| as the dividend, then corrects the quadrant in turn by magnitude swap, the sign of x and the sign of y; returns zero when both inputs are zero.

Parameters:

• y – The ordinate real value.

• x – The abscissa real value.

Returns:

The angle value after quadrant correction.

Return type:

Numeric

integer_power(value, exponent)

Compute a constant integer power by the square-and-multiply algorithm.

Parameters:

• value – The base value.

• exponent – The integer exponent, with absolute value at most 128.

Returns:

The power result; negative exponents are computed as reciprocals.

Return type:

Numeric

Raises:

ValidationError – The absolute value of the exponent exceeds 128.

intrinsic(name, args, kind)

Expand the real and complex decompositions of a math intrinsic.

rect, phase, atan2, hypot and two-argument log are handled first; the real path goes through sqrt arithmetic or a math kernel, the complex path combines real kernels with algebraic identities, and log-type kernels additionally flag log(0) as a domain failure.

Parameters:

• name – The intrinsic function name.

• args – List of actual Numeric arguments.

• kind – The expected result kind, real or complex.

Returns:

The decomposed result value.

Return type:

Numeric

Raises:

ValidationError – A complex decomposition for the function is missing.

finish(outputs, status)

Finish the build after copying outputs and uncomputing all temporary registers.

Parameters:

• outputs – A sequence of (target reference tuple, output value Numeric) pairs.

• status – The 2-bit target register the aggregated status is written to.

Returns:

The fully built reversible module.

Return type:

Operation

oracq.infrastructure.mathfunc.numeric.elementary_kernel(name, fmt, config)

Generate the Chebyshev approximation kernel module of one elementary real function.

Samples degree+1 points on the configured interval to obtain the Chebyshev coefficients, combines them into a polynomial circuit via the Clenshaw recurrence, and sets the corresponding status bits for interval overflow and domain errors.

Parameters:

• name – Math function name; the same-named math function must exist and have a configured approximation interval.

• fmt – The fixed-point format.

• config – The MathConfig generation configuration.

Returns:

The reversible module with interface a, out, status; the sampling coefficient recipe

is recorded in the math_approximation attribute.

Return type:

Operation

Raises:

ValidationError – The approximation interval crosses the function domain.