From a2e661082ff7e07311ad0df6e6684653716407f6 Mon Sep 17 00:00:00 2001 From: Vincent van Wingerden <25651976+vivanwin@users.noreply.github.com> Date: Thu, 6 Aug 2020 09:42:22 +0200 Subject: Add documentation for Q# --- qsharp.html.markdown | 192 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 qsharp.html.markdown (limited to 'qsharp.html.markdown') diff --git a/qsharp.html.markdown b/qsharp.html.markdown new file mode 100644 index 00000000..b4a55d14 --- /dev/null +++ b/qsharp.html.markdown @@ -0,0 +1,192 @@ +--- +language: Q# +contributors: + - ["Vincent van Wingerden", "https://github.com/vivanwin"] + - ["Mariia Mykhailova", "https://github.com/tcNickolas"] +filename: LearnQSharp.qs +--- + +Q# is a high-level domain-specific language which enables developers to write quantum algorithms. Q# programs can be executed on a quantum simulator running on a classical computer and (in future) on quantum computers. + +This is the new outline +```C# +// Single-line comments start with // + +///////////////////////////////////// +// 1. Quantum data types and operators + +// The most important part of quantum programs is qubits. +// In Q# type Qubit represents the qubits which can be used. +// This will allocate an array of two new qubits as the variable qs. +using (qs = Qubit[2]) { + + // The qubits have internal state that you cannot access to read or modify directly. + // You can inspect the current state of your quantum program if you're running it on a classical simulator. + // Note that this will not work on actual quantum hardware! + DumpMachine(); + + // If you want to change the state of a qubit, you have to do this by applying quantum gates to the qubit. + H(q[0]); // This changes the state of the first qubit from |0⟩ (the initial state of allocated qubits) to (|0⟩ + |1⟩) / sqrt(2). + // q[1] = |1⟩; - this does NOT work, you have to manipulate a qubit by using gates. + + // You can apply multi-qubit gates to several qubits. + CNOT(qs[0], qs[1]); + + // You can also apply a controlled version of a gate: a gate that is applied if all control qubits are in |1⟩ state. + // The first argument is an array of control qubits, the second argument is the target qubit. + Controlled Y([qs[0]], qs[1]); + + // If you want to apply an anti-controlled gate (a gate that is applied if all control qubits are in |0⟩ state), you can use a library function. + ApplyControlledOnInt(0, X, [qs[0]], qs[1]); + + // To read the information from the quantum system, you use measurements. + // Measurements return a value of Result data type: Zero or One. + // You can print measurement results as a classical value. + Message($"Measured {M(qs[0])}, {M(qs[1])}"); +} + + +///////////////////////////////////// +// 2. Classical data types and operators + +// Numbers in Q# can be stored in Int, BigInt or Double. +let i = 1; // This defines an Int variable i equal to 1 +let bi = 1L; // This defines a BigInt variable bi equal to 1 +let d = 1.0; // This defines a Double variable d equal to 1 + +// Arithmetic is done as expected, as long as the types are the same +let n = 2 * 10; // = 20 +// Q# does not have implicit type cast, so to perform arithmetic on values of different types, you need to cast type explicitly +let nd = IntAsDouble(2) * 1.0; // = 20.0 + +// Boolean type is called Bool +let trueBool = true; +let falseBool = false; + +// Logic operators work as expected +let andBool = true and false; +let orBool = true or false; +let notBool = not false; + +// Strings +let str = "Hello World!"; + +// Equality is == +let x = 10 == 15; // is false + +// Range is a sequence of integers and can be defined like: start..step..stop +let xi = 1..2..7; // Gives the sequence 1,3,5,7 + +// Assigning new value to a variable: +// by default all Q# variables are immutable; +// if the variable was defined using let, you cannot reassign its value. + +// When you want to make a variable mutable, you have to declare it as such, +// and use the set word to update value +mutable xii = true; +set xii = false; + +// You can create an array for any data type like this +let xiii = new Double[10]; + +// Getting an element from an array +let xiv = xiii[8]; + +// Assigning a new value to an array element +mutable xv = new Double[10]; +set xv w/= 5 <- 1; + + +///////////////////////////////////// +// 3. Control flow + +// If structures work a little different than most languages +if (a == 1) { + // ... +} elif (a == 2) { + // ... +} else { + // ... +} + +// Foreach loops can be used to iterate over an array +for (qubit in qubits) { + X(qubit); +} + +// Regular for loops can be used to iterate over a range of numbers +for (index in 0 .. Length(qubits) - 1) { + X(qubits[index]); +} + +// While loops are restricted for use in classical context only +mutable index = 0; +while (index < 10) { + set index += 1; +} + +// Quantum equivalent of a while loop is a repeat-until-success loop. +// Because of the probabilistic nature of quantum computing sometimes +// you want to repeat a certain sequence of operations until a specific condition is achieved; you can use this loop to express this. +repeat { + // Your operation here +} +until (success criteria) // This could be a measurement to check if the state is reached +fixup { + // Resetting to the initial conditions, if required +} + + +///////////////////////////////////// +// 4. Putting it all together + +// Q# code is written in operations and functions +operation ApplyXGate(source : Qubit) : Unit { + X(source); +} + +// If the operation implements a unitary transformation, you can define +// adjoint and controlled variants of it. +// The easiest way to do that is to add "is Adj + Ctl" after Unit. +// This will tell the compiler to generate the variants automatically. +operation ApplyXGateCA (source : Qubit) : Unit is Adj + Ctl { + X(source); +} + +// Now you can call Adjoint ApplyXGateCA and Controlled ApplyXGateCA. + + +// To run Q# code, you can put @EntryPoint() before the operation you want to run first +@EntryPoint() +operation XGateDemo() : Unit { + using (q = Qubit()) { + ApplyXGate(q); + } +} + +// Here is a simple example: a quantum random number generator. +// We will generate a classical array of random bits using quantum code. +@EntryPoint() +operation QRNGDemo() : Unit { + mutable bits = new Int[5]; // Array we'll use to store bits + using (q = Qubit()) { // Allocate a qubit + for (i in 0 .. 4) { // Generate each bit independently + H(q); // Apply Hadamard gate to prepare equal superposition + let result = M(q); // Measure the qubit to get Zero or One with 50/50 probability + let bit = result == Zero ? 0 | 1; // Convert measurement result to an integer + set bits w/= i <- bit; // Write generated bit to an array + } + } + Message($"{bits}"); // Print the result +} +``` + + +## Further Reading + +The [Quantum Katas][1] offer great self-paced tutorials and programming exercises to learn quantum computing and Q#. + +[Q# Documentation][2] is official Q# documentation, including language reference and user guides. + +[1]: https://github.com/microsoft/QuantumKatas +[2]: https://docs.microsoft.com/quantum/ \ No newline at end of file -- cgit v1.2.3 From 7e28066384d24f80bd4edfdeedfea82d6ba12656 Mon Sep 17 00:00:00 2001 From: Andrew Ryan Davis Date: Thu, 6 Aug 2020 13:55:38 -0700 Subject: Formatting fix Changing formatting to fix issue --- qsharp.html.markdown | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'qsharp.html.markdown') diff --git a/qsharp.html.markdown b/qsharp.html.markdown index b4a55d14..f778aea7 100644 --- a/qsharp.html.markdown +++ b/qsharp.html.markdown @@ -9,6 +9,7 @@ filename: LearnQSharp.qs Q# is a high-level domain-specific language which enables developers to write quantum algorithms. Q# programs can be executed on a quantum simulator running on a classical computer and (in future) on quantum computers. This is the new outline + ```C# // Single-line comments start with // @@ -189,4 +190,4 @@ The [Quantum Katas][1] offer great self-paced tutorials and programming exercise [Q# Documentation][2] is official Q# documentation, including language reference and user guides. [1]: https://github.com/microsoft/QuantumKatas -[2]: https://docs.microsoft.com/quantum/ \ No newline at end of file +[2]: https://docs.microsoft.com/quantum/ -- cgit v1.2.3 From ceefb4adf521bed164122388a3121f262903b852 Mon Sep 17 00:00:00 2001 From: Andrew Ryan Davis Date: Thu, 6 Aug 2020 14:15:59 -0700 Subject: Adjusting formatting to clean up carriage return and multi line comment The line limit is making things a bit skewed, and adding multi line comment --- qsharp.html.markdown | 70 +++++++++++++++++++++++++++++++--------------------- 1 file changed, 42 insertions(+), 28 deletions(-) (limited to 'qsharp.html.markdown') diff --git a/qsharp.html.markdown b/qsharp.html.markdown index f778aea7..409eac4a 100644 --- a/qsharp.html.markdown +++ b/qsharp.html.markdown @@ -3,6 +3,7 @@ language: Q# contributors: - ["Vincent van Wingerden", "https://github.com/vivanwin"] - ["Mariia Mykhailova", "https://github.com/tcNickolas"] + - ["Andrew Ryan Davis", "https://github.com/AndrewDavis1191"] filename: LearnQSharp.qs --- @@ -13,6 +14,11 @@ This is the new outline ```C# // Single-line comments start with // +/ +Multi-line comments +like so +\ + ///////////////////////////////////// // 1. Quantum data types and operators @@ -22,27 +28,33 @@ This is the new outline using (qs = Qubit[2]) { // The qubits have internal state that you cannot access to read or modify directly. - // You can inspect the current state of your quantum program if you're running it on a classical simulator. + // You can inspect the current state of your quantum program + // if you're running it on a classical simulator. // Note that this will not work on actual quantum hardware! DumpMachine(); - // If you want to change the state of a qubit, you have to do this by applying quantum gates to the qubit. - H(q[0]); // This changes the state of the first qubit from |0⟩ (the initial state of allocated qubits) to (|0⟩ + |1⟩) / sqrt(2). + // If you want to change the state of a qubit + // you have to do this by applying quantum gates to the qubit. + H(q[0]); // This changes the state of the first qubit + // from |0⟩ (the initial state of allocated qubits) to (|0⟩ + |1⟩) / sqrt(2). // q[1] = |1⟩; - this does NOT work, you have to manipulate a qubit by using gates. // You can apply multi-qubit gates to several qubits. CNOT(qs[0], qs[1]); - // You can also apply a controlled version of a gate: a gate that is applied if all control qubits are in |1⟩ state. - // The first argument is an array of control qubits, the second argument is the target qubit. + / You can also apply a controlled version of a gate: + a gate that is applied if all control qubits are in |1⟩ state. + \ The first argument is an array of control qubits, the second argument is the target qubit. Controlled Y([qs[0]], qs[1]); - // If you want to apply an anti-controlled gate (a gate that is applied if all control qubits are in |0⟩ state), you can use a library function. + / If you want to apply an anti-controlled gate + (a gate that is applied if all control qubits are in |0⟩ state), + \ you can use a library function. ApplyControlledOnInt(0, X, [qs[0]], qs[1]); - // To read the information from the quantum system, you use measurements. - // Measurements return a value of Result data type: Zero or One. - // You can print measurement results as a classical value. + / To read the information from the quantum system, you use measurements. + Measurements return a value of Result data type: Zero or One. + \ You can print measurement results as a classical value. Message($"Measured {M(qs[0])}, {M(qs[1])}"); } @@ -57,7 +69,8 @@ let d = 1.0; // This defines a Double variable d equal to 1 // Arithmetic is done as expected, as long as the types are the same let n = 2 * 10; // = 20 -// Q# does not have implicit type cast, so to perform arithmetic on values of different types, you need to cast type explicitly +// Q# does not have implicit type cast, +// so to perform arithmetic on values of different types, you need to cast type explicitly let nd = IntAsDouble(2) * 1.0; // = 20.0 // Boolean type is called Bool @@ -78,9 +91,9 @@ let x = 10 == 15; // is false // Range is a sequence of integers and can be defined like: start..step..stop let xi = 1..2..7; // Gives the sequence 1,3,5,7 -// Assigning new value to a variable: -// by default all Q# variables are immutable; -// if the variable was defined using let, you cannot reassign its value. +/ Assigning new value to a variable: + by default all Q# variables are immutable; +\ if the variable was defined using let, you cannot reassign its value. // When you want to make a variable mutable, you have to declare it as such, // and use the set word to update value @@ -126,9 +139,10 @@ while (index < 10) { set index += 1; } -// Quantum equivalent of a while loop is a repeat-until-success loop. -// Because of the probabilistic nature of quantum computing sometimes -// you want to repeat a certain sequence of operations until a specific condition is achieved; you can use this loop to express this. +/ Quantum equivalent of a while loop is a repeat-until-success loop. + Because of the probabilistic nature of quantum computing sometimes + you want to repeat a certain sequence of operations +\ until a specific condition is achieved; you can use this loop to express this. repeat { // Your operation here } @@ -146,10 +160,10 @@ operation ApplyXGate(source : Qubit) : Unit { X(source); } -// If the operation implements a unitary transformation, you can define -// adjoint and controlled variants of it. -// The easiest way to do that is to add "is Adj + Ctl" after Unit. -// This will tell the compiler to generate the variants automatically. +/ If the operation implements a unitary transformation, you can define + adjoint and controlled variants of it. + The easiest way to do that is to add "is Adj + Ctl" after Unit. +\ This will tell the compiler to generate the variants automatically. operation ApplyXGateCA (source : Qubit) : Unit is Adj + Ctl { X(source); } @@ -169,16 +183,16 @@ operation XGateDemo() : Unit { // We will generate a classical array of random bits using quantum code. @EntryPoint() operation QRNGDemo() : Unit { - mutable bits = new Int[5]; // Array we'll use to store bits - using (q = Qubit()) { // Allocate a qubit - for (i in 0 .. 4) { // Generate each bit independently - H(q); // Apply Hadamard gate to prepare equal superposition - let result = M(q); // Measure the qubit to get Zero or One with 50/50 probability - let bit = result == Zero ? 0 | 1; // Convert measurement result to an integer - set bits w/= i <- bit; // Write generated bit to an array + mutable bits = new Int[5]; / Array we'll use to store bits + using (q = Qubit()) { / Allocate a qubit + for (i in 0 .. 4) { / Generate each bit independently + H(q); / Apply Hadamard gate prepares equal superposition + let result = M(q); / Measure the qubit to get 0 or 1 with 50/50 prob + let bit = result == Zero ? 0 | 1; / Convert measurement result to an integer + set bits w/= i <- bit; / Write generated bit to an array } } - Message($"{bits}"); // Print the result + Message($"{bits}"); / Print the result } ``` -- cgit v1.2.3 From 983a48226a7e03ab44e0f363593b000f242d7fe9 Mon Sep 17 00:00:00 2001 From: Andrew Ryan Davis Date: Thu, 6 Aug 2020 14:26:18 -0700 Subject: Changing those comments back until a Q# formatter is available Looks like using C# formatter, it can't accept the Q# multi-lines. Makes sense --- qsharp.html.markdown | 62 +++++++++++++++++++++++++++------------------------- 1 file changed, 32 insertions(+), 30 deletions(-) (limited to 'qsharp.html.markdown') diff --git a/qsharp.html.markdown b/qsharp.html.markdown index 409eac4a..16f7f96d 100644 --- a/qsharp.html.markdown +++ b/qsharp.html.markdown @@ -14,10 +14,12 @@ This is the new outline ```C# // Single-line comments start with // -/ +*// Multi-line comments like so -\ +\*/ + +// Note: Using C# multi-line around Q# because there doesn't appear to be a markdown formatter yet. ///////////////////////////////////// // 1. Quantum data types and operators @@ -42,19 +44,19 @@ using (qs = Qubit[2]) { // You can apply multi-qubit gates to several qubits. CNOT(qs[0], qs[1]); - / You can also apply a controlled version of a gate: - a gate that is applied if all control qubits are in |1⟩ state. - \ The first argument is an array of control qubits, the second argument is the target qubit. + // You can also apply a controlled version of a gate: + // a gate that is applied if all control qubits are in |1⟩ state. + // The first argument is an array of control qubits, the second argument is the target qubit. Controlled Y([qs[0]], qs[1]); - / If you want to apply an anti-controlled gate - (a gate that is applied if all control qubits are in |0⟩ state), - \ you can use a library function. + // If you want to apply an anti-controlled gate + // (a gate that is applied if all control qubits are in |0⟩ state), + // you can use a library function. ApplyControlledOnInt(0, X, [qs[0]], qs[1]); - / To read the information from the quantum system, you use measurements. - Measurements return a value of Result data type: Zero or One. - \ You can print measurement results as a classical value. + // To read the information from the quantum system, you use measurements. + // Measurements return a value of Result data type: Zero or One. + // You can print measurement results as a classical value. Message($"Measured {M(qs[0])}, {M(qs[1])}"); } @@ -91,9 +93,9 @@ let x = 10 == 15; // is false // Range is a sequence of integers and can be defined like: start..step..stop let xi = 1..2..7; // Gives the sequence 1,3,5,7 -/ Assigning new value to a variable: - by default all Q# variables are immutable; -\ if the variable was defined using let, you cannot reassign its value. +// Assigning new value to a variable: +// by default all Q# variables are immutable; +// if the variable was defined using let, you cannot reassign its value. // When you want to make a variable mutable, you have to declare it as such, // and use the set word to update value @@ -139,10 +141,10 @@ while (index < 10) { set index += 1; } -/ Quantum equivalent of a while loop is a repeat-until-success loop. - Because of the probabilistic nature of quantum computing sometimes - you want to repeat a certain sequence of operations -\ until a specific condition is achieved; you can use this loop to express this. +// Quantum equivalent of a while loop is a repeat-until-success loop. +// Because of the probabilistic nature of quantum computing sometimes +// you want to repeat a certain sequence of operations +// until a specific condition is achieved; you can use this loop to express this. repeat { // Your operation here } @@ -160,10 +162,10 @@ operation ApplyXGate(source : Qubit) : Unit { X(source); } -/ If the operation implements a unitary transformation, you can define - adjoint and controlled variants of it. - The easiest way to do that is to add "is Adj + Ctl" after Unit. -\ This will tell the compiler to generate the variants automatically. +// If the operation implements a unitary transformation, you can define +// adjoint and controlled variants of it. +// The easiest way to do that is to add "is Adj + Ctl" after Unit. +// This will tell the compiler to generate the variants automatically. operation ApplyXGateCA (source : Qubit) : Unit is Adj + Ctl { X(source); } @@ -183,16 +185,16 @@ operation XGateDemo() : Unit { // We will generate a classical array of random bits using quantum code. @EntryPoint() operation QRNGDemo() : Unit { - mutable bits = new Int[5]; / Array we'll use to store bits - using (q = Qubit()) { / Allocate a qubit - for (i in 0 .. 4) { / Generate each bit independently - H(q); / Apply Hadamard gate prepares equal superposition - let result = M(q); / Measure the qubit to get 0 or 1 with 50/50 prob - let bit = result == Zero ? 0 | 1; / Convert measurement result to an integer - set bits w/= i <- bit; / Write generated bit to an array + mutable bits = new Int[5]; // Array we'll use to store bits + using (q = Qubit()) { // Allocate a qubit + for (i in 0 .. 4) { // Generate each bit independently + H(q); // Apply Hadamard gate prepares equal superposition + let result = M(q); // Measure the qubit to get 0 or 1 with 50/50 prob + let bit = result == Zero ? 0 | 1; // Convert measurement result to an integer + set bits w/= i <- bit; // Write generated bit to an array } } - Message($"{bits}"); / Print the result + Message($"{bits}"); // Print the result } ``` -- cgit v1.2.3 From b70f50c666da9358d1f5b9a0b7745464453126a7 Mon Sep 17 00:00:00 2001 From: Andrew Ryan Davis Date: Thu, 6 Aug 2020 14:45:02 -0700 Subject: Fixing that pesky multi-line --- qsharp.html.markdown | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'qsharp.html.markdown') diff --git a/qsharp.html.markdown b/qsharp.html.markdown index 16f7f96d..034af3c9 100644 --- a/qsharp.html.markdown +++ b/qsharp.html.markdown @@ -14,10 +14,12 @@ This is the new outline ```C# // Single-line comments start with // -*// +/* +/ Multi-line comments like so -\*/ +\ +*/ // Note: Using C# multi-line around Q# because there doesn't appear to be a markdown formatter yet. -- cgit v1.2.3 From af19db1735a0b8dfcb675661c5bc8a4cbfa5af9b Mon Sep 17 00:00:00 2001 From: Andrew Ryan Davis Date: Thu, 6 Aug 2020 14:50:39 -0700 Subject: Fixing last remaining carriage return formatting --- qsharp.html.markdown | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) (limited to 'qsharp.html.markdown') diff --git a/qsharp.html.markdown b/qsharp.html.markdown index 034af3c9..bf51a58b 100644 --- a/qsharp.html.markdown +++ b/qsharp.html.markdown @@ -21,7 +21,8 @@ like so \ */ -// Note: Using C# multi-line around Q# because there doesn't appear to be a markdown formatter yet. +// Note: Using C# multi-line around Q# +// there doesn't appear to be a Q# markdown formatter yet. ///////////////////////////////////// // 1. Quantum data types and operators @@ -40,7 +41,8 @@ using (qs = Qubit[2]) { // If you want to change the state of a qubit // you have to do this by applying quantum gates to the qubit. H(q[0]); // This changes the state of the first qubit - // from |0⟩ (the initial state of allocated qubits) to (|0⟩ + |1⟩) / sqrt(2). + // from |0⟩ (the initial state of allocated qubits) + // to (|0⟩ + |1⟩) / sqrt(2). // q[1] = |1⟩; - this does NOT work, you have to manipulate a qubit by using gates. // You can apply multi-qubit gates to several qubits. @@ -48,7 +50,8 @@ using (qs = Qubit[2]) { // You can also apply a controlled version of a gate: // a gate that is applied if all control qubits are in |1⟩ state. - // The first argument is an array of control qubits, the second argument is the target qubit. + // The first argument is an array of control qubits, + // the second argument is the target qubit. Controlled Y([qs[0]], qs[1]); // If you want to apply an anti-controlled gate @@ -74,7 +77,8 @@ let d = 1.0; // This defines a Double variable d equal to 1 // Arithmetic is done as expected, as long as the types are the same let n = 2 * 10; // = 20 // Q# does not have implicit type cast, -// so to perform arithmetic on values of different types, you need to cast type explicitly +// so to perform arithmetic on values of different types, +// you need to cast type explicitly let nd = IntAsDouble(2) * 1.0; // = 20.0 // Boolean type is called Bool @@ -190,9 +194,9 @@ operation QRNGDemo() : Unit { mutable bits = new Int[5]; // Array we'll use to store bits using (q = Qubit()) { // Allocate a qubit for (i in 0 .. 4) { // Generate each bit independently - H(q); // Apply Hadamard gate prepares equal superposition - let result = M(q); // Measure the qubit to get 0 or 1 with 50/50 prob - let bit = result == Zero ? 0 | 1; // Convert measurement result to an integer + H(q); // Hadamard gate sets equal superposition + let result = M(q); // Measure qubit gets 0|1 with 50/50 prob + let bit = result == Zero ? 0 | 1; // Convert measurement result to integer set bits w/= i <- bit; // Write generated bit to an array } } -- cgit v1.2.3 From 17e3a634414f61be4fc4f456cae3d489cc32b224 Mon Sep 17 00:00:00 2001 From: Mariia Mykhailova Date: Thu, 6 Aug 2020 15:26:59 -0700 Subject: [qsharp/en] Remove mention of multi-line comments Q# does not support multi-line comments, so that mention can be misleading. --- qsharp.html.markdown | 11 ----------- 1 file changed, 11 deletions(-) (limited to 'qsharp.html.markdown') diff --git a/qsharp.html.markdown b/qsharp.html.markdown index bf51a58b..b256043c 100644 --- a/qsharp.html.markdown +++ b/qsharp.html.markdown @@ -9,20 +9,9 @@ filename: LearnQSharp.qs Q# is a high-level domain-specific language which enables developers to write quantum algorithms. Q# programs can be executed on a quantum simulator running on a classical computer and (in future) on quantum computers. -This is the new outline - ```C# // Single-line comments start with // -/* -/ -Multi-line comments -like so -\ -*/ - -// Note: Using C# multi-line around Q# -// there doesn't appear to be a Q# markdown formatter yet. ///////////////////////////////////// // 1. Quantum data types and operators -- cgit v1.2.3