다음을 통해 공유


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

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

필수 조건

Python 프로그램을 실행하려면 다음도 필요합니다.

  • Python Python 및 Pip이 설치된 환경입니다.

  • qdk Python 라이브러리, azure 추가 선택 사항 포함.

    python -m pip install --upgrade "qdk[azure]"
    

프로젝트 작동 방식 Q#

Q# 프로젝트에는 Q# 매니페스트 파일( 명명됨qsharp.json) 및 지정된 폴더 구조의 하나 이상의 .qs 파일이 포함됩니다. 직접 VS Code에서 또는 수동으로 Q# 프로젝트를 만들 수 있습니다.

파일을 열 .qs 면 컴파일러가 VS Code주변 폴더 계층 구조에서 매니페스트 파일을 검색하고 프로젝트의 범위를 결정합니다. 매니페스트 파일을 찾을 수 없는 경우 컴파일러는 단일 파일 모드에서 작동합니다.

Jupyter Notebook 또는 Python 파일에 project_root를 설정하면 컴파일러가 project_root 폴더에서 매니페스트 파일을 찾습니다.

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

Q# 프로젝트 정의

Q# 프로젝트는 프로젝트의 루트 폴더에 있어야 하는 매니페스트 파일( qsharp.json 이름 및 src폴더)의 존재에 의해 정의됩니다. 폴더에 src 원본 파일이 포함되어 있습니다 Q# . 프로그램 및 외부 프로젝트의 Q# 경우 Q# 컴파일러는 프로젝트 폴더를 자동으로 검색합니다. 프로그램 및 Python 파일의 경우 Jupyter Notebook 호출을 사용하여 프로젝트 폴더를 Q#qsharp.init 지정해야 합니다. 그러나 프로젝트의 폴더 구조 Q# 는 모든 유형의 프로그램에 대해 동일합니다.

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

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

.qs 파일을 VS Code에서 열면, Q# 컴파일러는 폴더 구조를 따라 위쪽으로 매니페스트 파일을 검색합니다. 컴파일러가 매니페스트 파일을 찾은 경우 컴파일러는 디렉터리의 모든 Q# 파일 /src 과 모든 하위 디렉터리를 포함합니다. 각 파일에 정의된 항목은 프로젝트 내의 다른 모든 파일에서 사용할 수 있게 됩니다.

예를 들어 다음 폴더 구조를 고려합니다.

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

파일을 /src/TeleportOperation/PrepareState/PrepareStateLib.qsQ# 열면 컴파일러는 다음을 수행합니다.

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

매니페스트 파일 만들기

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

{}

매니페스트 파일 예제

다음 예제에서는 매니페스트 파일이 프로젝트의 범위를 정의하는 방법을 보여 줍니다 Q# .

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

    {
        "author":"Microsoft",
        "license": "MIT"
    }
    
  • Q# 프로젝트 내에서 매니페스트 파일을 사용하여 Linter 설정을 미세 조정할 VS CodeQ# 수도 있습니다. 기본적으로 세 가지 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# 프로젝트 요구 사항 및 속성

다음 요구 사항 및 구성은 모든 Q# 프로젝트에 적용됩니다.

  • 프로젝트에 포함하려는 모든 .qs 파일은 프로젝트의 루트 src 폴더 아래에 있어야 하는 폴더 Q#아래에 있어야 합니다. Q# 프로젝트를 VS Code에서 만들면 /src 폴더가 자동으로 생성됩니다.

  • 매니페스트 파일은 src 폴더와 같은 위치에 있어야 합니다. 프로젝트를 Q#에서 VS Code 만들면 최소 파일이 자동으로 생성됩니다.

  • 문을 사용하여 import 프로젝트의 다른 파일에서 작업 및 함수를 참조합니다.

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

    또는 네임스페이스를 사용하여 개별적으로 참조합니다.

    MyMathLib.Multiply(x,y); 
    

Q# 프로젝트 전용

  • 기본적으로 .qs 작업인 Q# 파일 하나에만 Main() 프로젝트의 진입점 작업을 정의할 수 있습니다.
  • 진입점 정의가 .qs 있는 파일을 매니페스트 파일 아래의 프로젝트 디렉터리 수준에 배치해야 합니다.
  • 디스플레이 .qs에서 예측 텍스트로 표시되는 VS Code의 내용을 캐시하는 Q# 프로젝트의 모든 작업과 기능.
  • 선택한 작업 또는 함수의 네임스페이스를 아직 VS Code 가져오지 않은 경우 필요한 import 문을 자동으로 추가합니다.

프로젝트를 만드는 Q# 방법

프로젝트를 만들 Q# 려면 다음 단계를 수행합니다.

  1. VS Code 파일 탐색기에서 프로젝트의 루트 폴더로 사용할 폴더 Q# 로 이동합니다.

  2. 보기 메뉴를 열고 명령 팔레트를 선택합니다.

  3. EnterQDK: Q# 프로젝트를 만들고 Enter 키를 누르십시오. VS Code 는 폴더에 최소 매니페스트 파일을 만들고 템플릿 파일이 있는 /src 폴더를 Main.qs 추가합니다.

  4. 프로젝트에 대한 매니페스트 파일을 편집합니다. 매니페스트 파일 예제를 참조 하세요.

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

  6. 프로그램 Python 또는 Jupyter Notebook에서 Q# 프로젝트에 액세스하는 경우 qsharp.init를 사용하여 루트 폴더 경로를 설정합니다. 이 예제는 프로그래밍이 /src 프로젝트의 Q# 폴더에 있다고 가정합니다.

    qsharp.init(project_root = '../Teleportation_project')
    
  7. VS Code에서 파일Q#만 사용하는 경우, 컴파일러는 Q# 파일을 여는 경우 매니페스트 파일을 검색하고, 그 후 프로젝트의 루트 폴더를 확인한 다음 하위 폴더에서 .qs 파일을 검색합니다.

참고 항목

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

예제 프로젝트

이 양자 텔레포트 프로그램은 Q# 로컬 시뮬레이터에서 실행되는 프로젝트의 한 예입니다 VS Code. 하드웨어 또는 타사 시뮬레이터에서 Azure Quantum 프로그램을 실행하려면 시작하기 Q# 및 VS Code 프로그램을 컴파일하고 작업 영역 Azure Quantum에 연결하는 단계를 참조하세요.

이 예제에는 다음과 같은 디렉터리 구조가 있습니다.

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

매니페스트 파일에는 작성자 및 라이선스 필드가 포함됩니다.

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

Q# 원본 파일

주 파일 Main.qs에는 진입점이 포함되어 있으며, TeleportOperations.TeleportLib에서 가져온 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 파일에서 Teleport 작업을 정의하고 PrepareBellPair 파일에서 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);
    }

파일에는 PrepareStateLib.qs Bell 쌍을 만드는 데 사용할 수 있는 표준 작업이 포함되어 있습니다.

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

프로그램 실행

프로그램을 실행하는 환경의 탭을 선택합니다.

이 프로그램을 실행하려면 파일을 Main.qs 열고 VS Code실행을 선택합니다.

외부 종속성으로 프로젝트 구성 Q#

라이브러리와 유사한 다른 프로젝트에 대한 외부 종속성으로 프로젝트를 구성할 Q# 수 있습니다. 외부 Q# 프로젝트의 함수 및 작업은 여러 Q# 프로젝트에서 사용할 수 있습니다. 외부 종속성은 드라이브 공유에 상주하거나 공용 GitHub 리포지토리에 게시할 수 있습니다.

프로젝트를 외부 종속성으로 사용 Q# 하려면 다음을 수행해야 합니다.

  • 외부 프로젝트를 호출 프로젝트의 매니페스트 파일에 종속성으로 추가합니다.
  • 외부 프로젝트가 GitHub에 게시된 경우 파일 속성을 외부 프로젝트의 매니페스트 파일에 추가합니다.
  • 외부 프로젝트에 문을 추가 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을 참조합니다. Microsoft에서는 특정 버전의 종속성을 신뢰할 수 있도록 항상 커밋 해시를 사용하는 것을 권장합니다.

외부 프로젝트 매니페스트 파일

외부 Q# 프로젝트가 공용 GitHub 리포지토리에 게시된 경우 프로젝트에 사용된 모든 파일을 포함하여 파일 속성을 외부 프로젝트의 매니페스트 파일에 추가해야 합니다.

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

외부 프로젝트가 를 통해 가져오는 경우 "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 Std.Diagnostics;import Std.Diagnostics.*;

외부 프로젝트 예제

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

  1. 로컬 드라이브에 두 개의 폴더를 만듭니다(예: Project_AProject_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
    

    참고 항목

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

  6. 프로그램을 실행하려면 열고 /Project_A/Main.qsVS Code실행을 선택합니다.

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

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

여러 프로젝트 파일이 있을 수 있으므로 호출 가능 항목을 참조할 때 올바른 구문을 고려해야 합니다. 예를 들어 다음 파일 구조를 가진 프로젝트를 고려합니다.

  • /src
    • Main.qs
    • MathFunctions.qs

다음 코드는 외부 종속성을 호출합니다.

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

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

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