mapFolding 0.3.12__py3-none-any.whl → 0.4.1__py3-none-any.whl

mapFolding/someAssemblyRequired/synthesizeNumbaGeneralized.py

@@ -0,0 +1,325 @@
+from mapFolding import (
+	computationState,
+	EnumIndices,
+	formatModuleNameDEFAULT,
+	FREAKOUT,
+	getAlgorithmDispatcher,
+	getAlgorithmSource,
+	getFilenameFoldsTotal,
+	getPathFilenameFoldsTotal,
+	getPathJobRootDEFAULT,
+	getPathPackage,
+	getPathSyntheticModules,
+	hackSSOTdatatype,
+	indexMy,
+	indexTrack,
+	moduleOfSyntheticModules,
+	myPackageNameIs,
+	ParametersNumba,
+	parametersNumbaDEFAULT,
+	parametersNumbaFailEarly,
+	parametersNumbaMinimum,
+	parametersNumbaSuperJit,
+	parametersNumbaSuperJitParallel,
+	setDatatypeElephino,
+	setDatatypeFoldsTotal,
+	setDatatypeLeavesTotal,
+	setDatatypeModule,
+	Z0Z_getDatatypeModuleScalar,
+	Z0Z_getDecoratorCallable,
+	Z0Z_identifierCountFolds,
+	Z0Z_setDatatypeModuleScalar,
+	Z0Z_setDecoratorCallable,
+)
+from mapFolding.someAssemblyRequired.makeJob import makeStateJob
+from numpy import integer
+from numpy.typing import NDArray
+from types import ModuleType
+from typing import Any, Callable, cast, Dict, List, Optional, Sequence, Set, Tuple, Type, Union
+from Z0Z_tools import autoDecodingRLE
+import ast
+import autoflake
+import collections
+import copy
+import importlib.util
+import inspect
+import more_itertools
+import numba
+import numpy
+import os
+import pathlib
+import python_minifier
+
+youOughtaKnow = collections.namedtuple('youOughtaKnow', ['callableSynthesized', 'pathFilenameForMe', 'astForCompetentProgrammers'])
+
+# Generic
+class ifThis:
+	"""Generic AST node predicate builder."""
+	@staticmethod
+	def nameIs(allegedly: str) -> Callable[[ast.AST], bool]:
+		return lambda node: (isinstance(node, ast.Name) and node.id == allegedly)
+
+	@staticmethod
+	def isCallWithAttribute(moduleName: str, callableName: str) -> Callable[[ast.AST], bool]:
+		return lambda node: (isinstance(node, ast.Call)
+							and isinstance(node.func, ast.Attribute)
+							and isinstance(node.func.value, ast.Name)
+							and node.func.value.id == moduleName
+							and node.func.attr == callableName)
+
+	@staticmethod
+	def isCallWithName(callableName: str) -> Callable[[ast.AST], bool]:
+		return lambda node: (isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == callableName)
+
+	@staticmethod
+	def anyOf(*predicates: Callable[[ast.AST], bool]) -> Callable[[ast.AST], bool]:
+		return lambda node: any(pred(node) for pred in predicates)
+
+class Then:
+	"""Generic actions."""
+	@staticmethod
+	def copy_astCallKeywords(astCall: ast.Call) -> Dict[str, Any]:
+		"""Extract keyword parameters from a decorator AST node."""
+		dictionaryKeywords: Dict[str, Any] = {}
+		for keywordItem in astCall.keywords:
+			if isinstance(keywordItem.value, ast.Constant) and keywordItem.arg is not None:
+				dictionaryKeywords[keywordItem.arg] = keywordItem.value.value
+		return dictionaryKeywords
+
+	@staticmethod
+	def make_astCall(name: str, args: Optional[Sequence[ast.expr]]=None, list_astKeywords: Optional[Sequence[ast.keyword]]=None, dictionaryKeywords: Optional[Dict[str, Any]]=None) -> ast.Call:
+		list_dictionaryKeywords = [ast.keyword(arg=keyName, value=ast.Constant(value=keyValue)) for keyName, keyValue in dictionaryKeywords.items()] if dictionaryKeywords else []
+		return ast.Call(
+			func=ast.Name(id=name, ctx=ast.Load()),
+			args=list(args) if args else [],
+			keywords=list_dictionaryKeywords + list(list_astKeywords) if list_astKeywords else [],
+		)
+
+class NodeReplacer(ast.NodeTransformer):
+	"""
+	A node transformer that replaces or removes AST nodes based on a condition.
+	This transformer traverses an AST and for each node checks a predicate. If the predicate
+	returns True, the transformer uses the replacement builder to obtain a new node. Returning
+	None from the replacement builder indicates that the node should be removed.
+
+	Attributes:
+		findMe (Callable[[ast.AST], bool]): A function that determines whether a node should be replaced.
+		nodeReplacementBuilder (Callable[[ast.AST], Optional[ast.AST]]): A function that returns a new node
+			or None to remove the node.
+
+	Methods:
+		visit(node: ast.AST) -> Optional[ast.AST]:
+			Visits each node in the AST, replacing or removing it based on the predicate.
+	"""
+	def __init__(self, findMe: Callable[[ast.AST], bool], nodeReplacementBuilder: Callable[[ast.AST], Optional[ast.AST]]) -> None:
+		self.findMe = findMe
+		self.nodeReplacementBuilder = nodeReplacementBuilder
+
+	def visit(self, node: ast.AST) -> ast.AST | None | Any:
+		if self.findMe(node):
+			return self.nodeReplacementBuilder(node)
+		return super().visit(node)
+
+# Confusing: suspiciously specific but still reusable
+def thisIsNumbaDotJit(Ima: ast.AST) -> bool:
+	return ifThis.isCallWithAttribute(Z0Z_getDatatypeModuleScalar(), Z0Z_getDecoratorCallable())(Ima)
+
+def thisIsJit(Ima: ast.AST) -> bool:
+	return ifThis.isCallWithName(Z0Z_getDecoratorCallable())(Ima)
+
+def thisIsAnyNumbaJitDecorator(Ima: ast.AST) -> bool:
+	return thisIsNumbaDotJit(Ima) or thisIsJit(Ima)
+
+# Domain-based
+class UniversalImportTracker:
+	def __init__(self) -> None:
+		self.dictionaryImportFrom: Dict[str, Set] = collections.defaultdict(set)
+		self.setImport = set()
+
+	def addAst(self, astImport_: Union[ast.Import, ast.ImportFrom]) -> None:
+		if isinstance(astImport_, ast.Import):
+			for alias in astImport_.names:
+				self.setImport.add(alias.name)
+		elif isinstance(astImport_, ast.ImportFrom):
+			if astImport_.module is not None:
+				self.dictionaryImportFrom[astImport_.module].update(alias.name for alias in astImport_.names)
+
+	def addImportFromStr(self, module: str, name: str) -> None:
+		self.dictionaryImportFrom[module].add(name)
+
+	def addImportStr(self, name: str) -> None:
+		self.setImport.add(name)
+
+	def makeListAst(self) -> List[Union[ast.ImportFrom, ast.Import]]:
+		listAstImportFrom = [ast.ImportFrom(module=module, names=[ast.alias(name=name, asname=None)], level=0) for module, names in self.dictionaryImportFrom.items() for name in names]
+		listAstImport = [ast.Import(names=[ast.alias(name=name, asname=None)]) for name in self.setImport]
+		return listAstImportFrom + listAstImport
+
+# Intricate and specialized
+class RecursiveInliner(ast.NodeTransformer):
+	"""
+	Class RecursiveInliner:
+		A custom AST NodeTransformer designed to recursively inline function calls from a given dictionary
+		of function definitions into the AST. Once a particular function has been inlined, it is marked
+		as completed to avoid repeated inlining. This transformation modifies the AST in-place by substituting
+		eligible function calls with the body of their corresponding function.
+		Attributes:
+			dictionaryFunctions (Dict[str, ast.FunctionDef]):
+				A mapping of function name to its AST definition, used as a source for inlining.
+			callablesCompleted (Set[str]):
+				A set to track function names that have already been inlined to prevent multiple expansions.
+		Methods:
+			inlineFunctionBody(callableTargetName: str) -> Optional[ast.FunctionDef]:
+				Retrieves the AST definition for a given function name from dictionaryFunctions
+				and recursively inlines any function calls within it. Returns the function definition
+				that was inlined or None if the function was already processed.
+			visit_Call(callNode: ast.Call) -> ast.AST:
+				Inspects calls within the AST. If a function call matches one in dictionaryFunctions,
+				it is replaced by the inlined body. If the last statement in the inlined body is a return
+				or an expression, that value or expression is substituted; otherwise, a constant is returned.
+			visit_Expr(node: ast.Expr) -> Union[ast.AST, List[ast.AST]]:
+				Handles expression nodes in the AST. If the expression is a function call from
+				dictionaryFunctions, its statements are expanded in place, effectively inlining
+				the called function's statements into the surrounding context.
+	"""
+	def __init__(self, dictionaryFunctions: Dict[str, ast.FunctionDef]):
+		self.dictionaryFunctions = dictionaryFunctions
+		self.callablesCompleted: Set[str] = set()
+
+	def inlineFunctionBody(self, callableTargetName: str) -> Optional[ast.FunctionDef]:
+		if (callableTargetName in self.callablesCompleted):
+			return None
+
+		self.callablesCompleted.add(callableTargetName)
+		inlineDefinition = self.dictionaryFunctions[callableTargetName]
+		for astNode in ast.walk(inlineDefinition):
+			self.visit(astNode)
+		return inlineDefinition
+
+	def visit_Call(self, node: ast.Call) -> Any | ast.Constant | ast.Call | ast.AST:
+		callNodeVisited = self.generic_visit(node)
+		if (isinstance(callNodeVisited, ast.Call) and isinstance(callNodeVisited.func, ast.Name) and callNodeVisited.func.id in self.dictionaryFunctions):
+			inlineDefinition = self.inlineFunctionBody(callNodeVisited.func.id)
+			if (inlineDefinition and inlineDefinition.body):
+				statementTerminating = inlineDefinition.body[-1]
+				if (isinstance(statementTerminating, ast.Return) and statementTerminating.value is not None):
+					return self.visit(statementTerminating.value)
+				elif (isinstance(statementTerminating, ast.Expr) and statementTerminating.value is not None):
+					return self.visit(statementTerminating.value)
+				return ast.Constant(value=None)
+		return callNodeVisited
+
+	def visit_Expr(self, node: ast.Expr) -> Union[ast.AST, List[ast.AST]]:
+		if (isinstance(node.value, ast.Call)):
+			if (isinstance(node.value.func, ast.Name) and node.value.func.id in self.dictionaryFunctions):
+				inlineDefinition = self.inlineFunctionBody(node.value.func.id)
+				if (inlineDefinition):
+					return [self.visit(stmt) for stmt in inlineDefinition.body]
+		return self.generic_visit(node)
+
+class UnpackArrays(ast.NodeTransformer):
+	"""
+	A class that transforms array accesses using enum indices into local variables.
+
+	This AST transformer identifies array accesses using enum indices and replaces them
+	with local variables, adding initialization statements at the start of functions.
+
+	Parameters:
+		enumIndexClass (Type[EnumIndices]): The enum class used for array indexing
+		arrayName (str): The name of the array being accessed
+
+	Attributes:
+		enumIndexClass (Type[EnumIndices]): Stored enum class for index lookups
+		arrayName (str): Name of the array being transformed
+		substitutions (dict): Tracks variable substitutions and their original nodes
+
+	The transformer handles two main cases:
+	1. Scalar array access - array[EnumIndices.MEMBER]
+	2. Array slice access - array[EnumIndices.MEMBER, other_indices...]
+	For each identified access pattern, it:
+	1. Creates a local variable named after the enum member
+	2. Adds initialization code at function start
+	3. Replaces original array access with the local variable
+	"""
+
+	def __init__(self, enumIndexClass: Type[EnumIndices], arrayName: str) -> None:
+		self.enumIndexClass = enumIndexClass
+		self.arrayName = arrayName
+		self.substitutions: Dict[str, Any] = {}
+
+	def extract_member_name(self, node: ast.AST) -> Optional[str]:
+		"""Recursively extract enum member name from any node in the AST."""
+		if isinstance(node, ast.Attribute) and node.attr == 'value':
+			innerAttribute = node.value
+			while isinstance(innerAttribute, ast.Attribute):
+				if (isinstance(innerAttribute.value, ast.Name) and innerAttribute.value.id == self.enumIndexClass.__name__):
+					return innerAttribute.attr
+				innerAttribute = innerAttribute.value
+		return None
+
+	def transform_slice_element(self, node: ast.AST) -> ast.AST:
+		"""Transform any enum references within a slice element."""
+		if isinstance(node, ast.Subscript):
+			if isinstance(node.slice, ast.Attribute):
+				member_name = self.extract_member_name(node.slice)
+				if member_name:
+					return ast.Name(id=member_name, ctx=node.ctx)
+			elif isinstance(node, ast.Tuple):
+				# Handle tuple slices by transforming each element
+				return ast.Tuple(elts=cast(List[ast.expr], [self.transform_slice_element(elt) for elt in node.elts]), ctx=node.ctx)
+		elif isinstance(node, ast.Attribute):
+			member_name = self.extract_member_name(node)
+			if member_name:
+				return ast.Name(id=member_name, ctx=ast.Load())
+		return node
+
+	def visit_Subscript(self, node: ast.Subscript) -> ast.AST:
+		# Recursively visit any nested subscripts in value or slice
+		node.value = self.visit(node.value)
+		node.slice = self.visit(node.slice)
+		# If node.value is not our arrayName, just return node
+		if not (isinstance(node.value, ast.Name) and node.value.id == self.arrayName):
+			return node
+
+		# Handle scalar array access
+		if isinstance(node.slice, ast.Attribute):
+			memberName = self.extract_member_name(node.slice)
+			if memberName:
+				self.substitutions[memberName] = ('scalar', node)
+				return ast.Name(id=memberName, ctx=ast.Load())
+
+		# Handle array slice access
+		if isinstance(node.slice, ast.Tuple) and node.slice.elts:
+			firstElement = node.slice.elts[0]
+			memberName = self.extract_member_name(firstElement)
+			sliceRemainder = [self.visit(elem) for elem in node.slice.elts[1:]]
+			if memberName:
+				self.substitutions[memberName] = ('array', node)
+				if len(sliceRemainder) == 0:
+					return ast.Name(id=memberName, ctx=ast.Load())
+				return ast.Subscript(value=ast.Name(id=memberName, ctx=ast.Load()), slice=ast.Tuple(elts=sliceRemainder, ctx=ast.Load()) if len(sliceRemainder) > 1 else sliceRemainder[0], ctx=ast.Load())
+
+		# If single-element tuple, unwrap
+		if isinstance(node.slice, ast.Tuple) and len(node.slice.elts) == 1:
+			node.slice = node.slice.elts[0]
+
+		return node
+
+	def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef:
+		node = cast(ast.FunctionDef, self.generic_visit(node))
+
+		initializations = []
+		for name, (kind, original_node) in self.substitutions.items():
+			if kind == 'scalar':
+				initializations.append(ast.Assign(targets=[ast.Name(id=name, ctx=ast.Store())], value=original_node))
+			else:  # array
+				initializations.append(
+					ast.Assign(
+						targets=[ast.Name(id=name, ctx=ast.Store())],
+						value=ast.Subscript(value=ast.Name(id=self.arrayName, ctx=ast.Load()),
+							slice=ast.Attribute(value=ast.Attribute(
+									value=ast.Name(id=self.enumIndexClass.__name__, ctx=ast.Load()),
+									attr=name, ctx=ast.Load()), attr='value', ctx=ast.Load()), ctx=ast.Load())))
+
+		node.body = initializations + node.body
+		return node

mapFolding/someAssemblyRequired/synthesizeNumbaJob.py

@@ -0,0 +1,173 @@
+"""Synthesize one file to compute `foldsTotal` of `mapShape`."""
+from mapFolding.someAssemblyRequired.synthesizeNumba import *
+
+def doUnrollCountGaps(FunctionDefTarget: ast.FunctionDef, stateJob: computationState, allImports: UniversalImportTracker) -> Tuple[ast.FunctionDef, UniversalImportTracker]:
+	"""The initial results were very bad."""
+	FunctionDefTarget = findAndReplaceWhileLoopIn_body(FunctionDefTarget, 'indexDimension', stateJob['my'][indexMy.dimensionsTotal])
+	FunctionDefTarget = removeAssignTargetFrom_body(FunctionDefTarget, 'indexDimension')
+	FunctionDefTarget = removeAssignTargetFrom_body(FunctionDefTarget, 'connectionGraph')
+	FunctionDefTarget, allImports = insertArrayIn_body(FunctionDefTarget, 'connectionGraph', stateJob['connectionGraph'], allImports, stateJob['my'][indexMy.dimensionsTotal])
+	for index in range(stateJob['my'][indexMy.dimensionsTotal]):
+		class ReplaceConnectionGraph(ast.NodeTransformer):
+			def visit_Subscript(self, node: ast.Subscript) -> ast.AST:
+				node = cast(ast.Subscript, self.generic_visit(node))
+				if (isinstance(node.value, ast.Name) and node.value.id == "connectionGraph" and
+					isinstance(node.slice, ast.Tuple) and len(node.slice.elts) >= 1):
+					firstElement = node.slice.elts[0]
+					if isinstance(firstElement, ast.Constant) and firstElement.value == index:
+						newName = ast.Name(id=f"connectionGraph_{index}", ctx=ast.Load())
+						remainingIndices = node.slice.elts[1:]
+						if len(remainingIndices) == 1:
+							newSlice = remainingIndices[0]
+						else:
+							newSlice = ast.Tuple(elts=remainingIndices, ctx=ast.Load())
+						return ast.copy_location(ast.Subscript(value=newName, slice=newSlice, ctx=node.ctx), node)
+				return node
+		transformer = ReplaceConnectionGraph()
+		FunctionDefTarget = transformer.visit(FunctionDefTarget)
+	return FunctionDefTarget, allImports
+
+def writeJobNumba(mapShape: Sequence[int]
+				, algorithmSource: ModuleType
+				, callableTarget: Optional[str] = None
+				, parametersNumba: Optional[ParametersNumba] = None
+				, pathFilenameWriteJob: Optional[Union[str, os.PathLike[str]]] = None
+				, unrollCountGaps: Optional[bool] = False
+				, **keywordArguments: Optional[Any]
+				) -> pathlib.Path:
+	""" Parameters: **keywordArguments: most especially for `computationDivisions` if you want to make a parallel job. Also `CPUlimit`. """
+
+	""" Notes:
+	Hypothetically, everything can now be configured with parameters and functions. And changing how the job is written is relatively easy.
+
+	Overview
+	- the code starts life in theDao.py, which has many optimizations; `makeNumbaOptimizedFlow` increase optimization especially by using numba; `writeJobNumba` 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 `writeJobNumba` 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 and able to handle upstream and downstream changes
+
+	Minutia
+	- perf_counter is for testing. When I run a real job, I delete those lines
+	- avoid `with` statement
+
+	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
+	"""
+
+	# NOTE get the raw ingredients: data and the algorithm
+	stateJob = makeStateJob(mapShape, writeJob=False, **keywordArguments)
+	pythonSource = inspect.getsource(algorithmSource)
+	astModule = ast.parse(pythonSource)
+	setFunctionDef = {statement for statement in astModule.body if isinstance(statement, ast.FunctionDef)}
+	if not callableTarget:
+		if len(setFunctionDef) == 1:
+			FunctionDefTarget = setFunctionDef.pop()
+			callableTarget = FunctionDefTarget.name
+		else:
+			raise ValueError(f"I did not receive a `callableTarget` and {algorithmSource.__name__=} has more than one callable: {setFunctionDef}. Please select one.")
+	else:
+		FunctionDefTarget = setFunctionDef.pop() if callableTarget in {statement.name for statement in setFunctionDef} else None
+	if not FunctionDefTarget: raise ValueError(f"I received `{callableTarget=}` and {algorithmSource.__name__=}, but I could not find that function in that source.")
+
+	# NOTE `allImports` is a complementary container to `FunctionDefTarget`; the `FunctionDefTarget` cannot track its own imports very well.
+	allImports = UniversalImportTracker()
+	for statement in astModule.body:
+		if isinstance(statement, (ast.Import, ast.ImportFrom)):
+			allImports.addAst(statement)
+
+	# NOTE remove the parameters from the function signature
+	for pirateScowl in FunctionDefTarget.args.args.copy():
+		match pirateScowl.arg:
+			case 'my':
+				FunctionDefTarget, allImports = findAndReplaceArraySubscriptIn_body(FunctionDefTarget, pirateScowl.arg, stateJob[pirateScowl.arg], ['taskIndex', 'dimensionsTotal'], allImports)
+			case 'track':
+				FunctionDefTarget, allImports = findAndReplaceArrayIn_body(FunctionDefTarget, pirateScowl.arg, stateJob[pirateScowl.arg], allImports)
+			case 'connectionGraph':
+				FunctionDefTarget, allImports = insertArrayIn_body(FunctionDefTarget, pirateScowl.arg, stateJob[pirateScowl.arg], allImports)
+			case 'gapsWhere':
+				FunctionDefTarget, allImports = insertArrayIn_body(FunctionDefTarget, pirateScowl.arg, stateJob[pirateScowl.arg], allImports)
+			case 'foldGroups':
+				FunctionDefTarget = removeAssignTargetFrom_body(FunctionDefTarget, pirateScowl.arg)
+		FunctionDefTarget.args.args.remove(pirateScowl)
+
+	# NOTE replace identifiers with static values with their values
+	FunctionDefTarget, allImports = findAndReplaceAnnAssignIn_body(FunctionDefTarget, allImports)
+	FunctionDefTarget = findAstNameReplaceWithConstantIn_body(FunctionDefTarget, 'dimensionsTotal', int(stateJob['my'][indexMy.dimensionsTotal]))
+	FunctionDefTarget = findThingyReplaceWithConstantIn_body(FunctionDefTarget, 'foldGroups[-1]', int(stateJob['foldGroups'][-1]))
+
+	# NOTE an attempt at optimization
+	if unrollCountGaps:
+		FunctionDefTarget, allImports = doUnrollCountGaps(FunctionDefTarget, stateJob, allImports)
+
+	# NOTE starting the count and printing the total
+	pathFilenameFoldsTotal = getPathFilenameFoldsTotal(stateJob['mapShape'])
+	astLauncher = makeLauncherBasicJobNumba(FunctionDefTarget.name, pathFilenameFoldsTotal)
+	FunctionDefTarget, allImports = insertReturnStatementIn_body(FunctionDefTarget, stateJob['foldGroups'], allImports)
+
+	# NOTE add the perfect decorator
+	datatype = hackSSOTdatatype(Z0Z_identifierCountFolds)
+	FunctionDefTarget.returns = ast.Name(id=datatype, ctx=ast.Load())
+	FunctionDefTarget, allImports = decorateCallableWithNumba(FunctionDefTarget, allImports, parametersNumba)
+	if thisIsNumbaDotJit(FunctionDefTarget.decorator_list[0]):
+		astCall = cast(ast.Call, FunctionDefTarget.decorator_list[0])
+		astCall.func = ast.Name(id=Z0Z_getDecoratorCallable(), ctx=ast.Load())
+		FunctionDefTarget.decorator_list[0] = astCall
+
+	# NOTE add imports, make str, remove unused imports
+	astImports = allImports.makeListAst()
+	astModule = ast.Module(body=cast(List[ast.stmt], astImports + [FunctionDefTarget] + [astLauncher]), type_ignores=[])
+	ast.fix_missing_locations(astModule)
+	pythonSource = ast.unparse(astModule)
+	pythonSource = autoflake.fix_code(pythonSource, ['mapFolding', 'numba', 'numpy'])
+	pythonSource = python_minifier.minify(pythonSource, remove_annotations = False,
+		remove_pass = False,
+		remove_literal_statements = False,
+		combine_imports = True,
+		hoist_literals = False,
+		rename_locals = False,
+		rename_globals = False,
+		remove_object_base = False,
+		convert_posargs_to_args = False,
+		preserve_shebang = True,
+		remove_asserts = False,
+		remove_debug = False,
+		remove_explicit_return_none = False,
+		remove_builtin_exception_brackets = False,
+		constant_folding = False)
+
+	# NOTE put on disk
+	if pathFilenameWriteJob is None:
+		filename = getFilenameFoldsTotal(stateJob['mapShape'])
+		pathRoot = getPathJobRootDEFAULT()
+		pathFilenameWriteJob = pathlib.Path(pathRoot, pathlib.Path(filename).stem, pathlib.Path(filename).with_suffix('.py'))
+	else:
+		pathFilenameWriteJob = pathlib.Path(pathFilenameWriteJob)
+	pathFilenameWriteJob.parent.mkdir(parents=True, exist_ok=True)
+
+	pathFilenameWriteJob.write_text(pythonSource)
+
+	return pathFilenameWriteJob
+
+if __name__ == '__main__':
+	mapShape = [5,5]
+	from mapFolding.syntheticModules import numba_countSequential
+	algorithmSource: ModuleType = numba_countSequential
+
+	callableTarget = None
+
+	parametersNumba = parametersNumbaDEFAULT
+
+	pathFilenameWriteJob = None
+
+	setDatatypeFoldsTotal('int64', sourGrapes=True)
+	setDatatypeElephino('uint8', sourGrapes=True)
+	setDatatypeLeavesTotal('uint8', sourGrapes=True)
+	Z0Z_setDatatypeModuleScalar('numba')
+	Z0Z_setDecoratorCallable('jit')
+
+	writeJobNumba(mapShape, algorithmSource, callableTarget, parametersNumba, pathFilenameWriteJob)

mapFolding/someAssemblyRequired/synthesizeNumbaModules.py

@@ -0,0 +1,77 @@
+"""I suspect this function will be relatively stable for now.
+Managing settings and options, however, ... I've 'invented'
+everything I am doing. I would rather benefit from humanity's
+collective wisdom."""
+from mapFolding.someAssemblyRequired.synthesizeNumba import *
+
+def makeFlowNumbaOptimized(listCallablesInline: List[str], callableDispatcher: Optional[bool] = False, algorithmSource: Optional[ModuleType] = None, relativePathWrite: Optional[pathlib.Path] = None, formatFilenameWrite: Optional[str] = None) -> List[youOughtaKnow]:
+	if relativePathWrite and relativePathWrite.is_absolute():
+		raise ValueError("The path to write the module must be relative to the root of the package.")
+	if not algorithmSource:
+		algorithmSource = getAlgorithmSource()
+
+	listStuffYouOughtaKnow: List[youOughtaKnow] = []
+
+	def doThisStuff(callableTarget: str, parametersNumba: Optional[ParametersNumba], inlineCallables: bool, unpackArrays: bool, allImports: Optional[UniversalImportTracker], relativePathWrite: Optional[pathlib.Path], formatFilenameWrite: Optional[str]) -> youOughtaKnow:
+		pythonSource = inspect.getsource(algorithmSource)
+		pythonSource = makeAstModuleForOneCallable(pythonSource, callableTarget, parametersNumba, inlineCallables, unpackArrays, allImports)
+		if not pythonSource: raise FREAKOUT
+		pythonSource = autoflake.fix_code(pythonSource, ['mapFolding', 'numba', 'numpy'])
+
+		if not relativePathWrite:
+			pathWrite = getPathSyntheticModules()
+		else:
+			pathWrite = getPathPackage() / relativePathWrite
+		if not formatFilenameWrite:
+			formatFilenameWrite = formatModuleNameDEFAULT + '.py'
+		pathFilename = pathWrite  / formatFilenameWrite.format(callableTarget=callableTarget)
+
+		pathFilename.write_text(pythonSource)
+
+		howIsThisStillAThing = getPathPackage().parent
+		dumbassPythonNamespace = pathFilename.relative_to(howIsThisStillAThing).with_suffix('').parts
+		ImaModule = '.'.join(dumbassPythonNamespace)
+		astImportFrom = ast.ImportFrom(module=ImaModule, names=[ast.alias(name=callableTarget, asname=None)], level=0)
+
+		return youOughtaKnow(callableSynthesized=callableTarget, pathFilenameForMe=pathFilename, astForCompetentProgrammers=astImportFrom)
+
+	for callableTarget in listCallablesInline:
+		parametersNumba = None
+		inlineCallables = True
+		unpackArrays 	= False
+		allImports 		= None
+		match callableTarget:
+			case 'countParallel':
+				parametersNumba = parametersNumbaSuperJitParallel
+			case 'countSequential':
+				parametersNumba = parametersNumbaSuperJit
+				unpackArrays = True
+			case 'countInitialize':
+				parametersNumba = parametersNumbaDEFAULT
+		listStuffYouOughtaKnow.append(doThisStuff(callableTarget, parametersNumba, inlineCallables, unpackArrays, allImports, relativePathWrite, formatFilenameWrite))
+
+	if callableDispatcher:
+		callableTarget 	= getAlgorithmDispatcher().__name__
+		parametersNumba = None
+		inlineCallables	= False
+		unpackArrays	= False
+		allImports 		= UniversalImportTracker()
+		for stuff in listStuffYouOughtaKnow:
+			statement = stuff.astForCompetentProgrammers
+			if isinstance(statement, (ast.Import, ast.ImportFrom)):
+				allImports.addAst(statement)
+
+		listStuffYouOughtaKnow.append(doThisStuff(callableTarget, parametersNumba, inlineCallables, unpackArrays, allImports, relativePathWrite, formatFilenameWrite))
+
+	return listStuffYouOughtaKnow
+
+if __name__ == '__main__':
+	setDatatypeModule('numpy', sourGrapes=True)
+	setDatatypeFoldsTotal('int64', sourGrapes=True)
+	setDatatypeElephino('uint8', sourGrapes=True)
+	setDatatypeLeavesTotal('uint8', sourGrapes=True)
+	Z0Z_setDatatypeModuleScalar('numba')
+	Z0Z_setDecoratorCallable('jit')
+	listCallablesInline: List[str] = ['countInitialize', 'countParallel', 'countSequential']
+	callableDispatcher = True
+	makeFlowNumbaOptimized(listCallablesInline, callableDispatcher)

mapFolding/syntheticModules/numba_countInitialize.py

@@ -1,12 +1,12 @@
-from mapFolding import indexTrack
 from mapFolding import indexMy
-from numba import uint8
+from mapFolding import indexTrack
 from numba import jit
+from numba import uint8
 from numpy import ndarray
-from numpy import dtype
 from numpy import integer
-from typing import Any
+from numpy import dtype
 from typing import Tuple
+from typing import Any
 
 @jit((uint8[:, :, ::1], uint8[::1], uint8[::1], uint8[:, ::1]), _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)
 def countInitialize(connectionGraph: ndarray[Tuple[int, int, int], dtype[integer[Any]]], gapsWhere: ndarray[Tuple[int], dtype[integer[Any]]], my: ndarray[Tuple[int], dtype[integer[Any]]], track: ndarray[Tuple[int, int], dtype[integer[Any]]]) -> None:

mapFolding/syntheticModules/numba_countParallel.py

@@ -1,14 +1,14 @@
-from mapFolding import indexTrack
 from mapFolding import indexMy
-from numba import uint8
+from mapFolding import indexTrack
 from numba import jit
+from numba import uint8
 from numba import int64
 from numba import prange
 from numpy import ndarray
-from numpy import dtype
 from numpy import integer
-from typing import Any
+from numpy import dtype
 from typing import Tuple
+from typing import Any
 
 @jit((uint8[:, :, ::1], int64[::1], uint8[::1], uint8[::1], uint8[:, ::1]), _nrt=True, boundscheck=False, cache=True, error_model='numpy', fastmath=True, forceinline=True, inline='always', looplift=False, no_cfunc_wrapper=True, no_cpython_wrapper=True, nopython=True, parallel=True)
 def countParallel(connectionGraph: ndarray[Tuple[int, int, int], dtype[integer[Any]]], foldGroups: ndarray[Tuple[int], dtype[integer[Any]]], gapsWhere: ndarray[Tuple[int], dtype[integer[Any]]], my: ndarray[Tuple[int], dtype[integer[Any]]], track: ndarray[Tuple[int, int], dtype[integer[Any]]]) -> None:

mapFolding/syntheticModules/numba_countSequential.py

@@ -1,13 +1,13 @@
-from mapFolding import indexTrack
 from mapFolding import indexMy
-from numba import uint8
+from mapFolding import indexTrack
 from numba import jit
+from numba import uint8
 from numba import int64
 from numpy import ndarray
-from numpy import dtype
 from numpy import integer
-from typing import Any
+from numpy import dtype
 from typing import Tuple
+from typing import Any
 
 @jit((uint8[:, :, ::1], int64[::1], uint8[::1], uint8[::1], uint8[:, ::1]), _nrt=True, boundscheck=False, cache=True, error_model='numpy', fastmath=True, forceinline=True, inline='always', looplift=False, no_cfunc_wrapper=True, no_cpython_wrapper=True, nopython=True, parallel=False)
 def countSequential(connectionGraph: ndarray[Tuple[int, int, int], dtype[integer[Any]]], foldGroups: ndarray[Tuple[int], dtype[integer[Any]]], gapsWhere: ndarray[Tuple[int], dtype[integer[Any]]], my: ndarray[Tuple[int], dtype[integer[Any]]], track: ndarray[Tuple[int, int], dtype[integer[Any]]]) -> None:

mapFolding/syntheticModules/numba_doTheNeedful.py

@@ -1,17 +1,17 @@
+from mapFolding.syntheticModules.numba_countInitialize import countInitialize
+from mapFolding.syntheticModules.numba_countParallel import countParallel
+from mapFolding.syntheticModules.numba_countSequential import countSequential
 from mapFolding import indexMy
-from numba import uint8
 from numba import jit
+from numba import uint8
 from numba import int64
 from numpy import ndarray
-from numpy import dtype
 from numpy import integer
-from typing import Any
+from numpy import dtype
 from typing import Tuple
-from mapFolding.syntheticModules.numba_countInitialize import countInitialize
-from mapFolding.syntheticModules.numba_countParallel import countParallel
-from mapFolding.syntheticModules.numba_countSequential import countSequential
+from typing import Any
 
-@jit((uint8[:, :, ::1], int64[::1], uint8[::1], uint8[::1], uint8[::1], uint8[:, ::1]), _nrt=True, boundscheck=True, cache=True, error_model='python', fastmath=False, forceinline=True, inline='always', looplift=False, no_cfunc_wrapper=False, no_cpython_wrapper=False, nopython=True, parallel=False)
+@jit((uint8[:, :, ::1], int64[::1], uint8[::1], uint8[::1], uint8[::1], uint8[:, ::1]), _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)
 def doTheNeedful(connectionGraph: ndarray[Tuple[int, int, int], dtype[integer[Any]]], foldGroups: ndarray[Tuple[int], dtype[integer[Any]]], gapsWhere: ndarray[Tuple[int], dtype[integer[Any]]], mapShape: ndarray[Tuple[int], dtype[integer[Any]]], my: ndarray[Tuple[int], dtype[integer[Any]]], track: ndarray[Tuple[int, int], dtype[integer[Any]]]) -> None:
     countInitialize(connectionGraph, gapsWhere, my, track)
     if my[indexMy.taskDivisions.value] > 0: