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

mapFolding/__init__.py

@@ -11,36 +11,83 @@ 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
+    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
+    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
+    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
+    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)
+    - 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.
 """
-from mapFolding.basecamp import countFolds
-from mapFolding.oeis import clearOEIScache, getOEISids, OEIS_for_n, oeisIDfor_n
 
 __all__ = [
-    'clearOEIScache',
-    'countFolds',
-    'getOEISids',
-    'OEIS_for_n',
-    'oeisIDfor_n',
+        '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/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/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.
 
@@ -331,8 +331,7 @@ def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
 	ValueError
 		If the input is empty or contains negative values.
 	NotImplementedError
-		If fewer than two positive dimensions are provided, as this would not
-		represent a valid map folding problem.
+		If fewer than two positive dimensions are provided.
 	"""
 	if not listDimensions:
 		raise ValueError("`listDimensions` is a required parameter.")

mapFolding/oeis.py

@@ -22,8 +22,7 @@ implementation in the package.
 from collections.abc import Callable
 from datetime import datetime, timedelta
 from functools import cache
-from mapFolding.theSSOT import The
-from mapFolding.toolboxFilesystem import writeStringToHere
+from mapFolding import writeStringToHere, The
 from pathlib import Path
 from typing import Any, Final, TYPE_CHECKING
 import argparse
@@ -60,14 +59,20 @@ class SettingsOEIShardcodedValues(TypedDict):
 	valuesTestValidation: list[int]
 
 settingsOEIShardcodedValues: dict[str, SettingsOEIShardcodedValues] = {
+	'A000136': {
+		'getMapShape': lambda n: tuple(sorted([1, n])),
+		'valuesBenchmark': [14],
+		'valuesTestParallelization': [*range(3, 7)],
+		'valuesTestValidation': [random.randint(2, 9)],
+	},
 	'A001415': {
-		'getMapShape': lambda n: (2, n) if n >= 2 else (n, 2),
+		'getMapShape': lambda n: tuple(sorted([2, n])),
 		'valuesBenchmark': [14],
 		'valuesTestParallelization': [*range(3, 7)],
 		'valuesTestValidation': [random.randint(2, 9)],
 	},
 	'A001416': {
-		'getMapShape': lambda n: (3, n) if n >= 3 else (n, 3),
+		'getMapShape': lambda n: tuple(sorted([3, n])),
 		'valuesBenchmark': [9],
 		'valuesTestParallelization': [*range(3, 5)],
 		'valuesTestValidation': [random.randint(2, 6)],
@@ -149,9 +154,9 @@ def _parseBFileOEIS(OEISbFile: str, oeisID: str) -> dict[int, int]:
 		sequence ID or if the content format is invalid.
 	"""
 	bFileLines: list[str] = OEISbFile.strip().splitlines()
-	if not bFileLines.pop(0).startswith(f"# {oeisID}"):
-		warnings.warn(f"Content does not match sequence {oeisID}")
-		return {-1: -1}
+	# if not bFileLines.pop(0).startswith(f"# {oeisID}"):
+	# 	warnings.warn(f"Content does not match sequence {oeisID}")
+	# 	return {-1: -1}
 
 	OEISsequence: dict[int, int] = {}
 	for line in bFileLines:
@@ -162,6 +167,27 @@ def _parseBFileOEIS(OEISbFile: str, oeisID: str) -> dict[int, int]:
 	return OEISsequence
 
 def getOEISofficial(pathFilenameCache: Path, url: str) -> None | str:
+	"""
+	Retrieve OEIS sequence data from cache or online source.
+
+	This function implements a caching strategy for OEIS sequence data, first checking
+	if a local cached copy exists and is not expired. If a valid cache exists, it returns
+	the cached content; otherwise, it fetches the data from the OEIS website and
+	writes it to the cache for future use.
+
+	Parameters:
+		pathFilenameCache: Path to the local cache file.
+		url: URL to retrieve the OEIS sequence data from if cache is invalid or missing.
+
+	Returns:
+		oeisInformation: The retrieved OEIS sequence information as a string, or None if
+		the information could not be retrieved.
+
+	Notes:
+		The cache expiration period is controlled by the global `cacheDays` variable.
+		If the function fails to retrieve data from both cache and online source,
+		it will return None and issue a warning.
+	"""
 	tryCache: bool = False
 	if pathFilenameCache.exists():
 		fileAge: timedelta = datetime.now() - datetime.fromtimestamp(pathFilenameCache.stat().st_mtime)
@@ -175,6 +201,7 @@ def getOEISofficial(pathFilenameCache: Path, url: str) -> None | str:
 			tryCache = False
 
 	if not tryCache:
+		# Change http handling #13
 		httpResponse: urllib.response.addinfourl = urllib.request.urlopen(url)
 		oeisInformation = httpResponse.read().decode('utf-8')
 		writeStringToHere(oeisInformation, pathFilenameCache)
@@ -214,6 +241,27 @@ def getOEISidValues(oeisID: str) -> dict[int, int]:
 	return {-1: -1}
 
 def getOEISidInformation(oeisID: str) -> tuple[str, int]:
+	"""
+	Retrieve the description and offset for an OEIS sequence.
+
+	This function fetches the metadata for a given OEIS sequence ID, including
+	its textual description and index offset value. It uses a caching mechanism
+	to avoid redundant network requests while ensuring data freshness.
+
+	Parameters:
+		oeisID: The OEIS sequence identifier to retrieve information for.
+
+	Returns:
+		A tuple containing:
+		- description: A string describing the sequence's mathematical meaning.
+		- offset: An integer representing the starting index of the sequence.
+		  Usually 0 or 1, depending on the mathematical context.
+
+	Notes:
+		Sequence descriptions are parsed from the machine-readable format of OEIS.
+		If information cannot be retrieved, warning messages are issued and
+		fallback values are returned.
+	"""
 	oeisID = validateOEISid(oeisID)
 	pathFilenameCache: Path = pathCache / f"{oeisID}.txt"
 	url: str = f"https://oeis.org/search?q=id:{oeisID}&fmt=text"
@@ -243,6 +291,26 @@ def getOEISidInformation(oeisID: str) -> tuple[str, int]:
 	return description, offset
 
 def makeSettingsOEIS() -> dict[str, SettingsOEIS]:
+	"""
+	Construct the comprehensive settings dictionary for all implemented OEIS sequences.
+
+	This function builds a complete configuration dictionary for all supported OEIS
+	sequences by retrieving and combining:
+	1. Sequence values from OEIS b-files
+	2. Sequence metadata (descriptions and offsets)
+	3. Hardcoded mapping functions and test values
+
+	The resulting dictionary provides a single authoritative source for all OEIS-related
+	configurations used throughout the package, including:
+	- Mathematical descriptions of each sequence
+	- Functions to convert between sequence indices and map dimensions
+	- Known sequence values retrieved from OEIS
+	- Testing and benchmarking reference values
+
+	Returns:
+		A dictionary mapping OEIS sequence IDs to their complete settings objects,
+		containing all metadata and known values needed for computation and validation.
+	"""
 	settingsTarget: dict[str, SettingsOEIS] = {}
 	for oeisID in oeisIDsImplemented:
 		valuesKnownSherpa: dict[int, int] = getOEISidValues(oeisID)
@@ -277,6 +345,25 @@ def makeDictionaryFoldsTotalKnown() -> dict[tuple[int, ...], int]:
 	return dictionaryMapDimensionsToFoldsTotalKnown
 
 def getFoldsTotalKnown(mapShape: tuple[int, ...]) -> int:
+	"""
+	Retrieve the known total number of foldings for a given map shape.
+
+	This function looks up precalculated folding totals for specific map dimensions
+	from OEIS sequences. It serves as a rapid reference for known values without
+	requiring computation, and can be used to validate algorithm results.
+
+	Parameters:
+		mapShape: A tuple of integers representing the dimensions of the map.
+
+	Returns:
+		foldingsTotal: The known total number of foldings for the given map shape,
+		or -1 if the map shape doesn't match any known values in the OEIS sequences.
+
+	Notes:
+		The function uses a cached dictionary (via makeDictionaryFoldsTotalKnown) to
+		efficiently retrieve values without repeatedly parsing OEIS data. Map shape
+		tuples are sorted internally to ensure consistent lookup regardless of dimension order.
+	"""
 	lookupFoldsTotal = makeDictionaryFoldsTotalKnown()
 	return lookupFoldsTotal.get(tuple(mapShape), -1)
 

mapFolding/someAssemblyRequired/RecipeJob.py

@@ -0,0 +1,103 @@
+from mapFolding.someAssemblyRequired import ShatteredDataclass, ast_Identifier, parsePathFilename2astModule, str_nameDOTname
+from mapFolding.someAssemblyRequired.toolboxNumba import theNumbaFlow
+from mapFolding.someAssemblyRequired.transformationTools import shatter_dataclassesDOTdataclass
+from mapFolding.theSSOT import ComputationState, DatatypeElephino as TheDatatypeElephino, DatatypeFoldsTotal as TheDatatypeFoldsTotal, DatatypeLeavesTotal as TheDatatypeLeavesTotal
+from mapFolding.toolboxFilesystem import getPathFilenameFoldsTotal, getPathRootJobDEFAULT
+
+import dataclasses
+from pathlib import Path, PurePosixPath
+from typing import TypeAlias
+
+@dataclasses.dataclass
+class RecipeJob:
+	state: ComputationState
+	# TODO create function to calculate `foldsTotalEstimated`
+	foldsTotalEstimated: int = 0
+	shatteredDataclass: ShatteredDataclass = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType]
+
+	# ========================================
+	# Source
+	source_astModule = parsePathFilename2astModule(theNumbaFlow.pathFilenameSequential)
+	sourceCountCallable: ast_Identifier = theNumbaFlow.callableSequential
+
+	sourceLogicalPathModuleDataclass: str_nameDOTname = theNumbaFlow.logicalPathModuleDataclass
+	sourceDataclassIdentifier: ast_Identifier = theNumbaFlow.dataclassIdentifier
+	sourceDataclassInstance: ast_Identifier = theNumbaFlow.dataclassInstance
+
+	sourcePathPackage: PurePosixPath | None = theNumbaFlow.pathPackage
+	sourcePackageIdentifier: ast_Identifier | None = theNumbaFlow.packageIdentifier
+
+	# ========================================
+	# Filesystem (names of physical objects)
+	pathPackage: PurePosixPath | None = None
+	pathModule: PurePosixPath | None = PurePosixPath(getPathRootJobDEFAULT())
+	""" `pathModule` will override `pathPackage` and `logicalPathRoot`."""
+	fileExtension: str = theNumbaFlow.fileExtension
+	pathFilenameFoldsTotal: PurePosixPath = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType]
+
+	# ========================================
+	# Logical identifiers (as opposed to physical identifiers)
+	packageIdentifier: ast_Identifier | None = None
+	logicalPathRoot: str_nameDOTname | None = None
+	""" `logicalPathRoot` likely corresponds to a physical filesystem directory."""
+	moduleIdentifier: ast_Identifier = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType]
+	countCallable: ast_Identifier = sourceCountCallable
+	dataclassIdentifier: ast_Identifier | None = sourceDataclassIdentifier
+	dataclassInstance: ast_Identifier | None = sourceDataclassInstance
+	logicalPathModuleDataclass: str_nameDOTname | None = sourceLogicalPathModuleDataclass
+
+	# ========================================
+	# Datatypes
+	DatatypeFoldsTotal: TypeAlias = TheDatatypeFoldsTotal
+	DatatypeElephino: TypeAlias = TheDatatypeElephino
+	DatatypeLeavesTotal: TypeAlias = TheDatatypeLeavesTotal
+
+	def _makePathFilename(self,
+			pathRoot: PurePosixPath | None = None,
+			logicalPathINFIX: str_nameDOTname | None = None,
+			filenameStem: str | None = None,
+			fileExtension: str | None = None,
+			) -> PurePosixPath:
+		if pathRoot is None:
+			pathRoot = self.pathPackage or PurePosixPath(Path.cwd())
+		if logicalPathINFIX:
+			whyIsThisStillAThing: list[str] = logicalPathINFIX.split('.')
+			pathRoot = pathRoot.joinpath(*whyIsThisStillAThing)
+		if filenameStem is None:
+			filenameStem = self.moduleIdentifier
+		if fileExtension is None:
+			fileExtension = self.fileExtension
+		filename: str = filenameStem + fileExtension
+		return pathRoot.joinpath(filename)
+
+	@property
+	def pathFilenameModule(self) -> PurePosixPath:
+		if self.pathModule is None:
+			return self._makePathFilename()
+		else:
+			return self._makePathFilename(pathRoot=self.pathModule, logicalPathINFIX=None)
+
+	def __post_init__(self):
+		pathFilenameFoldsTotal = PurePosixPath(getPathFilenameFoldsTotal(self.state.mapShape))
+
+		if self.moduleIdentifier is None: # pyright: ignore[reportUnnecessaryComparison]
+			self.moduleIdentifier = pathFilenameFoldsTotal.stem
+
+		if self.pathFilenameFoldsTotal is None: # pyright: ignore[reportUnnecessaryComparison]
+			self.pathFilenameFoldsTotal = pathFilenameFoldsTotal
+
+		if self.shatteredDataclass is None and self.logicalPathModuleDataclass and self.dataclassIdentifier and self.dataclassInstance: # pyright: ignore[reportUnnecessaryComparison]
+			self.shatteredDataclass = shatter_dataclassesDOTdataclass(self.logicalPathModuleDataclass, self.dataclassIdentifier, self.dataclassInstance)
+
+	# ========================================
+	# Fields you probably don't need =================================
+	# Dispatcher =================================
+	sourceDispatcherCallable: ast_Identifier = theNumbaFlow.callableDispatcher
+	dispatcherCallable: ast_Identifier = sourceDispatcherCallable
+	# Parallel counting =================================
+	sourceDataclassInstanceTaskDistribution: ast_Identifier = theNumbaFlow.dataclassInstanceTaskDistribution
+	sourceConcurrencyManagerNamespace: ast_Identifier = theNumbaFlow.concurrencyManagerNamespace
+	sourceConcurrencyManagerIdentifier: ast_Identifier = theNumbaFlow.concurrencyManagerIdentifier
+	dataclassInstanceTaskDistribution: ast_Identifier = sourceDataclassInstanceTaskDistribution
+	concurrencyManagerNamespace: ast_Identifier = sourceConcurrencyManagerNamespace
+	concurrencyManagerIdentifier: ast_Identifier = sourceConcurrencyManagerIdentifier

mapFolding/someAssemblyRequired/__init__.py

@@ -1,66 +1,87 @@
 """
-Code transformation framework for algorithmic optimization.
+Code Transformation Framework for Algorithm Optimization and Testing
 
 This package implements a comprehensive framework for programmatically analyzing,
-transforming, and generating Python code. It enables sophisticated algorithm optimization
-through abstract syntax tree (AST) manipulation, allowing algorithms to be transformed
-from a readable, functional implementation into highly-optimized variants tailored for
-different execution environments or specific computational tasks.
+transforming, and generating optimized Python code. It serves as the algorithmic
+optimization engine for the mapFolding package, enabling the conversion of readable,
+functional implementations into highly-optimized variants with verified correctness.
 
-Core capabilities:
-1. AST Pattern Recognition - Precisely identify and match code patterns using composable predicates
-2. Algorithm Transformation - Convert functional state-based implementations to primitive operations
-3. Dataclass "Shattering" - Decompose complex state objects into primitive components
-4. Performance Optimization - Apply domain-specific optimizations for numerical computation
-5. Code Generation - Generate specialized implementations with appropriate imports and syntax
+## Core Architecture Components
 
-The transformation assembly-line supports multiple optimization targets, from general-purpose
-acceleration to generating highly-specialized variants optimized for specific input parameters.
-This multi-level transformation approach allows for both development flexibility and
-runtime performance, preserving algorithm readability in the source while enabling
-maximum execution speed in production.
+1. **AST Manipulation Tools**
+   - Pattern recognition with composable predicates (ifThis)
+   - Node access with consistent interfaces (DOT)
+   - AST traversal and transformation (NodeChanger, NodeTourist)
+   - AST construction with sane defaults (Make)
+   - Node transformation operations (grab, Then)
 
-These tools were developed for map folding computation optimization but are designed as
-general-purpose utilities applicable to a wide range of code transformation scenarios,
-particularly for numerically-intensive algorithms that benefit from just-in-time compilation.
+2. **Container and Organization**
+   - Import tracking and management (LedgerOfImports)
+   - Function packaging with dependencies (IngredientsFunction)
+   - Module assembly with structured components (IngredientsModule)
+   - Recipe configuration for generating optimized code (RecipeSynthesizeFlow)
+   - Dataclass decomposition for compatibility (ShatteredDataclass)
+
+3. **Optimization Pipelines**
+   - General-purpose Numba acceleration (makeNumbaFlow)
+   - Job-specific optimization for concrete parameters (makeJobNumba)
+   - Specialized component transformation (decorateCallableWithNumba)
+
+## Integration with Testing Framework
+
+The transformation components are extensively tested through the package's test suite,
+which provides specialized fixtures and utilities for validating both the transformation
+process and the resulting optimized code:
+
+- **syntheticDispatcherFixture**: Creates and tests a complete Numba-optimized module
+  using RecipeSynthesizeFlow configuration
+
+- **test_writeJobNumba**: Tests the job-specific optimization process with RecipeJob
+
+These fixtures enable users to test their own custom recipes and job configurations
+with minimal effort. See the documentation in tests/__init__.py for details on
+extending the test suite for custom implementations.
+
+The framework balances multiple optimization levels - from general algorithmic
+improvements to parameter-specific optimizations - while maintaining the ability
+to verify correctness at each transformation stage through the integrated test suite.
 """
+
 from mapFolding.someAssemblyRequired._theTypes import (
-	ast_expr_Slice,
-	ast_Identifier,
-	astClassHasDOTnameNotName,
-	astClassHasDOTtarget,
-	astClassHasDOTvalue,
-	astClassOptionallyHasDOTnameNotName,
-	astMosDef,
-	Ima_funcTypeUNEDITED,
-	Ima_targetTypeUNEDITED,
-	ImaAnnotationType,
-	ImaAnnotationTypeVar,
-	intORlist_ast_type_paramORstr_orNone,
-	intORstr_orNone,
-	list_ast_type_paramORstr_orNone,
-	str_nameDOTname,
-	TypeCertified,
-	个,
+	ast_expr_Slice as ast_expr_Slice,
+	ast_Identifier as ast_Identifier,
+	astClassHasDOTnameNotName as astClassHasDOTnameNotName,
+	astClassHasDOTtarget as astClassHasDOTtarget,
+	astClassHasDOTvalue_expr as astClassHasDOTvalue_expr,
+	astClassHasDOTvalue_exprNone as astClassHasDOTvalue_exprNone,
+	astClassHasDOTtargetAttributeNameSubscript as astClassHasDOTtargetAttributeNameSubscript,
+	astClassHasDOTtarget_expr as astClassHasDOTtarget_expr,
+	astClassHasDOTvalue as astClassHasDOTvalue,
+	astClassOptionallyHasDOTnameNotName as astClassOptionallyHasDOTnameNotName,
+	intORlist_ast_type_paramORstr_orNone as intORlist_ast_type_paramORstr_orNone,
+	intORstr_orNone as intORstr_orNone,
+	list_ast_type_paramORstr_orNone as list_ast_type_paramORstr_orNone,
+	str_nameDOTname as str_nameDOTname,
+	个 as 个,
 	)
 
 from mapFolding.someAssemblyRequired._toolboxPython import (
-	importLogicalPath2Callable,
-	importPathFilename2Callable,
-	NodeChanger,
-	NodeTourist,
-	parseLogicalPath2astModule,
-	parsePathFilename2astModule,
+	importLogicalPath2Callable as importLogicalPath2Callable,
+	importPathFilename2Callable as importPathFilename2Callable,
+	NodeChanger as NodeChanger,
+	NodeTourist as NodeTourist,
+	parseLogicalPath2astModule as parseLogicalPath2astModule,
+	parsePathFilename2astModule as parsePathFilename2astModule,
 	)
 
-from mapFolding.someAssemblyRequired._toolboxAntecedents import be, DOT, ifThis, 又
-from mapFolding.someAssemblyRequired._tool_Make import Make
-from mapFolding.someAssemblyRequired._tool_Then import Then
+from mapFolding.someAssemblyRequired._toolboxAntecedents import be as be, DOT as DOT, ifThis as ifThis
+from mapFolding.someAssemblyRequired._tool_Make import Make as Make
+from mapFolding.someAssemblyRequired._tool_Then import grab as grab, Then as Then
 
 from mapFolding.someAssemblyRequired._toolboxContainers import (
-	IngredientsFunction,
-	IngredientsModule,
-	LedgerOfImports,
-	RecipeSynthesizeFlow,
-	ShatteredDataclass,
+	IngredientsFunction as IngredientsFunction,
+	IngredientsModule as IngredientsModule,
+	LedgerOfImports as LedgerOfImports,
+	RecipeSynthesizeFlow as RecipeSynthesizeFlow,
+	ShatteredDataclass as ShatteredDataclass,
 )