Python Binding Layer (C++ Side)

pybind11 Binding Entry (the pysparq._core module generated from PySparQ/core.cpp)

Auxiliary macro definitions for the PySparQ binding layer.

Defines registration macros reused by the pybind11 binding module (core.cpp): batch binding of controllable methods (BIND_CONTROLLABLE_METHODS), operator class registration (BIND_BASE_OPERATOR / BIND_SELF_ADJOINT_OPERATOR / BIND_BASE_OPERATOR_SUBNAME), and dagger method binding (BIND_DAG_METHODS)

Defines

BIND_CONTROLLABLE_METHODS(CLASS_NAME)

Batch-bind the conditional control methods and condition-variable attributes of a controllable (ClassControllable) operator class.

Expands to a single .def(…) chain containing: the four condition_variable_* read-only attributes, the four groups of overloaded condition-setting methods conditioned_by_nonzeros / conditioned_by_all_ones / conditioned_by_bit / conditioned_by_value, and the corresponding clear_control_* clearing methods

Parameters:

  • CLASS_NAME – Name of the operator class whose controllable methods are to be bound

BIND_BASE_OPERATOR(NAME)

Register an operator class derived from BaseOperator.

Parameters:

  • NAME – C++ class name (also used as the exported Python class name)

BIND_SELF_ADJOINT_OPERATOR(NAME)

Register a self-adjoint operator class derived from SelfAdjointOperator.

On Windows, additionally binds call (operator()) explicitly to work around the issue with calling the inherited operator() from Python (see the English note above)

Parameters:

  • NAME – C++ class name (also used as the exported Python class name)

BIND_BASE_OPERATOR_SUBNAME(NAME, PYNAME)

Register an operator class derived from BaseOperator (with a custom Python class name)

Parameters:

  • NAME – C++ class name

  • PYNAME – Exported Python class name (may differ from the C++ class name)

BIND_DAG_METHODS(NAME)

Bind the dagger (adjoint/inverse) method dag(state) for an operator class.

Parameters:

  • NAME – C++ class name

namespace literals
namespace std

Binding Helper Macros (PySparQ/include/BindUtils.h)

Warning

doxygenfile: Cannot find file “BindUtils.h

Dynamic Operator Loader (PySparQ/pysparq/dynamic_operator/include/dynamic_operator_loader.h)

C++ dynamic operator loader.

Loads compiled dynamic libraries (.so/.dll) at runtime and retrieves operator factory functions

namespace pysparq

Typedefs

using CreateOperatorFunc = void *(*)()

Factory function type alias.

Signature of a factory function that creates BaseOperator-derived objects

Functions

template<typename FuncType>
FuncType get_typed_symbol(DynamicOperatorLoader &loader, const std::string &name)

Typed symbol retrieval helper.

Template Parameters:

FuncType – Function pointer type

Parameters:

  • loader – Dynamic library loader

  • name – Symbol name

Returns:

Typed function pointer, or nullptr on failure

class DynamicOperatorLoader
#include <dynamic_operator_loader.h>

Dynamic library loader.

Wraps platform-specific dynamic library loading, supporting Linux (dlopen), Windows (LoadLibrary), and macOS

Public Functions

explicit DynamicOperatorLoader(const std::string &lib_path)

Constructor, loads the specified dynamic library.

Parameters:

lib_path – Dynamic library file path (.so/.dll/.dylib)

~DynamicOperatorLoader()

Destructor, automatically unloads the dynamic library.

DynamicOperatorLoader(const DynamicOperatorLoader&) = delete
DynamicOperatorLoader &operator=(const DynamicOperatorLoader&) = delete
DynamicOperatorLoader(DynamicOperatorLoader &&other) noexcept
DynamicOperatorLoader &operator=(DynamicOperatorLoader &&other) noexcept
void *get_symbol(const std::string &name)

Retrieves a symbol (factory function) from the dynamic library.

Parameters:

name – Symbol name (e.g. “create_operator”)

Returns:

Pointer to the symbol, or nullptr on failure

bool is_valid() const

Checks whether the dynamic library was loaded successfully.

Returns:

true if loading succeeded, false if it failed

std::string get_error() const

Retrieves the most recent error message.

Returns:

Error description string, or an empty string when there is no error

const std::string &get_lib_path() const

Retrieves the dynamic library path.

Returns:

Library file path

Private Functions

void clear_error()

Clears the current error message.

void set_error_from_system()

Sets the error message (obtained from the system)

void close_library()

Closes the dynamic library (internal implementation)

Private Members

void *handle_

Dynamic library handle (platform-specific)

std::string lib_path_

Library file path.

std::string error_msg_

Error message.

Note

For the final interface that the binding layer exposes to Python, consult API Reference directly; for a usage guide on dynamic operators (runtime-compiled C++ operators), see Dynamic Operator Extension.

中文版 ===

Python 绑定层（C++ 侧）

pybind11 绑定入口（PySparQ/core.cpp 生成的 pysparq._core 模块）

Auxiliary macro definitions for the PySparQ binding layer.

Defines registration macros reused by the pybind11 binding module (core.cpp): batch binding of controllable methods (BIND_CONTROLLABLE_METHODS), operator class registration (BIND_BASE_OPERATOR / BIND_SELF_ADJOINT_OPERATOR / BIND_BASE_OPERATOR_SUBNAME), and dagger method binding (BIND_DAG_METHODS)

Defines

BIND_CONTROLLABLE_METHODS(CLASS_NAME)

Batch-bind the conditional control methods and condition-variable attributes of a controllable (ClassControllable) operator class.

Expands to a single .def(…) chain containing: the four condition_variable_* read-only attributes, the four groups of overloaded condition-setting methods conditioned_by_nonzeros / conditioned_by_all_ones / conditioned_by_bit / conditioned_by_value, and the corresponding clear_control_* clearing methods

Parameters:

  • CLASS_NAME – Name of the operator class whose controllable methods are to be bound

BIND_BASE_OPERATOR(NAME)

Register an operator class derived from BaseOperator.

Parameters:

  • NAME – C++ class name (also used as the exported Python class name)

BIND_SELF_ADJOINT_OPERATOR(NAME)

Register a self-adjoint operator class derived from SelfAdjointOperator.

On Windows, additionally binds call (operator()) explicitly to work around the issue with calling the inherited operator() from Python (see the English note above)

Parameters:

  • NAME – C++ class name (also used as the exported Python class name)

BIND_BASE_OPERATOR_SUBNAME(NAME, PYNAME)

Register an operator class derived from BaseOperator (with a custom Python class name)

Parameters:

  • NAME – C++ class name

  • PYNAME – Exported Python class name (may differ from the C++ class name)

BIND_DAG_METHODS(NAME)

Bind the dagger (adjoint/inverse) method dag(state) for an operator class.

Parameters:

  • NAME – C++ class name

namespace literals
namespace std

绑定辅助宏（PySparQ/include/BindUtils.h）

Warning

doxygenfile: Cannot find file “BindUtils.h

动态算子加载器（PySparQ/pysparq/dynamic_operator/include/dynamic_operator_loader.h）

C++ dynamic operator loader.

Loads compiled dynamic libraries (.so/.dll) at runtime and retrieves operator factory functions

namespace pysparq

Typedefs

using CreateOperatorFunc = void *(*)()

Factory function type alias.

Signature of a factory function that creates BaseOperator-derived objects

Functions

template<typename FuncType>
FuncType get_typed_symbol(DynamicOperatorLoader &loader, const std::string &name)

Typed symbol retrieval helper.

Template Parameters:

FuncType – Function pointer type

Parameters:

  • loader – Dynamic library loader

  • name – Symbol name

Returns:

Typed function pointer, or nullptr on failure

class DynamicOperatorLoader
#include <dynamic_operator_loader.h>

Dynamic library loader.

Wraps platform-specific dynamic library loading, supporting Linux (dlopen), Windows (LoadLibrary), and macOS

Public Functions

explicit DynamicOperatorLoader(const std::string &lib_path)

Constructor, loads the specified dynamic library.

Parameters:

lib_path – Dynamic library file path (.so/.dll/.dylib)

~DynamicOperatorLoader()

Destructor, automatically unloads the dynamic library.

DynamicOperatorLoader(const DynamicOperatorLoader&) = delete
DynamicOperatorLoader &operator=(const DynamicOperatorLoader&) = delete
DynamicOperatorLoader(DynamicOperatorLoader &&other) noexcept
DynamicOperatorLoader &operator=(DynamicOperatorLoader &&other) noexcept
void *get_symbol(const std::string &name)

Retrieves a symbol (factory function) from the dynamic library.

Parameters:

name – Symbol name (e.g. “create_operator”)

Returns:

Pointer to the symbol, or nullptr on failure

bool is_valid() const

Checks whether the dynamic library was loaded successfully.

Returns:

true if loading succeeded, false if it failed

std::string get_error() const

Retrieves the most recent error message.

Returns:

Error description string, or an empty string when there is no error

const std::string &get_lib_path() const

Retrieves the dynamic library path.

Returns:

Library file path

Private Functions

void clear_error()

Clears the current error message.

void set_error_from_system()

Sets the error message (obtained from the system)

void close_library()

Closes the dynamic library (internal implementation)

Private Members

void *handle_

Dynamic library handle (platform-specific)

std::string lib_path_

Library file path.

std::string error_msg_

Error message.

Note

绑定层暴露给 Python 的最终接口请直接查阅 API Reference； 动态算子（运行时编译 C++ 算子）的使用指南见 Dynamic Operator Extension。