# Quantum random numbers in Python
[](https://github.com/sbalian/quantum-random/actions/workflows/tests.yml)
[](https://pypi.org/project/quantum-random/)
[](https://pypistats.org/packages/quantum-random)
Use the [Python random module][pyrandom] with real quantum random numbers from
[ANU][anu]. The default pseudo-random generator is replaced by calls to
the ANU API.
## Usage
Import `qrandom` and use it like the standard `random` module. For example:
```python
>>> import qrandom
>>> qrandom.random()
0.15357449726583722
>>> qrandom.sample(range(10), 2)
[6, 4]
>>> qrandom.gauss(0.0, 1.0)
-0.8370871276247828
```
Alternatively, you can use the class `qrandom.QuantumRandom`. It has the same
interface as `random.Random`.
There is also a [NumPy][numpy] interface, although it is not fully tested:
```python
>>> from qrandom.numpy import quantum_rng
>>> qrng = quantum_rng()
>>> qrng.random((3, 3)) # use like numpy.random.default_rng()
array([[0.37220278, 0.24337193, 0.67534826],
[0.209068 , 0.25108681, 0.49201691],
[0.35894084, 0.72219929, 0.55388594]])
```
NumPy is supported using [RandomGen][randomgen].
## Installation
The minimum supported Python version is 3.9. Install with `pip`:
```bash
pip install -U quantum-random
```
If you want NumPy support:
```bash
pip install -U 'quantum-random[numpy]'
```
## First-time setup: setting your API key
ANU requires you to use an API key. You can get a free trial or pay for a key
[here][anupricing].
You can pass your key to `qrandom` in three ways:
1. By setting the environment variable `QRANDOM_API_KEY`.
2. By running the included command line utility `qrandom-init` to save your
key in `qrandom.ini` in a subdirectory of your home config directory
as specified by XDG, e.g., `/home/<your-username>/.config/qrandom/`.
3. By running `qrandom-init` to save your key in `qrandom.ini` in a directory
of your choice, and then specifying this directory by setting
`QRANDOM_CONFIG_DIR`.
If `QRANDOM_API_KEY` is set, its value is used as the API key and the
config file is not read. Otherwise, `qrandom` will look for the key
in the config directory. The config directory defaults to the XDG home config
and can be changed by setting `QRANDOM_CONFIG_DIR`.
## Pre-fetching batches
Batches of quantum numbers are fetched from the API as needed.
Each batch contains 1024 numbers. Use `qrandom.fill(n)` to fetch `n` batches
if you need to pre-fetch at the start of your computation.
## Tests
The tests run for Python 3.9 - 3.12 on the latest Windows,
macOS and Ubuntu runner images. Use [tox][tox] to run the tests locally.
See [here](./analysis/uniform.md) for a visualisation and a Kolmogorov–Smirnov
test.
## Notes on implementation
The `qrandom` module exposes a class derived from `random.Random` with a
`random()` method that outputs quantum floats in the range [0, 1)
(converted from 64-bit integers). Overriding `random.Random.random`
is sufficient to make the `qrandom` module behave mostly like the
`random` module as described in the [Python docs][pyrandom]. The exceptions
are `getrandbits()` and `randbytes()`: these are not available in
`qrandom`. Because `getrandbits()` is not available, `randrange()` cannot
produce arbitrarily long sequences. Finally, the user is warned when `seed()`
is called because the quantum generator has no state. For the same reason,
`getstate()` and `setstate()` are not implemented.
## License
See [LICENCE](./LICENSE).
[anu]: https://quantumnumbers.anu.edu.au
[anupricing]: https://quantumnumbers.anu.edu.au/pricing
[pyrandom]: https://docs.python.org/3/library/random.html
[tox]: https://tox.wiki/en/latest/
[numpy]: https://numpy.org
[randomgen]: https://github.com/bashtage/randomgen
Raw data
{
"_id": null,
"home_page": "https://github.com/sbalian/quantum-random/",
"name": "quantum-random",
"maintainer": "Seto Balian",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "seto.balian@gmail.com",
"keywords": "quantum,random,statistics",
"author": "Seto Balian",
"author_email": "seto.balian@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/93/08/3c68ea0aa47b7067d096a37b46bd592a7f203ae4d7890fc0e383c33759a4/quantum_random-1.4.0.tar.gz",
"platform": null,
"description": "# Quantum random numbers in Python\n\n[](https://github.com/sbalian/quantum-random/actions/workflows/tests.yml)\n[](https://pypi.org/project/quantum-random/)\n\n[](https://pypistats.org/packages/quantum-random)\n\n\nUse the [Python random module][pyrandom] with real quantum random numbers from\n[ANU][anu]. The default pseudo-random generator is replaced by calls to\nthe ANU API.\n\n## Usage\n\nImport `qrandom` and use it like the standard `random` module. For example:\n\n```python\n>>> import qrandom\n\n>>> qrandom.random()\n0.15357449726583722\n\n>>> qrandom.sample(range(10), 2)\n[6, 4]\n\n>>> qrandom.gauss(0.0, 1.0)\n-0.8370871276247828\n```\n\nAlternatively, you can use the class `qrandom.QuantumRandom`. It has the same\ninterface as `random.Random`.\n\nThere is also a [NumPy][numpy] interface, although it is not fully tested:\n\n```python\n>>> from qrandom.numpy import quantum_rng\n\n>>> qrng = quantum_rng()\n\n>>> qrng.random((3, 3)) # use like numpy.random.default_rng()\narray([[0.37220278, 0.24337193, 0.67534826],\n [0.209068 , 0.25108681, 0.49201691],\n [0.35894084, 0.72219929, 0.55388594]])\n```\n\nNumPy is supported using [RandomGen][randomgen].\n\n## Installation\n\nThe minimum supported Python version is 3.9. Install with `pip`:\n\n```bash\npip install -U quantum-random\n```\n\nIf you want NumPy support:\n\n```bash\npip install -U 'quantum-random[numpy]'\n```\n\n## First-time setup: setting your API key\n\nANU requires you to use an API key. You can get a free trial or pay for a key\n[here][anupricing].\n\nYou can pass your key to `qrandom` in three ways:\n\n1. By setting the environment variable `QRANDOM_API_KEY`.\n2. By running the included command line utility `qrandom-init` to save your\nkey in `qrandom.ini` in a subdirectory of your home config directory\nas specified by XDG, e.g., `/home/<your-username>/.config/qrandom/`.\n3. By running `qrandom-init` to save your key in `qrandom.ini` in a directory\nof your choice, and then specifying this directory by setting\n`QRANDOM_CONFIG_DIR`.\n\nIf `QRANDOM_API_KEY` is set, its value is used as the API key and the\nconfig file is not read. Otherwise, `qrandom` will look for the key\nin the config directory. The config directory defaults to the XDG home config\nand can be changed by setting `QRANDOM_CONFIG_DIR`.\n\n## Pre-fetching batches\n\nBatches of quantum numbers are fetched from the API as needed.\nEach batch contains 1024 numbers. Use `qrandom.fill(n)` to fetch `n` batches\nif you need to pre-fetch at the start of your computation.\n\n## Tests\n\nThe tests run for Python 3.9 - 3.12 on the latest Windows,\nmacOS and Ubuntu runner images. Use [tox][tox] to run the tests locally.\n\nSee [here](./analysis/uniform.md) for a visualisation and a Kolmogorov\u2013Smirnov\ntest.\n\n## Notes on implementation\n\nThe `qrandom` module exposes a class derived from `random.Random` with a\n`random()` method that outputs quantum floats in the range [0, 1)\n(converted from 64-bit integers). Overriding `random.Random.random`\nis sufficient to make the `qrandom` module behave mostly like the\n`random` module as described in the [Python docs][pyrandom]. The exceptions\nare `getrandbits()` and `randbytes()`: these are not available in\n`qrandom`. Because `getrandbits()` is not available, `randrange()` cannot\nproduce arbitrarily long sequences. Finally, the user is warned when `seed()`\nis called because the quantum generator has no state. For the same reason,\n`getstate()` and `setstate()` are not implemented.\n\n## License\n\nSee [LICENCE](./LICENSE).\n\n[anu]: https://quantumnumbers.anu.edu.au\n[anupricing]: https://quantumnumbers.anu.edu.au/pricing\n[pyrandom]: https://docs.python.org/3/library/random.html\n[tox]: https://tox.wiki/en/latest/\n[numpy]: https://numpy.org\n[randomgen]: https://github.com/bashtage/randomgen\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Quantum random numbers",
"version": "1.4.0",
"project_urls": {
"Homepage": "https://github.com/sbalian/quantum-random/",
"Repository": "https://github.com/sbalian/quantum-random/"
},
"split_keywords": [
"quantum",
"random",
"statistics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f15b7636ad6c4c7f0abb2a489fe9f868af2696ea9a6a051f740091ec36d3b14c",
"md5": "15786caf7f67de42bd9b90ee98131c33",
"sha256": "692c5ba6adc6f310d4b6614fc9b61911cc5a72965dd2e99770ba7f2e15835d5f"
},
"downloads": -1,
"filename": "quantum_random-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "15786caf7f67de42bd9b90ee98131c33",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 8863,
"upload_time": "2024-02-25T22:21:18",
"upload_time_iso_8601": "2024-02-25T22:21:18.050947Z",
"url": "https://files.pythonhosted.org/packages/f1/5b/7636ad6c4c7f0abb2a489fe9f868af2696ea9a6a051f740091ec36d3b14c/quantum_random-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "93083c68ea0aa47b7067d096a37b46bd592a7f203ae4d7890fc0e383c33759a4",
"md5": "6c05e3f3d50d005ca793acaa128eebf5",
"sha256": "a4e2eb840c223529a404ca3eafc78e96a0057ee6d129cbe160cfea25537db2be"
},
"downloads": -1,
"filename": "quantum_random-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "6c05e3f3d50d005ca793acaa128eebf5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 7159,
"upload_time": "2024-02-25T22:21:19",
"upload_time_iso_8601": "2024-02-25T22:21:19.828250Z",
"url": "https://files.pythonhosted.org/packages/93/08/3c68ea0aa47b7067d096a37b46bd592a7f203ae4d7890fc0e383c33759a4/quantum_random-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-25 22:21:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sbalian",
"github_project": "quantum-random",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "quantum-random"
}
JSON
