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

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,3 +1,29 @@
+"""
+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,
@@ -5,6 +31,7 @@ from mapFolding.someAssemblyRequired.transformationTools import (
 	ifThis as ifThis,
 	IngredientsFunction as IngredientsFunction,
 	IngredientsModule as IngredientsModule,
+	inlineThisFunctionWithTheseValues as inlineThisFunctionWithTheseValues,
 	LedgerOfImports as LedgerOfImports,
 	Make as Make,
 	makeDictionaryReplacementStatements as makeDictionaryReplacementStatements,
@@ -13,5 +40,7 @@ from mapFolding.someAssemblyRequired.transformationTools import (
 	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,20 +1,38 @@
+"""
+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,7 +1,28 @@
+"""
+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, cast
+from typing import Any, cast, Final, TYPE_CHECKING
 import ast
 
 try:

mapFolding/someAssemblyRequired/synthesizeNumbaFlow.py

@@ -0,0 +1,196 @@
+"""
+Orchestrator for generating Numba-optimized versions of the map folding algorithm.
+
+This module transforms the pure Python implementation of the map folding algorithm
+into a highly-optimized Numba implementation. It serves as the high-level coordinator
+for the code transformation process, orchestrating the following steps:
+
+1. Extracting the core algorithm functions from the source implementation
+2. Transforming function signatures and state handling for Numba compatibility
+3. Converting state-based operations to direct primitive operations
+4. Applying Numba decorators with appropriate optimization parameters
+5. Managing imports and dependencies for the generated code
+6. Assembling and writing the transformed implementation
+
+The transformation process preserves the algorithm's logic while dramatically improving
+performance by leveraging Numba's just-in-time compilation capabilities. This module
+depends on the abstract transformation tools, dataclass handling utilities, and
+Numba-specific optimization configurations from other modules in the package.
+
+The primary entry point is the makeNumbaFlow function, which can be executed directly
+to generate a fresh optimized implementation.
+"""
+
+from mapFolding.someAssemblyRequired import (
+	extractFunctionDef,
+	ifThis,
+	IngredientsFunction,
+	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
+import ast
+
+def makeNumbaFlow(numbaFlow: RecipeSynthesizeFlow = RecipeSynthesizeFlow()) -> None:
+	"""
+	Think about a better organization of this function.
+
+	Currently, transform `Callable` in order:
+		sourceDispatcherCallable
+		sourceInitializeCallable
+		sourceParallelCallable
+		sourceSequentialCallable
+
+	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.
+
+	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?
+
+	# 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
+
+	# ===========================================================
+	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)
+
+	# TODO remove hardcoding
+	namespaceHARDCODED = 'concurrencyManager'
+	identifierHARDCODED = 'submit'
+	sourceNamespace = namespaceHARDCODED
+	sourceIdentifier = identifierHARDCODED
+	NodeReplacer(
+		findThis = ifThis.isAssignAndValueIsCallNamespace_Identifier(sourceNamespace, sourceIdentifier)
+		, doThat = Then.insertThisAbove(shatteredDataclass.listAnnAssign4DataclassUnpack)
+			).visit(ingredientsDispatcher.astFunctionDef)
+	NodeReplacer(
+		findThis = ifThis.isCallNamespace_Identifier(sourceNamespace, sourceIdentifier)
+		, doThat = Then.replaceWith(Make.astCall(Make.astAttribute(Make.astName(sourceNamespace), sourceIdentifier)
+									, 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)
+
+	# ===========================================================
+	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
+	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))
+
+	write_astModule(ingredientsModuleNumbaUnified, numbaFlow.pathFilenameDispatcher, numbaFlow.packageName)
+
+if __name__ == '__main__':
+	makeNumbaFlow()

mapFolding/someAssemblyRequired/synthesizeNumbaJobVESTIGIAL.py

@@ -2,8 +2,7 @@
 from collections.abc import Sequence
 from typing import Any, cast, TYPE_CHECKING
 from mapFolding.filesystem import getFilenameFoldsTotal, getPathFilenameFoldsTotal
-from mapFolding.someAssemblyRequired import ( ifThis, Make, NodeReplacer, Then, )
-from mapFolding.someAssemblyRequired.transformationTools import LedgerOfImports
+from mapFolding.someAssemblyRequired import ( ifThis, LedgerOfImports, Make, NodeReplacer, Then, )
 from mapFolding.theSSOT import ( ComputationState, raiseIfNoneGitHubIssueNumber3, getPathJobRootDEFAULT, )
 from os import PathLike
 from pathlib import Path
@@ -16,7 +15,7 @@ import copy
 import inspect
 import numpy
 if TYPE_CHECKING:
-	from mapFolding.someAssemblyRequired.synthesizeDataConverters import makeStateJob
+	from mapFolding.someAssemblyRequired.transformDataStructures import makeStateJobOUTDATED
 	from mapFolding.someAssemblyRequired.ingredientsNumba import thisIsNumbaDotJit, decorateCallableWithNumba
 	from mapFolding.someAssemblyRequired.ingredientsNumba import ParametersNumba, parametersNumbaDEFAULT
 
@@ -291,7 +290,7 @@ def writeJobNumba(mapShape: Sequence[int], algorithmSource: ModuleType, callable
 	"""
 
 	# NOTE get the raw ingredients: data and the algorithm
-	stateJob = makeStateJob(mapShape, writeJob=False, **keywordArguments)
+	stateJob = makeStateJobOUTDATED(mapShape, writeJob=False, **keywordArguments)
 	pythonSource: str = inspect.getsource(algorithmSource)
 	astModule: ast.Module = ast.parse(pythonSource)
 	setFunctionDef: set[ast.FunctionDef] = {statement for statement in astModule.body if isinstance(statement, ast.FunctionDef)}

mapFolding/someAssemblyRequired/transformDataStructures.py

@@ -0,0 +1,162 @@
+"""
+Utilities for transforming complex data structures in Python code generation.
+
+This module provides specialized tools for working with structured data types during
+the code transformation process, with a particular focus on handling dataclasses. It
+implements functionality that enables:
+
+1. Decomposing dataclasses into individual fields for efficient processing
+2. Creating optimized parameter passing for transformed functions
+3. Converting between different representations of data structures
+4. Serializing and deserializing computation state objects
+
+The core functionality revolves around the "shattering" process that breaks down
+a dataclass into its constituent components, making each field individually accessible
+for code generation and optimization purposes. This dataclass handling is critical for
+transforming algorithms that operate on unified state objects into optimized implementations
+that work with primitive types directly.
+
+While developed for transforming map folding computation state objects, the utilities are
+designed to be applicable to various data structure transformation scenarios.
+"""
+
+from collections.abc import Sequence
+from importlib import import_module
+from inspect import getsource as inspect_getsource
+from mapFolding.beDRY import outfitCountFolds, validateListDimensions
+from mapFolding.filesystem import getPathFilenameFoldsTotal
+from mapFolding.someAssemblyRequired import (
+	ast_Identifier,
+	extractClassDef,
+	ifThis,
+	LedgerOfImports,
+	Make,
+	NodeCollector,
+	strDotStrCuzPyStoopid,
+	Then,
+	Z0Z_executeActionUnlessDescendantMatches,
+)
+from mapFolding.theSSOT import ComputationState, getSourceAlgorithm
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Literal, overload
+import ast
+import dataclasses
+import pickle
+
+# Would `LibCST` be better than `ast` in some cases? https://github.com/hunterhogan/mapFolding/issues/7
+
+countingIdentifierHARDCODED = 'groupsOfFolds'
+
+@dataclasses.dataclass
+class ShatteredDataclass:
+	astAssignDataclassRepack: ast.Assign
+	astSubscriptPrimitiveTupleAnnotations4FunctionDef_returns: ast.Subscript
+	astTuple4AssignTargetsToFragments: ast.Tuple
+	countingVariableAnnotation: ast.expr
+	countingVariableName: ast.Name
+	ledgerDataclassANDFragments: LedgerOfImports = dataclasses.field(default_factory=LedgerOfImports)
+	list_ast_argAnnotated4ArgumentsSpecification: list[ast.arg] = dataclasses.field(default_factory=list)
+	list_keyword4DataclassInitialization: list[ast.keyword] = dataclasses.field(default_factory=list)
+	listAnnAssign4DataclassUnpack: list[ast.AnnAssign] = dataclasses.field(default_factory=list)
+	listAnnotations: list[ast.expr] = dataclasses.field(default_factory=list)
+	listNameDataclassFragments4Parameters: list[ast.Name] = dataclasses.field(default_factory=list)
+
+def shatter_dataclassesDOTdataclass(logicalPathModule: strDotStrCuzPyStoopid, dataclass_Identifier: ast_Identifier, instance_Identifier: ast_Identifier) -> ShatteredDataclass:
+	"""
+	Parameters:
+		logicalPathModule: gimme string cuz python is stoopid
+		dataclass_Identifier: The identifier of the dataclass to be dismantled.
+		instance_Identifier: In the synthesized module/function/scope, the identifier that will be used for the instance.
+	"""
+	module: ast.Module = ast.parse(inspect_getsource(import_module(logicalPathModule)))
+	astName_dataclassesDOTdataclass = Make.astName(dataclass_Identifier)
+
+	dataclass = extractClassDef(dataclass_Identifier, module)
+	if not isinstance(dataclass, ast.ClassDef):
+		raise ValueError(f"I could not find {dataclass_Identifier=} in {logicalPathModule=}.")
+
+	ledgerDataclassANDFragments = LedgerOfImports()
+	list_ast_argAnnotated4ArgumentsSpecification: list[ast.arg] = []
+	list_keyword4DataclassInitialization: list[ast.keyword] = []
+	listAnnAssign4DataclassUnpack: list[ast.AnnAssign] = []
+	listAnnotations: list[ast.expr] = []
+	listNameDataclassFragments4Parameters: list[ast.Name] = []
+
+	# TODO get the value from `groupsOfFolds: DatatypeFoldsTotal = dataclasses.field(default=DatatypeFoldsTotal(0), metadata={'theCountingIdentifier': True})`
+	countingVariable = countingIdentifierHARDCODED
+
+	addToLedgerPredicate = ifThis.isAnnAssignAndAnnotationIsName
+	addToLedgerAction = Then.Z0Z_ledger(logicalPathModule, ledgerDataclassANDFragments)
+	addToLedger = NodeCollector(addToLedgerPredicate, [addToLedgerAction])
+
+	exclusionPredicate = ifThis.is_keyword_IdentifierEqualsConstantValue('init', False)
+	appendKeywordAction = Then.Z0Z_appendKeywordMirroredTo(list_keyword4DataclassInitialization)
+	filteredAppendKeywordAction = Z0Z_executeActionUnlessDescendantMatches(exclusionPredicate, appendKeywordAction) # type: ignore
+
+	NodeCollector(
+		ifThis.isAnnAssignAndTargetIsName,
+			[Then.Z0Z_appendAnnAssignOf_nameDOTnameTo(instance_Identifier, listAnnAssign4DataclassUnpack)
+			, Then.append_targetTo(listNameDataclassFragments4Parameters) # type: ignore
+			, lambda node: addToLedger.visit(node)
+			, filteredAppendKeywordAction
+			, lambda node: list_ast_argAnnotated4ArgumentsSpecification.append(Make.ast_arg(node.target.id, node.annotation)) # type: ignore
+			, lambda node: listAnnotations.append(node.annotation) # type: ignore
+			]
+		).visit(dataclass)
+
+	shatteredDataclass = ShatteredDataclass(
+	astAssignDataclassRepack = Make.astAssign(listTargets=[Make.astName(instance_Identifier)], value=Make.astCall(astName_dataclassesDOTdataclass, list_astKeywords=list_keyword4DataclassInitialization))
+	, astSubscriptPrimitiveTupleAnnotations4FunctionDef_returns = Make.astSubscript(Make.astName('tuple'), Make.astTuple(listAnnotations))
+	, astTuple4AssignTargetsToFragments = Make.astTuple(listNameDataclassFragments4Parameters, ast.Store())
+	, countingVariableAnnotation = next(ast_arg.annotation for ast_arg in list_ast_argAnnotated4ArgumentsSpecification if ast_arg.arg == countingVariable) or Make.astName('Any')
+	, countingVariableName = Make.astName(countingVariable)
+	, ledgerDataclassANDFragments = ledgerDataclassANDFragments
+	, list_ast_argAnnotated4ArgumentsSpecification = list_ast_argAnnotated4ArgumentsSpecification
+	, list_keyword4DataclassInitialization = list_keyword4DataclassInitialization
+	, listAnnAssign4DataclassUnpack = listAnnAssign4DataclassUnpack
+	, listAnnotations = listAnnotations
+	, listNameDataclassFragments4Parameters = listNameDataclassFragments4Parameters
+	)
+
+	shatteredDataclass.ledgerDataclassANDFragments.addImportFromStr(logicalPathModule, dataclass_Identifier)
+	return shatteredDataclass
+
+@overload
+def makeStateJobOUTDATED(listDimensions: Sequence[int], *, writeJob: Literal[True], **keywordArguments: Any) -> Path: ...
+@overload
+def makeStateJobOUTDATED(listDimensions: Sequence[int], *, writeJob: Literal[False], **keywordArguments: Any) -> ComputationState: ...
+def makeStateJobOUTDATED(listDimensions: Sequence[int], *, writeJob: bool = True, **keywordArguments: Any) -> ComputationState | Path:
+	"""
+	Creates a computation state job for map folding calculations and optionally saves it to disk.
+
+	This function initializes a computation state for map folding calculations based on the given dimensions,
+	sets up the initial counting configuration, and can optionally save the state to a pickle file.
+
+	Parameters:
+		listDimensions: List of integers representing the dimensions of the map to be folded.
+		writeJob (True): Whether to save the state to disk.
+		**keywordArguments: Additional keyword arguments to pass to the computation state initialization.
+
+	Returns:
+		stateUniversal|pathFilenameJob: The computation state for the map folding calculations, or
+			the path to the saved state file if writeJob is True.
+	"""
+	mapShape = validateListDimensions(listDimensions)
+	stateUniversal: ComputationState = outfitCountFolds(mapShape, **keywordArguments)
+
+	moduleSource: ModuleType = getSourceAlgorithm()
+	# TODO `countInitialize` is hardcoded
+	stateUniversal = moduleSource.countInitialize(stateUniversal)
+
+	if not writeJob:
+		return stateUniversal
+
+	pathFilenameChopChop = getPathFilenameFoldsTotal(stateUniversal.mapShape, None)
+	suffix = pathFilenameChopChop.suffix
+	pathJob = Path(str(pathFilenameChopChop)[0:-len(suffix)])
+	pathJob.mkdir(parents=True, exist_ok=True)
+	pathFilenameJob = pathJob / 'stateJob.pkl'
+
+	pathFilenameJob.write_bytes(pickle.dumps(stateUniversal))
+	return pathFilenameJob