다음을 통해 공유

프로젝트 및 사용자 지정 라이브러리를 만들고 관리하는 Q# 방법

  • 아티클

이 문서에서는 프로젝트를Q# 방법을 알아봅니다. Q# 프로젝트는 서로의 작업 및 함수에 액세스할 수 있는 여러 Q# 파일이 있는 폴더 구조입니다. 프로젝트는 소스 코드를 논리적으로 구성하는 데 유용합니다. 외부 원본에서 액세스할 수 있는 사용자 지정 라이브러리로 프로젝트를 사용할 수도 있습니다.

필수 조건

  • 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#Q# 매니페스트 파일( qsharp.json) 및 지정된 폴더 구조에 있는 하나 이상의 *.qs 파일이 포함됩니다. 사용자가 VS Code에서 *.qs 파일을 열거나 Jupyter Notebook 또는 Python 파일에서 설정하는 project_root 경우 컴파일러는 주변 폴더 계층 구조에서 매니페스트 파일을 검색하고 프로젝트의 범위를 결정합니다. 매니페스트 파일을 찾을 수 없는 경우 컴파일러는 단일 파일 모드에서 작동합니다. VS Code에서 Q# 수동으로 또는 직접 프로젝트를 만들 수 있습니다.

외부 Q# 프로젝트는 다른 디렉터리 또는 공용 GitHub 리포지토리에 상주하며 사용자 지정 라이브러리 역할을 하는 표준 Q# 프로젝트입니다. 외부 프로젝트는 문을 사용하여 export 외부 프로그램에서 액세스할 수 있는 함수 및 작업을 정의합니다. 프로그램은 외부 프로젝트를 매니페스트 파일의 종속성으로 정의하고 문을 사용하여 import 외부 프로젝트의 항목(작업, 함수, 구조체 및 네임스페이스)에 액세스합니다. 자세한 내용은 외부 종속성으로 프로젝트 사용을 참조 하세요.

Q# 프로젝트 정의

Q# 프로젝트는 qsharp.json 명명된 매니페스트 파일과 Q# 폴더가 있는 것으로 정의되며, 둘 다 프로젝트의 루트 폴더에 있어야 합니다. 프로그램 및 외부 프로젝트의 Q# 경우 Q# 컴파일러는 프로젝트 폴더를 자동으로 검색합니다. Python 프로그램 및 Jupyter Notebook의 경우 호출을 사용하여 프로젝트 폴더qsharp.init. 그러나 프로젝트의 폴더 구조 Q# 는 모든 유형의 프로그램에서 동일하게 유지됩니다.

프로젝트의 폴더 구조 및 계층 구조입니다 Q# .

프로젝트 폴더 정의(Q# 프로그램)

VS Code Q# 에서 *.qs 파일을 열면 컴파일러가 폴더 구조에서 매니페스트 파일을 위쪽으로 검색합니다. 매니페스트 파일을 찾으면 컴파일러는 /src 디렉터리 또는 해당 하위 디렉터리의 모든 Q# 파일을 포함합니다. 각 파일의 항목은 프로젝트 내의 다른 모든 파일에서 사용할 수 있습니다.

예를 들어 이 폴더 구조는 다음과 같습니다.

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

/src/TeleportOperation/PrepareState/PrepareStateLib.qs 파일을 열면 컴파일러:Q#

  1. /src/TeleportOperation/PrepareState/에서 qsharp.json 확인합니다.
  2. /src/TeleportOperation에서 qsharp.json 확인합니다.
  3. qsharp.json /src를 확인합니다.
  4. qsharp.json 확인 / 합니다.
  5. / 프로젝트의 루트 디렉터리로 설정되며 매니페스트 파일의 설정에 따라 프로젝트의 루트 아래에 있는 모든 *.qs 파일을 포함합니다.

매니페스트 파일 만들기

매니페스트 파일은 선택적으로 작성자, 라이선스 및 lints 필드를 포함할 수 있는 qsharp.json 명명된 간단한 .json 파일입니다. 실행 가능한 최소 매니페스트 파일은 문자열 {}입니다. VS Code에서 프로젝트를 만들 Q# 면 최소한의 매니페스트 파일이 만들어집니다.

{}

매니페스트 파일 예제

다음은 매니페스트 파일이 프로젝트의 범위를 정의하는 방법의 Q# 몇 가지 예입니다.

  • 이 예제 에서 작성 자는 지정된 유일한 필드이므로 이 디렉터리의 모든 *.qs 파일과 모든 하위 디렉터리가 프로젝트에 포함 Q# 됩니다.

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

  • Q# 프로젝트 내에서 매니페스트 파일을 사용하여 VS Code Q# Linter 설정을 미세 조정할 수도 있습니다. 기본적으로 세 가지 Linter 규칙은 다음과 같습니다.

    • needlessParens: default = allow

    • divisionByZero: default = warn

    • redundantSemicolons: default = warn

      매니페스트 파일을 사용하여 각 규칙을 allowwarn또는 error로 설정할 수 있습니다.

      {
    "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# 프로젝트 전용

  • 프로젝트의 *.qs 파일 Q# 하나만 단일 Main() 작업으로 정의된 진입점을 가질 수 있습니다.
  • 진입점 정의가 있는 *.qs 파일은 매니페스트 파일 아래의 모든 수준에서 찾을 수 있습니다.
  • 프로젝트의 아무 곳이나 Q# *.qs 파일에서 캐시되는 모든 작업 또는 함수는 VS Code의 예측 텍스트에 표시됩니다.
  • 선택한 작업 또는 함수의 네임스페이스를 아직 가져오지 않은 경우 VS Code는 필요한 import 문을 자동으로 추가합니다.

프로젝트를 만드는 Q# 단계

이러한 단계는 모든 Q# 프로젝트에 적용 됩니다.

  1. VS Code 파일 탐색기에서 프로젝트의 루트 폴더에 사용할 폴더 Q# 를 마우스 오른쪽 단추로 클릭하고 프로젝트 만들기 Q# 를 선택하거나 폴더를 열고 명령 팔레트 >>보기Q#: 프로젝트 만들기Q#...를 선택합니다.

  2. VS Code는 폴더에 최소 매니페스트 파일을 만들고 템플릿 파일이 있는 /src 폴더를 Main.qs 추가합니다.

  3. 필요에 따라 매니페스트 파일을 편집합니다. 매니페스트 파일 예제를 참조 하세요.

  4. 폴더 아래에 원본 파일을 추가하고 구성합니다 Q#/src .

  5. Python 프로그램 또는 Jupyter Notebook Q#에서 프로젝트에 액세스하는 qsharp.init 경우 . 이 예제에서는 프로그램이 프로젝트의 /src 폴더에 있다고 가정합니다 Q# .

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

  6. VS Code에서 파일만 Q# 사용하는 경우 파일을 열 Q# 때 컴파일러는 매니페스트 파일을 검색하고 프로젝트의 루트 폴더를 확인한 다음 하위 폴더에서 *.qs 파일을 검색합니다.

참고 항목

2단계에서 매니페스트 파일 및 폴더를 /src 수동으로 만들 수도 있습니다.

예제 프로젝트

이 양자 텔레포트 프로그램은 이전에 표시된 단일 폴더 구조를 기반으로 하는 프로젝트의 예 Q# 이며 VS Code의 로컬 시뮬레이터에서 실행됩니다. Azure Quantum 하드웨어 또는 타사 시뮬레이터에서 프로그램을 실행하려면, 프로그램 및 VSCode 시작하기 를 참조하여 프로그램을 컴파일하고 Azure 작업 공간에 연결하는 단계를 확인하세요.

이 예제에서는 다음 디렉터리 구조를 사용합니다.

  • 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 파일을 열고 실행을 선택합니다.

외부 종속성으로 프로젝트 구성 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 리포지토리에 게시된 경우 프로젝트에 사용되는 모든 파일을 포함하여 외부 프로젝트의 매니페스트 파일에 파일 속성을 추가해야 합니다.

{
    "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;

참고 항목

라이브러리 및 네임스페이스를 참조하는 데 사용되는 현재 사용되는 open 문 Q#은 여전히 지원되지만 결국에는 사용되지 않습니다. 그 동안 필요에 따라 현재 파일을 업데이트하여 문을 사용할 import 수 있습니다. 예를 들어 . open Microsoft.Quantum.Diagnostics;import Microsoft.Quantum.Diagnostics.*; 또한 표준 import 라이브러리와 Q# 함께 문을 사용하는 경우 루트 네임스페이스를 Std.로 줄일 수 있습니다. 예를 들어 다음과 import Microsoft.Quantum.Diagnostics.*; 같이 import Std.Diagnostics.*;작성할 수 있습니다.

외부 프로젝트 예제

이 예제에서는 이전 예제와 동일한 텔레포트 프로그램을 사용하지만 호출 프로그램과 호출 가능 프로그램을 다른 프로젝트로 구분합니다.

  1. 로컬 드라이브에 두 개의 폴더(예: "Project_A" 및 "Project_B")를 만듭니다.

  2. Q# 프로젝트를 만들기 위한 단계의 단계에 따라 각 폴더에 Q# 만듭니다.

  3. Project_A 호출 프로그램에서 다음 코드를 매니페스트 파일에 복사하여 필요에 따라 경로를 편집합니다Project_B

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

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

  5. 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

    참고 항목

    PrepareBellPair Project_A 프로그램에서 직접 호출되지 않으므로 작업을 내보낼 필요가 없습니다. Project_B 로컬 범위에 있으므로 Teleport 작업에서 이미 액세스할 수 있습니다.

  6. 프로그램을 실행하려면 VS Code에서 /Project_A/Main.qs를 열고 실행을 선택합니다.

프로젝트 및 암시적 네임스페이스

Q# 프로젝트에서 네임스페이스가 *.qs 프로그램에 지정되지 않은 경우 컴파일러는 파일 이름을 네임스페이스로 사용합니다. 그런 다음 외부 종속성에서 호출 가능한 호출 가능 항목을 참조하면 dependencyName< 구문을 >사용합니다.<네임스페이스>입니다.<호출할 수 있습니다>. 그러나 파일 이름이 "Main.qs"인 경우 컴파일러는 네임스페이스를 가정하고 호출 구문은 dependencyName<이라고 >가정합니다.<이전 예제>와 같이 callableimport MyTeleportLib.Teleport입니다.

여러 프로젝트 파일이 있는 것은 드문 일이 아니므로 호출 가능 파일을 참조할 때 올바른 구문을 고려해야 합니다. 예를 들어 다음 파일 구조의 프로젝트에서

  • src/
    • Main.qs
    • MathFunctions.qs

외부 종속성에 대한 호출은

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

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

네임스페이스 동작에 대한 자세한 내용은 사용자 네임스페이스를 참조 하세요.