Baca dalam bahasa Inggris

Bagikan melalui

Cara membuat dan mengelola Q# proyek dan pustaka kustom

  • Artikel

Dalam artikel ini, Anda akan mempelajari cara membuat, mengelola, dan berbagi Q# proyek. Q# proyek adalah 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 pustaka kustom yang dapat diakses dari sumber eksternal.

Prasyarat

Untuk menjalankan program Python, Anda juga perlu:

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

Cara Q# kerja proyek

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. Anda dapat membuat Q# proyek secara manual atau langsung di Visual Studio Code.

Proyek eksternal Q# adalah proyek standar Q# yang berada di direktori lain atau di repositori GitHub publik dan bertindak sebagai pustaka kustom. Proyek eksternal 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.

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.

Struktur folder dan hierarki untuk Q# proyek.

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.

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.

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

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"
            }
        }
}

Catatan

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.