qsharp-lang 1.1.2-dev → 1.1.4-dev

package/docs/Microsoft.Quantum.Arrays/Partitioned.md

@@ -0,0 +1,44 @@
+---
+uid: Microsoft.Quantum.Arrays.Partitioned
+title: Partitioned function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Partitioned
+qsharp.summary: Splits an array into multiple parts.
+---
+
+# Partitioned function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function Partitioned<'T>(partitionSizes : Int[], array : 'T[]) : 'T[][]
+```
+
+## Summary
+Splits an array into multiple parts.
+
+## Input
+### partitionSizes
+Number of elements in each split part of array.
+### array
+Input array to be split.
+
+## Output
+Multiple arrays where the first array is the first `partitionSizes[0]` of `array`
+and the second array are the next `partitionSizes[1]` of `array` etc. The last array
+will contain all remaining elements. If the array is split exactly, the
+last array will be the empty array, indicating there are no remaining elements.
+In other words, `Tail(Partitioned(...))` will always return the remaining
+elements, while `Most(Partitioned(...))` will always return the complete
+partitions of the array.
+
+## Example
+```qsharp
+// The following returns [[2, 3], [5], [7]];
+let split = Partitioned([2, 1], [2, 3, 5, 7]);
+// The following returns [[2, 3], [5, 7], []];
+let split = Partitioned([2, 2], [2, 3, 5, 7]);
+```

package/docs/Microsoft.Quantum.Arrays/Rest.md

@@ -0,0 +1,34 @@
+---
+uid: Microsoft.Quantum.Arrays.Rest
+title: Rest function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Rest
+qsharp.summary: Creates an array that is equal to an input array except that the first array
+element is dropped.
+---
+
+# Rest function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function Rest<'T>(array : 'T[]) : 'T[]
+```
+
+## Summary
+Creates an array that is equal to an input array except that the first array
+element is dropped.
+
+## Type Parameters
+### 'T
+The type of the array elements.
+
+## Input
+### array
+An array whose second to last elements are to form the output array.
+
+## Output
+An array containing the elements `array[1..Length(array) - 1]`.

package/docs/Microsoft.Quantum.Arrays/Reversed.md

@@ -0,0 +1,34 @@
+---
+uid: Microsoft.Quantum.Arrays.Reversed
+title: Reversed function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Reversed
+qsharp.summary: Create an array that contains the same elements as an input array but in reversed
+order.
+---
+
+# Reversed function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function Reversed<'T>(array : 'T[]) : 'T[]
+```
+
+## Summary
+Create an array that contains the same elements as an input array but in reversed
+order.
+
+## Type Parameters
+### 'T
+The type of the array elements.
+
+## Input
+### array
+An array whose elements are to be copied in reversed order.
+
+## Output
+An array containing the elements `array[Length(array) - 1]` .. `array[0]`.

package/docs/Microsoft.Quantum.Arrays/SequenceI.md

@@ -0,0 +1,41 @@
+---
+uid: Microsoft.Quantum.Arrays.SequenceI
+title: SequenceI function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: SequenceI
+qsharp.summary: Get an array of integers in a given interval.
+---
+
+# SequenceI function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function SequenceI(from : Int, to : Int) : Int[]
+```
+
+## Summary
+Get an array of integers in a given interval.
+
+## Input
+### from
+An inclusive start index of the interval.
+### to
+An inclusive end index of the interval that is not smaller than `from`.
+
+## Output
+An array containing the sequence of numbers `from`, `from + 1`, ...,
+`to`.
+
+## Example
+```qsharp
+let arr1 = SequenceI(0, 3); // [0, 1, 2, 3]
+let arr2 = SequenceI(23, 29); // [23, 24, 25, 26, 27, 28, 29]
+let arr3 = SequenceI(-5, -2); // [-5, -4, -3, -2]
+
+let numbers = SequenceI(0, _); // function to create sequence from 0 to `to`
+let naturals = SequenceI(1, _); // function to create sequence from 1 to `to`
+```

package/docs/Microsoft.Quantum.Arrays/SequenceL.md

@@ -0,0 +1,41 @@
+---
+uid: Microsoft.Quantum.Arrays.SequenceL
+title: SequenceL function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: SequenceL
+qsharp.summary: Get an array of integers in a given interval.
+---
+
+# SequenceL function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function SequenceL(from : BigInt, to : BigInt) : BigInt[]
+```
+
+## Summary
+Get an array of integers in a given interval.
+
+## Input
+### from
+An inclusive start index of the interval.
+### to
+An inclusive end index of the interval that is not smaller than `from`.
+
+## Output
+An array containing the sequence of numbers `from`, `from + 1`, ...,
+`to`.
+
+## Remarks
+The difference between `from` and `to` must fit into an `Int` value.
+
+## Example
+```qsharp
+let arr1 = SequenceL(0L, 3L); // [0L, 1L, 2L, 3L]
+let arr2 = SequenceL(23L, 29L); // [23L, 24L, 25L, 26L, 27L, 28L, 29L]
+let arr3 = SequenceL(-5L, -2L); // [-5L, -4L, -3L, -2L]
+```

package/docs/Microsoft.Quantum.Arrays/Sorted.md

@@ -0,0 +1,52 @@
+---
+uid: Microsoft.Quantum.Arrays.Sorted
+title: Sorted function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Sorted
+qsharp.summary: Given an array, returns the elements of that array sorted by a given
+comparison function.
+---
+
+# Sorted function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function Sorted<'T>(comparison : (('T, 'T) -> Bool), array : 'T[]) : 'T[]
+```
+
+## Summary
+Given an array, returns the elements of that array sorted by a given
+comparison function.
+
+## Type Parameters
+### 'T
+The type of each element of `array`.
+
+## Input
+### comparison
+A function that compares two elements such that `a` is considered to
+be less than or equal to `b` if `comparison(a, b)` is `true`.
+### array
+The array to be sorted.
+
+## Output
+An array containing the same elements as `array`, such that for all
+elements `a` occurring earlier than elements `b`, `comparison(a, b)`
+is `true`.
+
+## Example
+The following snippet sorts an array of integers to occur in ascending
+order:
+```qsharp
+let sortedArray = Sorted(LessThanOrEqualI, [3, 17, 11, -201, -11]);
+```
+
+## Remarks
+The function `comparison` is assumed to be transitive, such that
+if `comparison(a, b)` and `comparison(b, c)`, then `comparison(a, c)`
+is assumed. If this property does not hold, then the output of this
+function may be incorrect.

package/docs/Microsoft.Quantum.Arrays/Subarray.md

@@ -0,0 +1,51 @@
+---
+uid: Microsoft.Quantum.Arrays.Subarray
+title: Subarray function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Subarray
+qsharp.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.
+---
+
+# Subarray function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function Subarray<'T>(locations : Int[], array : 'T[]) : 'T[]
+```
+
+## 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.
+
+## Remarks
+If `locations` contains repeated elements, the corresponding elements
+of `array` will likewise be repeated.
+
+## Type Parameters
+### 'T
+The type of `array` elements.
+
+## Input
+### locations
+A list of locations in the input array that is used to define the subarray.
+### array
+An array from which a subarray will be generated.
+
+## Output
+An array `out` of elements whose locations correspond to the subarray,
+such that `out[index] == array[locations[index]]`.
+
+## Example
+
+```qsharp
+let array = [1, 2, 3, 4];
+let permutation = Subarray([3, 0, 2, 1], array); // [4, 1, 3, 2]
+let duplicates = Subarray([1, 2, 2], array);     // [2, 3, 3]
+```

package/docs/Microsoft.Quantum.Arrays/Swapped.md

@@ -0,0 +1,40 @@
+---
+uid: Microsoft.Quantum.Arrays.Swapped
+title: Swapped function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Swapped
+qsharp.summary: Applies a swap of two elements in an array.
+---
+
+# Swapped function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function Swapped<'T>(firstIndex : Int, secondIndex : Int, array : 'T[]) : 'T[]
+```
+
+## Summary
+Applies a swap of two elements in an array.
+
+## Input
+### firstIndex
+Index of the first element to be swapped.
+
+### secondIndex
+Index of the second element to be swapped.
+
+### array
+Array with elements to be swapped.
+
+## Output
+The array with the in place swap applied.
+
+## Example
+```qsharp
+// The following returns [0, 3, 2, 1, 4]
+Swapped(1, 3, [0, 1, 2, 3, 4]);
+```

package/docs/Microsoft.Quantum.Arrays/Tail.md

@@ -0,0 +1,32 @@
+---
+uid: Microsoft.Quantum.Arrays.Tail
+title: Tail function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Tail
+qsharp.summary: Returns the last element of the array.
+---
+
+# Tail function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function Tail<'A>(array : 'A[]) : 'A
+```
+
+## Summary
+Returns the last element of the array.
+
+## Type Parameters
+### 'A
+The type of the array elements.
+
+## Input
+### array
+Array of which the last element is taken. Array must have at least 1 element.
+
+## Output
+The last element of the array.

package/docs/Microsoft.Quantum.Arrays/Transposed.md

@@ -0,0 +1,47 @@
+---
+uid: Microsoft.Quantum.Arrays.Transposed
+title: Transposed function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Transposed
+qsharp.summary: Returns the transpose of a matrix represented as an array
+of arrays.
+---
+
+# Transposed function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function Transposed<'T>(matrix : 'T[][]) : 'T[][]
+```
+
+## Summary
+Returns the transpose of a matrix represented as an array
+of arrays.
+
+## Description
+Input as an r x c matrix with r rows and c columns.  The matrix
+is row-based, i.e., `matrix[i][j]` accesses the element at row `i` and column `j`.
+
+This function returns the c x r matrix that is the transpose of the
+input matrix.
+
+## Type Parameters
+### 'T
+The type of each element of `matrix`.
+
+## Input
+### matrix
+Row-based r x c matrix.
+
+## Output
+Transposed c x r matrix.
+
+## Example
+```qsharp
+// same as [[1, 4], [2, 5], [3, 6]]
+let transposed = Transposed([[1, 2, 3], [4, 5, 6]]);
+```

package/docs/Microsoft.Quantum.Arrays/Unzipped.md

@@ -0,0 +1,46 @@
+---
+uid: Microsoft.Quantum.Arrays.Unzipped
+title: Unzipped function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Unzipped
+qsharp.summary: Given an array of 2-tuples, returns a tuple of two arrays, each containing
+the elements of the tuples of the input array.
+---
+
+# Unzipped function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function Unzipped<'T, 'U>(array : ('T, 'U)[]) : ('T[], 'U[])
+```
+
+## Summary
+Given an array of 2-tuples, returns a tuple of two arrays, each containing
+the elements of the tuples of the input array.
+
+## Type Parameters
+### 'T
+The type of the first element in each tuple.
+### 'U
+The type of the second element in each tuple.
+
+## Input
+### array
+An array containing 2-tuples.
+
+## Output
+Two arrays, the first one containing all first elements of the input
+tuples, the second one containing all second elements of the input tuples.
+
+## Example
+```qsharp
+// split is same as ([5, 4, 3, 2, 1], [true, false, true, true, false])
+let split = Unzipped([(5, true), (4, false), (3, true), (2, true), (1, false)]);
+```
+
+## See Also
+- Microsoft.Quantum.Arrays.Zipped

package/docs/Microsoft.Quantum.Arrays/Where.md

@@ -0,0 +1,36 @@
+---
+uid: Microsoft.Quantum.Arrays.Where
+title: Where function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Where
+qsharp.summary: Given a predicate and an array, returns the indices of that
+array where the predicate is true.
+---
+
+# Where function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function Where<'T>(predicate : ('T -> Bool), array : 'T[]) : Int[]
+```
+
+## Summary
+Given a predicate and an array, returns the indices of that
+array where the predicate is true.
+
+## Type Parameters
+### 'T
+The type of `array` elements.
+
+## Input
+### predicate
+A function from `'T` to Boolean that is used to filter elements.
+### array
+An array of elements over `'T`.
+
+## Output
+An array of indices where `predicate` is true.

package/docs/Microsoft.Quantum.Arrays/Windows.md

@@ -0,0 +1,47 @@
+---
+uid: Microsoft.Quantum.Arrays.Windows
+title: Windows function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Windows
+qsharp.summary: Returns all consecutive subarrays of length `size`.
+---
+
+# Windows function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function Windows<'T>(size : Int, array : 'T[]) : 'T[][]
+```
+
+## Summary
+Returns all consecutive subarrays of length `size`.
+
+## Description
+This function returns all `n - size + 1` subarrays of
+length `size` in order, where `n` is the length of `array`.
+The first subarrays are `array[0..size - 1], array[1..size], array[2..size + 1]`
+until the last subarray `array[n - size..n - 1]`.
+
+## Type Parameters
+### 'T
+The type of `array` elements.
+
+## Input
+### size
+Length of the subarrays.
+
+### array
+An array of elements.
+
+## Example
+```qsharp
+// same as [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
+let windows = Windows(3, [1, 2, 3, 4, 5]);
+```
+
+## Remarks
+The size of the window must be a positive integer no greater than the size of the array

package/docs/Microsoft.Quantum.Arrays/Zipped.md

@@ -0,0 +1,50 @@
+---
+uid: Microsoft.Quantum.Arrays.Zipped
+title: Zipped function
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: function
+qsharp.namespace: Microsoft.Quantum.Arrays
+qsharp.name: Zipped
+qsharp.summary: Given two arrays, returns a new array of pairs such that each pair
+contains an element from each original array.
+---
+
+# Zipped function
+
+Namespace: [Microsoft.Quantum.Arrays](xref:Microsoft.Quantum.Arrays)
+
+```qsharp
+function Zipped<'T, 'U>(left : 'T[], right : 'U[]) : ('T, 'U)[]
+```
+
+## Summary
+Given two arrays, returns a new array of pairs such that each pair
+contains an element from each original array.
+
+## Type Parameters
+### 'T
+The type of the left array elements.
+### 'U
+The type of the right array elements.
+
+## Input
+### left
+An array containing values for the first element of each tuple.
+### right
+An array containing values for the second element of each tuple.
+
+## Output
+An array containing pairs of the form `(left[index], right[index])` for
+each `index`. If the two arrays are not of equal length, the output will
+be as long as the shorter of the inputs.
+
+## Example
+```qsharp
+let left = [1, 3, 71];
+let right = [false, true];
+let pairs = Zipped(left, right); // [(1, false), (3, true)]
+```
+
+## See Also
+- Microsoft.Quantum.Arrays.Unzipped

package/docs/Microsoft.Quantum.Canon/ApplyCNOTChain.md

@@ -0,0 +1,35 @@
+---
+uid: Microsoft.Quantum.Canon.ApplyCNOTChain
+title: ApplyCNOTChain operation
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: opeartion
+qsharp.namespace: Microsoft.Quantum.Canon
+qsharp.name: ApplyCNOTChain
+qsharp.summary: Computes the parity of a register of qubits in-place.
+---
+
+# ApplyCNOTChain operation
+
+Namespace: [Microsoft.Quantum.Canon](xref:Microsoft.Quantum.Canon)
+
+```qsharp
+operation ApplyCNOTChain(qubits : Qubit[]) : Unit is Adj + Ctl
+```
+
+## Summary
+Computes the parity of a register of qubits in-place.
+
+## Input
+### qubits
+Array of qubits whose parity is to be computed and stored.
+
+## Remarks
+This operation transforms the state of its input as
+$$
+\begin{align}
+    \ket{q_0} \ket{q_1} \cdots \ket{q_{n - 1}} & \mapsto
+    \ket{q_0} \ket{q_0 \oplus q_1} \ket{q_0 \oplus q_1 \oplus q_2} \cdots
+        \ket{q_0 \oplus \cdots \oplus q_{n - 1}}.
+\end{align}
+$$

package/docs/Microsoft.Quantum.Canon/ApplyControlledOnBitString.md

@@ -0,0 +1,42 @@
+---
+uid: Microsoft.Quantum.Canon.ApplyControlledOnBitString
+title: ApplyControlledOnBitString operation
+ms.date: 02/16/2024 12:00:00 AM
+ms.topic: managed-reference
+qsharp.kind: opeartion
+qsharp.namespace: Microsoft.Quantum.Canon
+qsharp.name: ApplyControlledOnBitString
+qsharp.summary: Applies a unitary operation on the target,
+controlled on a state specified by a given bit mask.
+---
+
+# ApplyControlledOnBitString operation
+
+Namespace: [Microsoft.Quantum.Canon](xref:Microsoft.Quantum.Canon)
+
+```qsharp
+operation ApplyControlledOnBitString<'T>(bits : Bool[], oracle : ('T => Unit is Adj + Ctl), controlRegister : Qubit[], target : 'T) : Unit is Adj + Ctl
+```
+
+## Summary
+Applies a unitary operation on the target,
+controlled on a state specified by a given bit mask.
+
+## Input
+### bits
+The bit string to control the given unitary operation on.
+### oracle
+The unitary operation to be applied on the target.
+### target
+The target to be passed to `oracle` as an input.
+### controlRegister
+A quantum register that controls application of `oracle`.
+
+## Remarks
+The pattern given by `bits` may be shorter than `controlRegister`,
+in which case additional control qubits are ignored (that is, neither
+controlled on $\ket{0}$ nor $\ket{1}$).
+If `bits` is longer than `controlRegister`, an error is raised.
+
+For example, `bits = [0,1,0,0,1]` means that `oracle` is applied if and only if `controlRegister`
+is in the state $\ket{0}\ket{1}\ket{0}\ket{0}\ket{1}$.