Context 類別

一個獨立的 Q# 直譯器環境。

Context 提供一個自包含的 Q# 執行環境，讓程式碼在獨立於其他 Context 實例中被評估、編譯與執行。每個情境都維護自己的代號空間。

上下文有一個 code屬性，這是一個包含在此上下文中定義的所有 Q# 操作與型別的Python模組。這讓你能從 Python 呼叫 Q# 操作。

範例：


   ctx = qdk.Context()
   ctx.eval("operation Main() : Result { use q = Qubit(); X(q); MResetZ(q) }")
   assert ctx.run("Main()", 2) == [qdk.Result.One, qdk.Result.One]
   assert ctx.code.Main() == qdk.Result.One

初始化一個新的孤立 Q# 上下文。

建構函式

Context(*, 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, _is_global_context: bool = False)

僅限關鍵字的參數

名稱	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	預設值: None
_is_global_context	預設值: False

方法

circuit	合成 Q# 程序的線路。必須提供項目表達式或作業。
compile	將 Q# 原始程式碼編譯成可提交至目標的程式。必須提供一個有參數的 entry expression 或 callable 的 callable。範例：
dump_machine	會以 StateDump 物件回傳模擬器的稀疏狀態向量。
eval	評估 Q# 原始程式碼。輸出會列印至主控台。
get_target_profile	回傳此上下文的目標設定檔。
import_openqasm	將 OpenQASM 原始碼匯入此上下文的直譯器。
logical_counts	從 Q# 原始碼中擷取邏輯資源計數。必須提供一個有參數的 entry expression 或 callable 的 callable。
run	針對指定的拍攝次數執行指定的 Q# 運算式。每個拍攝都會使用模擬器的獨立實例。
set_classical_seed	設定用於標準函式庫經典隨機數運算的隨機數產生器的種子。此規則適用於本情境下所有執行、編譯或估算的 Q# 程式碼。
set_quantum_seed	設定用於量子測量的隨機數產生器的種子。此規則適用於本情境下所有執行、編譯或估算的 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_machine

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

dump_machine() -> StateDump

傳回

類型	Description
StateDump	模擬器的狀態。

eval

評估 Q# 原始程式碼。

輸出會列印至主控台。

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

參數

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

僅限關鍵字的參數

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

傳回

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

例外狀況

類型	Description
QSharpError	如果在評估原始碼時出現錯誤，

get_target_profile

回傳此上下文的目標設定檔。

get_target_profile() -> TargetProfile

import_openqasm

將 OpenQASM 原始碼匯入此上下文的直譯器。

import_openqasm(source: str, **kwargs: Any) -> Any

參數

名稱 Description

名稱	Description
source 必要	str 一個 OpenQASM 程式或片段。
**kwargs 必要	額外的關鍵字論點。常見選項： `name` （STR）：這個計畫的名稱。這是該計畫的入門點。 `search_path` （str）：用於解析檔案參考的可選搜尋路徑。 `output_semantics` （OutputSemantics）：編譯的輸出語意。 `program_type` （程式類型）：要執行的程式編譯類型： `ProgramType.Operation` （預設）：來源成為全域命名空間中的 Q# 操作，包含任何宣告的經典輸入參數及每個宣告量子位元的參數，而任何顯式或隱式輸出宣告則成為操作的回傳型別。 `ProgramType.File`：將輸入來源視為獨立程式，並在命名空間中建立 `qasm_import` 一個操作，只接受經典參數，內部分配所需的量子位元，並在操作結束時釋放它們。 `ProgramType.Fragments`：在目前互動直譯器中執行所提供的原始碼，定義當前作用域中任何宣告的變數或操作，並回傳原始碼中最後一個陳述式的值。

source

必要

str

一個 OpenQASM 程式或片段。

**kwargs

必要

額外的關鍵字論點。常見選項：

name （STR）：這個計畫的名稱。這是該計畫的入門點。
search_path （str）：用於解析檔案參考的可選搜尋路徑。
output_semantics （OutputSemantics）：編譯的輸出語意。
program_type （程式類型）：要執行的程式編譯類型：
- ProgramType.Operation （預設）：來源成為全域命名空間中的 Q# 操作，包含任何宣告的經典輸入參數及每個宣告量子位元的參數，而任何顯式或隱式輸出宣告則成為操作的回傳型別。
- ProgramType.File：將輸入來源視為獨立程式，並在命名空間中建立 qasm_import 一個操作，只接受經典參數，內部分配所需的量子位元，並在操作結束時釋放它們。
- ProgramType.Fragments：在目前互動直譯器中執行所提供的原始碼，定義當前作用域中任何宣告的變數或操作，並回傳原始碼中最後一個陳述式的值。

傳回

類型	Description
Any	原始碼最後一個陳述句回傳的值。

例外狀況

類型	Description
QasmError	如果在產生、解析或分析 OpenQASM 原始碼時出現錯誤，
QSharpError	如果程式編譯時出現錯誤，

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，種子將由熵生成。

屬性

code

code: Any