mapFolding 0.8.6__py3-none-any.whl → 0.9.1__py3-none-any.whl

mapFolding/syntheticModules/{numbaCount_doTheNeedful.py → numbaCount.py}

@@ -47,7 +47,7 @@ def countInitialize(state: ComputationState) -> ComputationState:
     return state
 
 @jit(_nrt=True, boundscheck=False, cache=True, error_model='numpy', fastmath=True, forceinline=True, inline='always', looplift=False, no_cfunc_wrapper=False, no_cpython_wrapper=False, nopython=True, parallel=False)
-def countParallel(mapShape: tuple[DatatypeLeavesTotal, ...], leavesTotal: DatatypeLeavesTotal, taskDivisions: DatatypeLeavesTotal, concurrencyLimit: DatatypeElephino, connectionGraph: Array3D, dimensionsTotal: DatatypeLeavesTotal, countDimensionsGapped: Array1DLeavesTotal, dimensionsUnconstrained: DatatypeLeavesTotal, gapRangeStart: Array1DElephino, gapsWhere: Array1DLeavesTotal, leafAbove: Array1DLeavesTotal, leafBelow: Array1DLeavesTotal, foldGroups: Array1DFoldsTotal, foldsTotal: DatatypeFoldsTotal, gap1ndex: DatatypeLeavesTotal, gap1ndexCeiling: DatatypeElephino, groupsOfFolds: DatatypeFoldsTotal, indexDimension: DatatypeLeavesTotal, indexLeaf: DatatypeLeavesTotal, indexMiniGap: DatatypeElephino, leaf1ndex: DatatypeElephino, leafConnectee: DatatypeElephino, taskIndex: DatatypeLeavesTotal) -> DatatypeFoldsTotal:
+def countParallel(mapShape: tuple[DatatypeLeavesTotal, ...], leavesTotal: DatatypeLeavesTotal, taskDivisions: DatatypeLeavesTotal, concurrencyLimit: DatatypeElephino, connectionGraph: Array3D, dimensionsTotal: DatatypeLeavesTotal, countDimensionsGapped: Array1DLeavesTotal, dimensionsUnconstrained: DatatypeLeavesTotal, gapRangeStart: Array1DElephino, gapsWhere: Array1DLeavesTotal, leafAbove: Array1DLeavesTotal, leafBelow: Array1DLeavesTotal, foldGroups: Array1DFoldsTotal, foldsTotal: DatatypeFoldsTotal, gap1ndex: DatatypeLeavesTotal, gap1ndexCeiling: DatatypeElephino, groupsOfFolds: DatatypeFoldsTotal, indexDimension: DatatypeLeavesTotal, indexLeaf: DatatypeLeavesTotal, indexMiniGap: DatatypeElephino, leaf1ndex: DatatypeLeavesTotal, leafConnectee: DatatypeElephino, taskIndex: DatatypeLeavesTotal) -> DatatypeFoldsTotal:
     while leaf1ndex > 0:
         if leaf1ndex <= 1 or leafBelow[0] == 1:
             if leaf1ndex > leavesTotal:
@@ -92,7 +92,7 @@ def countParallel(mapShape: tuple[DatatypeLeavesTotal, ...], leavesTotal: Dataty
     return groupsOfFolds
 
 @jit(_nrt=True, boundscheck=False, cache=True, error_model='numpy', fastmath=True, forceinline=True, inline='always', looplift=False, no_cfunc_wrapper=False, no_cpython_wrapper=False, nopython=True, parallel=False)
-def countSequential(mapShape: tuple[DatatypeLeavesTotal, ...], leavesTotal: DatatypeLeavesTotal, taskDivisions: DatatypeLeavesTotal, concurrencyLimit: DatatypeElephino, connectionGraph: Array3D, dimensionsTotal: DatatypeLeavesTotal, countDimensionsGapped: Array1DLeavesTotal, dimensionsUnconstrained: DatatypeLeavesTotal, gapRangeStart: Array1DElephino, gapsWhere: Array1DLeavesTotal, leafAbove: Array1DLeavesTotal, leafBelow: Array1DLeavesTotal, foldGroups: Array1DFoldsTotal, foldsTotal: DatatypeFoldsTotal, gap1ndex: DatatypeLeavesTotal, gap1ndexCeiling: DatatypeElephino, groupsOfFolds: DatatypeFoldsTotal, indexDimension: DatatypeLeavesTotal, indexLeaf: DatatypeLeavesTotal, indexMiniGap: DatatypeElephino, leaf1ndex: DatatypeElephino, leafConnectee: DatatypeElephino, taskIndex: DatatypeLeavesTotal) -> tuple[tuple[DatatypeLeavesTotal, ...], DatatypeLeavesTotal, DatatypeLeavesTotal, DatatypeElephino, Array3D, DatatypeLeavesTotal, Array1DLeavesTotal, DatatypeLeavesTotal, Array1DElephino, Array1DLeavesTotal, Array1DLeavesTotal, Array1DLeavesTotal, Array1DFoldsTotal, DatatypeFoldsTotal, DatatypeLeavesTotal, DatatypeElephino, DatatypeFoldsTotal, DatatypeLeavesTotal, DatatypeLeavesTotal, DatatypeElephino, DatatypeElephino, DatatypeElephino, DatatypeLeavesTotal]:
+def countSequential(mapShape: tuple[DatatypeLeavesTotal, ...], leavesTotal: DatatypeLeavesTotal, taskDivisions: DatatypeLeavesTotal, concurrencyLimit: DatatypeElephino, connectionGraph: Array3D, dimensionsTotal: DatatypeLeavesTotal, countDimensionsGapped: Array1DLeavesTotal, dimensionsUnconstrained: DatatypeLeavesTotal, gapRangeStart: Array1DElephino, gapsWhere: Array1DLeavesTotal, leafAbove: Array1DLeavesTotal, leafBelow: Array1DLeavesTotal, foldGroups: Array1DFoldsTotal, foldsTotal: DatatypeFoldsTotal, gap1ndex: DatatypeLeavesTotal, gap1ndexCeiling: DatatypeElephino, groupsOfFolds: DatatypeFoldsTotal, indexDimension: DatatypeLeavesTotal, indexLeaf: DatatypeLeavesTotal, indexMiniGap: DatatypeElephino, leaf1ndex: DatatypeLeavesTotal, leafConnectee: DatatypeElephino, taskIndex: DatatypeLeavesTotal) -> tuple[tuple[DatatypeLeavesTotal, ...], DatatypeLeavesTotal, DatatypeLeavesTotal, DatatypeElephino, Array3D, DatatypeLeavesTotal, Array1DLeavesTotal, DatatypeLeavesTotal, Array1DElephino, Array1DLeavesTotal, Array1DLeavesTotal, Array1DLeavesTotal, Array1DFoldsTotal, DatatypeFoldsTotal, DatatypeLeavesTotal, DatatypeElephino, DatatypeFoldsTotal, DatatypeLeavesTotal, DatatypeLeavesTotal, DatatypeElephino, DatatypeLeavesTotal, DatatypeElephino, DatatypeLeavesTotal]:
     while leaf1ndex > 0:
         if leaf1ndex <= 1 or leafBelow[0] == 1:
             if leaf1ndex > leavesTotal:
@@ -124,6 +124,9 @@ def countSequential(mapShape: tuple[DatatypeLeavesTotal, ...], leavesTotal: Data
             leaf1ndex -= 1
             leafBelow[leafAbove[leaf1ndex]] = leafBelow[leaf1ndex]
             leafAbove[leafBelow[leaf1ndex]] = leafAbove[leaf1ndex]
+        if groupsOfFolds and leaf1ndex == 3:
+            groupsOfFolds *= 2
+            break
         if leaf1ndex > 0:
             gap1ndex -= 1
             leafAbove[leaf1ndex] = gapsWhere[gap1ndex]
@@ -164,7 +167,7 @@ def doTheNeedful(state: ComputationState) -> ComputationState:
                 indexDimension: DatatypeLeavesTotal = state.indexDimension
                 indexLeaf: DatatypeLeavesTotal = state.indexLeaf
                 indexMiniGap: DatatypeElephino = state.indexMiniGap
-                leaf1ndex: DatatypeElephino = state.leaf1ndex
+                leaf1ndex: DatatypeLeavesTotal = state.leaf1ndex
                 leafConnectee: DatatypeElephino = state.leafConnectee
                 taskIndex: DatatypeLeavesTotal = state.taskIndex
                 dictionaryConcurrency[indexSherpa] = concurrencyManager.submit(countParallel, mapShape, leavesTotal, taskDivisions, concurrencyLimit, connectionGraph, dimensionsTotal, countDimensionsGapped, dimensionsUnconstrained, gapRangeStart, gapsWhere, leafAbove, leafBelow, foldGroups, foldsTotal, gap1ndex, gap1ndexCeiling, groupsOfFolds, indexDimension, indexLeaf, indexMiniGap, leaf1ndex, leafConnectee, taskIndex)
@@ -192,7 +195,7 @@ def doTheNeedful(state: ComputationState) -> ComputationState:
         indexDimension: DatatypeLeavesTotal = state.indexDimension
         indexLeaf: DatatypeLeavesTotal = state.indexLeaf
         indexMiniGap: DatatypeElephino = state.indexMiniGap
-        leaf1ndex: DatatypeElephino = state.leaf1ndex
+        leaf1ndex: DatatypeLeavesTotal = state.leaf1ndex
         leafConnectee: DatatypeElephino = state.leafConnectee
         taskIndex: DatatypeLeavesTotal = state.taskIndex
         mapShape, leavesTotal, taskDivisions, concurrencyLimit, connectionGraph, dimensionsTotal, countDimensionsGapped, dimensionsUnconstrained, gapRangeStart, gapsWhere, leafAbove, leafBelow, foldGroups, foldsTotal, gap1ndex, gap1ndexCeiling, groupsOfFolds, indexDimension, indexLeaf, indexMiniGap, leaf1ndex, leafConnectee, taskIndex = countSequential(mapShape, leavesTotal, taskDivisions, concurrencyLimit, connectionGraph, dimensionsTotal, countDimensionsGapped, dimensionsUnconstrained, gapRangeStart, gapsWhere, leafAbove, leafBelow, foldGroups, foldsTotal, gap1ndex, gap1ndexCeiling, groupsOfFolds, indexDimension, indexLeaf, indexMiniGap, leaf1ndex, leafConnectee, taskIndex)

mapFolding/theDao.py

@@ -43,12 +43,6 @@ def activeLeafIsTheFirstLeaf(state: ComputationState) -> bool:
 def allDimensionsAreUnconstrained(state: ComputationState) -> bool:
 	return not state.dimensionsUnconstrained
 
-def undoLastLeafPlacement(state: ComputationState) -> ComputationState:
-	state.leaf1ndex -= 1
-	state.leafBelow[state.leafAbove[state.leaf1ndex]] = state.leafBelow[state.leaf1ndex]
-	state.leafAbove[state.leafBelow[state.leaf1ndex]] = state.leafAbove[state.leaf1ndex]
-	return state
-
 def countGaps(state: ComputationState) -> ComputationState:
 	state.gapsWhere[state.gap1ndexCeiling] = state.leafConnectee
 	if state.countDimensionsGapped[state.leafConnectee] == 0:
@@ -100,6 +94,16 @@ def initializeVariablesToFindGaps(state: ComputationState) -> ComputationState:
 	state.indexDimension = 0
 	return state
 
+def insertLeafAtGap(state: ComputationState) -> ComputationState:
+	state.gap1ndex -= 1
+	state.leafAbove[state.leaf1ndex] = state.gapsWhere[state.gap1ndex]
+	state.leafBelow[state.leaf1ndex] = state.leafBelow[state.leafAbove[state.leaf1ndex]]
+	state.leafBelow[state.leafAbove[state.leaf1ndex]] = state.leaf1ndex
+	state.leafAbove[state.leafBelow[state.leaf1ndex]] = state.leaf1ndex
+	state.gapRangeStart[state.leaf1ndex] = state.gap1ndex
+	state.leaf1ndex += 1
+	return state
+
 def insertUnconstrainedLeaf(state: ComputationState) -> ComputationState:
 	state.indexLeaf = 0
 	while state.indexLeaf < state.leaf1ndex:
@@ -123,22 +127,18 @@ def loopUpToDimensionsTotal(state: ComputationState) -> bool:
 def noGapsHere(state: ComputationState) -> bool:
 	return (state.leaf1ndex > 0) and (state.gap1ndex == state.gapRangeStart[state.leaf1ndex - 1])
 
-def insertLeafAtGap(state: ComputationState) -> ComputationState:
-	state.gap1ndex -= 1
-	state.leafAbove[state.leaf1ndex] = state.gapsWhere[state.gap1ndex]
-	state.leafBelow[state.leaf1ndex] = state.leafBelow[state.leafAbove[state.leaf1ndex]]
-	state.leafBelow[state.leafAbove[state.leaf1ndex]] = state.leaf1ndex
-	state.leafAbove[state.leafBelow[state.leaf1ndex]] = state.leaf1ndex
-	state.gapRangeStart[state.leaf1ndex] = state.gap1ndex
-	state.leaf1ndex += 1
-	return state
-
 def thereIsAnActiveLeaf(state: ComputationState) -> bool:
 	return state.leaf1ndex > 0
 
 def thisIsMyTaskIndex(state: ComputationState) -> bool:
 	return (state.leaf1ndex != state.taskDivisions) or (state.leafConnectee % state.taskDivisions == state.taskIndex)
 
+def undoLastLeafPlacement(state: ComputationState) -> ComputationState:
+	state.leaf1ndex -= 1
+	state.leafBelow[state.leafAbove[state.leaf1ndex]] = state.leafBelow[state.leaf1ndex]
+	state.leafAbove[state.leafBelow[state.leaf1ndex]] = state.leafAbove[state.leaf1ndex]
+	return state
+
 def updateLeafConnectee(state: ComputationState) -> ComputationState:
 	state.leafConnectee = state.connectionGraph[state.indexDimension, state.leaf1ndex, state.leafBelow[state.leafConnectee]]
 	return state
@@ -218,6 +218,9 @@ def countSequential(state: ComputationState) -> ComputationState:
 					state = incrementIndexMiniGap(state)
 		while noGapsHere(state):
 			state = undoLastLeafPlacement(state)
+		if state.groupsOfFolds and state.leaf1ndex == 3:
+			state.groupsOfFolds *= 2
+			break
 		if thereIsAnActiveLeaf(state):
 			state = insertLeafAtGap(state)
 	state.foldGroups[state.taskIndex] = state.groupsOfFolds

mapFolding/theSSOT.py

@@ -19,74 +19,115 @@ to avoid namespace collisions when transforming algorithms.
 from collections.abc import Callable
 from importlib import import_module as importlib_import_module
 from inspect import getfile as inspect_getfile
-from numpy import dtype, int64 as numpy_int64, int16 as numpy_int16, integer, ndarray
+from numpy import dtype, int64 as numpy_int64, int16 as numpy_int16, integer, ndarray, uint8 as numpy_uint8
 from pathlib import Path
 from tomli import load as tomli_load
 from types import ModuleType
 from typing import Any, TypeAlias, TypeVar
 import dataclasses
+from numba import int64, uint8
 
-# =============================================================================
-# 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'
+logicalPathModuleDispatcherHARDCODED: str = 'mapFolding.syntheticModules.numbaCount'
 callableDispatcherHARDCODED: str = 'doTheNeedful'
 concurrencyPackageHARDCODED = 'multiprocessing'
+# from mapFolding.someAssemblyRequired.toolboxNumba.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(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. """
+	dataclassInstanceTaskDistribution: str = dataclasses.field(default=None, metadata={'evaluateWhen': 'packaging'}) # pyright: ignore[reportAssignmentType]
+	"""Variable name for the parallel distribution instance of the computation state."""
 
-	@property # This is not a field, and that annoys me.
+	logicalPathModuleDataclass: str = dataclasses.field(default=None, metadata={'evaluateWhen': 'packaging'}) # pyright: ignore[reportAssignmentType]
+	"""Fully qualified import path to the module containing the computation state dataclass."""
+
+	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,35 +136,36 @@ 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
 
-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
+# DatatypeLeavesTotal: TypeAlias = int
+NumPyLeavesTotal: TypeAlias = numpy_uint8
+# 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
 
-DatatypeElephino: TypeAlias = int
-NumPyElephino: TypeAlias = numpy_int16
+# DatatypeElephino: TypeAlias = int
+NumPyElephino: TypeAlias = numpy_uint8
+# NumPyElephino: TypeAlias = numpy_int16
 
-DatatypeFoldsTotal: TypeAlias = int
+# DatatypeFoldsTotal: TypeAlias = int
 NumPyFoldsTotal: TypeAlias = numpy_int64
 
+DatatypeLeavesTotal = uint8
+DatatypeElephino = uint8
+DatatypeFoldsTotal = int64
+
 Array3D: TypeAlias = ndarray[tuple[int, int, int], dtype[NumPyLeavesTotal]]
 Array1DLeavesTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyLeavesTotal]]
 Array1DElephino: TypeAlias = ndarray[tuple[int], dtype[NumPyElephino]]
@@ -131,57 +173,118 @@ 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."""
+
+	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."""
 
-	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]
+	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)
-	leaf1ndex: DatatypeElephino = DatatypeElephino(1)
+	"""Index used when filtering common gaps."""
+
+	leaf1ndex: DatatypeLeavesTotal = DatatypeLeavesTotal(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."""
+
+	# leafSequence: list[DatatypeLeavesTotal] = dataclasses.field(default_factory=list, metadata={'elementConstructor': 'DatatypeLeavesTotal'})
+
 	taskIndex: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+	"""Index of the current parallel task when using task divisions."""
 
 	def __post_init__(self) -> None:
+		# self.leafSequence = [self.leaf1ndex]
 		from mapFolding.beDRY import getConnectionGraph, makeDataContainer
 		self.dimensionsTotal = DatatypeLeavesTotal(len(self.mapShape))
 		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.1.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: mapFolding
+Version: 0.9.1
+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/)