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

mapFolding/someAssemblyRequired/synthesizeNumbaJob.py

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

mapFolding/someAssemblyRequired/transformDataStructures.py

@@ -20,149 +20,216 @@ While developed for transforming map folding computation state objects, the util
 designed to be applicable to various data structure transformation scenarios.
 """
 
-from collections.abc import Sequence
-from importlib import import_module as importlib_import_module
-from inspect import getsource as inspect_getsource
-from mapFolding.beDRY import outfitCountFolds, validateListDimensions
+from collections.abc import Callable
+from copy import deepcopy
+from mapFolding.beDRY import outfitCountFolds
 from mapFolding.filesystem import getPathFilenameFoldsTotal
 from mapFolding.someAssemblyRequired import (
 	ast_Identifier,
+	be,
 	extractClassDef,
 	ifThis,
-	LedgerOfImports,
+	ImaAnnotationType,
+	importLogicalPath2Callable,
 	Make,
-	NodeCollector,
-	strDotStrCuzPyStoopid,
+	NodeTourist,
+	parseLogicalPath2astModule,
+	str_nameDOTname,
 	Then,
-	Z0Z_executeActionUnlessDescendantMatches,
+	又,
 )
-from mapFolding.theSSOT import ComputationState, The
-from pathlib import Path
-from types import ModuleType
+from mapFolding.someAssemblyRequired._toolboxContainers import LedgerOfImports
+from mapFolding.theSSOT import ComputationState, raiseIfNoneGitHubIssueNumber3, The
+from os import PathLike
+from pathlib import Path, PurePath
 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'
+# Create dummy AST elements for use as defaults
+dummyAssign = Make.Assign([Make.Name("dummyTarget")], Make.Constant(None))
+dummySubscript = Make.Subscript(Make.Name("dummy"), Make.Name("slice"))
+dummyTuple = Make.Tuple([Make.Name("dummyElement")])
 
 @dataclasses.dataclass
 class ShatteredDataclass:
-	astAssignDataclassRepack: ast.Assign
-	astSubscriptPrimitiveTupleAnnotations4FunctionDef_returns: ast.Subscript
-	astTuple4AssignTargetsToFragments: ast.Tuple
-	countingVariableAnnotation: ast.expr
+	countingVariableAnnotation: ImaAnnotationType
+	"""Type annotation for the counting variable extracted from the dataclass."""
 	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:
+	"""AST name node representing the counting variable identifier."""
+	field2AnnAssign: dict[ast_Identifier, ast.AnnAssign] = dataclasses.field(default_factory=dict)
+	"""Maps field names to their corresponding AST call expressions."""
+	Z0Z_field2AnnAssign: dict[ast_Identifier, tuple[ast.AnnAssign, str]] = dataclasses.field(default_factory=dict)
+	fragments4AssignmentOrParameters: ast.Tuple = dummyTuple
+	"""AST tuple used as target for assignment to capture returned fragments."""
+	ledger: LedgerOfImports = dataclasses.field(default_factory=LedgerOfImports)
+	"""Import records for the dataclass and its constituent parts."""
+	list_argAnnotated4ArgumentsSpecification: list[ast.arg] = dataclasses.field(default_factory=list)
+	"""Function argument nodes with annotations for parameter specification."""
+	list_keyword_field__field4init: list[ast.keyword] = dataclasses.field(default_factory=list)
+	"""Keyword arguments for dataclass initialization with field=field format."""
+	listAnnotations: list[ImaAnnotationType] = dataclasses.field(default_factory=list)
+	"""Type annotations for each dataclass field."""
+	listName4Parameters: list[ast.Name] = dataclasses.field(default_factory=list)
+	"""Name nodes for each dataclass field used as function parameters."""
+	listUnpack: list[ast.AnnAssign] = dataclasses.field(default_factory=list)
+	"""Annotated assignment statements to extract fields from dataclass."""
+	map_stateDOTfield2Name: dict[ast.expr, ast.Name] = dataclasses.field(default_factory=dict)
+	"""Maps AST expressions to Name nodes for find-replace operations."""
+	repack: ast.Assign = dummyAssign
+	"""AST assignment statement that reconstructs the original dataclass instance."""
+	signatureReturnAnnotation: ast.Subscript = dummySubscript
+	"""tuple-based return type annotation for function definitions."""
+
+@dataclasses.dataclass
+class DeReConstructField2ast:
+	dataclassesDOTdataclassLogicalPathModule: dataclasses.InitVar[str_nameDOTname]
+	dataclassClassDef: dataclasses.InitVar[ast.ClassDef]
+	dataclassesDOTdataclassInstance_Identifier: dataclasses.InitVar[ast_Identifier]
+	field: dataclasses.InitVar[dataclasses.Field[Any]]
+
+	ledger: LedgerOfImports = dataclasses.field(default_factory=LedgerOfImports)
+
+	name: ast_Identifier = dataclasses.field(init=False)
+	typeBuffalo: type[Any] | str | Any = dataclasses.field(init=False)
+	default: Any | None = dataclasses.field(init=False)
+	default_factory: Callable[..., Any] | None = dataclasses.field(init=False)
+	repr: bool = dataclasses.field(init=False)
+	hash: bool | None = dataclasses.field(init=False)
+	init: bool = dataclasses.field(init=False)
+	compare: bool = dataclasses.field(init=False)
+	metadata: dict[Any, Any] = dataclasses.field(init=False)
+	kw_only: bool = dataclasses.field(init=False)
+
+	astName: ast.Name = dataclasses.field(init=False)
+	ast_keyword_field__field: ast.keyword = dataclasses.field(init=False)
+	ast_nameDOTname: ast.Attribute = dataclasses.field(init=False)
+	astAnnotation: ImaAnnotationType = dataclasses.field(init=False)
+	ast_argAnnotated: ast.arg = dataclasses.field(init=False)
+	astAnnAssignConstructor: ast.AnnAssign = dataclasses.field(init=False)
+	Z0Z_hack: tuple[ast.AnnAssign, str] = dataclasses.field(init=False)
+
+	def __post_init__(self, dataclassesDOTdataclassLogicalPathModule: str_nameDOTname, dataclassClassDef: ast.ClassDef, dataclassesDOTdataclassInstance_Identifier: ast_Identifier, field: dataclasses.Field[Any]) -> None:
+		self.compare = field.compare
+		self.default = field.default if field.default is not dataclasses.MISSING else None
+		self.default_factory = field.default_factory if field.default_factory is not dataclasses.MISSING else None
+		self.hash = field.hash
+		self.init = field.init
+		self.kw_only = field.kw_only if field.kw_only is not dataclasses.MISSING else False
+		self.metadata = dict(field.metadata)
+		self.name = field.name
+		self.repr = field.repr
+		self.typeBuffalo = field.type
+
+		self.astName = Make.Name(self.name)
+		self.ast_keyword_field__field = Make.keyword(self.name, self.astName)
+		self.ast_nameDOTname = Make.Attribute(Make.Name(dataclassesDOTdataclassInstance_Identifier), self.name)
+
+		sherpa = NodeTourist(ifThis.isAnnAssign_targetIs(ifThis.isName_Identifier(self.name)), 又.annotation(Then.getIt)).captureLastMatch(dataclassClassDef)
+		if sherpa is None: raise raiseIfNoneGitHubIssueNumber3
+		else: self.astAnnotation = sherpa
+
+		self.ast_argAnnotated = Make.arg(self.name, self.astAnnotation)
+
+		dtype = self.metadata.get('dtype', None)
+		if dtype:
+			constructor = 'array'
+			self.astAnnAssignConstructor = Make.AnnAssign(self.astName, self.astAnnotation, Make.Call(Make.Name(constructor), list_astKeywords=[Make.keyword('dtype', Make.Name(dtype.__name__))]))
+			self.ledger.addImportFrom_asStr('numpy', constructor)
+			self.ledger.addImportFrom_asStr('numpy', dtype.__name__)
+			self.Z0Z_hack = (self.astAnnAssignConstructor, 'array')
+		elif be.Name(self.astAnnotation):
+			self.astAnnAssignConstructor = Make.AnnAssign(self.astName, self.astAnnotation, Make.Call(self.astAnnotation, [Make.Constant(-1)]))
+			self.ledger.addImportFrom_asStr(dataclassesDOTdataclassLogicalPathModule, self.astAnnotation.id)
+			self.Z0Z_hack = (self.astAnnAssignConstructor, 'scalar')
+		elif be.Subscript(self.astAnnotation):
+			elementConstructor: ast_Identifier = self.metadata['elementConstructor']
+			self.ledger.addImportFrom_asStr(dataclassesDOTdataclassLogicalPathModule, elementConstructor)
+			takeTheTuple: ast.Tuple = deepcopy(self.astAnnotation.slice)
+			self.astAnnAssignConstructor = Make.AnnAssign(self.astName, self.astAnnotation, takeTheTuple)
+			self.Z0Z_hack = (self.astAnnAssignConstructor, elementConstructor)
+		if be.Name(self.astAnnotation):
+			self.ledger.addImportFrom_asStr(dataclassesDOTdataclassLogicalPathModule, self.astAnnotation.id) # pyright: ignore [reportUnknownArgumentType, reportUnknownMemberType, reportIJustCalledATypeGuardMethod_WTF]
+
+def shatter_dataclassesDOTdataclass(logicalPathModule: str_nameDOTname, 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.
 	"""
-	# TODO learn whether dataclasses.make_dataclass would be useful to transform the target dataclass into the `ShatteredDataclass`
-
-	module: ast.Module = ast.parse(inspect_getsource(importlib_import_module(logicalPathModule)))
-	astName_dataclassesDOTdataclass = Make.astName(dataclass_Identifier)
-
-	dataclass = extractClassDef(module, dataclass_Identifier)
-	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)
+	Official_fieldOrder: list[ast_Identifier] = []
+	dictionaryDeReConstruction: dict[ast_Identifier, DeReConstructField2ast] = {}
+
+	dataclassClassDef = extractClassDef(parseLogicalPath2astModule(logicalPathModule), dataclass_Identifier)
+	if not isinstance(dataclassClassDef, ast.ClassDef): raise ValueError(f"I could not find {dataclass_Identifier=} in {logicalPathModule=}.")
+
+	countingVariable = None
+	for aField in dataclasses.fields(importLogicalPath2Callable(logicalPathModule, dataclass_Identifier)): # pyright: ignore [reportArgumentType]
+		Official_fieldOrder.append(aField.name)
+		dictionaryDeReConstruction[aField.name] = DeReConstructField2ast(logicalPathModule, dataclassClassDef, instance_Identifier, aField)
+		if aField.metadata.get('theCountingIdentifier', False):
+			countingVariable = dictionaryDeReConstruction[aField.name].name
+
+	if countingVariable is None:
+		raise ValueError(f"I could not find the counting variable in {dataclass_Identifier=} in {logicalPathModule=}.")
 
 	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
+		countingVariableAnnotation=dictionaryDeReConstruction[countingVariable].astAnnotation,
+		countingVariableName=dictionaryDeReConstruction[countingVariable].astName,
+		field2AnnAssign={dictionaryDeReConstruction[field].name: dictionaryDeReConstruction[field].astAnnAssignConstructor for field in Official_fieldOrder},
+		Z0Z_field2AnnAssign={dictionaryDeReConstruction[field].name: dictionaryDeReConstruction[field].Z0Z_hack for field in Official_fieldOrder},
+		list_argAnnotated4ArgumentsSpecification=[dictionaryDeReConstruction[field].ast_argAnnotated for field in Official_fieldOrder],
+		list_keyword_field__field4init=[dictionaryDeReConstruction[field].ast_keyword_field__field for field in Official_fieldOrder if dictionaryDeReConstruction[field].init],
+		listAnnotations=[dictionaryDeReConstruction[field].astAnnotation for field in Official_fieldOrder],
+		listName4Parameters=[dictionaryDeReConstruction[field].astName for field in Official_fieldOrder],
+		listUnpack=[Make.AnnAssign(dictionaryDeReConstruction[field].astName, dictionaryDeReConstruction[field].astAnnotation, dictionaryDeReConstruction[field].ast_nameDOTname) for field in Official_fieldOrder],
+		map_stateDOTfield2Name={dictionaryDeReConstruction[field].ast_nameDOTname: dictionaryDeReConstruction[field].astName for field in Official_fieldOrder},
+		)
+	shatteredDataclass.fragments4AssignmentOrParameters = Make.Tuple(shatteredDataclass.listName4Parameters, ast.Store())
+	shatteredDataclass.repack = Make.Assign(listTargets=[Make.Name(instance_Identifier)], value=Make.Call(Make.Name(dataclass_Identifier), list_astKeywords=shatteredDataclass.list_keyword_field__field4init))
+	shatteredDataclass.signatureReturnAnnotation = Make.Subscript(Make.Name('tuple'), Make.Tuple(shatteredDataclass.listAnnotations))
+
+	shatteredDataclass.ledger.update(*(dictionaryDeReConstruction[field].ledger for field in Official_fieldOrder))
+	shatteredDataclass.ledger.addImportFrom_asStr(logicalPathModule, dataclass_Identifier)
 
-def getSourceAlgorithmVESTIGIAL() -> ModuleType:
-	moduleImported: ModuleType = importlib_import_module(The.logicalPathModuleSourceAlgorithm)
-	return moduleImported
+	return shatteredDataclass
 
 @overload
-def makeStateJobOUTDATED(listDimensions: Sequence[int], *, writeJob: Literal[True], **keywordArguments: Any) -> Path: ...
+def makeInitializedComputationState(mapShape: tuple[int, ...], writeJob: Literal[True], *,  pathFilename: PathLike[str] | PurePath | None = None, **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:
+def makeInitializedComputationState(mapShape: tuple[int, ...], writeJob: Literal[False] = False, **keywordArguments: Any) -> ComputationState: ...
+def makeInitializedComputationState(mapShape: tuple[int, ...], writeJob: bool = False, *,  pathFilename: PathLike[str] | PurePath | None = None, **keywordArguments: Any) -> ComputationState | Path:
 	"""
-	Creates a computation state job for map folding calculations and optionally saves it to disk.
+	Initializes a computation state 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.
+	This function initializes a computation state using the source algorithm.
 
-	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.
+	Hint: If you want an uninitialized state, call `outfitCountFolds` directly.
 
+	Parameters:
+		mapShape: List of integers representing the dimensions of the map to be folded.
+		writeJob (False): Whether to save the state to disk.
+		pathFilename (getPathFilenameFoldsTotal.pkl): The path and filename to save the state. If None, uses a default path.
+		**keywordArguments: computationDivisions:int|str|None=None,concurrencyLimit:int=1.
 	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 = getSourceAlgorithmVESTIGIAL()
-	# TODO `countInitialize` is hardcoded
-	stateUniversal = moduleSource.countInitialize(stateUniversal)
+	initializeState = importLogicalPath2Callable(The.logicalPathModuleSourceAlgorithm, The.sourceCallableInitialize)
+	stateUniversal = initializeState(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'
+	if pathFilename:
+		pathFilenameJob = Path(pathFilename)
+		pathFilenameJob.parent.mkdir(parents=True, exist_ok=True)
+	else:
+		pathFilenameJob = getPathFilenameFoldsTotal(stateUniversal.mapShape).with_suffix('.pkl')
 
 	pathFilenameJob.write_bytes(pickle.dumps(stateUniversal))
 	return pathFilenameJob