Native implementation registry

oracq.infrastructure.native

Registration of PySparQ module-level implementations; runtime capabilities do not masquerade as gate-level closure.

class oracq.infrastructure.native.NativeSite(module, arguments, resources)[source]

Bases: object

A module call site in the execution flow taken over by a native implementation.

Variables:

  • module (oracq.infrastructure.ir.Module) – declaration of the called module.

  • arguments (tuple[oracq.infrastructure.ir.Ref, ...]) – argument views corresponding one-to-one with the module registers.

  • resources (tuple[str, ...]) – resource binding names corresponding one-to-one with the module resources.

module
arguments
resources
class oracq.infrastructure.native.NativeEntry(module, factory, label, kind)[source]

Bases: object

A native implementation registration entry under one module name.

Variables:

  • module (oracq.infrastructure.ir.Module) – module description declared at registration, used to compare against same-named modules in programs.

  • factory (collections.abc.Callable) – implementation factory only called with a NativeContext argument at execution time.

  • label (str) – implementation name displayed in execution reports.

  • kind (str) – implementation category tag, pysparq_custom by default.

module
factory
label
kind
class oracq.infrastructure.native.NativeRegistry[source]

Bases: object

Register PySparQ module-level native implementations by module name and verify coverage against programs.

entries
register(operation, factory, *, label=None, kind='pysparq_custom')[source]

Register the native implementation of one module.

Parameters:

  • operation – Operation or Module providing the module declaration.

  • factory – factory called with a NativeContext argument at execution time; heavy work such as C++ compilation is deferred inside the factory as needed, not done at registration.

  • label – display name of the implementation in execution reports; the module name is used when omitted.

  • kind – implementation category tag.

Returns:

returns itself to support chained registration.

Return type:

NativeRegistry

Raises:

ValidationError – the module name is already registered with different content.

matching(program)[source]

Compute the set of module names in a program taken over by native implementations.

Parameters:

program – program to verify.

Returns:

module names that match a registered entry by name and module declaration.

Return type:

frozenset[str]

Raises:

ValidationError – a same-named module does not match the declaration at registration.

missing(program)[source]

List entry-reachable open declaration module names not yet covered by native implementations.

Parameters:

program – program to check.

Returns:

open declaration module names sorted by name; an empty tuple when there is no gap.

Return type:

tuple[str, …]

Raises:

ValidationError – the program failed RIR structural validation.

class oracq.infrastructure.native.NativeContext(ps, site, names, qrams, memories)[source]

Bases: object

Execution environment passed to native factories, bridging RIR formal parameters and PySparQ runtime objects.

Variables:

  • ps (object) – currently imported pysparq module.

  • site (oracq.infrastructure.native.NativeSite) – native call site being executed.

  • names (dict) – mapping from RIR register names to PySparQ register names.

  • qrams (dict) – mapping from resource names to PySparQ QRAM objects.

  • memories (dict) – mapping from resource names to sparse word data dicts.

ps
site
names
qrams
memories
register_id(parameter)[source]

Resolve a quantum formal parameter of the module to a PySparQ integer register id.

Parameters:

parameter – module register formal parameter name.

Returns:

id given by PySparQ System.get_id for the corresponding register.

Raises:

ValidationError – the argument is not a single view covering exactly one whole register, such as a slice or concatenation.

qram(parameter)[source]

Resolve a resource formal parameter of the module to the QRAM object bound at this call site.

Parameters:

parameter – module resource formal parameter name.

Returns:

PySparQ QRAM object bound to this formal parameter.

class oracq.infrastructure.native.DynamicCppFactory(name, source, parameters, *, cache_dir, base_class='SelfAdjointOperator')[source]

Bases: object

Calls the real compile_operator on demand; C++ code is not written into RIR.

name
source
parameters
cache_dir
base_class