mapFolding 0.3.11__tar.gz → 0.4.0__tar.gz

mapfolding-0.4.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.2
+Name: mapFolding
+Version: 0.4.0
+Summary: Count distinct ways to fold a map (or a strip of stamps)
+Author-email: Hunter Hogan <HunterHogan@pm.me>
+License: CC-BY-NC-4.0
+Project-URL: Donate, https://www.patreon.com/integrated
+Project-URL: Homepage, https://github.com/hunterhogan/mapFolding
+Project-URL: Repository, https://github.com/hunterhogan/mapFolding.git
+Keywords: A001415,A001416,A001417,A001418,A195646,folding,map folding,OEIS,stamp folding
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Other Audience
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numba
+Requires-Dist: numpy
+Requires-Dist: Z0Z_tools
+Provides-Extra: synthesizemodules
+Requires-Dist: autoflake; extra == "synthesizemodules"
+Requires-Dist: more_itertools; extra == "synthesizemodules"
+Requires-Dist: python_minifier; extra == "synthesizemodules"
+Provides-Extra: testing
+Requires-Dist: mypy; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: pytest-env; extra == "testing"
+Requires-Dist: pytest-mypy; extra == "testing"
+Requires-Dist: pytest-xdist; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: updateCitation; extra == "testing"
+
+# mapFolding: Algorithms for enumerating distinct map/stamp folding patterns 🗺️
+
+[![pip install mapFolding](https://img.shields.io/badge/pip%20install-mapFolding-gray.svg?colorB=3b434b)](https://pypi.org/project/mapFolding/)
+[![Static Badge](https://img.shields.io/badge/stinkin'%20badges-don't%20need-b98e5e)](https://youtu.be/g6f_miE91mk&t=4)
+[![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
+![Static Badge](https://img.shields.io/badge/issues-I%20have%20them-brightgreen)
+[![License: CC-BY-NC-4.0](https://img.shields.io/badge/License-CC_BY--NC_4.0-3b434b)](https://creativecommons.org/licenses/by-nc/4.0/)
+![PyPI - Downloads](https://img.shields.io/pypi/dd/mapFolding)
+![GitHub repo size](https://img.shields.io/github/repo-size/hunterhogan/mapFolding)
+
+---
+
+## Quick start
+
+```sh
+pip install mapFolding
+```
+
+`OEIS_for_n` will run a computation from the command line.
+
+```cmd
+(mapFolding) C:\apps\mapFolding> OEIS_for_n A001418 5
+186086600 distinct folding patterns.
+Time elapsed: 1.605 seconds
+```
+
+Use `mapFolding.oeisIDfor_n()` to compute a(n) for an OEIS ID.
+
+```python
+from mapFolding import oeisIDfor_n
+foldsTotal = oeisIDfor_n( 'A001418', 4 )
+```
+
+---
+
+## Features
+
+### 1. Simple, easy usage based on OEIS IDs
+
+`mapFolding` directly implements some IDs from [_The On-Line Encyclopedia of Integer Sequences_](https://oeis.org/) ([BibTex](https://github.com/hunterhogan/mapFolding/blob/main/citations/oeis.bibtex) citation).
+
+Use `getOEISids` to get the most up-to-date list of available OEIS IDs.
+
+```cmd
+(mapFolding) C:\apps\mapFolding> getOEISids
+
+Available OEIS sequences:
+  A001415: Number of ways of folding a 2 X n strip of stamps.
+  A001416: Number of ways of folding a 3 X n strip of stamps.
+  A001417: Number of ways of folding a 2 X 2 X ... X 2 n-dimensional map.
+  A001418: Number of ways of folding an n X n sheet of stamps.
+  A195646: Number of ways of folding a 3 X 3 X ... X 3 n-dimensional map.
+```
+
+### 2. **Algorithm Zoo** 🦒
+
+- **Lunnon’s 1971 Algorithm**: A painstakingly debugged version of [the original typo-riddled code](https://github.com/hunterhogan/mapFolding/blob/mapFolding/reference/foldings.txt)
+- The /reference directory.
+- **Numba-JIT Accelerated**: Up to 1000× faster than pure Python ([benchmarks](https://github.com/hunterhogan/mapFolding/blob/mapFolding/notes/Speed%20highlights.md))
+
+### 3. **For Researchers** 🔬
+
+- Change multiple minute settings, such as the bit width of the data types.
+- Transform the algorithm using AST
+- Create hyper-optimized modules to compute a specific map.
+
+## Map-folding Video
+
+~~This caused my neurosis:~~ I enjoyed the following video, which is what introduced me to map folding.
+
+"How Many Ways Can You Fold a Map?" by Physics for the Birds, 2024 November 13 ([BibTex](https://github.com/hunterhogan/mapFolding/blob/main/citations/Physics_for_the_Birds.bibtex) citation)
+
+[![How Many Ways Can You Fold a Map?](https://i.ytimg.com/vi/sfH9uIY3ln4/hq720.jpg)](https://www.youtube.com/watch?v=sfH9uIY3ln4)
+
+---
+
+## My recovery
+
+[![Static Badge](https://img.shields.io/badge/2011_August-Homeless_since-blue?style=flat)](https://HunterThinks.com/support)
+[![YouTube Channel Subscribers](https://img.shields.io/youtube/channel/subscribers/UC3Gx7kz61009NbhpRtPP7tw)](https://www.youtube.com/@HunterHogan)
+
+[![CC-BY-NC-4.0](https://github.com/hunterhogan/mapFolding/blob/main/CC-BY-NC-4.0.svg)](https://creativecommons.org/licenses/by-nc/4.0/)

mapfolding-0.4.0/README.md

@@ -0,0 +1,82 @@
+# mapFolding: Algorithms for enumerating distinct map/stamp folding patterns 🗺️
+
+[![pip install mapFolding](https://img.shields.io/badge/pip%20install-mapFolding-gray.svg?colorB=3b434b)](https://pypi.org/project/mapFolding/)
+[![Static Badge](https://img.shields.io/badge/stinkin'%20badges-don't%20need-b98e5e)](https://youtu.be/g6f_miE91mk&t=4)
+[![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
+![Static Badge](https://img.shields.io/badge/issues-I%20have%20them-brightgreen)
+[![License: CC-BY-NC-4.0](https://img.shields.io/badge/License-CC_BY--NC_4.0-3b434b)](https://creativecommons.org/licenses/by-nc/4.0/)
+![PyPI - Downloads](https://img.shields.io/pypi/dd/mapFolding)
+![GitHub repo size](https://img.shields.io/github/repo-size/hunterhogan/mapFolding)
+
+---
+
+## Quick start
+
+```sh
+pip install mapFolding
+```
+
+`OEIS_for_n` will run a computation from the command line.
+
+```cmd
+(mapFolding) C:\apps\mapFolding> OEIS_for_n A001418 5
+186086600 distinct folding patterns.
+Time elapsed: 1.605 seconds
+```
+
+Use `mapFolding.oeisIDfor_n()` to compute a(n) for an OEIS ID.
+
+```python
+from mapFolding import oeisIDfor_n
+foldsTotal = oeisIDfor_n( 'A001418', 4 )
+```
+
+---
+
+## Features
+
+### 1. Simple, easy usage based on OEIS IDs
+
+`mapFolding` directly implements some IDs from [_The On-Line Encyclopedia of Integer Sequences_](https://oeis.org/) ([BibTex](https://github.com/hunterhogan/mapFolding/blob/main/citations/oeis.bibtex) citation).
+
+Use `getOEISids` to get the most up-to-date list of available OEIS IDs.
+
+```cmd
+(mapFolding) C:\apps\mapFolding> getOEISids
+
+Available OEIS sequences:
+  A001415: Number of ways of folding a 2 X n strip of stamps.
+  A001416: Number of ways of folding a 3 X n strip of stamps.
+  A001417: Number of ways of folding a 2 X 2 X ... X 2 n-dimensional map.
+  A001418: Number of ways of folding an n X n sheet of stamps.
+  A195646: Number of ways of folding a 3 X 3 X ... X 3 n-dimensional map.
+```
+
+### 2. **Algorithm Zoo** 🦒
+
+- **Lunnon’s 1971 Algorithm**: A painstakingly debugged version of [the original typo-riddled code](https://github.com/hunterhogan/mapFolding/blob/mapFolding/reference/foldings.txt)
+- The /reference directory.
+- **Numba-JIT Accelerated**: Up to 1000× faster than pure Python ([benchmarks](https://github.com/hunterhogan/mapFolding/blob/mapFolding/notes/Speed%20highlights.md))
+
+### 3. **For Researchers** 🔬
+
+- Change multiple minute settings, such as the bit width of the data types.
+- Transform the algorithm using AST
+- Create hyper-optimized modules to compute a specific map.
+
+## Map-folding Video
+
+~~This caused my neurosis:~~ I enjoyed the following video, which is what introduced me to map folding.
+
+"How Many Ways Can You Fold a Map?" by Physics for the Birds, 2024 November 13 ([BibTex](https://github.com/hunterhogan/mapFolding/blob/main/citations/Physics_for_the_Birds.bibtex) citation)
+
+[![How Many Ways Can You Fold a Map?](https://i.ytimg.com/vi/sfH9uIY3ln4/hq720.jpg)](https://www.youtube.com/watch?v=sfH9uIY3ln4)
+
+---
+
+## My recovery
+
+[![Static Badge](https://img.shields.io/badge/2011_August-Homeless_since-blue?style=flat)](https://HunterThinks.com/support)
+[![YouTube Channel Subscribers](https://img.shields.io/youtube/channel/subscribers/UC3Gx7kz61009NbhpRtPP7tw)](https://www.youtube.com/@HunterHogan)
+
+[![CC-BY-NC-4.0](https://github.com/hunterhogan/mapFolding/blob/main/CC-BY-NC-4.0.svg)](https://creativecommons.org/licenses/by-nc/4.0/)

mapfolding-0.4.0/mapFolding/__init__.py

@@ -0,0 +1,68 @@
+# fundamentals
+from mapFolding.theSSOT import (
+	computationState,
+	EnumIndices,
+	getDispatcherCallable,
+	getPathPackage,
+	indexMy,
+	indexTrack,
+	myPackageNameIs,
+)
+
+# Datatype management
+from mapFolding.theSSOT import (
+	hackSSOTdatatype,
+	hackSSOTdtype,
+	setDatatypeElephino,
+	setDatatypeFoldsTotal,
+	setDatatypeLeavesTotal,
+	setDatatypeModule,
+)
+
+# Synthesize modules
+from mapFolding.theSSOT import (
+	formatModuleNameDEFAULT,
+	getAlgorithmCallable,
+	getAlgorithmSource,
+	getPathJobRootDEFAULT,
+	getPathSyntheticModules,
+	moduleOfSyntheticModules,
+	Z0Z_getDatatypeModuleScalar,
+	Z0Z_getDecoratorCallable,
+	Z0Z_setDatatypeModuleScalar,
+	Z0Z_setDecoratorCallable,
+	Z0Z_identifierCountFolds,
+)
+
+# Parameters for the prima donna
+from mapFolding.theSSOT import (
+	ParametersNumba,
+	parametersNumbaDEFAULT,
+	parametersNumbaFailEarly,
+	parametersNumbaMinimum,
+	parametersNumbaParallelDEFAULT,
+	parametersNumbaSuperJit,
+	parametersNumbaSuperJitParallel,
+)
+
+# Coping
+from mapFolding.theSSOT import (
+	FREAKOUT,
+)
+
+from mapFolding.beDRY import (
+	getFilenameFoldsTotal,
+	getPathFilenameFoldsTotal,
+	outfitCountFolds,
+	saveFoldsTotal,
+)
+
+from mapFolding.basecamp import countFolds
+from mapFolding.oeis import clearOEIScache, getOEISids, oeisIDfor_n
+
+__all__ = [
+	'clearOEIScache',
+	'countFolds',
+	'getOEISids',
+	'oeisIDfor_n',
+]

mapfolding-0.4.0/mapFolding/basecamp.py

@@ -0,0 +1,55 @@
+from mapFolding import computationState, getDispatcherCallable, getPathFilenameFoldsTotal, outfitCountFolds, saveFoldsTotal
+from typing import Optional, Sequence, Union
+import os
+
+def countFolds(listDimensions: Sequence[int]
+				, pathLikeWriteFoldsTotal: Optional[Union[str, os.PathLike[str]]] = None
+				, computationDivisions: Optional[Union[int, str]] = None
+				, CPUlimit: Optional[Union[int, float, bool]] = None
+				, **keywordArguments: Optional[Union[str, bool]]
+				) -> int:
+	"""Count the total number of possible foldings for a given map dimensions.
+
+	Parameters:
+		listDimensions: List of integers representing the dimensions of the map to be folded.
+		pathLikeWriteFoldsTotal (None): Path, filename, or pathFilename to write the total fold count to.
+			If a directory is provided, creates a file with a default name based on map dimensions.
+		computationDivisions (None):
+			Whether and how to divide the computational work. See notes for details.
+		CPUlimit (None): This is only relevant if there are `computationDivisions`: whether and how to limit the CPU usage. See notes for details.
+		**keywordArguments: Datatype management.
+	Returns:
+		foldsTotal: Total number of distinct ways to fold a map of the given dimensions.
+
+	Computation divisions:
+		- None: no division of the computation into tasks; sets task divisions to 0
+		- int: direct set the number of task divisions; cannot exceed the map's total leaves
+		- "maximum": divides into `leavesTotal`-many `taskDivisions`
+		- "cpu": limits the divisions to the number of available CPUs, i.e. `concurrencyLimit`
+
+	Limits on CPU usage `CPUlimit`:
+		- `False`, `None`, or `0`: No limits on CPU usage; uses all available CPUs. All other values will potentially limit CPU usage.
+		- `True`: Yes, limit the CPU usage; limits to 1 CPU.
+		- Integer `>= 1`: Limits usage to the specified number of CPUs.
+		- Decimal value (`float`) between 0 and 1: Fraction of total CPUs to use.
+		- Decimal value (`float`) between -1 and 0: Fraction of CPUs to *not* use.
+		- Integer `<= -1`: Subtract the absolute value from total CPUs.
+
+	N.B.: You probably don't want to divide the computation into tasks.
+		If you want to compute a large `foldsTotal`, dividing the computation into tasks is usually a bad idea. Dividing the algorithm into tasks is inherently inefficient: efficient division into tasks means there would be no overlap in the work performed by each task. When dividing this algorithm, the amount of overlap is between 50% and 90% by all tasks: at least 50% of the work done by every task must be done by _all_ tasks. If you improve the computation time, it will only change by -10 to -50% depending on (at the very least) the ratio of the map dimensions and the number of leaves. If an undivided computation would take 10 hours on your computer, for example, the computation will still take at least 5 hours but you might reduce the time to 9 hours. Most of the time, however, you will increase the computation time. If logicalCores >= leavesTotal, it will probably be faster. If logicalCores <= 2 * leavesTotal, it will almost certainly be slower for all map dimensions.
+	"""
+	stateUniversal: computationState = outfitCountFolds(listDimensions, computationDivisions=computationDivisions, CPUlimit=CPUlimit, **keywordArguments)
+
+	pathFilenameFoldsTotal = None
+	if pathLikeWriteFoldsTotal is not None:
+		pathFilenameFoldsTotal = getPathFilenameFoldsTotal(stateUniversal['mapShape'], pathLikeWriteFoldsTotal)
+
+	dispatcher = getDispatcherCallable()
+	dispatcher(**stateUniversal)
+
+	foldsTotal = int(stateUniversal['foldGroups'][0:-1].sum() * stateUniversal['foldGroups'][-1])
+
+	if pathFilenameFoldsTotal is not None:
+		saveFoldsTotal(pathFilenameFoldsTotal, foldsTotal)
+
+	return foldsTotal