# [Collatz](https://github.com/Skenvy/Collatz): [Python](https://github.com/Skenvy/Collatz/tree/main/python) 🐍🐍🐍
Functions related to [the Collatz/Syracuse/3N+1 problem](https://en.wikipedia.org/wiki/Collatz_conjecture), implemented in [Python](https://www.python.org/).
## Getting Started
[To install the latest from pypi](https://pypi.org/project/collatz/);
```sh
pip install collatz
```
## Usage
Provides the basic functionality to interact with the Collatz conjecture.
The parameterisation uses the same `(P,a,b)` notation as Conway's generalisations.
Besides the function and reverse function, there is also functionality to retrieve the hailstone sequence, the "stopping time"/"total stopping time", or tree-graph.
The only restriction placed on parameters is that both `P` and `a` can't be `0`.
### collatz.function(~)
`(n:int, P:int=2, a:int=3, b:int=1)`
```python
>>> import collatz
>>> # The default "Collatz function"
>>> collatz.function(5)
16
>>> # Alternatively, you can parameterise the function.
>>> collatz.function(5, P=7, a=5, b=17)
42
```
### collatz.reverse_function(~)
`(n:int, P:int=2, a:int=3, b:int=1)`
```python
>>> import collatz
>>> # Get the list of values that return the input.
>>> collatz.reverse_function(4)
[1, 8]
>>> # Alternatively, you can parameterise the reverse_function.
>>> collatz.reverse_function(5, P=5, a=2, b=3)
[1, 25]
```
### collatz.hailstone_sequence(~)
`(initial_value:int, P:int=2, a:int=3, b:int=1, max_total_stopping_time:int=1000, total_stopping_time:bool=True, verbose:bool=True)`
```python
>>> import collatz
>>> # Get the sequence of values forming the hailstone from an initial value
>>> collatz.hailstone_sequence(10)
[10, 5, 16, 8, 4, 2, 1, ['TOTAL_STOPPING_TIME', 6]]
>>> # Determines if it's in a cycle
>>> collatz.hailstone_sequence(-56)
[-56, -28, 'CYCLE_INIT', [-14, -7, -20, -10, -5], ['CYCLE_LENGTH', 5]]
>>> # The verbose messages can be muted, although this might leave a sense of ambiguity for larger lists.
>>> collatz.hailstone_sequence(-200, verbose=False)
[-200, -100, -50, -25, -74, -37, -110, -55, -164, -82, -41, -122, -61, -182, -91, -272, -136, -68, -34, -17, -50]
>>> # Although hailstones typically go to the "total stop" of 1, they can be set to terminate on the regular stop
>>> collatz.hailstone_sequence(5, total_stopping_time=False)
[5, 16, 8, 4, ['STOPPING_TIME', 3]]
```
### collatz.stopping_time(~)
`(initial_value:int, P:int=2, a:int=3, b:int=1, max_stopping_time:int=1000, total_stopping_time:bool=False)`
```python
>>> import collatz
>>> # Reports the stopping time, the amount of iterations of the function to reach a value lower than the initial value.
>>> collatz.stopping_time(5)
3
>>> # Can be used to find the "total stopping time" as well, the amount of iterations to reach "1"
>>> collatz.stopping_time(5, total_stopping_time=True)
5
>>> # Although most cylces have a stopping time, by targetting the total stopping time, you can see if a value leads into a cycle by the 'inf' return
>>> collatz.stopping_time(-17, total_stopping_time=True)
inf
>>> # Some cycles are small enough that starting on the lowest absolute value will still identify a cycle.
>>> collatz.stopping_time(-1)
inf
>>> # If it overruns maximum stopping time, returns nothing.
>>> collatz.stopping_time(5, max_stopping_time=-1)
>>> # <None>
```
### collatz.tree_graph(~)
`(initial_value:int, max_orbit_distance:int, P:int=2, a:int=3, b:int=1)`
```python
>>> import collatz
>>> # See the tree graph built by a reverse function traversal, to the depth specified by max_orbit_distance.
>>> collatz.tree_graph(1, 3)
{1: {2: {4: {'CYCLE_INIT': 1, 8: {}}}}}
>>> collatz.tree_graph(1, 12)
{1: {2: {4: {'CYCLE_INIT': 1, 8: {16: {5: {10: {3: {6: {12: {24: {48: {96: {}}}}}}, 20: {40: {13: {26: {52: {17: {}, 104: {}}}}, 80: {160: {53: {106: {}}, 320: {640: {}}}}}}}}, 32: {64: {21: {42: {84: {168: {336: {672: {}}}}}}, 128: {256: {85: {170: {340: {113: {}, 680: {}}}}, 512: {1024: {341: {682: {}}, 2048: {4096: {}}}}}}}}}}}}}}
>>> # Can also be parameterised;
>>> collatz.tree_graph(1, 2, P=5, a=2, b=3)
{1: {-1: {-5: {}, -2: {}}, 5: {'CYCLE_INIT': 1, 25: {}}}}
```
## [Sphinx+MyST generated docs](https://skenvy.github.io/Collatz/python/)
## Developing
### The first time setup
```
git clone https://github.com/Skenvy/Collatz.git && cd Collatz/python && make venv
```
### Iterative development
* `make build` will test and build the wheel and force reinstall it into the local venv, to test the built distribution
## [Open Source Insights](https://deps.dev/pypi/collatz)
Raw data
{
"_id": null,
"home_page": "https://github.com/Skenvy/Collatz",
"name": "collatz",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "Collatz,Ulam,Kakutani's,Thwaites,Hasse's,Syracus",
"author": "Skenvy",
"author_email": "nathan.a.z.levett@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e8/5e/aef18d071fd2b1bc49550ef16c95a657ae8415c5a9f984c683ea11063ada/collatz-1.0.1.tar.gz",
"platform": null,
"description": "# [Collatz](https://github.com/Skenvy/Collatz): [Python](https://github.com/Skenvy/Collatz/tree/main/python) \ud83d\udc0d\ud83d\udc0d\ud83d\udc0d\nFunctions related to [the Collatz/Syracuse/3N+1 problem](https://en.wikipedia.org/wiki/Collatz_conjecture), implemented in [Python](https://www.python.org/).\n## Getting Started\n[To install the latest from pypi](https://pypi.org/project/collatz/);\n```sh\npip install collatz\n```\n## Usage\nProvides the basic functionality to interact with the Collatz conjecture.\nThe parameterisation uses the same `(P,a,b)` notation as Conway's generalisations.\nBesides the function and reverse function, there is also functionality to retrieve the hailstone sequence, the \"stopping time\"/\"total stopping time\", or tree-graph. \nThe only restriction placed on parameters is that both `P` and `a` can't be `0`.\n### collatz.function(~)\n`(n:int, P:int=2, a:int=3, b:int=1)`\n```python\n>>> import collatz\n>>> # The default \"Collatz function\"\n>>> collatz.function(5)\n16\n>>> # Alternatively, you can parameterise the function.\n>>> collatz.function(5, P=7, a=5, b=17)\n42\n```\n### collatz.reverse_function(~)\n`(n:int, P:int=2, a:int=3, b:int=1)`\n```python\n>>> import collatz\n>>> # Get the list of values that return the input.\n>>> collatz.reverse_function(4)\n[1, 8]\n>>> # Alternatively, you can parameterise the reverse_function.\n>>> collatz.reverse_function(5, P=5, a=2, b=3)\n[1, 25]\n```\n### collatz.hailstone_sequence(~)\n`(initial_value:int, P:int=2, a:int=3, b:int=1, max_total_stopping_time:int=1000, total_stopping_time:bool=True, verbose:bool=True)`\n```python\n>>> import collatz\n>>> # Get the sequence of values forming the hailstone from an initial value\n>>> collatz.hailstone_sequence(10)\n[10, 5, 16, 8, 4, 2, 1, ['TOTAL_STOPPING_TIME', 6]]\n>>> # Determines if it's in a cycle\n>>> collatz.hailstone_sequence(-56)\n[-56, -28, 'CYCLE_INIT', [-14, -7, -20, -10, -5], ['CYCLE_LENGTH', 5]]\n>>> # The verbose messages can be muted, although this might leave a sense of ambiguity for larger lists.\n>>> collatz.hailstone_sequence(-200, verbose=False)\n[-200, -100, -50, -25, -74, -37, -110, -55, -164, -82, -41, -122, -61, -182, -91, -272, -136, -68, -34, -17, -50]\n>>> # Although hailstones typically go to the \"total stop\" of 1, they can be set to terminate on the regular stop\n>>> collatz.hailstone_sequence(5, total_stopping_time=False)\n[5, 16, 8, 4, ['STOPPING_TIME', 3]]\n```\n### collatz.stopping_time(~)\n`(initial_value:int, P:int=2, a:int=3, b:int=1, max_stopping_time:int=1000, total_stopping_time:bool=False)`\n```python\n>>> import collatz\n>>> # Reports the stopping time, the amount of iterations of the function to reach a value lower than the initial value.\n>>> collatz.stopping_time(5)\n3\n>>> # Can be used to find the \"total stopping time\" as well, the amount of iterations to reach \"1\"\n>>> collatz.stopping_time(5, total_stopping_time=True)\n5\n>>> # Although most cylces have a stopping time, by targetting the total stopping time, you can see if a value leads into a cycle by the 'inf' return\n>>> collatz.stopping_time(-17, total_stopping_time=True)\ninf\n>>> # Some cycles are small enough that starting on the lowest absolute value will still identify a cycle.\n>>> collatz.stopping_time(-1)\ninf\n>>> # If it overruns maximum stopping time, returns nothing.\n>>> collatz.stopping_time(5, max_stopping_time=-1)\n>>> # <None>\n```\n### collatz.tree_graph(~)\n`(initial_value:int, max_orbit_distance:int, P:int=2, a:int=3, b:int=1)`\n```python\n>>> import collatz\n>>> # See the tree graph built by a reverse function traversal, to the depth specified by max_orbit_distance.\n>>> collatz.tree_graph(1, 3)\n{1: {2: {4: {'CYCLE_INIT': 1, 8: {}}}}}\n>>> collatz.tree_graph(1, 12)\n{1: {2: {4: {'CYCLE_INIT': 1, 8: {16: {5: {10: {3: {6: {12: {24: {48: {96: {}}}}}}, 20: {40: {13: {26: {52: {17: {}, 104: {}}}}, 80: {160: {53: {106: {}}, 320: {640: {}}}}}}}}, 32: {64: {21: {42: {84: {168: {336: {672: {}}}}}}, 128: {256: {85: {170: {340: {113: {}, 680: {}}}}, 512: {1024: {341: {682: {}}, 2048: {4096: {}}}}}}}}}}}}}}\n>>> # Can also be parameterised;\n>>> collatz.tree_graph(1, 2, P=5, a=2, b=3)\n{1: {-1: {-5: {}, -2: {}}, 5: {'CYCLE_INIT': 1, 25: {}}}}\n```\n## [Sphinx+MyST generated docs](https://skenvy.github.io/Collatz/python/)\n## Developing\n### The first time setup\n```\ngit clone https://github.com/Skenvy/Collatz.git && cd Collatz/python && make venv\n```\n### Iterative development\n* `make build` will test and build the wheel and force reinstall it into the local venv, to test the built distribution\n## [Open Source Insights](https://deps.dev/pypi/collatz)\n",
"bugtrack_url": null,
"license": "Apache Software License",
"summary": "Enabling experimenting with functions related to or involved in the Collatz conjecture.",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/Skenvy/Collatz/issues",
"Homepage": "https://github.com/Skenvy/Collatz"
},
"split_keywords": [
"collatz",
"ulam",
"kakutani's",
"thwaites",
"hasse's",
"syracus"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8991c35f885fd549a60f9b8199d45bafd4b387a2965a7ca599fcb385fd78f118",
"md5": "aa9f2bdc4ab5ba073e6f39b16a965c4d",
"sha256": "4c920a31ffbbfe1fb5821fd1e24b381abfbe4e166a65656d30c933d553c3895c"
},
"downloads": -1,
"filename": "collatz-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aa9f2bdc4ab5ba073e6f39b16a965c4d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 12208,
"upload_time": "2023-07-29T19:01:01",
"upload_time_iso_8601": "2023-07-29T19:01:01.571109Z",
"url": "https://files.pythonhosted.org/packages/89/91/c35f885fd549a60f9b8199d45bafd4b387a2965a7ca599fcb385fd78f118/collatz-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e85eaef18d071fd2b1bc49550ef16c95a657ae8415c5a9f984c683ea11063ada",
"md5": "4c1ef9c01d2d9c81ae5f4d71cc7b9bdb",
"sha256": "3e63622b0d06bb7ceb5231a21138988db8d5762b71daae7adb9a4660317eeeb3"
},
"downloads": -1,
"filename": "collatz-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "4c1ef9c01d2d9c81ae5f4d71cc7b9bdb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 18519,
"upload_time": "2023-07-29T19:01:03",
"upload_time_iso_8601": "2023-07-29T19:01:03.178362Z",
"url": "https://files.pythonhosted.org/packages/e8/5e/aef18d071fd2b1bc49550ef16c95a657ae8415c5a9f984c683ea11063ada/collatz-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-29 19:01:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Skenvy",
"github_project": "Collatz",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "collatz"
}
JSON
