From 8e9cfa202be16d25ae3b09c1d600dddc0d11676e Mon Sep 17 00:00:00 2001 From: Mathias Soeken Date: Tue, 22 Sep 2020 11:50:23 +0200 Subject: [PATCH 1/3] ApplyTo operations. --- .../src/Canon/Combinators/ApplyToArray.qs | 406 ++++++++++++++++++ 1 file changed, 406 insertions(+) create mode 100644 Standard/src/Canon/Combinators/ApplyToArray.qs diff --git a/Standard/src/Canon/Combinators/ApplyToArray.qs b/Standard/src/Canon/Combinators/ApplyToArray.qs new file mode 100644 index 00000000000..d57e99e66e2 --- /dev/null +++ b/Standard/src/Canon/Combinators/ApplyToArray.qs @@ -0,0 +1,406 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. + +namespace Microsoft.Quantum.Canon { + open Microsoft.Quantum.Arrays; + + /// # Summary + /// Applies an operation to the first element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Head(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which the first will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToHeadA + /// - Microsoft.Quantum.Canon.ApplyToHeadC + /// - Microsoft.Quantum.Canon.ApplyToHeadCA + operation ApplyToHead<'T>(op : ('T => Unit), targets : 'T[]) : Unit { + op(Head(targets)); + } + + /// # Summary + /// Applies an operation to the first element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Head(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which the first will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToHead + /// - Microsoft.Quantum.Canon.ApplyToHeadC + /// - Microsoft.Quantum.Canon.ApplyToHeadCA + operation ApplyToHeadA<'T>(op : ('T => Unit is Adj), targets : 'T[]) : Unit is Adj { + op(Head(targets)); + } + + /// # Summary + /// Applies an operation to the first element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Head(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which the first will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToHead + /// - Microsoft.Quantum.Canon.ApplyToHeadA + /// - Microsoft.Quantum.Canon.ApplyToHeadCA + operation ApplyToHeadC<'T>(op : ('T => Unit is Ctl), targets : 'T[]) : Unit is Ctl { + op(Head(targets)); + } + + /// # Summary + /// Applies an operation to the first element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Head(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which the first will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToHead + /// - Microsoft.Quantum.Canon.ApplyToHeadA + /// - Microsoft.Quantum.Canon.ApplyToHeadC + operation ApplyToHeadCA<'T>(op : ('T => Unit is Adj+Ctl), targets : 'T[]) : Unit is Adj+Ctl { + op(Head(targets)); + } + + /// # Summary + /// Applies an operation to all but the first element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Rest(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which all but the first will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToRestA + /// - Microsoft.Quantum.Canon.ApplyToRestC + /// - Microsoft.Quantum.Canon.ApplyToRestCA + operation ApplyToRest<'T>(op : ('T[] => Unit), targets : 'T[]) : Unit { + op(Rest(targets)); + } + + /// # Summary + /// Applies an operation to all but the first element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Rest(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which all but the first will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToRest + /// - Microsoft.Quantum.Canon.ApplyToRestC + /// - Microsoft.Quantum.Canon.ApplyToRestCA + operation ApplyToRestA<'T>(op : ('T[] => Unit is Adj), targets : 'T[]) : Unit is Adj { + op(Rest(targets)); + } + + /// # Summary + /// Applies an operation to all but the first element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Rest(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which all but the first will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToRest + /// - Microsoft.Quantum.Canon.ApplyToRestA + /// - Microsoft.Quantum.Canon.ApplyToRestCA + operation ApplyToRestC<'T>(op : ('T[] => Unit is Ctl), targets : 'T[]) : Unit is Ctl { + op(Rest(targets)); + } + + /// # Summary + /// Applies an operation to all but the first element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Rest(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which all but the first will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToRest + /// - Microsoft.Quantum.Canon.ApplyToRestA + /// - Microsoft.Quantum.Canon.ApplyToRestC + operation ApplyToRestCA<'T>(op : ('T[] => Unit is Adj+Ctl), targets : 'T[]) : Unit is Adj+Ctl { + op(Rest(targets)); + } + + /// # Summary + /// Applies an operation to the last element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Tail(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which the last will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToTailA + /// - Microsoft.Quantum.Canon.ApplyToTailC + /// - Microsoft.Quantum.Canon.ApplyToTailCA + operation ApplyToTail<'T>(op : ('T => Unit), targets : 'T[]) : Unit { + op(Tail(targets)); + } + + /// # Summary + /// Applies an operation to the last element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Tail(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which the last will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToTail + /// - Microsoft.Quantum.Canon.ApplyToTailC + /// - Microsoft.Quantum.Canon.ApplyToTailCA + operation ApplyToTailA<'T>(op : ('T => Unit is Adj), targets : 'T[]) : Unit is Adj { + op(Tail(targets)); + } + + /// # Summary + /// Applies an operation to the last element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Tail(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which the last will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToTail + /// - Microsoft.Quantum.Canon.ApplyToTailA + /// - Microsoft.Quantum.Canon.ApplyToTailCA + operation ApplyToTailC<'T>(op : ('T => Unit is Ctl), targets : 'T[]) : Unit is Ctl { + op(Tail(targets)); + } + + /// # Summary + /// Applies an operation to the last element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Tail(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which the last will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToTail + /// - Microsoft.Quantum.Canon.ApplyToTailA + /// - Microsoft.Quantum.Canon.ApplyToTailC + operation ApplyToTailCA<'T>(op : ('T => Unit is Adj+Ctl), targets : 'T[]) : Unit is Adj+Ctl { + op(Tail(targets)); + } + + /// # Summary + /// Applies an operation to all but the last element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Most(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which all but the last will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToMostA + /// - Microsoft.Quantum.Canon.ApplyToMostC + /// - Microsoft.Quantum.Canon.ApplyToMostCA + operation ApplyToMost<'T>(op : ('T[] => Unit), targets : 'T[]) : Unit { + op(Most(targets)); + } + + /// # Summary + /// Applies an operation to all but the last element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Most(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which all but the last will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToMost + /// - Microsoft.Quantum.Canon.ApplyToMostC + /// - Microsoft.Quantum.Canon.ApplyToMostCA + operation ApplyToMostA<'T>(op : ('T[] => Unit is Adj), targets : 'T[]) : Unit is Adj { + op(Most(targets)); + } + + /// # Summary + /// Applies an operation to all but the last element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Most(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which all but the last will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToMost + /// - Microsoft.Quantum.Canon.ApplyToMostA + /// - Microsoft.Quantum.Canon.ApplyToMostCA + operation ApplyToMostC<'T>(op : ('T[] => Unit is Ctl), targets : 'T[]) : Unit is Ctl { + op(Most(targets)); + } + + /// # Summary + /// Applies an operation to all but the last element of an array. + /// + /// # Description + /// Given an operation `op` and an array of targets `targets`, + /// applies `op(Most(targets))`. + /// + /// # Input + /// ## op + /// An operation to be applied. + /// ## target + /// An array of targets, of which all but the last will be applied to `op`. + /// + /// # Type Parameters + /// ## 'T + /// The input type of the operation to be applied. + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToMost + /// - Microsoft.Quantum.Canon.ApplyToMostA + /// - Microsoft.Quantum.Canon.ApplyToMostC + operation ApplyToMostCA<'T>(op : ('T[] => Unit is Adj+Ctl), targets : 'T[]) : Unit is Adj+Ctl { + op(Most(targets)); + } +} From b8375933224a7ea79d2bde7cc615a6f7aef233f5 Mon Sep 17 00:00:00 2001 From: Mathias Soeken Date: Wed, 23 Sep 2020 11:04:07 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Chris Granade --- Standard/src/Canon/Combinators/ApplyToArray.qs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Standard/src/Canon/Combinators/ApplyToArray.qs b/Standard/src/Canon/Combinators/ApplyToArray.qs index d57e99e66e2..57f2076d890 100644 --- a/Standard/src/Canon/Combinators/ApplyToArray.qs +++ b/Standard/src/Canon/Combinators/ApplyToArray.qs @@ -25,6 +25,13 @@ namespace Microsoft.Quantum.Canon { /// - Microsoft.Quantum.Canon.ApplyToHeadA /// - Microsoft.Quantum.Canon.ApplyToHeadC /// - Microsoft.Quantum.Canon.ApplyToHeadCA + /// + /// # Example + /// The following Q# snippets are equivalent: + /// ```Q# + /// ApplyToHead(H, register); + /// H(Head(register)); + /// ``` operation ApplyToHead<'T>(op : ('T => Unit), targets : 'T[]) : Unit { op(Head(targets)); } From 8af5d930004a79b133d5af0ac74790a8e2ef22f0 Mon Sep 17 00:00:00 2001 From: Mathias Soeken Date: Wed, 23 Sep 2020 11:28:31 +0200 Subject: [PATCH 3/3] Examples. --- .../src/Canon/Combinators/ApplyToArray.qs | 31 ++++++++++++++++--- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/Standard/src/Canon/Combinators/ApplyToArray.qs b/Standard/src/Canon/Combinators/ApplyToArray.qs index 57f2076d890..1d364e82a13 100644 --- a/Standard/src/Canon/Combinators/ApplyToArray.qs +++ b/Standard/src/Canon/Combinators/ApplyToArray.qs @@ -21,17 +21,17 @@ namespace Microsoft.Quantum.Canon { /// ## 'T /// The input type of the operation to be applied. /// - /// # See Also - /// - Microsoft.Quantum.Canon.ApplyToHeadA - /// - Microsoft.Quantum.Canon.ApplyToHeadC - /// - Microsoft.Quantum.Canon.ApplyToHeadCA - /// /// # Example /// The following Q# snippets are equivalent: /// ```Q# /// ApplyToHead(H, register); /// H(Head(register)); /// ``` + /// + /// # See Also + /// - Microsoft.Quantum.Canon.ApplyToHeadA + /// - Microsoft.Quantum.Canon.ApplyToHeadC + /// - Microsoft.Quantum.Canon.ApplyToHeadCA operation ApplyToHead<'T>(op : ('T => Unit), targets : 'T[]) : Unit { op(Head(targets)); } @@ -128,6 +128,13 @@ namespace Microsoft.Quantum.Canon { /// ## 'T /// The input type of the operation to be applied. /// + /// # Example + /// The following Q# snippets are equivalent: + /// ```Q# + /// ApplyToRest(ApplyCNOTChain, register); + /// ApplyCNOTChain(Rest(register)); + /// ``` + /// /// # See Also /// - Microsoft.Quantum.Canon.ApplyToRestA /// - Microsoft.Quantum.Canon.ApplyToRestC @@ -228,6 +235,13 @@ namespace Microsoft.Quantum.Canon { /// ## 'T /// The input type of the operation to be applied. /// + /// # Example + /// The following Q# snippets are equivalent: + /// ```Q# + /// ApplyToTail(H, register); + /// H(Tail(register)); + /// ``` + /// /// # See Also /// - Microsoft.Quantum.Canon.ApplyToTailA /// - Microsoft.Quantum.Canon.ApplyToTailC @@ -328,6 +342,13 @@ namespace Microsoft.Quantum.Canon { /// ## 'T /// The input type of the operation to be applied. /// + /// # Example + /// The following Q# snippets are equivalent: + /// ```Q# + /// ApplyToMost(ApplyCNOTChain, register); + /// ApplyCNOTChain(Most(register)); + /// ``` + /// /// # See Also /// - Microsoft.Quantum.Canon.ApplyToMostA /// - Microsoft.Quantum.Canon.ApplyToMostC