feat: explicit random stabilizer states using Categorical state sampling and qbinomial coefficients

[Fe-r-oz]

This PR aims to provide Julia re-implementation of the algorithm for generating random stabilizer states, as described in G.I. Struchalin et al.'s paper "Experimental Estimation of Quantum State Properties from Classical Shadows" (PRX Quantum 2, 010307, 2021), specifically in Appendix A.

Key features:

• Efficient Sampling: Uses Categorical distribution from Julia’s Distributions package for uniform sampling of stabilizer states.
• Polynomial-time Complexity: Optimized with a focus on reducing computational complexity for state generation.
• Explicit State Generation: Calculates the full 2n-dimensional state vector, essential for experimental simulations.
• q-Binomial Coefficients: Utilizes q-binomial coefficients for efficient calculation of stabilizer state cardinality and uniform sampling.

This was inspired from a very recent paper, Fast algorithms for classical specifications of stabiliser states and Clifford gates, (posted on 3 Jan, 2025) that provided 10 new algorithms for stabilizer formalism. I think we might have most of functionality mentioned in second paper to some extent already, we can benchmark these 10 algorithms against stim and qiskit as this paper provided a lot of benchmarks. Please refer to Appendix B: Timed Benchmarks. The second paper utilized the random stabilizer state generation algorithm given in the first mentioned paper:

Please let me know your thoughts before I proceed. Thank you!

Reference to #25. This implementation gives me a QuantumOpticsBase vibe.

julia> random_stabilizer_state(5)
32-element Vector{ComplexF32}:
  0.17677669f0 + 0.0f0im
        -0.0f0 - 0.17677669f0im
  0.17677669f0 + 0.0f0im
        -0.0f0 - 0.17677669f0im
         0.0f0 + 0.17677669f0im
 -0.17677669f0 + 0.0f0im
        -0.0f0 - 0.17677669f0im
  0.17677669f0 + 0.0f0im
         0.0f0 + 0.17677669f0im
  0.17677669f0 + 0.0f0im
         0.0f0 + 0.17677669f0im
  0.17677669f0 + 0.0f0im
  0.17677669f0 + 0.0f0im
         0.0f0 + 0.17677669f0im
 -0.17677669f0 + 0.0f0im
        -0.0f0 - 0.17677669f0im
        -0.0f0 - 0.17677669f0im
  0.17677669f0 + 0.0f0im
         0.0f0 + 0.17677669f0im
 -0.17677669f0 + 0.0f0im
 -0.17677669f0 + 0.0f0im
         0.0f0 + 0.17677669f0im
 -0.17677669f0 + 0.0f0im
         0.0f0 + 0.17677669f0im
  0.17677669f0 + 0.0f0im
         0.0f0 + 0.17677669f0im
 -0.17677669f0 + 0.0f0im
        -0.0f0 - 0.17677669f0im
         0.0f0 + 0.17677669f0im
  0.17677669f0 + 0.0f0im
         0.0f0 + 0.17677669f0im
  0.17677669f0 + 0.0f0im

julia> random_stabilizer_state(5)
32-element Vector{ComplexF32}:
   0.0f0 - 0.0f0im
  0.25f0 + 0.0f0im
  0.25f0 + 0.0f0im
   0.0f0 - 0.0f0im
  -0.0f0 + 0.25f0im
   0.0f0 - 0.0f0im
   0.0f0 - 0.0f0im
  -0.0f0 + 0.25f0im
   0.0f0 - 0.0f0im
 -0.25f0 - 0.0f0im
 -0.25f0 - 0.0f0im
   0.0f0 - 0.0f0im
  -0.0f0 + 0.25f0im
   0.0f0 - 0.0f0im
   0.0f0 - 0.0f0im
  -0.0f0 + 0.25f0im
   0.0f0 - 0.0f0im
  0.25f0 + 0.0f0im
 -0.25f0 - 0.0f0im
   0.0f0 - 0.0f0im
  -0.0f0 + 0.25f0im
   0.0f0 - 0.0f0im
   0.0f0 - 0.0f0im
   0.0f0 - 0.25f0im
   0.0f0 - 0.0f0im
 -0.25f0 - 0.0f0im
  0.25f0 + 0.0f0im
   0.0f0 - 0.0f0im
  -0.0f0 + 0.25f0im
   0.0f0 - 0.0f0im
   0.0f0 - 0.0f0im
   0.0f0 - 0.25f0im

julia> random_stabilizer_state(4)
16-element Vector{ComplexF32}:
         0.0f0 + 0.0f0im
         0.0f0 + 0.0f0im
  0.35355338f0 + 0.0f0im
 -0.35355338f0 + 0.0f0im
         0.0f0 + 0.0f0im
         0.0f0 + 0.0f0im
  0.35355338f0 + 0.0f0im
 -0.35355338f0 + 0.0f0im
         0.0f0 + 0.35355338f0im
         0.0f0 - 0.35355338f0im
         0.0f0 + 0.0f0im
         0.0f0 + 0.0f0im
         0.0f0 - 0.35355338f0im
         0.0f0 + 0.35355338f0im
         0.0f0 + 0.0f0im
         0.0f0 + 0.0f0im

• The code is properly formatted and commented.
• Substantial new functionality is documented within the docs.
• All new functionality is tested.
• All of the automated tests on github pass.
• We recently started enforcing formatting checks. If formatting issues are reported in the new code you have written, please correct them.

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 77 lines in your changes missing coverage. Please review.

Project coverage is 81.42%. Comparing base (3297023) to head (85d713f).

Files with missing lines	Patch %	Lines
src/randoms.jl	0.00%	77 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #461      +/-   ##
==========================================
- Coverage   82.83%   81.42%   -1.42%     
==========================================
  Files          70       70              
  Lines        4656     4733      +77     
==========================================
- Hits         3857     3854       -3     
- Misses        799      879      +80     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.