From d7668baf00fd392e2d6f2ad0fe938e4214b49ba8 Mon Sep 17 00:00:00 2001 From: Sarah Marshall Date: Fri, 11 Sep 2020 16:19:15 -0700 Subject: [PATCH 01/14] Add Capability attribute to Microsoft.Quantum.Core --- src/Simulation/QsharpCore/Core.qs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/Simulation/QsharpCore/Core.qs b/src/Simulation/QsharpCore/Core.qs index 69d3287f5ee..7ef83f78d95 100644 --- a/src/Simulation/QsharpCore/Core.qs +++ b/src/Simulation/QsharpCore/Core.qs @@ -30,6 +30,21 @@ namespace Microsoft.Quantum.Core { @Attribute() newtype Deprecated = (NewName : String); + /// # Summary + /// Compiler-recognized attribute used to mark a callable with the runtime capabilities it requires. + /// + /// # Input + /// ## Level + /// The name of the runtime capability level required by the callable. + /// + /// # Remarks + /// The valid capability level names, in order of increasing capabilities, are: + /// + /// 1. QPRGen0 + /// 2. QPRGen1 + /// 3. Unknown + @Attribute() + newtype Capability = (Level : String); /// # Summary /// Returns a default instance of the specified type. From 6eec594207bb875d02a34b1be74294846e8976eb Mon Sep 17 00:00:00 2001 From: Sarah Marshall Date: Wed, 30 Sep 2020 12:06:37 -0700 Subject: [PATCH 02/14] Override Reset capability --- src/Simulation/QsharpCore/Core.qs | 2 -- src/Simulation/QsharpCore/Intrinsic.qs | 9 ++------- 2 files changed, 2 insertions(+), 9 deletions(-) diff --git a/src/Simulation/QsharpCore/Core.qs b/src/Simulation/QsharpCore/Core.qs index 7ef83f78d95..ce5930c6619 100644 --- a/src/Simulation/QsharpCore/Core.qs +++ b/src/Simulation/QsharpCore/Core.qs @@ -151,5 +151,3 @@ namespace Microsoft.Quantum.Core { } } - - diff --git a/src/Simulation/QsharpCore/Intrinsic.qs b/src/Simulation/QsharpCore/Intrinsic.qs index 0a22cb388f1..24d32cc4c9f 100644 --- a/src/Simulation/QsharpCore/Intrinsic.qs +++ b/src/Simulation/QsharpCore/Intrinsic.qs @@ -666,10 +666,9 @@ namespace Microsoft.Quantum.Intrinsic { /// # Input /// ## qubit /// The qubit whose state is to be reset to $\ket{0}$. + @Capability("QPRGen0") operation Reset (target : Qubit) : Unit { - - if (M(target) == One) - { + if (M(target) == One) { X(target); } } @@ -683,12 +682,8 @@ namespace Microsoft.Quantum.Intrinsic { /// ## qubits /// An array of qubits whose states are to be reset to $\ket{0}$. operation ResetAll (qubits : Qubit[]) : Unit { - for (qubit in qubits) { Reset(qubit); } } - } - - From 972c382d1f1f05e409eb0f41393215f491e40210 Mon Sep 17 00:00:00 2001 From: Sarah Marshall Date: Fri, 2 Oct 2020 15:41:02 -0700 Subject: [PATCH 03/14] Use "Named Items" instead of "Input" in doc --- src/Simulation/QsharpCore/Core.qs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Simulation/QsharpCore/Core.qs b/src/Simulation/QsharpCore/Core.qs index ce5930c6619..846fbd1bc86 100644 --- a/src/Simulation/QsharpCore/Core.qs +++ b/src/Simulation/QsharpCore/Core.qs @@ -22,7 +22,7 @@ namespace Microsoft.Quantum.Core { /// # Summary /// Compiler-recognized attribute used to mark a type or callable as deprecated. /// - /// # Input + /// # Named Items /// ## NewName /// The full name of the type or callable to use instead. /// Is set to the empty String if a type or callable has been deprecated without substitution. @@ -33,7 +33,7 @@ namespace Microsoft.Quantum.Core { /// # Summary /// Compiler-recognized attribute used to mark a callable with the runtime capabilities it requires. /// - /// # Input + /// # Named Items /// ## Level /// The name of the runtime capability level required by the callable. /// From 2b3c51902225b3a30d7f6db337d7ed4a29044132 Mon Sep 17 00:00:00 2001 From: Sarah Marshall Date: Fri, 2 Oct 2020 15:48:59 -0700 Subject: [PATCH 04/14] Add documentation for capability levels --- src/Simulation/QsharpCore/Core.qs | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/src/Simulation/QsharpCore/Core.qs b/src/Simulation/QsharpCore/Core.qs index 846fbd1bc86..3b20ea8ca1c 100644 --- a/src/Simulation/QsharpCore/Core.qs +++ b/src/Simulation/QsharpCore/Core.qs @@ -31,18 +31,28 @@ namespace Microsoft.Quantum.Core { newtype Deprecated = (NewName : String); /// # Summary - /// Compiler-recognized attribute used to mark a callable with the runtime capabilities it requires. + /// Compiler-recognized attribute used to mark a callable with the runtime capabilities it + /// requires. /// /// # Named Items /// ## Level /// The name of the runtime capability level required by the callable. /// /// # Remarks - /// The valid capability level names, in order of increasing capabilities, are: + /// The valid capability level names, in order of increasing capabilities (or decreasing + /// restrictions), are: /// - /// 1. QPRGen0 - /// 2. QPRGen1 - /// 3. Unknown + /// ## QPRGen0 + /// Measurement results cannot be compared for equality. + /// + /// ## QPRGen1 + /// Measurement results can be compared for equality only in if-statement conditional + /// expressions in operations. The block of an if-statement that depends on a result cannot + /// contain set statements for mutable variables declared outside the block, or return + /// statements. + /// + /// ## Unknown + /// No known runtime restrictions. Any Q# program can be executed. @Attribute() newtype Capability = (Level : String); From d2db5542e0e2198cc9f297a722b94133296a4380 Mon Sep 17 00:00:00 2001 From: Sarah Marshall Date: Mon, 19 Oct 2020 13:44:57 -0700 Subject: [PATCH 05/14] Rename attribute to RequiresCapability --- src/Simulation/QsharpCore/Core.qs | 2 +- src/Simulation/QsharpCore/Intrinsic.qs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Simulation/QsharpCore/Core.qs b/src/Simulation/QsharpCore/Core.qs index 3b20ea8ca1c..2d7e5cde663 100644 --- a/src/Simulation/QsharpCore/Core.qs +++ b/src/Simulation/QsharpCore/Core.qs @@ -54,7 +54,7 @@ namespace Microsoft.Quantum.Core { /// ## Unknown /// No known runtime restrictions. Any Q# program can be executed. @Attribute() - newtype Capability = (Level : String); + newtype RequiresCapability = (Level : String); /// # Summary /// Returns a default instance of the specified type. diff --git a/src/Simulation/QsharpCore/Intrinsic.qs b/src/Simulation/QsharpCore/Intrinsic.qs index 24d32cc4c9f..842fe41a3a3 100644 --- a/src/Simulation/QsharpCore/Intrinsic.qs +++ b/src/Simulation/QsharpCore/Intrinsic.qs @@ -666,7 +666,7 @@ namespace Microsoft.Quantum.Intrinsic { /// # Input /// ## qubit /// The qubit whose state is to be reset to $\ket{0}$. - @Capability("QPRGen0") + @RequiresCapability("QPRGen0") operation Reset (target : Qubit) : Unit { if (M(target) == One) { X(target); From 1538eef3197ae1996e453506b340bbb5c0cdc54d Mon Sep 17 00:00:00 2001 From: Sarah Marshall Date: Mon, 19 Oct 2020 14:02:24 -0700 Subject: [PATCH 06/14] Add Reason property --- src/Simulation/QsharpCore/Core.qs | 5 ++++- src/Simulation/QsharpCore/Intrinsic.qs | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/src/Simulation/QsharpCore/Core.qs b/src/Simulation/QsharpCore/Core.qs index 2d7e5cde663..8cfede0723d 100644 --- a/src/Simulation/QsharpCore/Core.qs +++ b/src/Simulation/QsharpCore/Core.qs @@ -37,6 +37,9 @@ namespace Microsoft.Quantum.Core { /// # Named Items /// ## Level /// The name of the runtime capability level required by the callable. + /// + /// ## Reason + /// A description of why the callable requires this runtime capability. /// /// # Remarks /// The valid capability level names, in order of increasing capabilities (or decreasing @@ -54,7 +57,7 @@ namespace Microsoft.Quantum.Core { /// ## Unknown /// No known runtime restrictions. Any Q# program can be executed. @Attribute() - newtype RequiresCapability = (Level : String); + newtype RequiresCapability = (Level : String, Reason : String); /// # Summary /// Returns a default instance of the specified type. diff --git a/src/Simulation/QsharpCore/Intrinsic.qs b/src/Simulation/QsharpCore/Intrinsic.qs index 842fe41a3a3..848b0d01bf6 100644 --- a/src/Simulation/QsharpCore/Intrinsic.qs +++ b/src/Simulation/QsharpCore/Intrinsic.qs @@ -666,7 +666,7 @@ namespace Microsoft.Quantum.Intrinsic { /// # Input /// ## qubit /// The qubit whose state is to be reset to $\ket{0}$. - @RequiresCapability("QPRGen0") + @RequiresCapability("QPRGen0", "Reset may be replaced by a supported implementation on all execution targets.") operation Reset (target : Qubit) : Unit { if (M(target) == One) { X(target); From cfe438552c0eaa7a951a89ed3dc2b28f5414192b Mon Sep 17 00:00:00 2001 From: Sarah Marshall Date: Mon, 19 Oct 2020 14:08:12 -0700 Subject: [PATCH 07/14] Update capability names --- src/Simulation/QsharpCore/Core.qs | 8 ++++---- src/Simulation/QsharpCore/Intrinsic.qs | 15 +++++++++------ 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/src/Simulation/QsharpCore/Core.qs b/src/Simulation/QsharpCore/Core.qs index 8cfede0723d..d9f5cd8a5f2 100644 --- a/src/Simulation/QsharpCore/Core.qs +++ b/src/Simulation/QsharpCore/Core.qs @@ -45,17 +45,17 @@ namespace Microsoft.Quantum.Core { /// The valid capability level names, in order of increasing capabilities (or decreasing /// restrictions), are: /// - /// ## QPRGen0 + /// ## BasicQuantumFunctionality /// Measurement results cannot be compared for equality. /// - /// ## QPRGen1 + /// ## BasicMeasurementFeedback /// Measurement results can be compared for equality only in if-statement conditional /// expressions in operations. The block of an if-statement that depends on a result cannot /// contain set statements for mutable variables declared outside the block, or return /// statements. /// - /// ## Unknown - /// No known runtime restrictions. Any Q# program can be executed. + /// ## FullComputation + /// No runtime restrictions. Any Q# program can be executed. @Attribute() newtype RequiresCapability = (Level : String, Reason : String); diff --git a/src/Simulation/QsharpCore/Intrinsic.qs b/src/Simulation/QsharpCore/Intrinsic.qs index 848b0d01bf6..85114413875 100644 --- a/src/Simulation/QsharpCore/Intrinsic.qs +++ b/src/Simulation/QsharpCore/Intrinsic.qs @@ -657,23 +657,26 @@ namespace Microsoft.Quantum.Intrinsic { operation M (qubit : Qubit) : Result { return Measure([PauliZ], [qubit]); } - - + + /// # Summary /// Given a single qubit, measures it and ensures it is in the |0⟩ state /// such that it can be safely released. /// /// # Input - /// ## qubit + /// ## target /// The qubit whose state is to be reset to $\ket{0}$. - @RequiresCapability("QPRGen0", "Reset may be replaced by a supported implementation on all execution targets.") + @RequiresCapability( + "BasicQuantumFunctionality", + "Reset is replaced by a supported implementation on all execution targets." + ) operation Reset (target : Qubit) : Unit { if (M(target) == One) { X(target); } } - - + + /// # Summary /// Given an array of qubits, measure them and ensure they are in the |0⟩ state /// such that they can be safely released. From fb0d91945ebf5df60a8e5c2c04c603c327db0dee Mon Sep 17 00:00:00 2001 From: Sarah Marshall Date: Mon, 19 Oct 2020 14:24:28 -0700 Subject: [PATCH 08/14] Move attribute to Microsoft.Quantum.Targeting --- src/Simulation/QsharpCore/Core.qs | 29 --------------------- src/Simulation/QsharpCore/Intrinsic.qs | 1 + src/Simulation/QsharpCore/Targeting.qs | 35 ++++++++++++++++++++++++++ 3 files changed, 36 insertions(+), 29 deletions(-) create mode 100644 src/Simulation/QsharpCore/Targeting.qs diff --git a/src/Simulation/QsharpCore/Core.qs b/src/Simulation/QsharpCore/Core.qs index d9f5cd8a5f2..fe4a5d02e50 100644 --- a/src/Simulation/QsharpCore/Core.qs +++ b/src/Simulation/QsharpCore/Core.qs @@ -30,35 +30,6 @@ namespace Microsoft.Quantum.Core { @Attribute() newtype Deprecated = (NewName : String); - /// # Summary - /// Compiler-recognized attribute used to mark a callable with the runtime capabilities it - /// requires. - /// - /// # Named Items - /// ## Level - /// The name of the runtime capability level required by the callable. - /// - /// ## Reason - /// A description of why the callable requires this runtime capability. - /// - /// # Remarks - /// The valid capability level names, in order of increasing capabilities (or decreasing - /// restrictions), are: - /// - /// ## BasicQuantumFunctionality - /// Measurement results cannot be compared for equality. - /// - /// ## BasicMeasurementFeedback - /// Measurement results can be compared for equality only in if-statement conditional - /// expressions in operations. The block of an if-statement that depends on a result cannot - /// contain set statements for mutable variables declared outside the block, or return - /// statements. - /// - /// ## FullComputation - /// No runtime restrictions. Any Q# program can be executed. - @Attribute() - newtype RequiresCapability = (Level : String, Reason : String); - /// # Summary /// Returns a default instance of the specified type. /// diff --git a/src/Simulation/QsharpCore/Intrinsic.qs b/src/Simulation/QsharpCore/Intrinsic.qs index 85114413875..0ce887c0ae6 100644 --- a/src/Simulation/QsharpCore/Intrinsic.qs +++ b/src/Simulation/QsharpCore/Intrinsic.qs @@ -4,6 +4,7 @@ namespace Microsoft.Quantum.Intrinsic { open Microsoft.Quantum.Math; open Microsoft.Quantum.Convert; + open Microsoft.Quantum.Targeting; @Deprecated("Microsoft.Quantum.Random.DrawCategorical") operation Random (probs : Double[]) : Int { diff --git a/src/Simulation/QsharpCore/Targeting.qs b/src/Simulation/QsharpCore/Targeting.qs new file mode 100644 index 00000000000..7009cdb1251 --- /dev/null +++ b/src/Simulation/QsharpCore/Targeting.qs @@ -0,0 +1,35 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +/// # Summary +/// This namespace includes Q# core functions and operations. +namespace Microsoft.Quantum.Targeting { + /// # Summary + /// Compiler-recognized attribute used to mark a callable with the runtime capabilities it + /// requires. + /// + /// # Named Items + /// ## Level + /// The name of the runtime capability level required by the callable. + /// + /// ## Reason + /// A description of why the callable requires this runtime capability. + /// + /// # Remarks + /// The valid capability level names, in order of increasing capabilities (or decreasing + /// restrictions), are: + /// + /// ## BasicQuantumFunctionality + /// Measurement results cannot be compared for equality. + /// + /// ## BasicMeasurementFeedback + /// Measurement results can be compared for equality only in if-statement conditional + /// expressions in operations. The block of an if-statement that depends on a result cannot + /// contain set statements for mutable variables declared outside the block, or return + /// statements. + /// + /// ## FullComputation + /// No runtime restrictions. Any Q# program can be executed. + @Attribute() + newtype RequiresCapability = (Level : String, Reason : String); +} From 8e919e67e0f5acd705450995ce9c7e0bd2c0fe9b Mon Sep 17 00:00:00 2001 From: Sarah Marshall <33814365+samarsha@users.noreply.github.com> Date: Tue, 20 Oct 2020 12:08:46 -0700 Subject: [PATCH 09/14] Format capability names as string literals Co-authored-by: Chris Granade --- src/Simulation/QsharpCore/Targeting.qs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Simulation/QsharpCore/Targeting.qs b/src/Simulation/QsharpCore/Targeting.qs index 7009cdb1251..1b4f03c8ff4 100644 --- a/src/Simulation/QsharpCore/Targeting.qs +++ b/src/Simulation/QsharpCore/Targeting.qs @@ -19,10 +19,10 @@ namespace Microsoft.Quantum.Targeting { /// The valid capability level names, in order of increasing capabilities (or decreasing /// restrictions), are: /// - /// ## BasicQuantumFunctionality + /// ## `"BasicQuantumFunctionality"` /// Measurement results cannot be compared for equality. /// - /// ## BasicMeasurementFeedback + /// ## `"BasicMeasurementFeedback"` /// Measurement results can be compared for equality only in if-statement conditional /// expressions in operations. The block of an if-statement that depends on a result cannot /// contain set statements for mutable variables declared outside the block, or return From 7b72c69b11c175ae64c34384f802a0e0cd681e5e Mon Sep 17 00:00:00 2001 From: Sarah Marshall Date: Tue, 20 Oct 2020 12:10:28 -0700 Subject: [PATCH 10/14] Add quotes around FullComputation --- src/Simulation/QsharpCore/Targeting.qs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Simulation/QsharpCore/Targeting.qs b/src/Simulation/QsharpCore/Targeting.qs index 1b4f03c8ff4..054d680abb3 100644 --- a/src/Simulation/QsharpCore/Targeting.qs +++ b/src/Simulation/QsharpCore/Targeting.qs @@ -28,7 +28,7 @@ namespace Microsoft.Quantum.Targeting { /// contain set statements for mutable variables declared outside the block, or return /// statements. /// - /// ## FullComputation + /// ## `"FullComputation"` /// No runtime restrictions. Any Q# program can be executed. @Attribute() newtype RequiresCapability = (Level : String, Reason : String); From 39e4207525e9809a0560ae920c527cb9f5ed545f Mon Sep 17 00:00:00 2001 From: Sarah Marshall Date: Tue, 20 Oct 2020 12:47:05 -0700 Subject: [PATCH 11/14] Update namespace description --- src/Simulation/QsharpCore/Targeting.qs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Simulation/QsharpCore/Targeting.qs b/src/Simulation/QsharpCore/Targeting.qs index 054d680abb3..d3f6304b76c 100644 --- a/src/Simulation/QsharpCore/Targeting.qs +++ b/src/Simulation/QsharpCore/Targeting.qs @@ -2,7 +2,7 @@ // Licensed under the MIT License. /// # Summary -/// This namespace includes Q# core functions and operations. +/// This namespace provides functionality for targeting specific quantum processors. namespace Microsoft.Quantum.Targeting { /// # Summary /// Compiler-recognized attribute used to mark a callable with the runtime capabilities it From 8926b9fe4956438c71a012d02d152223c16025c6 Mon Sep 17 00:00:00 2001 From: Sarah Marshall <33814365+samarsha@users.noreply.github.com> Date: Tue, 20 Oct 2020 12:47:47 -0700 Subject: [PATCH 12/14] Update copyright header Co-authored-by: Chris Granade --- src/Simulation/QsharpCore/Targeting.qs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Simulation/QsharpCore/Targeting.qs b/src/Simulation/QsharpCore/Targeting.qs index d3f6304b76c..1423e78e561 100644 --- a/src/Simulation/QsharpCore/Targeting.qs +++ b/src/Simulation/QsharpCore/Targeting.qs @@ -1,4 +1,4 @@ -// Copyright (c) Microsoft Corporation. All rights reserved. +// Copyright (c) Microsoft Corporation. // Licensed under the MIT License. /// # Summary From 9f15210d8bde0c9a5eb4c141262b3f93eacbfd15 Mon Sep 17 00:00:00 2001 From: Sarah Marshall Date: Tue, 20 Oct 2020 13:08:31 -0700 Subject: [PATCH 13/14] Add note that attribute is compiler-generated --- src/Simulation/QsharpCore/Targeting.qs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/Simulation/QsharpCore/Targeting.qs b/src/Simulation/QsharpCore/Targeting.qs index 1423e78e561..9a013866f47 100644 --- a/src/Simulation/QsharpCore/Targeting.qs +++ b/src/Simulation/QsharpCore/Targeting.qs @@ -16,8 +16,11 @@ namespace Microsoft.Quantum.Targeting { /// A description of why the callable requires this runtime capability. /// /// # Remarks - /// The valid capability level names, in order of increasing capabilities (or decreasing - /// restrictions), are: + /// This attribute is added automatically by the compiler. It should not be used except in rare + /// cases where the compiler does not infer the required capability correctly. + /// + /// Below is the list of capability level names, in order of increasing capabilities or + /// decreasing restrictions: /// /// ## `"BasicQuantumFunctionality"` /// Measurement results cannot be compared for equality. From 2843c3c41074074392f46af1a1909ec145e305ff Mon Sep 17 00:00:00 2001 From: Sarah Marshall Date: Tue, 20 Oct 2020 16:58:18 -0700 Subject: [PATCH 14/14] Clarify behavior when attribute is manually added --- src/Simulation/QsharpCore/Targeting.qs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/Simulation/QsharpCore/Targeting.qs b/src/Simulation/QsharpCore/Targeting.qs index 9a013866f47..989a5eb7ec9 100644 --- a/src/Simulation/QsharpCore/Targeting.qs +++ b/src/Simulation/QsharpCore/Targeting.qs @@ -16,8 +16,9 @@ namespace Microsoft.Quantum.Targeting { /// A description of why the callable requires this runtime capability. /// /// # Remarks - /// This attribute is added automatically by the compiler. It should not be used except in rare - /// cases where the compiler does not infer the required capability correctly. + /// This attribute is automatically added to callables by the compiler, unless an instance of + /// this attribute already exists on the callable. It should not be used except in rare cases + /// where the compiler does not infer the required capability correctly. /// /// Below is the list of capability level names, in order of increasing capabilities or /// decreasing restrictions: