mapFolding 0.8.2__py3-none-any.whl → 0.8.4__py3-none-any.whl

mapFolding/someAssemblyRequired/synthesizeNumbaFlow.py

@@ -22,172 +22,135 @@ to generate a fresh optimized implementation.
 """
 
 from mapFolding.someAssemblyRequired import (
-	extractFunctionDef,
+	be,
 	ifThis,
-	IngredientsFunction,
+	Make,
+	NodeChanger,
+	NodeTourist,
+	Then,
+	Z0Z_inlineThisFunctionWithTheseValues,
+	Z0Z_lameFindReplace,
+	Z0Z_makeDictionaryReplacementStatements,
+	又,
+)
+from mapFolding.someAssemblyRequired._toolboxContainers import (
+	astModuleToIngredientsFunction,
 	IngredientsModule,
 	LedgerOfImports,
-	Make,
-	makeDictionaryReplacementStatements,
-	NodeCollector,
-	NodeReplacer,
 	RecipeSynthesizeFlow,
-	Then,
-	write_astModule,
-	Z0Z_replaceMatchingASTnodes,
-	inlineThisFunctionWithTheseValues,
 )
 from mapFolding.someAssemblyRequired.ingredientsNumba import decorateCallableWithNumba
 from mapFolding.someAssemblyRequired.transformDataStructures import shatter_dataclassesDOTdataclass
-from mapFolding.theSSOT import raiseIfNoneGitHubIssueNumber3
+from mapFolding.someAssemblyRequired.transformationTools import write_astModule
 import ast
 
-def makeNumbaFlow(numbaFlow: RecipeSynthesizeFlow = RecipeSynthesizeFlow()) -> None:
-	"""
-	Think about a better organization of this function.
+def makeNumbaFlow(numbaFlow: RecipeSynthesizeFlow) -> None:
+	# 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
 
-	Currently, transform `Callable` in order:
-		sourceDispatcherCallable
-		sourceInitializeCallable
-		sourceParallelCallable
-		sourceSequentialCallable
+	listAllIngredientsFunctions = [
+	(ingredientsInitialize := astModuleToIngredientsFunction(numbaFlow.source_astModule, numbaFlow.sourceCallableInitialize)),
+	(ingredientsParallel := astModuleToIngredientsFunction(numbaFlow.source_astModule, numbaFlow.sourceCallableParallel)),
+	(ingredientsSequential := astModuleToIngredientsFunction(numbaFlow.source_astModule, numbaFlow.sourceCallableSequential)),
+	(ingredientsDispatcher := astModuleToIngredientsFunction(numbaFlow.source_astModule, numbaFlow.sourceCallableDispatcher)),
+	]
+
+	# 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)
+
+	# assignRecipeIdentifiersToCallable. =============================
+	# TODO How can I use `RecipeSynthesizeFlow` as the SSOT for the pairs of items that may need to be replaced?
+	# 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),
+						(numbaFlow.sourceCallableInitialize, numbaFlow.callableInitialize),
+						(numbaFlow.sourceCallableParallel, numbaFlow.callableParallel),
+						(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.visit(ingredients.astFunctionDef)
+
+	ingredientsDispatcher.astFunctionDef.name = numbaFlow.callableDispatcher
+	ingredientsInitialize.astFunctionDef.name = numbaFlow.callableInitialize
+	ingredientsParallel.astFunctionDef.name = numbaFlow.callableParallel
+	ingredientsSequential.astFunctionDef.name = numbaFlow.callableSequential
+
+	# Assign identifiers per the recipe. ==============================
+	listFindReplace = [(numbaFlow.sourceDataclassInstance, numbaFlow.dataclassInstance),
+		(numbaFlow.sourceDataclassInstanceTaskDistribution, numbaFlow.dataclassInstanceTaskDistribution),
+		(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.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))))
+	updateConcurrencyManager.visit(ingredientsDispatcher.astFunctionDef)
+
+	# shatter Dataclass =======================================================
+	instance_Identifier = numbaFlow.dataclassInstance
+	getTheOtherRecord_damn = numbaFlow.dataclassInstanceTaskDistribution
+	shatteredDataclass = shatter_dataclassesDOTdataclass(numbaFlow.logicalPathModuleDataclass, numbaFlow.sourceDataclassIdentifier, instance_Identifier)
+	ingredientsDispatcher.imports.update(shatteredDataclass.ledger)
+
+	# 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)))
+
+	unpack4sequentialCallable = NodeChanger(ifThis.isAssignAndValueIsCall_Identifier(numbaFlow.callableSequential), Then.insertThisAbove(shatteredDataclass.listUnpack))
+	repack4sequentialCallable = NodeChanger(ifThis.isAssignAndValueIsCall_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)
+
+	# parallelCallable =========================================================
+	ingredientsParallel.astFunctionDef.args = Make.argumentsSpecification(args=shatteredDataclass.list_argAnnotated4ArgumentsSpecification)
+	replaceCall2concurrencyManager = NodeChanger(ifThis.isCallAttributeNamespace_Identifier(numbaFlow.concurrencyManagerNamespace, numbaFlow.concurrencyManagerIdentifier), Then.replaceWith(Make.Call(Make.Attribute(Make.Name(numbaFlow.concurrencyManagerNamespace), numbaFlow.concurrencyManagerIdentifier), listArguments=[Make.Name(numbaFlow.callableParallel)] + shatteredDataclass.listName4Parameters)))
+
+	# 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.visit(ingredientsDispatcher.astFunctionDef)
+	replaceAssignParallelCallable = NodeChanger(ifThis.isAssignAndTargets0Is(ifThis.isSubscript_Identifier(getTheOtherRecord_damn)), Then.DOTvalue(Then.replaceWith(astCallConcurrencyResult[0])))
+	replaceAssignParallelCallable.visit(ingredientsDispatcher.astFunctionDef)
+	changeReturnParallelCallable = NodeChanger(be.Return, Then.replaceWith(Make.Return(shatteredDataclass.countingVariableName)))
+	ingredientsParallel.astFunctionDef.returns = shatteredDataclass.countingVariableAnnotation
 
-	But, it should be organized around each transformation. So, when the parameters of `sourceSequentialCallable`
-	are transformed, for example, the statement in `sourceDispatcherCallable` that calls `sourceSequentialCallable` should be
-	transformed at the same time: literally in the same function-or-NodeReplacer-or-subroutine. That would help
-	avoid bugs.
+	unpack4parallelCallable = NodeChanger(ifThis.isAssignAndValueIsCallAttributeNamespace_Identifier(numbaFlow.concurrencyManagerNamespace, numbaFlow.concurrencyManagerIdentifier), Then.insertThisAbove(shatteredDataclass.listUnpack))
 
-	Furthermore, if the above example transformation requires unpacking the dataclass, for example, then the unpacking
-	would be automatically triggered. I have no idea how that would happen, but the transformations are highly predictable,
-	so using a programming language to construct if-this-then-that cascades shouldn't be a problem, you know?
+	unpack4parallelCallable.visit(ingredientsDispatcher.astFunctionDef)
+	replaceCall2concurrencyManager.visit(ingredientsDispatcher.astFunctionDef)
+	changeReturnParallelCallable.visit(ingredientsParallel.astFunctionDef)
 
-	# TODO a tool to automatically remove unused variables from the ArgumentsSpecification (return, and returns) _might_ be nice.
-	"""
-	dictionaryReplacementStatements = makeDictionaryReplacementStatements(numbaFlow.source_astModule)
-	# TODO remember that `sequentialCallable` and `sourceSequentialCallable` are two different values.
-	# Figure out dynamic flow control to synthesized modules https://github.com/hunterhogan/mapFolding/issues/4
+	ingredientsParallel.astFunctionDef = Z0Z_lameFindReplace(ingredientsParallel.astFunctionDef, shatteredDataclass.map_stateDOTfield2Name)
 
-	# ===========================================================
-	sourcePython = numbaFlow.sourceDispatcherCallable
-	astFunctionDef = extractFunctionDef(sourcePython, numbaFlow.source_astModule)
-	if not astFunctionDef: raise raiseIfNoneGitHubIssueNumber3
-	ingredientsDispatcher = IngredientsFunction(astFunctionDef, LedgerOfImports(numbaFlow.source_astModule))
-
-	# sourceParallelCallable
-	shatteredDataclass = shatter_dataclassesDOTdataclass(numbaFlow.logicalPathModuleDataclass, numbaFlow.sourceDataclassIdentifier, numbaFlow.sourceDataclassInstanceTaskDistribution)
-	ingredientsDispatcher.imports.update(shatteredDataclass.ledgerDataclassANDFragments)
-
-	NodeReplacer(
-		findThis = ifThis.isAssignAndValueIsCallNamespace_Identifier(numbaFlow.sourceConcurrencyManagerNamespace, numbaFlow.sourceConcurrencyManagerIdentifier)
-		, doThat = Then.insertThisAbove(shatteredDataclass.listAnnAssign4DataclassUnpack)
-			).visit(ingredientsDispatcher.astFunctionDef)
-	NodeReplacer(
-		findThis = ifThis.isCallNamespace_Identifier(numbaFlow.sourceConcurrencyManagerNamespace, numbaFlow.sourceConcurrencyManagerIdentifier)
-		, doThat = Then.replaceWith(Make.astCall(Make.astAttribute(Make.astName(numbaFlow.sourceConcurrencyManagerNamespace), numbaFlow.sourceConcurrencyManagerIdentifier)
-									, listArguments=[Make.astName(numbaFlow.parallelCallable)] + shatteredDataclass.listNameDataclassFragments4Parameters))
-			).visit(ingredientsDispatcher.astFunctionDef)
-
-	CapturedAssign: list[ast.AST] = []
-	CapturedCall: list[ast.Call] = []
-	findThis = ifThis.isCall
-	doThat = [Then.appendTo(CapturedCall)]
-	capture = NodeCollector(findThis, doThat)
-
-	NodeCollector(
-		findThis = ifThis.isAssignAndTargets0Is(ifThis.isSubscript_Identifier(numbaFlow.sourceDataclassInstance))
-		, doThat = [Then.appendTo(CapturedAssign)
-					, lambda node: capture.visit(node)]
-			).visit(ingredientsDispatcher.astFunctionDef)
-
-	newAssign = CapturedAssign[0]
-	NodeReplacer(
-		findThis = lambda node: ifThis.isSubscript(node) and ifThis.isAttribute(node.value) and ifThis.isCall(node.value.value)
-		, doThat = Then.replaceWith(CapturedCall[0])
-			).visit(newAssign)
-
-	NodeReplacer(
-		findThis = ifThis.isAssignAndTargets0Is(ifThis.isSubscript_Identifier(numbaFlow.sourceDataclassInstance))
-		, doThat = Then.replaceWith(newAssign)
-			).visit(ingredientsDispatcher.astFunctionDef)
-
-	# sourceSequentialCallable
-	shatteredDataclass = shatter_dataclassesDOTdataclass(numbaFlow.logicalPathModuleDataclass, numbaFlow.sourceDataclassIdentifier, numbaFlow.sourceDataclassInstance)
-
-	ingredientsDispatcher.imports.update(shatteredDataclass.ledgerDataclassANDFragments)
-
-	NodeReplacer(
-		findThis = ifThis.isAssignAndValueIsCall_Identifier(numbaFlow.sourceSequentialCallable)
-		, doThat = Then.insertThisAbove(shatteredDataclass.listAnnAssign4DataclassUnpack)
-			).visit(ingredientsDispatcher.astFunctionDef)
-	NodeReplacer(
-		findThis = ifThis.isAssignAndValueIsCall_Identifier(numbaFlow.sourceSequentialCallable)
-		, doThat = Then.insertThisBelow([shatteredDataclass.astAssignDataclassRepack])
-			).visit(ingredientsDispatcher.astFunctionDef)
-	NodeReplacer(
-		findThis = ifThis.isAssignAndValueIsCall_Identifier(numbaFlow.sourceSequentialCallable)
-		, doThat = Then.replaceWith(Make.astAssign(listTargets=[shatteredDataclass.astTuple4AssignTargetsToFragments], value=Make.astCall(Make.astName(numbaFlow.sequentialCallable), shatteredDataclass.listNameDataclassFragments4Parameters)))
-			).visit(ingredientsDispatcher.astFunctionDef)
-
-	ingredientsDispatcher.astFunctionDef.name = numbaFlow.dispatcherCallable
-
-	# ===========================================================
-	sourcePython = numbaFlow.sourceInitializeCallable
-	astFunctionDef = extractFunctionDef(sourcePython, numbaFlow.source_astModule)
-	if not astFunctionDef: raise raiseIfNoneGitHubIssueNumber3
-	astFunctionDef = inlineThisFunctionWithTheseValues(astFunctionDef, dictionaryReplacementStatements)
-	ingredientsInitialize = IngredientsFunction(astFunctionDef, LedgerOfImports(numbaFlow.source_astModule))
-
-	# ===========================================================
-	sourcePython = numbaFlow.sourceParallelCallable
-	astFunctionDef = extractFunctionDef(sourcePython, numbaFlow.source_astModule)
-	if not astFunctionDef: raise raiseIfNoneGitHubIssueNumber3
-	astFunctionDef = inlineThisFunctionWithTheseValues(astFunctionDef, dictionaryReplacementStatements)
-	ingredientsParallel = IngredientsFunction(astFunctionDef, LedgerOfImports(numbaFlow.source_astModule))
-	ingredientsParallel.astFunctionDef.name = numbaFlow.parallelCallable
-	ingredientsParallel.astFunctionDef.args = Make.astArgumentsSpecification(args=shatteredDataclass.list_ast_argAnnotated4ArgumentsSpecification)
-	NodeReplacer(
-		findThis = ifThis.isReturn
-		, doThat = Then.replaceWith(Make.astReturn(shatteredDataclass.astTuple4AssignTargetsToFragments))
-			).visit(ingredientsParallel.astFunctionDef)
-
-	NodeReplacer(
-		findThis = ifThis.isReturn
-		, doThat = Then.replaceWith(Make.astReturn(shatteredDataclass.countingVariableName))
-			).visit(ingredientsParallel.astFunctionDef)
-	ingredientsParallel.astFunctionDef.returns = shatteredDataclass.countingVariableAnnotation
-	replacementMap = {statement.value: statement.target for statement in shatteredDataclass.listAnnAssign4DataclassUnpack}
-	ingredientsParallel.astFunctionDef = Z0Z_replaceMatchingASTnodes(ingredientsParallel.astFunctionDef, replacementMap) # type: ignore
+	# numba decorators =========================================
 	ingredientsParallel = decorateCallableWithNumba(ingredientsParallel)
-
-	# ===========================================================
-	sourcePython = numbaFlow.sourceSequentialCallable
-	astFunctionDef = extractFunctionDef(sourcePython, numbaFlow.source_astModule)
-	if not astFunctionDef: raise raiseIfNoneGitHubIssueNumber3
-	astFunctionDef = inlineThisFunctionWithTheseValues(astFunctionDef, dictionaryReplacementStatements)
-	ingredientsSequential = IngredientsFunction(astFunctionDef, LedgerOfImports(numbaFlow.source_astModule))
-	ingredientsSequential.astFunctionDef.name = numbaFlow.sequentialCallable
-	ingredientsSequential.astFunctionDef.args = Make.astArgumentsSpecification(args=shatteredDataclass.list_ast_argAnnotated4ArgumentsSpecification)
-	NodeReplacer(
-		findThis = ifThis.isReturn
-		, doThat = Then.replaceWith(Make.astReturn(shatteredDataclass.astTuple4AssignTargetsToFragments))
-			).visit(ingredientsSequential.astFunctionDef)
-	NodeReplacer(
-		findThis = ifThis.isReturn
-		, doThat = Then.replaceWith(Make.astReturn(shatteredDataclass.astTuple4AssignTargetsToFragments))
-			).visit(ingredientsSequential.astFunctionDef)
-	ingredientsSequential.astFunctionDef.returns = shatteredDataclass.astSubscriptPrimitiveTupleAnnotations4FunctionDef_returns
-	replacementMap = {statement.value: statement.target for statement in shatteredDataclass.listAnnAssign4DataclassUnpack}
-	ingredientsSequential.astFunctionDef = Z0Z_replaceMatchingASTnodes(ingredientsSequential.astFunctionDef, replacementMap) # type: ignore
 	ingredientsSequential = decorateCallableWithNumba(ingredientsSequential)
 
-	# ===========================================================
-	ingredientsModuleNumbaUnified = IngredientsModule(
-		ingredientsFunction=[ingredientsInitialize,
-							ingredientsParallel,
-							ingredientsSequential,
-							ingredientsDispatcher], imports=LedgerOfImports(numbaFlow.source_astModule))
+	# Module-level transformations ===========================================================
+	ingredientsModuleNumbaUnified = IngredientsModule(ingredientsFunction=listAllIngredientsFunctions, imports=LedgerOfImports(numbaFlow.source_astModule))
 
-	write_astModule(ingredientsModuleNumbaUnified, numbaFlow.pathFilenameDispatcher, numbaFlow.packageName)
+	write_astModule(ingredientsModuleNumbaUnified, numbaFlow.pathFilenameDispatcher, numbaFlow.packageIdentifier)
 
+theNumbaFlow: RecipeSynthesizeFlow = RecipeSynthesizeFlow()
 if __name__ == '__main__':
-	makeNumbaFlow()
+	makeNumbaFlow(theNumbaFlow)

mapFolding/someAssemblyRequired/synthesizeNumbaJob.py

@@ -0,0 +1,247 @@
+"""Synthesize one file to compute `foldsTotal` of `mapShape`."""
+from mapFolding.someAssemblyRequired import ast_Identifier, be, ifThis, Make, NodeChanger, NodeTourist, parsePathFilename2astModule, str_nameDOTname, Then, write_astModule, 又
+from mapFolding.someAssemblyRequired.ingredientsNumba import decorateCallableWithNumba, ParametersNumba, parametersNumbaDefault
+from mapFolding.someAssemblyRequired.synthesizeNumbaFlow import theNumbaFlow
+from mapFolding.someAssemblyRequired.transformDataStructures import makeInitializedComputationState, shatter_dataclassesDOTdataclass, ShatteredDataclass
+from mapFolding.someAssemblyRequired._toolboxContainers import astModuleToIngredientsFunction, IngredientsFunction, IngredientsModule, LedgerOfImports
+from mapFolding.filesystem import getFilenameFoldsTotal, getPathFilenameFoldsTotal, getPathRootJobDEFAULT
+from mapFolding.theSSOT import ComputationState, The
+from pathlib import Path, PurePosixPath
+from typing import cast
+from Z0Z_tools import autoDecodingRLE
+import ast
+import dataclasses
+
+list_IdentifiersNotUsedAllHARDCODED = ['concurrencyLimit', 'foldsTotal', 'mapShape',]
+list_IdentifiersNotUsedParallelSequentialHARDCODED = ['indexLeaf']
+list_IdentifiersNotUsedSequentialHARDCODED = ['foldGroups', 'taskDivisions', 'taskIndex',]
+
+list_IdentifiersReplacedHARDCODED = ['groupsOfFolds',]
+
+list_IdentifiersStaticValuesHARDCODED = ['dimensionsTotal', 'leavesTotal',]
+
+list_IdentifiersNotUsedHARDCODED = list_IdentifiersStaticValuesHARDCODED + list_IdentifiersReplacedHARDCODED + list_IdentifiersNotUsedAllHARDCODED + list_IdentifiersNotUsedParallelSequentialHARDCODED + list_IdentifiersNotUsedSequentialHARDCODED
+
+@dataclasses.dataclass
+class Z0Z_RecipeJob:
+	state: ComputationState
+	# TODO create function to calculate `foldsTotalEstimated`
+	foldsTotalEstimated: int = 0
+	useNumbaProgressBar: bool = True
+	numbaProgressBarIdentifier: ast_Identifier = 'ProgressBarGroupsOfFolds'
+	shatteredDataclass: ShatteredDataclass = dataclasses.field(default=None, init=True) # type: ignore[assignment, reportAssignmentType]
+
+	# ========================================
+	# Source
+	source_astModule = parsePathFilename2astModule(theNumbaFlow.pathFilenameSequential)
+	sourceCountCallable: ast_Identifier = theNumbaFlow.callableSequential
+
+	sourceLogicalPathModuleDataclass: str_nameDOTname = theNumbaFlow.logicalPathModuleDataclass
+	sourceDataclassIdentifier: ast_Identifier = theNumbaFlow.dataclassIdentifier
+	sourceDataclassInstance: ast_Identifier = theNumbaFlow.dataclassInstance
+
+	sourcePathPackage: PurePosixPath | None = theNumbaFlow.pathPackage
+	sourcePackageIdentifier: ast_Identifier | None = theNumbaFlow.packageIdentifier
+
+	# ========================================
+	# Filesystem (names of physical objects)
+	pathPackage: PurePosixPath | None = None
+	pathModule: PurePosixPath | None = PurePosixPath(getPathRootJobDEFAULT())
+	""" `pathModule` will override `pathPackage` and `logicalPathRoot`."""
+	fileExtension: str = theNumbaFlow.fileExtension
+	pathFilenameFoldsTotal: PurePosixPath = dataclasses.field(default=None, init=True) # type: ignore[assignment, 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]
+	countCallable: ast_Identifier = sourceCountCallable
+	dataclassIdentifier: ast_Identifier | None = sourceDataclassIdentifier
+	dataclassInstance: ast_Identifier | None = sourceDataclassInstance
+	logicalPathModuleDataclass: str_nameDOTname | None = sourceLogicalPathModuleDataclass
+
+	def _makePathFilename(self,
+			pathRoot: PurePosixPath | None = None,
+			logicalPathINFIX: str_nameDOTname | None = None,
+			filenameStem: str | None = None,
+			fileExtension: str | None = None,
+			) -> PurePosixPath:
+		if pathRoot is None:
+			pathRoot = self.pathPackage or PurePosixPath(Path.cwd())
+		if logicalPathINFIX:
+			whyIsThisStillAThing: list[str] = logicalPathINFIX.split('.')
+			pathRoot = pathRoot.joinpath(*whyIsThisStillAThing)
+		if filenameStem is None:
+			filenameStem = self.moduleIdentifier
+		if fileExtension is None:
+			fileExtension = self.fileExtension
+		filename: str = filenameStem + fileExtension
+		return pathRoot.joinpath(filename)
+
+	@property
+	def pathFilenameModule(self) -> PurePosixPath:
+		if self.pathModule is None:
+			return self._makePathFilename()
+		else:
+			return self._makePathFilename(pathRoot=self.pathModule, logicalPathINFIX=None)
+
+	def __post_init__(self):
+		pathFilenameFoldsTotal = PurePosixPath(getPathFilenameFoldsTotal(self.state.mapShape))
+
+		if self.moduleIdentifier is None:
+			self.moduleIdentifier = pathFilenameFoldsTotal.stem
+
+		if self.pathFilenameFoldsTotal is None:
+			self.pathFilenameFoldsTotal = pathFilenameFoldsTotal
+
+		if self.shatteredDataclass is None and self.logicalPathModuleDataclass and self.dataclassIdentifier and self.dataclassInstance:
+			self.shatteredDataclass = shatter_dataclassesDOTdataclass(self.logicalPathModuleDataclass, self.dataclassIdentifier, self.dataclassInstance)
+
+	# ========================================
+	# Fields you probably don't need =================================
+	# Dispatcher =================================
+	sourceDispatcherCallable: ast_Identifier = theNumbaFlow.callableDispatcher
+	dispatcherCallable: ast_Identifier = sourceDispatcherCallable
+	# Parallel counting =================================
+	sourceDataclassInstanceTaskDistribution: ast_Identifier = theNumbaFlow.dataclassInstanceTaskDistribution
+	sourceConcurrencyManagerNamespace: ast_Identifier = theNumbaFlow.concurrencyManagerNamespace
+	sourceConcurrencyManagerIdentifier: ast_Identifier = theNumbaFlow.concurrencyManagerIdentifier
+	dataclassInstanceTaskDistribution: ast_Identifier = sourceDataclassInstanceTaskDistribution
+	concurrencyManagerNamespace: ast_Identifier = sourceConcurrencyManagerNamespace
+	concurrencyManagerIdentifier: ast_Identifier = sourceConcurrencyManagerIdentifier
+
+def addLauncherNumbaProgress(ingredientsModule: IngredientsModule, ingredientsFunction: IngredientsFunction, job: Z0Z_RecipeJob) -> IngredientsModule:
+
+	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)
+		writeStream = open('{job.pathFilenameFoldsTotal.as_posix()}', 'w')
+		writeStream.write(str(foldsTotal))
+		writeStream.close()
+"""
+	numba_progressPythonClass: ast_Identifier = 'ProgressBar'
+	numba_progressNumbaType: ast_Identifier = 'ProgressBarType'
+	ingredientsModule.imports.addImportFrom_asStr('numba_progress', numba_progressPythonClass)
+	ingredientsModule.imports.addImportFrom_asStr('numba_progress', numba_progressNumbaType)
+
+	ast_argNumbaProgress = ast.arg(arg=job.numbaProgressBarIdentifier, annotation=ast.Name(id=numba_progressPythonClass, ctx=ast.Load()))
+	ingredientsFunction.astFunctionDef.args.args.append(ast_argNumbaProgress)
+
+	findThis = ifThis.isAugAssign_targetIs(ifThis.isName_Identifier(job.shatteredDataclass.countingVariableName.id))
+	doThat = Then.replaceWith(Make.Expr(Make.Call(Make.Attribute(Make.Name(job.numbaProgressBarIdentifier),'update'),[Make.Constant(1)])))
+	countWithProgressBar = NodeChanger(findThis, doThat)
+	countWithProgressBar.visit(ingredientsFunction.astFunctionDef)
+
+	ingredientsModule.appendLauncher(ast.parse(linesLaunch))
+
+	return ingredientsModule
+
+def move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsFunction: IngredientsFunction, job: Z0Z_RecipeJob) -> IngredientsFunction:
+	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:
+		if ast_arg.arg in job.shatteredDataclass.field2AnnAssign:
+			if ast_arg.arg in list_IdentifiersNotUsed:
+				pass
+			else:
+				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
+					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
+					case _:
+						list_exprDOTannotation: list[ast.expr] = []
+						list_exprDOTvalue: list[ast.expr] = []
+						for dimension in job.state.mapShape:
+							list_exprDOTannotation.append(Make.Name(elementConstructor))
+							list_exprDOTvalue.append(Make.Call(Make.Name(elementConstructor), [Make.Constant(dimension)]))
+						ImaAnnAssign.annotation.slice.elts = list_exprDOTannotation # type: ignore
+						ImaAnnAssign.value.elts = list_exprDOTvalue # type: ignore
+
+				ingredientsFunction.astFunctionDef.body.insert(0, ImaAnnAssign)
+
+			findThis = ifThis.is_arg_Identifier(ast_arg.arg)
+			remove_arg = NodeChanger(findThis, Then.removeIt)
+			remove_arg.visit(ingredientsFunction.astFunctionDef)
+
+	ast.fix_missing_locations(ingredientsFunction.astFunctionDef)
+	return ingredientsFunction
+
+def makeJobNumba(job: Z0Z_RecipeJob, parametersNumba: ParametersNumba = parametersNumbaDefault):
+		# get the raw ingredients: data and the algorithm
+	ingredientsCount: IngredientsFunction = astModuleToIngredientsFunction(job.source_astModule, job.countCallable)
+
+	# Change the return so you can dynamically determine which variables are not used
+	removeReturnStatement = NodeChanger(be.Return, Then.removeIt)
+	removeReturnStatement.visit(ingredientsCount.astFunctionDef)
+	ingredientsCount.astFunctionDef.returns = Make.Constant(value=None)
+
+	# Remove `foldGroups` and any other unused statements, so you can dynamically determine which variables are not used
+	findThis = ifThis.isAssignAndTargets0Is(ifThis.isSubscript_Identifier('foldGroups'))
+	doThat = Then.removeIt
+	remove_foldGroups = NodeChanger(findThis, doThat)
+	remove_foldGroups.visit(ingredientsCount.astFunctionDef)
+
+	# replace identifiers with static values with their values, so you can dynamically determine which variables are not used
+	list_IdentifiersStaticValues = list_IdentifiersStaticValuesHARDCODED
+	for identifier in list_IdentifiersStaticValues:
+		findThis = ifThis.isName_Identifier(identifier)
+		doThat = Then.replaceWith(Make.Constant(int(job.state.__dict__[identifier])))
+		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()
+	ingredientsModule = addLauncherNumbaProgress(ingredientsModule, ingredientsCount, job)
+	parametersNumba['nogil'] = True
+
+	ingredientsCount = move_arg2FunctionDefDOTbodyAndAssignInitialValues(ingredientsCount, job)
+
+	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, parametersNumba)
+
+	ingredientsModule.appendIngredientsFunction(ingredientsCount)
+
+		# add imports, make str, remove unused imports
+		# put on disk
+	write_astModule(ingredientsModule, job.pathFilenameModule, job.packageIdentifier)
+
+	"""
+	Overview
+	- the code starts life in theDao.py, which has many optimizations;
+		- `makeNumbaOptimizedFlow` increase optimization especially by using numba;
+		- `makeJobNumba` increases optimization especially by limiting its capabilities to just one set of parameters
+	- the synthesized module must run well as a standalone interpreted-Python script
+	- the next major optimization step will (probably) be to use the module synthesized by `makeJobNumba` to compile a standalone executable
+	- Nevertheless, at each major optimization step, the code is constantly being improved and optimized, so everything must be well organized (read: semantic) and able to handle a range of arbitrary upstream and not disrupt downstream transformations
+
+	Necessary
+	- Move the function's parameters to the function body,
+	- initialize identifiers with their state types and values,
+
+	Optimizations
+	- replace static-valued identifiers with their values
+	- narrowly focused imports
+
+	Minutia
+	- do not use `with` statement inside numba jitted code, except to use numba's obj mode
+	"""
+
+if __name__ == '__main__':
+	mapShape = (6,6)
+	state = makeInitializedComputationState(mapShape)
+	aJob = Z0Z_RecipeJob(state)
+	makeJobNumba(aJob)