Работа с проектами Q#

Статья
07/06/2024

С помощью выпуска Azure Quantum Development Kitможно определить Q# проекты, которые являются структурами папок с несколькими Q# файлами, которые могут получить доступ к ресурсам друг друга. Проекты полезны для создания повторно используемых библиотек и логического упорядочения исходного кода.

Проект Q# содержит файл манифеста Q# с именем qsharp.json и один или несколько файлов *.qs в указанной структуре папок. Когда пользователь открывает файл *.qs в VS Code или задает project_root файл Jupyter Notebook или Python, компилятор выполняет поиск в окружающей иерархии папок для файла манифеста и определяет область проекта. Если файл манифеста не найден, компилятор работает в одном режиме. Q# Проект можно создать вручную или непосредственно в VS Code.

Необходимые компоненты

Рабочая область Azure Quantum по подписке Azure. Сведения о создании рабочей области см. в статье Создание рабочей области Azure Quantum.
Среда Python с установленным Python и Pip .
Visual Studio Code с установленным расширением Azure Quantum Development Kit и 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

Определение папки проекта (Q# программы)

При открытии файла *.qs в VS Code Q# компилятор выполняет поиск вверх в структуре папок для файла манифеста qsharp.json . Если он находит файл манифеста, компилятор выполняет поиск вниз по всем вложенным папкам каталога src для файлов *.qs и кэширует все операции или функции, а также делает эти операции и функции доступными для всех файлов *.qs в зависимости от правил исключения файла манифеста.

Например, учитывая эту структуру папок:

Teleportation_project
- qsharp.json
- src
  - RunTeleport.qs
  - TeleportOperations
    - Teleport.qs
    - PrepareState
      - PrepareState.qs

При открытии файла /src/TeleportOperation/PrepareState/PrepareState.qsQ# компилятор:

Проверяет /src/TeleportOperation/PrepareState/ для файла qsharp.json .
Проверяет значение /src/TeleportOperation для qsharp.json.
Проверяет /src для qsharp.json.
Проверяет / наличие qsharp.json.
/ Устанавливает в качестве корневого каталога проекта и включает все файлы *.qs в корневом каталоге проекта в соответствии с параметрами файла манифеста.

Определение папки проекта (программы Python и Jupyter Notebook)

При использовании программы Python или ячейки Jupyter Notebook для доступа Q# к ресурсам необходимо задать корневой каталог проекта непосредственно с помощью инструкции qsharp.init . Использование той же структуры папок из предыдущего примера

Teleportation_project
- qsharp.json
- src
- MyPythonProgram.py
  - RunTeleport.qs
  - TeleportOperations
    - Teleport.qs
    - PrepareState
      - PrepareState.qs

Перед выполнением вызовов к любым Q# операциям вы задали project_root значение.

Предполагая, что программа Python находится в папке Q# проекта,

import qsharp

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

Примечание.

Если вы планируете скомпилировать программу для отправки в службу Azure Quantum, необходимо также добавить target_profile параметр в инструкцию qsharp.init . По умолчанию задает профиль Unrestriced таким образом, qsharp.init чтобы можно было протестировать любой квантовый код в локальном симуляторе. Однако для отправки задания в Azure Quantum может потребоваться задать профиль Base или Adaptive_RI, например, qsharp.init(project_root = './Teleportation_project', target_profile = qsharp.TargeProfile.Base). Дополнительные сведения о профилях см. в target разделе "Профили QIRtarget".

Путь к корневой папке относится к файлу, который его задает, то есть Q# папка проекта может находиться в любом месте, а вызывающая программа не обязательно должна находиться в проекте. Допустимый путь также может быть './MyProjects/Teleportation_project'или ../../Teleportation_project.

Компилятор Q# проверяет наличие допустимого файла qsharp.json в указанной корневой папке и делает все ресурсы *.qs в папке src , доступной для ссылки, в соответствии с правилами исключения файла манифеста.

Создание файла манифеста

Файл манифеста — это простой файл .json с именем qsharp.json , который может включать поля author, license и ints . Минимальный жизнеспособный файл манифеста — это строка {}. При создании проекта в VS Code создается минимальный Q# файл манифеста.

{}

Примеры файлов манифеста

Ниже приведены некоторые примеры того, как файлы манифеста Q# могут определять область проекта.

В этом примере автор является единственным полем, поэтому все файлы *.qs в этом каталоге и все его подкаталогы включены в Q# проект.

{
    "author":"Microsoft"
}

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

В проекте также можно использовать файл манифеста для точной Q# настройки параметров VS Code Q# Linter. По умолчанию три правила Linter:

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

Используя файл манифеста, можно задать для каждого правила значение allow, warnили error, например,

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

Q# Требования к проекту и свойства

Следующие требования и конфигурации применяются ко всем Q# проектам.

Все файлы *.qs, которые необходимо включить в проект, должны находиться в папке с именем src, которая должна находиться в корневой папке Q# проекта. При создании Q# проекта в VS Code /src папка создается автоматически.
Файл манифеста qsharp.json должен быть на том же уровне, что и папка src. При создании Q# проекта в VS Code файл qsharp.json создается автоматически.
К операциям и функциям в доступных исходных файлах можно получить доступ с помощью open инструкций:

open MyMathLib;
...
    Multiply(x,y);

или ссылки на них с пространством имен:

MyMathLib.Multiply(x,y);

Только для Q# программ

В проекте может быть @EntryPoint() определен только один файл Q# *.qs.
Файл *.qs с @EntryPoint() определением может находиться на любом уровне ниже файла манифеста.
Любая операция или функция, кэшируемая из файла *.qs в любом месте проекта, отображается в прогнозном тексте Q# в VS Code.
Если пространство имен для выбранной операции или функции еще не добавлено, VS Code автоматически добавляет необходимую open инструкцию.

Действия по созданию Q# проекта

В проводнике VS Code щелкните правой кнопкой мыши папку, которую вы хотите использовать для Q# корневой папки проекта, и выберите "Создать Q# проект" или откройте папку и выберите "Просмотреть > палитру команд>Q#: создать Q# проект...".
VS Code создает минимальный файл манифеста qsharp.json в папке и добавляет /src папку с файлом Main.qs шаблона.
Измените файл манифеста по мере необходимости. См . примеры файлов манифеста.
Добавьте и упорядочение Q# исходных файлов в папке /src .
Если вы обращаетесь к Q# проекту из программы Python или Jupyter Notebook, задайте путь к корневой папке с помощью qsharp.init. В этом примере предполагается, что программа находится в той же папке, что и корневая папка Q# проекта:
```
qsharp.init(project_root = './Teleportation_project')
```
Если вы используете только Q# файлы в VS Code, при открытии Q# файла компилятор ищет файл манифеста qsharp.json , определяет корневую папку проекта, а затем сканирует вложенную папку для файлов *.qs.

Примечание.

Вы также можете вручную создать файл манифеста и папку /src на шаге 2.

Пример проекта

Эта программа квантового телепортации является примером Q# проекта на основе структуры папок, показанной ранее, и выполняется на локальном симуляторе в VS Code. Сведения о запуске программы на оборудовании Azure Quantum или сторонних симуляторах см. в статье "Начало работы с Q# программами и VSCode ", чтобы выполнить компиляцию программы и подключиться к рабочей области Azure.

В примере используется эта структура каталогов:

Teleportation_project
- qsharp.json
- src
  - RunTeleport.qs
  - TeleportOperations
    - Teleport.qs
    - PrepareState
      - PrepareState.qs

Файл манифеста qsharp.json содержит поля автора и лицензии:

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

Q# исходные файлы

При одной незначительной разнице - @EntryPoint() оператор - исходные файлы одинаковы для Q# программы, программы Python или Jupyter Notebook.

Основной файл RunTeleport.qs содержит точку входа и ссылается на TeleportLib пространство имен в Teleport.qs.

namespace RunTeleport {

    open TeleportLib;   // references the TeleportLib namespace in Teleport.qs

    @EntryPoint()       // @EntryPoint() not necessary for Python or Jupyter Notebook programs
    operation RunTeleportationExample() : Unit {
        use msg = Qubit();
        use target = Qubit();

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

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

Teleport.qs определяет Teleport() операцию и вызывает PrepareBellPair() операцию из PrepareState.qs.

namespace TeleportLib {

    open PrepareBell;     // references the PrepareBell namespace in PrepareState.qs
 
    operation Teleport(msg : Qubit, target : Qubit) : Unit {
        use here = Qubit();

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

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

        Reset(here);
    }
}

Файл PrepareState.qs содержит стандартную операцию повторного использования для создания пары Bell.

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

Запуск программ

Выберите вкладку для среды, в которой выполняется программа.

Чтобы запустить эту программу, откройте файл RunTeleport.qs в VS Code и выберите "Выполнить".

Для программы Jupyter Notebook исходные файлы не требуют атрибута @EntryPoint() . Файлы работают только в качестве исходных библиотек.

Чтобы запустить эту программу в 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 same folder as the root folder
qsharp.init(project_root = './Teleportation_project')

Если путь действителен, появится сообщение подтверждения. Q# initialized with configuration: {'targetProfile': 'unrestricted'}

Запустите программу, вызвав основную операцию с помощью волшебной %%qsharp команды

%%qsharp
// call the main operation
RunTeleport.RunTeleportationExample();

или с помощью инструкции qsharp.eval()

print (qsharp.eval("RunTeleport.RunTeleportationExample()"));

Для программы Python исходные файлы не требуют атрибута @EntryPoint() . Файлы работают только в качестве исходных библиотек.

Чтобы запустить эту программу, выполните следующие команды:

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