mapFolding 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

mapFolding/__init__.py

@@ -1,107 +1,9 @@
-from collections import defaultdict
-from types import ModuleType
-import importlib
+from mapFolding.basecamp import countFolds
+from mapFolding.oeis import clearOEIScache, getOEISids, OEIS_for_n
 
-_dictionaryListsImportFrom: dict[str, list[str]] = defaultdict(list)
-
-def __getattr__(name: str):
-	if name not in _mapSymbolToModule:
-		raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
-
-	try:
-		moduleAsStr: str = _mapSymbolToModule[name]
-		module: ModuleType =  importlib.import_module(moduleAsStr)
-		blankSymbol = getattr(module, name)
-	except (ImportError, ModuleNotFoundError, AttributeError):
-		raise
-
-	# The need to inject into globals tells us that the symbol has not actually been imported
-	globals()[name] = blankSymbol
-	return blankSymbol
-
-_dictionaryListsImportFrom['mapFolding.basecamp'].extend([
-	'countFolds',
-])
-
-_dictionaryListsImportFrom['mapFolding.beDRY'].extend([
-	'getFilenameFoldsTotal',
-	'getPathFilenameFoldsTotal',
-	'outfitCountFolds',
-	'saveFoldsTotal',
-])
-
-_dictionaryListsImportFrom['mapFolding.oeis'].extend([
+__all__ = [
 	'clearOEIScache',
+	'countFolds',
 	'getOEISids',
-	'oeisIDfor_n',
-])
-
-# fundamentals
-_dictionaryListsImportFrom['mapFolding.theSSOT'].extend([
-	'computationState',
-	'EnumIndices',
-	'getDispatcherCallable',
-	'indexMy',
-	'indexTrack',
-	'myPackageNameIs',
-	'pathPackage',
-])
-
-# Datatype management
-_dictionaryListsImportFrom['mapFolding.theSSOT'].extend([
-	'getDatatypeModule',
-	'hackSSOTdatatype',
-	'hackSSOTdtype',
-	'setDatatypeElephino',
-	'setDatatypeFoldsTotal',
-	'setDatatypeLeavesTotal',
-	'setDatatypeModule',
-])
-
-# Synthesize modules
-_dictionaryListsImportFrom['mapFolding.theSSOT'].extend([
-	'additional_importsHARDCODED',
-	'formatFilenameModule',
-	'getAlgorithmDispatcher',
-	'getAlgorithmSource',
-	'getPathJobRootDEFAULT',
-	'getPathSyntheticModules',
-	'listCallablesDispatchees',
-	'moduleOfSyntheticModules',
-	'Z0Z_filenameModuleWrite',
-	'Z0Z_filenameWriteElseCallableTarget',
-	'Z0Z_getDatatypeModuleScalar',
-	'Z0Z_getDecoratorCallable',
-	'Z0Z_identifierCountFolds',
-	'Z0Z_setDatatypeModuleScalar',
-	'Z0Z_setDecoratorCallable',
-])
-
-# Parameters for the prima donna
-_dictionaryListsImportFrom['mapFolding.theSSOT'].extend([
-	'ParametersNumba',
-	'parametersNumbaDEFAULT',
-	'parametersNumbaFailEarly',
-	'parametersNumbaMinimum',
-	'parametersNumbaParallelDEFAULT',
-	'parametersNumbaSuperJit',
-	'parametersNumbaSuperJitParallel',
-])
-
-# Coping
-_dictionaryListsImportFrom['mapFolding.theSSOT'].extend([
-	'FREAKOUT',
-])
-
-_mapSymbolToModule: dict[str, str] = {}
-for moduleAsStr, listSymbolsAsStr in _dictionaryListsImportFrom.items():
-	for symbolAsStr in listSymbolsAsStr:
-		_mapSymbolToModule[symbolAsStr] = moduleAsStr
-
-from typing import TYPE_CHECKING
-if TYPE_CHECKING:
-	from basecamp import *
-	from beDRY import *
-	from oeis import *
-	from theDao import *
-	from theSSOT import *
+	'OEIS_for_n',
+]

mapFolding/basecamp.py

@@ -1,5 +1,7 @@
 from collections.abc import Sequence
-from mapFolding import computationState, getDispatcherCallable, getPathFilenameFoldsTotal, outfitCountFolds, saveFoldsTotal
+from mapFolding.beDRY import outfitCountFolds, setCPUlimit, validateListDimensions
+from mapFolding.filesystem import getPathFilenameFoldsTotal, saveFoldsTotal
+from mapFolding.theSSOT import ComputationState, getPackageDispatcher
 from os import PathLike
 from pathlib import Path
 
@@ -37,15 +39,17 @@ def countFolds(listDimensions: Sequence[int]
 	N.B.: You probably don't want to divide the computation into tasks.
 		If you want to compute a large `foldsTotal`, dividing the computation into tasks is usually a bad idea. Dividing the algorithm into tasks is inherently inefficient: efficient division into tasks means there would be no overlap in the work performed by each task. When dividing this algorithm, the amount of overlap is between 50% and 90% by all tasks: at least 50% of the work done by every task must be done by _all_ tasks. If you improve the computation time, it will only change by -10 to -50% depending on (at the very least) the ratio of the map dimensions and the number of leaves. If an undivided computation would take 10 hours on your computer, for example, the computation will still take at least 5 hours but you might reduce the time to 9 hours. Most of the time, however, you will increase the computation time. If logicalCores >= leavesTotal, it will probably be faster. If logicalCores <= 2 * leavesTotal, it will almost certainly be slower for all map dimensions.
 	"""
-	stateUniversal: computationState = outfitCountFolds(listDimensions, computationDivisions=computationDivisions, CPUlimit=CPUlimit)
+	mapShape: tuple[int, ...] = validateListDimensions(listDimensions)
+	concurrencyLimit: int = setCPUlimit(CPUlimit)
+	computationStateInitialized: ComputationState = outfitCountFolds(mapShape, computationDivisions, concurrencyLimit)
 
-	dispatcher = getDispatcherCallable()
-	dispatcher(**stateUniversal)
+	dispatcher = getPackageDispatcher()
+	computationStateComplete: ComputationState = dispatcher(computationStateInitialized)
 
-	foldsTotal = int(stateUniversal['foldGroups'][0:-1].sum() * stateUniversal['foldGroups'][-1])
+	computationStateComplete.getFoldsTotal()
 
 	if pathLikeWriteFoldsTotal is not None:
-		pathFilenameFoldsTotal: Path = getPathFilenameFoldsTotal(stateUniversal['mapShape'], pathLikeWriteFoldsTotal)
-		saveFoldsTotal(pathFilenameFoldsTotal, foldsTotal)
+		pathFilenameFoldsTotal: Path = getPathFilenameFoldsTotal(computationStateComplete.mapShape, pathLikeWriteFoldsTotal)
+		saveFoldsTotal(pathFilenameFoldsTotal, computationStateComplete.foldsTotal)
 
-	return foldsTotal
+	return computationStateComplete.foldsTotal

mapFolding/beDRY.py

@@ -1,103 +1,112 @@
 """A relatively stable API for oft-needed functionality."""
-from mapFolding import (
-	computationState,
-	getDatatypeModule,
-	getPathJobRootDEFAULT,
-	hackSSOTdatatype,
-	hackSSOTdtype,
-	indexMy,
-	indexTrack,
-	setDatatypeLeavesTotal,
+from mapFolding.theSSOT import (
+	Array3D,
+	ComputationState,
+	getDatatypePackage,
+	getNumpyDtypeDefault,
 )
 from collections.abc import Sequence
-from numba import get_num_threads, set_num_threads 
-from numpy import dtype, integer, ndarray
-from numpy.typing import DTypeLike, NDArray
-from pathlib import Path
 from sys import maxsize as sysMaxsize
 from typing import Any
 from Z0Z_tools import defineConcurrencyLimit, intInnit, oopsieKwargsie
 import numpy
-import os
 
-def getFilenameFoldsTotal(mapShape: Sequence[int] | ndarray[tuple[int], dtype[integer[Any]]]) -> str:
-	"""Imagine your computer has been counting folds for 9 days, and when it tries to save your newly discovered value,
-	the filename is invalid. I bet you think this function is more important after that thought experiment.
-
-	Make a standardized filename for the computed value `foldsTotal`.
+def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
+	if not listDimensions:
+		raise ValueError("listDimensions is a required parameter.")
+	listValidated: list[int] = intInnit(listDimensions, 'listDimensions')
+	listNonNegative: list[int] = []
+	for dimension in listValidated:
+		if dimension < 0:
+			raise ValueError(f"Dimension {dimension} must be non-negative")
+		listNonNegative.append(dimension)
+	dimensionsValid = [dimension for dimension in listNonNegative if dimension > 0]
+	if len(dimensionsValid) < 2:
+		raise NotImplementedError(f"This function requires listDimensions, {listDimensions}, to have at least two dimensions greater than 0. You may want to look at https://oeis.org/.")
+	return tuple(sorted(dimensionsValid))
+
+def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
+	productDimensions = 1
+	for dimension in mapShape:
+		if dimension > sysMaxsize // productDimensions:
+			raise OverflowError(f"I received {dimension=} in {mapShape=}, but the product of the dimensions exceeds the maximum size of an integer on this system.")
+		productDimensions *= dimension
+	return productDimensions
+
+def getNumpyDtype(datatype: type[numpy.signedinteger[Any]] | None = None) -> type[numpy.signedinteger[Any]]:
+	"""An imperfect way to reduce code duplication."""
+	if 'numpy' == getDatatypePackage():
+		numpyDtype = datatype or getNumpyDtypeDefault()
+	else:
+		raise NotImplementedError("Somebody done broke it.")
+	return numpyDtype
+
+def makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: type[numpy.signedinteger[Any]] | None = None) -> Array3D:
+	numpyDtype = getNumpyDtype(datatype)
+	dimensionsTotal = len(mapShape)
+	cumulativeProduct = numpy.multiply.accumulate([1] + list(mapShape), dtype=numpyDtype)
+	arrayDimensions = numpy.array(mapShape, dtype=numpyDtype)
+	coordinateSystem = numpy.zeros((dimensionsTotal, leavesTotal + 1), dtype=numpyDtype)
+	for indexDimension in range(dimensionsTotal):
+		for leaf1ndex in range(1, leavesTotal + 1):
+			coordinateSystem[indexDimension, leaf1ndex] = (((leaf1ndex - 1) // cumulativeProduct[indexDimension]) % arrayDimensions[indexDimension] + 1)
 
-	The filename takes into account
-		- the dimensions of the map, aka `mapShape`, aka `listDimensions`
-		- no spaces in the filename
-		- safe filesystem characters
-		- unique extension
-		- Python-safe strings:
-			- no starting with a number
-			- no reserved words
-			- no dashes or other special characters
-			- uh, I can't remember, but I found some other frustrating limitations
-		- if 'p' is still the first character of the filename, I picked that because it was the original identifier for the map shape in Lunnan's code
+	connectionGraph = numpy.zeros((dimensionsTotal, leavesTotal + 1, leavesTotal + 1), dtype=numpyDtype)
+	for indexDimension in range(dimensionsTotal):
+		for activeLeaf1ndex in range(1, leavesTotal + 1):
+			for connectee1ndex in range(1, activeLeaf1ndex + 1):
+				isFirstCoord = coordinateSystem[indexDimension, connectee1ndex] == 1
+				isLastCoord = coordinateSystem[indexDimension, connectee1ndex] == arrayDimensions[indexDimension]
+				exceedsActive = connectee1ndex + cumulativeProduct[indexDimension] > activeLeaf1ndex
+				isEvenParity = (coordinateSystem[indexDimension, activeLeaf1ndex] & 1) == (coordinateSystem[indexDimension, connectee1ndex] & 1)
 
-	Parameters:
-		mapShape: A sequence of integers representing the dimensions of the map.
+				if (isEvenParity and isFirstCoord) or (not isEvenParity and (isLastCoord or exceedsActive)):
+					connectionGraph[indexDimension, activeLeaf1ndex, connectee1ndex] = connectee1ndex
+				elif isEvenParity and not isFirstCoord:
+					connectionGraph[indexDimension, activeLeaf1ndex, connectee1ndex] = connectee1ndex - cumulativeProduct[indexDimension]
+				elif not isEvenParity and not (isLastCoord or exceedsActive):
+					connectionGraph[indexDimension, activeLeaf1ndex, connectee1ndex] = connectee1ndex + cumulativeProduct[indexDimension]
+	return connectionGraph
 
-	Returns:
-		filenameFoldsTotal: A filename string in format 'pMxN.foldsTotal' where M,N are sorted dimensions
-	"""
-	return 'p' + 'x'.join(str(dimension) for dimension in sorted(mapShape)) + '.foldsTotal'
+def makeDataContainer(shape: int | tuple[int, ...], datatype: type[numpy.signedinteger[Any]] | None = None) -> numpy.ndarray[Any, numpy.dtype[numpy.signedinteger[Any]]]:
+	numpyDtype = getNumpyDtype(datatype)
+	return numpy.zeros(shape, dtype=numpyDtype)
 
-def getLeavesTotal(listDimensions: Sequence[int]) -> int:
-	"""
-	How many leaves are in the map.
+def setCPUlimit(CPUlimit: Any | None) -> int:
+	"""Sets CPU limit for Numba concurrent operations. Note that it can only affect Numba-jitted functions that have not yet been imported.
 
 	Parameters:
-		listDimensions: A list of integers representing dimensions.
-
+		CPUlimit: whether and how to limit the CPU usage. See notes for details.
 	Returns:
-		productDimensions: The product of all positive integer dimensions.
-	"""
-	listNonNegative = parseDimensions(listDimensions, 'listDimensions')
-	listPositive = [dimension for dimension in listNonNegative if dimension > 0]
-
-	if not listPositive:
-		return 0
-	else:
-		productDimensions = 1
-		for dimension in listPositive:
-			if dimension > sysMaxsize // productDimensions:
-				raise OverflowError(f"I received {dimension=} in {listDimensions=}, but the product of the dimensions exceeds the maximum size of an integer on this system.")
-			productDimensions *= dimension
-
-		return productDimensions
-
-def getPathFilenameFoldsTotal(mapShape: Sequence[int] | ndarray[tuple[int], dtype[integer[Any]]], pathLikeWriteFoldsTotal: str | os.PathLike[str] | None = None) -> Path:
-	"""Get a standardized path and filename for the computed value `foldsTotal`.
-
-	If you provide a directory, the function will append a standardized filename. If you provide a filename
-	or a relative path and filename, the function will prepend the default path.
-
-	Parameters:
-		mapShape: List of dimensions for the map folding problem.
-		pathLikeWriteFoldsTotal (pathJobRootDEFAULT): Path, filename, or relative path and filename. If None, uses default path.
-			Defaults to None.
+		concurrencyLimit: The actual concurrency limit that was set
+	Raises:
+		TypeError: If CPUlimit is not of the expected types
 
-	Returns:
-		pathFilenameFoldsTotal: Absolute path and filename.
+	Limits on CPU usage `CPUlimit`:
+		- `False`, `None`, or `0`: No limits on CPU usage; uses all available CPUs. All other values will potentially limit CPU usage.
+		- `True`: Yes, limit the CPU usage; limits to 1 CPU.
+		- Integer `>= 1`: Limits usage to the specified number of CPUs.
+		- Decimal value (`float`) between 0 and 1: Fraction of total CPUs to use.
+		- Decimal value (`float`) between -1 and 0: Fraction of CPUs to *not* use.
+		- Integer `<= -1`: Subtract the absolute value from total CPUs.
 	"""
-	pathLikeSherpa = Path(pathLikeWriteFoldsTotal) if pathLikeWriteFoldsTotal is not None else None
-	if not pathLikeSherpa:
-		pathLikeSherpa = getPathJobRootDEFAULT()
-	if pathLikeSherpa.is_dir():
-		pathFilenameFoldsTotal = pathLikeSherpa / getFilenameFoldsTotal(mapShape)
-	elif pathLikeSherpa.is_absolute():
-		pathFilenameFoldsTotal = pathLikeSherpa
+	if not (CPUlimit is None or isinstance(CPUlimit, (bool, int, float))):
+		CPUlimit = oopsieKwargsie(CPUlimit)
+
+	concurrencyLimit: int = int(defineConcurrencyLimit(CPUlimit))
+	from mapFolding.theSSOT import concurrencyPackage
+	if concurrencyPackage == 'numba':
+		from numba import get_num_threads, set_num_threads
+		set_num_threads(concurrencyLimit)
+		concurrencyLimit = get_num_threads()
+	elif concurrencyPackage == 'algorithm':
+		concurrencyLimit = 1
 	else:
-		pathFilenameFoldsTotal = getPathJobRootDEFAULT() / pathLikeSherpa
+		raise NotImplementedError("This function only supports the 'numba' concurrency package.")
 
-	pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
-	return pathFilenameFoldsTotal
+	return concurrencyLimit
 
-def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: int, CPUlimit: bool | float | int | None, listDimensions: Sequence[int]) -> int:
+def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: int, leavesTotal: int) -> int:
 	"""
 	Determines whether to divide the computation into tasks and how many divisions.
 
@@ -131,12 +140,11 @@ def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: i
 	Task divisions should not exceed total leaves or the folds will be over-counted.
 	"""
 	taskDivisions = 0
-	leavesTotal = getLeavesTotal(listDimensions)
 	if not computationDivisions:
 		pass
 	elif isinstance(computationDivisions, int):
 		taskDivisions = computationDivisions
-	elif isinstance(computationDivisions, str):  # type: ignore 'Unnecessary isinstance call; "str" is always an instance of "str", so sayeth Pylance'. Yeah, well "User is not always an instance of "correct input" so sayeth the programmer.
+	elif isinstance(computationDivisions, str): # type: ignore 'Unnecessary isinstance call; "str" is always an instance of "str", so sayeth Pylance'. Yeah, well "User is not always an instance of "correct input" so sayeth the programmer.
 		computationDivisions = computationDivisions.lower()
 		if computationDivisions == 'maximum':
 			taskDivisions = leavesTotal
@@ -146,209 +154,11 @@ def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: i
 		raise ValueError(f"I received {computationDivisions} for the parameter, `computationDivisions`, but the so-called programmer didn't implement code for that.")
 
 	if taskDivisions > leavesTotal:
-		raise ValueError(f"Problem: `taskDivisions`, ({taskDivisions}), is greater than `leavesTotal`, ({leavesTotal}), which will cause duplicate counting of the folds.\n\nChallenge: you cannot directly set `taskDivisions` or `leavesTotal`. They are derived from parameters that may or may not still be named `computationDivisions`, `CPUlimit` , and `listDimensions` and from dubious-quality Python code.\n\nFor those parameters, I received {computationDivisions=}, {CPUlimit=}, and {listDimensions=}.\n\nPotential solutions: get a different hobby or set `computationDivisions` to a different value.")
-
-	return taskDivisions
-
-def makeConnectionGraph(listDimensions: Sequence[int], **keywordArguments: str | None) -> ndarray[tuple[int, int, int], dtype[integer[Any]]]:
-	"""
-	Constructs a multi-dimensional connection graph representing the connections between the leaves of a map with the given dimensions.
-	Also called a Cartesian product decomposition or dimensional product mapping.
-
-	Parameters
-		listDimensions: A sequence of integers representing the dimensions of the map.
-		**keywordArguments: Datatype management.
-
-	Returns
-		connectionGraph: A 3D numpy array with shape of (dimensionsTotal, leavesTotal + 1, leavesTotal + 1).
-	"""
-	ImaSetTheDatatype = keywordArguments.get('datatype', None)
-	if ImaSetTheDatatype:
-		setDatatypeLeavesTotal(ImaSetTheDatatype)
-	dtype = hackSSOTdtype('connectionGraph')
-	mapShape = validateListDimensions(listDimensions)
-	leavesTotal = getLeavesTotal(mapShape)
-	arrayDimensions = numpy.array(mapShape, dtype=dtype)
-	dimensionsTotal = len(arrayDimensions)
-
-	cumulativeProduct = numpy.multiply.accumulate([1] + mapShape, dtype=dtype)
-	coordinateSystem = numpy.zeros((dimensionsTotal, leavesTotal + 1), dtype=dtype)
-	for indexDimension in range(dimensionsTotal):
-		for leaf1ndex in range(1, leavesTotal + 1):
-			coordinateSystem[indexDimension, leaf1ndex] = ( ((leaf1ndex - 1) // cumulativeProduct[indexDimension]) % arrayDimensions[indexDimension] + 1 )
-
-	connectionGraph: ndarray[tuple[int, int, int], numpy.dtype[integer[Any]]] = numpy.zeros((dimensionsTotal, leavesTotal + 1, leavesTotal + 1), dtype=dtype)
-	for indexDimension in range(dimensionsTotal):
-		for activeLeaf1ndex in range(1, leavesTotal + 1):
-			for connectee1ndex in range(1, activeLeaf1ndex + 1):
-				isFirstCoord = coordinateSystem[indexDimension, connectee1ndex] == 1
-				isLastCoord = coordinateSystem[indexDimension, connectee1ndex] == arrayDimensions[indexDimension]
-				exceedsActive = connectee1ndex + cumulativeProduct[indexDimension] > activeLeaf1ndex
-				isEvenParity = (coordinateSystem[indexDimension, activeLeaf1ndex] & 1) == (coordinateSystem[indexDimension, connectee1ndex] & 1)
-
-				if (isEvenParity and isFirstCoord) or (not isEvenParity and (isLastCoord or exceedsActive)):
-					connectionGraph[indexDimension, activeLeaf1ndex, connectee1ndex] = connectee1ndex
-				elif isEvenParity and not isFirstCoord:
-					connectionGraph[indexDimension, activeLeaf1ndex, connectee1ndex] = connectee1ndex - cumulativeProduct[indexDimension]
-				elif not isEvenParity and not (isLastCoord or exceedsActive):
-					connectionGraph[indexDimension, activeLeaf1ndex, connectee1ndex] = connectee1ndex + cumulativeProduct[indexDimension]
+		raise ValueError(f"Problem: `taskDivisions`, ({taskDivisions}), is greater than `leavesTotal`, ({leavesTotal}), which will cause duplicate counting of the folds.\n\nChallenge: you cannot directly set `taskDivisions` or `leavesTotal`. They are derived from parameters that may or may not still be named `computationDivisions`, `CPUlimit` , and `listDimensions` and from dubious-quality Python code.")
+	return int(max(0, taskDivisions))
 
-	return connectionGraph
-
-def makeDataContainer(shape: int | tuple[int, ...], datatype: DTypeLike | None = None) -> NDArray[integer[Any]]:
-	"""Create a zeroed-out `ndarray` with the given shape and datatype.
-
-	Parameters:
-		shape: The shape of the array. Can be an integer for 1D arrays
-			or a tuple of integers for multi-dimensional arrays.
-		datatype ('dtypeFoldsTotal'): The desired data type for the array.
-			If `None`, defaults to 'dtypeFoldsTotal'. Defaults to None.
-
-	Returns:
-		dataContainer: A new array of given shape and type, filled with zeros.
-
-	Notes:
-		If a version of the algorithm were to use something other than numpy, such as JAX or CUDA, because other
-		functions use this function, it would be much easier to change the datatype "ecosystem".
-	"""
-	numpyDtype = datatype or hackSSOTdtype('dtypeFoldsTotal')
-	if 'numpy' == getDatatypeModule():
-		return numpy.zeros(shape, dtype=numpyDtype)
-	else:
-		raise NotImplementedError("Somebody done broke it.")
-
-def outfitCountFolds(listDimensions: Sequence[int]
-					, computationDivisions: int | str | None = None
-					, CPUlimit: bool | float | int | None = None
-					) -> computationState:
-	"""
-	Initializes and configures the computation state for map folding computations.
-
-	Parameters:
-		listDimensions: The dimensions of the map to be folded
-		computationDivisions (None): see `getTaskDivisions`
-		CPUlimit (None): see `setCPUlimit`
-
-	Returns:
-		stateInitialized: The initialized computation state
-	"""
-	my = makeDataContainer(len(indexMy), hackSSOTdtype('my'))
-
-	mapShape = tuple(sorted(validateListDimensions(listDimensions)))
-	concurrencyLimit = setCPUlimit(CPUlimit)
-	my[indexMy.taskDivisions] = getTaskDivisions(computationDivisions, concurrencyLimit, CPUlimit, mapShape)
-
-	foldGroups = makeDataContainer(max(my[indexMy.taskDivisions] + 1, 2), hackSSOTdtype('foldGroups'))
+def outfitCountFolds(mapShape: tuple[int, ...], computationDivisions: int | str | None = None, concurrencyLimit: int = 1) -> ComputationState:
 	leavesTotal = getLeavesTotal(mapShape)
-	foldGroups[-1] = leavesTotal
-
-	my[indexMy.dimensionsTotal] = len(mapShape)
-	my[indexMy.leaf1ndex] = 1
-	stateInitialized = computationState(
-		connectionGraph = makeConnectionGraph(mapShape, datatype=hackSSOTdatatype('connectionGraph')),
-		foldGroups = foldGroups,
-		mapShape = numpy.array(mapShape, dtype=hackSSOTdtype('mapShape')),
-		my = my,
-		gapsWhere = makeDataContainer(int(leavesTotal) * int(leavesTotal) + 1, hackSSOTdtype('gapsWhere')),
-		track = makeDataContainer((len(indexTrack), leavesTotal + 1), hackSSOTdtype('track')),
-		)
-
-	return stateInitialized
-
-def parseDimensions(dimensions: Sequence[int], parameterName: str = 'listDimensions') -> list[int]:
-	"""
-	Parse and validate the dimensions are non-negative integers.
-
-	Parameters:
-		dimensions: Sequence of integers representing dimensions.
-		parameterName ('listDimensions'): Name of the parameter for error messages. Defaults to 'listDimensions'.
-	Returns:
-		listNonNegative: List of validated non-negative integers.
-	Raises:
-		ValueError: If any dimension is negative or if the list is empty.
-		TypeError: If any element cannot be converted to integer (raised by `intInnit`).
-	"""
-	listValidated: list[int] = intInnit(dimensions, parameterName)
-	listNonNegative: list[int] = []
-	for dimension in listValidated:
-		if dimension < 0:
-			raise ValueError(f"Dimension {dimension} must be non-negative")
-		listNonNegative.append(dimension)
-
-	return listNonNegative
-
-def saveFoldsTotal(pathFilename: str | os.PathLike[str], foldsTotal: int) -> None:
-	"""
-	Save foldsTotal with multiple fallback mechanisms.
-
-	Parameters:
-		pathFilename: Target save location
-		foldsTotal: Critical computed value to save
-	"""
-	try:
-		pathFilenameFoldsTotal = Path(pathFilename)
-		pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
-		pathFilenameFoldsTotal.write_text(str(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)
-
-def setCPUlimit(CPUlimit: Any | None) -> int:
-	"""Sets CPU limit for Numba concurrent operations. Note that it can only affect Numba-jitted functions that have not yet been imported.
-
-	Parameters:
-		CPUlimit: whether and how to limit the CPU usage. See notes for details.
-	Returns:
-		concurrencyLimit: The actual concurrency limit that was set
-	Raises:
-		TypeError: If CPUlimit is not of the expected types
-
-	Limits on CPU usage `CPUlimit`:
-		- `False`, `None`, or `0`: No limits on CPU usage; uses all available CPUs. All other values will potentially limit CPU usage.
-		- `True`: Yes, limit the CPU usage; limits to 1 CPU.
-		- Integer `>= 1`: Limits usage to the specified number of CPUs.
-		- Decimal value (`float`) between 0 and 1: Fraction of total CPUs to use.
-		- Decimal value (`float`) between -1 and 0: Fraction of CPUs to *not* use.
-		- Integer `<= -1`: Subtract the absolute value from total CPUs.
-	"""
-	if not (CPUlimit is None or isinstance(CPUlimit, (bool, int, float))):
-		CPUlimit = oopsieKwargsie(CPUlimit)
-
-	concurrencyLimit = int(defineConcurrencyLimit(CPUlimit))
-	set_num_threads(concurrencyLimit)
-	concurrencyLimit: int = get_num_threads()
-
-	return concurrencyLimit
-
-def validateListDimensions(listDimensions: Sequence[int]) -> list[int]:
-	"""
-	Validates and sorts a sequence of at least two positive dimensions.
-
-	Parameters:
-		listDimensions: A sequence of integer dimensions to be validated.
-
-	Returns:
-		dimensionsValidSorted: A list, with at least two elements, of only positive integers.
-
-	Raises:
-		ValueError: If the input listDimensions is empty.
-		NotImplementedError: If the resulting list of positive dimensions has fewer than two elements.
-	"""
-	if not listDimensions:
-		raise ValueError("listDimensions is a required parameter.")
-	listNonNegative = parseDimensions(listDimensions, 'listDimensions')
-	dimensionsValid = [dimension for dimension in listNonNegative if dimension > 0]
-	if len(dimensionsValid) < 2:
-		raise NotImplementedError(f"This function requires listDimensions, {listDimensions}, to have at least two dimensions greater than 0. You may want to look at https://oeis.org/.")
-	return sorted(dimensionsValid)
+	taskDivisions = getTaskDivisions(computationDivisions, concurrencyLimit, leavesTotal)
+	computationStateInitialized = ComputationState(mapShape, leavesTotal, taskDivisions)
+	return computationStateInitialized

mapFolding/filesystem.py

@@ -0,0 +1,87 @@
+"""Filesystem functions for mapFolding package."""
+from pathlib import Path
+import os
+
+def saveFoldsTotal(pathFilename: str | os.PathLike[str], foldsTotal: int) -> None:
+	"""
+	Save foldsTotal with multiple fallback mechanisms.
+
+	Parameters:
+		pathFilename: Target save location
+		foldsTotal: Critical computed value to save
+	"""
+	try:
+		pathFilenameFoldsTotal = Path(pathFilename)
+		pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
+		pathFilenameFoldsTotal.write_text(str(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 getFilenameFoldsTotal(mapShape: tuple[int, ...]) -> str:
+	"""Imagine your computer has been counting folds for 9 days, and when it tries to save your newly discovered value,
+	the filename is invalid. I bet you think this function is more important after that thought experiment.
+
+	Make a standardized filename for the computed value `foldsTotal`.
+
+	The filename takes into account
+		- the dimensions of the map, aka `mapShape`, aka `listDimensions`
+		- no spaces in the filename
+		- safe filesystem characters
+		- unique extension
+		- Python-safe strings:
+			- no starting with a number
+			- no reserved words
+			- no dashes or other special characters
+			- uh, I can't remember, but I found some other frustrating limitations
+		- if 'p' is still the first character of the filename, I picked that because it was the original identifier for the map shape in Lunnan's code
+
+	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
+	"""
+	return 'p' + 'x'.join(str(dimension) for dimension in sorted(mapShape)) + '.foldsTotal'
+
+def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal: str | os.PathLike[str] | None = None) -> Path:
+	"""Get a standardized path and filename for the computed value `foldsTotal`.
+
+	If you provide a directory, the function will append a standardized filename. If you provide a filename
+	or a relative path and filename, the function will prepend the default path.
+
+	Parameters:
+		mapShape: List of dimensions for the map folding problem.
+		pathLikeWriteFoldsTotal (pathJobRootDEFAULT): Path, filename, or relative path and filename. If None, uses default path.
+			Defaults to None.
+
+	Returns:
+		pathFilenameFoldsTotal: Absolute path and filename.
+	"""
+	from mapFolding.theSSOT import getPathJobRootDEFAULT
+
+	if pathLikeWriteFoldsTotal is None:
+		pathFilenameFoldsTotal = getPathJobRootDEFAULT() / 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 = getPathJobRootDEFAULT() / pathLikeSherpa
+
+	pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
+	return pathFilenameFoldsTotal