qsharp 模块

Q# 解释器公共 API。

此模块是包中 qdk Q# 解释器功能的公共图面。

密钥导出：

init — 初始化或重置 Q# 解释器。
eval — 计算 Q# 表达式并返回其值。
run — 为一个或多个镜头运行 Q# 条目表达式。
compile — 将 Q# 源编译为 QIR 进行硬件提交。
circuit — 从 Q# 代码合成线路图。
estimate — 估计量子资源（已弃用;改用 qre ）。
logical_counts — 从 Q# 代码中提取逻辑门计数。
dump_machine — 以 .. 的形式 StateDump返回当前模拟器状态。
dump_circuit — 返回跟踪线路（需要 trace_circuit=True 输入 init）。
dump_operation — 计算 Q# 运算的一元矩阵。
set_quantum_seed， set_classical_seed — 控制 RNG 种子。
estimate_custom — 使用用户提供的算法、量子比特和代码参数运行泛型资源估算器。
QSharpError — 在 Q# 编译或运行时错误上引发。
TargetProfile — 编译目标配置文件枚举。
Result， Pauli — Q# 基元类型。
CircuitGenerationMethod — 控制如何合成线路。
StateDump， ShotResult — 解释器输出类型。
PauliNoise、 DepolarizingNoise、 BitFlipNoise、 PhaseFlipNoise — 模拟的噪音模型。

类

BitFlipNoise	模拟中使用的位翻转噪音。创建新的 BitFlipNoise 实例。位翻转通道应用概率 Pauli-X 错误 `p`。
CircuitGenerationMethod	Q# 解释器公共 API。此模块是包中 `qdk` Q# 解释器功能的公共图面。密钥导出： init — 初始化或重置 Q# 解释器。 eval — 计算 Q# 表达式并返回其值。 run — 为一个或多个镜头运行 Q# 条目表达式。 compile — 将 Q# 源编译为 QIR 进行硬件提交。 circuit — 从 Q# 代码合成线路图。 estimate — 估计量子资源（已弃用;改用 qre ）。 logical_counts — 从 Q# 代码中提取逻辑门计数。 dump_machine — 以 .. 的形式 StateDump返回当前模拟器状态。 dump_circuit — 返回跟踪线路（需要 `trace_circuit=True` 输入 init）。 dump_operation — 计算 Q# 运算的一元矩阵。 set_quantum_seed， set_classical_seed — 控制 RNG 种子。 estimate_custom — 使用用户提供的算法、量子比特和代码参数运行泛型资源估算器。 QSharpError — 在 Q# 编译或运行时错误上引发。 TargetProfile — 编译目标配置文件枚举。 Result， Pauli — Q# 基元类型。 CircuitGenerationMethod — 控制如何合成线路。 StateDump， ShotResult — 解释器输出类型。 PauliNoise、 DepolarizingNoise、 BitFlipNoise、 PhaseFlipNoise — 模拟的噪音模型。
DepolarizingNoise	模拟中使用的去极化噪音。创建新的 DepolarizingNoise 实例。反极化通道应用 Pauli-X、Pauli-Y 或 Pauli-Z 错误，每个错误 `p / 3`都有概率。
Pauli	Q# Pauli 运算符。
PauliNoise	要用于模拟的 Pauli 噪音表示为 Pauli-X、Pauli-Y 和 Pauli-Z 错误的概率创建具有给定错误概率的新 PauliNoise 实例。
PhaseFlipNoise	模拟中使用的相位翻转噪音。创建新的 PhaseFlipNoise 实例。相位翻转通道应用概率 Pauli-Z 错误 `p`。
QSharpError	从 Q# 解释器返回的错误。
Result	Q# 度量结果。
ShotResult	拍摄的单个结果。
StateDump	从 Q# 解释器返回的状态转储。
TargetProfile	Q# 目标配置文件。目标配置文件描述将用于运行 Q# 程序的硬件或模拟器的功能。

函数

circuit

合成 Q# 程序的线路。必须提供条目表达式或操作。

circuit(entry_expr: str | Callable | GlobalCallable | Closure | None = None, *args, operation: str | None = None, generation_method: CircuitGenerationMethod | None = None, max_operations: int | None = None, source_locations: bool = False, group_by_scope: bool = True, prune_classical_qubits: bool = False) -> Circuit

参数

名称	说明
entry_expr	str 或 Callable 条目表达式。或者，可以提供可调用方，这必须是 Q# 可调用的。默认值: None
*args 必需	要传递给可调用项的参数（如果提供）。

仅限关键字的参数

名称	说明
operation	str 要合成的操作。这可以是操作的名称或 lambda 表达式。该操作必须仅采用量子比特或量子比特数组作为参数。默认值: None
generation_method	CircuitGenerationMethod 用于生成线路的方法。 ClassicalEval 评估线路生成时的传统控制流。 Simulate 运行完整的模拟来跟踪线路。 Static 使用部分评估，需要非`Unrestricted` 目标配置文件。 `None`默认为自动选择生成方法。默认值: None
max_operations	int 要包括在线路中的最大操作数。 `None`默认值表示没有限制。默认值: None
source_locations	bool 如果 `True`为每个门指定其源位置。默认值: False
group_by_scope	bool 如果 `True`按其包含的范围（如函数声明或循环块）对操作进行分组。默认值: True
prune_classical_qubits	bool 如果 `True`，则删除从未在量子门中使用的量子比特（例如仅用作经典控件的量子比特）。默认值: False

类型	说明
<xref:Circuit>	合成线路。

例外

类型	说明
QSharpError	如果合成线路时出错。

compile

将 Q# 源代码编译为可提交到目标的程序。必须提供条目表达式或具有参数的可调用项。

Example:

compile(entry_expr: str | Callable | GlobalCallable | Closure, *args) -> QirInputData

参数

名称	说明
entry_expr 必需	将用作程序的入口点的 Q# 表达式。或者，可以提供可调用方，这必须是 Q# 可调用的。
*args 必需	要传递给可调用项的参数（如果提供）。

类型	说明
<xref:QirInputData>	已编译的程序。用于 `str()` 获取 QIR 字符串。

dump_circuit

转储显示模拟器的当前状态的线路。

此线路将包含已在模拟器中应用到当前点的入口。

要求使用 trace_circuit=True 初始化解释器。

dump_circuit() -> Circuit

类型	说明
<xref:Circuit>	当前线路跟踪。

例外

类型	说明
QSharpError	如果未使用解释器初始化 `trace_circuit=True`

dump_machine

以 StateDump 对象的形式返回模拟器的稀疏状态向量。

dump_machine() -> StateDump

类型	说明
StateDump	模拟器的状态。

dump_operation

返回表示所执行的操作的复数的平方矩阵。

dump_operation(operation: str, num_qubits: int) -> List[List[complex]]

参数

名称	说明
operation 必需	要执行的操作，必须对量子比特列表进行操作。
num_qubits 必需	要使用的量子比特数。

类型	说明
List[List[complex]]	表示操作的矩阵。

estimate

估计 Q# 源代码的资源。必须提供条目表达式或具有参数的可调用项。

自版本以来已弃用此版本： 函数使用旧版资源估算器 API。改用 qdk.qre。

estimate(entry_expr: str | Callable | GlobalCallable | Closure, params: Dict[str, Any] | List | EstimatorParams | None = None, *args) -> EstimatorResult

参数

名称	说明
entry_expr 必需	条目表达式。或者，可以提供可调用方，这必须是 Q# 可调用的。
params	用于配置物理估计的参数。默认值: None
*args 必需	要传递给可调用项的参数（如果提供）。

类型	说明
EstimatorResult	估计的资源。

estimate_custom

estimate_custom(algorithm, qubit, qec, factories=Ellipsis, *, error_budget=0.01, max_factories=None, logical_depth_factor=None, max_physical_qubits=None, max_duration=None, error_budget_pruning=False)

参数

名称	说明
algorithm 必需
qubit 必需
qec 必需
factories	默认值: Ellipsis

仅限关键字的参数

名称	说明
error_budget	默认值: 0.01
max_factories	默认值: None
logical_depth_factor	默认值: None
max_physical_qubits	默认值: None
max_duration	默认值: None
error_budget_pruning	默认值: False

eval

评估 Q# 源代码。

输出打印到控制台。

eval(source: str, *, save_events: bool = False) -> Any

参数

名称	说明
source 必需	要评估的 Q# 源代码。

仅限关键字的参数

名称	说明
save_events	如果为 true，将保存并返回所有输出。如果为 false，则会打印它们。默认值: False

类型	说明
Any	源代码中最后一个语句返回的值，或保存的输出（如果 `save_events` 为 true）。

例外

类型	说明
QSharpError	如果评估源代码时出错。

init

初始化 Q# 解释器。

init(*, target_profile: TargetProfile = TargetProfile.Unrestricted, target_name: str | None = None, project_root: str | None = None, language_features: List[str] | None = None, trace_circuit: bool | None = None) -> Config

仅限关键字的参数

名称	说明
target_profile	设置目标配置文件允许 Q# 解释器生成与特定目标兼容的程序。请参阅 TargetProfile。默认值: Unrestricted
target_name	用于推断兼容target_profile设置的目标计算机的可选名称。默认值: None
project_root	包含 Q# 项目的根目录的可选路径。它必须包含 qsharp.json 项目清单。默认值: None
language_features	要启用的语言功能标志的可选列表。它们对应于实验性或预览版 Q# 语言功能。有效值为： `"v2-preview-syntax"`：启用 Q# v2 预览语法。这消除了对作用域内量子比特分配块形式（`use q = Qubit() { ... }`）的支持，而需要语句形式（`use q = Qubit();`）。它还消除了将 `set` 关键字用于可变变量赋值的要求。默认值: None
trace_circuit	启用在执行期间跟踪线路。 dump_circuit函数返回线路需要传递 True。线路函数不受此参数的影响，并且将始终生成线路。默认值: None

类型	说明
<xref:Config>	Q# 解释器配置。

logical_counts

从 Q# 源代码中提取逻辑资源计数。必须提供条目表达式或具有参数的可调用项。

logical_counts(entry_expr: str | Callable | GlobalCallable | Closure, *args) -> LogicalCounts

参数

名称	说明
entry_expr 必需	条目表达式。或者，可以提供可调用方，这必须是 Q# 可调用的。

类型	说明
LogicalCounts	按逻辑门计数对资源进行编程。

run

为给定的镜头数运行给定的 Q# 表达式。每个镜头使用模拟器的独立实例。

run(entry_expr: str | Callable | GlobalCallable | Closure, shots: int, *args, on_result: Callable[[ShotResult], None] | None = None, save_events: bool = False, noise: Tuple[float, float, float] | PauliNoise | BitFlipNoise | PhaseFlipNoise | DepolarizingNoise | NoiseConfig | None = None, qubit_loss: float | None = None, seed: int | None = None, type: Literal['sparse', 'clifford'] | None = None, num_qubits: int | None = None) -> List[Any]

参数

名称	说明
entry_expr 必需	条目表达式。或者，可以提供可调用方，这必须是 Q# 可调用的。
shots 必需	要运行的镜头数。
*args 必需	要传递给可调用项的参数（如果提供）。
on_result 必需	将随每个结果一起调用的回调函数。
save_events 必需	如果为 true，将保存每个镜头的输出。如果为 false，则会打印它们。
noise 必需	模拟中使用的噪音。
qubit_loss 必需	模拟中量子比特损失的概率。
seed 必需	模拟中用于随机数生成器的种子（如果有）。
type 必需	要使用的模拟器类型。如果未指定，将使用默认稀疏状态矢量模拟。
num_qubits 必需	要用于模拟类型“clifford”的量子比特数。如果未指定，则 Clifford 模拟器假定默认为 1000 个量子比特。

仅限关键字的参数

名称	说明
on_result	默认值: None
save_events	默认值: False
noise	默认值: None
qubit_loss	默认值: None
seed	默认值: None
type	默认值: None
num_qubits	默认值: None

类型	说明
List[Any]	结果或运行时错误的列表。如果 `save_events` 为 true，则返回列表 `ShotResult` 。

例外

类型	说明
QSharpError	如果解释输入时出错。
ValueError	如果拍摄次数小于 1。

set_classical_seed

设置用于标准库经典随机数运算的随机数生成器的种子。这适用于执行、编译或估计的所有 Q# 代码。

set_classical_seed(seed: int | None) -> None

参数

名称	说明
seed 必需	用于经典随机数生成器的种子。如果为 None，则种子将从 entropy 生成。

set_quantum_seed

设置用于量子度量的随机数生成器的种子。这适用于执行、编译或估计的所有 Q# 代码。

set_quantum_seed(seed: int | None) -> None

参数

名称	说明
seed 必需	要用于量子随机数生成器的种子。如果为 None，则种子将从 entropy 生成。