mapFolding 0.8.5__py3-none-any.whl → 0.9.0__py3-none-any.whl

mapFolding/theSSOT.py

@@ -26,67 +26,107 @@ from types import ModuleType
 from typing import Any, TypeAlias, TypeVar
 import dataclasses
 
-# =============================================================================
-# The Wrong Way: Evaluate When Packaging
-
+# Evaluate When Packaging https://github.com/hunterhogan/mapFolding/issues/18
 try:
 	packageNamePACKAGING: str = tomli_load(Path("../pyproject.toml").open('rb'))["project"]["name"]
 except Exception:
 	packageNamePACKAGING = "mapFolding"
 
-# The Wrong Way: Evaluate When Installing
-
+# Evaluate When Installing https://github.com/hunterhogan/mapFolding/issues/18
 def getPathPackageINSTALLING() -> Path:
 	pathPackage: Path = Path(inspect_getfile(importlib_import_module(packageNamePACKAGING)))
 	if pathPackage.is_file():
 		pathPackage = pathPackage.parent
 	return pathPackage
 
-# =============================================================================
-# The Wrong Way: HARDCODED
+# I believe these values should be dynamically determined, so I have conspicuously marked them "HARDCODED"
+# and created downstream logic that assumes the values were dynamically determined.
 # Figure out dynamic flow control to synthesized modules https://github.com/hunterhogan/mapFolding/issues/4
-
-# from mapFolding.someAssemblyRequired.synthesizeNumbaFlow.theNumbaFlow
 logicalPathModuleDispatcherHARDCODED: str = 'mapFolding.syntheticModules.numbaCount_doTheNeedful'
 callableDispatcherHARDCODED: str = 'doTheNeedful'
 concurrencyPackageHARDCODED = 'multiprocessing'
+# from mapFolding.someAssemblyRequired.synthesizeNumbaFlow.theNumbaFlow
 
-# =============================================================================
-# The following is an improvement, but it is not the full solution.
-# I hope that the standardized markers, `metadata={'evaluateWhen': 'packaging'}` will help to automate
-# whatever needs to happen so that the following is well implemented.
-# @dataclasses.dataclass(frozen=True)
+# PackageSettings in theSSOT.py and immutability https://github.com/hunterhogan/mapFolding/issues/11
 @dataclasses.dataclass
 class PackageSettings:
+	"""
+	Centralized configuration settings for the mapFolding package.
+
+	This class implements the Single Source of Truth (SSOT) principle for package
+	configuration, providing a consistent interface for accessing package settings,
+	paths, and dispatch functions. The primary instance of this class, named `The`,
+	is imported and used throughout the package to retrieve configuration values.
+	"""
 
 	logicalPathModuleDispatcher: str | None = None
+	"""Logical import path to the module containing the dispatcher function."""
+
 	callableDispatcher: str | None = None
-	concurrencyPackage: str |None = None
+	"""Name of the function within the dispatcher module that will be called."""
+
+	concurrencyPackage: str | None = None
+	"""Package to use for concurrent execution (e.g., 'multiprocessing', 'numba')."""
+
+	# "Evaluate When Packaging" and "Evaluate When Installing" https://github.com/hunterhogan/mapFolding/issues/18
 	dataclassIdentifier: str = dataclasses.field(default='ComputationState', metadata={'evaluateWhen': 'packaging'})
+	"""Name of the dataclass used to track computation state."""
+
 	dataclassInstance: str = dataclasses.field(default='state', metadata={'evaluateWhen': 'packaging'})
+	"""Default variable name for instances of the computation state dataclass."""
+
 	dataclassInstanceTaskDistributionSuffix: str = dataclasses.field(default='Parallel', metadata={'evaluateWhen': 'packaging'})
+	"""Suffix added to dataclassInstance for parallel task distribution."""
+
 	dataclassModule: str = dataclasses.field(default='theSSOT', metadata={'evaluateWhen': 'packaging'})
+	"""Module containing the computation state dataclass definition."""
+
 	datatypePackage: str = dataclasses.field(default='numpy', metadata={'evaluateWhen': 'packaging'})
+	"""Package providing the numeric data types used in computation."""
+
 	fileExtension: str = dataclasses.field(default='.py', metadata={'evaluateWhen': 'installing'})
+	"""Default file extension for generated code files."""
+
 	packageName: str = dataclasses.field(default = packageNamePACKAGING, metadata={'evaluateWhen': 'packaging'})
-	pathPackage: Path = dataclasses.field(default_factory=getPathPackageINSTALLING, init=False, metadata={'evaluateWhen': 'installing'})
+	"""Name of this package, used for import paths and configuration."""
+
+	pathPackage: Path = dataclasses.field(default_factory=getPathPackageINSTALLING, metadata={'evaluateWhen': 'installing'})
+	"""Absolute path to the installed package directory."""
+
 	sourceAlgorithm: str = dataclasses.field(default='theDao', metadata={'evaluateWhen': 'packaging'})
+	"""Module containing the reference implementation of the algorithm."""
+
 	sourceCallableDispatcher: str = dataclasses.field(default='doTheNeedful', metadata={'evaluateWhen': 'packaging'})
+	"""Name of the function that dispatches computation in the source algorithm."""
+
 	sourceCallableInitialize: str = dataclasses.field(default='countInitialize', metadata={'evaluateWhen': 'packaging'})
+	"""Name of the function that initializes computation in the source algorithm."""
+
 	sourceCallableParallel: str = dataclasses.field(default='countParallel', metadata={'evaluateWhen': 'packaging'})
+	"""Name of the function that performs parallel computation in the source algorithm."""
+
 	sourceCallableSequential: str = dataclasses.field(default='countSequential', metadata={'evaluateWhen': 'packaging'})
+	"""Name of the function that performs sequential computation in the source algorithm."""
+
 	sourceConcurrencyManagerIdentifier: str = dataclasses.field(default='submit', metadata={'evaluateWhen': 'packaging'})
+	"""Method name used to submit tasks to the concurrency manager."""
+
 	sourceConcurrencyManagerNamespace: str = dataclasses.field(default='concurrencyManager', metadata={'evaluateWhen': 'packaging'})
+	"""Variable name used for the concurrency manager instance."""
+
 	sourceConcurrencyPackage: str = dataclasses.field(default='multiprocessing', metadata={'evaluateWhen': 'packaging'})
+	"""Default package used for concurrency in the source algorithm."""
+
+	dataclassInstanceTaskDistribution: str = dataclasses.field(default=None, metadata={'evaluateWhen': 'packaging'}) # pyright: ignore[reportAssignmentType]
+	"""Variable name for the parallel distribution instance of the computation state."""
 
-	dataclassInstanceTaskDistribution: str = dataclasses.field(init=False, metadata={'evaluateWhen': 'packaging'})
-	""" During parallel computation, this identifier helps to create deep copies of the dataclass instance. """
-	logicalPathModuleDataclass: str = dataclasses.field(init=False)
-	""" The package.module.name logical path to the dataclass. """
-	logicalPathModuleSourceAlgorithm: str = dataclasses.field(init=False)
-	""" The package.module.name logical path to the source algorithm. """
+	logicalPathModuleDataclass: str = dataclasses.field(default=None, metadata={'evaluateWhen': 'packaging'}) # pyright: ignore[reportAssignmentType]
+	"""Fully qualified import path to the module containing the computation state dataclass."""
 
-	@property # This is not a field, and that annoys me.
+	logicalPathModuleSourceAlgorithm: str = dataclasses.field(default=None, metadata={'evaluateWhen': 'packaging'}) # pyright: ignore[reportAssignmentType]
+	"""Fully qualified import path to the module containing the source algorithm."""
+
+	@property
 	def dispatcher(self) -> Callable[['ComputationState'], 'ComputationState']:
 		""" _The_ callable that connects `countFolds` to the logic that does the work."""
 		logicalPath: str = self.logicalPathModuleDispatcher or self.logicalPathModuleSourceAlgorithm
@@ -95,26 +135,20 @@ class PackageSettings:
 		return getattr(moduleImported, identifier)
 
 	def __post_init__(self) -> None:
-		self.dataclassInstanceTaskDistribution = self.dataclassInstance + self.dataclassInstanceTaskDistributionSuffix
+		if self.dataclassInstanceTaskDistribution is None: # pyright: ignore[reportUnnecessaryComparison]
+			self.dataclassInstanceTaskDistribution = self.dataclassInstance + self.dataclassInstanceTaskDistributionSuffix
 
-		self.logicalPathModuleDataclass = '.'.join([self.packageName, self.dataclassModule])
-		self.logicalPathModuleSourceAlgorithm = '.'.join([self.packageName, self.sourceAlgorithm])
+		if self.logicalPathModuleDataclass is None: # pyright: ignore[reportUnnecessaryComparison]
+			self.logicalPathModuleDataclass = '.'.join([self.packageName, self.dataclassModule])
+		if self.logicalPathModuleSourceAlgorithm is None: # pyright: ignore[reportUnnecessaryComparison]
+			self.logicalPathModuleSourceAlgorithm = '.'.join([self.packageName, self.sourceAlgorithm])
 
 The = PackageSettings(logicalPathModuleDispatcher=logicalPathModuleDispatcherHARDCODED, callableDispatcher=callableDispatcherHARDCODED, concurrencyPackage=concurrencyPackageHARDCODED)
 
-# To remove this function, I need to learn how to change "conftest.py" to patch this.
-def getPackageDispatcher() -> Callable[['ComputationState'], 'ComputationState']:
-	"""Get the dispatcher callable for the package.
-
-	This function retrieves the dispatcher callable for the package based on the
-	logical path module and callable dispatcher defined in the PackageSettings.
-	"""
-	return The.dispatcher
 # =============================================================================
 # Flexible Data Structure System Needs Enhanced Paradigm https://github.com/hunterhogan/mapFolding/issues/9
-# Efficient translation of Python scalar types to Numba types https://github.com/hunterhogan/mapFolding/issues/8
 
-numpyIntegerType = TypeVar('numpyIntegerType', bound=integer[Any], covariant=True)
+NumPyIntegerType = TypeVar('NumPyIntegerType', bound=integer[Any], covariant=True)
 
 DatatypeLeavesTotal: TypeAlias = int
 NumPyLeavesTotal: TypeAlias = numpy_int16 # this would be uint8, but mapShape (2,2,2,2, 2,2,2,2) has 256 leaves, so generic containers must accommodate at least 256 leaves
@@ -132,32 +166,92 @@ Array1DFoldsTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyFoldsTotal]]
 
 @dataclasses.dataclass
 class ComputationState:
-	mapShape: tuple[DatatypeLeavesTotal, ...] = dataclasses.field(init=True, metadata={'elementConstructor': 'DatatypeLeavesTotal'}) # NOTE Python is anti-DRY, again, `DatatypeLeavesTotal` needs to match the type
+	"""
+	Represents the complete state of a map folding computation.
+
+	This dataclass encapsulates all the information required to compute the number of
+	possible ways to fold a map, including the map dimensions, leaf connections,
+	computation progress, and fold counting. It serves as the central data structure
+	that flows through the entire computational algorithm.
+
+	Fields are categorized into:
+	1. Input parameters (mapShape, leavesTotal, etc.)
+	2. Core computational structures (connectionGraph, etc.)
+	3. Tracking variables for the folding algorithm state
+	4. Result accumulation fields (foldsTotal, groupsOfFolds)
+
+	The data structures and algorithms are based on Lunnon's 1971 paper on map folding.
+	"""
+	# NOTE Python is anti-DRY, again, `DatatypeLeavesTotal` metadata needs to match the type
+	mapShape: tuple[DatatypeLeavesTotal, ...] = dataclasses.field(init=True, metadata={'elementConstructor': 'DatatypeLeavesTotal'})
+	"""Dimensions of the map to be folded, as a tuple of integers."""
+
 	leavesTotal: DatatypeLeavesTotal
+	"""Total number of leaves (unit squares) in the map, equal to the product of all dimensions."""
+
 	taskDivisions: DatatypeLeavesTotal
+	"""Number of parallel tasks to divide the computation into. Zero means sequential computation."""
+
 	concurrencyLimit: DatatypeElephino
+	"""Maximum number of concurrent processes to use during computation."""
 
 	connectionGraph: Array3D = dataclasses.field(init=False, metadata={'dtype': Array3D.__args__[1].__args__[0]}) # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
+	"""3D array encoding the connections between leaves in all dimensions."""
+
 	dimensionsTotal: DatatypeLeavesTotal = dataclasses.field(init=False)
+	"""Total number of dimensions in the map shape."""
+
+	# I am using `dataclasses.field` metadata and `typeAlias.__args__[1].__args__[0]` to make the code more DRY. https://github.com/hunterhogan/mapFolding/issues/9
+	countDimensionsGapped: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Tracks how many dimensions are gapped for each leaf."""
+
+	dimensionsUnconstrained: DatatypeLeavesTotal = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Number of dimensions that are not constrained in the current folding state."""
+
+	gapRangeStart: Array1DElephino = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DElephino.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Starting index for the gap range for each leaf."""
 
-	countDimensionsGapped: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # type: ignore[arg-type, reportAssignmentType]
-	dimensionsUnconstrained: DatatypeLeavesTotal = dataclasses.field(default=None, init=True) # type: ignore[assignment, reportAssignmentType]
-	gapRangeStart: Array1DElephino = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DElephino.__args__[1].__args__[0]}) # type: ignore[arg-type, reportAssignmentType]
-	gapsWhere: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # type: ignore[arg-type, reportAssignmentType]
-	leafAbove: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # type: ignore[arg-type, reportAssignmentType]
-	leafBelow: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # type: ignore[arg-type, reportAssignmentType]
-	foldGroups: Array1DFoldsTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DFoldsTotal.__args__[1].__args__[0]}) # type: ignore[arg-type, reportAssignmentType]
+	gapsWhere: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Tracks where gaps occur in the folding pattern."""
+
+	leafAbove: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""For each leaf, stores the index of the leaf above it in the folding pattern."""
+
+	leafBelow: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""For each leaf, stores the index of the leaf below it in the folding pattern."""
+
+	foldGroups: Array1DFoldsTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DFoldsTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Accumulator for fold groups across parallel tasks."""
 
 	foldsTotal: DatatypeFoldsTotal = DatatypeFoldsTotal(0)
+	"""The final computed total number of distinct folding patterns."""
+
 	gap1ndex: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+	"""Current index into gaps array during algorithm execution."""
+
 	gap1ndexCeiling: DatatypeElephino = DatatypeElephino(0)
+	"""Upper limit for gap index during the current algorithm phase."""
+
 	groupsOfFolds: DatatypeFoldsTotal = dataclasses.field(default=DatatypeFoldsTotal(0), metadata={'theCountingIdentifier': True})
+	"""Accumulator for the number of fold groups found during computation."""
+
 	indexDimension: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+	"""Current dimension being processed during algorithm execution."""
+
 	indexLeaf: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+	"""Current leaf index during iteration."""
+
 	indexMiniGap: DatatypeElephino = DatatypeElephino(0)
+	"""Index used when filtering common gaps."""
+
 	leaf1ndex: DatatypeElephino = DatatypeElephino(1)
+	"""Active leaf being processed in the folding algorithm. Starts at 1, not 0."""
+
 	leafConnectee: DatatypeElephino = DatatypeElephino(0)
+	"""Leaf that is being connected to the active leaf."""
+
 	taskIndex: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+	"""Index of the current parallel task when using task divisions."""
 
 	def __post_init__(self) -> None:
 		from mapFolding.beDRY import getConnectionGraph, makeDataContainer
@@ -165,24 +259,22 @@ class ComputationState:
 		leavesTotalAsInt = int(self.leavesTotal)
 		self.connectionGraph = getConnectionGraph(self.mapShape, leavesTotalAsInt, self.__dataclass_fields__['connectionGraph'].metadata['dtype'])
 
-		if self.dimensionsUnconstrained is None: # type: ignore
-			self.dimensionsUnconstrained = DatatypeLeavesTotal(int(self.dimensionsTotal))
+		if self.dimensionsUnconstrained is None: self.dimensionsUnconstrained = DatatypeLeavesTotal(int(self.dimensionsTotal)) # pyright: ignore[reportUnnecessaryComparison]
 
-		if self.foldGroups is None: # type: ignore
+		if self.foldGroups is None: # pyright: ignore[reportUnnecessaryComparison]
 			self.foldGroups = makeDataContainer(max(2, int(self.taskDivisions) + 1), self.__dataclass_fields__['foldGroups'].metadata['dtype'])
 			self.foldGroups[-1] = self.leavesTotal
 
-		if self.gapsWhere is None: self.gapsWhere = makeDataContainer(leavesTotalAsInt * leavesTotalAsInt + 1, self.__dataclass_fields__['gapsWhere'].metadata['dtype']) # type: ignore
+		# Dataclasses, Default factories, and arguments in `ComputationState` https://github.com/hunterhogan/mapFolding/issues/12
+		if self.gapsWhere is None: self.gapsWhere = makeDataContainer(leavesTotalAsInt * leavesTotalAsInt + 1, self.__dataclass_fields__['gapsWhere'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
 
-		if self.countDimensionsGapped is None: self.countDimensionsGapped = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['countDimensionsGapped'].metadata['dtype']) # type: ignore
-		if self.gapRangeStart is None: self.gapRangeStart = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['gapRangeStart'].metadata['dtype']) # type: ignore
-		if self.leafAbove is None: self.leafAbove = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafAbove'].metadata['dtype']) # type: ignore
-		if self.leafBelow is None: self.leafBelow = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafBelow'].metadata['dtype']) # type: ignore
+		if self.countDimensionsGapped is None: self.countDimensionsGapped = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['countDimensionsGapped'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
+		if self.gapRangeStart is None: self.gapRangeStart = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['gapRangeStart'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
+		if self.leafAbove is None: self.leafAbove = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafAbove'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
+		if self.leafBelow is None: self.leafBelow = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafBelow'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
 
+	# Automatic, or not, calculation in dataclass `ComputationState` https://github.com/hunterhogan/mapFolding/issues/14
 	def getFoldsTotal(self) -> None:
 		self.foldsTotal = DatatypeFoldsTotal(self.foldGroups[0:-1].sum() * self.leavesTotal)
 
-# =============================================================================
-# The coping way.
-
 class raiseIfNoneGitHubIssueNumber3(Exception): pass

mapFolding/toolboxFilesystem.py

@@ -22,7 +22,7 @@ The functions here adhere to a consistent approach to path handling:
 - Progressive fallback strategies for saving critical computation results.
 - Preemptive filesystem validation to detect issues before computation begins.
 """
-from mapFolding.theSSOT import The
+from mapFolding import The
 from os import PathLike
 from pathlib import Path, PurePath
 from sys import modules as sysModules

mapfolding-0.9.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,46 @@
+mapFolding/__init__.py,sha256=TXCWanI9snueVZMTtjLNpvG4um7vyPXmJeIvvrBuJCA,3887
+mapFolding/basecamp.py,sha256=L0eduDE8-5SnEYpnI-GHs-am4ico9kEn75SuOUgibZ8,4770
+mapFolding/beDRY.py,sha256=cWMHETsTofpGMKmbEB3E8NiiujmyYOVq0HW-VqI3-Pk,15272
+mapFolding/oeis.py,sha256=qgmlMbqDZ1O3DKrhKttm2J0Lwm9iGGKqLhwJQNULLGM,16995
+mapFolding/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mapFolding/theDao.py,sha256=MVopt1LzhdIQYA97SEoq9bdzct6hbK0lEyPxBAAlVTc,9934
+mapFolding/theSSOT.py,sha256=20Z0Cs2Sj5EZPFXE6dT_rb6iH6DTBVq-gaysemQTVPc,16829
+mapFolding/toolboxFilesystem.py,sha256=5RZ9CshZwgjejH_sMG4_Kk4JX3QJLkK30OqFeL5jFWg,9974
+mapFolding/reference/__init__.py,sha256=UIEU8BJR_YDzjFQcLel3XtHzOCJiOUGlGiWzOzbvhik,2206
+mapFolding/reference/flattened.py,sha256=QK1xG9SllqCoi68e86Hyl9d9ATUAAFNpTQI-3zmcp5I,16072
+mapFolding/reference/hunterNumba.py,sha256=iLfyqwGdAh6c5GbapnKsWhAsNsR3O-fyGGHAdohluLw,7258
+mapFolding/reference/irvineJavaPort.py,sha256=UEfIX4QbPLl5jnyfYIyX5YRR3_rYvPUikK8jLehsFko,4076
+mapFolding/reference/jaxCount.py,sha256=TuDNKOnyhQfuixKmIxO9Algv7dvy7KMGhgsV3h96FGE,14853
+mapFolding/reference/lunnanNumpy.py,sha256=mMgrgbrBpe4nmo72ThEI-MGH0OwEHmfMPczSXHp2qKo,4357
+mapFolding/reference/lunnanWhile.py,sha256=ZL8GAQtPs5nJZSgoDl5USrLSS_zs03y98y1Z9E4jOmQ,3799
+mapFolding/reference/rotatedEntryPoint.py,sha256=5ughpKUT2JQhoAKgoDUdYNjgWQYPGV8v-7dWEAdDmfE,10274
+mapFolding/reference/total_countPlus1vsPlusN.py,sha256=yJZAVLVdoXqHag2_N6_6CT-Q6HXBgRro-eny93-Rlpw,9307
+mapFolding/reference/jobsCompleted/__init__.py,sha256=TU93ZGUW1xEkT6d9mQFn_rp5DvRy0ZslEB2Q6MF5ZDc,2596
+mapFolding/reference/jobsCompleted/[2x19]/p2x19.py,sha256=_tvYtfzMWVo2VtUbIAieoscb4N8FFflgTdW4-ljBUuA,19626
+mapFolding/reference/jobsCompleted/p2x19/p2x19.py,sha256=eZEw4Me4ocTt6VXoK2-Sbd5SowZtxRIbN9dZmc7OCVg,6395
+mapFolding/someAssemblyRequired/__init__.py,sha256=ZtYMGjxMnl1mnwSLSBm73meaXP1P_MBd4RlAwlOyRXY,3318
+mapFolding/someAssemblyRequired/_theTypes.py,sha256=YFiQI6zsrFNruvqGDXHJVH0OWXsOj9EwDrt4G59OVHA,3995
+mapFolding/someAssemblyRequired/_tool_Make.py,sha256=-ISVrr09mYuo5dhJfjYs38jhSd_IjYPrheGC6RWUmBI,7373
+mapFolding/someAssemblyRequired/_tool_Then.py,sha256=uc1of9ZPCp5Vrh5Qg80giatGHwT9wRzW3dWaKxGYQsg,4125
+mapFolding/someAssemblyRequired/_toolboxAntecedents.py,sha256=bK5IDfHZ_p1p4rhQ1Q21FM4J8i9Yl6gD7mAOw6NJahU,10591
+mapFolding/someAssemblyRequired/_toolboxContainers.py,sha256=yIad3WTL60qGdLd87Wr-FJccNyhGLD3tsFJGA0sdknU,24183
+mapFolding/someAssemblyRequired/_toolboxPython.py,sha256=dkEWp4-SAc8xe-pkeCXh6iVUSolSlXSFCBun1Asn1gE,7639
+mapFolding/someAssemblyRequired/getLLVMforNoReason.py,sha256=9RPU6vK_eUg64GtVFI_nZnvUryXw8gfHJs9NyDYHIvg,2745
+mapFolding/someAssemblyRequired/synthesizeNumbaJob.py,sha256=7jwUcHpZk3T_PoFgLtZhYayx5VbJP1f15a2JPlZegFI,14453
+mapFolding/someAssemblyRequired/toolboxNumba.py,sha256=GkBmcztmGSwm2bolK76FPPdc2c9AWrtMGztgZb3rS7Y,24381
+mapFolding/someAssemblyRequired/transformationTools.py,sha256=bI8ApAb-Z-VIdRa-ORQilnT6LjejTPeTyC5nOrpDz94,23323
+mapFolding/syntheticModules/__init__.py,sha256=evVFqhCGa-WZKDiLcnQWjs-Bj34eRnfSLqz_d7dFYZY,83
+mapFolding/syntheticModules/numbaCount_doTheNeedful.py,sha256=vSqV1WbyZ0mXg2TNgMR9EndiitVKM8GQa72ijOUCEZ8,15659
+mapfolding-0.9.0.dist-info/licenses/LICENSE,sha256=NxH5Y8BdC-gNU-WSMwim3uMbID2iNDXJz7fHtuTdXhk,19346
+tests/__init__.py,sha256=UIvSWWz_anRXBELKPOdhfRoZ4hArHQTvghHrRquDHHw,1940
+tests/conftest.py,sha256=G8vhDSTdTbYZUFBUKLFOUOzDL1Ja6NVZmICCh4biZas,14298
+tests/test_computations.py,sha256=oT2f_7Hzis3dLgOmfzlA_I-5fG3D0NURWab0rZkARfc,6152
+tests/test_filesystem.py,sha256=T2DkjBoI3lW6tCxd5BilPmUFrVukNKLjOOZVZxLM560,3004
+tests/test_oeis.py,sha256=uxvwmgbnylSDdsVJfuAT0LuYLbIVFwSgdLxHm-xUGBM,5043
+tests/test_other.py,sha256=zZmSZpcNsk4oeD4EHNLMNtmiz9hnwwoV62DFSQrLKwo,4258
+tests/test_tasks.py,sha256=yrExYvFP23TEA3ta0IotMNmi59rwQ3Y9hA3fwvIhxTE,2851
+mapfolding-0.9.0.dist-info/METADATA,sha256=yjarli2blxeiwu9i1nFOrPT6gevc6YRzIbDy8KMbbr4,7445
+mapfolding-0.9.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+mapfolding-0.9.0.dist-info/entry_points.txt,sha256=F3OUeZR1XDTpoH7k3wXuRb3KF_kXTTeYhu5AGK1SiOQ,146
+mapfolding-0.9.0.dist-info/top_level.txt,sha256=1gP2vFaqPwHujGwb3UjtMlLEGN-943VSYFR7V4gDqW8,17
+mapfolding-0.9.0.dist-info/RECORD,,

tests/__init__.py

@@ -0,0 +1,44 @@
+"""
+Map Folding Test Suite and Validation Framework
+
+This test suite provides comprehensive testing capabilities for the mapFolding package
+and its optimization framework. It is specifically designed to enable both package
+maintenance and custom extension testing, making it easy for users to validate their
+own recipe configurations and job implementations.
+
+## Key Testing Capabilities
+
+1. **Algorithm Validation**
+   - Tests core algorithm correctness against known OEIS sequence values
+   - Validates both sequential and parallel execution paths
+   - Ensures consistency across different implementation strategies
+
+2. **Code Generation Testing**
+   - Tests the AST transformation pipeline from source to optimized implementations
+   - Validates that generated Numba-accelerated modules produce correct results
+   - Ensures robust code generation across different parameter sets
+
+3. **Job-Specific Testing**
+   - Tests specialized job module generation for specific map shapes
+   - Validates execution of the generated modules
+   - Verifies correct output file creation and value storage
+
+## Testing Your Own Implementations
+
+This suite is designed to make it easy to test your custom recipes and jobs:
+
+### For Custom Recipes (RecipeSynthesizeFlow):
+Copy and adapt the `syntheticDispatcherFixture` and associated tests from
+`test_computations.py` to validate your customized code transformation pipelines.
+
+### For Custom Jobs (RecipeJob):
+Copy and adapt the `test_writeJobNumba` function to test specialized job modules
+for specific map shapes with your custom configurations.
+
+The entire test infrastructure is built on fixtures and utilities that handle
+complex setup and validation, allowing you to focus on your implementation details
+while leveraging the existing validation framework.
+
+See the module docstrings in `test_computations.py` and `conftest.py` for detailed
+guidance on adapting these tests for your own purposes.
+"""