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

mapFolding/syntheticModules/numbaCount_doTheNeedful.py

@@ -2,6 +2,7 @@ from concurrent.futures import Future as ConcurrentFuture, ProcessPoolExecutor
 from copy import deepcopy
 from mapFolding.theSSOT import Array1DElephino, Array1DFoldsTotal, Array1DLeavesTotal, Array3D, ComputationState, DatatypeElephino, DatatypeFoldsTotal, DatatypeLeavesTotal
 from numba import jit
+from numpy import array, int16, int64
 
 def countInitialize(state: ComputationState) -> ComputationState:
     while state.leaf1ndex > 0:
@@ -22,11 +23,11 @@ def countInitialize(state: ComputationState) -> ComputationState:
                         state.leafConnectee = state.connectionGraph[state.indexDimension, state.leaf1ndex, state.leafBelow[state.leafConnectee]]
                 state.indexDimension += 1
             if not state.dimensionsUnconstrained:
-                indexLeaf = 0
-                while indexLeaf < state.leaf1ndex:
-                    state.gapsWhere[state.gap1ndexCeiling] = indexLeaf
+                state.indexLeaf = 0
+                while state.indexLeaf < state.leaf1ndex:
+                    state.gapsWhere[state.gap1ndexCeiling] = state.indexLeaf
                     state.gap1ndexCeiling += 1
-                    indexLeaf += 1
+                    state.indexLeaf += 1
             state.indexMiniGap = state.gap1ndex
             while state.indexMiniGap < state.gap1ndexCeiling:
                 state.gapsWhere[state.gap1ndex] = state.gapsWhere[state.indexMiniGap]
@@ -139,36 +140,38 @@ def doTheNeedful(state: ComputationState) -> ComputationState:
     state = countInitialize(state)
     if state.taskDivisions > 0:
         dictionaryConcurrency: dict[int, ConcurrentFuture[ComputationState]] = {}
-        with ProcessPoolExecutor(state.concurrencyLimit) as concurrencyManager:
-            for indexSherpa in range(state.taskDivisions):
-                stateParallel = deepcopy(state)
-                stateParallel.taskIndex = indexSherpa
-                mapShape: tuple[DatatypeLeavesTotal, ...] = stateParallel.mapShape
-                leavesTotal: DatatypeLeavesTotal = stateParallel.leavesTotal
-                taskDivisions: DatatypeLeavesTotal = stateParallel.taskDivisions
-                concurrencyLimit: DatatypeElephino = stateParallel.concurrencyLimit
-                connectionGraph: Array3D = stateParallel.connectionGraph
-                dimensionsTotal: DatatypeLeavesTotal = stateParallel.dimensionsTotal
-                countDimensionsGapped: Array1DLeavesTotal = stateParallel.countDimensionsGapped
-                dimensionsUnconstrained: DatatypeLeavesTotal = stateParallel.dimensionsUnconstrained
-                gapRangeStart: Array1DElephino = stateParallel.gapRangeStart
-                gapsWhere: Array1DLeavesTotal = stateParallel.gapsWhere
-                leafAbove: Array1DLeavesTotal = stateParallel.leafAbove
-                leafBelow: Array1DLeavesTotal = stateParallel.leafBelow
-                foldGroups: Array1DFoldsTotal = stateParallel.foldGroups
-                foldsTotal: DatatypeFoldsTotal = stateParallel.foldsTotal
-                gap1ndex: DatatypeLeavesTotal = stateParallel.gap1ndex
-                gap1ndexCeiling: DatatypeElephino = stateParallel.gap1ndexCeiling
-                groupsOfFolds: DatatypeFoldsTotal = stateParallel.groupsOfFolds
-                indexDimension: DatatypeLeavesTotal = stateParallel.indexDimension
-                indexLeaf: DatatypeLeavesTotal = stateParallel.indexLeaf
-                indexMiniGap: DatatypeElephino = stateParallel.indexMiniGap
-                leaf1ndex: DatatypeElephino = stateParallel.leaf1ndex
-                leafConnectee: DatatypeElephino = stateParallel.leafConnectee
-                taskIndex: DatatypeLeavesTotal = stateParallel.taskIndex
+        stateParallel = deepcopy(state)
+        with ProcessPoolExecutor(stateParallel.concurrencyLimit) as concurrencyManager:
+            for indexSherpa in range(stateParallel.taskDivisions):
+                state = deepcopy(stateParallel)
+                state.taskIndex = indexSherpa
+                mapShape: tuple[DatatypeLeavesTotal, ...] = state.mapShape
+                leavesTotal: DatatypeLeavesTotal = state.leavesTotal
+                taskDivisions: DatatypeLeavesTotal = state.taskDivisions
+                concurrencyLimit: DatatypeElephino = state.concurrencyLimit
+                connectionGraph: Array3D = state.connectionGraph
+                dimensionsTotal: DatatypeLeavesTotal = state.dimensionsTotal
+                countDimensionsGapped: Array1DLeavesTotal = state.countDimensionsGapped
+                dimensionsUnconstrained: DatatypeLeavesTotal = state.dimensionsUnconstrained
+                gapRangeStart: Array1DElephino = state.gapRangeStart
+                gapsWhere: Array1DLeavesTotal = state.gapsWhere
+                leafAbove: Array1DLeavesTotal = state.leafAbove
+                leafBelow: Array1DLeavesTotal = state.leafBelow
+                foldGroups: Array1DFoldsTotal = state.foldGroups
+                foldsTotal: DatatypeFoldsTotal = state.foldsTotal
+                gap1ndex: DatatypeLeavesTotal = state.gap1ndex
+                gap1ndexCeiling: DatatypeElephino = state.gap1ndexCeiling
+                groupsOfFolds: DatatypeFoldsTotal = state.groupsOfFolds
+                indexDimension: DatatypeLeavesTotal = state.indexDimension
+                indexLeaf: DatatypeLeavesTotal = state.indexLeaf
+                indexMiniGap: DatatypeElephino = state.indexMiniGap
+                leaf1ndex: DatatypeElephino = state.leaf1ndex
+                leafConnectee: DatatypeElephino = state.leafConnectee
+                taskIndex: DatatypeLeavesTotal = state.taskIndex
                 dictionaryConcurrency[indexSherpa] = concurrencyManager.submit(countParallel, mapShape, leavesTotal, taskDivisions, concurrencyLimit, connectionGraph, dimensionsTotal, countDimensionsGapped, dimensionsUnconstrained, gapRangeStart, gapsWhere, leafAbove, leafBelow, foldGroups, foldsTotal, gap1ndex, gap1ndexCeiling, groupsOfFolds, indexDimension, indexLeaf, indexMiniGap, leaf1ndex, leafConnectee, taskIndex)
-            for indexSherpa in range(state.taskDivisions):
-                state.foldGroups[indexSherpa] = dictionaryConcurrency[indexSherpa].result()
+            for indexSherpa in range(stateParallel.taskDivisions):
+                stateParallel.foldGroups[indexSherpa] = dictionaryConcurrency[indexSherpa].result()
+        state = stateParallel
     else:
         mapShape: tuple[DatatypeLeavesTotal, ...] = state.mapShape
         leavesTotal: DatatypeLeavesTotal = state.leavesTotal

mapFolding/theDao.py

@@ -101,11 +101,11 @@ def initializeVariablesToFindGaps(state: ComputationState) -> ComputationState:
 	return state
 
 def insertUnconstrainedLeaf(state: ComputationState) -> ComputationState:
-	indexLeaf = 0
-	while indexLeaf < state.leaf1ndex:
-		state.gapsWhere[state.gap1ndexCeiling] = indexLeaf
+	state.indexLeaf = 0
+	while state.indexLeaf < state.leaf1ndex:
+		state.gapsWhere[state.gap1ndexCeiling] = state.indexLeaf
 		state.gap1ndexCeiling += 1
-		indexLeaf += 1
+		state.indexLeaf += 1
 	return state
 
 def leafBelowSentinelIs1(state: ComputationState) -> bool:
@@ -227,13 +227,15 @@ def doTheNeedful(state: ComputationState) -> ComputationState:
 	state = countInitialize(state)
 	if state.taskDivisions > 0:
 		dictionaryConcurrency: dict[int, ConcurrentFuture[ComputationState]] = {}
-		with ProcessPoolExecutor(state.concurrencyLimit) as concurrencyManager:
-			for indexSherpa in range(state.taskDivisions):
-				stateParallel = deepcopy(state)
-				stateParallel.taskIndex = indexSherpa
-				dictionaryConcurrency[indexSherpa] = concurrencyManager.submit(countParallel, stateParallel)
-			for indexSherpa in range(state.taskDivisions):
-				state.foldGroups[indexSherpa] = dictionaryConcurrency[indexSherpa].result().foldGroups[indexSherpa]
+		stateParallel = deepcopy(state)
+		with ProcessPoolExecutor(stateParallel.concurrencyLimit) as concurrencyManager:
+			for indexSherpa in range(stateParallel.taskDivisions):
+				state = deepcopy(stateParallel)
+				state.taskIndex = indexSherpa
+				dictionaryConcurrency[indexSherpa] = concurrencyManager.submit(countParallel, state)
+			for indexSherpa in range(stateParallel.taskDivisions):
+				stateParallel.foldGroups[indexSherpa] = dictionaryConcurrency[indexSherpa].result().foldGroups[indexSherpa]
+		state = stateParallel
 	else:
 		state = countSequential(state)
 

mapFolding/theSSOT.py

@@ -19,21 +19,13 @@ to avoid namespace collisions when transforming algorithms.
 from collections.abc import Callable
 from importlib import import_module as importlib_import_module
 from inspect import getfile as inspect_getfile
-from numpy import dtype, int64 as numpy_int64, int16 as numpy_int16, ndarray
+from numpy import dtype, int64 as numpy_int64, int16 as numpy_int16, integer, ndarray
 from pathlib import Path
-from sys import modules as sysModules
 from tomli import load as tomli_load
 from types import ModuleType
-from typing import TypeAlias
+from typing import Any, TypeAlias, TypeVar
 import dataclasses
 
-# Figure out dynamic flow control to synthesized modules https://github.com/hunterhogan/mapFolding/issues/4
-# I _think_, in theSSOT, I have abstracted the flow settings to only these couple of lines:
-packageFlowSynthetic = 'numba'
-# Z0Z_packageFlow = 'algorithm'
-Z0Z_packageFlow = packageFlowSynthetic
-Z0Z_concurrencyPackage = 'multiprocessing'
-
 # =============================================================================
 # The Wrong Way: Evaluate When Packaging
 
@@ -50,84 +42,111 @@ def getPathPackageINSTALLING() -> Path:
 		pathPackage = pathPackage.parent
 	return pathPackage
 
+# =============================================================================
+# The Wrong Way: HARDCODED
+# Figure out dynamic flow control to synthesized modules https://github.com/hunterhogan/mapFolding/issues/4
+
+# from mapFolding.someAssemblyRequired.synthesizeNumbaFlow.theNumbaFlow
+logicalPathModuleDispatcherHARDCODED: str = 'mapFolding.syntheticModules.numbaCount_doTheNeedful'
+callableDispatcherHARDCODED: str = 'doTheNeedful'
+concurrencyPackageHARDCODED = 'multiprocessing'
+
+# =============================================================================
 # The following is an improvement, but it is not the full solution.
 # I hope that the standardized markers, `metadata={'evaluateWhen': 'packaging'}` will help to automate
 # whatever needs to happen so that the following is well implemented.
-@dataclasses.dataclass(frozen=True)
+# @dataclasses.dataclass(frozen=True)
+@dataclasses.dataclass
 class PackageSettings:
-	concurrencyPackage = Z0Z_concurrencyPackage
+
+	logicalPathModuleDispatcher: str | None = None
+	callableDispatcher: str | None = None
+	concurrencyPackage: str |None = None
 	dataclassIdentifier: str = dataclasses.field(default='ComputationState', metadata={'evaluateWhen': 'packaging'})
 	dataclassInstance: str = dataclasses.field(default='state', metadata={'evaluateWhen': 'packaging'})
 	dataclassInstanceTaskDistributionSuffix: str = dataclasses.field(default='Parallel', metadata={'evaluateWhen': 'packaging'})
 	dataclassModule: str = dataclasses.field(default='theSSOT', metadata={'evaluateWhen': 'packaging'})
 	datatypePackage: str = dataclasses.field(default='numpy', metadata={'evaluateWhen': 'packaging'})
-	dispatcherCallable: str = dataclasses.field(default='doTheNeedful', metadata={'evaluateWhen': 'packaging'})
 	fileExtension: str = dataclasses.field(default='.py', metadata={'evaluateWhen': 'installing'})
-	moduleOfSyntheticModules: str = dataclasses.field(default='syntheticModules', metadata={'evaluateWhen': 'packaging'})
 	packageName: str = dataclasses.field(default = packageNamePACKAGING, metadata={'evaluateWhen': 'packaging'})
 	pathPackage: Path = dataclasses.field(default_factory=getPathPackageINSTALLING, init=False, metadata={'evaluateWhen': 'installing'})
 	sourceAlgorithm: str = dataclasses.field(default='theDao', metadata={'evaluateWhen': 'packaging'})
+	sourceCallableDispatcher: str = dataclasses.field(default='doTheNeedful', metadata={'evaluateWhen': 'packaging'})
+	sourceCallableInitialize: str = dataclasses.field(default='countInitialize', metadata={'evaluateWhen': 'packaging'})
+	sourceCallableParallel: str = dataclasses.field(default='countParallel', metadata={'evaluateWhen': 'packaging'})
+	sourceCallableSequential: str = dataclasses.field(default='countSequential', metadata={'evaluateWhen': 'packaging'})
 	sourceConcurrencyManagerIdentifier: str = dataclasses.field(default='submit', metadata={'evaluateWhen': 'packaging'})
 	sourceConcurrencyManagerNamespace: str = dataclasses.field(default='concurrencyManager', metadata={'evaluateWhen': 'packaging'})
-	sourceInitializeCallable: str = dataclasses.field(default='countInitialize', metadata={'evaluateWhen': 'packaging'})
-	sourceParallelCallable: str = dataclasses.field(default='countParallel', metadata={'evaluateWhen': 'packaging'})
-	sourceSequentialCallable: str = dataclasses.field(default='countSequential', metadata={'evaluateWhen': 'packaging'})
-
-	@property # These are not fields, and that annoys me.
-	def dataclassInstanceTaskDistribution(self) -> str:
-		""" Compute the task distribution identifier by concatenating dataclassInstance and dataclassInstanceTaskDistributionSuffix. """
-		# it follows that `metadata={'evaluateWhen': 'packaging'}`
-		return self.dataclassInstance + self.dataclassInstanceTaskDistributionSuffix
-
-	@property # These are not fields, and that annoys me.
-	def logicalPathModuleSourceAlgorithm(self) -> str:
-		""" Compute the logical path module for the source algorithm by joining packageName and sourceAlgorithm. """
-		# it follows that `metadata={'evaluateWhen': 'packaging'}`
-		return '.'.join([self.packageName, self.sourceAlgorithm])
-
-	@property # These are not fields, and that annoys me.
-	def logicalPathModuleDataclass(self) -> str:
-		""" Compute the logical path module for the dataclass by joining packageName and dataclassModule. """
-		# it follows that `metadata={'evaluateWhen': 'packaging'}`
-		return '.'.join([self.packageName, self.dataclassModule])
-
-The = PackageSettings()
+	sourceConcurrencyPackage: str = dataclasses.field(default='multiprocessing', metadata={'evaluateWhen': 'packaging'})
+
+	dataclassInstanceTaskDistribution: str = dataclasses.field(init=False, metadata={'evaluateWhen': 'packaging'})
+	""" During parallel computation, this identifier helps to create deep copies of the dataclass instance. """
+	logicalPathModuleDataclass: str = dataclasses.field(init=False)
+	""" The package.module.name logical path to the dataclass. """
+	logicalPathModuleSourceAlgorithm: str = dataclasses.field(init=False)
+	""" The package.module.name logical path to the source algorithm. """
+
+	@property # This is not a field, and that annoys me.
+	def dispatcher(self) -> Callable[['ComputationState'], 'ComputationState']:
+		""" _The_ callable that connects `countFolds` to the logic that does the work."""
+		logicalPath: str = self.logicalPathModuleDispatcher or self.logicalPathModuleSourceAlgorithm
+		identifier: str = self.callableDispatcher or self.sourceCallableDispatcher
+		moduleImported: ModuleType = importlib_import_module(logicalPath)
+		return getattr(moduleImported, identifier)
+
+	def __post_init__(self) -> None:
+		self.dataclassInstanceTaskDistribution = self.dataclassInstance + self.dataclassInstanceTaskDistributionSuffix
+
+		self.logicalPathModuleDataclass = '.'.join([self.packageName, self.dataclassModule])
+		self.logicalPathModuleSourceAlgorithm = '.'.join([self.packageName, self.sourceAlgorithm])
 
+The = PackageSettings(logicalPathModuleDispatcher=logicalPathModuleDispatcherHARDCODED, callableDispatcher=callableDispatcherHARDCODED, concurrencyPackage=concurrencyPackageHARDCODED)
+
+# To remove this function, I need to learn how to change "conftest.py" to patch this.
+def getPackageDispatcher() -> Callable[['ComputationState'], 'ComputationState']:
+	"""Get the dispatcher callable for the package.
+
+	This function retrieves the dispatcher callable for the package based on the
+	logical path module and callable dispatcher defined in the PackageSettings.
+	"""
+	return The.dispatcher
 # =============================================================================
 # Flexible Data Structure System Needs Enhanced Paradigm https://github.com/hunterhogan/mapFolding/issues/9
+# Efficient translation of Python scalar types to Numba types https://github.com/hunterhogan/mapFolding/issues/8
+
+numpyIntegerType = TypeVar('numpyIntegerType', bound=integer[Any], covariant=True)
 
 DatatypeLeavesTotal: TypeAlias = int
-# this would be uint8, but mapShape (2,2,2,2, 2,2,2,2) has 256 leaves, so generic containers must accommodate at least 256 leaves
-numpyLeavesTotal: TypeAlias = numpy_int16
+NumPyLeavesTotal: TypeAlias = numpy_int16 # this would be uint8, but mapShape (2,2,2,2, 2,2,2,2) has 256 leaves, so generic containers must accommodate at least 256 leaves
 
 DatatypeElephino: TypeAlias = int
-numpyElephino: TypeAlias = numpy_int16
+NumPyElephino: TypeAlias = numpy_int16
 
 DatatypeFoldsTotal: TypeAlias = int
-numpyFoldsTotal: TypeAlias = numpy_int64
+NumPyFoldsTotal: TypeAlias = numpy_int64
 
-Array3D: TypeAlias = ndarray[tuple[int, int, int], dtype[numpyLeavesTotal]]
-Array1DLeavesTotal: TypeAlias = ndarray[tuple[int], dtype[numpyLeavesTotal]]
-Array1DElephino: TypeAlias = ndarray[tuple[int], dtype[numpyElephino]]
-Array1DFoldsTotal: TypeAlias = ndarray[tuple[int], dtype[numpyFoldsTotal]]
+Array3D: TypeAlias = ndarray[tuple[int, int, int], dtype[NumPyLeavesTotal]]
+Array1DLeavesTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyLeavesTotal]]
+Array1DElephino: TypeAlias = ndarray[tuple[int], dtype[NumPyElephino]]
+Array1DFoldsTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyFoldsTotal]]
 
 @dataclasses.dataclass
 class ComputationState:
-	mapShape: tuple[DatatypeLeavesTotal, ...]
+	mapShape: tuple[DatatypeLeavesTotal, ...] = dataclasses.field(init=True, metadata={'elementConstructor': 'DatatypeLeavesTotal'}) # NOTE Python is anti-DRY, again, `DatatypeLeavesTotal` needs to match the type
 	leavesTotal: DatatypeLeavesTotal
 	taskDivisions: DatatypeLeavesTotal
 	concurrencyLimit: DatatypeElephino
 
-	connectionGraph: Array3D = dataclasses.field(init=False)
+	connectionGraph: Array3D = dataclasses.field(init=False, metadata={'dtype': Array3D.__args__[1].__args__[0]}) # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
 	dimensionsTotal: DatatypeLeavesTotal = dataclasses.field(init=False)
 
-	countDimensionsGapped: Array1DLeavesTotal = dataclasses.field(default=None, init=True) # type: ignore[arg-type, reportAssignmentType]
+	countDimensionsGapped: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # type: ignore[arg-type, reportAssignmentType]
 	dimensionsUnconstrained: DatatypeLeavesTotal = dataclasses.field(default=None, init=True) # type: ignore[assignment, reportAssignmentType]
-	gapRangeStart: Array1DElephino = dataclasses.field(default=None, init=True) # type: ignore[arg-type, reportAssignmentType]
-	gapsWhere: Array1DLeavesTotal = dataclasses.field(default=None, init=True) # type: ignore[arg-type, reportAssignmentType]
-	leafAbove: Array1DLeavesTotal = dataclasses.field(default=None, init=True) # type: ignore[arg-type, reportAssignmentType]
-	leafBelow: Array1DLeavesTotal = dataclasses.field(default=None, init=True) # type: ignore[arg-type, reportAssignmentType]
-	foldGroups: Array1DFoldsTotal = dataclasses.field(default=None, init=True) # type: ignore[arg-type, reportAssignmentType]
+	gapRangeStart: Array1DElephino = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DElephino.__args__[1].__args__[0]}) # type: ignore[arg-type, reportAssignmentType]
+	gapsWhere: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # type: ignore[arg-type, reportAssignmentType]
+	leafAbove: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # type: ignore[arg-type, reportAssignmentType]
+	leafBelow: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # type: ignore[arg-type, reportAssignmentType]
+	foldGroups: Array1DFoldsTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DFoldsTotal.__args__[1].__args__[0]}) # type: ignore[arg-type, reportAssignmentType]
 
 	foldsTotal: DatatypeFoldsTotal = DatatypeFoldsTotal(0)
 	gap1ndex: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
@@ -139,95 +158,31 @@ class ComputationState:
 	leaf1ndex: DatatypeElephino = DatatypeElephino(1)
 	leafConnectee: DatatypeElephino = DatatypeElephino(0)
 	taskIndex: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
-	# Efficient translation of Python scalar types to Numba types https://github.com/hunterhogan/mapFolding/issues/8
 
 	def __post_init__(self) -> None:
-		from mapFolding.beDRY import makeConnectionGraph, makeDataContainer
+		from mapFolding.beDRY import getConnectionGraph, makeDataContainer
 		self.dimensionsTotal = DatatypeLeavesTotal(len(self.mapShape))
-		self.connectionGraph = makeConnectionGraph(self.mapShape, self.leavesTotal, numpyLeavesTotal)
+		leavesTotalAsInt = int(self.leavesTotal)
+		self.connectionGraph = getConnectionGraph(self.mapShape, leavesTotalAsInt, self.__dataclass_fields__['connectionGraph'].metadata['dtype'])
 
-		if self.dimensionsUnconstrained is None: # pyright: ignore[reportUnnecessaryComparison]
+		if self.dimensionsUnconstrained is None: # type: ignore
 			self.dimensionsUnconstrained = DatatypeLeavesTotal(int(self.dimensionsTotal))
 
-		if self.foldGroups is None:
-			self.foldGroups = makeDataContainer(max(2, int(self.taskDivisions) + 1), numpyFoldsTotal)
+		if self.foldGroups is None: # type: ignore
+			self.foldGroups = makeDataContainer(max(2, int(self.taskDivisions) + 1), self.__dataclass_fields__['foldGroups'].metadata['dtype'])
 			self.foldGroups[-1] = self.leavesTotal
 
-		leavesTotalAsInt = int(self.leavesTotal)
+		if self.gapsWhere is None: self.gapsWhere = makeDataContainer(leavesTotalAsInt * leavesTotalAsInt + 1, self.__dataclass_fields__['gapsWhere'].metadata['dtype']) # type: ignore
 
-		if self.countDimensionsGapped is None:
-			self.countDimensionsGapped = makeDataContainer(leavesTotalAsInt + 1, numpyLeavesTotal)
-		if self.gapRangeStart is None:
-			self.gapRangeStart = makeDataContainer(leavesTotalAsInt + 1, numpyElephino)
-		if self.gapsWhere is None:
-			self.gapsWhere = makeDataContainer(leavesTotalAsInt * leavesTotalAsInt + 1, numpyLeavesTotal)
-		if self.leafAbove is None:
-			self.leafAbove = makeDataContainer(leavesTotalAsInt + 1, numpyLeavesTotal)
-		if self.leafBelow is None:
-			self.leafBelow = makeDataContainer(leavesTotalAsInt + 1, numpyLeavesTotal)
+		if self.countDimensionsGapped is None: self.countDimensionsGapped = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['countDimensionsGapped'].metadata['dtype']) # type: ignore
+		if self.gapRangeStart is None: self.gapRangeStart = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['gapRangeStart'].metadata['dtype']) # type: ignore
+		if self.leafAbove is None: self.leafAbove = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafAbove'].metadata['dtype']) # type: ignore
+		if self.leafBelow is None: self.leafBelow = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafBelow'].metadata['dtype']) # type: ignore
 
 	def getFoldsTotal(self) -> None:
 		self.foldsTotal = DatatypeFoldsTotal(self.foldGroups[0:-1].sum() * self.leavesTotal)
 
-# =============================================================================
-
-# TODO learn how to see this from the user's perspective
-def getPathJobRootDEFAULT() -> Path:
-	if 'google.colab' in sysModules:
-		pathJobDEFAULT: Path = Path("/content/drive/MyDrive") / "jobs"
-	else:
-		pathJobDEFAULT = The.pathPackage / "jobs"
-	return pathJobDEFAULT
-
 # =============================================================================
 # The coping way.
 
 class raiseIfNoneGitHubIssueNumber3(Exception): pass
-
-# =============================================================================
-# THIS IS A STUPID SYSTEM BUT I CAN'T FIGURE OUT AN IMPROVEMENT
-# NOTE This section for _default_ values probably has value
-# https://github.com/hunterhogan/mapFolding/issues/4
-theFormatStrModuleSynthetic = "{packageFlow}Count"
-theFormatStrModuleForCallableSynthetic = theFormatStrModuleSynthetic + "_{callableTarget}"
-
-theLogicalPathModuleDispatcher: str = The.logicalPathModuleSourceAlgorithm
-
-theModuleDispatcherSynthetic: str = theFormatStrModuleForCallableSynthetic.format(packageFlow=packageFlowSynthetic, callableTarget=The.dispatcherCallable)
-theLogicalPathModuleDispatcherSynthetic: str = '.'.join([The.packageName, The.moduleOfSyntheticModules, theModuleDispatcherSynthetic])
-
-if Z0Z_packageFlow == packageFlowSynthetic: # pyright: ignore [reportUnnecessaryComparison]
-	# NOTE this as a default value _might_ have value
-	theLogicalPathModuleDispatcher = theLogicalPathModuleDispatcherSynthetic
-
-# dynamically set the return type https://github.com/hunterhogan/mapFolding/issues/5
-def getPackageDispatcher() -> Callable[[ComputationState], ComputationState]:
-	# NOTE but this part, if the package flow is synthetic, probably needs to be delegated
-	# to the authority for creating _that_ synthetic flow.
-
-	moduleImported: ModuleType = importlib_import_module(theLogicalPathModuleDispatcher)
-	dispatcherCallable = getattr(moduleImported, The.dispatcherCallable)
-	return dispatcherCallable
-
-"""Technical concepts I am likely using and likely want to use more effectively:
-- Configuration Registry
-- Write-Once, Read-Many (WORM) / Immutable Initialization
-- Lazy Initialization
-- Separate configuration from business logic
-
-----
-theSSOT and yourSSOT
-
-----
-delay realization/instantiation until a concrete value is desired
-moment of truth: when the value is needed, not when the value is defined
-
-----
-2025 March 11
-Note to self: fundamental concept in Python:
-Identifiers: scope and resolution, LEGB (Local, Enclosing, Global, Builtin)
-- Local: Inside the function
-- Enclosing: Inside enclosing functions
-- Global: At the uppermost level
-- Builtin: Python's built-in names
-"""

mapFolding/toolboxFilesystem.py

@@ -0,0 +1,219 @@
+"""
+Filesystem utilities for managing map folding computation results.
+
+This module provides functions for standardized handling of files related to the mapFolding
+package, with a focus on saving, retrieving, and naming computation results. It implements
+consistent naming conventions and path resolution strategies to ensure that:
+
+1. Computation results are stored in a predictable location.
+2. Filenames follow a consistent pattern based on map dimensions.
+3. Results can be reliably retrieved for future reference.
+4. The system handles file operations safely with appropriate error handling.
+
+The module serves as the standardized interface between the computational components
+of the package and the filesystem, abstracting away the details of file operations
+and path management. It provides robust fallback mechanisms to preserve computation
+results even in the face of filesystem errors, which is critical for long-running
+computations that may take days to complete.
+
+The functions here adhere to a consistent approach to path handling:
+- Cross-platform compatibility through the use of `pathlib`.
+- Default locations determined intelligently based on the runtime environment.
+- Progressive fallback strategies for saving critical computation results.
+- Preemptive filesystem validation to detect issues before computation begins.
+"""
+from mapFolding.theSSOT import The
+from os import PathLike
+from pathlib import Path, PurePath
+from sys import modules as sysModules
+import os
+import platformdirs
+
+def getFilenameFoldsTotal(mapShape: tuple[int, ...]) -> str:
+	"""
+	Create a standardized filename for a computed `foldsTotal` value.
+
+	This function generates a consistent, filesystem-safe filename based on map dimensions.
+	Standardizing filenames ensures that results can be reliably stored and retrieved,
+	avoiding potential filesystem incompatibilities or Python naming restrictions.
+
+	Parameters:
+		mapShape: A sequence of integers representing the dimensions of the map.
+
+	Returns:
+		filenameFoldsTotal: A filename string in format 'pMxN.foldsTotal' where M,N are sorted dimensions.
+
+	Notes:
+		The filename format ensures:
+		- No spaces in the filename
+		- Safe filesystem characters
+		- Unique extension (.foldsTotal)
+		- Python-safe strings (no starting with numbers, no reserved words)
+		- The 'p' prefix comes from Lunnan's original code.
+	"""
+	return 'p' + 'x'.join(str(dimension) for dimension in sorted(mapShape)) + '.foldsTotal'
+
+def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal: PathLike[str] | PurePath | None = None) -> Path:
+	"""
+	Get a standardized path and filename for the computed `foldsTotal` value.
+
+	This function resolves paths for storing computation results, handling different
+	input types including directories, absolute paths, or relative paths. It ensures
+	that all parent directories exist in the resulting path.
+
+	Parameters:
+		mapShape: List of dimensions for the map folding problem.
+		pathLikeWriteFoldsTotal (getPathJobRootDEFAULT): Path, filename, or relative path and filename.
+			If None, uses default path. If a directory, appends standardized filename.
+
+	Returns:
+		pathFilenameFoldsTotal: Absolute path and filename for storing the `foldsTotal` value.
+
+	Notes:
+		The function creates any necessary directories in the path if they don't exist.
+	"""
+
+	if pathLikeWriteFoldsTotal is None:
+		pathFilenameFoldsTotal = getPathRootJobDEFAULT() / getFilenameFoldsTotal(mapShape)
+	else:
+		pathLikeSherpa = Path(pathLikeWriteFoldsTotal)
+		if pathLikeSherpa.is_dir():
+			pathFilenameFoldsTotal = pathLikeSherpa / getFilenameFoldsTotal(mapShape)
+		elif pathLikeSherpa.is_file() and pathLikeSherpa.is_absolute():
+			pathFilenameFoldsTotal = pathLikeSherpa
+		else:
+			pathFilenameFoldsTotal = getPathRootJobDEFAULT() / pathLikeSherpa
+
+	pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
+	return pathFilenameFoldsTotal
+
+def getPathRootJobDEFAULT() -> Path:
+	"""
+	Get the default root directory for map folding computation jobs.
+
+	This function determines the appropriate default directory for storing computation
+	results based on the current runtime environment. It uses platform-specific
+	directories for normal environments and adapts to special environments like
+	Google Colab.
+
+	Returns:
+		pathJobDEFAULT: Path to the default directory for storing computation results
+
+	Notes:
+		- For standard environments, uses `platformdirs` to find appropriate user data directory.
+		- For Google Colab, uses a specific path in Google Drive.
+		- Creates the directory if it doesn't exist.
+	"""
+	pathJobDEFAULT = Path(platformdirs.user_data_dir(appname=The.packageName, appauthor=False, ensure_exists=True))
+	if 'google.colab' in sysModules:
+		pathJobDEFAULT = Path("/content/drive/MyDrive") / The.packageName
+	pathJobDEFAULT.mkdir(parents=True, exist_ok=True)
+	return pathJobDEFAULT
+
+def _saveFoldsTotal(pathFilename: PathLike[str] | PurePath, foldsTotal: int) -> None:
+	"""
+	Internal helper function to save a `foldsTotal` value to a file.
+
+	This is a low-level function used by the public `saveFoldsTotal` function.
+	It handles the basic file operation without extensive error handling.
+
+	Parameters:
+		pathFilename: Path where the `foldsTotal` value should be saved
+		foldsTotal: The integer value to save
+	"""
+	pathFilenameFoldsTotal = Path(pathFilename)
+	pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
+	pathFilenameFoldsTotal.write_text(str(foldsTotal))
+
+def saveFoldsTotal(pathFilename: PathLike[str] | PurePath, foldsTotal: int) -> None:
+	"""
+	Save `foldsTotal` value to disk with multiple fallback mechanisms.
+
+	This function attempts to save the computed `foldsTotal` value to the specified
+	location, with backup strategies in case the primary save attempt fails.
+	The robustness is critical since these computations may take days to complete.
+
+	Parameters:
+		pathFilename: Target save location for the `foldsTotal` value
+		foldsTotal: The computed value to save
+
+	Notes:
+		If the primary save fails, the function will attempt alternative save methods:
+		1. Print the value prominently to `stdout`.
+		2. Create a fallback file in the current working directory.
+		3. As a last resort, simply print the value.
+	"""
+	try:
+		_saveFoldsTotal(pathFilename, foldsTotal)
+	except Exception as ERRORmessage:
+		try:
+			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal = }\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+			print(ERRORmessage)
+			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal = }\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+			randomnessPlanB = (int(str(foldsTotal).strip()[-1]) + 1) * ['YO_']
+			filenameInfixUnique = ''.join(randomnessPlanB)
+			pathFilenamePlanB = os.path.join(os.getcwd(), 'foldsTotal' + filenameInfixUnique + '.txt')
+			writeStreamFallback = open(pathFilenamePlanB, 'w')
+			writeStreamFallback.write(str(foldsTotal))
+			writeStreamFallback.close()
+			print(str(pathFilenamePlanB))
+		except Exception:
+			print(foldsTotal)
+	return None
+
+def saveFoldsTotalFAILearly(pathFilename: PathLike[str] | PurePath) -> None:
+	"""
+	Preemptively test file write capabilities before beginning computation.
+
+	This function performs validation checks on the target file location before
+	a potentially long-running computation begins. It tests several critical
+	aspects of filesystem functionality to ensure results can be saved:
+
+	1. Checks if the file already exists to prevent accidental overwrites.
+	2. Verifies that parent directories exist.
+	3. Tests if the system can write a test value to the file.
+	4. Confirms that the written value can be read back correctly.
+
+	Parameters:
+		pathFilename: The path and filename where computation results will be saved.
+
+	Raises:
+		FileExistsError: If the target file already exists.
+		FileNotFoundError: If parent directories don't exist or if write tests fail.
+
+	Notes:
+		This function helps prevent a situation where a computation runs for
+		hours or days only to discover at the end that results cannot be saved.
+	"""
+	if Path(pathFilename).exists():
+		raise FileExistsError(f"`{pathFilename = }` exists: a battle of overwriting might cause tears.")
+	if not Path(pathFilename).parent.exists():
+		raise FileNotFoundError(f"I received `{pathFilename = }` 0.000139 seconds ago from a function that promised it created the parent directory, but the parent directory does not exist. Fix that now, so your computation doesn't get deleted later. And be compassionate to others.")
+	foldsTotal = 149302889205120
+	_saveFoldsTotal(pathFilename, foldsTotal)
+	if not Path(pathFilename).exists():
+		raise FileNotFoundError(f"I just wrote a test file to `{pathFilename = }`, but it does not exist. Fix that now, so your computation doesn't get deleted later. And continually improve your empathy skills.")
+	foldsTotalRead = int(Path(pathFilename).read_text())
+	if foldsTotalRead != foldsTotal:
+		raise FileNotFoundError(f"I wrote a test file to `{pathFilename = }` with contents of `{str(foldsTotal) = }`, but I read `{foldsTotalRead = }` from the file. Python says the values are not equal. Fix that now, so your computation doesn't get corrupted later. And be pro-social.")
+
+def writeStringToHere(this: str, pathFilename: PathLike[str] | PurePath) -> None:
+	"""
+	Write a string to a file, creating parent directories if needed.
+
+	This utility function provides a consistent interface for writing string content
+	to files across the package. It handles path creation and ensures proper
+	string conversion.
+
+	Parameters:
+		this: The string content to write to the file.
+		pathFilename: The target file path where the string should be written.
+
+	Notes:
+		This function creates all parent directories in the path if they don't exist,
+		making it safe to use with newly created directory structures.
+	"""
+	pathFilename = Path(pathFilename)
+	pathFilename.parent.mkdir(parents=True, exist_ok=True)
+	pathFilename.write_text(str(this))
+	return None