*(Graph of the first 26 compressed Collatz sequences)*
# Syracuse
syracuse, The Syracuse problem (aka Collatz conjecture) library.
## About the project
The syracuse library provides a way to generate Collatz sequences (either "normal" or compressed forms) and some functions to deal with.
### The Collatz conjecture
The Collatz conjecture, also known as the "3n + 1 problem" or the "Syracuse problem", is an unsolved hypothesis in mathematics that concerns a sequence of operations applied to a positive integer. The conjecture states that no matter what the starting value of this integer is, the sequence will always eventually reach the value 1.
More specifically, the Collatz conjecture states that if one takes a positive integer n and applies the following function:
- If n is even, divide it by 2.
- If n is odd, multiply it by 3 and add 1.
Then, repeat the process with the resulting value, applying the function over and over again until the value of n eventually reaches 1.
> For example, if one takes n = 6, the sequence for the Collatz conjecture would be:
> 6, 3, 10, 5, 16, 8, 4, 2, 1.
Although the conjecture has been computationally tested for extremely large values, it remains unproven to this day.
### The compressed form
*(definition partially inspired by the [relevant article on Wikipedia](https://en.wikipedia.org/wiki/Collatz_conjecture))*
Since 3n+1 is even whenever n is odd, one may instead use the "compressed" form of the Collatz function:
- if n is even, divide it by 2.
- if n is odd, multiply it by 3, add 1 **and divide the result by 2**.
This definition yields smaller values for the stopping time and total stopping time without changing the overall dynamics of the process.
> For example, consider the Collatz sequence for the number 17:
> 17, 52, 26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1
>
> The compressed form of this sequence would be:
> 17, 26, 13, 20, 10, 5, 8, 4, 2, 1
The compressed form of the Collatz sequence has been the subject of much research, as it provides insights into the behavior of the original sequence and can be used to search for cycles and other patterns. However, the Collatz conjecture itself remains unproven, and the compressed form of the sequence does not provide a proof or disproof of the conjecture.
### Why the name "syracuse" ?
The Collatz conjecture is also known as the Syracuse problem because it was first introduced by Lothar Collatz in a 1950 paper, where he credited his colleague, mathematician Helmut Hasse, with calling it the Syracuse problem. The name "Syracuse" refers to the University of Syracuse, where Collatz was working at the time.
The name "Syracuse problem" has since become a common alternative to "Collatz conjecture", especially in French and Italian-speaking countries, where it is often referred to as the "problème de Syracuse" or "problema di Syracuse", respectively.
Regardless of the name used, the conjecture remains one of the most famous and challenging open problems in mathematics, and it continues to attract the attention of mathematicians and computer scientists around the world.
## Getting started
### Prerequisites
Of course, syracuse cannot run without Python ! More precisely, it requires at least the 3.11 version of our beloved language.
syracuse depends on the following packages. The installation of syracuse should install automatically those packages if they are missing on your system. If it fails, you can install them individually:
* networkx: version 3.0.0 or above
```sh
pip install networkx["default"]
```
* matplotlib: version 3.6.0 or above
```sh
pip install matplotlib
```
* numpy: version 1.24.0 or above
```sh
pip install numpy
```
* pydot: version 1.4.2 or above
```sh
pip install pydot
```
* more-itertools: version 9.1.0 or above
```sh
pip install more-itertools
```
### Installation
Install from PyPi with:
```sh
pip install syracuse
```
As an alternative, you can download the `*.whl` file from the last [release on the syracuse Github repository](https://github.com/devfred78/syracuse/releases), and execute the following command (replace "X.Y.Z" by the right version number):
```sh
pip install syracuse-X.Y.Z-py3-none-any.whl
```
## Usage
Basic usage:
```pycon
>>> # Import the core library
>>> import syracuse
>>> # Create a Syracuse sequence with 27 as initial value
>>> my_sequence = syracuse.Syracuse(27)
>>> # Stopping time
>>> my_sequence.stopping_time
96
>>> # Total stopping time
>>> my_sequence.total_stopping_time
111
>>> # Maximum reached value
>>> my_sequence.max
9232
>>> # Full sequence (until 1)
>>> my_sequence.total_stopping_sequence
(27, 82, 41, 124, 62, 31, 94, 47, 142, 71, 214, 107, 322, 161,
484, 242, 121, 364, 182, 91, 274, 137, 412, 206, 103, 310, 155,
466, 233, 700, 350, 175, 526, 263, 790, 395, 1186, 593, 1780,
890, 445, 1336, 668, 334, 167, 502, 251, 754, 377, 1132, 566,
283, 850, 425, 1276, 638, 319, 958, 479, 1438, 719, 2158, 1079,
3238, 1619, 4858, 2429, 7288, 3644, 1822, 911, 2734, 1367, 4102,
2051, 6154, 3077, 9232, 4616, 2308, 1154, 577, 1732, 866, 433,
1300, 650, 325, 976, 488, 244, 122, 61, 184, 92, 46, 23, 70, 35,
106, 53, 160, 80, 40, 20, 10, 5, 16, 8, 4, 2, 1)
>>> # Import the sequences library
>>> import syracuse.sequences
>>> # Create an iterator over the records of the max values (A006884)
>>> # with all possible optimizations
>>> max_records = syracuse.sequences.max_value_records(15)
>>> # Iterate over the first 30 records
>>> for _ in range(30):
... print(f"{next(max_records)}, ", end="", flush=True)
...
1, 2, 3, 7, 15, 27, 255, 447, 639, 703, 1819, 4255, 4591, 9663,
20895, 26623, 31911, 60975, 77671, 113383, 138367, 159487, 270271,
665215, 704511, 1042431, 1212415, 1441407, 1875711, 1988859,
>>> # Import the drawing library
>>> import syracuse.drawing
>>> # Display the full sequence in a Matplotlib window
>>> syracuse.drawing.single_sequence_to_matplotlib_figure(my_sequence, test=True)
```
For deeper explanations, please refer to the [documentation](https://devfred78.github.io/syracuse/).
## Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement" or "bug", according to whether you want to share a proposal of a new function, or to record an anomaly.
Don't forget to give the project a star! Thanks again!
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
Distributed under the MIT License. Check out [LICENSE.md](https://github.com/devfred78/syracuse/blob/main/LICENSE.md) file for more information.
## Acknowledgments
I would like greatfully to thank:
Graphviz [authors](https://graphviz.org/) for this impressive graph visualization software, especially for the creation of the useful [DOT Langage](https://graphviz.org/doc/info/lang.html).
[The Matplotlib development team](https://matplotlib.org/) for providing a very powerful library "for creating static, animated, and interactive visualizations in Python".
NumPy [community](https://numpy.org/) for this fundamental tool to be used as a priority if you want make serious scientific computations with Python.
[MkDocs](https://www.mkdocs.org/), [mkdocstrings](https://mkdocstrings.github.io/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) for giving the ability to create in a very simple way an accessible documentation for either tiny or big projects.
[Make a README](https://www.makeareadme.com/), [Sayan Mondal](https://medium.com/swlh/how-to-make-the-perfect-readme-md-on-github-92ed5771c061), [Hillary Nyakundi](https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/) and [othneildrew](https://github.com/othneildrew/Best-README-Template) for providing very interesting materials to write good README files (far better than I can write by myself !).
[Choose an open source license](https://choosealicense.com/) for helping to choose the best suitable license for this project.
[Semantic Versioning](https://semver.org/) for providing clear specifications for versioning projects.
[Real Python](https://realpython.com/) for contributing really increasing skills in Python for everyone, novices or veterans.
[GitHub](https://github.com/) for hosting this project, and helping to share it.
[Pypi](https://pypi.org/) for providing a very convenient way to share modules and package to the entire Python community.
And, of course, all the former, current and further contributors of this project !
Raw data
{
"_id": null,
"home_page": "https://github.com/devfred78/syracuse",
"name": "syracuse",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<3.12",
"maintainer_email": "",
"keywords": "syracuse,collatz,3n+1,conjecture,ulan,kakutani,thwaites,hasse,hailstone,wondrous",
"author": "devfred78",
"author_email": "97401939+devfred78@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/26/91/195358f093578324d5684ce46aa6b59960b526e038df5f8d6c8aa5282d33/syracuse-0.4.0.tar.gz",
"platform": null,
"description": "\n\n\n\n\n\n\n*(Graph of the first 26 compressed Collatz sequences)*\n\n# Syracuse\n\nsyracuse, The Syracuse problem (aka Collatz conjecture) library.\n\n## About the project\n\nThe syracuse library provides a way to generate Collatz sequences (either \"normal\" or compressed forms) and some functions to deal with.\n\n### The Collatz conjecture\n\nThe Collatz conjecture, also known as the \"3n + 1 problem\" or the \"Syracuse problem\", is an unsolved hypothesis in mathematics that concerns a sequence of operations applied to a positive integer. The conjecture states that no matter what the starting value of this integer is, the sequence will always eventually reach the value 1.\n\nMore specifically, the Collatz conjecture states that if one takes a positive integer n and applies the following function:\n\n- If n is even, divide it by 2.\n- If n is odd, multiply it by 3 and add 1.\n\nThen, repeat the process with the resulting value, applying the function over and over again until the value of n eventually reaches 1.\n\n> For example, if one takes n = 6, the sequence for the Collatz conjecture would be:\n> 6, 3, 10, 5, 16, 8, 4, 2, 1.\n\nAlthough the conjecture has been computationally tested for extremely large values, it remains unproven to this day.\n\n### The compressed form\n\n*(definition partially inspired by the [relevant article on Wikipedia](https://en.wikipedia.org/wiki/Collatz_conjecture))*\n\nSince 3n+1 is even whenever n is odd, one may instead use the \"compressed\" form of the Collatz function:\n\n- if n is even, divide it by 2.\n- if n is odd, multiply it by 3, add 1 **and divide the result by 2**.\n\nThis definition yields smaller values for the stopping time and total stopping time without changing the overall dynamics of the process. \n\n> For example, consider the Collatz sequence for the number 17:\n> 17, 52, 26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1\n>\n> The compressed form of this sequence would be:\n> 17, 26, 13, 20, 10, 5, 8, 4, 2, 1\n\nThe compressed form of the Collatz sequence has been the subject of much research, as it provides insights into the behavior of the original sequence and can be used to search for cycles and other patterns. However, the Collatz conjecture itself remains unproven, and the compressed form of the sequence does not provide a proof or disproof of the conjecture.\n\n### Why the name \"syracuse\" ?\n\nThe Collatz conjecture is also known as the Syracuse problem because it was first introduced by Lothar Collatz in a 1950 paper, where he credited his colleague, mathematician Helmut Hasse, with calling it the Syracuse problem. The name \"Syracuse\" refers to the University of Syracuse, where Collatz was working at the time.\n\nThe name \"Syracuse problem\" has since become a common alternative to \"Collatz conjecture\", especially in French and Italian-speaking countries, where it is often referred to as the \"probl\u00e8me de Syracuse\" or \"problema di Syracuse\", respectively.\n\nRegardless of the name used, the conjecture remains one of the most famous and challenging open problems in mathematics, and it continues to attract the attention of mathematicians and computer scientists around the world.\n\n## Getting started\n\n### Prerequisites\n\nOf course, syracuse cannot run without Python ! More precisely, it requires at least the 3.11 version of our beloved language.\n\nsyracuse depends on the following packages. The installation of syracuse should install automatically those packages if they are missing on your system. If it fails, you can install them individually:\n\n* networkx: version 3.0.0 or above\n\n\t```sh\n\tpip install networkx[\"default\"]\n\t```\n\n* matplotlib: version 3.6.0 or above\n\n\t```sh\n\tpip install matplotlib\n\t```\n\n* numpy: version 1.24.0 or above\n\n\t```sh\n\tpip install numpy\n\t```\n\n* pydot: version 1.4.2 or above\n\n\t```sh\n\tpip install pydot\n\t```\n\n* more-itertools: version 9.1.0 or above\n\n\t```sh\n\tpip install more-itertools\n\t```\n\n### Installation\n\nInstall from PyPi with:\n\n```sh\npip install syracuse\n```\n\nAs an alternative, you can download the `*.whl` file from the last [release on the syracuse Github repository](https://github.com/devfred78/syracuse/releases), and execute the following command (replace \"X.Y.Z\" by the right version number):\n\n```sh\npip install syracuse-X.Y.Z-py3-none-any.whl\n```\n\n## Usage\n\nBasic usage:\n\n```pycon\n>>> # Import the core library\n>>> import syracuse\n\n>>> # Create a Syracuse sequence with 27 as initial value\n>>> my_sequence = syracuse.Syracuse(27)\n\n>>> # Stopping time\n>>> my_sequence.stopping_time\n96\n>>> # Total stopping time\n>>> my_sequence.total_stopping_time\n111\n>>> # Maximum reached value\n>>> my_sequence.max\n9232\n>>> # Full sequence (until 1)\n>>> my_sequence.total_stopping_sequence\n(27, 82, 41, 124, 62, 31, 94, 47, 142, 71, 214, 107, 322, 161,\n 484, 242, 121, 364, 182, 91, 274, 137, 412, 206, 103, 310, 155,\n 466, 233, 700, 350, 175, 526, 263, 790, 395, 1186, 593, 1780,\n 890, 445, 1336, 668, 334, 167, 502, 251, 754, 377, 1132, 566,\n 283, 850, 425, 1276, 638, 319, 958, 479, 1438, 719, 2158, 1079,\n 3238, 1619, 4858, 2429, 7288, 3644, 1822, 911, 2734, 1367, 4102,\n 2051, 6154, 3077, 9232, 4616, 2308, 1154, 577, 1732, 866, 433,\n 1300, 650, 325, 976, 488, 244, 122, 61, 184, 92, 46, 23, 70, 35,\n 106, 53, 160, 80, 40, 20, 10, 5, 16, 8, 4, 2, 1)\n\n>>> # Import the sequences library\n>>> import syracuse.sequences\n\n>>> # Create an iterator over the records of the max values (A006884)\n>>> # with all possible optimizations\n>>> max_records = syracuse.sequences.max_value_records(15)\n\n>>> # Iterate over the first 30 records\n>>> for _ in range(30):\n...\t\tprint(f\"{next(max_records)}, \", end=\"\", flush=True)\n...\n1, 2, 3, 7, 15, 27, 255, 447, 639, 703, 1819, 4255, 4591, 9663,\n20895, 26623, 31911, 60975, 77671, 113383, 138367, 159487, 270271,\n665215, 704511, 1042431, 1212415, 1441407, 1875711, 1988859,\n\n>>> # Import the drawing library\n>>> import syracuse.drawing\n\n>>> # Display the full sequence in a Matplotlib window\n>>> syracuse.drawing.single_sequence_to_matplotlib_figure(my_sequence, test=True)\n```\n\n\n\nFor deeper explanations, please refer to the [documentation](https://devfred78.github.io/syracuse/).\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\" or \"bug\", according to whether you want to share a proposal of a new function, or to record an anomaly.\n\nDon't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nDistributed under the MIT License. Check out [LICENSE.md](https://github.com/devfred78/syracuse/blob/main/LICENSE.md) file for more information.\n\n## Acknowledgments\n\nI would like greatfully to thank:\n\nGraphviz [authors](https://graphviz.org/) for this impressive graph visualization software, especially for the creation of the useful [DOT Langage](https://graphviz.org/doc/info/lang.html).\n\n[The Matplotlib development team](https://matplotlib.org/) for providing a very powerful library \"for creating static, animated, and interactive visualizations in Python\".\n\nNumPy [community](https://numpy.org/) for this fundamental tool to be used as a priority if you want make serious scientific computations with Python.\n\n[MkDocs](https://www.mkdocs.org/), [mkdocstrings](https://mkdocstrings.github.io/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) for giving the ability to create in a very simple way an accessible documentation for either tiny or big projects.\n\n[Make a README](https://www.makeareadme.com/), [Sayan Mondal](https://medium.com/swlh/how-to-make-the-perfect-readme-md-on-github-92ed5771c061), [Hillary Nyakundi](https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/) and [othneildrew](https://github.com/othneildrew/Best-README-Template) for providing very interesting materials to write good README files (far better than I can write by myself !).\n\n[Choose an open source license](https://choosealicense.com/) for helping to choose the best suitable license for this project.\n\n[Semantic Versioning](https://semver.org/) for providing clear specifications for versioning projects.\n\n[Real Python](https://realpython.com/) for contributing really increasing skills in Python for everyone, novices or veterans.\n\n[GitHub](https://github.com/) for hosting this project, and helping to share it.\n\n[Pypi](https://pypi.org/) for providing a very convenient way to share modules and package to the entire Python community.\n\nAnd, of course, all the former, current and further contributors of this project !",
"bugtrack_url": null,
"license": "MIT",
"summary": "The Syracuse problem (aka Collatz conjecture) library",
"version": "0.4.0",
"split_keywords": [
"syracuse",
"collatz",
"3n+1",
"conjecture",
"ulan",
"kakutani",
"thwaites",
"hasse",
"hailstone",
"wondrous"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9f4c8b6095eecbdfa810975c4cb4f9d65d8947667ed8a39c46f50211fee44849",
"md5": "276c8e3a9932224b68e62e0848e326e8",
"sha256": "978cc0006689dfa26b894acf379abc22010797be2be326e864b478f5201d4c59"
},
"downloads": -1,
"filename": "syracuse-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "276c8e3a9932224b68e62e0848e326e8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<3.12",
"size": 18690,
"upload_time": "2023-04-17T20:29:04",
"upload_time_iso_8601": "2023-04-17T20:29:04.211076Z",
"url": "https://files.pythonhosted.org/packages/9f/4c/8b6095eecbdfa810975c4cb4f9d65d8947667ed8a39c46f50211fee44849/syracuse-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2691195358f093578324d5684ce46aa6b59960b526e038df5f8d6c8aa5282d33",
"md5": "ba041faaab37320d686312c425e95b88",
"sha256": "281bbc16dfec761278e9b018338984cb58bb1ee28b46a230f28cb7601572a9d7"
},
"downloads": -1,
"filename": "syracuse-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "ba041faaab37320d686312c425e95b88",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<3.12",
"size": 21040,
"upload_time": "2023-04-17T20:29:06",
"upload_time_iso_8601": "2023-04-17T20:29:06.642662Z",
"url": "https://files.pythonhosted.org/packages/26/91/195358f093578324d5684ce46aa6b59960b526e038df5f8d6c8aa5282d33/syracuse-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-17 20:29:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "devfred78",
"github_project": "syracuse",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "syracuse"
}
JSON
