general-purpose quantization. includes [directed rounding](https://en.wikipedia.org/wiki/Rounding#Directed_rounding_to_an_integer), [tie-breaking rounding](https://en.wikipedia.org/wiki/Rounding#Rounding_to_the_nearest_integer), [randomized rounding](https://en.wikipedia.org/wiki/Rounding#Randomized_rounding_to_an_integer), [truncation](https://en.wikipedia.org/wiki/Truncation), [rounding to multiples](https://en.wikipedia.org/wiki/Rounding#Rounding_to_a_specified_multiple), [negative zeroes](https://en.wikipedia.org/wiki/Rounding#Negative_zero_in_meteorology), and a bit more!
# how to install
```shell
pip install pyquantize
```
# how to use
there is only one function in the module: `quantize`
import it like so:
```python
from pyquantize import quantize
quantize(3.14, 0.8)
# 3.2
```
usage:
```python
quantize(number,
quantum = 1,
offset = 0,
centre = 0,
threshold = 0.5,
directed = False,
signed_zero = True,
mode = 'even')
```
number: an `int` or a `float` type. no default. the number to be quantized
quantum: an `int` or a `float` type. default is 1. the number will be quantized to multiples of this quantum. `quantize(x, quantum=0.7)` will snap the number to […, -1.4, -0.7, 0, 0.7, 1.4, …]
offset: an `int` or a `float` type. default is 0. the quantization grid will be offset by this amount. `quantize(x, quantum=0.7, offset=0.2)` will change the grid from […, -1.4, -0.7, 0, 0.7, 1.4, …] to […, -1.2, -0.5, 0.2, 0.9, 1.6, …]
centre: an `int` or a `float` type. default is 0. affects `'towards'` and `'away'` modes. `quantize(x, centre=float('inf'), mode='towards')` is the same as `quantize(x, mode='ceil')`. `quantize(x, centre=float('-inf'), mode='towards')` is the same as `quantize(x, mode='floor')`
similarly so for `mode='away'`
threshold an `int` or a `float` type. default is 0.5. must satisfy 0 ≤ threshold ≤ 1. it determines the percentage at which the number is rounded up or down
directed: a `bool` type. default is False. if False, `mode` is only applied for ties (where the number is exactly between multiples of quantum, like 0.5 between 0 and 1). if True, `mode` is *always* applied
signed_zero: a `bool` type. default is True. if True, whenever the result is zero, it shows whether it was rounded from the negative or positive side. for example, -0.1 rounds to -0.0 instead of 0.0. if False, this rounds to 0.0 as usual
mode: a `str` type. default is 'even'. determines the method for quantization. options are:
`'threshold'` - quantize down if the fractional part is less than threshold
`'floor'` - quantize down towards -∞
`'ceil'` - quantize up towards +∞
`'towards'` - quantize towards centre
`'away'` - quantize away from centre
`'even'` - quantize towards nearest even multiple (default)
`'odd'` - quantize towards nearest odd multiple
`'alternate'` - quantize up or down alternately according to quantize.alternate_last
`'random'` - quantize up or down randomly
`'stochastic'` - quantize up or down according to stochastic probability
`'alternate'`, `'random'`, `'stochastic'` are [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorthm)
when mode is `'alternate'`, the last state is remembered as an attribute of the function, which you can access as `quantize.alternate_last` (a bool type)
(this function may occasionally round to unexpected results, due to [floating point imprecision](https://en.wikipedia.org/wiki/Floating-point_arithmetic))
# tidbits
to simulate rounding, try:
```python
def qround(number, digits=0, *args, **kwargs):
return quantize(number, quantum=10**-digits, *args, **kwargs)
print(qround(2.34, 1, directed=True, mode='stochastic'))
# 2.3 or 2.4
```
unlike python's `round`, you can even round a number to a non-integer amount of digits!
```
print(qround(2.34, 1.5))
# 2.2135943621178655
```
to simulate rounded division, try:
```python
def qdivmod(dividend, divisor, *args, **kwargs):
result = quantize(dividend/divisor, *args, **kwargs)
return result, dividend-result*divisor
print(qdivmod(2.34, 1, directed=True, mode='stochastic'))
# (1, 1.0) or (2, -0.5)
```
stochastic division! neat huh?? or try even-rounded integer division:
```
print(qdivmod(3, 2, mode='even'))
# (2, -1)
print(qdivmod(4, 2, mode='even'))
# (2, 0)
print(qdivmod(5, 2, mode='even'))
# (2, 1)
```
or check that stochastic mode works:
```python
count = 0
for i in range(10**5):
count += quantize(0.9, directed=True, mode='stochastic')
print(count/10**5)
# ≈0.9
```
(psst! these functions arent actually defined in pyquantize. just fun little trinkets. or you can ask me if youd like them to be included!)
# how to uninstall
```shell
pip uninstall pyquantize
```
# the end ~
if you can help me port this to other languages, ~~i~~ *the open-source community* would be super grateful! :)
and if you liked this, please please give me a star it really helps
Raw data
{
"_id": null,
"home_page": null,
"name": "pyquantize",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6.0",
"maintainer_email": null,
"keywords": "quantize, rounding, stochastic, python, math",
"author": null,
"author_email": "deftasparagusanaconda <deftasparagusanaconda@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/20/2d/39331907c699d1451d21f37453fd90bcc9973af51883b8dc9796b44f5bce/pyquantize-0.1.0.tar.gz",
"platform": null,
"description": "general-purpose quantization. includes [directed rounding](https://en.wikipedia.org/wiki/Rounding#Directed_rounding_to_an_integer), [tie-breaking rounding](https://en.wikipedia.org/wiki/Rounding#Rounding_to_the_nearest_integer), [randomized rounding](https://en.wikipedia.org/wiki/Rounding#Randomized_rounding_to_an_integer), [truncation](https://en.wikipedia.org/wiki/Truncation), [rounding to multiples](https://en.wikipedia.org/wiki/Rounding#Rounding_to_a_specified_multiple), [negative zeroes](https://en.wikipedia.org/wiki/Rounding#Negative_zero_in_meteorology), and a bit more!\n\n# how to install\n\n```shell\npip install pyquantize\n```\n\n# how to use\n\nthere is only one function in the module: `quantize` \nimport it like so:\n\n```python\nfrom pyquantize import quantize\n\nquantize(3.14, 0.8)\n# 3.2\n```\n\nusage:\n```python\nquantize(number,\n\t\tquantum = 1,\n\t\toffset = 0,\n\t\tcentre = 0,\n\t\tthreshold = 0.5,\n\t\tdirected = False,\n\t\tsigned_zero = True,\n\t\tmode = 'even')\n```\n\nnumber: an `int` or a `float` type. no default. the number to be quantized\n\nquantum: an `int` or a `float` type. default is 1. the number will be quantized to multiples of this quantum. `quantize(x, quantum=0.7)` will snap the number to [\u2026, -1.4, -0.7, 0, 0.7, 1.4, \u2026]\n\noffset: an `int` or a `float` type. default is 0. the quantization grid will be offset by this amount. `quantize(x, quantum=0.7, offset=0.2)` will change the grid from [\u2026, -1.4, -0.7, 0, 0.7, 1.4, \u2026] to [\u2026, -1.2, -0.5, 0.2, 0.9, 1.6, \u2026]\n\ncentre: an `int` or a `float` type. default is 0. affects `'towards'` and `'away'` modes. `quantize(x, centre=float('inf'), mode='towards')` is the same as `quantize(x, mode='ceil')`. `quantize(x, centre=float('-inf'), mode='towards')` is the same as `quantize(x, mode='floor')`\nsimilarly so for `mode='away'`\n\nthreshold an `int` or a `float` type. default is 0.5. must satisfy 0 \u2264 threshold \u2264 1. it determines the percentage at which the number is rounded up or down\n\ndirected: a `bool` type. default is False. if False, `mode` is only applied for ties (where the number is exactly between multiples of quantum, like 0.5 between 0 and 1). if True, `mode` is *always* applied\n\nsigned_zero: a `bool` type. default is True. if True, whenever the result is zero, it shows whether it was rounded from the negative or positive side. for example, -0.1 rounds to -0.0 instead of 0.0. if False, this rounds to 0.0 as usual\n\nmode: a `str` type. default is 'even'. determines the method for quantization. options are: \n`'threshold'` - quantize down if the fractional part is less than threshold \n`'floor'` - quantize down towards -\u221e \n`'ceil'` - quantize up towards +\u221e \n`'towards'` - quantize towards centre \n`'away'` - quantize away from centre \n`'even'` - quantize towards nearest even multiple (default) \n`'odd'` - quantize towards nearest odd multiple \n`'alternate'` - quantize up or down alternately according to quantize.alternate_last \n`'random'` - quantize up or down randomly \n`'stochastic'` - quantize up or down according to stochastic probability \n\n`'alternate'`, `'random'`, `'stochastic'` are [non-deterministic](https://en.wikipedia.org/wiki/Nondeterministic_algorthm)\n\nwhen mode is `'alternate'`, the last state is remembered as an attribute of the function, which you can access as `quantize.alternate_last` (a bool type)\n\n(this function may occasionally round to unexpected results, due to [floating point imprecision](https://en.wikipedia.org/wiki/Floating-point_arithmetic))\n\n# tidbits \n\nto simulate rounding, try: \n```python\ndef qround(number, digits=0, *args, **kwargs):\n\treturn quantize(number, quantum=10**-digits, *args, **kwargs)\n\nprint(qround(2.34, 1, directed=True, mode='stochastic'))\n# 2.3 or 2.4\n```\nunlike python's `round`, you can even round a number to a non-integer amount of digits!\n```\nprint(qround(2.34, 1.5))\n# 2.2135943621178655\n```\n\nto simulate rounded division, try:\n```python\ndef qdivmod(dividend, divisor, *args, **kwargs):\n\tresult = quantize(dividend/divisor, *args, **kwargs)\n\treturn result, dividend-result*divisor\n\nprint(qdivmod(2.34, 1, directed=True, mode='stochastic'))\n# (1, 1.0) or (2, -0.5)\n\n```\nstochastic division! neat huh?? or try even-rounded integer division:\n\n```\nprint(qdivmod(3, 2, mode='even'))\n# (2, -1)\nprint(qdivmod(4, 2, mode='even'))\n# (2, 0)\nprint(qdivmod(5, 2, mode='even'))\n# (2, 1)\n```\n\nor check that stochastic mode works:\n\n```python\ncount = 0\nfor i in range(10**5):\n\tcount += quantize(0.9, directed=True, mode='stochastic')\n\nprint(count/10**5)\n# \u22480.9\n```\n\n(psst! these functions arent actually defined in pyquantize. just fun little trinkets. or you can ask me if youd like them to be included!)\n\n# how to uninstall\n\n```shell\npip uninstall pyquantize\n```\n\n# the end ~\nif you can help me port this to other languages, ~~i~~ *the open-source community* would be super grateful! :) \nand if you liked this, please please give me a star it really helps\n",
"bugtrack_url": null,
"license": null,
"summary": "general-purpose quantization",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/YOUR_USERNAME/pyquantize#readme",
"Homepage": "https://github.com/deftasparagusanaconda/pyquantize",
"Repository": "https://github.com/deftasparagusanaconda/pyquantize"
},
"split_keywords": [
"quantize",
" rounding",
" stochastic",
" python",
" math"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3795c025954a2c179596711797248dd4108f83ce425a22cf5b50b379cedb1637",
"md5": "eef80c750c0da7c4149a317292c1a214",
"sha256": "a2c8a1a7007baaa5577c11cf85826cd2b17b2beeccf1edeb58d05fd31b76b9fb"
},
"downloads": -1,
"filename": "pyquantize-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eef80c750c0da7c4149a317292c1a214",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6.0",
"size": 17213,
"upload_time": "2025-08-28T17:36:38",
"upload_time_iso_8601": "2025-08-28T17:36:38.235350Z",
"url": "https://files.pythonhosted.org/packages/37/95/c025954a2c179596711797248dd4108f83ce425a22cf5b50b379cedb1637/pyquantize-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "202d39331907c699d1451d21f37453fd90bcc9973af51883b8dc9796b44f5bce",
"md5": "7c77268518960c18136791b43839497f",
"sha256": "b718248d7d2bded602f0e5b41c5a068de3cd778a43f2c6e7696bbe5c516efc2d"
},
"downloads": -1,
"filename": "pyquantize-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "7c77268518960c18136791b43839497f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.0",
"size": 16806,
"upload_time": "2025-08-28T17:36:40",
"upload_time_iso_8601": "2025-08-28T17:36:40.396992Z",
"url": "https://files.pythonhosted.org/packages/20/2d/39331907c699d1451d21f37453fd90bcc9973af51883b8dc9796b44f5bce/pyquantize-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 17:36:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "YOUR_USERNAME",
"github_project": "pyquantize#readme",
"github_not_found": true,
"lcname": "pyquantize"
}
JSON
