mapFolding 0.12.1__py3-none-any.whl → 0.12.2__py3-none-any.whl

mapFolding/someAssemblyRequired/makeJobTheorem2Numba.py

@@ -1,41 +1,71 @@
-from mapFolding import getPathFilenameFoldsTotal, MapFoldingState, packageSettings
-from mapFolding.someAssemblyRequired import IfThis, raiseIfNoneGitHubIssueNumber3
+"""
+Map folding AST transformation system: Specialized job generation and optimization implementation.
+
+This module implements the specialized job generation layer of the map folding AST transformation
+system, executing the complete transformation process to convert generic map folding algorithms
+into highly optimized, standalone computation modules. Building upon the configuration orchestration
+established in the recipe system, this module applies the full sequence of transformations from
+pattern recognition through Numba compilation to produce self-contained computational solutions
+optimized for specific map dimensions and calculation contexts.
+
+The transformation implementation addresses the computational demands of map folding research where
+calculations can require hours or days to complete. The specialization process converts abstract
+algorithms with flexible parameters into concrete, statically-optimized code that leverages
+just-in-time compilation for maximum performance. Each generated module targets specific map
+shapes and calculation modes, enabling aggressive compiler optimizations based on known constraints
+and embedded constants.
+
+The optimization process executes systematic transformations including static value embedding to
+replace parameterized values with compile-time constants, dead code elimination to remove unused
+variables and code paths, parameter internalization to convert function parameters into embedded
+variables, import optimization to replace generic imports with specific implementations, Numba
+decoration with appropriate compilation directives, progress integration for long-running calculations,
+and launcher generation for standalone execution entry points.
+
+The resulting modules represent the culmination of the entire AST transformation system, producing
+self-contained Python scripts that execute independently with dramatically improved performance
+compared to original generic algorithms while maintaining mathematical correctness and providing
+essential progress feedback capabilities for large-scale computational research.
+"""
+
 from astToolkit import (
-	Be,
-	ClassIsAndAttribute,
-	extractFunctionDef,
-	IngredientsFunction,
-	IngredientsModule,
-	LedgerOfImports,
-	Make,
-	NodeChanger,
-	NodeTourist,
-	str_nameDOTname,
-	Then,
+	Be, ClassIsAndAttribute, extractFunctionDef, identifierDotAttribute, IngredientsFunction,
+	IngredientsModule, LedgerOfImports, Make, NodeChanger, NodeTourist, Then,
 )
 from astToolkit.transformationTools import write_astModule
+from mapFolding import getPathFilenameFoldsTotal, MapFoldingState, packageSettings
+from mapFolding.someAssemblyRequired import IfThis
 from mapFolding.someAssemblyRequired.RecipeJob import RecipeJobTheorem2Numba
-from mapFolding.someAssemblyRequired.toolkitNumba import decorateCallableWithNumba, parametersNumbaLight, SpicesJobNumba
+from mapFolding.someAssemblyRequired.toolkitNumba import (
+	decorateCallableWithNumba, parametersNumbaLight, SpicesJobNumba,
+)
 from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds
 from pathlib import PurePosixPath
 from typing import cast, NamedTuple
-from Z0Z_tools import autoDecodingRLE
+from Z0Z_tools import autoDecodingRLE, raiseIfNone
 import ast
-"""Synthesize one file to compute `foldsTotal` of `mapShape`."""
 
-listIdentifiersNotUsedAllHARDCODED = ['concurrencyLimit', 'foldsTotal', 'mapShape',]
-listIdentifiersNotUsedParallelSequentialHARDCODED = ['indexLeaf']
-listIdentifiersNotUsedSequentialHARDCODED = ['foldGroups', 'taskDivisions', 'taskIndex',]
+# Configuration lists for code optimization and dead code elimination
+listIdentifiersNotUsedAllHARDCODED: list[str] = ['concurrencyLimit', 'foldsTotal', 'mapShape',]
+"""Identifiers that are universally unused across all optimization contexts."""
+
+listIdentifiersNotUsedParallelSequentialHARDCODED: list[str] = ['indexLeaf']
+"""Identifiers unused in both parallel and sequential execution modes."""
+
+listIdentifiersNotUsedSequentialHARDCODED: list[str] = ['foldGroups', 'taskDivisions', 'taskIndex',]
+"""Identifiers unused specifically in sequential execution mode."""
 
-listIdentifiersReplacedHARDCODED = ['groupsOfFolds',]
+listIdentifiersReplacedHARDCODED: list[str] = ['groupsOfFolds',]
+"""Identifiers that get replaced with optimized equivalents during transformation."""
 
-listIdentifiersStaticValuesHARDCODED = ['dimensionsTotal', 'leavesTotal',]
+listIdentifiersStaticValuesHARDCODED: list[str] = ['dimensionsTotal', 'leavesTotal',]
+"""Identifiers with compile-time constant values that can be embedded directly."""
 
-listIdentifiersNotUsedHARDCODED = listIdentifiersStaticValuesHARDCODED + listIdentifiersReplacedHARDCODED + listIdentifiersNotUsedAllHARDCODED + listIdentifiersNotUsedParallelSequentialHARDCODED + listIdentifiersNotUsedSequentialHARDCODED
+listIdentifiersNotUsedHARDCODED: list[str] = listIdentifiersStaticValuesHARDCODED + listIdentifiersReplacedHARDCODED + listIdentifiersNotUsedAllHARDCODED + listIdentifiersNotUsedParallelSequentialHARDCODED + listIdentifiersNotUsedSequentialHARDCODED
+"""Complete list of all identifiers that can be eliminated during optimization."""
 
 def addLauncherNumbaProgress(ingredientsModule: IngredientsModule, ingredientsFunction: IngredientsFunction, job: RecipeJobTheorem2Numba, spices: SpicesJobNumba) -> tuple[IngredientsModule, IngredientsFunction]:
-	"""
-	Add progress tracking capabilities to a Numba-optimized function.
+	"""Add progress tracking capabilities to a Numba-optimized function.
 
 	This function modifies both the module and the function to integrate Numba-compatible
 	progress tracking for long-running calculations. It performs several key transformations:
@@ -56,8 +86,9 @@ def addLauncherNumbaProgress(ingredientsModule: IngredientsModule, ingredientsFu
 		spices: Configuration specifying progress bar details.
 
 	Returns:
-		A tuple containing the modified module and function with progress tracking.
+		Modified module and function with integrated progress tracking capabilities.
 	"""
+
 	linesLaunch: str = f"""
 if __name__ == '__main__':
 	with ProgressBar(total={job.foldsTotalEstimated}, update_interval=2) as statusUpdate:
@@ -90,17 +121,16 @@ if __name__ == '__main__':
 	return ingredientsModule, ingredientsFunction
 
 def move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsFunction: IngredientsFunction, job: RecipeJobTheorem2Numba) -> IngredientsFunction:
-	"""
-	Convert function parameters into initialized variables with concrete values.
+	"""Convert function parameters into initialized variables with concrete values.
 
 	This function implements a critical transformation that converts function parameters
 	into statically initialized variables in the function body. This enables several
 	optimizations:
 
-	1. Eliminating parameter passing overhead.
-	2. Embedding concrete values directly in the code.
-	3. Allowing Numba to optimize based on known value characteristics.
-	4. Simplifying function signatures for specialized use cases.
+	1. Eliminating parameter passing overhead
+	2. Embedding concrete values directly in the code
+	3. Allowing Numba to optimize based on known value characteristics
+	4. Simplifying function signatures for specialized use cases
 
 	The function handles different data types (scalars, arrays, custom types) appropriately,
 	replacing abstract parameter references with concrete values from the computation state.
@@ -115,7 +145,7 @@ def move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsFunction: Ingre
 	"""
 	ingredientsFunction.imports.update(job.shatteredDataclass.imports)
 
-	list_argCuzMyBrainRefusesToThink = ingredientsFunction.astFunctionDef.args.args + ingredientsFunction.astFunctionDef.args.posonlyargs + ingredientsFunction.astFunctionDef.args.kwonlyargs
+	list_argCuzMyBrainRefusesToThink: list[ast.arg] = ingredientsFunction.astFunctionDef.args.args + ingredientsFunction.astFunctionDef.args.posonlyargs + ingredientsFunction.astFunctionDef.args.kwonlyargs
 	list_arg_arg: list[str] = [ast_arg.arg for ast_arg in list_argCuzMyBrainRefusesToThink]
 	listName: list[ast.Name] = []
 	NodeTourist(Be.Name, Then.appendTo(listName)).visit(ingredientsFunction.astFunctionDef)
@@ -154,9 +184,31 @@ def move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsFunction: Ingre
 	return ingredientsFunction
 
 def makeJobNumba(job: RecipeJobTheorem2Numba, spices: SpicesJobNumba) -> None:
+	"""Generate an optimized Numba-compiled computation module for map folding calculations.
+
+	This function orchestrates the complete code transformation pipeline to convert
+	a generic map folding algorithm into a highly optimized, specialized computation
+	module. The transformation process includes:
+
+	1. Extract and modify the source function from the generic algorithm
+	2. Replace static-valued identifiers with their concrete values
+	3. Convert function parameters to embedded initialized variables
+	4. Remove unused code paths and variables for optimization
+	5. Configure appropriate Numba decorators for JIT compilation
+	6. Add progress tracking capabilities for long-running computations
+	7. Generate standalone launcher code for direct execution
+	8. Write the complete optimized module to the filesystem
 
-	astFunctionDef = extractFunctionDef(job.source_astModule, job.countCallable)
-	if not astFunctionDef: raise raiseIfNoneGitHubIssueNumber3
+	The resulting module is a self-contained Python script that can execute
+	map folding calculations for the specific map dimensions with maximum
+	performance through just-in-time compilation.
+
+	Parameters:
+		job: Configuration recipe containing source locations, target paths, and state.
+		spices: Optimization settings including Numba parameters and progress options.
+	"""
+
+	astFunctionDef: ast.FunctionDef = raiseIfNone(extractFunctionDef(job.source_astModule, job.countCallable))
 	ingredientsCount: IngredientsFunction = IngredientsFunction(astFunctionDef, LedgerOfImports())
 
 	# Remove `foldGroups` and any other unused statements, so you can dynamically determine which variables are not used
@@ -167,7 +219,7 @@ def makeJobNumba(job: RecipeJobTheorem2Numba, spices: SpicesJobNumba) -> None:
 	# remove_foldGroups.visit(ingredientsCount.astFunctionDef)
 
 	# replace identifiers with static values with their values, so you can dynamically determine which variables are not used
-	listIdentifiersStaticValues = listIdentifiersStaticValuesHARDCODED
+	listIdentifiersStaticValues: list[str] = listIdentifiersStaticValuesHARDCODED
 	for identifier in listIdentifiersStaticValues:
 		findThis = IfThis.isNameIdentifier(identifier)
 		doThat = Then.replaceWith(Make.Constant(int(job.state.__dict__[identifier])))
@@ -198,14 +250,26 @@ if __name__ == '__main__':
 		ingredientsCount.astFunctionDef.returns = job.shatteredDataclass.countingVariableAnnotation
 
 	ingredientsCount = move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsCount, job)
-
 	class DatatypeConfig(NamedTuple):
-		Z0Z_module: str_nameDOTname
+		"""Configuration for mapping framework datatypes to Numba-compatible types.
+
+		This configuration class defines how abstract datatypes used in the map folding
+		framework should be replaced with concrete Numba-compatible types during code
+		generation. Each configuration specifies the source module, target type name,
+		and optional import alias for the transformation.
+
+		Attributes:
+			fml: Framework datatype identifier to be replaced.
+			Z0Z_module: Module containing the target datatype (e.g., 'numba', 'numpy').
+			Z0Z_type_name: Concrete type name in the target module.
+			Z0Z_asname: Optional import alias for the type.
+		"""
 		fml: str
+		Z0Z_module: identifierDotAttribute
 		Z0Z_type_name: str
 		Z0Z_asname: str | None = None
 
-	listDatatypeConfigs = [
+	listDatatypeConfigs: list[DatatypeConfig] = [
 		DatatypeConfig(fml='DatatypeLeavesTotal', Z0Z_module='numba', Z0Z_type_name='uint8'),
 		DatatypeConfig(fml='DatatypeElephino', Z0Z_module='numba', Z0Z_type_name='uint16'),
 		DatatypeConfig(fml='DatatypeFoldsTotal', Z0Z_module='numba', Z0Z_type_name='uint64'),
@@ -234,7 +298,6 @@ if __name__ == '__main__':
 	ingredientsCount.astFunctionDef.decorator_list = [] # TODO low-priority, handle this more elegantly
 	# TODO when I add the function signature in numba style back to the decorator, the logic needs to handle `ProgressBarType:`
 	ingredientsCount = decorateCallableWithNumba(ingredientsCount, spices.parametersNumba)
-
 	ingredientsModule.appendIngredientsFunction(ingredientsCount)
 	write_astModule(ingredientsModule, job.pathFilenameModule, job.packageIdentifier)
 

mapFolding/someAssemblyRequired/toolkitNumba.py

@@ -1,30 +1,61 @@
 """
-Numba-specific Tools for Generating Optimized Code
+Map folding AST transformation system: Numba integration and just-in-time compilation optimization.
 
-This module provides specialized tools for transforming standard Python code into
-Numba-accelerated implementations. It implements a comprehensive transformation
-assembly-line that:
+This module provides the compilation optimization layer of the map folding AST transformation system,
+implementing comprehensive tools for applying Numba's just-in-time compilation to functions generated
+by the core transformation tools. Building upon the dataclass decomposition and function optimization
+capabilities established in the operational core, this module completes the transformation process
+by applying aggressive performance optimizations through strategic compiler configuration.
 
-1. Converts dataclass-based algorithm implementations into Numba-compatible versions.
-2. Applies appropriate Numba decorators with optimized configuration settings.
-3. Restructures code to work within Numba's constraints.
-4. Manages type information for optimized compilation.
+The integration addresses the final stage of the transformation process where decomposed, optimized
+functions receive Numba decorators with carefully configured optimization parameters. The module
+handles the complexities of type signature generation, import management, and decorator conflict
+resolution that arise when converting high-level map folding algorithms into machine-optimized code.
 
-The module bridges the gap between readable, maintainable Python code and
-highly-optimized numerical computing implementations, enabling significant
-performance improvements while preserving code semantics and correctness.
+Two primary compilation strategies accommodate different performance and compatibility requirements:
+aggressive optimization for production numerical computing provides maximum performance through
+comprehensive compiler directives including nopython mode, bounds checking elimination, forced
+function inlining, and fastmath optimizations; lightweight optimization maintains broader compatibility
+while achieving significant performance gains through selective compiler optimizations suitable for
+development and testing environments.
+
+The strategic application of these optimization configurations enables map folding calculations that
+require hours or days to complete, transforming abstract mathematical algorithms into highly efficient
+computational modules. The compilation layer integrates seamlessly with the broader transformation
+system to produce standalone modules optimized for specific map dimensions and computational contexts.
 """
 
+from astToolkit import identifierDotAttribute, IngredientsFunction, Make
 from collections.abc import Callable, Sequence
-from mapFolding import NotRequired, TypedDict
-from astToolkit import  IngredientsFunction, Make, str_nameDOTname
-from astToolkit.transformationTools import write_astModule
 from numba.core.compiler import CompilerBase as numbaCompilerBase
-from typing import Any, cast, Final
+from typing import Any, cast, Final, NotRequired, TypedDict
 import ast
 import dataclasses
+import warnings
 
 class ParametersNumba(TypedDict):
+	"""
+	Configuration parameters for Numba compilation decorators.
+
+	This TypedDict defines all possible configuration options that can be passed to Numba's
+	`@jit` decorator to control compilation behavior. The parameters enable fine-tuned control
+	over optimization strategies, debugging features, and runtime behavior.
+
+	Key compilation modes:
+		nopython: Forces compilation without Python fallback for maximum performance
+		cache: Enables compilation result caching to disk for faster subsequent runs
+		fastmath: Allows aggressive mathematical optimizations at cost of IEEE compliance
+		parallel: Enables automatic parallelization of supported operations
+
+	Debug and development options:
+		debug: Enables debug information generation
+		boundscheck: Controls array bounds checking (disabled for performance in production)
+		error_model: Defines how numerical errors are handled ('numpy' vs 'python')
+
+	Only `cache`, `error_model`, and `fastmath` are required fields. All other fields are
+	optional via `NotRequired`, allowing flexible configuration while requiring explicit
+	decisions on critical performance and correctness parameters.
+	"""
 	_dbg_extend_lifetimes: NotRequired[bool]
 	_dbg_optnone: NotRequired[bool]
 	_nrt: NotRequired[bool]
@@ -49,22 +80,121 @@ class ParametersNumba(TypedDict):
 	target: NotRequired[str]
 
 parametersNumbaDefault: Final[ParametersNumba] = { '_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, }
-"""Middle of the road: fast, lean, but will talk to non-jitted functions."""
+"""
+Comprehensive Numba configuration for maximum performance optimization.
+
+This configuration provides aggressive optimization settings suitable for production
+numerical computing code. Key characteristics:
+	Enables nopython mode for full compilation without Python fallback
+	Disables bounds checking for maximum array access performance
+	Forces function inlining with 'always' policy for reduced call overhead
+	Uses numpy error model for consistent numerical behavior
+	Enables fastmath for aggressive floating-point optimizations
+	Disables loop lifting to prevent unexpected performance penalties
+
+The configuration prioritizes execution speed over compatibility, producing highly
+optimized machine code at the cost of reduced interoperability with uncompiled
+Python functions.
+"""
+
 parametersNumbaLight: Final[ParametersNumba] = {'cache': True, 'error_model': 'numpy', 'fastmath': True, 'forceinline': True}
+"""
+Minimal Numba configuration for basic optimization with maximum compatibility.
+
+This lightweight configuration provides essential optimizations while maintaining
+broad compatibility with existing Python code. Suitable for:
+	Development and debugging phases
+	Code that needs to interoperate with non-Numba functions
+	Situations where full nopython mode causes compilation issues
+
+Key features:
+	Enables compilation caching for faster subsequent runs
+	Uses numpy error model for consistent mathematical behavior
+	Enables fastmath and function inlining for performance gains
+	Allows Python object mode fallback when needed
+"""
+
+Z0Z_numbaDataTypeModule: identifierDotAttribute = 'numba'
+"""
+Module identifier for Numba imports and type annotations.
+
+This constant specifies the module path used when importing Numba-specific types and decorators
+in generated code. It serves as the single source of truth for the Numba module reference,
+enabling consistent import statements across all generated functions.
+"""
 
-Z0Z_numbaDataTypeModule: str_nameDOTname = 'numba'
 Z0Z_decoratorCallable: str = 'jit'
+"""
+The Numba decorator function name used for just-in-time compilation.
+
+This constant identifies the specific Numba decorator applied to functions for compilation.
+While Numba offers multiple decorators (`@jit`, `@njit`, `@vectorize`), this toolkit focuses
+on the general-purpose `@jit` decorator with configurable parameters for flexibility.
+"""
 
 def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, parametersNumba: ParametersNumba | None = None) -> IngredientsFunction:
+	"""
+	Transform a Python function into a Numba-accelerated version with appropriate decorators.
+
+	This function applies Numba's @jit decorator to an existing function definition within
+	an IngredientsFunction container. It handles the complete transformation pipeline:
+
+	1. Removes any existing decorators that might conflict with Numba
+	2. Constructs type signatures for Numba compilation when possible
+	3. Applies the @jit decorator with specified or default parameters
+	4. Updates import requirements to include necessary Numba modules
+
+	The transformation preserves function semantics while enabling significant performance
+	improvements through just-in-time compilation. Type inference is attempted for
+	function parameters and return values to enable optimized compilation paths.
+	Parameters:
+		ingredientsFunction: Container holding the function definition and associated metadata
+		parametersNumba: Optional Numba configuration; uses parametersNumbaDefault if None
+	Returns:
+		Modified IngredientsFunction with Numba decorator applied and imports updated
+	"""
 	def Z0Z_UnhandledDecorators(astCallable: ast.FunctionDef) -> ast.FunctionDef:
+		"""
+		Remove existing decorators from function definition to prevent conflicts with Numba.
+
+		Numba compilation can be incompatible with certain Python decorators, so this
+		function strips all existing decorators from a function definition before
+		applying the Numba @jit decorator. Removed decorators are logged as warnings
+		for debugging purposes.
+
+		TODO: Implement more sophisticated decorator handling that can preserve
+		compatible decorators and intelligently handle decorator composition.
+
+		Parameters:
+			astCallable: Function definition AST node to process
+
+		Returns:
+			astCallable: Function definition with decorator list cleared
+		"""
 		# TODO: more explicit handling of decorators. I'm able to ignore this because I know `algorithmSource` doesn't have any decorators.
 		for decoratorItem in astCallable.decorator_list.copy():
-			import warnings
 			astCallable.decorator_list.remove(decoratorItem)
 			warnings.warn(f"Removed decorator {ast.unparse(decoratorItem)} from {astCallable.name}")
 		return astCallable
 
 	def makeSpecialSignatureForNumba(signatureElement: ast.arg) -> ast.Subscript | ast.Name | None: # pyright: ignore[reportUnusedFunction]
+		"""
+		Generate Numba-compatible type signatures for function parameters.
+
+		This function analyzes function parameter type annotations and converts them into
+		Numba-compatible type signature expressions. It handles various annotation patterns
+		including array types with shape and dtype information, scalar types with simple
+		name annotations, and complex subscripted types requiring special handling.
+
+		The generated signatures enable Numba to perform more efficient compilation by
+		providing explicit type information rather than relying solely on type inference.
+
+		Parameters:
+			signatureElement: Function parameter with type annotation to convert
+
+		Returns:
+			Numba-compatible type signature AST node, or None if conversion not possible
+		"""
 		if isinstance(signatureElement.annotation, ast.Subscript) and isinstance(signatureElement.annotation.slice, ast.Tuple):
 			annotationShape: ast.expr = signatureElement.annotation.slice.elts[0]
 			if isinstance(annotationShape, ast.Subscript) and isinstance(annotationShape.slice, ast.Tuple):
@@ -113,7 +243,7 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 	ingredientsFunction.astFunctionDef = Z0Z_UnhandledDecorators(ingredientsFunction.astFunctionDef)
 	if parametersNumba is None:
 		parametersNumba = parametersNumbaDefault
-	listDecoratorKeywords: list[ast.keyword] = [Make.keyword(parameterName, Make.Constant(parameterValue)) for parameterName, parameterValue in parametersNumba.items()]
+	listDecoratorKeywords: list[ast.keyword] = [Make.keyword(parameterName, Make.Constant(parameterValue)) for parameterName, parameterValue in parametersNumba.items()] # pyright: ignore[reportArgumentType]
 
 	decoratorModule = Z0Z_numbaDataTypeModule
 	decoratorCallable = Z0Z_decoratorCallable
@@ -127,6 +257,28 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 
 @dataclasses.dataclass
 class SpicesJobNumba:
+	"""
+	Configuration container for Numba-specific job processing options.
+
+	This dataclass encapsulates configuration settings that control how Numba
+	compilation and execution is applied to job processing functions. It provides
+	a centralized way to manage Numba-specific settings that affect both
+	compilation behavior and runtime features like progress reporting.
+
+	The class serves as a bridge between the generic job processing system and
+	Numba's specialized requirements, enabling consistent application of
+	optimization settings across different computational contexts.
+
+	Attributes:
+		useNumbaProgressBar: Enable progress bar display for long-running computations
+		numbaProgressBarIdentifier: Progress bar implementation identifier
+		parametersNumba: Numba compilation parameters with sensible defaults
+	"""
 	useNumbaProgressBar: bool = True
+	"""Enable progress bar display for Numba-compiled functions with long execution times."""
+
 	numbaProgressBarIdentifier: str = 'ProgressBarGroupsOfFolds'
+	"""Identifier for the progress bar implementation used in Numba-compiled code."""
+
 	parametersNumba: ParametersNumba = dataclasses.field(default_factory=ParametersNumba)  # pyright: ignore[reportArgumentType, reportCallIssue, reportUnknownVariableType]
+	"""Numba compilation parameters; defaults to empty dict allowing decorator defaults."""

mapFolding/someAssemblyRequired/transformationTools.py

@@ -1,45 +1,42 @@
 """
-AST Transformation Tools for Python Code Generation
-
-This module provides tools for manipulating and transforming Python abstract syntax trees
-to generate optimized code. It implements a system that:
-
-1. Extracts functions and classes from existing modules.
-2. Reshapes and transforms them through AST manipulation.
-3. Manages dependencies and imports.
-4. Generates optimized code with specialized implementations.
-
-The module is particularly focused on transforming general-purpose Python code into
-high-performance implementations, especially through dataclass decomposition and
-function inlining for Numba compatibility.
-
-At its core, the module implements a transformation assembly-line where code flows from
-readable, maintainable implementations to highly optimized versions while preserving
-logical structure and correctness.
+Map folding AST transformation system: Core dataclass decomposition and function optimization tools.
+
+This module implements the essential transformation capabilities that form the operational core of
+the map folding AST transformation system. Working with the pattern recognition foundation and
+decomposition containers established in the foundational layers, these tools execute the critical
+transformations that convert dataclass-based functions into optimized implementations suitable
+for Numba just-in-time compilation.
+
+The transformation process addresses the fundamental incompatibility between dataclass-dependent
+map folding algorithms and Numba's compilation requirements. While dataclass instances provide
+clean, maintainable interfaces for complex mathematical state, Numba cannot directly process
+these objects but excels at optimizing operations on primitive values and tuples. The tools
+bridge this architectural gap through systematic function signature transformation and calling
+convention adaptation.
+
+The three-stage transformation pattern implemented here follows a precise sequence: dataclass
+decomposition breaks down dataclass definitions into constituent AST components while extracting
+field definitions and type annotations; function transformation converts functions accepting
+dataclass parameters to functions accepting individual field parameters with updated signatures
+and return types; caller adaptation modifies calling code to unpack dataclass instances, invoke
+transformed functions, and repack results back into dataclass instances.
+
+This approach enables seamless integration between high-level dataclass-based interfaces and
+low-level optimized implementations, maintaining code clarity while achieving performance gains
+through specialized compilation paths essential for computationally intensive map folding research.
 """
 
-from astToolkit import ClassIsAndAttribute
-from mapFolding.someAssemblyRequired import (
-	DeReConstructField2ast,
-	IfThis,
-	ShatteredDataclass,
-)
-from astToolkit import(
-	Be,
-	extractClassDef,
-	IngredientsFunction,
-	Make,
-	NodeChanger,
-	parseLogicalPath2astModule,
-	str_nameDOTname,
-	Then,
+from astToolkit import (
+	Be, ClassIsAndAttribute, extractClassDef, identifierDotAttribute, IngredientsFunction, Make,
+	NodeChanger, parseLogicalPath2astModule, Then,
 )
 from astToolkit.transformationTools import unparseFindReplace
+from mapFolding.someAssemblyRequired import DeReConstructField2ast, IfThis, ShatteredDataclass
 from Z0Z_tools import importLogicalPath2Callable
 import ast
 import dataclasses
 
-def shatter_dataclassesDOTdataclass(logicalPathModule: str_nameDOTname, dataclassIdentifier: str, instanceIdentifier: str) -> ShatteredDataclass:
+def shatter_dataclassesDOTdataclass(logicalPathModule: identifierDotAttribute, dataclassIdentifier: str, instanceIdentifier: str) -> ShatteredDataclass:
 	"""
 	Decompose a dataclass definition into AST components for manipulation and code generation.
 
@@ -72,8 +69,9 @@ def shatter_dataclassesDOTdataclass(logicalPathModule: str_nameDOTname, dataclas
 	Official_fieldOrder: list[str] = []
 	dictionaryDeReConstruction: dict[str, DeReConstructField2ast] = {}
 
-	dataclassClassDef = extractClassDef(parseLogicalPath2astModule(logicalPathModule), dataclassIdentifier)
-	if not isinstance(dataclassClassDef, ast.ClassDef): raise ValueError(f"I could not find `{dataclassIdentifier = }` in `{logicalPathModule = }`.")
+	dataclassClassDef: ast.ClassDef | None = extractClassDef(parseLogicalPath2astModule(logicalPathModule), dataclassIdentifier)
+	if not isinstance(dataclassClassDef, ast.ClassDef):
+		raise ValueError(f"I could not find `{dataclassIdentifier = }` in `{logicalPathModule = }`.")
 
 	countingVariable = None
 	for aField in dataclasses.fields(importLogicalPath2Callable(logicalPathModule, dataclassIdentifier)): # pyright: ignore [reportArgumentType]
@@ -81,11 +79,10 @@ def shatter_dataclassesDOTdataclass(logicalPathModule: str_nameDOTname, dataclas
 		dictionaryDeReConstruction[aField.name] = DeReConstructField2ast(logicalPathModule, dataclassClassDef, instanceIdentifier, aField)
 		if aField.metadata.get('theCountingIdentifier', False):
 			countingVariable = dictionaryDeReConstruction[aField.name].name
-
 	if countingVariable is None:
-		import warnings
-		warnings.warn(message=f"I could not find the counting variable in `{dataclassIdentifier = }` in `{logicalPathModule = }`.", category=UserWarning)
-		raise Exception
+		# import warnings
+		# warnings.warn(message=f"I could not find the counting variable in `{dataclassIdentifier = }` in `{logicalPathModule = }`.", category=UserWarning)
+		raise ValueError(f"I could not find the counting variable in `{dataclassIdentifier = }` in `{logicalPathModule = }`.")
 
 	shatteredDataclass = ShatteredDataclass(
 		countingVariableAnnotation=dictionaryDeReConstruction[countingVariable].astAnnotation,
@@ -109,7 +106,29 @@ def shatter_dataclassesDOTdataclass(logicalPathModule: str_nameDOTname, dataclas
 	return shatteredDataclass
 
 def removeDataclassFromFunction(ingredientsTarget: IngredientsFunction, shatteredDataclass: ShatteredDataclass) -> IngredientsFunction:
-	ingredientsTarget.astFunctionDef.args = Make.arguments(args=shatteredDataclass.list_argAnnotated4ArgumentsSpecification)
+	"""
+	Transform a function that operates on dataclass instances to work with individual field parameters.
+
+	This function performs the core transformation required for Numba compatibility by removing dataclass
+	dependencies from function signatures and implementations. It modifies the target function to:
+
+	1. Replace the single dataclass parameter with individual field parameters.
+	2. Update the return type annotation to return a tuple of field values.
+	3. Transform return statements to return the tuple of fields.
+	4. Replace all dataclass attribute access with direct field variable access.
+
+	This transformation is essential for creating Numba-compatible functions from dataclass-based
+	implementations, as Numba cannot handle dataclass instances directly but can efficiently
+	process individual primitive values and tuples.
+
+	Parameters:
+		ingredientsTarget: The function definition and its dependencies to be transformed.
+		shatteredDataclass: The decomposed dataclass components providing AST mappings and transformations.
+
+	Returns:
+		ingredientsTarget: The modified function ingredients with dataclass dependencies removed.
+	"""
+	ingredientsTarget.astFunctionDef.args = Make.arguments(list_arg=shatteredDataclass.list_argAnnotated4ArgumentsSpecification)
 	ingredientsTarget.astFunctionDef.returns = shatteredDataclass.signatureReturnAnnotation
 	changeReturnCallable = NodeChanger(Be.Return, Then.replaceWith(Make.Return(shatteredDataclass.fragments4AssignmentOrParameters)))
 	changeReturnCallable.visit(ingredientsTarget.astFunctionDef)
@@ -117,6 +136,31 @@ def removeDataclassFromFunction(ingredientsTarget: IngredientsFunction, shattere
 	return ingredientsTarget
 
 def unpackDataclassCallFunctionRepackDataclass(ingredientsCaller: IngredientsFunction, targetCallableIdentifier: str, shatteredDataclass: ShatteredDataclass) -> IngredientsFunction:
+	"""
+	Transform a caller function to interface with a dataclass-free target function.
+
+	This function complements `removeDataclassFromFunction` by modifying calling code to work with
+	the transformed target function. It implements the unpacking and repacking pattern required
+	when a dataclass-based caller needs to invoke a function that has been converted to accept
+	individual field parameters instead of dataclass instances.
+
+	The transformation creates a three-step pattern around the target function call:
+	1. Unpack the dataclass instance into individual field variables.
+	2. Call the target function with the unpacked field values.
+	3. Repack the returned field values back into a dataclass instance.
+
+	This enables seamless integration between dataclass-based high-level code and optimized
+	field-based implementations, maintaining the original interface while enabling performance
+	optimizations in the target function.
+
+	Parameters:
+		ingredientsCaller: The calling function definition and its dependencies to be transformed.
+		targetCallableIdentifier: The name of the target function being called.
+		shatteredDataclass: The decomposed dataclass components providing unpacking and repacking logic.
+
+	Returns:
+		ingredientsCaller: The modified caller function with appropriate unpacking and repacking around the target call.
+	"""
 	astCallTargetCallable = Make.Call(Make.Name(targetCallableIdentifier), shatteredDataclass.listName4Parameters)
 	replaceAssignTargetCallable = NodeChanger(ClassIsAndAttribute.valueIs(ast.Assign, IfThis.isCallIdentifier(targetCallableIdentifier)), Then.replaceWith(Make.Assign([shatteredDataclass.fragments4AssignmentOrParameters], value=astCallTargetCallable)))
 	unpack4targetCallable = NodeChanger(ClassIsAndAttribute.valueIs(ast.Assign, IfThis.isCallIdentifier(targetCallableIdentifier)), Then.insertThisAbove(shatteredDataclass.listUnpack))