Amostras contribuindo para o Kit de Desenvolvimento QuânticoContributing Samples to the Quantum Development Kit

Se está interessado em contribuir com o código para o repositório de amostras,obrigado por fazer da comunidade de desenvolvimento quântico um lugar melhor!If you're interested in contributing code to the samples repository, thank you for making the quantum development community a better place!

O Kit de Desenvolvimento Quântico mostra repositórioThe Quantum Development Kit Samples Repository

Para ajudá-lo a preparar a sua contribuição para ajudar o máximo possível, é útil dar uma olhada rápida na forma como o repositório de amostras está definido:To help you prepare your contribution to help out as much as possible, it's helpful to take a quick look at how the samples repository is laid out:

microsoft/Quantum
📁 samples/
  📁 algorithms/
    📁 chsh-game/
      📝 CHSHGame.csproj
      📝 Game.qs
      📝 Host.cs
      📝 host.py
      📝 README.md
     ⋮
  📁 arithmetic/
  📁 characterization/
  📁 chemistry/
   ⋮

Ou seja, as amostras do repositório microsoft/Quantum são divididas por área temática em diferentes pastas, tais como algorithms/ , ou arithmetic/ characterization/ .That is, the samples in the microsoft/Quantum repository are broken down by subject area into different folders such as algorithms/, arithmetic/, or characterization/. Dentro da pasta para cada área de assunto, cada amostra é constituída por uma única pasta que recolhe tudo o que um utilizador precisa para explorar e fazer uso dessa amostra.Within the folder for each subject area, each sample consists of a single folder that collects everything a user will need to explore and make use of that sample.

Como as amostras são estruturadasHow Samples are Structured

Olhando para os ficheiros que compõem cada pasta, vamos mergulhar na algorithms/chsh-game/ amostra.Looking at the files that make up each folder, let's dive into the algorithms/chsh-game/ sample.

FicheiroFile DescriçãoDescription
CHSHGame.csproj Q# projeto usado para construir a amostra com o .NET Core SDKQ# project used to build the sample with the .NET Core SDK
Game.qs Q# operações e funções para a amostraQ# operations and functions for the sample
Host.cs C# programa de anfitrião usado para executar a amostraC# host program used to run the sample
host.py Programa de anfitrião python usado para executar a amostraPython host program used to run the sample
README.md Documentação sobre o que a amostra faz e como usá-laDocumentation on what the sample does and how to use it

Nem todas as amostras terão exatamente o mesmo conjunto de ficheiros (por exemplo: algumas amostras podem ser C#-only, outras podem não ter um hospedeiro Python, ou algumas amostras podem exigir que os ficheiros de dados auxillary funcionem).Not all samples will have the exact same set of files (e.g.: some samples may be C#-only, others may not have a Python host, or some samples may require auxillary data files to work).

Anatomia de um Arquivo README ÚtilAnatomy of a Helpful README File

Um ficheiro especialmente importante, no entanto, é o README.md ficheiro, já que é isso que os utilizadores precisam para começar com a sua amostra!One especially important file, though, is the README.md file, as that's what users need to get started with your sample!

Cada um README.md deve começar com alguns metadados que ajudam docs.microsoft.com/samples encontrar a sua contribuição.Each README.md should start with some metadata that helps docs.microsoft.com/samples find your contribution.

Estes metadados são fornecidos como um cabeçalho YAML que indica quais as línguas que a sua amostra cobre (normalmente, isto será qsharp , e ) e quais os produtos que a sua amostra cobre csharp python (normalmente, qdk apenas).This metadata is provided as a YAML header that indicates what languages your sample covers (typically, this will be qsharp, csharp, and python), and what products your sample covers (typically, just qdk).

---
page_type: sample
languages:
- qsharp
- python
- csharp
products:
- qdk
description: "This sample uses the CHSH game to demonstrate how Q# programs can be used to prepare and work with entanglement."
urlFragment: validating-quantum-mechanics
jupyter:

Importante

A page_type: sample chave no cabeçalho é necessária para que a sua amostra apareça em docs.microsoft.com/samples.The page_type: sample key in the header is required for your sample to appear at docs.microsoft.com/samples. Da mesma forma, as product chaves e as chaves são language fundamentais para ajudar os utilizadores a encontrar e executar a sua amostra.Similarly, the product and language keys are critical for helping users to find and run your sample.

Depois disso, é útil dar uma pequena introdução que diga o que a sua nova amostra faz:After that, it's helpful to give a short intro that says what your new sample does:

  cell_markers: region,endregion
  text_representation:
    extension: .md
    format_name: markdown
    format_version: '1.2'
    jupytext_version: 1.5.2
kernelspec:
  display_name: .NET (PowerShell)
  language: PowerShell

Os utilizadores da sua amostra também apreciarão saber o que precisam para executá-lo (por exemplo: os utilizadores só precisam do próprio Kit de Desenvolvimento Quântico, ou precisam de software adicional, como node.js?):Users of your sample will also appreciate knowing what they need to run it (e.g.: do users just need the Quantum Development Kit itself, or do they need additional software such as node.js?):

---

# Validating Quantum Mechanics with the CHSH Game

Com tudo isso no lugar, pode dizer aos utilizadores como executar a sua amostra:With all that in place, you can tell users how to run your sample:

This sample demonstrates:
- How to prepare entangled states with Q#.
- How to measure part of an entangled register.
- Using Q# to understand superposition and entanglement.

In this sample, you can use Q# to prepare qubits in an entangled state, and to check that measuring these qubits lets you win a game known as the _CHSH game_ more often than you can without entanglement.
This game helps us understand entanglement, and has even been used experimentally to help test that the universe really is quantum mechanical in nature.

## Prerequisites

- The Microsoft [Quantum Development Kit](https://docs.microsoft.com/quantum/install-guide/).

## Running the Sample

This sample can be run in a number of different ways, depending on your preferred environment.

### Python in Visual Studio Code or the Command Line

At a terminal, run the following command:

```powershell
python host.py
```

Finalmente, é útil dizer aos utilizadores o que cada ficheiro da sua amostra faz, e onde podem ir para mais informações:Finally, it's helpful to tell users what each file in your sample does, and where they can go for more information:


At a terminal, run the following command:

```powershell
dotnet run
```

### C# in Visual Studio 2019

Open the folder containing this sample in Visual Studio ("Open a local folder"

Aviso

Certifique-se de que utiliza URLs absolutos aqui, uma vez que a sua amostra aparecerá num URL diferente quando renderizado em docs.microsoft.com/samples!Make sure to use absolute URLs here, since your sample will appear at a different URL when rendered at docs.microsoft.com/samples!