PySparQ.pysparq.dynamic_operator.compiler¶

运行时 C++ 代码编译系统

提供动态编译用户自定义 C++ 算子的功能，支持： - 自动生成代码框架 - 调用 g++ 编译为共享库 (.so) - 代码哈希缓存机制，避免重复编译 - 编译错误捕获和格式化

Exceptions¶

CompilationError

编译错误异常

Classes¶

CompilerConfig

编译器配置

Functions¶

`clear_cache`(→ int)	清除编译缓存
`compile_cpp_code`(→ str)	编译 C++ 代码为共享库
`compute_code_hash`(→ str)	计算代码哈希值，用于缓存
`find_project_root`(→ Optional[pathlib.Path])	查找项目根目录或已安装的包目录
`format_compile_error`(→ str)	格式化编译错误输出
`generate_cpp_source`(→ str)	生成完整的 C++ 源文件
`get_cache_info`(→ dict)	获取缓存信息
`quick_compile`(→ str)	快速编译 C++ 算子代码

Module Contents¶

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

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

编译器配置

初始化编译器配置

参数:

cxx -- C++ 编译器命令（默认 g++）
std -- C++ 标准版本（默认 c++17）
opt_level -- 优化级别（默认 O2）
include_paths -- 额外的头文件搜索路径
lib_paths -- 额外的库文件搜索路径
libraries -- 需要链接的库
extra_flags -- 额外的编译器标志
template -- 自定义代码模板

get_compile_flags() → list[源代码]¶: 生成编译器标志列表

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 调用辅助函数 - 应用算子到 SparseState
// Python 侧通过 state._cpp_ptr() 获取 C++ SparseState* 指针，
// ctypes 将其作为 ctypes.c_void_p 传递。
extern "C" void apply_operator(BaseOperator* op, SparseState* state) {{
    if (op && state) {{
        (*op)(*state);
    }}
}}

// Python 调用辅助函数 - 应用 dagger
extern "C" void apply_operator_dag(BaseOperator* op, SparseState* state) {{
    if (op && state) {{
        op->dag(*state);
    }}
}}

// 获取基类类型
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[源代码]¶

清除编译缓存

参数:: cache_dir -- 缓存目录（默认使用系统临时目录）
返回:: 删除的文件数量

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

编译 C++ 代码为共享库

参数:

cpp_code -- 用户提供的 C++ 代码（包含类定义）
class_name -- 算子类名
cache_dir -- 缓存目录（默认使用系统临时目录）
ctor_params -- 构造函数参数声明
ctor_args -- 构造函数参数调用
config -- 编译器配置
project_root -- 项目根目录（自动检测）
verbose -- 是否输出详细日志

返回:

编译后的共享库路径 (.so 文件)

抛出:

CompilationError -- 编译失败
FileNotFoundError -- 找不到编译器

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

计算代码哈希值，用于缓存

哈希包括：代码内容、类名、编译器版本和配置

参数:

cpp_code -- 用户 C++ 代码
class_name -- 算子类名
config -- 编译器配置

返回:

16 字符的十六进制哈希字符串

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

对于已安装的包，目录结构为: - site-packages/pysparq/ (Python包) - site-packages/include/ (头文件，包含 basic_components.h)

对于源代码目录: - 项目根目录包含 SparQ/ 和 PySparQ/

返回:: 项目根目录路径或已安装的包目录，未找到返回 None

PySparQ.pysparq.dynamic_operator.compiler.format_compile_error(stderr: str, source_path: str) → str[源代码]¶

格式化编译错误输出

简化文件路径
高亮错误行
提取关键错误信息

参数:

stderr -- 编译器标准错误输出
source_path -- 源文件路径

返回:

格式化后的错误信息

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

生成完整的 C++ 源文件

参数:

cpp_code -- 用户提供的 C++ 代码（包含类定义）
class_name -- 算子类名
ctor_params -- 构造函数参数声明（如 "int n, double theta"）
ctor_args -- 构造函数参数调用（如 "n, theta"）
config -- 编译器配置（使用模板）

返回:

完整的 C++ 源代码字符串

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

获取缓存信息

参数:: cache_dir -- 缓存目录
返回:: 包含缓存统计信息的字典

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

快速编译 C++ 算子代码

参数:

class_code -- 包含类定义的 C++ 代码
class_name -- 类名
verbose -- 是否输出详细日志

返回:

共享库文件路径