Welcome to Qoin’s documentation!

class qoin.QRNG

QRNG class provides random number generation using quantum computing.

Methods

choice(items)

Choose a random element from the list of items.

choices(items, num_selections)

Choose random element(s) from the list of items.

randbin()

Generate a random boolean.

randint(lowerbound, upperbound)

Generate a random integer from [lowerbound, upperbound).

random(num_digits)

Generate a random float between 0 and 1.

sample(items, num_selections)

Choose random element(s) from the list of items.

shuffle(items)

Shuffle the list of items.
choice(items: MutableSequence[Any]) → Any

Choose a random element from the list of items.

Parameters:
`items`MutableSequence[Any]

The list of items.

Returns:
Any

The item selected.

Raises:
TypeError

If the items are not an instance of MutableSequence.

Notes

The random element is selected using the quantum circuit. The quantum circuit generates a uniform distribution over all possible elements in the list. The distribution is then measured to extract the random element.

The random element is selected using the following steps:

  1. Create a uniform distribution over all possible elements.

  2. Apply measurement to the distribution.

  3. Extract the quasi-probability distribution from the result.

  4. Convert the quasi-probability distribution to counts.

  5. Postprocess the measurement result.

  6. Return the random element.

Examples

>>> random_choice = qrng.choice([1, 2, 3, 4, 5])
>>> random_choice in [1, 2, 3, 4, 5]
True
>>> qrng.choice(1)
Traceback (most recent call last):
    ...
TypeError: Population must be a MutableSequence.
choices(items: MutableSequence[Any], num_selections: int) → Any | list[Any]

Choose random element(s) from the list of items.

Parameters:
`items`MutableSequence[Any]

The list of items.

`num_selections`int

The number of selections.

Returns:
Any | list[Any]

The item(s) selected.

Raises:
TypeError

If the items are not MutableSequence.

ValueError

If the number of selections is less than or equal to 0.

Notes

The random element(s) are selected using the quantum circuit. The quantum circuit generates a uniform distribution over all possible elements in the list. The distribution is then measured to extract the random element(s).

The random element(s) are selected using the following steps:

  1. Calculate the number of selections.

  2. Create a uniform distribution over all possible elements.

  3. Apply measurement to the distribution.

  4. Extract the quasi-probability distribution from the result.

  5. Convert the quasi-probability distribution to counts.

  6. Postprocess the measurement result.

  7. Return the random element(s).

Examples

>>> random_choices = qrng.choices([1, 2, 3, 4, 5], 3)
>>> all(random_choice in [1, 2, 3, 4, 5] for random_choice in random_choices)
True
>>> qrng.choices(1, 3)
Traceback (most recent call last):
    ...
TypeError: Population must be a MutableSequence.
>>> qrng.choices([1, 2, 3, 4, 5], 0)
Traceback (most recent call last):
    ...
ValueError: Sample larger than population or is negative.
randbin() → bool

Generate a random boolean.

Returns:
`random_bin`bool

The random boolean.

Notes

The random boolean is generated using the quantum circuit. The quantum circuit generates a uniform distribution over all possible booleans. The distribution is then measured to extract the random boolean.

The random boolean is generated using the following steps:

  1. Create a uniform distribution over all possible booleans.

  2. Apply measurement to the distribution.

  3. Extract the quasi-probability distribution from the result.

  4. Convert the quasi-probability distribution to counts.

  5. Postprocess the measurement result.

  6. Return the random boolean.

Examples

>>> random_bool = qrng.randbin()
>>> type_checker = isinstance(random_bool, bool)
>>> bound_checker = random_bool == True or random_bool == False
>>> type_checker and bound_checker
True
randint(lowerbound: int, upperbound: int) → int

Generate a random integer from [lowerbound, upperbound).

Parameters:
`lowerbound`int

The lowerbound of the selection.

`upperbound`int

The upperbound of the selection.

Returns:
`return_int`int

The random number generated from the selection.

Raises:
TypeError

If the lowerbound and upperbound are not integers.

ValueError

If the upperbound is less than the lowerbound.

Notes

The random integer is generated using the quantum circuit. The quantum circuit generates a uniform distribution over all possible integers between the lowerbound and upperbound. The distribution is then measured to extract the random integer.

The random integer is generated using the following steps:

  1. Calculate the difference between the upperbound and lowerbound.

  2. Scale the difference to the closest power of 2.

  3. Calculate the number of qubits needed to represent the selection.

  4. Create a uniform distribution over all possible integers.

  5. Apply measurement to the distribution.

  6. Extract the quasi-probability distribution from the result.

  7. Convert the quasi-probability distribution to counts.

  8. Postprocess the measurement result.

  9. Scale the integer back.

  10. Shift range from [0;upperbound-lowerbound-1] to [lowerbound;upperbound-1].

  11. Return the random integer.

random(num_digits: int) → float

Generate a random float between 0 and 1.

Parameters:
`num_digits`int

The number of bits used to represent the angle divider.

Returns:
`random_float`float

The random generated float.

Raises:
TypeError

If the number of digits is not an integer.

ValueError

If the number of digits is less than or equal to 0.

Notes

The random float is generated using the quantum circuit. The quantum circuit generates a uniform distribution over all possible floats between 0 and 1. The distribution is then measured to extract the random float.

The random float is generated using the following steps:

  1. Calculate the number of bits used to represent the angle divider.

  2. Create a uniform distribution over all possible floats.

  3. Apply measurement to the distribution.

  4. Extract the quasi-probability distribution from the result.

  5. Convert the quasi-probability distribution to counts.

  6. Postprocess the measurement result.

  7. Return the random float.

Examples

>>> random_float = qrng.random(5)
>>> type_checker = isinstance(random_float, float)
>>> bound_checker = random_float < 1 and random_float >= 0
>>> bound_checker = bound_checker and len(str(random_float)) == 7
>>> type_checker and bound_checker
True
>>> qrng.random(3.2)
Traceback (most recent call last):
    ...
TypeError: Number of digits must be an integer.
>>> qrng.random(0)
Traceback (most recent call last):
    ...
ValueError: Number of digits must be greater than 0.
sample(items: MutableSequence[Any], num_selections: int) → Any | list[Any]

Choose random element(s) from the list of items.

Parameters:
`items`MutableSequence[Any]

The list of items.

`num_selections`int

The number of selections.

Returns:
Any | list[Any]

The item(s) selected.

Raises:
TypeError

If the items are not MutableSequence.

ValueError

If the number of selections is less than or equal to 0.

Notes

The random element(s) are selected using the quantum circuit. The quantum circuit generates a uniform distribution over all possible elements in the list. The distribution is then measured to extract the random element(s).

The random element(s) are selected using the following steps:

  1. Calculate the number of selections.

  2. Create a uniform distribution over all possible elements.

  3. Apply measurement to the distribution.

  4. Extract the quasi-probability distribution from the result.

  5. Convert the quasi-probability distribution to counts.

  6. Postprocess the measurement result.

  7. Return the random element(s).

Examples

>>> random_samples = qrng.sample([1, 2, 3, 4, 5], 3)
>>> bound_checker = all(random_sample in [1, 2, 3, 4, 5]
... for random_sample in random_samples)
>>> unique_checker = len(set(random_samples)) == 3
>>> bound_checker and unique_checker
True
>>> qrng.sample(1, 3)
Traceback (most recent call last):
    ...
TypeError: Population must be a MutableSequence.
>>> qrng.sample([1, 2, 3, 4, 5], 6)
Traceback (most recent call last):
    ...
ValueError: Sample larger than population or is negative.
shuffle(items: MutableSequence[Any]) → list[Any]

Shuffle the list of items.

Parameters:
`items`list[Any]

The list of items to shuffle.

Returns:
list[Any]

The shuffled list of items.

Raises:
TypeError

If the items are not a list.

Notes

The list of items is shuffled using the quantum circuit. The quantum circuit generates a uniform distribution over all possible permutations of the list. The distribution is then measured to extract the random permutation.

The list of items is shuffled using the following steps:

  1. Create a uniform distribution over all possible permutations.

  2. Apply measurement to the distribution.

  3. Extract the quasi-probability distribution from the result.

  4. Convert the quasi-probability distribution to counts.

  5. Postprocess the measurement result.

  6. Return the shuffled list of items.

Examples

>>> shuffled = qrng.shuffle([1, 2, 3, 4, 5])
>>> len(set(shuffled)) == 5
True
>>> qrng.shuffle(1)
Traceback (most recent call last):
    ...
TypeError: Population must be a MutableSequence.