PySparQ.pysparq.dynamic_operator.compiler

Runtime C++ code compilation system

Provides the ability to compile user-defined C++ operators at runtime, with support for: - Automatic code skeleton generation - Invoking g++ to build a shared library (.so) - Code hash based caching to avoid redundant compilation - Compilation error capture and formatting

Exceptions

CompilationError

Compilation error exception.

Classes

CompilerConfig

Compiler configuration.

Functions

clear_cache(→ int)

Clear the compilation cache

compile_cpp_code(→ str)

Compile C++ code into a shared library

compute_code_hash(→ str)

Compute the code hash used for caching

find_project_root(→ Optional[pathlib.Path])

Locate the project root directory or the installed package directory

format_compile_error(→ str)

Format compiler error output

generate_cpp_source(→ str)

Generate the complete C++ source file

get_cache_info(→ dict)

Get cache information

quick_compile(→ str)

Quickly compile C++ operator code

Module Contents

exception PySparQ.pysparq.dynamic_operator.compiler.CompilationError(message: str, stderr: str = '', returncode: int = 0)[source]

Bases: Exception

Compilation error exception.

Initialize self. See help(type(self)) for accurate signature.

returncode = 0[source]
stderr = ''[source]
class PySparQ.pysparq.dynamic_operator.compiler.CompilerConfig(cxx: str = 'g++', std: str = 'c++17', opt_level: str = 'O2', include_paths: list | None = None, lib_paths: list | None = None, libraries: list | None = None, extra_flags: list | None = None, template: str | None = None)[source]

Compiler configuration.

Initialize the compiler configuration

Parameters:

  • cxx – C++ compiler command (default g++)

  • std – C++ standard version (default c++17)

  • opt_level – Optimization level (default O2)

  • include_paths – Extra header search paths

  • lib_paths – Extra library search paths

  • libraries – Libraries to link against

  • extra_flags – Extra compiler flags

  • template – Custom code template

get_compile_flags() → list[source]

Generate the list of compiler flags.

DEFAULT_TEMPLATE = Multiline-String[source]
Show Value
"""#include "basic_components.h"
#include <vector>
#include <complex>

using namespace qram_simulator;

{USER_CPP_CODE}

extern "C" BaseOperator* create_operator({CTOR_PARAMS}) {{
    return new {CLASS_NAME}({CTOR_ARGS});
}}

extern "C" void destroy_operator(BaseOperator* op) {{
    delete op;
}}

extern "C" const char* get_operator_name() {{
    return "{CLASS_NAME}";
}}
"""
PYTHON_TEMPLATE = Multiline-String[source]
Show Value
"""#include "basic_components.h"
#include <vector>
#include <complex>

using namespace qram_simulator;

{USER_CPP_CODE}

extern "C" BaseOperator* create_operator({CTOR_PARAMS}) {{
    return new {CLASS_NAME}({CTOR_ARGS});
}}

extern "C" void destroy_operator(BaseOperator* op) {{
    delete op;
}}

extern "C" const char* get_operator_name() {{
    return "{CLASS_NAME}";
}}

// Python call helper - applies the operator to a SparseState
// The Python side obtains the C++ SparseState* pointer via state._cpp_ptr(),
// which ctypes passes as ctypes.c_void_p.
extern "C" void apply_operator(BaseOperator* op, SparseState* state) {{
    if (op && state) {{
        (*op)(*state);
    }}
}}

// Python call helper - applies the dagger
extern "C" void apply_operator_dag(BaseOperator* op, SparseState* state) {{
    if (op && state) {{
        op->dag(*state);
    }}
}}

// Returns the base class type
extern "C" const char* get_base_class() {{
    return "{BASE_CLASS}";
}}
"""
cxx = 'g++'[source]
extra_flags = [][source]
include_paths = [][source]
lib_paths = [][source]
libraries = [][source]
opt_level = 'O2'[source]
std = 'c++17'[source]
template = Multiline-String[source]
Show Value
"""#include "basic_components.h"
#include <vector>
#include <complex>

using namespace qram_simulator;

{USER_CPP_CODE}

extern "C" BaseOperator* create_operator({CTOR_PARAMS}) {{
    return new {CLASS_NAME}({CTOR_ARGS});
}}

extern "C" void destroy_operator(BaseOperator* op) {{
    delete op;
}}

extern "C" const char* get_operator_name() {{
    return "{CLASS_NAME}";
}}
"""
PySparQ.pysparq.dynamic_operator.compiler.clear_cache(cache_dir: str | None = None) → int[source]

Clear the compilation cache

Parameters:

cache_dir – Cache directory (defaults to the system temporary directory)

Returns:

The number of deleted files

PySparQ.pysparq.dynamic_operator.compiler.compile_cpp_code(cpp_code: str, class_name: str, cache_dir: str | None = None, ctor_params: str = '', ctor_args: str = '', config: CompilerConfig | None = None, project_root: str | None = None, verbose: bool = False) → str[source]

Compile C++ code into a shared library

Parameters:

  • cpp_code – User-provided C++ code (containing the class definition)

  • class_name – Operator class name

  • cache_dir – Cache directory (defaults to the system temporary directory)

  • ctor_params – Constructor parameter declarations

  • ctor_args – Constructor call arguments

  • config – Compiler configuration

  • project_root – Project root directory (auto-detected)

  • verbose – Whether to print verbose logs

Returns:

Path of the compiled shared library (.so file)

Raises:
PySparQ.pysparq.dynamic_operator.compiler.compute_code_hash(cpp_code: str, class_name: str, config: CompilerConfig) → str[source]

Compute the code hash used for caching

The hash covers: code content, class name, compiler version, and configuration

Parameters:

  • cpp_code – User C++ code

  • class_name – Operator class name

  • config – Compiler configuration

Returns:

A 16-character hexadecimal hash string

PySparQ.pysparq.dynamic_operator.compiler.find_project_root() → pathlib.Path | None[source]

Locate the project root directory or the installed package directory

For an installed package, the directory layout is: - site-packages/pysparq/ (Python package) - site-packages/include/ (headers, including basic_components.h)

For a source checkout (the SparQSim repository): - The project root contains extern/qram-simulator/ (C++ core submodule) and PySparQ/

Returns:

The project root path or the installed package directory; None if not found

PySparQ.pysparq.dynamic_operator.compiler.format_compile_error(stderr: str, source_path: str) → str[source]

Format compiler error output

  • Simplifies file paths

  • Highlights error lines

  • Extracts the key error information

Parameters:

  • stderr – Compiler standard error output

  • source_path – Source file path

Returns:

The formatted error message

PySparQ.pysparq.dynamic_operator.compiler.generate_cpp_source(cpp_code: str, class_name: str, ctor_params: str = '', ctor_args: str = '', config: CompilerConfig | None = None) → str[source]

Generate the complete C++ source file

Parameters:

  • cpp_code – User-provided C++ code (containing the class definition)

  • class_name – Operator class name

  • ctor_params – Constructor parameter declarations (e.g. “int n, double theta”)

  • ctor_args – Constructor call arguments (e.g. “n, theta”)

  • config – Compiler configuration (provides the template)

Returns:

The complete C++ source code string

PySparQ.pysparq.dynamic_operator.compiler.get_cache_info(cache_dir: str | None = None) → dict[source]

Get cache information

Parameters:

cache_dir – Cache directory

Returns:

A dictionary with cache statistics

PySparQ.pysparq.dynamic_operator.compiler.quick_compile(class_code: str, class_name: str, verbose: bool = False) → str[source]

Quickly compile C++ operator code

Parameters:

  • class_code – C++ code containing the class definition

  • class_name – Class name

  • verbose – Whether to print verbose logs

Returns:

The shared library file path