docs: Add documentation for random library#171
Conversation
There was a problem hiding this comment.
Nice job Henry, you've explained things well. I have a few minor suggestions. Also would be good to crosslink to the API docs where possible (see suggestion below).
I was also curious about how this notebook example on randomness relates to the content here. What do you think about replacing this example with this langauge guide section or absorbing some of the content?
|
|
||
| # Random Number Generation | ||
|
|
||
| Guppy provides two implementations of the `PCG32` pseudo-random number generator. ``guppylang.std.qsystem.random`` lowers to calls to a platform RNG, while ``guppylang.std.random`` is a native Guppy implementation. |
There was a problem hiding this comment.
Is there a good reference you could link to on what PCG32 is?
|
|
||
| The main distinction between the two implementations is how the state of the RNG is stored. The native Guppy RNG stores the state locally, while the `qsystem` RNG state is stored globally. This difference has implications for programs with multiple RNGs, as the global nature of the `qsystem` RNG state means that each RNG cannot be treated as completely independent. | ||
|
|
||
| ## qsystem RNG |
There was a problem hiding this comment.
Nit: (you can ignore if you wish) You could make this "The qsystem RNG" to avoid starting the heading with a lower case character.
|
|
||
| ## qsystem RNG | ||
|
|
||
| If you are unsure which RNG to use, the qsystem RNG is recommended due to its broader range of available features. To create an instance of the qsystem RNG, use ``guppylang.std.qsystem.random.RNG`` with an initial `seed`. The RNG offers two basic methods for generating random integers: |
There was a problem hiding this comment.
| If you are unsure which RNG to use, the qsystem RNG is recommended due to its broader range of available features. To create an instance of the qsystem RNG, use ``guppylang.std.qsystem.random.RNG`` with an initial `seed`. The RNG offers two basic methods for generating random integers: | |
| If you are unsure which RNG to use, the qsystem RNG is recommended due to its broader range of available features. To create an instance of the qsystem RNG, use [guppylang.std.qsystem.random.RNG](../api/generated/guppylang.std.qsystem.random.RNG.rst)with an initial `seed`. The RNG offers two basic methods for generating random integers: |
More crosslinks to the API docs throughout would be very useful I think. If you have build the docs locally then VSCode can autocomplete the right path in api/generated.
| weights = array(1.0, 2.0, 7.0) | ||
| dist = make_discrete_distribution(weights) | ||
| rng = RNG(123) | ||
| choice = dist.sample(rng) |
There was a problem hiding this comment.
This example does a good job of showing the interface for RNG. I wonder if doing something with the choice value we have computed would make it better.
Maybe we could apply a Pauli to some qubits depending on the value we have computed. I would like to allude to use cases in quantum programs where possible in the language guide.
|
|
||
| # Random Number Generation | ||
|
|
||
| Guppy provides two implementations of the `PCG32` pseudo-random number generator. ``guppylang.std.qsystem.random`` lowers to calls to a platform RNG, while ``guppylang.std.random`` is a native Guppy implementation. |
There was a problem hiding this comment.
Super nit: You could define the RNG acronym explicitly the first time and then just use RNG throughout.
2 participants
Closes #165