mapFolding 0.8.5__tar.gz → 0.9.0__tar.gz

mapfolding-0.9.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: mapFolding
+Version: 0.9.0
+Summary: Map folding algorithm with code transformation framework for optimizing numerical computations
+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
+Project-URL: Issues, https://github.com/hunterhogan/mapFolding/issues
+Keywords: A001415,A001416,A001417,A001418,A195646,algorithmic optimization,AST manipulation,code generation,code transformation,combinatorics,computational geometry,dataclass transformation,folding pattern enumeration,just-in-time compilation,map folding,Numba optimization,OEIS,performance optimization,source code analysis,stamp folding
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: autoflake
+Requires-Dist: more_itertools
+Requires-Dist: numba_progress
+Requires-Dist: numba
+Requires-Dist: numpy
+Requires-Dist: platformdirs
+Requires-Dist: python_minifier
+Requires-Dist: tomli
+Requires-Dist: Z0Z_tools
+Provides-Extra: testing
+Requires-Dist: mypy; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: pytest-env; extra == "testing"
+Requires-Dist: pytest-xdist; extra == "testing"
+Requires-Dist: pyupgrade; extra == "testing"
+Requires-Dist: ruff; extra == "testing"
+Dynamic: license-file
+
+# mapFolding: High-Performance Algorithm Playground for Computational Enthusiasts 🗺️
+
+[![pip install mapFolding](https://img.shields.io/badge/pip%20install-mapFolding-gray.svg?colorB=3b434b)](https://pypi.org/project/mapFolding/)
+[![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
+[![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/)
+
+**This package is for you if:**
+
+- You're fascinated by computational algorithms and their optimization
+- You want to explore AST transformation techniques for Python performance tuning
+- You're interested in solving mathematical puzzles through code
+- You're learning about Numba and advanced Python optimization
+
+**This package is NOT for you if:**
+
+- You're looking for a general-purpose folding simulation tool
+- You need commercial-ready mapping software
+- You want simple visualization of folding patterns
+
+## What Does This Package Actually Do?
+
+`mapFolding` solves a specific mathematical problem: counting the number of distinct ways to fold a rectangular map. While this may sound niche, it's a fascinating computational challenge that demonstrates:
+
+1. How to transform readable algorithms into blazingly fast implementations
+2. Advanced techniques for Python optimization using AST manipulation
+3. Numba acceleration with specialized compilation strategies
+4. Algorithms for problems that grow combinatorially
+
+The package has achieved new computational records, including first-ever calculations for large maps that were previously infeasible.
+
+```python
+# Compute the number of ways to fold a 5×5 grid:
+from mapFolding import oeisIDfor_n
+foldsTotal = oeisIDfor_n('A001418', 5)  # Returns 186,086,600
+```
+
+## Key Benefits for Computational Enthusiasts
+
+### 1. Algorithm Transformation Laboratory
+
+See how the same algorithm evolves from readable Python to highly-optimized implementations:
+
+```python
+# The intuitive, readable version:
+def countFolds(mapShape):
+    # ...implement readable algorithm...
+
+# The transformed, optimized version (auto-generated):
+@numba.jit(nopython=True, parallel=True, fastmath=True)
+def countFolds_optimized(shape_param):
+    # ...blazingly fast implementation...
+```
+
+### 2. Code Generation Framework
+
+Study and extend a complete Python code transformation pipeline:
+
+- AST analysis and manipulation
+- Dataclass decomposition ("shattering")
+- Automatic import management
+- Type specialization for numerical computing
+
+### 3. Exhaustive Test Framework
+
+Leverage a sophisticated test suite for validating your own optimizations:
+
+```python
+# Test your own recipe implementation with just a few lines:
+@pytest.fixture
+def myCustomRecipeFixture(useThisDispatcher, pathTmpTesting):
+    myRecipe = RecipeSynthesizeFlow(
+        # Your custom configuration here
+    )
+    # ...transformation code...
+    return customDispatcher
+
+def test_myCustomImplementation(myCustomRecipeFixture):
+    # Automatic validation against known values
+```
+
+## Installation and Getting Started
+
+```sh
+pip install mapFolding
+```
+
+Try a quick calculation:
+
+```python
+from mapFolding import oeisIDfor_n
+
+# Calculate ways to fold a 2×4 map
+result = oeisIDfor_n('A001415', 4)  # Returns 8
+print(f"A 2×4 map can be folded {result} different ways")
+```
+
+## Mathematical Background (For the Curious)
+
+The map folding problem was introduced by Lunnon in 1971 and connects to combinatorial geometry, computational complexity, and integer sequence analysis. The calculations provide entries to the Online Encyclopedia of Integer Sequences (OEIS).
+
+This package implements several OEIS sequences, including:
+
+- A001415: Number of ways to fold a 2×n strip (now calculated up to n=20!)
+- A001418: Number of ways to fold an n×n square grid
+
+## Explore the Repository
+
+The repository structure reveals the package's educational value:
+
+- `reference/`: Historical implementations and algorithm evolution
+- `someAssemblyRequired/`: Code transformation framework
+- `tests/`: Comprehensive test suite with fixtures for your own implementations
+
+## Who Is This For, Really?
+
+If you've read this far and are intrigued by computational puzzles, algorithm optimization, or Python performance techniques, this package offers a playground for exploration. It's particularly valuable for:
+
+- Computer science students studying algorithm optimization
+- Python developers exploring Numba and AST manipulation
+- Computational mathematicians interested in combinatorial problems
+- Anyone fascinated by the intersection of mathematics and computing
+
+Whether you use it to solve map folding problems or to study its optimization techniques, `mapFolding` offers a unique window into advanced Python programming approaches.
+
+[![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.9.0/README.md

@@ -0,0 +1,125 @@
+# mapFolding: High-Performance Algorithm Playground for Computational Enthusiasts 🗺️
+
+[![pip install mapFolding](https://img.shields.io/badge/pip%20install-mapFolding-gray.svg?colorB=3b434b)](https://pypi.org/project/mapFolding/)
+[![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
+[![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/)
+
+**This package is for you if:**
+
+- You're fascinated by computational algorithms and their optimization
+- You want to explore AST transformation techniques for Python performance tuning
+- You're interested in solving mathematical puzzles through code
+- You're learning about Numba and advanced Python optimization
+
+**This package is NOT for you if:**
+
+- You're looking for a general-purpose folding simulation tool
+- You need commercial-ready mapping software
+- You want simple visualization of folding patterns
+
+## What Does This Package Actually Do?
+
+`mapFolding` solves a specific mathematical problem: counting the number of distinct ways to fold a rectangular map. While this may sound niche, it's a fascinating computational challenge that demonstrates:
+
+1. How to transform readable algorithms into blazingly fast implementations
+2. Advanced techniques for Python optimization using AST manipulation
+3. Numba acceleration with specialized compilation strategies
+4. Algorithms for problems that grow combinatorially
+
+The package has achieved new computational records, including first-ever calculations for large maps that were previously infeasible.
+
+```python
+# Compute the number of ways to fold a 5×5 grid:
+from mapFolding import oeisIDfor_n
+foldsTotal = oeisIDfor_n('A001418', 5)  # Returns 186,086,600
+```
+
+## Key Benefits for Computational Enthusiasts
+
+### 1. Algorithm Transformation Laboratory
+
+See how the same algorithm evolves from readable Python to highly-optimized implementations:
+
+```python
+# The intuitive, readable version:
+def countFolds(mapShape):
+    # ...implement readable algorithm...
+
+# The transformed, optimized version (auto-generated):
+@numba.jit(nopython=True, parallel=True, fastmath=True)
+def countFolds_optimized(shape_param):
+    # ...blazingly fast implementation...
+```
+
+### 2. Code Generation Framework
+
+Study and extend a complete Python code transformation pipeline:
+
+- AST analysis and manipulation
+- Dataclass decomposition ("shattering")
+- Automatic import management
+- Type specialization for numerical computing
+
+### 3. Exhaustive Test Framework
+
+Leverage a sophisticated test suite for validating your own optimizations:
+
+```python
+# Test your own recipe implementation with just a few lines:
+@pytest.fixture
+def myCustomRecipeFixture(useThisDispatcher, pathTmpTesting):
+    myRecipe = RecipeSynthesizeFlow(
+        # Your custom configuration here
+    )
+    # ...transformation code...
+    return customDispatcher
+
+def test_myCustomImplementation(myCustomRecipeFixture):
+    # Automatic validation against known values
+```
+
+## Installation and Getting Started
+
+```sh
+pip install mapFolding
+```
+
+Try a quick calculation:
+
+```python
+from mapFolding import oeisIDfor_n
+
+# Calculate ways to fold a 2×4 map
+result = oeisIDfor_n('A001415', 4)  # Returns 8
+print(f"A 2×4 map can be folded {result} different ways")
+```
+
+## Mathematical Background (For the Curious)
+
+The map folding problem was introduced by Lunnon in 1971 and connects to combinatorial geometry, computational complexity, and integer sequence analysis. The calculations provide entries to the Online Encyclopedia of Integer Sequences (OEIS).
+
+This package implements several OEIS sequences, including:
+
+- A001415: Number of ways to fold a 2×n strip (now calculated up to n=20!)
+- A001418: Number of ways to fold an n×n square grid
+
+## Explore the Repository
+
+The repository structure reveals the package's educational value:
+
+- `reference/`: Historical implementations and algorithm evolution
+- `someAssemblyRequired/`: Code transformation framework
+- `tests/`: Comprehensive test suite with fixtures for your own implementations
+
+## Who Is This For, Really?
+
+If you've read this far and are intrigued by computational puzzles, algorithm optimization, or Python performance techniques, this package offers a playground for exploration. It's particularly valuable for:
+
+- Computer science students studying algorithm optimization
+- Python developers exploring Numba and AST manipulation
+- Computational mathematicians interested in combinatorial problems
+- Anyone fascinated by the intersection of mathematics and computing
+
+Whether you use it to solve map folding problems or to study its optimization techniques, `mapFolding` offers a unique window into advanced Python programming approaches.
+
+[![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.9.0/mapFolding/__init__.py

@@ -0,0 +1,93 @@
+"""
+Map folding enumeration and counting algorithms with advanced optimization capabilities.
+
+This package implements algorithms to count and enumerate the distinct ways
+a rectangular map can be folded, based on the mathematical problem described
+in Lunnon's 1971 paper. It provides multiple layers of functionality, from
+high-level user interfaces to sophisticated algorithmic optimizations and code
+transformation tools.
+
+Core modules:
+- basecamp: Public API with simplified interfaces for end users
+- theDao: Core computational algorithm using a functional state-transformation approach
+- beDRY: Core utility functions implementing consistent data handling, validation, and
+    resource management across the package's computational assembly-line
+- theSSOT: Single Source of Truth for configuration, types, and state management
+- toolboxFilesystem: Cross-platform file management services for storing and retrieving
+    computation results with robust error handling and fallback mechanisms
+- oeis: Interface to the Online Encyclopedia of Integer Sequences for known results
+
+Extended functionality:
+- someAssemblyRequired: Code transformation framework that optimizes the core algorithm
+    through AST manipulation, dataclass transformation, and compilation techniques
+    - The system converts readable code into high-performance implementations through
+      a systematic analysis and transformation pipeline
+    - Provides tools to "shatter" complex dataclasses into primitive components,
+      enabling compatibility with Numba and other optimization frameworks
+    - Creates specialized implementations tailored for specific input parameters
+
+Testing and extension:
+- tests: Comprehensive test suite designed for both verification and extension
+    - Provides fixtures and utilities that simplify testing of custom implementations
+    - Enables users to validate their own recipes and job configurations with minimal code
+    - Offers standardized testing patterns that maintain consistency across the codebase
+    - See tests/__init__.py for detailed documentation on extending the test suite
+
+Special directories:
+- .cache/: Stores cached data from external sources like OEIS to improve performance
+- syntheticModules/: Contains dynamically generated, optimized implementations of the
+    core algorithm created by the code transformation framework
+- reference/: Historical implementations and educational resources for algorithm exploration
+    - reference/jobsCompleted/: Contains successful computations for previously unknown values,
+        including first-ever calculations for 2x19 and 2x20 maps (OEIS A001415)
+
+This package balances algorithm readability and understandability with
+high-performance computation capabilities, allowing users to compute map folding
+totals for larger dimensions than previously feasible while also providing
+a foundation for exploring advanced code transformation techniques.
+"""
+
+__all__ = [
+        'clearOEIScache',
+        'countFolds',
+        'getOEISids',
+        'OEIS_for_n',
+        'oeisIDfor_n',
+]
+
+from mapFolding.theSSOT import (
+    Array1DElephino,
+    Array1DFoldsTotal,
+    Array1DLeavesTotal,
+    Array3D,
+    ComputationState,
+    DatatypeElephino,
+    DatatypeFoldsTotal,
+    DatatypeLeavesTotal,
+    NumPyElephino,
+    NumPyFoldsTotal,
+    NumPyIntegerType,
+    NumPyLeavesTotal,
+    raiseIfNoneGitHubIssueNumber3,
+    The,
+)
+
+from mapFolding.theDao import countInitialize, doTheNeedful
+
+from mapFolding.beDRY import (
+    outfitCountFolds,
+    setProcessorLimit,
+    validateListDimensions,
+)
+
+from mapFolding.toolboxFilesystem import (
+    getPathFilenameFoldsTotal,
+    getPathRootJobDEFAULT,
+    saveFoldsTotal,
+    saveFoldsTotalFAILearly,
+    writeStringToHere,
+)
+
+from mapFolding.basecamp import countFolds
+
+from mapFolding.oeis import clearOEIScache, getFoldsTotalKnown, getOEISids, OEIS_for_n, oeisIDfor_n

{mapfolding-0.8.5 → mapfolding-0.9.0}/mapFolding/basecamp.py

@@ -13,9 +13,16 @@ implementation, and optional persistence of results.
 """
 
 from collections.abc import Sequence
-from mapFolding.theSSOT import ComputationState, getPackageDispatcher, The
-from mapFolding.beDRY import outfitCountFolds, setProcessorLimit, validateListDimensions
-from mapFolding.toolboxFilesystem import getPathFilenameFoldsTotal, saveFoldsTotal, saveFoldsTotalFAILearly
+from mapFolding import (
+	ComputationState,
+	getPathFilenameFoldsTotal,
+	outfitCountFolds,
+	saveFoldsTotal,
+	saveFoldsTotalFAILearly,
+	setProcessorLimit,
+	The,
+	validateListDimensions,
+)
 from os import PathLike
 from pathlib import PurePath
 
@@ -24,18 +31,27 @@ def countFolds(listDimensions: Sequence[int]
 				, computationDivisions: int | str | None = None
 				, CPUlimit: int | float | bool | None = None
 				) -> int:
-	"""Count the total number of possible foldings for a given map dimensions.
+	"""
+	Count the total number of possible foldings for a given map dimensions.
+
+	This function serves as the main public interface to the map folding algorithm,
+	handling all parameter validation, computation state management, and result
+	persistence in a user-friendly way.
 
-	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.
-	Returns:
-		foldsTotal: Total number of distinct ways to fold a map of the given 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.
+	Returns
+	-------
+	foldsTotal: Total number of distinct ways to fold a map of the given dimensions.
 
+	Notes
+	-----
 	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
@@ -51,7 +67,8 @@ def countFolds(listDimensions: Sequence[int]
 		- 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.
+
+	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.
 	"""
 	mapShape: tuple[int, ...] = validateListDimensions(listDimensions)
 	concurrencyLimit: int = setProcessorLimit(CPUlimit, The.concurrencyPackage)
@@ -63,9 +80,7 @@ def countFolds(listDimensions: Sequence[int]
 	else:
 		pathFilenameFoldsTotal = None
 
-	dispatcherCallableProxy = getPackageDispatcher()
-	computationStateComplete: ComputationState = dispatcherCallableProxy(computationStateInitialized)
-	# computationStateComplete: ComputationState = The.dispatcher(computationStateInitialized)
+	computationStateComplete: ComputationState = The.dispatcher(computationStateInitialized)
 
 	computationStateComplete.getFoldsTotal()
 

{mapfolding-0.8.5 → mapfolding-0.9.0}/mapFolding/beDRY.py

@@ -19,7 +19,7 @@ These utilities form a stable internal API that other modules depend on, particu
 produce optimized implementations.
 """
 from collections.abc import Sequence
-from mapFolding.theSSOT import ComputationState, numpyIntegerType
+from mapFolding import ComputationState, NumPyIntegerType
 from numpy import dtype as numpy_dtype, int64 as numpy_int64, ndarray
 from sys import maxsize as sysMaxsize
 from typing import Any
@@ -165,7 +165,7 @@ def _makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int) -> ndarray
 					connectionGraph[indexDimension, activeLeaf1ndex, connectee1ndex] = connectee1ndex + cumulativeProduct[indexDimension]
 	return connectionGraph
 
-def getConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: type[numpyIntegerType]) -> ndarray[tuple[int, int, int], numpy_dtype[numpyIntegerType]]:
+def getConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: type[NumPyIntegerType]) -> ndarray[tuple[int, int, int], numpy_dtype[NumPyIntegerType]]:
 	"""
 	Create a properly typed connection graph for the map folding algorithm.
 
@@ -193,7 +193,7 @@ def getConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: ty
 	connectionGraph = connectionGraph.astype(datatype)
 	return connectionGraph
 
-def makeDataContainer(shape: int | tuple[int, ...], datatype: type[numpyIntegerType]) -> ndarray[Any, numpy_dtype[numpyIntegerType]]:
+def makeDataContainer(shape: int | tuple[int, ...], datatype: type[NumPyIntegerType]) -> ndarray[Any, numpy_dtype[NumPyIntegerType]]:
 	"""
 	Create a typed NumPy array container with initialized values.