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

mapFolding/__init__.py

@@ -1,45 +1,93 @@
 """
-Map folding enumeration and counting algorithms with optimization capabilities.
+Map folding enumeration and counting algorithms with advanced optimization capabilities.
 
-This package implements algorithms to count and enumerate the various ways
+This package implements algorithms to count and enumerate the distinct ways
 a rectangular map can be folded, based on the mathematical problem described
 in Lunnon's 1971 paper. It provides multiple layers of functionality, from
-high-level user interfaces to low-level algorithmic optimizations and code
+high-level user interfaces to sophisticated algorithmic optimizations and code
 transformation tools.
 
 Core modules:
 - basecamp: Public API with simplified interfaces for end users
 - theDao: Core computational algorithm using a functional state-transformation approach
 - beDRY: Core utility functions implementing consistent data handling, validation, and
-  resource management across the package's computational assembly-line
+    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 strives to balance algorithm readability and understandability with
+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.
+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.
 

mapFolding/oeis.py

@@ -2,26 +2,30 @@
 Interface to The Online Encyclopedia of Integer Sequences (OEIS) for map folding sequences.
 
 This module provides a comprehensive interface for accessing and utilizing integer sequences
-from the OEIS that relate to map folding problems. It implements functionality to:
+from the OEIS that relate to map folding problems. It serves as the bridge between
+mathematical sequence definitions and the computational algorithm, implementing:
 
-1. Retrieve sequence data from OEIS with local caching for performance
-2. Map sequence indices to corresponding map shapes based on sequence definitions
-3. Provide a command-line interface for sequence lookups
-4. Execute map folding computations for sequence terms not available in OEIS
+1. Retrieval of sequence data from OEIS with local caching for performance optimization.
+2. Mapping of sequence indices to corresponding map shapes based on sequence definitions.
+3. Command-line and programmatic interfaces for sequence lookups and validation.
+4. Computation of sequence terms not available in the OEIS database.
 
 The module maintains a registry of implemented OEIS sequences (A001415-A001418, A195646)
-with their metadata, known values, and functions to convert between sequence indices and
+with their metadata, known values, and conversion functions between sequence indices and
 map dimensions. This allows the package to validate results against established mathematical
-literature and extend sequences beyond their currently known terms.
+literature while also extending sequences beyond their currently known terms.
+
+Each sequence is carefully mapped to its corresponding map folding problem, enabling
+seamless integration between the mathematical definition in OEIS and the computational
+implementation in the package.
 """
 from collections.abc import Callable
 from datetime import datetime, timedelta
-from mapFolding.theSSOT import The
-from mapFolding.toolboxFilesystem import writeStringToHere
+from functools import cache
+from mapFolding import writeStringToHere, The
 from pathlib import Path
 from typing import Any, Final, TYPE_CHECKING
 import argparse
-import pathlib
 import random
 import sys
 import time
@@ -36,9 +40,6 @@ else:
 
 cacheDays = 30
 
-"""
-Section: make `settingsOEIS`"""
-
 pathCache: Path = The.pathPackage / ".cache"
 
 class SettingsOEIS(TypedDict):
@@ -159,7 +160,28 @@ def _parseBFileOEIS(OEISbFile: str, oeisID: str) -> dict[int, int]:
 		OEISsequence[n] = aOFn
 	return OEISsequence
 
-def getOEISofficial(pathFilenameCache: pathlib.Path, url: str) -> None | str:
+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)
@@ -173,6 +195,7 @@ def getOEISofficial(pathFilenameCache: pathlib.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)
@@ -186,6 +209,7 @@ def getOEISidValues(oeisID: str) -> dict[int, int]:
 	"""
 	Retrieves the specified OEIS sequence as a dictionary mapping integer indices
 	to their corresponding values.
+
 	This function checks for a cached local copy of the sequence data, using it if
 	it has not expired. Otherwise, it fetches the sequence data from the OEIS
 	website and writes it to the cache. The parsed data is returned as a dictionary
@@ -195,7 +219,7 @@ def getOEISidValues(oeisID: str) -> dict[int, int]:
 		oeisID: The identifier of the OEIS sequence to retrieve.
 	Returns:
 		OEISsequence: A dictionary where each key is an integer index, `n`, and each
-		value is the corresponding "a(n)" from the OEIS entry.
+		value is the corresponding `a(n)` from the OEIS entry.
 	Raises:
 		ValueError: If the cached or downloaded file format is invalid.
 		IOError: If there is an error reading from or writing to the local cache.
@@ -211,6 +235,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"
@@ -240,6 +285,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)
@@ -259,8 +324,42 @@ def makeSettingsOEIS() -> dict[str, SettingsOEIS]:
 settingsOEIS: dict[str, SettingsOEIS] = makeSettingsOEIS()
 """All values and settings for `oeisIDsImplemented`."""
 
-"""
-Section: private functions"""
+@cache
+def makeDictionaryFoldsTotalKnown() -> dict[tuple[int, ...], int]:
+	"""Returns a dictionary mapping dimension tuples to their known folding totals."""
+	dictionaryMapDimensionsToFoldsTotalKnown: dict[tuple[int, ...], int] = {}
+
+	for settings in settingsOEIS.values():
+		sequence = settings['valuesKnown']
+
+		for n, foldingsTotal in sequence.items():
+			mapShape = settings['getMapShape'](n)
+			mapShape = tuple(sorted(mapShape))
+			dictionaryMapDimensionsToFoldsTotalKnown[mapShape] = foldingsTotal
+	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)
 
 def _formatHelpText() -> str:
 	"""Format standardized help text for both CLI and interactive use."""
@@ -285,35 +384,32 @@ def _formatOEISsequenceInfo() -> str:
 		for oeisID in oeisIDsImplemented
 	)
 
-"""
-Section: public functions"""
-
 def oeisIDfor_n(oeisID: str, n: int | Any) -> int:
 	"""
-	Calculate a(n) of a sequence from "The On-Line Encyclopedia of Integer Sequences" (OEIS).
+	Calculate `a(n)` of a sequence from "The On-Line Encyclopedia of Integer Sequences" (OEIS).
 
 	Parameters:
 		oeisID: The ID of the OEIS sequence.
 		n: A non-negative integer for which to calculate the sequence value.
 
 	Returns:
-		sequenceValue: a(n) of the OEIS sequence.
+		sequenceValue: `a(n)` of the OEIS sequence.
 
 	Raises:
-		ValueError: If n is negative.
+		ValueError: If `n` is negative.
 		KeyError: If the OEIS sequence ID is not directly implemented.
 	"""
 	oeisID = validateOEISid(oeisID)
 
 	if not isinstance(n, int) or n < 0:
-		raise ValueError("`n` must be non-negative integer.")
+		raise ValueError(f"I received `{n = }` in the form of `{type(n) = }`, but it must be non-negative integer in the form of `{int}`.")
 
 	mapShape: tuple[int, ...] = settingsOEIS[oeisID]['getMapShape'](n)
 
 	if n <= 1 or len(mapShape) < 2:
 		offset: int = settingsOEIS[oeisID]['offset']
 		if n < offset:
-			raise ArithmeticError(f"OEIS sequence {oeisID} is not defined at n={n}.")
+			raise ArithmeticError(f"OEIS sequence {oeisID} is not defined at {n = }.")
 		foldsTotal: int = settingsOEIS[oeisID]['valuesKnown'][n]
 		return foldsTotal
 	from mapFolding.basecamp import countFolds

mapFolding/someAssemblyRequired/__init__.py

@@ -1,46 +1,67 @@
 """
-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_expr,
+	astClassHasDOTvalue_exprNone,
+	astClassHasDOTtargetAttributeNameSubscript,
+	astClassHasDOTtarget_expr,
 	astClassHasDOTvalue,
 	astClassOptionallyHasDOTnameNotName,
-	astMosDef,
-	Ima_funcTypeUNEDITED,
-	Ima_targetTypeUNEDITED,
-	ImaAnnotationType,
-	ImaAnnotationTypeVar,
 	intORlist_ast_type_paramORstr_orNone,
 	intORstr_orNone,
 	list_ast_type_paramORstr_orNone,
 	str_nameDOTname,
-	TypeCertified,
 	个,
 	)
 
@@ -53,9 +74,9 @@ from mapFolding.someAssemblyRequired._toolboxPython import (
 	parsePathFilename2astModule,
 	)
 
-from mapFolding.someAssemblyRequired._toolboxAntecedents import be, DOT, ifThis, 又
+from mapFolding.someAssemblyRequired._toolboxAntecedents import DOT, ifThis
 from mapFolding.someAssemblyRequired._tool_Make import Make
-from mapFolding.someAssemblyRequired._tool_Then import Then
+from mapFolding.someAssemblyRequired._tool_Then import grab, Then
 
 from mapFolding.someAssemblyRequired._toolboxContainers import (
 	IngredientsFunction,

mapFolding/someAssemblyRequired/_theTypes.py

@@ -1,20 +1,24 @@
-"""It's still wrong, but typing information is being transmitted between functions, methods, and modules."""
 from typing import Any, TYPE_CHECKING, TypeAlias as typing_TypeAlias, TypeVar as typing_TypeVar
 import ast
+# TODO understand typing.
 
 stuPyd: typing_TypeAlias = str
-
 if TYPE_CHECKING:
 	"""	3.12 new: ast.ParamSpec, ast.type_param, ast.TypeAlias, ast.TypeVar, ast.TypeVarTuple
 		3.11 new: ast.TryStar"""
 	astClassHasDOTnameNotName: typing_TypeAlias = ast.alias | ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.ParamSpec | ast.TypeVar | ast.TypeVarTuple
-	astClassHasDOTvalue: typing_TypeAlias = ast.AnnAssign | ast.Assign | ast.Attribute | ast.AugAssign | ast.Await | ast.Constant | ast.DictComp | ast.Expr | ast.FormattedValue | ast.keyword | ast.MatchValue | ast.NamedExpr | ast.Return | ast.Starred | ast.Subscript | ast.TypeAlias | ast.Yield | ast.YieldFrom
+	astClassHasDOTvalue_expr: typing_TypeAlias = ast.Assign | ast.Attribute | ast.AugAssign | ast.Await | ast.DictComp | ast.Expr | ast.FormattedValue | ast.keyword | ast.MatchValue | ast.NamedExpr | ast.Starred | ast.Subscript | ast.TypeAlias | ast.YieldFrom
+
 else:
 	astClassHasDOTnameNotName = stuPyd
-	astClassHasDOTvalue = stuPyd
+	astClassHasDOTvalue_expr = stuPyd
 
+astClassHasDOTtargetAttributeNameSubscript: typing_TypeAlias = ast.AnnAssign | ast.AugAssign
+astClassHasDOTtarget_expr: typing_TypeAlias = ast.AsyncFor | ast.comprehension | ast.For
+astClassHasDOTtarget: typing_TypeAlias = ast.NamedExpr | astClassHasDOTtarget_expr | astClassHasDOTtargetAttributeNameSubscript
 astClassOptionallyHasDOTnameNotName: typing_TypeAlias = ast.ExceptHandler | ast.MatchAs | ast.MatchStar
-astClassHasDOTtarget: typing_TypeAlias = ast.AnnAssign | ast.AsyncFor | ast.AugAssign | ast.comprehension | ast.For | ast.NamedExpr
+astClassHasDOTvalue_exprNone: typing_TypeAlias = ast.AnnAssign | ast.Return | ast.Yield
+astClassHasDOTvalue: typing_TypeAlias = ast.Constant | ast.MatchSingleton | astClassHasDOTvalue_expr | astClassHasDOTvalue_exprNone
 
 ast_expr_Slice: typing_TypeAlias = ast.expr
 ast_Identifier: typing_TypeAlias = str
@@ -22,18 +26,10 @@ intORlist_ast_type_paramORstr_orNone: typing_TypeAlias = Any
 intORstr_orNone: typing_TypeAlias = Any
 list_ast_type_paramORstr_orNone: typing_TypeAlias = Any
 str_nameDOTname: typing_TypeAlias = stuPyd
-ImaAnnotationType: typing_TypeAlias = ast.Attribute | ast.Constant | ast.Name | ast.Subscript
-ImaAnnotationTypeVar = typing_TypeVar('ImaAnnotationTypeVar', ast.Attribute, ast.Constant, ast.Name, ast.Subscript)
-
-Ima_funcTypeUNEDITED: typing_TypeAlias = ast.Attribute | ast.Await | ast.BinOp | ast.BoolOp | ast.Call | ast.Compare | ast.Constant | ast.Dict | ast.DictComp | ast.FormattedValue | ast.GeneratorExp | ast.IfExp | ast.JoinedStr | ast.Lambda | ast.List | ast.ListComp | ast.Name | ast.NamedExpr | ast.Set | ast.SetComp | ast.Slice | ast.Starred | ast.Subscript | ast.Tuple | ast.UnaryOp | ast.Yield | ast.YieldFrom
-Ima_targetTypeUNEDITED: typing_TypeAlias = ast.AST
-
-# TODO understand whatever the fuck `typing.TypeVar` is _supposed_ to fucking do.
-TypeCertified = typing_TypeVar('TypeCertified', bound = ast.AST, covariant=True)
-astMosDef = typing_TypeVar('astMosDef', bound=astClassHasDOTnameNotName)
 
-个 = typing_TypeVar('个', bound= ast.AST | ast_Identifier, covariant=True)
+个 = typing_TypeVar('个', bound= ast.AST, covariant=True)
 
+# All ast classes by subgroup:
 Ima_ast_boolop: typing_TypeAlias = ast.boolop | ast.And | ast.Or
 Ima_ast_cmpop: typing_TypeAlias = ast.cmpop | ast.Eq | ast.NotEq | ast.Lt | ast.LtE | ast.Gt | ast.GtE | ast.Is | ast.IsNot | ast.In | ast.NotIn
 Ima_ast_excepthandler: typing_TypeAlias = ast.excepthandler | ast.ExceptHandler