mapFolding 0.12.1__py3-none-any.whl → 0.12.3__py3-none-any.whl

mapFolding/__init__.py

@@ -1,22 +1,48 @@
-from typing import Any, TypeAlias
-import sys
-
-yourPythonIsOld: TypeAlias = Any
-# ruff: noqa: E402
-
-if sys.version_info >= (3, 11):
-	from typing import TypedDict as TypedDict
-	from typing import NotRequired as NotRequired
-else:
-	try:
-		from typing_extensions import TypedDict as TypedDict
-		from typing_extensions import NotRequired as NotRequired
-	except Exception:
-		TypedDict = dict[yourPythonIsOld, yourPythonIsOld]
-		from collections.abc import Iterable
-		NotRequired: TypeAlias = Iterable
-
-from mapFolding.datatypes import (
+"""Computational toolkit for analyzing multi-dimensional map folding patterns.
+
+(AI generated docstring)
+
+The mapFolding package provides a complete implementation of Lunnon's 1971 algorithm
+for counting distinct folding patterns in multi-dimensional maps. This toolkit
+transforms the complex combinatorial mathematics of map folding into accessible
+computational tools, enabling researchers and practitioners to analyze folding
+patterns across dimensions from simple 2D strips to complex multi-dimensional
+hypercubes.
+
+The package architecture follows Domain-Driven Design principles, organizing
+functionality around mathematical concepts rather than implementation details.
+The computational framework integrates type safety, persistent result storage,
+and mathematical validation through OEIS sequence integration.
+
+Core Transformation Tools:
+    countFolds: Primary interface for computing folding pattern counts
+    MapFoldingState: Computational state management for recursive analysis
+    Connection graph generation: Mathematical foundation for folding relationships
+    Task division utilities: Experimental parallel computation options
+    OEIS integration: Mathematical validation and sequence discovery
+
+Primary Use Cases:
+    Mathematical research into folding pattern properties and relationships
+    Educational exploration of combinatorial mathematics concepts
+    Computational validation of theoretical results
+    Extension of known mathematical sequences through new discoveries
+
+The package handles the full spectrum of map folding analysis, from simple
+educational examples to research-grade computations requiring multi-day processing
+time. Results integrate seamlessly with the mathematical community through
+comprehensive OEIS connectivity and standardized result persistence.
+
+For researchers: The computational foundation supports both replication of
+established results and discovery of new mathematical relationships.
+
+For educators: The clear interfaces and type safety enable confident exploration
+of combinatorial concepts without computational complexity barriers.
+
+For practitioners: The robust result persistence and type safety ensure
+reliable completion of complex analytical tasks.
+"""
+
+from mapFolding._theTypes import (
 	Array1DElephino as Array1DElephino,
 	Array1DFoldsTotal as Array1DFoldsTotal,
 	Array1DLeavesTotal as Array1DLeavesTotal,
@@ -30,7 +56,7 @@ from mapFolding.datatypes import (
 	NumPyLeavesTotal as NumPyLeavesTotal,
 )
 
-from mapFolding.theSSOT import PackageSettings as PackageSettings, packageSettings as packageSettings
+from mapFolding._theSSOT import packageSettings as packageSettings
 
 from mapFolding.beDRY import (
 	getConnectionGraph as getConnectionGraph,

mapFolding/_theSSOT.py

@@ -0,0 +1,81 @@
+"""
+Foundation layer for the map folding computational ecosystem.
+
+(AI generated docstring)
+
+This module establishes the fundamental configuration infrastructure that underpins
+all map folding operations. Map folding, as defined by Lunnon's 1971 algorithm,
+requires precise coordination of computational resources, type systems, and data
+flow management to solve the complex combinatorial problem of counting distinct
+folding patterns across multi-dimensional maps.
+
+The Single Source Of Truth (SSOT) principle governs this foundation, ensuring that
+package identity, filesystem locations, and concurrency configuration remain
+consistent across all computational phases. During packaging, static metadata is
+resolved from pyproject.toml. During installation, filesystem-dependent paths are
+dynamically discovered. During runtime, the `packageSettings` instance provides
+unified access to all configuration values, enabling the sophisticated computational
+framework that follows.
+
+This configuration foundation supports the type system definition, core utility
+functions, computational state management, result persistence, and ultimately the
+main computational interface that users interact with to solve map folding problems.
+"""
+
+from hunterMakesPy import PackageSettings
+import dataclasses
+
+packageNameHARDCODED = "mapFolding"
+"""Hardcoded package name used as fallback when dynamic resolution fails."""
+
+concurrencyPackageHARDCODED = 'multiprocessing'
+"""Default package identifier for concurrent execution operations."""
+
+@dataclasses.dataclass
+class mapFoldingPackageSettings(PackageSettings):
+	"""Centralized configuration container for all package-wide settings.
+
+	(AI generated docstring)
+
+	This dataclass serves as the single source of truth for package configuration,
+	providing both static and dynamically-resolved values needed throughout the
+	package lifecycle. The metadata on each field indicates when that value is
+	determined - either during packaging or at installation/runtime.
+
+	The design supports different evaluation phases to optimize performance and
+	reliability. Packaging-time values can be determined during package creation,
+	while installing-time values require filesystem access or module introspection.
+
+	Attributes
+	----------
+	fileExtension : str = '.py'
+		Standard file extension for Python modules in this package.
+	packageName : str
+		Canonical name of the package as defined in project configuration.
+	pathPackage : Path
+		Absolute filesystem path to the installed package directory.
+	concurrencyPackage : str | None = None
+		Package identifier for concurrent execution operations.
+
+	"""
+
+	concurrencyPackage: str | None = None
+	"""
+	Package identifier for concurrent execution operations.
+
+	(AI generated docstring)
+
+	Specifies which Python package should be used for parallel processing
+	in computationally intensive operations. When None, the default concurrency
+	package specified in the module constants is used. Accepted values include
+	'multiprocessing' for standard parallel processing and 'numba' for
+	specialized numerical computations.
+	"""
+
+concurrencyPackage = concurrencyPackageHARDCODED
+"""Active concurrency package configuration for the current session."""
+
+packageSettings = mapFoldingPackageSettings(
+	identifierPackageFALLBACK=packageNameHARDCODED
+	, concurrencyPackage=concurrencyPackage)
+"""Global package settings."""

mapFolding/_theTypes.py

@@ -0,0 +1,148 @@
+"""
+Type system architecture for map folding computational domains.
+
+(AI generated docstring)
+
+Building upon the configuration foundation, this module defines the complete type
+hierarchy that ensures type safety and semantic clarity throughout the map folding
+computational framework. The type system recognizes three distinct computational
+domains, each with specific data characteristics and performance requirements
+that emerge from Lunnon's algorithm implementation.
+
+The Leaves domain handles map sections, their indices, and dimensional parameters.
+The Elephino domain manages internal computational state, gap calculations, and
+temporary indices used during the recursive folding analysis. The Folds domain
+represents final pattern counts and computation results. Each domain employs both
+Python types for general computation and NumPy types for performance-critical
+array operations.
+
+This dual-type strategy enables the core utility functions to operate with type
+safety while maintaining the computational efficiency required for analyzing
+complex multi-dimensional folding patterns. The array types built from these
+base types provide the structured data containers that computational state
+management depends upon.
+"""
+from numpy import dtype, integer, ndarray, uint8 as numpy_uint8, uint16 as numpy_uint16, uint64 as numpy_uint64
+from typing import Any, TypeAlias, TypeVar
+
+NumPyIntegerType = TypeVar('NumPyIntegerType', bound=integer[Any], covariant=True)
+"""
+Generic type variable for NumPy integer types used in computational operations.
+
+(AI generated docstring)
+
+This type variable enables generic programming with NumPy integer types while
+maintaining type safety. It supports covariant relationships between different
+NumPy integer types and their array containers.
+"""
+
+DatatypeLeavesTotal: TypeAlias = int
+"""
+Python type for leaf-related counts and indices in map folding computations.
+
+(AI generated docstring)
+
+Represents quantities related to individual map sections (leaves), including
+total leaf counts, leaf indices, and dimensional parameters. Uses standard
+Python integers for compatibility with general computations while enabling
+conversion to NumPy types when performance optimization is needed.
+"""
+
+NumPyLeavesTotal: TypeAlias = numpy_uint8
+"""
+NumPy type for efficient leaf-related computations and array operations.
+
+(AI generated docstring)
+
+Corresponds to `DatatypeLeavesTotal` but optimized for NumPy operations.
+Uses 8-bit unsigned integers since leaf counts in practical map folding
+scenarios typically remain small (under 256).
+"""
+
+DatatypeElephino: TypeAlias = int
+"""
+Python type for internal computational indices and intermediate values.
+
+(AI generated docstring)
+
+Used for temporary variables, gap indices, and other internal computational
+state that doesn't directly correspond to leaves or final fold counts. The
+name follows the package convention for internal computational domains.
+"""
+
+NumPyElephino: TypeAlias = numpy_uint16
+"""
+NumPy type for internal computational operations requiring moderate value ranges.
+
+(AI generated docstring)
+
+Corresponds to `DatatypeElephino` with 16-bit unsigned integer storage,
+providing sufficient range for internal computations while maintaining
+memory efficiency in array operations.
+"""
+
+DatatypeFoldsTotal: TypeAlias = int
+"""
+Python type for final fold counts and pattern totals.
+
+(AI generated docstring)
+
+Represents the ultimate results of map folding computations - the total number
+of distinct folding patterns possible for a given map configuration. These
+values can grow exponentially with map size, requiring flexible integer types.
+"""
+
+NumPyFoldsTotal: TypeAlias = numpy_uint64
+"""
+NumPy type for large fold count computations and high-precision results.
+
+(AI generated docstring)
+
+Corresponds to `DatatypeFoldsTotal` using 64-bit unsigned integers to
+accommodate the exponentially large values that can result from map folding
+computations on even moderately-sized maps.
+"""
+
+Array3D: TypeAlias = ndarray[tuple[int, int, int], dtype[NumPyLeavesTotal]]
+"""
+Three-dimensional NumPy array type for connection graph representations.
+
+(AI generated docstring)
+
+Used to store the connectivity relationships between map leaves in a
+3D array structure. The array uses `NumPyLeavesTotal` element type since
+the stored values represent leaf indices and connection states.
+"""
+
+Array1DLeavesTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyLeavesTotal]]
+"""
+One-dimensional NumPy array type for leaf-related data sequences.
+
+(AI generated docstring)
+
+Stores sequences of leaf counts, indices, or related values in efficient
+array format. Common uses include leaf sequences, gap locations, and
+dimensional data where each element relates to the leaves domain.
+"""
+
+Array1DElephino: TypeAlias = ndarray[tuple[int], dtype[NumPyElephino]]
+"""
+One-dimensional NumPy array type for internal computational sequences.
+
+(AI generated docstring)
+
+Used for storing sequences of internal computational values such as
+gap range starts, temporary indices, and other intermediate results
+that require the elephino computational domain's value range.
+"""
+
+Array1DFoldsTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyFoldsTotal]]
+"""
+One-dimensional NumPy array type for sequences of fold count results.
+
+(AI generated docstring)
+
+Stores sequences of fold totals and pattern counts, using the large
+integer type to accommodate the potentially enormous values that
+result from complex map folding computations.
+"""

mapFolding/basecamp.py

@@ -1,27 +1,37 @@
 """
-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.
+Unified interface for map folding computation orchestration.
+
+(AI generated docstring)
+
+This module represents the culmination of the computational ecosystem, providing
+the primary entry point where users interact with the complete map folding analysis
+system. It orchestrates all preceding layers: the configuration foundation,
+type system, core utilities, state management, and persistent storage to deliver
+a seamless computational experience.
+
+The interface handles multiple computation flows including sequential algorithms,
+experimental task division strategies, and various mathematical theorem implementations.
+It provides flexible parameter validation, computation method selection, task
+division management, processor utilization control, and automatic result persistence.
+Integration with OEIS sequences enables research validation and mathematical
+verification of computed results.
+
+Through this unified interface, researchers and practitioners can access the full
+power of Lunnon's algorithm implementation while the underlying computational
+complexity remains elegantly abstracted. The interface ensures that whether
+solving simple 2D problems or complex multi-dimensional challenges, users receive
+consistent, reliable, and efficiently computed folding pattern counts.
 """
 
 from collections.abc import Sequence
 from mapFolding import (
-	getPathFilenameFoldsTotal,
-	packageSettings,
-	saveFoldsTotal,
-	saveFoldsTotalFAILearly,
-	setProcessorLimit,
-	validateListDimensions,
-)
+	getPathFilenameFoldsTotal, packageSettings, saveFoldsTotal, saveFoldsTotalFAILearly, setProcessorLimit,
+	validateListDimensions)
 from os import PathLike
 from pathlib import PurePath
+import contextlib
 
-def countFolds(listDimensions: Sequence[int] | None = None
+def countFolds(listDimensions: Sequence[int] | None = None  # noqa: C901
 				, pathLikeWriteFoldsTotal: PathLike[str] | PurePath | None = None
 				, computationDivisions: int | str | None = None
 				, CPUlimit: int | float | bool | None = None
@@ -34,6 +44,8 @@ def countFolds(listDimensions: Sequence[int] | None = None
 	"""
 	Count the total number of possible foldings for a given map dimensions.
 
+	(AI generated docstring)
+
 	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.
 
@@ -78,32 +90,33 @@ def countFolds(listDimensions: Sequence[int] | None = None
 	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 =====================================================================
+	# mapShape ---------------------------------------------------------------------
 
 	if mapShape:
 		pass
 	else:
 		if oeisID and oeis_n:
-			from mapFolding.oeis import settingsOEIS
-			try:
+			from mapFolding.oeis import settingsOEIS  # noqa: PLC0415
+			with contextlib.suppress(KeyError):
 				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:
+		message = (
+			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.""")
+	but I was unable to select a map for which to count the folds."""
+		)
+		raise ValueError(message)
 
-	# task division instructions ===============================================
+	# task division instructions -----------------------------------------------------
 
 	if computationDivisions:
 		concurrencyLimit: int = setProcessorLimit(CPUlimit, packageSettings.concurrencyPackage)
-		from mapFolding.beDRY import getLeavesTotal, getTaskDivisions
+		from mapFolding.beDRY import getLeavesTotal, getTaskDivisions  # noqa: PLC0415
 		leavesTotal: int = getLeavesTotal(mapShape)
 		taskDivisions = getTaskDivisions(computationDivisions, concurrencyLimit, leavesTotal)
 		del leavesTotal
@@ -111,7 +124,7 @@ def countFolds(listDimensions: Sequence[int] | None = None
 		concurrencyLimit = 1
 		taskDivisions = 0
 
-	# memorialization instructions ===========================================
+	# memorialization instructions ---------------------------------------------
 
 	if pathLikeWriteFoldsTotal is not None:
 		pathFilenameFoldsTotal = getPathFilenameFoldsTotal(mapShape, pathLikeWriteFoldsTotal)
@@ -119,68 +132,70 @@ def countFolds(listDimensions: Sequence[int] | None = None
 	else:
 		pathFilenameFoldsTotal = None
 
-	# Flow control until I can figure out a good way ===============================
+	# Flow control until I can figure out a good way ---------------------------------
 
 	if flow == 'daoOfMapFolding':
-		from mapFolding.dataBaskets import MapFoldingState
+		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
-		from mapFolding.daoOfMapFolding import doTheNeedful
+		from mapFolding.daoOfMapFolding import doTheNeedful  # noqa: PLC0415
 		mapFoldingState = doTheNeedful(mapFoldingState)
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif flow == 'theorem2' and any((dimension > 2 for dimension in mapShape)):
-		from mapFolding.dataBaskets import MapFoldingState
+	elif flow == 'theorem2' and any(dimension > 2 for dimension in mapShape):  # noqa: PLR2004
+		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
-		from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds
+		from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds  # noqa: PLC0415
 		mapFoldingState = initializeGroupsOfFolds(mapFoldingState)
 
-		from mapFolding.syntheticModules.theorem2 import count
+		from mapFolding.syntheticModules.theorem2 import count  # noqa: PLC0415
 		mapFoldingState = count(mapFoldingState)
 
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif flow == 'theorem2Trimmed' and any((dimension > 2 for dimension in mapShape)):
-		from mapFolding.dataBaskets import MapFoldingState
+	elif flow == 'theorem2Trimmed' and any(dimension > 2 for dimension in mapShape):  # noqa: PLR2004
+		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
-		from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds
+		from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds  # noqa: PLC0415
 		mapFoldingState = initializeGroupsOfFolds(mapFoldingState)
 
-		from mapFolding.syntheticModules.theorem2Trimmed import count
+		from mapFolding.syntheticModules.theorem2Trimmed import count  # noqa: PLC0415
 		mapFoldingState = count(mapFoldingState)
 
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif (flow == 'theorem2Numba' or taskDivisions == 0) and any((dimension > 2 for dimension in mapShape)):
-		from mapFolding.dataBaskets import MapFoldingState
+	elif (flow == 'theorem2Numba' or taskDivisions == 0) and any(dimension > 2 for dimension in mapShape):  # noqa: PLR2004
+		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
-		from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds
+		from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds  # noqa: PLC0415
 		mapFoldingState = initializeGroupsOfFolds(mapFoldingState)
 
-		from mapFolding.syntheticModules.dataPacking import sequential
+		from mapFolding.syntheticModules.dataPacking import sequential  # noqa: PLC0415
 		mapFoldingState = sequential(mapFoldingState)
 
 		foldsTotal = mapFoldingState.foldsTotal
 
 	elif taskDivisions > 1:
-		from mapFolding.dataBaskets import ParallelMapFoldingState
+		from mapFolding.dataBaskets import ParallelMapFoldingState  # noqa: PLC0415
 		parallelMapFoldingState: ParallelMapFoldingState = ParallelMapFoldingState(mapShape, taskDivisions=taskDivisions)
 
-		from mapFolding.syntheticModules.countParallel import doTheNeedful
-		foldsTotal, listStatesParallel = doTheNeedful(parallelMapFoldingState, concurrencyLimit)
+		from mapFolding.syntheticModules.countParallel import doTheNeedful  # noqa: PLC0415
+
+		# `listStatesParallel` exists in case you want to research the parallel computation.
+		foldsTotal, listStatesParallel = doTheNeedful(parallelMapFoldingState, concurrencyLimit) # pyright: ignore[reportUnusedVariable]
 
 	else:
-		from mapFolding.dataBaskets import MapFoldingState
+		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
-		from mapFolding.syntheticModules.daoOfMapFolding import doTheNeedful
+		from mapFolding.syntheticModules.daoOfMapFolding import doTheNeedful  # noqa: PLC0415
 		mapFoldingState = doTheNeedful(mapFoldingState)
 		foldsTotal = mapFoldingState.foldsTotal
 
-	# Follow memorialization instructions ===========================================
+	# Follow memorialization instructions ---------------------------------------------
 
 	if pathFilenameFoldsTotal is not None:
 		saveFoldsTotal(pathFilenameFoldsTotal, foldsTotal)