Cara bekerja dengan Q# proyek

Dengan Azure Quantum Development Kit, Anda dapat menentukan Q# proyek, yang merupakan struktur folder dengan beberapa Q# file yang dapat mengakses operasi dan fungsi satu sama lain. Proyek berguna untuk mengatur kode sumber Anda secara logis. Anda juga dapat menggunakan proyek sebagai dependensi eksternal, atau pustaka kustom, yang dapat diakses dari sumber eksternal.

Proyek Q# berisi Q# file manifes, bernama qsharp.json, dan satu atau beberapa file *.qs dalam struktur folder tertentu. Saat pengguna membuka file *.qs di Visual Studio Code, atau mengatur project_root dalam file Jupyter Notebook atau Python, pengompilasi mencari hierarki folder di sekitarnya untuk file manifes dan menentukan cakupan proyek. Jika tidak ada file manifes yang ditemukan, pengkompilasi beroperasi dalam mode file tunggal. Proyek Q# dapat dibuat secara manual atau langsung di Visual Studio Code.

Proyek eksternal Q# adalah proyek standar Q# yang berada di direktori lain atau pada repositori GitHub publik dan menggunakan export pernyataan untuk menentukan fungsi dan operasi mana yang dapat diakses oleh program eksternal. Program menentukan proyek eksternal sebagai dependensi dalam file manifesnya, dan menggunakan import pernyataan untuk mengakses item (operasi, fungsi, struct, dan namespace) dalam proyek eksternal. Untuk informasi selengkapnya, lihat Menggunakan proyek sebagai dependensi eksternal.

Prasyarat

• Ruang kerja Azure Quantum di langganan Azure Anda. Untuk membuat ruang kerja, lihat Membuat ruang kerja Azure Quantum.
• Visual Studio Code dengan ekstensi Azure Quantum Development Kit dan Python terinstal.
• Akun GitHub, jika Anda berencana untuk menerbitkan proyek eksternal Anda ke repositori GitHub publik.

Untuk menjalankan program Python, Anda juga perlu:

• Lingkungan Python dengan Python dan Pip terinstal.
• Azure Quantum qsharp dan azure-quantum paket.

Q# Menentukan proyek

Proyek Q# didefinisikan oleh keberadaan file manifes, bernama qsharp.json, dan folder src (yang berisi Q# file sumber), yang keduanya harus berada di folder akar proyek. Untuk Q# program dan proyek eksternal, Q# pengkompilasi mendeteksi folder proyek secara otomatis. Untuk program Python dan Jupyter Notebooks, Anda harus menentukan Q# folder proyek dengan qsharp.init panggilan. Struktur folder untuk Q# proyek, bagaimanapun, tetap sama untuk semua jenis program.

Q# Menggunakan program

Menentukan folder proyek (Q# program)

Saat file *.qs dibuka di Visual Studio Code, pengkompilasi Q# mencari ke atas dalam struktur folder untuk file manifes. Jika menemukan file manifes, pengkompilasi kemudian menyertakan semua Q# file di direktori /src atau subdirektorinya. Setiap item file tersedia untuk semua file lain dalam proyek.

Misalnya, mengingat struktur folder ini:

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

saat Anda membuka file /src/TeleportOperation/PrepareState/PrepareStateLib.qs, pengkompilasi Q# :

1. Memeriksa /src/TeleportOperation/PrepareState/ untuk qsharp.json.
2. Memeriksa /src/TeleportOperation untuk qsharp.json.
3. Memeriksa /src untuk qsharp.json.
4. / Memeriksa qsharp.json.
5. / Menetapkan sebagai direktori akar proyek, dan menyertakan semua file *.qs di bawah akar dalam proyek, sesuai pengaturan file manifes.

Menggunakan Python atau Jupyter Notebook

Menentukan folder proyek (program Notebook Python dan Jupyter)

Saat Anda menggunakan program Python atau sel Jupyter Notebook untuk mengakses Q# sumber daya, Anda perlu mengatur direktori akar proyek secara langsung dengan qsharp.init pernyataan. Menggunakan struktur folder yang sama dari contoh sebelumnya

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

Anda akan mengatur project_root sebelum melakukan panggilan ke operasi apa pun Q# .

Dengan asumsi program Python Anda ada di folder /src,

import qsharp

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

Catatan

Jika Anda berencana untuk mengkompilasi program Anda untuk dikirimkan ke layanan Azure Quantum, Anda juga harus menambahkan parameter Anda target_profile ke qsharp.init pernyataan. Secara default, qsharp.init atur profil ke Unrestricted sehingga Anda dapat menguji kode kuantum apa pun di simulator lokal. Namun, untuk mengirimkan pekerjaan ke Azure Quantum, Anda mungkin perlu mengatur profil ke Base atau Adaptive_RI, misalnya, qsharp.init(project_root = '../Teleportation_project', target_profile = qsharp.TargeProfile.Base). Untuk informasi selengkapnya tentang target profil, lihat profil QIRtarget.

Jalur folder akar relatif terhadap file yang mengaturnya, yang berarti bahwa folder proyek Anda Q# dapat berada di mana saja dan program panggilan tidak harus berada dalam proyek. Jalur yang valid mungkin juga './MyProjects/Teleportation_project', atau ../../Teleportation_project.

Pengkompilasi Q# memverifikasi ada file manifes yang valid di folder akar yang ditentukan dan membuat sumber daya *.qs apa pun di bawah folder src tersedia untuk referensi dalam proyek.

Membuat file manifes

File manifes adalah file .json sederhana bernama qsharp.json yang dapat secara opsional menyertakan bidang penulis, lisensi, dan lints . File manifes minimum yang layak adalah string {}. Saat Anda membuat Q# proyek di Visual Studio Code, file manifes minimal dibuat untuk Anda.

{}

Contoh file manifes

Berikut ini adalah beberapa contoh bagaimana file manifes dapat menentukan cakupan proyek Anda Q# .

• Dalam contoh ini, penulis adalah satu-satunya bidang yang ditentukan, dan oleh karena itu semua file *.qs dalam direktori ini dan semua subdirektorinya disertakan dalam Q# proyek.

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

• Q# Dalam proyek, Anda juga dapat menggunakan file manifes untuk menyempurnakan pengaturan Linter Visual Studio CodeQ#. Secara default, tiga aturan Linter adalah:

  • needlessParens: default = allow
  • divisionByZero: default = warn
  • redundantSemicolons: default = warn

  Dengan menggunakan file manifes, Anda dapat mengatur setiap aturan ke allow, , warnatau error, misalnya

  {
      "author":"Microsoft",
      "lints": [
          {
            "lint": "needlessParens",
            "level": "allow"
          },
          {
            "lint": "redundantSemicolons",
            "level": "warn"
          },
          {
            "lint": "divisionByZero",
            "level": "error"
          }
        ]
  }
  

• Anda juga dapat menggunakan file manifes untuk menentukan proyek eksternal Q# sebagai dependensi dan mengakses operasi dan fungsi dari jarak jauh dalam proyek eksternal tersebut. Untuk informasi selengkapnya, lihat Menggunakan proyek sebagai dependensi eksternal.

Q# persyaratan dan properti proyek

Persyaratan dan konfigurasi berikut berlaku untuk semua Q# proyek.

• Semua file *.qs yang ingin Anda sertakan dalam proyek harus berada di bawah folder bernama src, yang harus berada di bawah folder akar .Q# Saat Anda membuat Q# proyek di Visual Studio Code, /src folder dibuat secara otomatis.

• File manifes harus berada pada tingkat yang sama dengan folder src . Saat Anda membuat Q# proyek di Visual Studio Code, file minimal dibuat secara otomatis.

• Gunakan import pernyataan untuk mereferensikan operasi dan fungsi dari file lain dalam proyek.

  import MyMathLib.*;  //imports all the callables in the MyMathLib namespace
  ...
      Multiply(x,y);
  

  atau mereferensikannya satu per satu dengan namespace

  MyMathLib.Multiply(x,y);  
  

Hanya untuk Q# proyek

• Hanya satu file *.qs dalam proyek yang Q# dapat memiliki titik masuk yang ditentukan, yang ditentukan oleh satu Main() operasi.
• File *.qs dengan definisi titik entri dapat ditemukan pada tingkat apa pun di bawah file manifes.
• Setiap operasi atau fungsi yang di-cache dari file *.qs di mana saja dalam Q# proyek ditampilkan dalam teks prediktif di Visual Studio Code.
• Jika namespace untuk operasi atau fungsi yang dipilih belum diimpor, Visual Studio Code secara otomatis menambahkan pernyataan yang diperlukan import .

Langkah-langkah untuk membuat Q# proyek

Langkah-langkah ini berlaku untuk semua Q# proyek.

1. Di penjelajah file Visual Studio Code, klik kanan folder yang ingin Anda gunakan untuk folder Q# akar proyek dan pilih Buat Q# proyek, atau buka folder dan pilih Tampilkan > Palet >Q#Perintah : Buat Q# proyek....

2. Visual Studio Code membuat file manifes minimal di folder, dan menambahkan /src folder dengan Main.qs file templat.

3. Edit file manifes sesuai kebutuhan. Lihat Contoh file manifes.

4. Tambahkan dan atur file sumber Anda Q# di /src bawah folder .

5. Jika Anda mengakses Q# proyek dari program Python atau Jupyter Notebook, atur jalur folder akar menggunakan qsharp.init. Contoh ini mengasumsikan program Anda berada di folder Q# /src proyek:

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

6. Jika Anda hanya Q# menggunakan file di Visual Studio Code, saat Anda membuka Q# file, pengkompilasi mencari file manifes, menentukan folder akar proyek, lalu memindai subfolder untuk file *.qs.

Catatan

Anda juga dapat membuat file manifes dan /src folder secara manual di langkah 2.

Contoh proyek

Program teleportasi kuantum ini adalah contoh Q# proyek berdasarkan struktur folder tunggal yang ditunjukkan sebelumnya, dan berjalan pada simulator lokal di VS Code. Untuk menjalankan program pada perangkat keras Azure Quantum atau simulator pihak ketiga, lihat Mulai menggunakan Q# program dan VSCode untuk langkah-langkah mengkompilasi program Anda dan menyambungkan ke ruang kerja Azure Anda.

Contoh menggunakan struktur direktori ini:

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

File manifes berisi bidang penulis dan lisensi :

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

Q# file sumber

File utama, Main.qs, berisi titik masuk dan mereferensikan TeleportOperations.TeleportLib namespace dari TeleportLib.qs.

    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 mendefinisikan Teleport() operasi dan memanggil PrepareBellPair() operasi dari PrepareStateLib.qs.

    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);
    }

File PrepareStateLib.qs berisi operasi standar yang dapat digunakan kembali untuk membuat pasangan Bell.

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

Menjalankan program

Pilih tab untuk lingkungan tempat Anda menjalankan program.

Q# Menjalankan program

Untuk menjalankan program ini, buka file Main.qs di Visual Studio Code dan pilih Jalankan.

Menjalankan Jupyter Notebook

Untuk menjalankan program ini di Jupyter Notebook, buka buku catatan baru dan jalankan sel berikut:

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')

Jika jalur Anda valid, Anda akan melihat pesan konfirmasi, Q# initialized with configuration: {'targetProfile': 'unrestricted'}

Jalankan program dengan memanggil operasi utama menggunakan %%qsharp perintah ajaib

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

atau dengan menggunakan qsharp.eval() pernyataan

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

Menjalankan program Python

Untuk menjalankan program ini, jalankan perintah berikut:

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')

Jalankan program dengan memanggil operasi utama dengan qsharp.eval()

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

Mengonfigurasi Q# proyek sebagai dependensi eksternal

Proyek Q# juga dapat dikonfigurasi sebagai dependensi eksternal untuk proyek lain, bertindak seperti pustaka, di mana fungsi dan operasi dalam proyek eksternal Q# tersedia untuk beberapa Q# proyek. Dependensi eksternal dapat berada di berbagi drive atau diterbitkan ke repositori GitHub publik.

Untuk menggunakan Q# proyek sebagai dependensi eksternal, Anda perlu:

• Tambahkan proyek eksternal sebagai dependensi dalam file manifes proyek panggilan.
• Jika proyek eksternal diterbitkan ke GitHub, tambahkan properti "file" ke file manifes proyek eksternal.
• Tambahkan export pernyataan ke proyek eksternal.
• Tambahkan import pernyataan ke proyek panggilan.

Mengonfigurasi file manifes

Proyek eksternal Q# dapat berada di berbagi drive lokal atau jaringan, atau diterbitkan ke repositori GitHub publik.

File manifes proyek panggilan

Untuk menambahkan dependensi ke proyek eksternal pada berbagi drive, tentukan dependensi dalam file manifes proyek panggilan.

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

di mana "MyDependency" adalah string yang ditentukan pengguna yang mengidentifikasi namespace saat memanggil operasi. Misalnya, jika Anda membuat dependensi bernama "MyMathFunctions", Anda akan memanggil fungsi dari dependensi tersebut dengan MyMathFunctions.MyFunction().

Untuk menambahkan dependensi ke proyek yang diterbitkan ke repositori GitHub publik

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

• Untuk dependensi GitHub, "ref" mengacu pada refspec GitHub. Microsoft merekomendasikan untuk selalu menggunakan hash penerapan, sehingga Anda dapat mengandalkan versi dependensi tertentu.

File manifes proyek eksternal

Jika proyek eksternal Q# Anda diterbitkan ke repositori GitHub publik, Anda harus menambahkan properti file ke file manifes proyek eksternal, termasuk semua file yang digunakan dalam proyek.

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

Properti "file" bersifat opsional untuk proyek eksternal yang diimpor melalui "path" (yaitu, impor berbasis filepath lokal). Ini hanya diperlukan untuk proyek yang diterbitkan ke GitHub.

Menggunakan pernyataan ekspor

Untuk membuat fungsi dan operasi dalam proyek eksternal dapat diakses oleh proyek panggilan, Anda menggunakan pernyataan tersebut export . Anda dapat mengekspor salah satu atau semua yang dapat dipanggil dalam file. Sintaks kartubebas tidak didukung, Anda harus menentukan setiap yang dapat dipanggil untuk diekspor.

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;             

Menggunakan pernyataan impor

Dari program panggilan, Anda menggunakan import pernyataan untuk membuat item dari dependensi eksternal tersedia. import pernyataan menggunakan namespace layanan yang ditentukan untuk dependensi dalam file manifes. Misalnya, untuk dependensi ini

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

Anda mengimpor callables sebagai

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

Pernyataan ini import juga mendukung sintaksis dan alias kartubebas

// 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; 

Catatan

Pernyataan yang saat ini digunakan open dalam Q#, yang digunakan untuk mereferensikan pustaka dan namespace layanan, masih didukung tetapi pada akhirnya tidak akan digunakan lagi. Sementara itu, Anda dapat secara opsional memperbarui file Anda saat ini untuk menggunakan pernyataan .import Misalnya, open Microsoft.Quantum.Diagnostics; dapat diganti dengan import Microsoft.Quantum.Diagnostics.*;. Perhatikan juga bahwa saat menggunakan import pernyataan dengan pustaka standar Q# , Anda dapat mempersingkat namespace layanan akar menjadi Std. Misalnya, import Microsoft.Quantum.Diagnostics.*; dapat ditulis sebagai import Std.Diagnostics.*;.

Contoh proyek eksternal

Untuk contoh ini, Anda akan menggunakan program teleportasi yang sama dengan contoh sebelumnya, tetapi memisahkan program panggilan dan panggilan ke dalam proyek yang berbeda.

1. Buat dua folder di drive lokal Anda, misalnya "Project_A" dan "Project_B".

2. Buat Q# proyek di setiap folder dengan mengikuti langkah-langkah dalam Langkah-langkah untuk membuat Q# proyek.

3. Dalam Project_A, program panggilan, salin kode berikut ke dalam file manifes, mengedit jalur sesuai kebutuhan untuk Project_B

   {
     "author": "Microsoft",
     "license": "MIT",
     "dependencies": {
       "MyTeleportLib": {
         "path": "/Project_B" 
         }
       }
     }    
   

4. Di Project_A, salin kode berikut ke 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);
       }
   }   
   

5. Di Project_B, salin kode berikut ke 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
   

   Catatan

   Perhatikan bahwa PrepareBellPair operasi tidak perlu diekspor karena tidak dipanggil langsung dari program Anda di Project_A. Karena berada dalam cakupan lokal Project_B, itu sudah dapat diakses oleh Teleport operasi.

6. Untuk menjalankan program, buka /Project_A/Main.qs di Visual Studio Code dan pilih Jalankan.

Proyek dan namespace implisit

Dalam Q# proyek, jika namespace tidak ditentukan dalam program *.qs, maka pengkompilasi menggunakan nama file sebagai namespace. Mereferensikan yang dapat dipanggil dari dependensi eksternal lalu menggunakan sintaks dependencyName<>.<namespace> layanan.<dapat dihubungi>. Namun, jika file diberi nama "Main.qs", pengkompilasi mengasumsikan namespace dan sintaks panggilan adalah <dependencyName>.<dapat> dipanggil, seperti dalam contoh sebelumnya, import MyTeleportLib.Teleport.

Karena tidak jarang memiliki beberapa file proyek, Anda perlu memperhitungkan sintaks yang benar saat mereferensikan yang dapat dipanggil. Misalnya, dalam proyek dengan struktur file berikut

• /Src
  • Main.qs
  • MathFunctions.qs

panggilan ke dependensi eksternal adalah

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

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

Untuk informasi selengkapnya tentang perilaku namespace layanan, lihat Namespace pengguna.