mapFolding 0.7.1__py3-none-any.whl → 0.8.1__py3-none-any.whl

mapFolding/reference/flattened.py

@@ -1,14 +1,15 @@
 """The algorithm flattened into semantic sections.
 This version is not maintained, so you may see differences from the current version."""
+from collections.abc import Sequence
 from numpy import integer
 from numpy.typing import NDArray
-from typing import List, Any, Final, Optional, Union, Sequence, Tuple, Type, TypedDict
+from typing import Any, Final, TypedDict
 import enum
 import numpy
 import sys
 
-def countFolds(listDimensions: Sequence[int], computationDivisions = None, CPUlimit: Optional[Union[int, float, bool]] = None):
-	def doWhile():
+def countFolds(listDimensions: Sequence[int], computationDivisions: int | str | None = None, CPUlimit: int | float | bool | None = None) -> int:
+	def doWhile() -> None:
 
 		while activeLeafGreaterThan0Condition():
 
@@ -49,99 +50,99 @@ def countFolds(listDimensions: Sequence[int], computationDivisions = None, CPUli
 			if placeLeafCondition():
 				placeLeaf()
 
-	def activeGapIncrement():
+	def activeGapIncrement() -> None:
 		my[indexMy.gap1ndex] += 1
 
-	def activeLeafGreaterThan0Condition():
+	def activeLeafGreaterThan0Condition() -> bool:
 		return my[indexMy.leaf1ndex] > 0
 
-	def activeLeafGreaterThanLeavesTotalCondition():
+	def activeLeafGreaterThanLeavesTotalCondition() -> bool:
 		return my[indexMy.leaf1ndex] > the[indexThe.leavesTotal]
 
-	def activeLeafIsTheFirstLeafCondition():
+	def activeLeafIsTheFirstLeafCondition() -> bool:
 		return my[indexMy.leaf1ndex] <= 1
 
-	def activeLeafNotEqualToTaskDivisionsCondition():
+	def activeLeafNotEqualToTaskDivisionsCondition() -> bool:
 		return my[indexMy.leaf1ndex] != the[indexThe.taskDivisions]
 
-	def allDimensionsAreUnconstrained():
+	def allDimensionsAreUnconstrained() -> bool:
 		return my[indexMy.dimensionsUnconstrained] == the[indexThe.dimensionsTotal]
 
-	def backtrack():
+	def backtrack() -> None:
 		my[indexMy.leaf1ndex] -= 1
 		track[indexTrack.leafBelow, track[indexTrack.leafAbove, my[indexMy.leaf1ndex]]] = track[indexTrack.leafBelow, my[indexMy.leaf1ndex]]
 		track[indexTrack.leafAbove, track[indexTrack.leafBelow, my[indexMy.leaf1ndex]]] = track[indexTrack.leafAbove, my[indexMy.leaf1ndex]]
 
-	def backtrackCondition():
+	def backtrackCondition() -> bool:
 		return my[indexMy.leaf1ndex] > 0 and my[indexMy.gap1ndex] == track[indexTrack.gapRangeStart, my[indexMy.leaf1ndex] - 1]
 
-	def computationDivisionsCondition():
+	def computationDivisionsCondition() -> bool:
 		return the[indexThe.taskDivisions] == int(False)
 
-	def countGaps():
+	def countGaps() -> None:
 		gapsWhere[my[indexMy.gap1ndexCeiling]] = my[indexMy.leafConnectee]
 		if track[indexTrack.countDimensionsGapped, my[indexMy.leafConnectee]] == 0:
 			gap1ndexCeilingIncrement()
 		track[indexTrack.countDimensionsGapped, my[indexMy.leafConnectee]] += 1
 
-	def dimension1ndexIncrement():
+	def dimension1ndexIncrement() -> None:
 		my[indexMy.dimension1ndex] += 1
 
-	def dimensionsUnconstrainedCondition():
+	def dimensionsUnconstrainedCondition() -> bool:
 		return connectionGraph[my[indexMy.dimension1ndex], my[indexMy.leaf1ndex], my[indexMy.leaf1ndex]] == my[indexMy.leaf1ndex]
 
-	def dimensionsUnconstrainedIncrement():
+	def dimensionsUnconstrainedIncrement() -> None:
 		my[indexMy.dimensionsUnconstrained] += 1
 
-	def filterCommonGaps():
+	def filterCommonGaps() -> None:
 		gapsWhere[my[indexMy.gap1ndex]] = gapsWhere[my[indexMy.indexMiniGap]]
 		if track[indexTrack.countDimensionsGapped, gapsWhere[my[indexMy.indexMiniGap]]] == the[indexThe.dimensionsTotal] - my[indexMy.dimensionsUnconstrained]:
 			activeGapIncrement()
 		track[indexTrack.countDimensionsGapped, gapsWhere[my[indexMy.indexMiniGap]]] = 0
 
-	def findGapsInitializeVariables():
+	def findGapsInitializeVariables() -> None:
 		my[indexMy.dimensionsUnconstrained] = 0
 		my[indexMy.gap1ndexCeiling] = track[indexTrack.gapRangeStart, my[indexMy.leaf1ndex] - 1]
 		my[indexMy.dimension1ndex] = 1
 
-	def foldsSubTotalsIncrement():
+	def foldsSubTotalsIncrement() -> None:
 		foldsSubTotals[my[indexMy.taskIndex]] += the[indexThe.leavesTotal]
 
-	def gap1ndexCeilingIncrement():
+	def gap1ndexCeilingIncrement() -> None:
 		my[indexMy.gap1ndexCeiling] += 1
 
-	def indexMiniGapIncrement():
+	def indexMiniGapIncrement() -> None:
 		my[indexMy.indexMiniGap] += 1
 
-	def indexMiniGapInitialization():
+	def indexMiniGapInitialization() -> None:
 		my[indexMy.indexMiniGap] = my[indexMy.gap1ndex]
 
-	def insertUnconstrainedLeaf():
+	def insertUnconstrainedLeaf() -> None:
 		my[indexMy.indexLeaf] = 0
 		while my[indexMy.indexLeaf] < my[indexMy.leaf1ndex]:
 			gapsWhere[my[indexMy.gap1ndexCeiling]] = my[indexMy.indexLeaf]
 			my[indexMy.gap1ndexCeiling] += 1
 			my[indexMy.indexLeaf] += 1
 
-	def leafBelowSentinelIs1Condition():
+	def leafBelowSentinelIs1Condition() -> bool:
 		return track[indexTrack.leafBelow, 0] == 1
 
-	def leafConnecteeInitialization():
+	def leafConnecteeInitialization() -> None:
 		my[indexMy.leafConnectee] = connectionGraph[my[indexMy.dimension1ndex], my[indexMy.leaf1ndex], my[indexMy.leaf1ndex]]
 
-	def leafConnecteeUpdate():
+	def leafConnecteeUpdate() -> None:
 		my[indexMy.leafConnectee] = connectionGraph[my[indexMy.dimension1ndex], my[indexMy.leaf1ndex], track[indexTrack.leafBelow, my[indexMy.leafConnectee]]]
 
-	def loopingLeavesConnectedToActiveLeaf():
+	def loopingLeavesConnectedToActiveLeaf() -> bool:
 		return my[indexMy.leafConnectee] != my[indexMy.leaf1ndex]
 
-	def loopingTheDimensions():
+	def loopingTheDimensions() -> bool:
 		return my[indexMy.dimension1ndex] <= the[indexThe.dimensionsTotal]
 
-	def loopingToActiveGapCeiling():
+	def loopingToActiveGapCeiling() -> bool:
 		return my[indexMy.indexMiniGap] < my[indexMy.gap1ndexCeiling]
 
-	def placeLeaf():
+	def placeLeaf() -> None:
 		my[indexMy.gap1ndex] -= 1
 		track[indexTrack.leafAbove, my[indexMy.leaf1ndex]] = gapsWhere[my[indexMy.gap1ndex]]
 		track[indexTrack.leafBelow, my[indexMy.leaf1ndex]] = track[indexTrack.leafBelow, track[indexTrack.leafAbove, my[indexMy.leaf1ndex]]]
@@ -150,13 +151,13 @@ def countFolds(listDimensions: Sequence[int], computationDivisions = None, CPUli
 		track[indexTrack.gapRangeStart, my[indexMy.leaf1ndex]] = my[indexMy.gap1ndex]
 		my[indexMy.leaf1ndex] += 1
 
-	def placeLeafCondition():
+	def placeLeafCondition() -> bool:
 		return my[indexMy.leaf1ndex] > 0
 
-	def taskIndexCondition():
+	def taskIndexCondition() -> bool:
 		return my[indexMy.leafConnectee] % the[indexThe.taskDivisions] == my[indexMy.taskIndex]
 
-	def thereAreComputationDivisionsYouMightSkip():
+	def thereAreComputationDivisionsYouMightSkip() -> bool:
 		if computationDivisionsCondition():
 			return True
 		if activeLeafNotEqualToTaskDivisionsCondition():
@@ -166,11 +167,11 @@ def countFolds(listDimensions: Sequence[int], computationDivisions = None, CPUli
 		return False
 
 	stateUniversal = outfitFoldings(listDimensions, computationDivisions=computationDivisions, CPUlimit=CPUlimit)
-	connectionGraph: Final[numpy.ndarray] = stateUniversal['connectionGraph']
+	connectionGraph: Final[NDArray[numpy.integer[Any]]] = stateUniversal['connectionGraph']
 	foldsSubTotals = stateUniversal['foldsSubTotals']
 	gapsWhere = stateUniversal['gapsWhere']
 	my = stateUniversal['my']
-	the: Final[numpy.ndarray] = stateUniversal['the']
+	the: Final[NDArray[numpy.integer[Any]]] = stateUniversal['the']
 	track = stateUniversal['track']
 
 	if the[indexThe.taskDivisions] == int(False):
@@ -192,7 +193,7 @@ def countFolds(listDimensions: Sequence[int], computationDivisions = None, CPUli
 class EnumIndices(enum.IntEnum):
 	"""Base class for index enums."""
 	@staticmethod
-	def _generate_next_value_(name, start, count, last_values):
+	def _generate_next_value_(name: str, start: int, count: int, last_values: list[int]) -> int:
 		"""0-indexed."""
 		return count
 
@@ -229,7 +230,7 @@ class indexTrack(EnumIndices):
 class computationState(TypedDict):
 	connectionGraph: NDArray[integer[Any]]
 	foldsSubTotals: NDArray[integer[Any]]
-	mapShape: Tuple[int, ...]
+	mapShape: tuple[int, ...]
 	my: NDArray[integer[Any]]
 	gapsWhere: NDArray[integer[Any]]
 	the: NDArray[integer[Any]]
@@ -262,7 +263,7 @@ def getLeavesTotal(listDimensions: Sequence[int]) -> int:
 
 		return productDimensions
 
-def getTaskDivisions(computationDivisions: Optional[Union[int, str]], concurrencyLimit: int, CPUlimit: Optional[Union[bool, float, int]], listDimensions: Sequence[int]):
+def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: int, CPUlimit: bool | float | int | None, listDimensions: Sequence[int]) -> int:
 	if not computationDivisions:
 		return 0
 	else:
@@ -284,7 +285,7 @@ def getTaskDivisions(computationDivisions: Optional[Union[int, str]], concurrenc
 
 	return taskDivisions
 
-def makeConnectionGraph(listDimensions: Sequence[int], **keywordArguments: Optional[Type]) -> NDArray[integer[Any]]:
+def makeConnectionGraph(listDimensions: Sequence[int], **keywordArguments: type | None) -> NDArray[integer[Any]]:
 	datatype = keywordArguments.get('datatype', dtypeMedium)
 	mapShape = validateListDimensions(listDimensions)
 	leavesTotal = getLeavesTotal(mapShape)
@@ -316,12 +317,12 @@ def makeConnectionGraph(listDimensions: Sequence[int], **keywordArguments: Optio
 					connectionGraph[dimension1ndex, activeLeaf1ndex, connectee1ndex] = connectee1ndex
 	return connectionGraph
 
-def makeDataContainer(shape, datatype: Optional[Type] = None):
+def makeDataContainer(shape: int | Sequence[int], datatype: type | None = None) -> NDArray[integer[Any]]:
 	if datatype is None:
 		datatype = dtypeMedium
 	return numpy.zeros(shape, dtype=datatype)
 
-def outfitFoldings(listDimensions: Sequence[int], computationDivisions: Optional[Union[int, str]] = None, CPUlimit: Optional[Union[bool, float, int]] = None, **keywordArguments: Optional[Type]) -> computationState:
+def outfitFoldings(listDimensions: Sequence[int], computationDivisions: int | str | None = None, CPUlimit: bool | float | int | None = None, **keywordArguments: type | None) -> computationState:
 	datatypeMedium = keywordArguments.get('datatypeMedium', dtypeMedium)
 	datatypeLarge = keywordArguments.get('datatypeLarge', dtypeLarge)
 
@@ -346,10 +347,10 @@ def outfitFoldings(listDimensions: Sequence[int], computationDivisions: Optional
 	stateInitialized['my'][indexMy.leaf1ndex] = 1
 	return stateInitialized
 
-def parseDimensions(dimensions: Sequence[int], parameterName: str = 'unnamed parameter') -> List[int]:
+def parseDimensions(dimensions: Sequence[int], parameterName: str = 'unnamed parameter') -> list[int]:
 	# listValidated = intInnit(dimensions, parameterName)
 	listNOTValidated = dimensions if isinstance(dimensions, (list, tuple)) else list(dimensions)
-	listNonNegative = []
+	listNonNegative: list[int] = []
 	for dimension in listNOTValidated:
 		if dimension < 0:
 			raise ValueError(f"Dimension {dimension} must be non-negative")
@@ -358,7 +359,7 @@ def parseDimensions(dimensions: Sequence[int], parameterName: str = 'unnamed par
 		raise ValueError("At least one dimension must be non-negative")
 	return listNonNegative
 
-def setCPUlimit(CPUlimit: Union[bool, float, int, None]) -> int:
+def setCPUlimit(CPUlimit: bool | float | int | None) -> int:
 	# if not (CPUlimit is None or isinstance(CPUlimit, (bool, int, float))):
 	#	 CPUlimit = oopsieKwargsie(CPUlimit)
 	# concurrencyLimit = defineConcurrencyLimit(CPUlimit)
@@ -367,7 +368,7 @@ def setCPUlimit(CPUlimit: Union[bool, float, int, None]) -> int:
 	concurrencyLimit = concurrencyLimitHARDCODED
 	return concurrencyLimit
 
-def validateListDimensions(listDimensions: Sequence[int]) -> List[int]:
+def validateListDimensions(listDimensions: Sequence[int]) -> list[int]:
 	if not listDimensions:
 		raise ValueError(f"listDimensions is a required parameter.")
 	listNonNegative = parseDimensions(listDimensions, 'listDimensions')

mapFolding/reference/hunterNumba.py

@@ -1,9 +1,9 @@
-from typing import List
+from typing import Any
 import numba
 import numpy
 
 @numba.jit(cache=True, nopython=True, fastmath=True)
-def countFolds(listDimensions: List[int]) -> int:
+def countFolds(listDimensions: list[int]) -> int:
 	"""
 	Count the number of distinct ways to fold a map with at least two positive dimensions.
 
@@ -13,10 +13,10 @@ def countFolds(listDimensions: List[int]) -> int:
 	Returns:
 		foldsTotal: The total number of distinct folds for the given map dimensions.
 	"""
-	def integerSmall(value) -> numpy.uint8:
+	def integerSmall(value: numpy.integer[Any] | Any) -> numpy.uint8:
 		return numpy.uint8(value)
 
-	def integerLarge(value) -> numpy.uint64:
+	def integerLarge(value: numpy.integer[Any] | Any) -> numpy.uint64:
 		return numpy.uint64(value)
 
 	dtypeMedium = numpy.uint8

mapFolding/reference/irvineJavaPort.py

@@ -2,7 +2,7 @@
 Ported from the Java version by Sean A. Irvine:
 https://github.com/archmageirvine/joeis/blob/80e3e844b11f149704acbab520bc3a3a25ac34ff/src/irvine/oeis/a001/A001415.java
 
-Citation: mapFolding/citations/jOEIS.bibtex
+Citation: https://github.com/hunterhogan/mapFolding/blob/134f2e6ecdf59fb6f6829c775475544a6aaaa800/citations/jOEIS.bibtex
 """
 def foldings(p: list[int], res: int = 0, mod: int = 0) -> int:
 	"""

mapFolding/reference/lunnanNumpy.py

@@ -2,10 +2,9 @@
 A generally faithful translation of the original Atlas Autocode code by W. F. Lunnon to Python using NumPy.
 W. F. Lunnon, Multi-dimensional map-folding, The Computer Journal, Volume 14, Issue 1, 1971, Pages 75-80, https://doi.org/10.1093/comjnl/14.1.75
 """
-from typing import List
 import numpy
 
-def foldings(p: List[int]) -> int:
+def foldings(p: list[int]) -> int:
 	"""
 	Run loop with (A, B) on each folding of a p[1] x ... x p[d] map, where A and B are the above and below vectors.
 
@@ -66,7 +65,7 @@ def foldings(p: List[int]) -> int:
 	# D[i][l][m] = leaf connected to m in section i when inserting l;
 
 	G: int = 0
-	l: int = 1
+	l = 1
 
 	# kick off with null folding
 	while l > 0:
@@ -86,7 +85,7 @@ def foldings(p: List[int]) -> int:
 					if D[i][l][l] == l:
 						dd = dd + 1
 					else:
-						m: int = D[i][l][l]
+						m = D[i][l][l]
 						while m != l:
 							gap[gg] = m
 							if count[m] == 0:

mapFolding/reference/lunnanWhile.py

@@ -2,9 +2,7 @@
 A largely faithful translation of the original Atlas Autocode code by W. F. Lunnon to Python using `while`.
 W. F. Lunnon, Multi-dimensional map-folding, The Computer Journal, Volume 14, Issue 1, 1971, Pages 75-80, https://doi.org/10.1093/comjnl/14.1.75
 """
-from typing import Sequence
-
-def foldings(p: Sequence[int]) -> int:
+def foldings(p: list[int]) -> int:
 	"""
 	Run loop with (A, B) on each folding of a p[1] x ... x p[d] map, where A and B are the above and below vectors.
 
@@ -38,8 +36,8 @@ def foldings(p: Sequence[int]) -> int:
 	# and later gap[gapter[l]] is the gap where leaf l is currently inserted
 
 	P = [1] * (d + 1)
-	C = [[0] * (n + 1) for dimension1 in range(d + 1)]
-	D = [[[0] * (n + 1) for dimension2 in range(n + 1)] for dimension1 in range(d + 1)]
+	C = [[0] * (n + 1) for _dimension1 in range(d + 1)]
+	D = [[[0] * (n + 1) for _dimension2 in range(n + 1)] for _dimension1 in range(d + 1)]
 
 	for i in range(1, d + 1):
 		P[i] = P[i - 1] * p[i - 1]
@@ -65,7 +63,7 @@ def foldings(p: Sequence[int]) -> int:
 	# D[i][l][m] = leaf connected to m in section i when inserting l;
 
 	G: int = 0
-	l: int = 1
+	l = 1
 
 	# kick off with null folding
 	while l > 0:
@@ -84,7 +82,7 @@ def foldings(p: Sequence[int]) -> int:
 				if D[i][l][l] == l:
 					dd = dd + 1
 				else:
-					m: int = D[i][l][l]
+					m = D[i][l][l]
 					while m != l:
 						gap[gg] = m
 						if count[m] == 0:

mapFolding/reference/rotatedEntryPoint.py

@@ -1,6 +1,5 @@
 from mapFolding import outfitFoldings
 from numba import njit
-from typing import List
 import numpy
 from numpy.typing import NDArray
 
@@ -42,7 +41,7 @@ tricky = [
 
 COUNTindicesStatic = len(tricky)
 
-def countFolds(listDimensions: List[int]):
+def countFolds(listDimensions: list[int]):
 	static = numpy.zeros(COUNTindicesStatic, dtype=numpy.int64)
 
 	listDimensions, static[leavesTotal], D, track,gapsWhere = outfitFoldings(listDimensions)
@@ -55,7 +54,7 @@ def countFolds(listDimensions: List[int]):
 	return foldingsTotal
 
 # @recordBenchmarks()
-def _sherpa(track: NDArray, gap: NDArray, static: NDArray, D: NDArray, p: List[int]):
+def _sherpa(track: NDArray, gap: NDArray, static: NDArray, D: NDArray, p: list[int]):
 	"""Performance critical section that counts foldings.
 
 	Parameters:

mapFolding/someAssemblyRequired/__init__.py

@@ -1,16 +1,46 @@
-from mapFolding.someAssemblyRequired.whatWillBe import (
+"""
+Code transformation framework for algorithmic optimization.
+
+This package implements a comprehensive framework for programmatically analyzing,
+transforming, and generating Python code. It enables sophisticated algorithm optimization
+through abstract syntax tree (AST) manipulation, allowing algorithms to be transformed
+from a readable, functional implementation into highly-optimized variants tailored for
+different execution environments or specific computational tasks.
+
+Core capabilities:
+1. AST Pattern Recognition - Precisely identify and match code patterns using composable predicates
+2. Algorithm Transformation - Convert functional state-based implementations to primitive operations
+3. Dataclass "Shattering" - Decompose complex state objects into primitive components
+4. Performance Optimization - Apply domain-specific optimizations for numerical computation
+5. Code Generation - Generate specialized implementations with appropriate imports and syntax
+
+The transformation pipeline supports multiple optimization targets, from general-purpose
+acceleration to generating highly-specialized variants optimized for specific input parameters.
+This multi-level transformation approach allows for both development flexibility and
+runtime performance, preserving algorithm readability in the source while enabling
+maximum execution speed in production.
+
+These tools were developed for map folding computation optimization but are designed as
+general-purpose utilities applicable to a wide range of code transformation scenarios,
+particularly for numerically-intensive algorithms that benefit from just-in-time compilation.
+"""
+from mapFolding.someAssemblyRequired.transformationTools import (
 	ast_Identifier as ast_Identifier,
 	extractClassDef as extractClassDef,
 	extractFunctionDef as extractFunctionDef,
-	executeActionUnlessDescendantMatches as executeActionUnlessDescendantMatches,
 	ifThis as ifThis,
 	IngredientsFunction as IngredientsFunction,
 	IngredientsModule as IngredientsModule,
+	inlineThisFunctionWithTheseValues as inlineThisFunctionWithTheseValues,
 	LedgerOfImports as LedgerOfImports,
-	listNumbaCallableDispatchees as listNumbaCallableDispatchees,
 	Make as Make,
+	makeDictionaryReplacementStatements as makeDictionaryReplacementStatements,
 	NodeCollector as NodeCollector,
 	NodeReplacer as NodeReplacer,
+	RecipeSynthesizeFlow as RecipeSynthesizeFlow,
 	strDotStrCuzPyStoopid as strDotStrCuzPyStoopid,
 	Then as Then,
+	write_astModule as write_astModule,
+	Z0Z_executeActionUnlessDescendantMatches as Z0Z_executeActionUnlessDescendantMatches,
+	Z0Z_replaceMatchingASTnodes as Z0Z_replaceMatchingASTnodes,
 	)

mapFolding/someAssemblyRequired/getLLVMforNoReason.py

@@ -1,21 +1,38 @@
-import importlib
+"""
+Utility for extracting LLVM IR from compiled Python modules.
+
+This module provides functionality to extract and save the LLVM Intermediate Representation (IR)
+generated when Numba compiles Python functions. It implements a simple interface that:
+
+1. Imports a specified Python module from its file path
+2. Extracts the LLVM IR from a specified function within that module
+3. Writes the IR to a file with the same base name but with the .ll extension
+
+The extracted LLVM IR can be valuable for debugging, optimization analysis, or educational
+purposes, as it provides a view into how high-level Python code is translated into
+lower-level representations for machine execution.
+
+While originally part of a tighter integration with the code generation pipeline,
+this module now operates as a standalone utility that can be applied to any module
+containing Numba-compiled functions.
+"""
 from importlib.machinery import ModuleSpec
+from pathlib import Path
 from types import ModuleType
 import importlib.util
 import llvmlite.binding
-import pathlib
 
-def writeModuleLLVM(pathFilename: pathlib.Path, identifierCallable: str) -> pathlib.Path:
-	"""Import the generated module directly and get its LLVM IR."""
-	specTarget: ModuleSpec | None = importlib.util.spec_from_file_location("generatedModule", pathFilename)
-	if specTarget is None or specTarget.loader is None:
-		raise ImportError(f"Could not create module spec or loader for {pathFilename}")
-	moduleTarget: ModuleType = importlib.util.module_from_spec(specTarget)
-	specTarget.loader.exec_module(moduleTarget)
+def writeModuleLLVM(pathFilename: Path, identifierCallable: str) -> Path:
+    """Import the generated module directly and get its LLVM IR."""
+    specTarget: ModuleSpec | None = importlib.util.spec_from_file_location("generatedModule", pathFilename)
+    if specTarget is None or specTarget.loader is None:
+        raise ImportError(f"Could not create module spec or loader for {pathFilename}")
+    moduleTarget: ModuleType = importlib.util.module_from_spec(specTarget)
+    specTarget.loader.exec_module(moduleTarget)
 
-	# Get LLVM IR and write to file
-	linesLLVM = moduleTarget.__dict__[identifierCallable].inspect_llvm()[()]
-	moduleLLVM: llvmlite.binding.ModuleRef = llvmlite.binding.module.parse_assembly(linesLLVM)
-	pathFilenameLLVM: pathlib.Path = pathFilename.with_suffix(".ll")
-	pathFilenameLLVM.write_text(str(moduleLLVM))
-	return pathFilenameLLVM
+    # Get LLVM IR and write to file
+    linesLLVM = moduleTarget.__dict__[identifierCallable].inspect_llvm()[()]
+    moduleLLVM: llvmlite.binding.ModuleRef = llvmlite.binding.module.parse_assembly(linesLLVM)
+    pathFilenameLLVM: Path = pathFilename.with_suffix(".ll")
+    pathFilenameLLVM.write_text(str(moduleLLVM))
+    return pathFilenameLLVM

mapFolding/someAssemblyRequired/ingredientsNumba.py

@@ -1,6 +1,29 @@
-from collections.abc import Callable
+"""
+Numba-specific ingredients for optimized code generation.
+
+This module provides specialized tools, constants, and types specifically designed
+for transforming Python code into Numba-accelerated implementations. It implements:
+
+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
+
+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.
+"""
+
+from collections.abc import Callable, Sequence
+from mapFolding.someAssemblyRequired import ifThis, IngredientsFunction, Make
 from numba.core.compiler import CompilerBase as numbaCompilerBase
-from typing import Any, TYPE_CHECKING, Final
+from typing import Any, cast, Final, TYPE_CHECKING
+import ast
 
 try:
 	from typing import NotRequired
@@ -98,3 +121,86 @@ parametersNumbaMinimum: Final[ParametersNumba] = {
 		'nopython': False,
 		'forceobj': True,
 		'parallel': False, }
+
+Z0Z_numbaDataTypeModule = 'numba'
+Z0Z_decoratorCallable = 'jit'
+
+def thisIsNumbaDotJit(Ima: ast.AST) -> bool:
+	return ifThis.isCallNamespace_Identifier(Z0Z_numbaDataTypeModule, Z0Z_decoratorCallable)(Ima)
+
+def thisIsJit(Ima: ast.AST) -> bool:
+	return ifThis.isCall_Identifier(Z0Z_decoratorCallable)(Ima)
+
+def thisIsAnyNumbaJitDecorator(Ima: ast.AST) -> bool:
+	return thisIsNumbaDotJit(Ima) or thisIsJit(Ima)
+
+def decorateCallableWithNumba(ingredientsFunction: IngredientsFunction, parametersNumba: ParametersNumba | None = None) -> IngredientsFunction:
+	def Z0Z_UnhandledDecorators(astCallable: ast.FunctionDef) -> ast.FunctionDef:
+		# TODO: more explicit handling of decorators. I'm able to ignore this because I know `algorithmSource` doesn't have any decorators.
+		for decoratorItem in astCallable.decorator_list.copy():
+			import warnings
+			astCallable.decorator_list.remove(decoratorItem)
+			warnings.warn(f"Removed decorator {ast.unparse(decoratorItem)} from {astCallable.name}")
+		return astCallable
+
+	def makeSpecialSignatureForNumba(signatureElement: ast.arg) -> ast.Subscript | ast.Name | None:
+		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):
+				shapeAsListSlices: list[ast.Slice] = [ast.Slice() for _axis in range(len(annotationShape.slice.elts))]
+				shapeAsListSlices[-1] = ast.Slice(step=ast.Constant(value=1))
+				shapeAST: ast.Slice | ast.Tuple = ast.Tuple(elts=list(shapeAsListSlices), ctx=ast.Load())
+			else:
+				shapeAST = ast.Slice(step=ast.Constant(value=1))
+
+			annotationDtype: ast.expr = signatureElement.annotation.slice.elts[1]
+			if (isinstance(annotationDtype, ast.Subscript) and isinstance(annotationDtype.slice, ast.Attribute)):
+				datatypeAST = annotationDtype.slice.attr
+			else:
+				datatypeAST = None
+
+			ndarrayName = signatureElement.arg
+			Z0Z_hacky_dtype: str = ndarrayName
+			datatype_attr = datatypeAST or Z0Z_hacky_dtype
+			ingredientsFunction.imports.addImportFromStr(datatypeModuleDecorator, datatype_attr)
+			datatypeNumba = ast.Name(id=datatype_attr, ctx=ast.Load())
+
+			return ast.Subscript(value=datatypeNumba, slice=shapeAST, ctx=ast.Load())
+
+		elif isinstance(signatureElement.annotation, ast.Name):
+			return signatureElement.annotation
+		return None
+
+	datatypeModuleDecorator: str = Z0Z_numbaDataTypeModule
+	list_argsDecorator: Sequence[ast.expr] = []
+
+	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)
+		if signatureElement:
+			list_arg4signature_or_function.append(signatureElement)
+
+	if ingredientsFunction.astFunctionDef.returns and isinstance(ingredientsFunction.astFunctionDef.returns, ast.Name):
+		theReturn: ast.Name = ingredientsFunction.astFunctionDef.returns
+		list_argsDecorator = [cast(ast.expr, ast.Call(func=ast.Name(id=theReturn.id, ctx=ast.Load())
+							, args=list_arg4signature_or_function if list_arg4signature_or_function else [], keywords=[] ) )]
+	elif list_arg4signature_or_function:
+		list_argsDecorator = [cast(ast.expr, ast.Tuple(elts=list_arg4signature_or_function, ctx=ast.Load()))]
+
+	ingredientsFunction.astFunctionDef = Z0Z_UnhandledDecorators(ingredientsFunction.astFunctionDef)
+	if parametersNumba is None:
+		parametersNumba = parametersNumbaDEFAULT
+	listDecoratorKeywords: list[ast.keyword] = [Make.ast_keyword(parameterName, Make.astConstant(parameterValue)) for parameterName, parameterValue in parametersNumba.items()]
+
+	decoratorModule: str = Z0Z_numbaDataTypeModule
+	decoratorCallable: str = Z0Z_decoratorCallable
+	ingredientsFunction.imports.addImportFromStr(decoratorModule, decoratorCallable)
+	# Leave this line in so that global edits will change it.
+	astDecorator: ast.Call = Make.astCall(Make.astName(decoratorCallable), list_argsDecorator, listDecoratorKeywords)
+	astDecorator: ast.Call = Make.astCall(Make.astName(decoratorCallable), list_astKeywords=listDecoratorKeywords) # type: ignore[no-redef]
+
+	ingredientsFunction.astFunctionDef.decorator_list = [astDecorator]
+	return ingredientsFunction