Math-function compilation entry

oracq.infrastructure.mathfunc

Compilation entry point for pure Python math functions.

oracq.infrastructure.mathfunc.compile_function(function, *, fmt=None, inputs=None, constants=None, helpers=None, output_names=None, config=None, max_unroll=128, entry=None)[source]

Compile an ordinary pure Python function into a reversible quantum module in one step.

The frontend first interprets the restricted AST into MIR, which is then lowered to modular RIR under the fixed-point format and math kernel configuration.

Parameters:

  • function – An ordinary Python function object, or a source string containing several defs and math/cmath imports; the module docstring and __future__ imports are ignored.

  • fmt – FixedFormat fixed-point format; FixedFormat(12, 6) is used when omitted.

  • inputs – Mapping from parameter names to real/complex/bool or Index(width); inferred from annotations when omitted.

  • constants – Mapping from parameter names to finite numeric values, bound as generation-time constants.

  • helpers – Helper functions appended to the entry namespace.

  • output_names – Output register names of the entry’s return values; when omitted a single return is out and multiple returns are out_0, out_1 and so on.

  • config – MathConfig math kernel degree and approximation interval configuration; the default configuration is used when omitted.

  • max_unroll – Maximum number of iterations a static range loop may unroll.

  • entry – Entry function name for the source-string form; the last def is used when omitted.

Returns:

The compilation result, carrying the reversible module, the original MIR and the input/output layouts.

Return type:

CompiledFunction

Raises:

  • FunctionCompileError – The source has a syntax error or contains statements the frontend does not support.

  • ValidationError – Validation of input kinds, the fixed-point format or the lowering stage failed.

oracq.infrastructure.mathfunc.lower_math_ir(program, *, fmt=None, config=None, output_names=None)[source]

Lower an already constructed MIR program into a reversible RIR module under the given generation configuration.

Parameters:

  • program – The MathProgram to lower; fully validated when the lowerer is constructed.

  • fmt – FixedFormat fixed-point format; FixedFormat(12, 6) is used when omitted.

  • config – MathConfig math kernel degree and approximation interval configuration; the default configuration is used when omitted.

  • output_names – Output register names of the entry’s return values; named automatically by the number of return values when omitted.

Returns:

The compilation result of the entry function.

Return type:

CompiledFunction

Raises:

ValidationError – MIR validation failed, or lowering-stage layout and fixed-point format validation failed.

class oracq.infrastructure.mathfunc.CompiledFunction(operation, math_ir, fmt, output_names, input_layout, output_layout)[source]

Bases: object

The complete result of one math function compilation.

Variables:

  • operation (oracq.infrastructure.builder.Operation) – The lowered reversible Operation; inputs stay unchanged, outputs and status are XOR-written back.

  • math_ir (oracq.infrastructure.mathfunc.graph.MathProgram) – The original MathProgram object that produced the module.

  • fmt (oracq.algorithms.common.arithmetic.FixedFormat) – The FixedFormat fixed-point format used for generation.

  • output_names (tuple[str, ...]) – The output port names of the entry’s return values.

  • input_layout (tuple[tuple[str, tuple[str, ...]], ...]) – Mapping from each logical input to its expanded physical register names; each entry is (parameter name, (register name, …)).

  • output_layout (tuple[tuple[str, tuple[str, ...]], ...]) – Mapping from each logical output to its expanded physical register names, structured like input_layout.

operation
math_ir
fmt
output_names
input_layout
output_layout
program()[source]

Return the full RIR program of the compilation result.

Returns:

The program merging the entry module and its dependency modules; semantics match Operation.program.

Return type:

Program

exception oracq.infrastructure.mathfunc.FunctionCompileError[source]

Bases: ValidationError

Exception raised when the math function frontend fails to parse or compile restricted Python source.

class oracq.infrastructure.mathfunc.MathProgram(entry, functions, version='0.1')[source]

Bases: object

MIR 0.1 top-level object: the entry function symbol and the full function table.

Variables:

  • entry (str) – The entry function’s symbol name, which must appear in functions.

  • functions (tuple[oracq.infrastructure.mathfunc.graph.MathFunction, ...]) – Immutable tuple of all MathFunction objects.

  • version (str) – The MIR version number, currently 0.1.

entry
functions
version = '0.1'
property function_map

Mapping from function symbol names to MathFunction.

validate()[source]

Check the program’s structural and type constraints and return self.

Covers the version number, function table immutability and entry validity, parameter uniqueness and kinds, sequential SSA references, operation arities and type promotion, constant finiteness, call interface consistency, and acyclicity of the function graph.

Returns:

Self, once validation has passed.

Return type:

MathProgram

Raises:

ValidationError – Any structural or type constraint is violated.

dumps()[source]

Validate first, then serialize the program into canonical JSON text.

Returns:

JSON text with sorted keys, two-space indentation and a trailing newline; non-ASCII characters are kept verbatim.

Return type:

str

Raises:

ValidationError – The program failed validation.

classmethod loads(text)[source]

Deserialize and validate an MIR program from JSON text.

Parameters:

text – JSON text produced by MathProgram.dumps.

Returns:

The validated program object.

Return type:

MathProgram

Raises:

ValidationError – The text is not valid MIR JSON, or failed validation.

class oracq.infrastructure.mathfunc.MathConfig(degree=6, intervals=())[source]

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)[source]

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.Index(width)[source]

Bases: object

Bit width declaration of an unsigned integer index parameter, for the inputs mapping.

Provides a shorter public register for unsigned integers such as row and column indices; it is converted to the current fixed-point representation when entering math computation, and the format must hold its full range.

Variables:

width (int) – Unsigned bit width, in the range 1..64.

width