mapFolding 0.9.0__tar.gz → 0.9.2__tar.gz

{mapfolding-0.9.0 → mapfolding-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapFolding
-Version: 0.9.0
+Version: 0.9.2
 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
@@ -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

mapfolding-0.9.2/mapFolding/__init__.py

@@ -0,0 +1,94 @@
+"""
+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 pipeline
+	- 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.theSSOT import (
+	Array1DElephino as Array1DElephino,
+	Array1DFoldsTotal as Array1DFoldsTotal,
+	Array1DLeavesTotal as Array1DLeavesTotal,
+	Array3D as Array3D,
+	ComputationState as ComputationState,
+	DatatypeElephino as DatatypeElephino,
+	DatatypeFoldsTotal as DatatypeFoldsTotal,
+	DatatypeLeavesTotal as DatatypeLeavesTotal,
+	NumPyElephino as NumPyElephino,
+	NumPyFoldsTotal as NumPyFoldsTotal,
+	NumPyIntegerType as NumPyIntegerType,
+	NumPyLeavesTotal as NumPyLeavesTotal,
+	raiseIfNoneGitHubIssueNumber3 as raiseIfNoneGitHubIssueNumber3,
+	The as The,
+)
+
+from mapFolding.theDao import (
+	countInitialize as countInitialize,
+	doTheNeedful as doTheNeedful,
+)
+
+from mapFolding.beDRY import (
+	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.basecamp import countFolds as 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.2/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 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.
+	"""
+	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.0 → mapfolding-0.9.2}/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
@@ -30,9 +29,8 @@ 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.
+	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 +45,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 +111,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 +125,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 +165,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 +176,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 +193,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 +215,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 +236,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 +252,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 +278,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 +305,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,26 +316,39 @@ 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
 	------
 	ValueError
 		If the input is empty or contains negative values.
 	NotImplementedError
-		If fewer than two positive dimensions are provided, as this would not
-		represent a valid map folding problem.
+		If fewer than two positive dimensions are provided.
 	"""
 	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)