diff --git a/compiler/qsc_partial_eval/src/tests/misc.rs b/compiler/qsc_partial_eval/src/tests/misc.rs index 3fdb33df0a..49dd390953 100644 --- a/compiler/qsc_partial_eval/src/tests/misc.rs +++ b/compiler/qsc_partial_eval/src/tests/misc.rs @@ -602,5 +602,5 @@ fn evaluation_error_within_stdlib_yield_correct_package_span() { } "#, }); - assert_error(&error, &expect!["UnexpectedDynamicValue(PackageSpan { package: PackageId(1), span: Span { lo: 13654, hi: 13669 } })"]); + assert_error(&error, &expect!["UnexpectedDynamicValue(PackageSpan { package: PackageId(1), span: Span { lo: 13850, hi: 13865 } })"]); } diff --git a/library/std/src/Std/Arrays.qs b/library/std/src/Std/Arrays.qs index bd099bda12..ff577e0ff3 100644 --- a/library/std/src/Std/Arrays.qs +++ b/library/std/src/Std/Arrays.qs @@ -37,6 +37,7 @@ function All<'T>(predicate : ('T -> Bool), array : 'T[]) : Bool { true } +/// # Summary /// Given an array and a predicate that is defined /// for the elements of the array, checks if at least one element of /// the array satisfies the predicate. @@ -68,6 +69,7 @@ function Any<'T>(predicate : ('T -> Bool), array : 'T[]) : Bool { false } +/// # Summary /// Splits an array into multiple parts of equal length. /// /// # Input @@ -95,6 +97,7 @@ function Chunks<'T>(chunkSize : Int, array : 'T[]) : 'T[][] { output } +/// # Summary /// Shift an array circularly left or right by a specific step size. /// /// # Type Parameters @@ -142,6 +145,7 @@ function CircularlyShifted<'T>(stepCount : Int, array : 'T[]) : 'T[] { rightPart + leftPart } +/// # Summary /// Extracts a column from a matrix. /// /// # Description @@ -178,6 +182,7 @@ function ColumnAt<'T>(column : Int, matrix : 'T[][]) : 'T[] { columnValues } +/// # Summary /// Given an array and a predicate that is defined /// for the elements of the array, returns the number of elements /// an array that consists of those elements that satisfy the predicate. @@ -210,6 +215,7 @@ function Count<'T>(predicate : ('T -> Bool), array : 'T[]) : Int { count } +/// # Summary /// Returns an array of diagonal elements of a 2-dimensional array /// /// # Description @@ -246,6 +252,7 @@ function Diagonal<'T>(matrix : 'T[][]) : 'T[] { diagonal } +/// # Summary /// Repeats an operation for a given number of samples, collecting its outputs /// in an array. /// @@ -277,6 +284,7 @@ operation DrawMany<'TInput, 'TOutput>(op : ('TInput => 'TOutput), nSamples : Int outputs } +/// # Summary /// Given an array, returns a new array containing elements of the original /// array along with the indices of each element. /// @@ -305,6 +313,7 @@ function Enumerated<'TElement>(array : 'TElement[]) : (Int, 'TElement)[] { MappedByIndex((index, element) -> (index, element), array) } +/// # Summary /// Returns an array containing the elements of another array, /// excluding elements at a given list of indices. /// @@ -346,6 +355,7 @@ function Excluding<'T>(remove : Int[], array : 'T[]) : 'T[] { output } +/// # Summary /// Given an array and a predicate that is defined /// for the elements of the array, returns an array that consists of /// those elements that satisfy the predicate. @@ -378,6 +388,7 @@ function Filtered<'T>(predicate : ('T -> Bool), array : 'T[]) : 'T[] { filtered } +/// # Summary /// Given an array and a function that maps an array element to some output /// array, returns the concatenated output arrays for each array element. /// @@ -411,6 +422,7 @@ function FlatMapped<'TInput, 'TOutput>(mapper : ('TInput -> 'TOutput[]), array : output } +/// # Summary /// Given an array of arrays, returns the concatenation of all arrays. /// /// # Type Parameters @@ -437,6 +449,7 @@ function Flattened<'T>(arrays : 'T[][]) : 'T[] { output } +/// # Summary /// Iterates a function `f` through an array `array`, returning /// `f(...f(f(initialState, array[0]), array[1]), ...)`. /// @@ -471,6 +484,7 @@ function Fold<'State, 'T>(folder : (('State, 'T) -> 'State), state : 'State, arr current } +/// # Summary /// Given an array and an operation that is defined /// for the elements of the array, returns a new array that consists /// of the images of the original array under the operation. @@ -500,6 +514,7 @@ operation ForEach<'T, 'U>(action : ('T => 'U), array : 'T[]) : 'U[] { output } +/// # Summary /// Returns the first element of the array. /// /// # Type Parameters @@ -517,6 +532,7 @@ function Head<'A>(array : 'A[]) : 'A { array[0] } +/// # Summary /// Returns a tuple of first and all remaining elements of the array. /// /// # Type Parameters @@ -533,6 +549,7 @@ function HeadAndRest<'A>(array : 'A[]) : ('A, 'A[]) { (Head(array), Rest(array)) } +/// # Summary /// Returns the first index of the first element in an array that satisfies /// a given predicate. If no such element exists, returns -1. /// @@ -561,6 +578,7 @@ function IndexOf<'T>(predicate : ('T -> Bool), array : 'T[]) : Int { -1 } +/// # Summary /// Given an array, returns a range over the indices of that array, suitable /// for use in a for loop. /// @@ -585,6 +603,7 @@ function IndexRange<'TElement>(array : 'TElement[]) : Range { 0..Length(array) - 1 } +/// # Summary /// Interleaves two arrays of (almost) same size. /// /// # Description @@ -632,6 +651,7 @@ function Interleaved<'T>(first : 'T[], second : 'T[]) : 'T[] { interleaved } +/// # Summary /// Returns true if and only if an array is empty. /// /// # Input @@ -644,6 +664,7 @@ function IsEmpty<'T>(array : 'T[]) : Bool { Length(array) == 0 } +/// # Summary /// Returns whether a 2-dimensional array has a rectangular shape /// /// # Type Parameters @@ -679,6 +700,7 @@ function IsRectangularArray<'T>(array : 'T[][]) : Bool { true } +/// # Summary /// Given an array, returns whether that array is sorted as defined by /// a given comparison function. /// @@ -710,6 +732,7 @@ function IsSorted<'T>(comparison : (('T, 'T) -> Bool), array : 'T[]) : Bool { true } +/// # Summary /// Returns whether a 2-dimensional array has a square shape /// /// # Type Parameters @@ -745,6 +768,7 @@ function IsSquareArray<'T>(array : 'T[][]) : Bool { true } +/// # Summary /// Given an array and a function that is defined /// for the elements of the array, returns a new array that consists /// of the images of the original array under the function. @@ -774,6 +798,7 @@ function Mapped<'T, 'U>(mapper : ('T -> 'U), array : 'T[]) : 'U[] { mapped } +/// # Summary /// Given an array and a function that is defined /// for the indexed elements of the array, returns a new array that consists /// of the images of the original array under the function. @@ -814,6 +839,7 @@ function MappedByIndex<'T, 'U>(mapper : ((Int, 'T) -> 'U), array : 'T[]) : 'U[] mapped } +/// # Summary /// Given a range and a function that takes an integer as input, /// returns a new array that consists /// of the images of the range values under the function. @@ -848,6 +874,7 @@ function MappedOverRange<'T>(mapper : (Int -> 'T), range : Range) : 'T[] { output } +/// # Summary /// Creates an array that is equal to an input array except that the last array /// element is dropped. /// @@ -865,6 +892,7 @@ function Most<'T>(array : 'T[]) : 'T[] { array[...Length(array) - 2] } +/// # Summary /// Returns a tuple of all but one and the last element of the array. /// /// # Type Parameters @@ -881,6 +909,7 @@ function MostAndTail<'A>(array : 'A[]) : ('A[], 'A) { (Most(array), Tail(array)) } +/// # Summary /// Returns an array padded at with specified values up to a /// specified length. /// @@ -925,6 +954,7 @@ function Padded<'T>(paddedLength : Int, defaultElement : 'T, inputArray : 'T[]) } } +/// # Summary /// Splits an array into multiple parts. /// /// # Input @@ -964,6 +994,7 @@ function Partitioned<'T>(partitionSizes : Int[], array : 'T[]) : 'T[][] { output } +/// # Summary /// Creates an array that is equal to an input array except that the first array /// element is dropped. /// @@ -981,6 +1012,7 @@ function Rest<'T>(array : 'T[]) : 'T[] { array[1...] } +/// # Summary /// Create an array that contains the same elements as an input array but in reversed /// order. /// @@ -998,6 +1030,7 @@ function Reversed<'T>(array : 'T[]) : 'T[] { array[...-1...] } +/// # Summary /// Get an array of integers in a given interval. /// /// # Input @@ -1028,6 +1061,7 @@ function SequenceI(from : Int, to : Int) : Int[] { array } +/// # Summary /// Get an array of integers in a given interval. /// /// # Input @@ -1061,6 +1095,7 @@ function SequenceL(from : BigInt, to : BigInt) : BigInt[] { array } +/// # Summary /// Given an array, returns the elements of that array sorted by a given /// comparison function. /// @@ -1110,6 +1145,7 @@ function Sorted<'T>(comparison : (('T, 'T) -> Bool), array : 'T[]) : 'T[] { ) } +/// # Summary /// Given two sorted arrays, returns a single array containing the /// elements of both in sorted order. Used internally by `Sorted`. internal function SortedMerged<'T>(comparison : (('T, 'T) -> Bool), left : 'T[], right : 'T[]) : 'T[] { @@ -1131,6 +1167,7 @@ internal function SortedMerged<'T>(comparison : (('T, 'T) -> Bool), left : 'T[], output + remainingLeft + remainingRight } +/// # Summary /// Takes an array and a list of locations and /// produces a new array formed from the elements of the original /// array that match the given locations. @@ -1168,6 +1205,7 @@ function Subarray<'T>(locations : Int[], array : 'T[]) : 'T[] { subarray } +/// # Summary /// Applies a swap of two elements in an array. /// /// # Input @@ -1194,6 +1232,7 @@ function Swapped<'T>(firstIndex : Int, secondIndex : Int, array : 'T[]) : 'T[] { w/ secondIndex <- array[firstIndex] } +/// # Summary /// Returns the transpose of a matrix represented as an array /// of arrays. /// @@ -1237,6 +1276,7 @@ function Transposed<'T>(matrix : 'T[][]) : 'T[][] { transposed } +/// # Summary /// Returns the last element of the array. /// /// # Type Parameters @@ -1255,6 +1295,7 @@ function Tail<'A>(array : 'A[]) : 'A { array[size - 1] } +/// # Summary /// Given an array of 2-tuples, returns a tuple of two arrays, each containing /// the elements of the tuples of the input array. /// @@ -1291,6 +1332,7 @@ function Unzipped<'T, 'U>(array : ('T, 'U)[]) : ('T[], 'U[]) { return (first, second); } +/// # Summary /// Given a predicate and an array, returns the indices of that /// array where the predicate is true. /// @@ -1316,6 +1358,7 @@ function Where<'T>(predicate : ('T -> Bool), array : 'T[]) : Int[] { indexes } +/// # Summary /// Returns all consecutive subarrays of length `size`. /// /// # Description @@ -1357,6 +1400,7 @@ function Windows<'T>(size : Int, array : 'T[]) : 'T[][] { windows } +/// # Summary /// Given two arrays, returns a new array of pairs such that each pair /// contains an element from each original array. /// diff --git a/library/std/src/Std/Convert.qs b/library/std/src/Std/Convert.qs index 08d2a1568e..58d8953f9f 100644 --- a/library/std/src/Std/Convert.qs +++ b/library/std/src/Std/Convert.qs @@ -21,11 +21,13 @@ function IntAsDouble(number : Int) : Double { body intrinsic; } +/// # Summary /// Converts a given integer `number` to an equivalent big integer. function IntAsBigInt(number : Int) : BigInt { body intrinsic; } +/// # Summary /// Converts a `Result` type to a `Bool` type, where `One` is mapped to /// `true` and `Zero` is mapped to `false`. /// @@ -39,6 +41,7 @@ function ResultAsBool(input : Result) : Bool { input == One } +/// # Summary /// Converts a `Bool` type to a `Result` type, where `true` is mapped to /// `One` and `false` is mapped to `Zero`. /// @@ -52,6 +55,7 @@ function BoolAsResult(input : Bool) : Result { if input { One } else { Zero } } +/// # Summary /// Produces a non-negative integer from a string of bits in little-endian format. /// `bits[0]` represents the least significant bit. /// @@ -72,6 +76,7 @@ function BoolArrayAsInt(bits : Bool[]) : Int { number } +/// # Summary /// Produces a binary representation of a non-negative integer, using the /// little-endian representation for the returned array. /// @@ -101,6 +106,7 @@ function IntAsBoolArray(number : Int, bits : Int) : Bool[] { result } +/// # Summary /// Converts an array of Boolean values into a non-negative BigInt, interpreting the /// array as a binary representation in little-endian format. /// @@ -126,6 +132,7 @@ function BoolArrayAsBigInt(boolArray : Bool[]) : BigInt { result } +/// # Summary /// Produces a binary representation of a non-negative BigInt, using the /// little-endian representation for the returned array. /// @@ -155,6 +162,7 @@ function BigIntAsBoolArray(number : BigInt, bits : Int) : Bool[] { result } +/// # Summary /// Produces a non-negative integer from a string of Results in little-endian format. /// /// # Input @@ -183,6 +191,7 @@ function ResultArrayAsInt(results : Result[]) : Int { number } +/// # Summary /// Converts a `Result[]` type to a `Bool[]` type, where `One` /// is mapped to `true` and `Zero` is mapped to `false`. /// @@ -201,6 +210,7 @@ function ResultArrayAsBoolArray(input : Result[]) : Bool[] { output } +/// # Summary /// Converts a `Bool[]` type to a `Result[]` type, where `true` /// is mapped to `One` and `false` is mapped to `Zero`. /// @@ -219,6 +229,7 @@ function BoolArrayAsResultArray(input : Bool[]) : Result[] { output } +/// # Summary /// Converts a complex number of type `Complex` to a complex /// number of type `ComplexPolar`. /// @@ -232,6 +243,7 @@ function ComplexAsComplexPolar(input : Complex) : ComplexPolar { return ComplexPolar(AbsComplex(input), ArgComplex(input)); } +/// # Summary /// Converts a complex number of type `ComplexPolar` to a complex /// number of type `Complex`. /// @@ -248,6 +260,7 @@ function ComplexPolarAsComplex(input : ComplexPolar) : Complex { ); } +/// # Summary /// Converts a given double-precision floating-point number to a string representation with desired precision, rounding if required. /// /// # Input diff --git a/library/std/src/Std/Diagnostics.qs b/library/std/src/Std/Diagnostics.qs index d71e87fe62..5f7d4894fa 100644 --- a/library/std/src/Std/Diagnostics.qs +++ b/library/std/src/Std/Diagnostics.qs @@ -29,6 +29,7 @@ function DumpMachine() : Unit { body intrinsic; } +/// # Summary /// Dumps the current target machine's status associated with the given qubits. /// /// # Input @@ -104,6 +105,7 @@ function DumpMatrix(qs : Qubit[]) : Unit { body intrinsic; } +/// # Summary /// Checks whether a qubit is in the |0⟩ state, returning true if it is. /// /// # Description @@ -125,6 +127,7 @@ operation CheckZero(qubit : Qubit) : Bool { body intrinsic; } +/// # Summary /// Checks whether all qubits in the provided array are in the |0⟩ state. Returns true if they are. /// /// # Description @@ -152,6 +155,7 @@ operation CheckAllZero(qubits : Qubit[]) : Bool { return true; } +/// # Summary /// Checks whether a given condition is true, failing with a message if it is not. /// /// # Description @@ -169,6 +173,7 @@ function Fact(actual : Bool, message : String) : Unit { } } +/// # Summary /// Given two operations, checks that they act identically for all input states. /// /// # Description @@ -225,6 +230,7 @@ operation CheckOperationsAreEqual( areEqual } +/// # Summary /// Starts counting the number of times the given operation is called. Fails if the operation is already being counted. /// /// # Description @@ -261,6 +267,7 @@ operation StartCountingOperation<'In, 'Out>(callable : 'In => 'Out) : Unit { body intrinsic; } +/// # Summary /// Stops counting the number of times the given operation is called and returns the count. Fails /// if the operation was not being counted. /// @@ -278,6 +285,7 @@ operation StopCountingOperation<'In, 'Out>(callable : 'In => 'Out) : Int { body intrinsic; } +/// # Summary /// Starts counting the number of times the given function is called. Fails if the function is already being counted. /// /// # Description @@ -305,6 +313,7 @@ operation StartCountingFunction<'In, 'Out>(callable : 'In -> 'Out) : Unit { body intrinsic; } +/// # Summary /// Stops counting the number of times the given function is called and returns the count. Fails /// if the function was not being counted. /// @@ -322,6 +331,7 @@ operation StopCountingFunction<'In, 'Out>(callable : 'In -> 'Out) : Int { body intrinsic; } +/// # Summary /// Starts counting the number of qubits allocated. Fails if qubits are already being counted. /// /// # Description @@ -344,6 +354,7 @@ operation StartCountingQubits() : Unit { body intrinsic; } +/// # Summary /// Stops counting the number of qubits allocated and returns the count. Fails if the qubits were not being counted. /// /// # Description diff --git a/library/std/src/Std/Intrinsic.qs b/library/std/src/Std/Intrinsic.qs index 03f5524ff9..1cc3e1f1d6 100644 --- a/library/std/src/Std/Intrinsic.qs +++ b/library/std/src/Std/Intrinsic.qs @@ -36,6 +36,7 @@ operation AND(control1 : Qubit, control2 : Qubit, target : Qubit) : Unit is Adj } } +/// # Summary /// Applies the AND gate that is more efficient for use with decomposition of multi-controlled operations. /// Note that target qubit must be in |0⟩ state. /// @@ -54,6 +55,7 @@ operation AND(control1 : Qubit, control2 : Qubit, target : Qubit) : Unit is Adj PhaseCCX(control1, control2, target); } +/// # Summary /// Applies the doubly controlled–NOT (CCNOT) gate to three qubits. /// /// # Input @@ -79,6 +81,7 @@ operation CCNOT(control1 : Qubit, control2 : Qubit, target : Qubit) : Unit is Ad adjoint self; } +/// # Summary /// Applies the controlled-NOT (CNOT) gate to a pair of qubits. /// /// # Input @@ -116,6 +119,7 @@ operation CNOT(control : Qubit, target : Qubit) : Unit is Adj + Ctl { adjoint self; } +/// # Summary /// Applies the exponential of a multi-qubit Pauli operator. /// /// # Input @@ -179,6 +183,7 @@ operation Exp(paulis : Pauli[], theta : Double, qubits : Qubit[]) : Unit is Adj } } +/// # Summary /// Applies the Hadamard transformation to a single qubit. /// /// # Input @@ -223,6 +228,7 @@ operation H(qubit : Qubit) : Unit is Adj + Ctl { adjoint self; } +/// # Summary /// Performs the identity operation (no-op) on a single qubit. /// /// # Remarks @@ -233,6 +239,7 @@ operation I(target : Qubit) : Unit is Adj + Ctl { adjoint self; } +/// # Summary /// Performs a measurement of a single qubit in the /// Pauli _Z_ basis. /// @@ -263,6 +270,7 @@ operation M(qubit : Qubit) : Result { __quantum__qis__m__body(qubit) } +/// # Summary /// Performs a measurement of a single qubit in the /// Pauli _Z_ basis. /// @@ -293,6 +301,7 @@ operation M(qubit : Qubit) : Result { Measure([PauliZ], [qubit]) } +/// # Summary /// Performs a joint measurement of one or more qubits in the /// specified Pauli bases. /// @@ -341,6 +350,7 @@ operation Measure(bases : Pauli[], qubits : Qubit[]) : Result { } } +/// # Summary /// Performs a joint measurement of one or more qubits in the /// specified Pauli bases. /// @@ -384,6 +394,7 @@ operation Measure(bases : Pauli[], qubits : Qubit[]) : Result { __quantum__qis__mresetz__body(aux) } +/// # Summary /// Applies a rotation about the given Pauli axis. /// /// # Input @@ -419,6 +430,7 @@ operation R(pauli : Pauli, theta : Double, qubit : Qubit) : Unit is Adj + Ctl { } } +/// # Summary /// Applies a rotation about the |1⟩ state by a given angle. /// /// # Input @@ -445,6 +457,7 @@ operation R1(theta : Double, qubit : Qubit) : Unit is Adj + Ctl { R(PauliI, -theta, qubit); } +/// # Summary /// Applies a rotation about the |1⟩ state by an angle specified /// as a dyadic fraction. /// @@ -480,6 +493,7 @@ operation R1Frac(numerator : Int, power : Int, qubit : Qubit) : Unit is Adj + Ct RFrac(PauliI, numerator, power + 1, qubit); } +/// # Summary /// Given a single qubit, measures it and ensures it is in the |0⟩ state /// such that it can be safely released. /// @@ -490,6 +504,7 @@ operation Reset(qubit : Qubit) : Unit { __quantum__qis__reset__body(qubit); } +/// # Summary /// Given an array of qubits, measure them and ensure they are in the |0⟩ state /// such that they can be safely released. /// @@ -502,6 +517,7 @@ operation ResetAll(qubits : Qubit[]) : Unit { } } +/// # Summary /// Applies a rotation about the given Pauli axis by an angle specified /// as a dyadic fraction. /// @@ -542,6 +558,7 @@ operation RFrac(pauli : Pauli, numerator : Int, power : Int, qubit : Qubit) : Un R(pauli, angle, qubit); } +/// # Summary /// Applies a rotation about the _x_-axis by a given angle. /// /// # Input @@ -586,6 +603,7 @@ operation Rx(theta : Double, qubit : Qubit) : Unit is Adj + Ctl { } } +/// # Summary /// Applies the two qubit Ising _XX_ rotation gate. /// /// # Input @@ -632,6 +650,7 @@ operation Rxx(theta : Double, qubit0 : Qubit, qubit1 : Qubit) : Unit is Adj + Ct } } +/// # Summary /// Applies a rotation about the _y_-axis by a given angle. /// /// # Input @@ -676,6 +695,7 @@ operation Ry(theta : Double, qubit : Qubit) : Unit is Adj + Ctl { } } +/// # Summary /// Applies the two qubit Ising _YY_ rotation gate. /// /// # Input @@ -722,6 +742,7 @@ operation Ryy(theta : Double, qubit0 : Qubit, qubit1 : Qubit) : Unit is Adj + Ct } } +/// # Summary /// Applies a rotation about the _z_-axis by a given angle. /// /// # Input @@ -770,6 +791,7 @@ operation Rz(theta : Double, qubit : Qubit) : Unit is Adj + Ctl { } } +/// # Summary /// Applies the two qubit Ising _ZZ_ rotation gate. /// /// # Input @@ -816,6 +838,7 @@ operation Rzz(theta : Double, qubit0 : Qubit, qubit1 : Qubit) : Unit is Adj + Ct } } +/// # Summary /// Applies the π/4 phase gate to a single qubit. /// /// # Input @@ -881,6 +904,7 @@ operation S(qubit : Qubit) : Unit is Adj + Ctl { } } +/// # Summary /// Applies the SWAP gate to a pair of qubits. /// /// # Input @@ -928,6 +952,7 @@ operation SWAP(qubit1 : Qubit, qubit2 : Qubit) : Unit is Adj + Ctl { } } +/// # Summary /// Applies the π/8 gate to a single qubit. /// /// # Input @@ -983,6 +1008,7 @@ operation T(qubit : Qubit) : Unit is Adj + Ctl { } } +/// # Summary /// Applies the Pauli _X_ gate. /// /// # Input @@ -1026,6 +1052,7 @@ operation X(qubit : Qubit) : Unit is Adj + Ctl { adjoint self; } +/// # Summary /// Applies the Pauli _Y_ gate. /// /// # Input @@ -1069,6 +1096,7 @@ operation Y(qubit : Qubit) : Unit is Adj + Ctl { adjoint self; } +/// # Summary /// Applies the Pauli _Z_ gate. /// /// # Input @@ -1112,6 +1140,7 @@ operation Z(qubit : Qubit) : Unit is Adj + Ctl { adjoint self; } +/// # Summary /// Logs a message. /// /// # Input diff --git a/library/std/src/Std/Math.qs b/library/std/src/Std/Math.qs index 9022c04e6b..c149ae0aa9 100644 --- a/library/std/src/Std/Math.qs +++ b/library/std/src/Std/Math.qs @@ -27,6 +27,7 @@ function PI() : Double { 3.14159265358979323846 } +/// # Summary /// Returns a double-precision approximation of the /// mathematical constant 𝒆 ≈ 2.7182818284590452354 /// @@ -43,6 +44,7 @@ function E() : Double { 2.7182818284590452354 } +/// # Summary /// Returns a double-precision approximation of the constant /// ㏑2 ≈ 0.6931471805599453 /// @@ -73,6 +75,7 @@ function IsNaN(d : Double) : Bool { return d != d; } +/// # Summary /// Returns whether a given floating-point value is either positive or /// negative infinity. /// @@ -121,6 +124,7 @@ function SignI(a : Int) : Int { } } +/// # Summary /// Returns -1, 0 or +1 that indicates the sign of a number. function SignD(a : Double) : Int { if (a < 0.0) { @@ -132,6 +136,7 @@ function SignD(a : Double) : Int { } } +/// # Summary /// Returns -1, 0 or +1 that indicates the sign of a number. function SignL(a : BigInt) : Int { if (a < 0L) { @@ -143,11 +148,13 @@ function SignL(a : BigInt) : Int { } } +/// # Summary /// Returns the absolute value of an integer. function AbsI(a : Int) : Int { a < 0 ? -a | a } +/// # Summary /// Returns the absolute value of a double-precision floating-point number. function AbsD(a : Double) : Double { a < 0.0 ? -a | a @@ -157,36 +164,43 @@ function AbsL(a : BigInt) : BigInt { a < 0L ? -a | a } +/// # Summary /// Returns the larger of two specified numbers. function MaxI(a : Int, b : Int) : Int { a > b ? a | b } +/// # Summary /// Returns the larger of two specified numbers. function MaxD(a : Double, b : Double) : Double { a > b ? a | b } +/// # Summary /// Returns the larger of two specified numbers. function MaxL(a : BigInt, b : BigInt) : BigInt { a > b ? a | b } +/// # Summary /// Returns the smaller of two specified numbers. function MinI(a : Int, b : Int) : Int { a < b ? a | b } +/// # Summary /// Returns the smaller of two specified numbers. function MinD(a : Double, b : Double) : Double { a < b ? a | b } +/// # Summary /// Returns the smaller of two specified numbers. function MinL(a : BigInt, b : BigInt) : BigInt { a < b ? a | b } +/// # Summary /// Given an array of integers, returns the largest element. /// /// # Input @@ -207,6 +221,7 @@ function Max(values : Int[]) : Int { max } +/// # Summary /// Given an array of integers, returns the smallest element. /// /// # Input @@ -237,62 +252,74 @@ function ArcCos(x : Double) : Double { body intrinsic; } +/// # Summary /// Returns the angle whose sine is the specified number. function ArcSin(y : Double) : Double { body intrinsic; } +/// # Summary /// Returns the angle whose tangent is the specified number. function ArcTan(d : Double) : Double { body intrinsic; } +/// # Summary /// Returns the angle whose tangent is the quotient of two specified numbers. function ArcTan2(y : Double, x : Double) : Double { body intrinsic; } +/// # Summary /// Returns the cosine of the specified angle. function Cos(theta : Double) : Double { body intrinsic; } +/// # Summary /// Returns the hyperbolic cosine of the specified angle. function Cosh(d : Double) : Double { body intrinsic; } +/// # Summary /// Returns the sine of the specified angle. function Sin(theta : Double) : Double { body intrinsic; } +/// # Summary /// Returns the hyperbolic sine of the specified angle. function Sinh(d : Double) : Double { body intrinsic; } +/// # Summary /// Returns the tangent of the specified angle. function Tan(d : Double) : Double { body intrinsic; } +/// # Summary /// Returns the hyperbolic tangent of the specified angle. function Tanh(d : Double) : Double { body intrinsic; } +/// # Summary /// Computes the inverse hyperbolic cosine of a number. function ArcCosh(x : Double) : Double { Log(x + Sqrt(x * x - 1.0)) } +/// # Summary /// Computes the inverse hyperbolic sine of a number. function ArcSinh(x : Double) : Double { Log(x + Sqrt(x * x + 1.0)) } +/// # Summary /// Computes the inverse hyperbolic tangent of a number. function ArcTanh(x : Double) : Double { Log((1.0 + x) / (1.0 - x)) * 0.5 @@ -308,16 +335,19 @@ function Sqrt(d : Double) : Double { body intrinsic; } +/// # Summary /// Returns the natural (base _e_) logarithm of a specified number. function Log(input : Double) : Double { body intrinsic; } +/// # Summary /// Returns the base-10 logarithm of a specified number. function Log10(input : Double) : Double { Log(input) / Log(10.0) } +/// # Summary /// Computes the base-2 logarithm of a number. function Lg(input : Double) : Double { Log(input) / Log(2.0) @@ -339,6 +369,7 @@ internal function ExtendedTruncation(value : Double) : (Int, Double, Bool) { (truncated, IntAsDouble(truncated) - value, value >= 0.0) } +/// # Summary /// Returns the smallest integer greater than or equal to the specified number. /// For example: Ceiling(3.1) = 4; Ceiling(-3.7) = -3 function Ceiling(value : Double) : Int { @@ -350,6 +381,7 @@ function Ceiling(value : Double) : Int { } } +/// # Summary /// Returns the largest integer less than or equal to the specified number. /// For example: Floor(3.7) = 3; Floor(-3.1) = -4 function Floor(value : Double) : Int { @@ -361,6 +393,7 @@ function Floor(value : Double) : Int { } } +/// # Summary /// Returns the nearest integer to the specified number. /// For example: Round(3.7) = 4; Round(-3.7) = -4 function Round(value : Double) : Int { @@ -383,11 +416,13 @@ function DivRemI(dividend : Int, divisor : Int) : (Int, Int) { (dividend / divisor, dividend % divisor) } +/// # Summary /// Divides one BigInteger value by another, returns the result and the remainder as a tuple. function DivRemL(dividend : BigInt, divisor : BigInt) : (BigInt, BigInt) { (dividend / divisor, dividend % divisor) } +/// # Summary /// Computes the canonical residue of `value` modulo `modulus`. /// The result is always in the range 0..modulus-1 even for negative numbers. function ModulusI(value : Int, modulus : Int) : Int { @@ -396,6 +431,7 @@ function ModulusI(value : Int, modulus : Int) : Int { (r < 0) ? (r + modulus) | r } +/// # Summary /// Computes the canonical residue of `value` modulo `modulus`. /// The result is always in the range 0..modulus-1 even for negative numbers. function ModulusL(value : BigInt, modulus : BigInt) : BigInt { @@ -404,6 +440,7 @@ function ModulusL(value : BigInt, modulus : BigInt) : BigInt { (r < 0L) ? (r + modulus) | r } +/// # Summary /// Returns an integer raised to a given power, with respect to a given /// modulus. I.e. (expBase^power) % modulus. function ExpModI(expBase : Int, power : Int, modulus : Int) : Int { @@ -434,6 +471,7 @@ function ExpModI(expBase : Int, power : Int, modulus : Int) : Int { res } +/// # Summary /// Returns an integer raised to a given power, with respect to a given /// modulus. I.e. (expBase^power) % modulus. function ExpModL(expBase : BigInt, power : BigInt, modulus : BigInt) : BigInt { @@ -464,6 +502,7 @@ function ExpModL(expBase : BigInt, power : BigInt, modulus : BigInt) : BigInt { res } +/// # Summary /// Returns the multiplicative inverse of a modular integer. /// /// # Description @@ -476,6 +515,7 @@ function InverseModI(a : Int, modulus : Int) : Int { ModulusI(u, modulus) } +/// # Summary /// Returns the multiplicative inverse of a modular integer. /// /// # Description @@ -506,6 +546,7 @@ function GreatestCommonDivisorI(a : Int, b : Int) : Int { aa } +/// # Summary /// Computes the greatest common divisor of two integers. /// Note: GCD is always positive except that GCD(0,0)=0. function GreatestCommonDivisorL(a : BigInt, b : BigInt) : BigInt { @@ -519,6 +560,7 @@ function GreatestCommonDivisorL(a : BigInt, b : BigInt) : BigInt { aa } +/// # Summary /// Returns a tuple (u,v) such that u*a+v*b=GCD(a,b) /// Note: GCD is always positive except that GCD(0,0)=0. function ExtendedGreatestCommonDivisorI(a : Int, b : Int) : (Int, Int) { @@ -538,6 +580,7 @@ function ExtendedGreatestCommonDivisorI(a : Int, b : Int) : (Int, Int) { (s1 * signA, t1 * signB) } +/// # Summary /// Returns a tuple (u,v) such that u*a+v*b=GCD(a,b) /// Note: GCD is always positive except that GCD(0,0)=0. function ExtendedGreatestCommonDivisorL(a : BigInt, b : BigInt) : (BigInt, BigInt) { @@ -557,6 +600,7 @@ function ExtendedGreatestCommonDivisorL(a : BigInt, b : BigInt) : (BigInt, BigIn (s1 * signA, t1 * signB) } +/// # Summary /// Returns if two integers are co-prime. /// /// # Description @@ -575,6 +619,7 @@ function IsCoprimeI(a : Int, b : Int) : Bool { GreatestCommonDivisorI(a, b) == 1 } +/// # Summary /// Returns if two integers are co-prime. /// /// # Description @@ -593,6 +638,7 @@ function IsCoprimeL(a : BigInt, b : BigInt) : Bool { GreatestCommonDivisorL(a, b) == 1L } +/// # Summary /// Finds the continued fraction convergent closest to `fraction` /// with the denominator less or equal to `denominatorBound` /// Using process similar to this: https://nrich.maths.org/1397 @@ -623,6 +669,7 @@ function ContinuedFractionConvergentI( } } +/// # Summary /// Finds the continued fraction convergent closest to `fraction` /// with the denominator less or equal to `denominatorBound` /// Using process similar to this: https://nrich.maths.org/1397 @@ -653,6 +700,7 @@ function ContinuedFractionConvergentL( } } +/// # Summary /// Computes the modulus between two real numbers. /// /// # Input @@ -696,6 +744,7 @@ function BitSizeI(a : Int) : Int { size } +/// # Summary /// For a non-negative integer `a`, returns the number of bits required to represent `a`. /// NOTE: This function returns the smallest n such that a < 2^n. function BitSizeL(a : BigInt) : Int { @@ -710,6 +759,7 @@ function BitSizeL(a : BigInt) : Int { size } +/// # Summary /// For a non-zero integer `a`, returns the number of trailing zero bits /// in the binary representation of `a`. function TrailingZeroCountI(a : Int) : Int { @@ -725,6 +775,7 @@ function TrailingZeroCountI(a : Int) : Int { count } +/// # Summary /// For a non-zero integer `a`, returns the number of trailing zero bits /// in the binary representation of `a`. function TrailingZeroCountL(a : BigInt) : Int { @@ -740,6 +791,7 @@ function TrailingZeroCountL(a : BigInt) : Int { count } +/// # Summary /// Returns the number of 1 bits in the binary representation of integer `n`. function HammingWeightI(n : Int) : Int { let i1 = n - ((n >>> 1) &&& 0x5555555555555555); @@ -800,6 +852,7 @@ function FactorialI(n : Int) : Int { ][n] } +/// # Summary /// Returns the factorial of a given number. /// /// # Input @@ -822,6 +875,7 @@ function FactorialL(n : Int) : BigInt { result } +/// # Summary /// Returns an approximate factorial of a given number. /// /// # Description @@ -859,6 +913,7 @@ function ApproximateFactorial(n : Int) : Double { a * b * c } +/// # Summary /// Returns the natural logarithm of the gamma function (aka the log-gamma /// function). /// @@ -910,6 +965,7 @@ function LogGammaD(x : Double) : Double { Log(2.506628274631000 * acc / x) + ((x + 0.5) * Log(tmp) - tmp) } +/// # Summary /// Returns the approximate natural logarithm of the factorial of a given /// integer. /// @@ -928,6 +984,7 @@ function LogFactorialD(n : Int) : Double { LogGammaD(IntAsDouble(n) + 1.0) } +/// # Summary /// Returns the approximate binomial coefficient of two integers. /// /// # Description @@ -977,6 +1034,7 @@ function SquaredNorm(array : Double[]) : Double { sum } +/// # Summary /// Returns the `L(p)` norm of a vector of `Double`s. /// /// That is, given an array x of type `Double[]`, this returns the p-norm @@ -1001,6 +1059,7 @@ function PNorm(p : Double, array : Double[]) : Double { sum^(1.0 / p) } +/// # Summary /// Normalizes a vector of `Double`s in the `L(p)` norm. /// /// That is, given an array x of type `Double[]`, this returns an array where @@ -1046,6 +1105,7 @@ function PNormalized(p : Double, array : Double[]) : Double[] { /// ``` struct Complex { Real : Double, Imag : Double } +/// # Summary /// Represents a complex number in polar form. /// The polar representation of a complex number is c = r⋅𝑒^(t𝑖). /// @@ -1056,6 +1116,7 @@ struct Complex { Real : Double, Imag : Double } /// The phase t ∈ ℝ of c. struct ComplexPolar { Magnitude : Double, Argument : Double } +/// # Summary /// Returns the squared absolute value of a complex number of type /// `Complex`. /// @@ -1069,6 +1130,7 @@ function AbsSquaredComplex(input : Complex) : Double { input.Real * input.Real + input.Imag * input.Imag } +/// # Summary /// Returns the absolute value of a complex number of type /// `Complex`. /// @@ -1082,6 +1144,7 @@ function AbsComplex(input : Complex) : Double { Sqrt(AbsSquaredComplex(input)) } +/// # Summary /// Returns the phase of a complex number of type /// `Complex`. /// @@ -1095,6 +1158,7 @@ function ArgComplex(input : Complex) : Double { ArcTan2(input.Imag, input.Real) } +/// # Summary /// Returns the squared absolute value of a complex number of type /// `ComplexPolar`. /// @@ -1108,6 +1172,7 @@ function AbsSquaredComplexPolar(input : ComplexPolar) : Double { input.Magnitude * input.Magnitude } +/// # Summary /// Returns the absolute value of a complex number of type /// `ComplexPolar`. /// @@ -1119,6 +1184,7 @@ function AbsSquaredComplexPolar(input : ComplexPolar) : Double { /// Absolute value |c| = r. function AbsComplexPolar(input : ComplexPolar) : Double { input.Magnitude } +/// # Summary /// Returns the phase of a complex number of type `ComplexPolar`. /// /// # Input @@ -1129,6 +1195,7 @@ function AbsComplexPolar(input : ComplexPolar) : Double { input.Magnitude } /// Phase Arg(c) = t. function ArgComplexPolar(input : ComplexPolar) : Double { input.Argument } +/// # Summary /// Returns the unary negation of an input of type `Complex`. /// /// # Input @@ -1141,6 +1208,7 @@ function NegationC(input : Complex) : Complex { Complex(-input.Real, -input.Imag) } +/// # Summary /// Returns the unary negation of an input of type `ComplexPolar` /// /// # Input @@ -1153,6 +1221,7 @@ function NegationCP(input : ComplexPolar) : ComplexPolar { ComplexPolar(input.Magnitude, input.Argument + PI()) } +/// # Summary /// Returns the sum of two inputs of type `Complex`. /// /// # Input @@ -1167,6 +1236,7 @@ function PlusC(a : Complex, b : Complex) : Complex { Complex(a.Real + b.Real, a.Imag + b.Imag) } +/// # Summary /// Returns the sum of two inputs of type `ComplexPolar`. /// /// # Input @@ -1186,6 +1256,7 @@ function PlusCP(a : ComplexPolar, b : ComplexPolar) : ComplexPolar { ) } +/// # Summary /// Returns the difference between two inputs of type `Complex`. /// /// # Input @@ -1200,6 +1271,7 @@ function MinusC(a : Complex, b : Complex) : Complex { Complex(a.Real - b.Real, a.Imag - b.Imag) } +/// # Summary /// Returns the difference between two inputs of type `ComplexPolar`. /// /// # Input @@ -1214,6 +1286,7 @@ function MinusCP(a : ComplexPolar, b : ComplexPolar) : ComplexPolar { PlusCP(a, NegationCP(b)) } +/// # Summary /// Returns the product of two inputs of type `Complex`. /// /// # Input @@ -1231,6 +1304,7 @@ function TimesC(a : Complex, b : Complex) : Complex { ) } +/// # Summary /// Returns the product of two inputs of type `ComplexPolar`. /// /// # Input @@ -1248,6 +1322,7 @@ function TimesCP(a : ComplexPolar, b : ComplexPolar) : ComplexPolar { ) } +/// # Summary /// Internal. Since it is easiest to define the power of two complex numbers /// in Cartesian form as returning in polar form, we define that here, then /// convert as needed. @@ -1274,6 +1349,7 @@ internal function PowCAsCP(base : Complex, power : Complex) : ComplexPolar { ComplexPolar(magnitude, angle) } +/// # Summary /// Returns a number raised to a given power of type `Complex`. /// Note that this is a multi-valued function, but only one value is returned. /// @@ -1289,6 +1365,7 @@ function PowC(a : Complex, power : Complex) : Complex { ComplexPolarAsComplex(PowCAsCP(a, power)) } +/// # Summary /// Returns a number raised to a given power of type `ComplexPolar`. /// Note that this is a multi-valued function, but only one value is returned. /// @@ -1304,6 +1381,7 @@ function PowCP(a : ComplexPolar, power : ComplexPolar) : ComplexPolar { PowCAsCP(ComplexPolarAsComplex(a), ComplexPolarAsComplex(power)) } +/// # Summary /// Returns the quotient of two inputs of type `Complex`. /// /// # Input @@ -1322,6 +1400,7 @@ function DividedByC(a : Complex, b : Complex) : Complex { ) } +/// # Summary /// Returns the quotient of two inputs of type `ComplexPolar`. /// /// # Input @@ -1355,6 +1434,7 @@ function SmallestFixedPoint(integerBits : Int, fractionalBits : Int) : Double { -(2.0^IntAsDouble(integerBits - 1)) } +/// # Summary /// Returns the largest representable number for specific fixed point dimensions. /// /// # Input diff --git a/library/std/src/Std/Measurement.qs b/library/std/src/Std/Measurement.qs index 2b538d8554..8639b947c4 100644 --- a/library/std/src/Std/Measurement.qs +++ b/library/std/src/Std/Measurement.qs @@ -29,6 +29,7 @@ operation MeasureAllZ(register : Qubit[]) : Result { Measure(Repeated(PauliZ, Length(register)), register) } +/// # Summary /// Measures each qubit in a given array in the standard basis. /// /// # Description @@ -63,6 +64,7 @@ operation MeasureEachZ(register : Qubit[]) : Result[] { results } +/// # Summary /// Measures each qubit in a given array in the Z basis /// and resets them to a fixed initial state. /// @@ -83,6 +85,7 @@ operation MResetEachZ(register : Qubit[]) : Result[] { results } +/// # Summary /// Measures a single qubit in the X basis, /// and resets it to a fixed initial state /// following the measurement. @@ -105,6 +108,7 @@ operation MResetX(target : Qubit) : Result { MResetZ(target) } +/// # Summary /// Measures a single qubit in the Y basis, /// and resets it to a fixed initial state /// following the measurement. @@ -129,6 +133,7 @@ operation MResetY(target : Qubit) : Result { MResetZ(target) } +/// # Summary /// Measures a single qubit in the Z basis, /// and resets it to a fixed initial state /// following the measurement. @@ -148,6 +153,7 @@ operation MResetZ(target : Qubit) : Result { __quantum__qis__mresetz__body(target) } +/// # Summary /// Measures the content of a quantum register and converts /// it to an integer. The measurement is performed with respect /// to the standard computational basis, i.e., the eigenbasis of `PauliZ`. diff --git a/library/std/src/Std/Random.qs b/library/std/src/Std/Random.qs index e1007dbe5d..40a80eb512 100644 --- a/library/std/src/Std/Random.qs +++ b/library/std/src/Std/Random.qs @@ -27,6 +27,7 @@ operation DrawRandomInt(min : Int, max : Int) : Int { body intrinsic; } +/// # Summary /// Draws a random real number from a uniform distribution /// in a given inclusive interval. Fails if `max < min`. /// @@ -50,6 +51,7 @@ operation DrawRandomDouble(min : Double, max : Double) : Double { body intrinsic; } +/// # Summary /// Given a success probability, returns a single Bernoulli trial /// that is true with the given probability. /// diff --git a/library/std/src/Std/ResourceEstimation.qs b/library/std/src/Std/ResourceEstimation.qs index f0da84c88e..17c7371b95 100644 --- a/library/std/src/Std/ResourceEstimation.qs +++ b/library/std/src/Std/ResourceEstimation.qs @@ -15,6 +15,7 @@ function SingleVariant() : Int { return 0; } +/// # Summary /// Informs the resource estimator of the start of the code fragment /// for which estimates caching can be done. This function /// is only available when using resource estimator execution target. @@ -36,6 +37,7 @@ function BeginEstimateCaching(name : String, variant : Int) : Bool { body intrinsic; } +/// # Summary /// Instructs the resource estimator to stop estimates caching /// because the code fragment in consideration is over. This function /// is only available when using resource estimator execution target. @@ -56,36 +58,42 @@ function AuxQubitCount(amount : Int) : (Int, Int) { return (0, amount); } +/// # Summary /// Returns a tuple that can be passed to the `AccountForEstimates` operation /// to specify that the number of the T gates is equal to the `amount`. function TCount(amount : Int) : (Int, Int) { return (1, amount); } +/// # Summary /// Returns a tuple that can be passed to the `AccountForEstimates` operation /// to specify that the number of rotations is equal to the `amount`. function RotationCount(amount : Int) : (Int, Int) { return (2, amount); } +/// # Summary /// Returns a tuple that can be passed to the `AccountForEstimates` operation /// to specify that the rotation depth is equal to the `amount`. function RotationDepth(amount : Int) : (Int, Int) { return (3, amount); } +/// # Summary /// Returns a tuple that can be passed to the `AccountForEstimates` operation /// to specify that the number of the CCZ gates is equal to the `amount`. function CczCount(amount : Int) : (Int, Int) { return (4, amount); } +/// # Summary /// Returns a tuple that can be passed to the `AccountForEstimates` operation /// to specify that the number Measurements is equal to the `amount`. function MeasurementCount(amount : Int) : (Int, Int) { return (5, amount); } +/// # Summary /// Pass the value returned by the function to the `AccountForEstimates` operation /// to indicate Parallel Synthesis Sequential Pauli Computation (PSSPC) layout. /// See https://arxiv.org/pdf/2211.07629.pdf for details. @@ -93,6 +101,7 @@ function PSSPCLayout() : Int { return 1; } +/// # Summary /// Account for the resource estimates of an unimplemented operation, /// which were obtained separately. This operation is only available /// when using resource estimator execution target. @@ -117,6 +126,7 @@ internal operation AccountForEstimatesInternal(estimates : (Int, Int)[], layout body intrinsic; } +/// # Summary /// Instructs the resource estimator to assume that the resources from the /// call of this operation until a call to `EndRepeatEstimates` are /// accounted for `count` times, without the need to execute the code that many @@ -138,6 +148,7 @@ internal operation BeginRepeatEstimatesInternal(count : Int) : Unit { body intrinsic; } +/// # Summary /// Companion operation to `BeginRepeatEstimates`. operation EndRepeatEstimates() : Unit { body ... { @@ -150,6 +161,7 @@ internal operation EndRepeatEstimatesInternal() : Unit { body intrinsic; } +/// # Summary /// Instructs the resource estimator to assume that the resources from the /// call of this operation until a call to `Adjoint RepeatEstimates` are /// accounted for `count` times, without the need to execute the code that many diff --git a/vscode/test/suites/debugger/debugger.test.ts b/vscode/test/suites/debugger/debugger.test.ts index f88bb0b87a..90447ef074 100644 --- a/vscode/test/suites/debugger/debugger.test.ts +++ b/vscode/test/suites/debugger/debugger.test.ts @@ -375,10 +375,10 @@ suite("Q# Debugger Tests", function suite() { sourceReference: 0, adapterData: "qsharp-adapter-data", }, - line: 201, + line: 206, column: 9, name: "H ", - endLine: 201, + endLine: 206, endColumn: 40, }, {