mapFolding 0.9.1__tar.gz → 0.9.3__tar.gz

{mapfolding-0.9.1 → mapfolding-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapFolding
-Version: 0.9.1
+Version: 0.9.3
 Summary: Map folding algorithm with code transformation framework for optimizing numerical computations
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 License: CC-BY-NC-4.0
@@ -8,7 +8,7 @@ Project-URL: Donate, https://www.patreon.com/integrated
 Project-URL: Homepage, https://github.com/hunterhogan/mapFolding
 Project-URL: Repository, https://github.com/hunterhogan/mapFolding.git
 Project-URL: Issues, https://github.com/hunterhogan/mapFolding/issues
-Keywords: A001415,A001416,A001417,A001418,A195646,algorithmic optimization,AST manipulation,code generation,code transformation,combinatorics,computational geometry,dataclass transformation,folding pattern enumeration,just-in-time compilation,map folding,Numba optimization,OEIS,performance optimization,source code analysis,stamp folding
+Keywords: A000136,A001415,A001416,A001417,A001418,A195646,algorithmic optimization,AST manipulation,code generation,code transformation,combinatorics,computational geometry,dataclass transformation,folding pattern enumeration,just-in-time compilation,map folding,Numba optimization,OEIS,performance optimization,source code analysis,stamp folding
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -38,6 +38,7 @@ Requires-Dist: numba
 Requires-Dist: numpy
 Requires-Dist: platformdirs
 Requires-Dist: python_minifier
+Requires-Dist: sympy
 Requires-Dist: tomli
 Requires-Dist: Z0Z_tools
 Provides-Extra: testing
@@ -105,7 +106,7 @@ def countFolds_optimized(shape_param):
 
 ### 2. Code Generation Framework
 
-Study and extend a complete Python code transformation pipeline:
+Study and extend a complete Python code transformation assembly line:
 
 - AST analysis and manipulation
 - Dataclass decomposition ("shattering")

{mapfolding-0.9.1 → mapfolding-0.9.3}/README.md

@@ -53,7 +53,7 @@ def countFolds_optimized(shape_param):
 
 ### 2. Code Generation Framework
 
-Study and extend a complete Python code transformation pipeline:
+Study and extend a complete Python code transformation assembly line:
 
 - AST analysis and manipulation
 - Dataclass decomposition ("shattering")

mapfolding-0.9.3/mapFolding/Z0Z_flowControl.py

@@ -0,0 +1,99 @@
+from collections.abc import Sequence
+from mapFolding import (
+	ComputationState,
+	getPathFilenameFoldsTotal,
+	outfitCountFolds,
+	saveFoldsTotal,
+	saveFoldsTotalFAILearly,
+	setProcessorLimit,
+	The,
+	validateListDimensions,
+)
+from os import PathLike
+from pathlib import PurePath
+
+def countFolds(listDimensions: Sequence[int] | None = None
+				, pathLikeWriteFoldsTotal: PathLike[str] | PurePath | None = None
+				, computationDivisions: int | str | None = None
+				, CPUlimit: int | float | bool | None = None
+				# , * I need to improve `standardizedEqualToCallableReturn` so it will work with keyword arguments
+				, mapShape: tuple[int, ...] | None = None
+				, oeisID: str | None = None
+				, oeis_n: int | None = None
+				, flow: str | None = None
+				) -> int:
+	"""
+	To select the execution path, I need at least:
+		- mapShape
+		- task division instructions
+		- memorialization instructions
+	"""
+
+	# mapShape =====================================================================
+
+	if mapShape:
+		pass
+	else:
+		if oeisID and oeis_n:
+			from mapFolding.oeis import settingsOEIS
+			try:
+				mapShape = settingsOEIS[oeisID]['getMapShape'](oeis_n)
+			except KeyError:
+				pass
+		if not mapShape and listDimensions:
+			mapShape = validateListDimensions(listDimensions)
+
+	if mapShape is None:
+		raise ValueError(f"""I received these values:
+	`{listDimensions = }`,
+	`{mapShape = }`,
+	`{oeisID = }` and `{oeis_n = }`,
+	but I was unable to select a map for which to count the folds.""")
+
+	# task division instructions ===============================================
+
+	if computationDivisions:
+		# NOTE `The.concurrencyPackage`
+		concurrencyLimit: int = setProcessorLimit(CPUlimit, The.concurrencyPackage)
+		from mapFolding.beDRY import getLeavesTotal, getTaskDivisions
+		leavesTotal: int = getLeavesTotal(mapShape)
+		taskDivisions = getTaskDivisions(computationDivisions, concurrencyLimit, leavesTotal)
+		del leavesTotal
+	else:
+		concurrencyLimit = 1
+		taskDivisions = 0
+
+	# memorialization instructions ===========================================
+
+	if pathLikeWriteFoldsTotal is not None:
+		pathFilenameFoldsTotal = getPathFilenameFoldsTotal(mapShape, pathLikeWriteFoldsTotal)
+		saveFoldsTotalFAILearly(pathFilenameFoldsTotal)
+	else:
+		pathFilenameFoldsTotal = None
+
+	# Flow control until I can figure out a good way ===============================
+
+	if flow == 'theDaoOfMapFolding':
+		from mapFolding.dataBaskets import MapFoldingState
+		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
+
+		from mapFolding.theDaoOfMapFolding import doTheNeedful
+		mapFoldingState = doTheNeedful(mapFoldingState)
+		foldsTotal = mapFoldingState.foldsTotal
+
+	# NOTE treat this as a default?
+	# flow based on `The` and `ComputationState` ====================================
+
+	else:
+		computationStateInitialized: ComputationState = outfitCountFolds(mapShape, computationDivisions, concurrencyLimit)
+		computationStateComplete: ComputationState = The.dispatcher(computationStateInitialized)
+
+		computationStateComplete.getFoldsTotal()
+		foldsTotal = computationStateComplete.foldsTotal
+
+	# Follow memorialization instructions ===========================================
+
+	if pathFilenameFoldsTotal is not None:
+		saveFoldsTotal(pathFilenameFoldsTotal, foldsTotal)
+
+	return foldsTotal

mapfolding-0.9.3/mapFolding/__init__.py

@@ -0,0 +1,96 @@
+"""
+Map folding enumeration and counting algorithms with advanced optimization capabilities.
+
+This package implements algorithms to count and enumerate the distinct ways a rectangular map can be folded, based on
+the mathematical problem described in Lunnon's 1971 paper. It provides multiple layers of functionality, from high-level
+user interfaces to sophisticated algorithmic optimizations and code transformation tools.
+
+Core modules:
+- basecamp: Public API with simplified interfaces for end users
+- theDao: Core computational algorithm using a functional state-transformation approach
+- beDRY: Core utility functions implementing consistent data handling, validation, and resource management across the
+	package's computational assembly-line
+- theSSOT: Single Source of Truth for configuration, types, and state management
+- toolboxFilesystem: Cross-platform file management services for storing and retrieving computation results with robust
+	error handling and fallback mechanisms
+- oeis: Interface to the Online Encyclopedia of Integer Sequences for known results
+
+Extended functionality:
+- someAssemblyRequired: Code transformation framework that optimizes the core algorithm through AST manipulation,
+	dataclass transformation, and compilation techniques
+	- The system converts readable code into high-performance implementations through a systematic analysis and
+		transformation assembly line
+	- Provides tools to "shatter" complex dataclasses into primitive components, enabling compatibility with Numba and
+		other optimization frameworks
+	- Creates specialized implementations tailored for specific input parameters
+
+Testing and extension:
+- tests: Comprehensive test suite designed for both verification and extension
+	- Provides fixtures and utilities that simplify testing of custom implementations
+	- Enables users to validate their own recipes and job configurations with minimal code
+	- Offers standardized testing patterns that maintain consistency across the codebase
+	- See tests/__init__.py for detailed documentation on extending the test suite
+
+Special directories:
+- .cache/: Stores cached data from external sources like OEIS to improve performance
+- syntheticModules/: Contains dynamically generated, optimized implementations of the core algorithm created by the code
+transformation framework
+- reference/: Historical implementations and educational resources for algorithm exploration
+	- reference/jobsCompleted/: Contains successful computations for previously unknown values, including first-ever
+		calculations for 2x19 and 2x20 maps (OEIS A001415)
+
+This package balances algorithm readability and understandability with high-performance computation capabilities,
+allowing users to compute map folding totals for larger dimensions than previously feasible while also providing a
+foundation for exploring advanced code transformation techniques.
+"""
+
+from mapFolding.datatypes import (
+	Array1DElephino as Array1DElephino,
+	Array1DFoldsTotal as Array1DFoldsTotal,
+	Array1DLeavesTotal as Array1DLeavesTotal,
+	Array3D as Array3D,
+	DatatypeElephino as DatatypeElephino,
+	DatatypeFoldsTotal as DatatypeFoldsTotal,
+	DatatypeLeavesTotal as DatatypeLeavesTotal,
+	NumPyElephino as NumPyElephino,
+	NumPyFoldsTotal as NumPyFoldsTotal,
+	NumPyIntegerType as NumPyIntegerType,
+	NumPyLeavesTotal as NumPyLeavesTotal,
+)
+
+from mapFolding.theSSOT import (
+	ComputationState as ComputationState,
+	raiseIfNoneGitHubIssueNumber3 as raiseIfNoneGitHubIssueNumber3,
+	The as The,
+)
+
+from mapFolding.theDao import (
+	countInitialize as countInitialize,
+	doTheNeedful as doTheNeedful,
+)
+
+from mapFolding.beDRY import (
+	getLeavesTotal as getLeavesTotal,
+	getTaskDivisions as getTaskDivisions,
+	outfitCountFolds as outfitCountFolds,
+	setProcessorLimit as setProcessorLimit,
+	validateListDimensions as validateListDimensions,
+)
+
+from mapFolding.toolboxFilesystem import (
+	getPathFilenameFoldsTotal as getPathFilenameFoldsTotal,
+	getPathRootJobDEFAULT as getPathRootJobDEFAULT,
+	saveFoldsTotal as saveFoldsTotal,
+	saveFoldsTotalFAILearly as saveFoldsTotalFAILearly,
+	writeStringToHere as writeStringToHere,
+)
+
+from mapFolding.Z0Z_flowControl import countFolds
+
+from mapFolding.oeis import (
+	clearOEIScache as clearOEIScache,
+	getFoldsTotalKnown as getFoldsTotalKnown,
+	getOEISids as getOEISids,
+	OEIS_for_n as OEIS_for_n,
+	oeisIDfor_n as oeisIDfor_n,
+)

mapfolding-0.9.3/mapFolding/basecamp.py

@@ -0,0 +1,95 @@
+"""
+Public API for the map folding algorithm with simplified interface.
+
+This module provides the main entry point for users of the mapFolding package, abstracting away the complexities of the
+computational algorithm. It offers a high-level interface to count the total number of possible ways to fold a
+rectangular map of specified dimensions, with options for customizing the computation process and saving results.
+
+The primary function is countFolds, which handles parameter validation, computation state management, dispatching to the
+appropriate algorithm implementation, and optional persistence of results.
+"""
+
+from collections.abc import Sequence
+from mapFolding import (
+	ComputationState,
+	getPathFilenameFoldsTotal,
+	outfitCountFolds,
+	saveFoldsTotal,
+	saveFoldsTotalFAILearly,
+	setProcessorLimit,
+	The,
+	validateListDimensions,
+)
+from os import PathLike
+from pathlib import PurePath
+
+def countFolds(listDimensions: Sequence[int]
+				, pathLikeWriteFoldsTotal: PathLike[str] | PurePath | None = None
+				, computationDivisions: int | str | None = None
+				, CPUlimit: int | float | bool | None = None
+				) -> int:
+	"""
+	Count the total number of possible foldings for a given map dimensions.
+
+	This function serves as the main public interface to the map folding algorithm, handling all parameter validation,
+	computation state management, and result persistence in a user-friendly way.
+
+	Parameters
+	----------
+	listDimensions
+		List of integers representing the dimensions of the map to be folded.
+	pathLikeWriteFoldsTotal: None
+		Path, filename, or pathFilename to write the total fold count to. If a directory is provided, creates a file
+		with a default name based on map dimensions.
+	computationDivisions: None
+		Whether and how to divide the computational work.
+		- `None`: no division of the computation into tasks; sets task divisions to 0.
+		- int: directly set the number of task divisions; cannot exceed the map's total leaves.
+		- `'maximum'`: divides into `leavesTotal`-many `taskDivisions`.
+		- `'cpu'`: limits the divisions to the number of available CPUs: i.e., `concurrencyLimit`.
+	CPUlimit: None
+		This is only relevant if there are `computationDivisions`: whether and how to limit the CPU usage.
+		- `False`, `None`, or `0`: No limits on processor usage; uses all available processors. All other values will
+		potentially limit processor usage.
+		- `True`: Yes, limit the processor usage; limits to 1 processor.
+		- Integer `>= 1`: Limits usage to the specified number of processors.
+		- Decimal value (`float`) between 0 and 1: Fraction of total processors to use.
+		- Decimal value (`float`) between -1 and 0: Fraction of processors to _not_ use.
+		- Integer `<= -1`: Subtract the absolute value from total processors.
+
+	Returns
+	-------
+	foldsTotal: Total number of distinct ways to fold a map of the given dimensions.
+
+	Note well
+	---------
+	You probably do not want to divide your 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.
+	"""
+	mapShape: tuple[int, ...] = validateListDimensions(listDimensions)
+	concurrencyLimit: int = setProcessorLimit(CPUlimit, The.concurrencyPackage)
+	computationStateInitialized: ComputationState = outfitCountFolds(mapShape, computationDivisions, concurrencyLimit)
+
+	if pathLikeWriteFoldsTotal is not None:
+		pathFilenameFoldsTotal = getPathFilenameFoldsTotal(computationStateInitialized.mapShape, pathLikeWriteFoldsTotal)
+		saveFoldsTotalFAILearly(pathFilenameFoldsTotal)
+	else:
+		pathFilenameFoldsTotal = None
+
+	computationStateComplete: ComputationState = The.dispatcher(computationStateInitialized)
+
+	computationStateComplete.getFoldsTotal()
+
+	if pathFilenameFoldsTotal is not None:
+		saveFoldsTotal(pathFilenameFoldsTotal, computationStateComplete.foldsTotal)
+
+	return computationStateComplete.foldsTotal

{mapfolding-0.9.1 → mapfolding-0.9.3}/mapFolding/beDRY.py

@@ -1,8 +1,8 @@
 """
 Core utility functions implementing DRY (Don't Repeat Yourself) principles for the mapFolding package.
 
-This module serves as the foundation for consistent data management and parameter validation
-across the entire mapFolding computation assembly-line. It provides critical utility functions that:
+This module serves as the foundation for consistent data management and parameter validation across the entire
+mapFolding computation assembly-line. It provides critical utility functions that:
 
 1. Calculate and validate fundamental computational parameters such as leaves total and task divisions.
 2. Generate specialized connection graphs that define the folding algorithm's constraints.
@@ -10,13 +10,12 @@ across the entire mapFolding computation assembly-line. It provides critical uti
 4. Construct and manage uniform data structures for the computation state.
 5. Ensure parameter validation and safe type conversion.
 
-The functions in this module maintain a clear separation between data initialization and algorithm
-implementation, enabling the package to support multiple computational strategies (sequential,
-parallel, and JIT-compiled) while ensuring consistent input handling and state management.
+The functions in this module maintain a clear separation between data initialization and algorithm implementation,
+enabling the package to support multiple computational strategies (sequential, parallel, and JIT-compiled) while
+ensuring consistent input handling and state management.
 
-These utilities form a stable internal API that other modules depend on, particularly theSSOT
-(Single Source of Truth), theDao (core algorithm), and the synthetic module generators that
-produce optimized implementations.
+These utilities form a stable internal API that other modules depend on, particularly theSSOT (Single Source of Truth),
+theDao (core algorithm), and the synthetic module generators that produce optimized implementations.
 """
 from collections.abc import Sequence
 from mapFolding import ComputationState, NumPyIntegerType
@@ -31,8 +30,6 @@ def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
 	Calculate the total number of leaves in a map with the given dimensions.
 
 	The total number of leaves is the product of all dimensions in the map shape.
-	This value is foundational for initializing the computation state and determining
-	task divisions.
 
 	Parameters
 	----------
@@ -47,8 +44,8 @@ def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
 	Raises
 	------
 	OverflowError
-		If the product of dimensions would exceed the system's maximum integer size.
-		This check prevents silent numeric overflow issues that could lead to incorrect results.
+		If the product of dimensions would exceed the system's maximum integer size. This check prevents silent numeric
+		overflow issues that could lead to incorrect results.
 	"""
 	productDimensions = 1
 	for dimension in mapShape:
@@ -113,10 +110,9 @@ def _makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int) -> ndarray
 	"""
 	Implementation of connection graph generation for map folding.
 
-	This is the internal implementation that calculates all possible connections between
-	leaves in a map folding problem based on Lunnon's algorithm. The function constructs a
-	three-dimensional array representing which leaves can be connected to each other for each
-	dimension of the map.
+	This is the internal implementation that calculates all possible connections between leaves in a map folding problem
+	based on Lunnon's algorithm. The function constructs a three-dimensional array representing which leaves can be
+	connected to each other for each dimension of the map.
 
 	Parameters
 	----------
@@ -128,17 +124,16 @@ def _makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int) -> ndarray
 	Returns
 	-------
 	connectionGraph
-		A 3D NumPy array with shape (`dimensionsTotal`, `leavesTotal`+1, `leavesTotal`+1)
-		where each entry [d,i,j] represents the leaf that would be connected to leaf j
-		when inserting leaf i in dimension d.
+		A 3D NumPy array with shape (`dimensionsTotal`, `leavesTotal`+1, `leavesTotal`+1) where each entry [d,i,j]
+		represents the leaf that would be connected to leaf j when inserting leaf i in dimension d.
 
 	Notes
 	-----
-	This is an implementation detail and shouldn't be called directly by external code.
-	Use `getConnectionGraph` instead, which applies proper typing.
+	This is an implementation detail and shouldn't be called directly by external code. Use `getConnectionGraph`
+	instead, which applies proper typing.
 
-	The algorithm calculates a coordinate system first, then determines connections
-	based on parity rules, boundary conditions, and dimensional constraints.
+	The algorithm calculates a coordinate system first, then determines connections based on parity rules, boundary
+	conditions, and dimensional constraints.
 	"""
 	dimensionsTotal = len(mapShape)
 	cumulativeProduct = numpy.multiply.accumulate([1] + list(mapShape), dtype=numpy_int64)
@@ -169,9 +164,9 @@ def getConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: ty
 	"""
 	Create a properly typed connection graph for the map folding algorithm.
 
-	This function serves as a typed wrapper around the internal implementation that
-	generates connection graphs. It provides the correct type information for the
-	returned array, ensuring consistency throughout the computation assembly-line.
+	This function serves as a typed wrapper around the internal implementation that generates connection graphs. It
+	provides the correct type information for the returned array, ensuring consistency throughout the computation
+	assembly-line.
 
 	Parameters
 	----------
@@ -180,14 +175,14 @@ def getConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: ty
 	leavesTotal
 		The total number of leaves in the map.
 	datatype
-		The NumPy integer type to use for the array elements, ensuring proper
-		memory usage and compatibility with the computation state.
+		The NumPy integer type to use for the array elements, ensuring proper memory usage and compatibility with the
+		computation state.
 
 	Returns
 	-------
 	connectionGraph
-		A 3D NumPy array with shape (`dimensionsTotal`, `leavesTotal`+1, `leavesTotal`+1)
-		with the specified `datatype`, representing all possible connections between leaves.
+		A 3D NumPy array with shape (`dimensionsTotal`, `leavesTotal`+1, `leavesTotal`+1) with the specified `datatype`,
+		representing all possible connections between leaves.
 	"""
 	connectionGraph = _makeConnectionGraph(mapShape, leavesTotal)
 	connectionGraph = connectionGraph.astype(datatype)
@@ -197,18 +192,16 @@ def makeDataContainer(shape: int | tuple[int, ...], datatype: type[NumPyIntegerT
 	"""
 	Create a typed NumPy array container with initialized values.
 
-	This function centralizes the creation of data containers used throughout the
-	computation assembly-line, enabling easy switching between different container types
-	or implementation strategies if needed in the future.
+	This function centralizes the creation of data containers used throughout the computation assembly-line, enabling
+	easy switching between different container types or implementation strategies if needed in the future.
 
 	Parameters
 	----------
 	shape
-		Either an integer (for 1D arrays) or a tuple of integers (for multi-dimensional arrays)
-		specifying the dimensions of the array.
+		Either an integer (for 1D arrays) or a tuple of integers (for multi-dimensional arrays) specifying the
+		dimensions of the array.
 	datatype
-		The NumPy integer type to use for the array elements, ensuring proper type
-		consistency and memory efficiency.
+		The NumPy integer type to use for the array elements, ensuring proper type consistency and memory efficiency.
 
 	Returns
 	-------
@@ -221,18 +214,17 @@ def outfitCountFolds(mapShape: tuple[int, ...], computationDivisions: int | str
 	"""
 	Initialize a `ComputationState` with validated parameters for map folding calculation.
 
-	This function serves as the central initialization point for creating a properly
-	configured `ComputationState` object, ensuring consistent calculation of the fundamental
-	parameters (`leavesTotal` and `taskDivisions`) across the entire package.
+	This function serves as the central initialization point for creating a properly configured `ComputationState`
+	object, ensuring consistent calculation of the fundamental parameters (`leavesTotal` and `taskDivisions`) across the
+	entire package.
 
 	Parameters
 	----------
 	mapShape
 		A tuple of integers representing the dimensions of the map.
 	computationDivisions: None
-		Controls how to divide the computation into parallel tasks. I know it is annoying,
-		but please see `getTaskDivisions` for details, so that you and I both know you have the most
-		accurate information.
+		Controls how to divide the computation into parallel tasks. I know it is annoying, but please see
+		`getTaskDivisions` for details, so that you and I both know you have the most accurate information.
 	concurrencyLimit: 1
 		Maximum number of concurrent processes to use during computation.
 
@@ -243,9 +235,8 @@ def outfitCountFolds(mapShape: tuple[int, ...], computationDivisions: int | str
 
 	Notes
 	-----
-	This function maintains the Single Source of Truth principle for `leavesTotal`
-	and `taskDivisions` calculation, ensuring these values are derived consistently
-	throughout the package.
+	This function maintains the Single Source of Truth principle for `leavesTotal` and `taskDivisions` calculation,
+	ensuring these values are derived consistently throughout the package.
 	"""
 	leavesTotal = getLeavesTotal(mapShape)
 	taskDivisions = getTaskDivisions(computationDivisions, concurrencyLimit, leavesTotal)
@@ -260,7 +251,8 @@ def setProcessorLimit(CPUlimit: Any | None, concurrencyPackage: str | None = Non
 	----------
 	CPUlimit: None
 		Controls processor usage limits:
-		- `False`, `None`, or `0`: No limits on processor usage; uses all available processors. All other values will potentially limit processor usage.
+		- `False`, `None`, or `0`: No limits on processor usage; uses all available processors. All other values will
+		potentially limit processor usage.
 		- `True`: Yes, limit the processor usage; limits to 1 processor.
 		- Integer `>= 1`: Limits usage to the specified number of processors.
 		- Decimal value (`float`) between 0 and 1: Fraction of total processors to use.
@@ -285,12 +277,12 @@ def setProcessorLimit(CPUlimit: Any | None, concurrencyPackage: str | None = Non
 
 	Notes
 	-----
-	If using `'numba'` as the concurrency package, the maximum number of processors is
-	retrieved from `numba.get_num_threads()` rather than by polling the hardware.
-	If Numba environment variables limit available processors, that will affect this function.
+	If using `'numba'` as the concurrency package, the maximum number of processors is retrieved from
+	`numba.get_num_threads()` rather than by polling the hardware. If Numba environment variables limit available
+	processors, that will affect this function.
 
-	When using Numba, this function must be called before importing any Numba-jitted
-	function for this processor limit to affect the Numba-jitted function.
+	When using Numba, this function must be called before importing any Numba-jitted function for this processor limit
+	to affect the Numba-jitted function.
 	"""
 	if not (CPUlimit is None or isinstance(CPUlimit, (bool, int, float))):
 		CPUlimit = oopsieKwargsie(CPUlimit)
@@ -312,9 +304,9 @@ def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
 	"""
 	Validate and normalize dimensions for a map folding problem.
 
-	This function serves as the gatekeeper for dimension inputs, ensuring that all
-	map dimensions provided to the package meet the requirements for valid computation.
-	It performs multiple validation steps and normalizes the dimensions into a consistent format.
+	This function serves as the gatekeeper for dimension inputs, ensuring that all map dimensions provided to the
+	package meet the requirements for valid computation. It performs multiple validation steps and normalizes the
+	dimensions into a consistent format.
 
 	Parameters
 	----------
@@ -323,8 +315,8 @@ def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
 
 	Returns
 	-------
-	tuple[int, ...]
-		A sorted tuple of positive integers representing the validated dimensions.
+	mapShape
+		An _unsorted_ tuple of positive integers representing the validated dimensions.
 
 	Raises
 	------
@@ -335,13 +327,27 @@ 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 = }` in `{listDimensions = }`, must be a non-negative integer.")
-		listNonNegative.append(dimension)
-	dimensionsValid = [dimension for dimension in listNonNegative if dimension > 0]
-	if len(dimensionsValid) < 2:
+	listOFint: list[int] = intInnit(listDimensions, 'listDimensions')
+	mapDimensions: list[int] = []
+	for dimension in listOFint:
+		if dimension <= 0:
+			raise ValueError(f"I received `{dimension = }` in `{listDimensions = }`, but all dimensions must be a non-negative integer.")
+		mapDimensions.append(dimension)
+	if len(mapDimensions) < 2:
 		raise NotImplementedError(f"This function requires `{listDimensions = }` to have at least two dimensions greater than 0. You may want to look at https://oeis.org/.")
-	return tuple(sorted(dimensionsValid))
+
+	"""
+	I previously sorted the dimensions for a few reasons that may or may not be valid:
+		1. After empirical testing, I believe that (2,10), for example, computes significantly faster than (10,2).
+		2. Standardization, generally.
+		3. If I recall correctly, after empirical testing, I concluded that sorted dimensions always leads to
+		non-negative values in the connection graph, but if the dimensions are not in ascending order of magnitude,
+		the connection graph might have negative values, which as far as I know, is not an inherent problem, but the
+		negative values propagate into other data structures, which requires the datatypes to hold negative values,
+		which means I cannot optimize the bit-widths of the datatypes as easily. (And optimized bit-widths helps with
+		performance.)
+
+	Furthermore, now that the package includes OEIS A000136, 1 x N stamps/maps, sorting could distort results.
+	"""
+	# NOTE Do NOT sort the dimensions.
+	return tuple(mapDimensions)

mapfolding-0.9.3/mapFolding/dataBaskets.py

@@ -0,0 +1,49 @@
+from mapFolding.beDRY import getConnectionGraph, getLeavesTotal, makeDataContainer
+from mapFolding.datatypes import Array3D, Array1DElephino, Array1DLeavesTotal, DatatypeElephino, DatatypeFoldsTotal, DatatypeLeavesTotal
+import dataclasses
+
+@dataclasses.dataclass
+class MapFoldingState:
+	mapShape: tuple[DatatypeLeavesTotal, ...] = dataclasses.field(init=True, metadata={'elementConstructor': 'DatatypeLeavesTotal'})
+
+	groupsOfFolds: DatatypeFoldsTotal = dataclasses.field(default=DatatypeFoldsTotal(0), metadata={'theCountingIdentifier': True})
+
+	gap1ndex: DatatypeElephino = DatatypeElephino(0)
+	gap1ndexCeiling: DatatypeElephino = DatatypeElephino(0)
+	indexDimension: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+	indexLeaf: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+	indexMiniGap: DatatypeElephino = DatatypeElephino(0)
+	leaf1ndex: DatatypeLeavesTotal = DatatypeLeavesTotal(1)
+	leafConnectee: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+
+	dimensionsUnconstrained: DatatypeLeavesTotal = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+
+	countDimensionsGapped: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	gapRangeStart: Array1DElephino = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DElephino.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	gapsWhere: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	leafAbove: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	leafBelow: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+
+	connectionGraph: Array3D = dataclasses.field(init=False, metadata={'dtype': Array3D.__args__[1].__args__[0]}) # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
+	dimensionsTotal: DatatypeLeavesTotal = dataclasses.field(init=False)
+	leavesTotal: DatatypeLeavesTotal = dataclasses.field(init=False)
+
+	@property
+	def foldsTotal(self) -> DatatypeFoldsTotal:
+		_foldsTotal = DatatypeFoldsTotal(self.leavesTotal) * self.groupsOfFolds
+		return _foldsTotal
+
+	def __post_init__(self) -> None:
+		self.dimensionsTotal = DatatypeLeavesTotal(len(self.mapShape))
+		self.leavesTotal = DatatypeLeavesTotal(getLeavesTotal(self.mapShape))
+
+		leavesTotalAsInt = int(self.leavesTotal)
+
+		self.connectionGraph = getConnectionGraph(self.mapShape, leavesTotalAsInt, self.__dataclass_fields__['connectionGraph'].metadata['dtype'])
+
+		if self.dimensionsUnconstrained is None: self.dimensionsUnconstrained = DatatypeLeavesTotal(int(self.dimensionsTotal)) # pyright: ignore[reportUnnecessaryComparison]
+		if self.gapsWhere is None: self.gapsWhere = makeDataContainer(leavesTotalAsInt * leavesTotalAsInt + 1, self.__dataclass_fields__['gapsWhere'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
+		if self.countDimensionsGapped is None: self.countDimensionsGapped = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['countDimensionsGapped'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
+		if self.gapRangeStart is None: self.gapRangeStart = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['gapRangeStart'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
+		if self.leafAbove is None: self.leafAbove = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafAbove'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
+		if self.leafBelow is None: self.leafBelow = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafBelow'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]