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 — 控制隨機種子。
estimate_custom — 執行使用使用者提供的演算法、量子位元及程式碼參數的通用資源估計器。
QSharpError — 在 Q# 編譯或執行時錯誤中產生。
TargetProfile — 編譯目標剖面列舉。
Result， Pauli — Q# 原始型態。
CircuitGenerationMethod — 控制電路的合成方式。
StateDump， ShotResult — 直譯器輸出型別。
PauliNoise， DepolarizingNoise，， BitFlipNoise， — PhaseFlipNoise 用於模擬的噪音模型。

類別

BitFlipNoise	用於模擬的位元翻轉噪音。建立新的 BitFlipNoise 實例。位元翻轉通道會以機率 `p`施加 Pauli-X 誤差。
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 — 控制隨機種子。 estimate_custom — 執行使用使用者提供的演算法、量子位元及程式碼參數的通用資源估計器。 QSharpError — 在 Q# 編譯或執行時錯誤中產生。 TargetProfile — 編譯目標剖面列舉。 Result， Pauli — Q# 原始型態。 CircuitGenerationMethod — 控制電路的合成方式。 StateDump， ShotResult — 直譯器輸出型別。 PauliNoise， DepolarizingNoise，， BitFlipNoise， — PhaseFlipNoise 用於模擬的噪音模型。
DepolarizingNoise	模擬中用於去極化的噪音。建立新的 DepolarizingNoise 實例。去偏振通道會 `p / 3`以的機率分別施加 Pauli-X、Pauli-Y 或 Pauli-Z 錯誤。
Pauli	Q# Pauli 運算符。
PauliNoise	用於模擬的泡利雜訊表示為保利-X、泡利-Y及 Pauli-Z 誤差的機率建立 PauliNoise 一個新的實例，並以給定的錯誤機率。
PhaseFlipNoise	用於模擬的相位翻轉噪聲。建立新的 PhaseFlipNoise 實例。相位反轉通道會以機率 `p`施加 Pauli-Z 誤差。
QSharpError	Q# 直譯器回傳錯誤。
Result	Q# 測量結果。
ShotResult	一槍的單一結果。
StateDump	Q# 直譯器回傳了一個狀態 dump。
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

參數

名稱	Description
entry_expr	str 或 Callable 一種進入的表達方式。或者，也可以提供一個可呼叫的可呼叫（callable），必須是 Q# 可呼叫的。預設值: None
*args 必要	若有可調用者，則可傳遞參數。

僅限關鍵字的參數

名稱	Description
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

傳回

類型	Description
<xref:Circuit>	合成電路。

例外狀況

類型	Description
QSharpError	如果合成線路時發生錯誤。

compile

將 Q# 原始程式碼編譯成可提交至目標的程式。必須提供一個有參數的 entry expression 或 callable 的 callable。

範例：

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

參數

名稱	Description
entry_expr 必要	將做為程序進入點的 Q# 運算式。或者，也可以提供一個可呼叫的可呼叫（callable），必須是 Q# 可呼叫的。
*args 必要	若有可調用者，則可傳遞參數。

傳回

類型	Description
<xref:QirInputData>	編譯的程式。用 `str()` 來取得 QIR 串。

dump_circuit

會輸出一個顯示模擬器當前狀態的電路。

此線路將包含模擬器中已套用至目前點的閘門。

需要解譯器初始化為 trace_circuit=True。

dump_circuit() -> Circuit

傳回

類型	Description
<xref:Circuit>	目前的電路走線。

例外狀況

類型	Description
QSharpError	如果直譯器沒有初始化為 `trace_circuit=True`

dump_machine

會以 StateDump 物件回傳模擬器的稀疏狀態向量。

dump_machine() -> StateDump

傳回

類型	Description
StateDump	模擬器的狀態。

dump_operation

傳回代表所執行作業之複數的平方矩陣。

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

參數

名稱	Description
operation 必要	要執行的作業，該作業必須在量子位清單上運作。
num_qubits 必要	要使用的量子位數目。

傳回

類型	Description
List[List[complex]]	表示作業的矩陣。

estimate

估計 Q# 原始程式碼的資源。必須提供一個有參數的 entry expression 或 callable 的 callable。

自版本 This：函式後已棄用 ，使用舊有的資源估計器 API。請改用 qdk.qre。

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

參數

名稱	Description
entry_expr 必要	項目表達式。或者，也可以提供一個可呼叫的可呼叫（callable），必須是 Q# 可呼叫的。
params	要設定實體估計的參數。預設值: None
*args 必要	若有可調用者，則可傳遞參數。

傳回

類型	Description
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)

參數

名稱	Description
algorithm 必要
qubit 必要
qec 必要
factories	預設值: Ellipsis

僅限關鍵字的參數

名稱	Description
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

參數

名稱	Description
source 必要	要評估的 Q# 原始程式碼。

僅限關鍵字的參數

名稱	Description
save_events	若為真，所有輸出都會被儲存並回傳。若為虛假，則會刊登。預設值: False

傳回

類型	Description
Any	原始碼最後一個語句回傳的值，或如果為真則 `save_events` 是儲存的輸出。

例外狀況

類型	Description
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

僅限關鍵字的參數

名稱	Description
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 函數回傳電路的必要條件。電路函數不受此參數影響，且始終會產生電路。預設值: None

傳回

類型	Description
<xref:Config>	Q# 直譯器的設定。

logical_counts

從 Q# 原始碼中擷取邏輯資源計數。必須提供一個有參數的 entry expression 或 callable 的 callable。

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

參數

名稱	Description
entry_expr 必要	項目表達式。或者，也可以提供一個可呼叫的可呼叫（callable），必須是 Q# 可呼叫的。

傳回

類型	Description
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]

參數

名稱	Description
entry_expr 必要	項目表達式。或者，也可以提供一個可呼叫的可呼叫（callable），必須是 Q# 可呼叫的。
shots 必要	要跑的投籃次數。
*args 必要	若有可調用者，則可傳遞參數。
on_result 必要	一個回調函式，每個結果都會被呼叫。
save_events 必要	如果屬實，每次射擊的輸出都會被保存下來。若為虛假，則會刊登。
noise 必要	模擬中使用的噪音。
qubit_loss 必要	模擬中量子位元遺失的機率。
seed 必要	模擬中隨機數產生器的種子（如果有的話）。
type 必要	該使用的模擬器類型。若未指定，則會使用預設的稀疏狀態向量模擬。
num_qubits 必要	模擬類型「clifford」所使用的量子位元數量。若未指定，Clifford模擬器預設為1000量子位元。

僅限關鍵字的參數

名稱	Description
on_result	預設值: None
save_events	預設值: False
noise	預設值: None
qubit_loss	預設值: None
seed	預設值: None
type	預設值: None
num_qubits	預設值: None

傳回

類型	Description
List[Any]	一份結果或執行時錯誤的清單。若 `save_events` 為真，則回傳一個的 `ShotResult` 列表。

例外狀況

類型	Description
QSharpError	如果解譯輸入時發生錯誤。
ValueError	如果射擊次數少於1發，

set_classical_seed

設定用於標準函式庫經典隨機數運算的隨機數產生器的種子。這適用於所有執行、編譯或估算的 Q# 程式碼。

set_classical_seed(seed: int | None) -> None

參數

名稱	Description
seed 必要	經典隨機數產生器的種子。若為 N，種子將由熵生成。

set_quantum_seed

設定用於量子測量的隨機數產生器的種子。這適用於所有執行、編譯或估算的 Q# 程式碼。

set_quantum_seed(seed: int | None) -> None

參數

名稱	Description
seed 必要	這是用來做量子隨機數產生器的種子。若為 N，種子將由熵生成。