プロジェクトを操作する Q# 方法

[アーティクル]
10/29/2024

Azure Quantum Development Kitでは、プロジェクトを定義 Q# できます。プロジェクトは、互いの操作と機能にアクセスできる複数 Q# のファイルを含むフォルダー構造です。プロジェクトは、ソースコードを論理的に整理するのに役立ちます。外部ソースからアクセスできる外部依存関係またはカスタムライブラリとしてプロジェクトを使用することもできます。

Q#プロジェクトには、qsharp.jsonという名前のマニフェストファイルと、指定したフォルダー構造内の 1 つ以上の *.qs ファイルが含まれていますQ#。ユーザーが VS Code で *.qs ファイルを開くか、Jupyter Notebook または Python ファイルで設定 project_root すると、コンパイラは、周囲のフォルダー階層でマニフェストファイルを検索し、プロジェクトのスコープを決定します。マニフェストファイルが見つからない場合、コンパイラは 1 つのファイルモードで動作します。プロジェクトは Q# 、手動で作成することも、VS Code で直接作成することもできます。

外部Q#プロジェクトは、別のディレクトリまたはパブリック GitHub リポジトリに存在し、ステートメントを使用exportして、外部プログラムからアクセスできる関数と操作を定義する標準Q#プロジェクトです。プログラムは、外部プロジェクトをマニフェストファイルの依存関係として定義し、ステートメントを使用 import して外部プロジェクトの項目 (操作、関数、構造体、および名前空間) にアクセスします。詳細については、「外部依存関係としてのプロジェクトの使用」を参照してください。

前提条件

Azure サブスクリプションの Azure Quantum ワークスペース。ワークスペースを作成するには、Azure Quantum ワークスペースの作成に関するページを参照してください。
Azure Quantum Development Kit 拡張機能と Python 拡張機能がインストールされた Visual Studio Code。
外部プロジェクトをパブリック GitHub リポジトリに発行する予定の場合は、GitHub アカウント。

Python プログラムを実行する場合は、次のものが必要です。

Python と Pip がインストールされた Python 環境。
Azure Quantum qsharp と azure-quantum パッケージ。

プロジェクトを定義するQ#

Q#プロジェクトは、qsharp.jsonという名前のマニフェストファイルと src フォルダー (ソースファイルを含むQ#) の存在によって定義され、どちらもプロジェクトのルートフォルダーに存在する必要があります。プログラムと外部プロジェクトの場合 Q# 、コンパイラは Q# プロジェクトフォルダーを自動的に検出します。 Python プログラムと Jupyter Notebook の場合は、呼び出しでプロジェクトフォルダーを Q# 指定する qsharp.init 必要があります。ただし、プロジェクトの Q# フォルダー構造は、すべての種類のプログラムで同じままです。

プロジェクトのフォルダー階層を Q# 示す図。

プログラムの Q# 使用
Python または Jupyter Notebook の使用

プロジェクトフォルダー (Q# プログラム) の定義

VS Code で *.qs ファイルを開くと、 Q# コンパイラはフォルダー構造内でマニフェストファイルを上方向に検索します。マニフェストファイルが見つかると、コンパイラは /src ディレクトリまたはそのサブディレクトリ内のすべての Q# ファイルを含めます。各ファイルの項目は、プロジェクト内の他のすべてのファイルで使用できます。

たとえば、次のフォルダー構造が考えられます。

Teleportation_project
- qsharp.json
- src
  - Main.qs
  - TeleportOperations
    - TeleportLib.qs
    - PrepareState
      - PrepareStateLib.qs

ファイル /src/TeleportOperation/PrepareState/PrepareStateLib.qs を開くと、コンパイラは次のようになりますQ#。

qsharp.jsonの /src/TeleportOperation/PrepareState/ を確認します。
qsharp.jsonの /src/TeleportOperation を確認します。
/src でqsharp.jsonをチェックします。
qsharp.jsonを確認 / します。
/プロジェクトのルートディレクトリとして確立し、マニフェストファイルの設定に従って、プロジェクトのルートの下にあるすべての *.qs ファイルを含めます。

プロジェクトフォルダーの定義 (Python および Jupyter Notebook プログラム)

Python プログラムまたは Jupyter Notebook セルを使用してリソースにアクセス Q# する場合は、ステートメントを使用してプロジェクトのルートディレクトリを直接設定する qsharp.init 必要があります。前の例と同じフォルダー構造を使用する

Teleportation_project
- qsharp.json
- src
- MyPythonProgram.py
  - Main.qs
  - TeleportOperations
    - TeleportLib.qs
    - PrepareState
      - PrepareStateLib.qs

は、操作Q#をproject_root呼び出す前に設定します。

Python プログラムが /src フォルダーにあると仮定すると、

import qsharp

qsharp.init(project_root = '../Teleportation_project')

Note

プログラムをコンパイルして Azure Quantum サービスに送信する場合は、ステートメントにパラメーターを追加 target_profile する qsharp.init 必要もあります。既定では、 qsharp.init ローカルシミュレーターで任意の量子コードをテストできるように、プロファイル Unrestricted を設定します。ただし、Azure Quantum にジョブを送信するには、プロファイルBaseAdaptive_RIの設定が必要になる場合があります。たとえば、 qsharp.init(project_root = '../Teleportation_project', target_profile = qsharp.TargeProfile.Base) プロファイルのtarget詳細については、QIR target プロファイルを参照してください。

ルートフォルダーのパスは、それを設定しているファイルを基準にしています。つまり Q# 、プロジェクトフォルダーは任意の場所にすることができ、呼び出し元のプログラムが必ずしもプロジェクト内にある必要はありません。有効なパスには './MyProjects/Teleportation_project'、または ../../Teleportation_project.

コンパイラはQ#、指定されたルートフォルダーに有効なマニフェストファイルがあることを確認し、src フォルダーの下にある *.qs リソースをプロジェクト内で参照できるようにします。

マニフェストファイルの作成

マニフェストファイルは、qsharp.jsonという名前の単純な.json ファイルで、必要に応じて作成者、ライセンス、および lint フィールドを含めることができます。実行可能な最小マニフェストファイルは文字列 {}です。 VS Code でプロジェクトを Q# 作成すると、最小限のマニフェストファイルが自動的に作成されます。

{}

マニフェストファイルの例

マニフェストファイルでプロジェクトのスコープ Q# を定義する方法の例を次に示します。

この例では、 author が指定された唯一のフィールドであるため、このディレクトリ内のすべての *.qs ファイルとそのすべてのサブディレクトリがプロジェクトに Q# 含まれます。
```
{
    "author":"Microsoft",
    "license": "MIT"
}
```
Q#プロジェクト内では、マニフェストファイルを使用して VS Code Q# リンター設定を微調整することもできます。既定では、次の 3 つのリンタールールがあります。
- needlessParens: default = allow
- divisionByZero: default = warn
- redundantSemicolons: default = warn
マニフェストファイルを使用して、各ルールを次warnerrorのいずれかにallow設定できます。
```
{
    "author":"Microsoft",
    "lints": [
        {
          "lint": "needlessParens",
          "level": "allow"
        },
        {
          "lint": "redundantSemicolons",
          "level": "warn"
        },
        {
          "lint": "divisionByZero",
          "level": "error"
        }
      ]
}
```
マニフェストファイルを使用して外部プロジェクトを依存関係として定義し、その外部 Q# プロジェクトの操作と関数にリモートでアクセスすることもできます。詳細については、「外部依存関係としてのプロジェクトの使用」を参照してください。

Q# プロジェクトの要件とプロパティ

次の要件と構成は、すべての Q# プロジェクトに適用されます。

プロジェクトに含める *.qs ファイルはすべて、src という名前のフォルダーの下Q#になければなりません。このフォルダーは、 . VS Code でプロジェクトを Q# 作成すると、 /src フォルダーが自動的に作成されます。
マニフェストファイルは、src フォルダーと同じレベルにする必要があります。 VS Code でプロジェクトを Q# 作成すると、最小限のファイルが自動的に作成されます。
ステートメントを使用して import 、プロジェクト内の他のファイルの操作と関数を参照します。
```
import MyMathLib.*;  //imports all the callables in the MyMathLib namespace
...
    Multiply(x,y);
```
名前空間を使用して個別に参照する
```
MyMathLib.Multiply(x,y);  
```

プロジェクトの場合 Q# のみ

1 つの操作で定義されたエントリポイントを持つことは、プロジェクト内 Q# の 1 つの Main() *.qs ファイルだけです。
エントリポイント定義を含む *.qs ファイルは、マニフェストファイルの下の任意のレベルに配置できます。
プロジェクト内の任意の場所 Q# にある *.qs ファイルからキャッシュされた操作または関数は、VS Code の予測テキストに表示されます。
選択した操作または関数の名前空間がまだインポートされていない場合、VS Code によって必要な import ステートメントが自動的に追加されます。

プロジェクトを作成する Q# 手順

これらの手順はすべての Q# プロジェクトに適用されます。

VS Code ファイルエクスプローラーで、プロジェクトのルートフォルダーに使用するフォルダーを右クリックし、[プロジェクトの作成] を選択するか、フォルダーを開いて [コマンドパレットQ#>の表示>: プロジェクトのQ#作成...] を選択します。Q# Q#
VS Code は、フォルダーに最小限のマニフェストファイルを作成し、テンプレートファイルを含む /src フォルダーを Main.qs 追加します。
必要に応じてマニフェストファイルを編集します。マニフェストファイルの例を参照してください。
フォルダーの下にソースファイルを Q# 追加して /src 整理します。
Python プログラムまたは Jupyter Notebook からプロジェクトにQ#アクセスする場合は、を使用してルートフォルダーパスをqsharp.init設定します。この例では、プログラムがプロジェクトの /src フォルダー Q# 内にあるものとします。
```
qsharp.init(project_root = '../Teleportation_project')
```
VS Code でファイルのみを Q# 使用している場合、ファイルを Q# 開くと、コンパイラはマニフェストファイルを検索し、プロジェクトのルートフォルダーを決定し、サブフォルダーで *.qs ファイルをスキャンします。

Note

手順 2 でマニフェストファイルとフォルダーを /src 手動で作成することもできます。

プロジェクトの例

この量子テレポートプログラムは、前に示した単一フォルダー構造に基づくプロジェクトの Q# 例であり、VS Code のローカルシミュレーターで実行されます。 Azure Quantum ハードウェアまたはサードパーティのシミュレーターでプログラムを実行するには、プログラムをコンパイルして Azure ワークスペースに接続する手順については、「プログラムと VSCode の概要Q#」を参照してください。

この例では、次のディレクトリ構造を使用します。

Teleportation_project
- qsharp.json
- src
  - Main.qs
  - TeleportOperations
    - TeleportLib.qs
    - PrepareState
      - PrepareStateLib.qs

マニフェストファイルには、作成者フィールドとライセンス フィールドが含まれています。

{
    "author":"Microsoft",
    "license":"MIT"
}

Q# ソースファイル

メインファイル Main.qs にはエントリポイントが含まれており、TeleportLib.qs から名前空間を TeleportOperations.TeleportLib 参照します。


    import TeleportOperations.TeleportLib.Teleport;   // references the Teleport operation from TeleportLib.qs

    operation Main() : Unit {
        use msg = Qubit();
        use target = Qubit();

        H(msg);
        Teleport(msg, target);    // calls the Teleport() operation from TeleportLib.qs
        H(target);

        if M(target) == Zero {
            Message("Teleported successfully!");
        
        Reset(msg);
        Reset(target);
        }
    }

TeleportLib.qs は操作をTeleport()定義し、PrepareStateLib.qs から操作を呼び出PrepareBellPair()します。


    import TeleportOperations.PrepareState.PrepareStateLib.*;     // references the namespace in PrepareStateLib.qs
 
    operation Teleport(msg : Qubit, target : Qubit) : Unit {
        use here = Qubit();

        PrepareBellPair(here, target);      // calls the PrepareBellPair() operation from PrepareStateLib.qs
        Adjoint PrepareBellPair(msg, here);

        if M(msg) == One { Z(target); }
        if M(here) == One { X(target); }

        Reset(here);
    }

PrepareStateLib.qs ファイルには、ベルペアを作成するための標準の再利用可能な操作が含まれています。

    
    operation PrepareBellPair(left : Qubit, right : Qubit) : Unit is Adj + Ctl {
        H(left);
        CNOT(left, right);
    }

プログラムの実行

プログラムを実行している環境のタブを選択します。

このプログラムを実行するには、VS Code で Main.qs ファイルを開き、[実行] を選択します。

Jupyter Notebook でこのプログラムを実行するには、新しいノートブックを開き、次のセルを実行します。

import qsharp

# set the root folder for the Q# project
# make adjustments to the path depending on where your program is saved

# this example assumes your program is in the /src folder
qsharp.init(project_root = '../Teleportation_project')

パスが有効な場合は、確認メッセージが表示されます。 Q# initialized with configuration: {'targetProfile': 'unrestricted'}

マジックコマンドを使用してメイン操作を呼び出してプログラムを %%qsharp 実行する

%%qsharp
// call the main operation
Main.Main();

またはステートメントを使用してqsharp.eval()

print (qsharp.eval("Main.Main()"))

このプログラムを実行するには、次のコマンドを実行します。

import qsharp

# set the root folder for the Q# project
# make adjustments to the path depending on where your program is saved

# this example assumes your program is in the same folder as the root folder
qsharp.init(project_root = '../Teleportation_project')

を使用してメイン操作を呼び出してプログラムを実行します。 qsharp.eval()

print (qsharp.eval("Main.Main()"))

外部依存関係としてのプロジェクトの構成Q#

プロジェクトは Q# 、他のプロジェクトの外部依存関係として構成することもできます。ライブラリと同様に動作し、外部 Q# プロジェクトの関数と操作を複数 Q# のプロジェクトで使用できます。外部依存関係は、ドライブ共有上に存在することも、パブリック GitHub リポジトリに公開することもできます。

プロジェクトを Q# 外部依存関係として使用するには、次の手順を実行する必要があります。

外部プロジェクトを依存関係として、呼び出し元プロジェクトのマニフェストファイルに追加します。
外部プロジェクトが GitHub に発行されている場合は、外部プロジェクトのマニフェストファイルに "files" プロパティを追加します。
外部プロジェクトにステートメントを追加 export します。
呼び出し元のプロジェクトにステートメントを追加 import します。

マニフェストファイルの構成

外部 Q# プロジェクトは、ローカルまたはネットワークドライブ共有上に配置することも、パブリック GitHub リポジトリに発行することもできます。

呼び出し元のプロジェクトマニフェストファイル

ドライブ共有上の外部プロジェクトに依存関係を追加するには、呼び出し元プロジェクトのマニフェストファイルで依存関係を定義します。

{
    "author": "Microsoft",
    "license": "MIT",
    "dependencies": {
        "MyDependency": {
            "path": "/path/to/project/folder/on/disk"
        }
    }
}

ここで、"MyDependency" は、操作を呼び出すときに名前空間を識別するユーザー定義の文字列です。たとえば、"MyMathFunctions" という名前の依存関係を作成する場合、その依存関係 MyMathFunctions.MyFunction()から関数を呼び出します。

パブリック GitHub リポジトリに発行されたプロジェクトに依存関係を追加するには

{
    "author": "Microsoft",
    "dependencies": {
        "MyDependency": {
            "github": {
                "owner": "GitHubUser",
                "repo": "GitHubRepoName",
                "ref": "CommitHash",
                "path": "/path/to/dependency"
            }
        }
}

GitHub の依存関係の場合、"ref" は GitHub refspec を参照します。特定のバージョンの依存関係に依存できるように、コミットハッシュを常に使用することをお勧めします。

外部プロジェクトマニフェストファイル

外部Q#プロジェクトがパブリック GitHub リポジトリに発行されている場合は、プロジェクトで使用されるすべてのファイルを含め、外部プロジェクトのマニフェストファイルに files プロパティを追加する必要があります。

{
    "author": "Microsoft",
    "license": "MIT",
    "files": [ "src/MyMathFunctions.qs", "src/Strings/MyStringFunctions.qs" ]
}

"files" プロパティは、インポート "path" する外部プロジェクト (つまり、ローカルファイルパスベースのインポート) では省略可能です。 GitHub に発行されたプロジェクトにのみ必要です。

export ステートメントの使用

外部プロジェクトの関数と操作を呼び出し元のプロジェクトからアクセスできるようにするには、ステートメントを export 使用します。ファイル内の任意またはすべての呼び出し可能な呼び出し可能ファイルをエクスポートできます。ワイルドカード構文はサポートされていません。エクスポートする呼び出し可能な各呼び出しを指定する必要があります。

operation Operation_A() : Unit {
...
}
operation Operation_B() : Unit  {
...
}

// makes just Operation_A available to calling programs
export Operation_A;           

// makes Operation_A and Operation_B available to calling programs         
export Operation_A, Operation_B, etc.; 

// makes Operation_A available as 'OpA'
export Operation_A as OpA;

import ステートメントの使用

呼び出し元のプログラムでは、ステートメントを使用 import して、外部依存関係の項目を使用できるようにします。 import ステートメントは、マニフェストファイル内の依存関係に対して定義されている名前空間を使用します。たとえば、この依存関係の場合

{
    "author": "Microsoft",
    "license": "MIT",
    "dependencies": {
        "MyMathFunctions": {
            "path": "/path/to/project/folder/on/disk"
        }
    }
}

次のように呼び出し可能ファイルをインポートします。

import MyMathFunctions.MyFunction;  // imports "MyFunction()" from the namespace
...

このステートメントでは import 、ワイルドカードの構文とエイリアスもサポートされています

// imports all items from the "MyMathFunctions" namespace
import MyMathFunctions.*;        

// imports the namespace as "Math", all items are accessible via "Math.<callable>"
import MyMathFunctions as Math;   

// imports a single item, available in the local scope as "Add"
import MyMathFunctions.MyFunction as Add;        

// imports can be combined on one line
import MyMathFunctions.MyFunction, MyMathFunctions.AnotherFunction as Multiply;

Note

ライブラリと名前空間をQ#参照するために使用される現在使用openされているステートメントは引き続きサポートされていますが、最終的には非推奨になります。それまでは、必要に応じて、ステートメントを使用するように現在のファイルを import 更新できます。たとえば、open Microsoft.Quantum.Diagnostics; は import Microsoft.Quantum.Diagnostics.*; に置き換えることができます。また、標準Q#ライブラリでステートメントをimport使用する場合は、ルート名前空間Stdを . たとえば、次 import Microsoft.Quantum.Diagnostics.*; のように import Std.Diagnostics.*;記述できます。

外部プロジェクトの例

この例では、前の例と同じテレポートプログラムを使用しますが、呼び出し元のプログラムと呼び出し可能なプログラムを異なるプロジェクトに分割します。

"Project_A" や "Project_B" など、ローカルドライブに 2 つのフォルダーを作成します。
プロジェクトを作成するQ#手順の手順に従って、各フォルダーにプロジェクトをQ#作成します。
Project_A、呼び出し元のプログラムで、次のコードをマニフェストファイルにコピーし、必要に応じてパスを編集Project_B
```
{
  "author": "Microsoft",
  "license": "MIT",
  "dependencies": {
    "MyTeleportLib": {
      "path": "/Project_B" 
      }
    }
  }    
```

Project_Aで、次のコードを Main.qs にコピーします

import MyTeleportLib.Teleport;   // imports the Teleport operation from the MyTeleportLib namespace defined in the manifest file

operation Main() : Unit {
    use msg = Qubit();
    use target = Qubit();

    H(msg);
    Teleport(msg, target);    // calls the Teleport() operation from the MyTeleportLib namespace
    H(target);

    if M(target) == Zero {
        Message("Teleported successfully!");

    Reset(msg);
    Reset(target);
    }
}

Project_Bで、次のコードを Main.qs にコピーします


    operation Teleport(msg : Qubit, target : Qubit) : Unit {
        use here = Qubit();

        PrepareBellPair(here, target); 
        Adjoint PrepareBellPair(msg, here);

        if M(msg) == One { Z(target); }
        if M(here) == One { X(target); }

        Reset(here);
    }

    operation PrepareBellPair(left : Qubit, right : Qubit) : Unit is Adj + Ctl {
        H(left);
        CNOT(left, right);
    }

    export Teleport;       //  makes the Teleport operation available to external programs

Note

PrepareBellPairこの操作は、Project_Aのプログラムから直接呼び出されないため、エクスポートする必要はありません。 Project_Bのローカルスコープ内にあるため、操作によって既に Teleport アクセスできます。

プログラムを実行するには、VS Code で /Project_A/Main.qs を開き、[実行] を選択します。

プロジェクトと暗黙的な名前空間

プロジェクトでは Q# 、*.qs プログラムで名前空間が指定されていない場合、コンパイラはファイル名を名前空間として使用します。外部依存関係から呼び出し可能な呼び出し可能オブジェクトを参照すると、構文 <dependencyName が使用されます>。<名前空間>。<呼び出し可能。> ただし、ファイルの名前が "Main.qs" の場合、コンパイラは名前空間を想定し、呼び出し元の構文は <dependencyName です>。<前の例import MyTeleportLib.Teleportのように、呼び出し可能>です。

複数のプロジェクトファイルを持つことは珍しくないため、呼び出し可能ファイルを参照する場合は、正しい構文を考慮する必要があります。たとえば、次のファイル構造を持つプロジェクトの場合

src/
- Main.qs
- MathFunctions.qs

外部依存関係への呼び出しは次のようになります。

import MyTeleportLib.MyFunction;        // "Main" namespace is implied

import MyTeleportLib.MathFunctions.MyFunction;   // "Math" namespace must be explicit

名前空間の動作の詳細については、「ユーザー名前空間」を参照してください。

次の方法で共有

プロジェクトを操作する Q# 方法

前提条件

プロジェクトを定義するQ#

プロジェクトフォルダー (Q# プログラム) の定義

プロジェクトフォルダーの定義 (Python および Jupyter Notebook プログラム)

マニフェストファイルの作成

マニフェストファイルの例

Q# プロジェクトの要件とプロパティ

プロジェクトを作成する Q# 手順

プロジェクトの例

Q# ソースファイル

プログラムの実行

外部依存関係としてのプロジェクトの構成Q#

マニフェストファイルの構成

呼び出し元のプロジェクトマニフェストファイル

外部プロジェクトマニフェストファイル

export ステートメントの使用

import ステートメントの使用

外部プロジェクトの例

プロジェクトと暗黙的な名前空間

フィードバック

その他のリソース

次の方法で共有

プロジェクトを操作する Q# 方法

前提条件

プロジェクトを定義するQ#

プロジェクト フォルダー (Q# プログラム) の定義

マニフェスト ファイルの作成

マニフェスト ファイルの例

Q# プロジェクトの要件とプロパティ

プロジェクトを作成する Q# 手順

プロジェクトの例

Q# ソース ファイル

プログラムの実行

外部依存関係としてのプロジェクトの構成Q#

マニフェスト ファイルの構成

呼び出し元のプロジェクト マニフェスト ファイル

外部プロジェクト マニフェスト ファイル

export ステートメントの使用

import ステートメントの使用

外部プロジェクトの例

プロジェクトと暗黙的な名前空間

フィードバック

その他のリソース

プロジェクトフォルダー (Q# プログラム) の定義

マニフェストファイルの作成

マニフェストファイルの例

Q# ソースファイル

マニフェストファイルの構成

呼び出し元のプロジェクトマニフェストファイル

外部プロジェクトマニフェストファイル