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

mapFolding/someAssemblyRequired/synthesizeNumbaJob.py

@@ -1,14 +1,35 @@
-"""Synthesize one file to compute `foldsTotal` of `mapShape`."""
+"""
+Job-specific Numba Code Generation for Map Folding Calculations
+
+This module specializes in generating highly-optimized, single-purpose Numba modules
+for specific map folding calculation jobs. Unlike the general-purpose transformation
+in toolboxNumba.py, this module creates standalone Python modules optimized for a
+single map shape with statically-encoded parameters.
+
+The code generation pipeline focuses on:
+
+1. Converting function parameters to initialized variables with concrete values.
+2. Replacing dynamic computations with statically-known values.
+3. Eliminating unused code paths and variables.
+4. Adding progress tracking for long-running calculations.
+5. Applying appropriate Numba optimizations for the specific calculation.
+
+This creates extremely fast, specialized implementations that can be run directly
+as Python scripts or further compiled into standalone executables.
+"""
+
 from mapFolding.toolboxFilesystem import getPathFilenameFoldsTotal
-from mapFolding.someAssemblyRequired import ast_Identifier, be, ifThis, Make, NodeChanger, Then, IngredientsFunction, IngredientsModule
+from mapFolding.someAssemblyRequired import ast_Identifier, ifThis, Make, NodeChanger, Then, IngredientsFunction, IngredientsModule, LedgerOfImports
 from mapFolding.someAssemblyRequired.toolboxNumba import RecipeJob, SpicesJobNumba, decorateCallableWithNumba
-from mapFolding.someAssemblyRequired.transformationTools import astModuleToIngredientsFunction, write_astModule
+from mapFolding.someAssemblyRequired.transformationTools import extractFunctionDef, write_astModule
 from mapFolding.someAssemblyRequired.transformationTools import makeInitializedComputationState
-from mapFolding.theSSOT import The
+from mapFolding.theSSOT import The, raiseIfNoneGitHubIssueNumber3
+from mapFolding.oeis import getFoldsTotalKnown
 from typing import cast
 from Z0Z_tools import autoDecodingRLE
 from pathlib import PurePosixPath
 import ast
+"""Synthesize one file to compute `foldsTotal` of `mapShape`."""
 
 list_IdentifiersNotUsedAllHARDCODED = ['concurrencyLimit', 'foldsTotal', 'mapShape',]
 list_IdentifiersNotUsedParallelSequentialHARDCODED = ['indexLeaf']
@@ -21,13 +42,36 @@ list_IdentifiersStaticValuesHARDCODED = ['dimensionsTotal', 'leavesTotal',]
 list_IdentifiersNotUsedHARDCODED = list_IdentifiersStaticValuesHARDCODED + list_IdentifiersReplacedHARDCODED + list_IdentifiersNotUsedAllHARDCODED + list_IdentifiersNotUsedParallelSequentialHARDCODED + list_IdentifiersNotUsedSequentialHARDCODED
 
 def addLauncherNumbaProgress(ingredientsModule: IngredientsModule, ingredientsFunction: IngredientsFunction, job: RecipeJob, spices: SpicesJobNumba) -> tuple[IngredientsModule, IngredientsFunction]:
+	"""
+	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:
+
+	1. Adds a progress bar parameter to the function signature
+	2. Replaces counting increments with progress bar updates
+	3. Creates a launcher section that displays and updates progress
+	4. Configures file output to save results upon completion
 
+	The progress tracking is particularly important for map folding calculations
+	which can take hours or days to complete, providing visual feedback and
+	estimated completion times.
+
+	Parameters:
+		ingredientsModule: The module where the function is defined.
+		ingredientsFunction: The function to modify with progress tracking.
+		job: Configuration specifying shape details and output paths.
+		spices: Configuration specifying progress bar details.
+
+	Returns:
+		A tuple containing the modified module and function with progress tracking.
+	"""
 	linesLaunch: str = f"""
 if __name__ == '__main__':
 	with ProgressBar(total={job.foldsTotalEstimated}, update_interval=2) as statusUpdate:
 		{job.countCallable}(statusUpdate)
 		foldsTotal = statusUpdate.n * {job.state.leavesTotal}
-		print('map {job.state.mapShape} =', foldsTotal)
+		print('\\nmap {job.state.mapShape} =', foldsTotal)
 		writeStream = open('{job.pathFilenameFoldsTotal.as_posix()}', 'w')
 		writeStream.write(str(foldsTotal))
 		writeStream.close()
@@ -50,12 +94,35 @@ if __name__ == '__main__':
 	return ingredientsModule, ingredientsFunction
 
 def move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsFunction: IngredientsFunction, job: RecipeJob) -> IngredientsFunction:
+	"""
+	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.
+
+	The function handles different data types (scalars, arrays, custom types) appropriately,
+	replacing abstract parameter references with concrete values from the computation state.
+	It also removes unused parameters and variables to eliminate dead code.
+
+	Parameters:
+		ingredientsFunction: The function to transform.
+		job: Recipe containing concrete values for parameters and field metadata.
+
+	Returns:
+		The modified function with parameters converted to initialized variables.
+	"""
 	ingredientsFunction.imports.update(job.shatteredDataclass.ledger)
 
 	list_IdentifiersNotUsed = list_IdentifiersNotUsedHARDCODED
 
-	list_argCauseMyBrainRefusesToDoThisTheRightWay = ingredientsFunction.astFunctionDef.args.args + ingredientsFunction.astFunctionDef.args.posonlyargs + ingredientsFunction.astFunctionDef.args.kwonlyargs
-	for ast_arg in list_argCauseMyBrainRefusesToDoThisTheRightWay:
+	list_argCuzMyBrainRefusesToThink = ingredientsFunction.astFunctionDef.args.args + ingredientsFunction.astFunctionDef.args.posonlyargs + ingredientsFunction.astFunctionDef.args.kwonlyargs
+	for ast_arg in list_argCuzMyBrainRefusesToThink:
 		if ast_arg.arg in job.shatteredDataclass.field2AnnAssign:
 			if ast_arg.arg in list_IdentifiersNotUsed:
 				pass
@@ -63,12 +130,11 @@ def move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsFunction: Ingre
 				ImaAnnAssign, elementConstructor = job.shatteredDataclass.Z0Z_field2AnnAssign[ast_arg.arg]
 				match elementConstructor:
 					case 'scalar':
-						ImaAnnAssign.value.args[0].value = int(job.state.__dict__[ast_arg.arg])  # type: ignore
+						ImaAnnAssign.value.args[0].value = int(job.state.__dict__[ast_arg.arg]) # type: ignore
 					case 'array':
-						# print(ast.dump(ImaAnnAssign))
 						dataAsStrRLE: str = autoDecodingRLE(job.state.__dict__[ast_arg.arg], addSpaces=True)
 						dataAs_astExpr: ast.expr = cast(ast.Expr, ast.parse(dataAsStrRLE).body[0]).value
-						ImaAnnAssign.value.args = [dataAs_astExpr]  # type: ignore
+						ImaAnnAssign.value.args = [dataAs_astExpr] # type: ignore
 					case _:
 						list_exprDOTannotation: list[ast.expr] = []
 						list_exprDOTvalue: list[ast.expr] = []
@@ -87,12 +153,36 @@ def move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsFunction: Ingre
 	ast.fix_missing_locations(ingredientsFunction.astFunctionDef)
 	return ingredientsFunction
 
-def makeJobNumba(job: RecipeJob, spices: SpicesJobNumba):
-		# get the raw ingredients: data and the algorithm
-	ingredientsCount: IngredientsFunction = astModuleToIngredientsFunction(job.source_astModule, job.countCallable)
+def makeJobNumba(job: RecipeJob, spices: SpicesJobNumba) -> None:
+	"""
+	Generate a highly-optimized, single-purpose Numba module for a specific map shape.
+
+	This function implements the complete transformation pipeline for creating a
+	standalone, specialized implementation for calculating map folding solutions for
+	a specific shape. The process includes:
+
+	1. Extracting the counting function from the source module
+	2. Removing unused code paths based on static analysis
+	3. Replacing dynamic variables with concrete values
+	4. Converting parameters to initialized variables
+	5. Adding progress tracking if requested
+	6. Applying Numba optimizations and type specifications
+	7. Writing the final module to the filesystem
+
+	The resulting Python module is both human-readable and extraordinarily efficient,
+	with all shape-specific optimizations statically encoded. This creates specialized
+	implementations that can be orders of magnitude faster than general-purpose code.
+
+	Parameters:
+		job: Configuration specifying the target shape, paths, and computation state.
+		spices: Configuration specifying Numba and progress tracking options.
+	"""
+	astFunctionDef = extractFunctionDef(job.source_astModule, job.countCallable)
+	if not astFunctionDef: raise raiseIfNoneGitHubIssueNumber3
+	ingredientsCount: IngredientsFunction = IngredientsFunction(astFunctionDef, LedgerOfImports())
 
 	# Change the return so you can dynamically determine which variables are not used
-	removeReturnStatement = NodeChanger(be.Return, Then.removeIt)
+	removeReturnStatement = NodeChanger(lambda node: isinstance(node, ast.Return), Then.removeIt) # type: ignore
 	removeReturnStatement.visit(ingredientsCount.astFunctionDef)
 	ingredientsCount.astFunctionDef.returns = Make.Constant(value=None)
 
@@ -110,21 +200,51 @@ def makeJobNumba(job: RecipeJob, spices: SpicesJobNumba):
 		NodeChanger(findThis, doThat).visit(ingredientsCount.astFunctionDef)
 
 	# This launcher eliminates the use of one identifier, so run it now and you can dynamically determine which variables are not used
+	ingredientsModule = IngredientsModule()
 	if spices.useNumbaProgressBar:
-		ingredientsModule = IngredientsModule()
 		ingredientsModule, ingredientsCount = addLauncherNumbaProgress(ingredientsModule, ingredientsCount, job, spices)
 		spices.parametersNumba['nogil'] = True
 
 	ingredientsCount = move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsCount, job)
 
+	Z0Z_Identifier = 'DatatypeLeavesTotal'
+	Z0Z_type = 'uint8'
+	ingredientsModule.imports.addImportFrom_asStr('numba', Z0Z_type)
+	Z0Z_module = 'typing'
+	Z0Z_annotation = 'TypeAlias'
+	ingredientsModule.imports.addImportFrom_asStr(Z0Z_module, Z0Z_annotation)
+	Z0Z_statement = Make.AnnAssign(Make.Name(Z0Z_Identifier, ast.Store()), Make.Name(Z0Z_annotation), Make.Name(Z0Z_type))
+	ingredientsModule.appendPrologue(statement=Z0Z_statement)
+
+	Z0Z_Identifier = 'DatatypeElephino'
+	Z0Z_type = 'int16'
+	ingredientsModule.imports.addImportFrom_asStr('numba', Z0Z_type)
+	Z0Z_module = 'typing'
+	Z0Z_annotation = 'TypeAlias'
+	ingredientsModule.imports.addImportFrom_asStr(Z0Z_module, Z0Z_annotation)
+	Z0Z_statement = Make.AnnAssign(Make.Name(Z0Z_Identifier, ast.Store()), Make.Name(Z0Z_annotation), Make.Name(Z0Z_type))
+	ingredientsModule.appendPrologue(statement=Z0Z_statement)
+
+	ingredientsCount.imports.removeImportFromModule('mapFolding.theSSOT')
+	Z0Z_module = 'numpy'
+	Z0Z_asname = 'Array1DLeavesTotal'
+	ingredientsCount.imports.removeImportFrom(Z0Z_module, None, Z0Z_asname)
+	Z0Z_type_name = 'uint8'
+	ingredientsCount.imports.addImportFrom_asStr(Z0Z_module, Z0Z_type_name, Z0Z_asname)
+	Z0Z_asname = 'Array1DElephino'
+	ingredientsCount.imports.removeImportFrom(Z0Z_module, None, Z0Z_asname)
+	Z0Z_type_name = 'int16'
+	ingredientsCount.imports.addImportFrom_asStr(Z0Z_module, Z0Z_type_name, Z0Z_asname)
+	Z0Z_asname = 'Array3D'
+	ingredientsCount.imports.removeImportFrom(Z0Z_module, None, Z0Z_asname)
+	Z0Z_type_name = 'uint8'
+	ingredientsCount.imports.addImportFrom_asStr(Z0Z_module, Z0Z_type_name, Z0Z_asname)
+
 	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)
-
-		# add imports, make str, remove unused imports
-		# put on disk
 	write_astModule(ingredientsModule, job.pathFilenameModule, job.packageIdentifier)
 
 	"""
@@ -149,10 +269,11 @@ def makeJobNumba(job: RecipeJob, spices: SpicesJobNumba):
 	"""
 
 if __name__ == '__main__':
-	mapShape = (3,4)
+	mapShape = (2,4)
 	state = makeInitializedComputationState(mapShape)
+	foldsTotalEstimated = getFoldsTotalKnown(state.mapShape) // state.leavesTotal
 	pathModule = PurePosixPath(The.pathPackage, 'jobs')
 	pathFilenameFoldsTotal = PurePosixPath(getPathFilenameFoldsTotal(state.mapShape, pathModule))
-	aJob = RecipeJob(state, pathModule=pathModule, pathFilenameFoldsTotal=pathFilenameFoldsTotal)
+	aJob = RecipeJob(state, foldsTotalEstimated, pathModule=pathModule, pathFilenameFoldsTotal=pathFilenameFoldsTotal)
 	spices = SpicesJobNumba()
 	makeJobNumba(aJob, spices)

mapFolding/someAssemblyRequired/toolboxNumba.py

@@ -1,45 +1,42 @@
 """
-Numba-specific ingredients for optimized code generation.
+Numba-specific Tools for Generating Optimized Code
 
-This module provides specialized tools, constants, and types specifically designed
-for transforming Python code into Numba-accelerated implementations. It implements:
+This module provides specialized tools for transforming standard Python code into
+Numba-accelerated implementations. It implements a comprehensive transformation
+assembly-line that:
 
-1. A range of Numba jit decorator configurations for different optimization scenarios
-2. Functions to identify and manipulate Numba decorators in abstract syntax trees
-3. Utilities for applying appropriate Numba typing to transformed code
-4. Parameter management for Numba compilation options
+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 configurations range from conservative options that prioritize compatibility and
-error detection to aggressive optimizations that maximize performance at the cost of
-flexibility. While this module specifically targets Numba, its design follows the pattern
-of generic code transformation tools in the package, allowing similar approaches to be
-applied to other acceleration technologies.
-
-This module works in conjunction with transformation tools to convert the general-purpose
-algorithm implementation into a highly-optimized Numba version.
+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.
 """
 
 from collections.abc import Callable, Sequence
+from mapFolding.someAssemblyRequired import grab, IngredientsModule, LedgerOfImports, Make, NodeChanger, NodeTourist, RecipeSynthesizeFlow, Then, ast_Identifier, ifThis, parsePathFilename2astModule, str_nameDOTname, IngredientsFunction, ShatteredDataclass
+from mapFolding.someAssemblyRequired.transformationTools import inlineFunctionDef, Z0Z_lameFindReplace, astModuleToIngredientsFunction, shatter_dataclassesDOTdataclass, write_astModule
+from mapFolding.theSSOT import ComputationState, DatatypeFoldsTotal as TheDatatypeFoldsTotal, DatatypeElephino as TheDatatypeElephino, DatatypeLeavesTotal as TheDatatypeLeavesTotal
 from mapFolding.toolboxFilesystem import getPathFilenameFoldsTotal, getPathRootJobDEFAULT
-from mapFolding.someAssemblyRequired import IngredientsModule, LedgerOfImports, Make, NodeChanger, NodeTourist, RecipeSynthesizeFlow, Then, ast_Identifier, be, ifThis, parsePathFilename2astModule, str_nameDOTname, IngredientsFunction, ShatteredDataclass
-from mapFolding.someAssemblyRequired.transformationTools import Z0Z_inlineThisFunctionWithTheseValues, Z0Z_lameFindReplace, Z0Z_makeDictionaryReplacementStatements, astModuleToIngredientsFunction, shatter_dataclassesDOTdataclass, write_astModule
-from mapFolding.theSSOT import ComputationState
 from numba.core.compiler import CompilerBase as numbaCompilerBase
 from pathlib import Path, PurePosixPath
-from typing import Any, cast, Final, TYPE_CHECKING
+from typing import Any, cast, Final, TYPE_CHECKING, TypeAlias, TypeGuard
 import ast
 import dataclasses
 
 try:
 	from typing import NotRequired
 except Exception:
-	from typing_extensions import NotRequired
+	from typing_extensions import NotRequired # pyright: ignore[reportShadowedImports]
 
 if TYPE_CHECKING:
 	from typing import TypedDict
 else:
 	TypedDict = dict[str,Any]
 
+# Consolidate settings classes through inheritance https://github.com/hunterhogan/mapFolding/issues/15
 theNumbaFlow: RecipeSynthesizeFlow = RecipeSynthesizeFlow()
 
 class ParametersNumba(TypedDict):
@@ -78,8 +75,8 @@ parametersNumbaSuperJitParallel: Final[ParametersNumba] = { **parametersNumbaSup
 """Speed, no helmet, concurrency, no talking to non-jitted functions."""
 parametersNumbaMinimum: Final[ParametersNumba] = { '_nrt': True, 'boundscheck': True, 'cache': True, 'error_model': 'numpy', 'fastmath': True, 'forceinline': False, 'inline': 'always', 'looplift': False, 'no_cfunc_wrapper': False, 'no_cpython_wrapper': False, 'nopython': False, 'forceobj': True, 'parallel': False, }
 
-Z0Z_numbaDataTypeModule = 'numba'
-Z0Z_decoratorCallable = 'jit'
+Z0Z_numbaDataTypeModule: str_nameDOTname = 'numba'
+Z0Z_decoratorCallable: ast_Identifier = 'jit'
 
 def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, parametersNumba: ParametersNumba | None = None) -> IngredientsFunction:
 	def Z0Z_UnhandledDecorators(astCallable: ast.FunctionDef) -> ast.FunctionDef:
@@ -90,7 +87,7 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 			warnings.warn(f"Removed decorator {ast.unparse(decoratorItem)} from {astCallable.name}")
 		return astCallable
 
-	def makeSpecialSignatureForNumba(signatureElement: ast.arg) -> ast.Subscript | ast.Name | None: # type: ignore
+	def makeSpecialSignatureForNumba(signatureElement: ast.arg) -> ast.Subscript | ast.Name | None: # pyright: ignore[reportUnusedFunction]
 		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):
@@ -123,7 +120,6 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 
 	list_arg4signature_or_function: list[ast.expr] = []
 	for parameter in ingredientsFunction.astFunctionDef.args.args:
-		# Efficient translation of Python scalar types to Numba types https://github.com/hunterhogan/mapFolding/issues/8
 		# For now, let Numba infer them.
 		continue
 		# signatureElement: ast.Subscript | ast.Name | None = makeSpecialSignatureForNumba(parameter)
@@ -142,8 +138,8 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 		parametersNumba = parametersNumbaDefault
 	listDecoratorKeywords: list[ast.keyword] = [Make.keyword(parameterName, Make.Constant(parameterValue)) for parameterName, parameterValue in parametersNumba.items()]
 
-	decoratorModule: str = Z0Z_numbaDataTypeModule
-	decoratorCallable: str = Z0Z_decoratorCallable
+	decoratorModule = Z0Z_numbaDataTypeModule
+	decoratorCallable = Z0Z_decoratorCallable
 	ingredientsFunction.imports.addImportFrom_asStr(decoratorModule, decoratorCallable)
 	# Leave this line in so that global edits will change it.
 	astDecorator: ast.Call = Make.Call(Make.Name(decoratorCallable), list_argsDecorator, listDecoratorKeywords)
@@ -152,18 +148,20 @@ def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, paramete
 	ingredientsFunction.astFunctionDef.decorator_list = [astDecorator]
 	return ingredientsFunction
 
+# Consolidate settings classes through inheritance https://github.com/hunterhogan/mapFolding/issues/15
 @dataclasses.dataclass
 class SpicesJobNumba:
 	useNumbaProgressBar: bool = True
 	numbaProgressBarIdentifier: ast_Identifier = 'ProgressBarGroupsOfFolds'
 	parametersNumba = parametersNumbaDefault
 
+# Consolidate settings classes through inheritance https://github.com/hunterhogan/mapFolding/issues/15
 @dataclasses.dataclass
 class RecipeJob:
 	state: ComputationState
 	# TODO create function to calculate `foldsTotalEstimated`
 	foldsTotalEstimated: int = 0
-	shatteredDataclass: ShatteredDataclass = dataclasses.field(default=None, init=True) # type: ignore[assignment, reportAssignmentType]
+	shatteredDataclass: ShatteredDataclass = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType]
 
 	# ========================================
 	# Source
@@ -183,20 +181,25 @@ class RecipeJob:
 	pathModule: PurePosixPath | None = PurePosixPath(getPathRootJobDEFAULT())
 	""" `pathModule` will override `pathPackage` and `logicalPathRoot`."""
 	fileExtension: str = theNumbaFlow.fileExtension
-	pathFilenameFoldsTotal: PurePosixPath = dataclasses.field(default=None, init=True) # type: ignore[assignment, reportAssignmentType]
+	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) # type: ignore[assignment, reportAssignmentType]
+	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,
@@ -225,13 +228,13 @@ class RecipeJob:
 	def __post_init__(self):
 		pathFilenameFoldsTotal = PurePosixPath(getPathFilenameFoldsTotal(self.state.mapShape))
 
-		if self.moduleIdentifier is None:
+		if self.moduleIdentifier is None: # pyright: ignore[reportUnnecessaryComparison]
 			self.moduleIdentifier = pathFilenameFoldsTotal.stem
 
-		if self.pathFilenameFoldsTotal is None:
+		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:
+		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)
 
 	# ========================================
@@ -247,7 +250,39 @@ class RecipeJob:
 	concurrencyManagerNamespace: ast_Identifier = sourceConcurrencyManagerNamespace
 	concurrencyManagerIdentifier: ast_Identifier = sourceConcurrencyManagerIdentifier
 
+class be:
+	@staticmethod
+	def Call(node: ast.AST) -> TypeGuard[ast.Call]:
+		return isinstance(node, ast.Call)
+	@staticmethod
+	def Return(node: ast.AST) -> TypeGuard[ast.Return]:
+		return isinstance(node, ast.Return)
+
 def makeNumbaFlow(numbaFlow: RecipeSynthesizeFlow) -> None:
+	"""
+	Transform standard Python algorithm code into optimized Numba implementations.
+
+	This function implements the complete transformation pipeline that converts
+	a conventional Python implementation into a high-performance Numba-accelerated
+	version. The process includes:
+
+	1. Extracting core algorithm functions from the source module
+	2. Inlining function calls to create self-contained implementations
+	3. Transforming dataclass access patterns for Numba compatibility
+	4. Applying appropriate Numba decorators with optimization settings
+	5. Generating a unified module with sequential and parallel implementations
+	6. Writing the transformed code to the filesystem with properly managed imports
+
+	The transformation preserves the logical structure and semantics of the original
+	implementation while making it compatible with Numba's constraints and
+	optimization capabilities. This creates a bridge between the general-purpose
+	implementation and the highly-optimized version needed for production use.
+
+	Parameters:
+		numbaFlow: Configuration object that specifies all aspects of the
+					transformation process, including source and target locations,
+					function and variable names, and output paths.
+	"""
 	# TODO a tool to automatically remove unused variables from the ArgumentsSpecification (return, and returns) _might_ be nice.
 	# Figure out dynamic flow control to synthesized modules https://github.com/hunterhogan/mapFolding/issues/4
 
@@ -259,14 +294,14 @@ def makeNumbaFlow(numbaFlow: RecipeSynthesizeFlow) -> None:
 	]
 
 	# Inline functions ========================================================
-	dictionaryReplacementStatements = Z0Z_makeDictionaryReplacementStatements(numbaFlow.source_astModule)
 	# NOTE Replacements statements are based on the identifiers in the _source_, so operate on the source identifiers.
-	ingredientsInitialize.astFunctionDef = Z0Z_inlineThisFunctionWithTheseValues(ingredientsInitialize.astFunctionDef, dictionaryReplacementStatements)
-	ingredientsParallel.astFunctionDef = Z0Z_inlineThisFunctionWithTheseValues(ingredientsParallel.astFunctionDef, dictionaryReplacementStatements)
-	ingredientsSequential.astFunctionDef = Z0Z_inlineThisFunctionWithTheseValues(ingredientsSequential.astFunctionDef, dictionaryReplacementStatements)
+	ingredientsInitialize.astFunctionDef = inlineFunctionDef(numbaFlow.sourceCallableInitialize, numbaFlow.source_astModule)
+	ingredientsParallel.astFunctionDef = inlineFunctionDef(numbaFlow.sourceCallableParallel, numbaFlow.source_astModule)
+	ingredientsSequential.astFunctionDef = inlineFunctionDef(numbaFlow.sourceCallableSequential, numbaFlow.source_astModule)
 
 	# assignRecipeIdentifiersToCallable. =============================
-	# TODO How can I use `RecipeSynthesizeFlow` as the SSOT for the pairs of items that may need to be replaced?
+	# Consolidate settings classes through inheritance https://github.com/hunterhogan/mapFolding/issues/15
+	# How can I use dataclass settings as the SSOT for specific actions? https://github.com/hunterhogan/mapFolding/issues/16
 	# NOTE reminder: you are updating these `ast.Name` here (and not in a more general search) because this is a
 	# narrow search for `ast.Call` so you won't accidentally replace unrelated `ast.Name`.
 	listFindReplace = [(numbaFlow.sourceCallableDispatcher, numbaFlow.callableDispatcher),
@@ -275,7 +310,7 @@ def makeNumbaFlow(numbaFlow: RecipeSynthesizeFlow) -> None:
 						(numbaFlow.sourceCallableSequential, numbaFlow.callableSequential),]
 	for ingredients in listAllIngredientsFunctions:
 		for source_Identifier, recipe_Identifier in listFindReplace:
-			updateCallName = NodeChanger(ifThis.isCall_Identifier(source_Identifier), Then.DOTfunc(Then.replaceWith(Make.Name(recipe_Identifier))))
+			updateCallName = NodeChanger(ifThis.isCall_Identifier(source_Identifier), grab.funcAttribute(Then.replaceWith(Make.Name(recipe_Identifier))))
 			updateCallName.visit(ingredients.astFunctionDef)
 
 	ingredientsDispatcher.astFunctionDef.name = numbaFlow.callableDispatcher
@@ -289,13 +324,13 @@ def makeNumbaFlow(numbaFlow: RecipeSynthesizeFlow) -> None:
 		(numbaFlow.sourceConcurrencyManagerNamespace, numbaFlow.concurrencyManagerNamespace),]
 	for ingredients in listAllIngredientsFunctions:
 		for source_Identifier, recipe_Identifier in listFindReplace:
-			updateName = NodeChanger(ifThis.isName_Identifier(source_Identifier), Then.DOTid(Then.replaceWith(recipe_Identifier)))
-			update_arg = NodeChanger(ifThis.isArgument_Identifier(source_Identifier), Then.DOTarg(Then.replaceWith(recipe_Identifier)))
+			updateName = NodeChanger(ifThis.isName_Identifier(source_Identifier) , grab.idAttribute(Then.replaceWith(recipe_Identifier)))
+			update_arg = NodeChanger(ifThis.isArgument_Identifier(source_Identifier), grab.argAttribute(Then.replaceWith(recipe_Identifier)))
 			updateName.visit(ingredients.astFunctionDef)
 			update_arg.visit(ingredients.astFunctionDef)
 
 	updateConcurrencyManager = NodeChanger(ifThis.isCallAttributeNamespace_Identifier(numbaFlow.sourceConcurrencyManagerNamespace, numbaFlow.sourceConcurrencyManagerIdentifier)
-										, Then.DOTfunc(Then.replaceWith(Make.Attribute(Make.Name(numbaFlow.concurrencyManagerNamespace), numbaFlow.concurrencyManagerIdentifier))))
+										, grab.funcAttribute(Then.replaceWith(Make.Attribute(Make.Name(numbaFlow.concurrencyManagerNamespace), numbaFlow.concurrencyManagerIdentifier))))
 	updateConcurrencyManager.visit(ingredientsDispatcher.astFunctionDef)
 
 	# shatter Dataclass =======================================================
@@ -304,25 +339,24 @@ def makeNumbaFlow(numbaFlow: RecipeSynthesizeFlow) -> None:
 	shatteredDataclass = shatter_dataclassesDOTdataclass(numbaFlow.logicalPathModuleDataclass, numbaFlow.sourceDataclassIdentifier, instance_Identifier)
 	ingredientsDispatcher.imports.update(shatteredDataclass.ledger)
 
+	# How can I use dataclass settings as the SSOT for specific actions? https://github.com/hunterhogan/mapFolding/issues/16
 	# Change callable parameters and Call to the callable at the same time ====
-	# TODO How can I use ast and/or other tools to ensure that when I change a callable, I also change the statements that call the callable?
-	# Asked differently, how do I integrate separate statements into a "subroutine", and that subroutine is "atomic/indivisible"?
 	# sequentialCallable =========================================================
 	ingredientsSequential.astFunctionDef.args = Make.argumentsSpecification(args=shatteredDataclass.list_argAnnotated4ArgumentsSpecification)
 	astCallSequentialCallable = Make.Call(Make.Name(numbaFlow.callableSequential), shatteredDataclass.listName4Parameters)
 	changeReturnSequentialCallable = NodeChanger(be.Return, Then.replaceWith(Make.Return(shatteredDataclass.fragments4AssignmentOrParameters)))
 	ingredientsSequential.astFunctionDef.returns = shatteredDataclass.signatureReturnAnnotation
-	replaceAssignSequentialCallable = NodeChanger(ifThis.isAssignAndValueIsCall_Identifier(numbaFlow.callableSequential), Then.replaceWith(Make.Assign(listTargets=[shatteredDataclass.fragments4AssignmentOrParameters], value=astCallSequentialCallable)))
+	replaceAssignSequentialCallable = NodeChanger(ifThis.isAssignAndValueIs(ifThis.isCall_Identifier(numbaFlow.callableSequential)), Then.replaceWith(Make.Assign(listTargets=[shatteredDataclass.fragments4AssignmentOrParameters], value=astCallSequentialCallable)))
 
-	unpack4sequentialCallable = NodeChanger(ifThis.isAssignAndValueIsCall_Identifier(numbaFlow.callableSequential), Then.insertThisAbove(shatteredDataclass.listUnpack))
-	repack4sequentialCallable = NodeChanger(ifThis.isAssignAndValueIsCall_Identifier(numbaFlow.callableSequential), Then.insertThisBelow([shatteredDataclass.repack]))
+	unpack4sequentialCallable = NodeChanger(ifThis.isAssignAndValueIs(ifThis.isCall_Identifier(numbaFlow.callableSequential)), Then.insertThisAbove(shatteredDataclass.listUnpack))
+	repack4sequentialCallable = NodeChanger(ifThis.isAssignAndValueIs(ifThis.isCall_Identifier(numbaFlow.callableSequential)), Then.insertThisBelow([shatteredDataclass.repack]))
 
 	changeReturnSequentialCallable.visit(ingredientsSequential.astFunctionDef)
 	replaceAssignSequentialCallable.visit(ingredientsDispatcher.astFunctionDef)
 	unpack4sequentialCallable.visit(ingredientsDispatcher.astFunctionDef)
 	repack4sequentialCallable.visit(ingredientsDispatcher.astFunctionDef)
 
-	ingredientsSequential.astFunctionDef = Z0Z_lameFindReplace(ingredientsSequential.astFunctionDef, shatteredDataclass.map_stateDOTfield2Name) # type: ignore
+	ingredientsSequential.astFunctionDef = Z0Z_lameFindReplace(ingredientsSequential.astFunctionDef, shatteredDataclass.map_stateDOTfield2Name)
 
 	# parallelCallable =========================================================
 	ingredientsParallel.astFunctionDef.args = Make.argumentsSpecification(args=shatteredDataclass.list_argAnnotated4ArgumentsSpecification)
@@ -330,20 +364,20 @@ def makeNumbaFlow(numbaFlow: RecipeSynthesizeFlow) -> None:
 
 	# NOTE I am dissatisfied with this logic for many reasons, including that it requires separate NodeCollector and NodeReplacer instances.
 	astCallConcurrencyResult: list[ast.Call] = []
-	get_astCallConcurrencyResult: NodeTourist = NodeTourist(ifThis.isAssignAndTargets0Is(ifThis.isSubscript_Identifier(getTheOtherRecord_damn)), lambda node: NodeTourist(be.Call, Then.appendTo(astCallConcurrencyResult)).visit(node)) # pyright: ignore[reportUnknownArgumentType, reportUnknownLambdaType]
+	get_astCallConcurrencyResult = NodeTourist(ifThis.isAssignAndTargets0Is(ifThis.isSubscript_Identifier(getTheOtherRecord_damn)), getIt(astCallConcurrencyResult))
 	get_astCallConcurrencyResult.visit(ingredientsDispatcher.astFunctionDef)
-	replaceAssignParallelCallable = NodeChanger(ifThis.isAssignAndTargets0Is(ifThis.isSubscript_Identifier(getTheOtherRecord_damn)), Then.DOTvalue(Then.replaceWith(astCallConcurrencyResult[0])))
+	replaceAssignParallelCallable = NodeChanger(ifThis.isAssignAndTargets0Is(ifThis.isSubscript_Identifier(getTheOtherRecord_damn)), grab.valueAttribute(Then.replaceWith(astCallConcurrencyResult[0])))
 	replaceAssignParallelCallable.visit(ingredientsDispatcher.astFunctionDef)
 	changeReturnParallelCallable = NodeChanger(be.Return, Then.replaceWith(Make.Return(shatteredDataclass.countingVariableName)))
 	ingredientsParallel.astFunctionDef.returns = shatteredDataclass.countingVariableAnnotation
 
-	unpack4parallelCallable = NodeChanger(ifThis.isAssignAndValueIsCallAttributeNamespace_Identifier(numbaFlow.concurrencyManagerNamespace, numbaFlow.concurrencyManagerIdentifier), Then.insertThisAbove(shatteredDataclass.listUnpack))
+	unpack4parallelCallable = NodeChanger(ifThis.isAssignAndValueIs(ifThis.isCallAttributeNamespace_Identifier(numbaFlow.concurrencyManagerNamespace, numbaFlow.concurrencyManagerIdentifier)), Then.insertThisAbove(shatteredDataclass.listUnpack))
 
 	unpack4parallelCallable.visit(ingredientsDispatcher.astFunctionDef)
 	replaceCall2concurrencyManager.visit(ingredientsDispatcher.astFunctionDef)
 	changeReturnParallelCallable.visit(ingredientsParallel.astFunctionDef)
 
-	ingredientsParallel.astFunctionDef = Z0Z_lameFindReplace(ingredientsParallel.astFunctionDef, shatteredDataclass.map_stateDOTfield2Name) # type: ignore
+	ingredientsParallel.astFunctionDef = Z0Z_lameFindReplace(ingredientsParallel.astFunctionDef, shatteredDataclass.map_stateDOTfield2Name)
 
 	# numba decorators =========================================
 	ingredientsParallel = decorateCallableWithNumba(ingredientsParallel)
@@ -351,8 +385,15 @@ def makeNumbaFlow(numbaFlow: RecipeSynthesizeFlow) -> None:
 
 	# Module-level transformations ===========================================================
 	ingredientsModuleNumbaUnified = IngredientsModule(ingredientsFunction=listAllIngredientsFunctions, imports=LedgerOfImports(numbaFlow.source_astModule))
+	ingredientsModuleNumbaUnified.removeImportFromModule('numpy')
 
 	write_astModule(ingredientsModuleNumbaUnified, numbaFlow.pathFilenameDispatcher, numbaFlow.packageIdentifier)
 
+def getIt(astCallConcurrencyResult: list[ast.Call]) -> Callable[[ast.AST], ast.AST]:
+	def workhorse(node: ast.AST) -> ast.AST:
+		NodeTourist(be.Call, Then.appendTo(astCallConcurrencyResult)).visit(node)
+		return node
+	return workhorse
+
 if __name__ == '__main__':
 	makeNumbaFlow(theNumbaFlow)