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)[源代码]¶

Bases: Exception

Compilation error exception.

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

returncode = 0[源代码]¶

stderr = ''[源代码]¶

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)[源代码]¶

Compiler configuration.

Initialize the compiler configuration

参数:

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[源代码]¶: Generate the list of compiler flags.

DEFAULT_TEMPLATE = Multiline-String[源代码]¶

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[源代码]¶

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++'[源代码]¶

extra_flags = [][源代码]¶

include_paths = [][源代码]¶

lib_paths = [][源代码]¶

libraries = [][源代码]¶

opt_level = 'O2'[源代码]¶

std = 'c++17'[源代码]¶

template = Multiline-String[源代码]¶

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[源代码]¶

Clear the compilation cache

参数:: cache_dir -- Cache directory (defaults to the system temporary directory)
返回:: 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[源代码]¶

Compile C++ code into a shared library

参数:

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

返回:

Path of the compiled shared library (.so file)

抛出:

CompilationError -- Compilation failed
FileNotFoundError -- Compiler not found

PySparQ.pysparq.dynamic_operator.compiler.compute_code_hash(cpp_code: str, class_name: str, config: CompilerConfig) → str[源代码]¶

Compute the code hash used for caching

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

参数:

cpp_code -- User C++ code
class_name -- Operator class name
config -- Compiler configuration

返回:

A 16-character hexadecimal hash string

PySparQ.pysparq.dynamic_operator.compiler.find_project_root() → pathlib.Path | None[源代码]¶

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/

返回:: 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[源代码]¶

Format compiler error output

Simplifies file paths
Highlights error lines
Extracts the key error information

参数:

stderr -- Compiler standard error output
source_path -- Source file path

返回:

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[源代码]¶

Generate the complete C++ source file

参数:

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)

返回:

The complete C++ source code string

PySparQ.pysparq.dynamic_operator.compiler.get_cache_info(cache_dir: str | None = None) → dict[源代码]¶

Get cache information

参数:: cache_dir -- Cache directory
返回:: A dictionary with cache statistics

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