Improvements to Microsoft.Quantum.Random namespace

[cgranade]

Abstract

This improvement to the Q# standard library would make it much simpler to use random numbers from within Q#, as the current intrinsic operation (Microsoft.Quantum.Intrinsic.Random) is specially tailored to a particular usecase and is not intended or designed to support random number generation in general. Users make extensive use of random sampling throughout many Q# programs (e.g.: to support QCVV, variational optimization, and other applications).

Proposed deprecations

• operation Microsoft.Quantum.Intrinsic.Random
• operation Microsoft.Quantum.Math.RandomInt
• operation Microsoft.Quantum.Math.RandomIntMod2
• operation Microsoft.Quantum.Math.RandomReal
• operation Microsoft.Quantum.Math.RandomSingleQubitPauli

Proposed additions

• namespace Microsoft.Quantum.Random
  • newtype ContinuousDistribution = (Sample : Unit => Double);
  • newtype DiscreteDistribution = (Sample : Unit => Int);
  • function ContinuousUniformDistribution(min : Double, max : Double) : ContinuousDistribution;
  • function DiscreteUniformDistribution(min : Int, max : Int) : DiscreteDistribution;
  • function CategoricalDistribution(props : Double[]) : DiscreteDistribution;
  • function StandardNormalDistribution() : ContinuousDistribution;
  • function NormalDistribution(mean : Double, variance : Double) : ContinuousDistribution;
  • function TransformedContinuousDistribution(transform : Double -> Double, distribution : ContinuousDistribution) : ContinuousDistribution;
  • operation MaybeChooseElement<'T>(data : 'T[], indexDistribution : DiscreteDistribution) : (Bool, 'T);
  • operation SampleBinomialTrial(successProbability : Double) : Bool;
  • operation DrawRandomPauli() : Pauli;
  • operation DrawRandomInt(min : Int, max : Int) : Int; // for convenience, replaces existing RandomInt operation
  • operation DrawRandomDouble(min : Double, max : Double) : Double // for convienence, replaces existing RandomReal

Example usecases

open Microsoft.Quantum.Arrays;

DrawMany(StandardNormalDistribution()::Sample, 10, ());

Related work and proposals

• Existing Microsoft.Quantum.Arrays.DrawMany operation. (Add Repeat and DrawMany operations. #276)
• C++11 STL : http://www.cplusplus.com/reference/random/
• scipy.stats: https://docs.scipy.org/doc/scipy/reference/stats.html

Future considerations and language feature dependencies

• Proposed type-parameterized UDT and DU language features could enable using Maybe<'T> as the result type of MaybeChooseElement. (Discriminated unions, Maybe? qsharp-compiler#406)
• Type-parameterized UDTs could enable removing distinction between ContinuousDistribution and DiscreteDistribution, moving to Distribution and Distribution instead. This would also allow Distribution<(Int, Int)> and other such multivariate distribution types. This would allow obviating DrawRandomPauli in favor of Distribution and Distribution<Pauli[]>. (Discriminated unions, Maybe? qsharp-compiler#406)
• Operation and function specializations could allow extending DrawMany to directly handle ContinuousDistribution and DiscreteDistribution, removing the need for the trailing (). Alternatively, DrawMany could provide a specialization for when operations take Unit input, also obviating the need for the trailing ().

[cgranade]

Closed by microsoft/qsharp-runtime#328.