mapFolding 0.12.0__tar.gz → 0.12.2__tar.gz

mapfolding-0.12.2/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: mapFolding
+Version: 0.12.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
+Project-URL: Donate, https://www.patreon.com/integrated
+Project-URL: Homepage, https://github.com/hunterhogan/mapFolding
+Project-URL: Issues, https://github.com/hunterhogan/mapFolding/issues
+Project-URL: Repository, https://github.com/hunterhogan/mapFolding.git
+Keywords: A000136,A001415,A001416,A001417,A001418,A195646,AST manipulation,Numba optimization,OEIS,algorithmic optimization,code generation,code transformation,combinatorics,computational geometry,dataclass transformation,folding pattern enumeration,just-in-time compilation,map folding,performance optimization,source code analysis,stamp folding
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Z0Z_tools
+Requires-Dist: astToolkit>=0.5.0
+Requires-Dist: autoflake
+Requires-Dist: numba
+Requires-Dist: numba_progress
+Requires-Dist: numpy
+Requires-Dist: platformdirs
+Requires-Dist: python_minifier
+Requires-Dist: sympy
+Requires-Dist: tomli
+Provides-Extra: testing
+Requires-Dist: mypy; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: pytest-env; extra == "testing"
+Requires-Dist: pytest-xdist; extra == "testing"
+Requires-Dist: pyupgrade; extra == "testing"
+Requires-Dist: ruff; extra == "testing"
+Requires-Dist: setuptools-scm; extra == "testing"
+Dynamic: license-file
+
+# mapFolding
+
+[![pip install mapFolding](https://img.shields.io/badge/pip%20install-mapFolding-gray.svg?colorB=3b434b)](https://pypi.org/project/mapFolding/)
+[![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
+[![License: CC-BY-NC-4.0](https://img.shields.io/badge/License-CC_BY--NC_4.0-3b434b)](https://creativecommons.org/licenses/by-nc/4.0/)
+
+A computational framework that starts with Lunnon's 1971 algorithm for counting distinct ways to fold maps and improves it. Plus there is a comprehensive AST transformation system for transforming algorithms for optimization and research.
+
+(Yo, the rest is AI generated and I don't have the energy to proofread it. This package helped me compute two previously unknown values: I'm sure others can improve it.)
+
+## The Mathematical Problem
+
+Map folding is a combinatorial problem: given a rectangular grid of unit squares, how many distinct ways can you fold it? "Distinct" means that foldings producing identical final shapes are counted as one. This problem connects to combinatorial geometry, integer sequences, and computational complexity theory.
+
+The calculations extend the Online Encyclopedia of Integer Sequences (OEIS):
+
+- **A001415**: 2×n strips (computed through n=20 for the first time)
+- **A001418**: n×n squares
+- **A001416**: 3×n strips
+- **A001417**: n-dimensional hypercubes
+- **A195646**: 3×3×...×3 hypercubes
+
+```python
+from mapFolding import oeisIDfor_n
+
+# How many ways can you fold a 2×4 strip?
+foldsTotal = oeisIDfor_n('A001415', 4)
+```
+
+## The Computational Challenge
+
+For larger maps, these calculations require hours or days to complete. A 2×20 strip requires processing leaves through billions of recursive operations. The package addresses this through systematic algorithm transformation: converting readable Python implementations into specialized, Numba-optimized modules that achieve order-of-magnitude performance improvements.
+
+## What This Package Provides
+
+### Core Functionality
+
+- **Complete implementation** of Lunnon's recursive algorithm
+- **Mathematical validation** through OEIS integration and caching
+- **Type-safe computational state** management with automatic initialization
+- **Result persistence** for long-running calculations
+
+### Algorithm Transformation System
+
+- **AST manipulation framework** for converting dataclass-based algorithms to optimized implementations
+- **Automatic code generation** that produces standalone, highly optimized computation modules
+- **Dataclass decomposition** to enable Numba compatibility while preserving readable source code
+- **Comprehensive optimization** including dead code elimination, static value embedding, and aggressive compilation settings
+
+### Educational Resources
+
+- **Historical implementations** showing algorithm evolution from 1971 to present
+- **Performance comparison** studies demonstrating optimization techniques
+- **Complete test suite** with patterns for validating custom implementations
+- **Reference documentation** for extending the transformation framework
+
+## Use Cases
+
+**Mathematical Research**: Explore folding pattern properties, extend known sequences, or validate theoretical results against computed values.
+
+**Algorithm Optimization Learning**: Study a complete transformation pipeline that converts high-level algorithms into production-ready optimized code.
+
+**Performance Computing Education**: Examine techniques for achieving maximum Python performance through Numba integration, AST manipulation, and specialized code generation.
+
+**Combinatorial Problem Solving**: Use the framework as a template for optimizing other recursive combinatorial algorithms.
+
+## Example Usage
+
+```python
+from mapFolding import countFolds
+
+# Count folding patterns for a 3×3 square
+result = countFolds([3, 3])
+
+# Access OEIS sequences directly
+from mapFolding import oeisIDfor_n
+strip_foldings = oeisIDfor_n('A001415', 6)  # 2×6 strip
+
+# Generate optimized code for specific dimensions
+from mapFolding.someAssemblyRequired import makeJobTheorem2Numba
+# Creates specialized modules for maximum performance
+```
+
+## Repository Structure
+
+- `mapFolding/`: Core implementation with modular architecture
+- `reference/`: Historical algorithm implementations and performance studies
+- `someAssemblyRequired/`: AST transformation framework
+- `tests/`: Comprehensive validation suite
+- `jobs/`: Generated optimized modules for specific calculations
+
+## Performance Characteristics
+
+- **Pure Python baseline**: Educational implementations for understanding
+- **NumPy optimization**: ~10× improvement through vectorized operations
+- **Numba compilation**: ~100× improvement through native code generation
+- **Specialized modules**: ~1000× improvement through static optimization and embedded constants
+
+Actual performance varies by map dimensions and available hardware.
+
+## My recovery
+
+[![Static Badge](https://img.shields.io/badge/2011_August-Homeless_since-blue?style=flat)](https://HunterThinks.com/support)
+[![YouTube Channel Subscribers](https://img.shields.io/youtube/channel/subscribers/UC3Gx7kz61009NbhpRtPP7tw)](https://www.youtube.com/@HunterHogan)
+
+## How to code
+
+Coding One Step at a Time:
+
+0. WRITE CODE.
+1. Don't write stupid code that's hard to revise.
+2. Write good code.
+3. When revising, write better code.
+
+[![CC-BY-NC-4.0](https://github.com/hunterhogan/mapFolding/blob/main/CC-BY-NC-4.0.svg)](https://creativecommons.org/licenses/by-nc/4.0/)

mapfolding-0.12.2/README.md

@@ -0,0 +1,115 @@
+# mapFolding
+
+[![pip install mapFolding](https://img.shields.io/badge/pip%20install-mapFolding-gray.svg?colorB=3b434b)](https://pypi.org/project/mapFolding/)
+[![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
+[![License: CC-BY-NC-4.0](https://img.shields.io/badge/License-CC_BY--NC_4.0-3b434b)](https://creativecommons.org/licenses/by-nc/4.0/)
+
+A computational framework that starts with Lunnon's 1971 algorithm for counting distinct ways to fold maps and improves it. Plus there is a comprehensive AST transformation system for transforming algorithms for optimization and research.
+
+(Yo, the rest is AI generated and I don't have the energy to proofread it. This package helped me compute two previously unknown values: I'm sure others can improve it.)
+
+## The Mathematical Problem
+
+Map folding is a combinatorial problem: given a rectangular grid of unit squares, how many distinct ways can you fold it? "Distinct" means that foldings producing identical final shapes are counted as one. This problem connects to combinatorial geometry, integer sequences, and computational complexity theory.
+
+The calculations extend the Online Encyclopedia of Integer Sequences (OEIS):
+
+- **A001415**: 2×n strips (computed through n=20 for the first time)
+- **A001418**: n×n squares
+- **A001416**: 3×n strips
+- **A001417**: n-dimensional hypercubes
+- **A195646**: 3×3×...×3 hypercubes
+
+```python
+from mapFolding import oeisIDfor_n
+
+# How many ways can you fold a 2×4 strip?
+foldsTotal = oeisIDfor_n('A001415', 4)
+```
+
+## The Computational Challenge
+
+For larger maps, these calculations require hours or days to complete. A 2×20 strip requires processing leaves through billions of recursive operations. The package addresses this through systematic algorithm transformation: converting readable Python implementations into specialized, Numba-optimized modules that achieve order-of-magnitude performance improvements.
+
+## What This Package Provides
+
+### Core Functionality
+
+- **Complete implementation** of Lunnon's recursive algorithm
+- **Mathematical validation** through OEIS integration and caching
+- **Type-safe computational state** management with automatic initialization
+- **Result persistence** for long-running calculations
+
+### Algorithm Transformation System
+
+- **AST manipulation framework** for converting dataclass-based algorithms to optimized implementations
+- **Automatic code generation** that produces standalone, highly optimized computation modules
+- **Dataclass decomposition** to enable Numba compatibility while preserving readable source code
+- **Comprehensive optimization** including dead code elimination, static value embedding, and aggressive compilation settings
+
+### Educational Resources
+
+- **Historical implementations** showing algorithm evolution from 1971 to present
+- **Performance comparison** studies demonstrating optimization techniques
+- **Complete test suite** with patterns for validating custom implementations
+- **Reference documentation** for extending the transformation framework
+
+## Use Cases
+
+**Mathematical Research**: Explore folding pattern properties, extend known sequences, or validate theoretical results against computed values.
+
+**Algorithm Optimization Learning**: Study a complete transformation pipeline that converts high-level algorithms into production-ready optimized code.
+
+**Performance Computing Education**: Examine techniques for achieving maximum Python performance through Numba integration, AST manipulation, and specialized code generation.
+
+**Combinatorial Problem Solving**: Use the framework as a template for optimizing other recursive combinatorial algorithms.
+
+## Example Usage
+
+```python
+from mapFolding import countFolds
+
+# Count folding patterns for a 3×3 square
+result = countFolds([3, 3])
+
+# Access OEIS sequences directly
+from mapFolding import oeisIDfor_n
+strip_foldings = oeisIDfor_n('A001415', 6)  # 2×6 strip
+
+# Generate optimized code for specific dimensions
+from mapFolding.someAssemblyRequired import makeJobTheorem2Numba
+# Creates specialized modules for maximum performance
+```
+
+## Repository Structure
+
+- `mapFolding/`: Core implementation with modular architecture
+- `reference/`: Historical algorithm implementations and performance studies
+- `someAssemblyRequired/`: AST transformation framework
+- `tests/`: Comprehensive validation suite
+- `jobs/`: Generated optimized modules for specific calculations
+
+## Performance Characteristics
+
+- **Pure Python baseline**: Educational implementations for understanding
+- **NumPy optimization**: ~10× improvement through vectorized operations
+- **Numba compilation**: ~100× improvement through native code generation
+- **Specialized modules**: ~1000× improvement through static optimization and embedded constants
+
+Actual performance varies by map dimensions and available hardware.
+
+## My recovery
+
+[![Static Badge](https://img.shields.io/badge/2011_August-Homeless_since-blue?style=flat)](https://HunterThinks.com/support)
+[![YouTube Channel Subscribers](https://img.shields.io/youtube/channel/subscribers/UC3Gx7kz61009NbhpRtPP7tw)](https://www.youtube.com/@HunterHogan)
+
+## How to code
+
+Coding One Step at a Time:
+
+0. WRITE CODE.
+1. Don't write stupid code that's hard to revise.
+2. Write good code.
+3. When revising, write better code.
+
+[![CC-BY-NC-4.0](https://github.com/hunterhogan/mapFolding/blob/main/CC-BY-NC-4.0.svg)](https://creativecommons.org/licenses/by-nc/4.0/)

mapfolding-0.12.2/mapFolding/__init__.py

@@ -0,0 +1,86 @@
+"""Computational toolkit for analyzing multi-dimensional map folding patterns.
+
+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.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 PackageSettings as PackageSettings, packageSettings as packageSettings
+
+from mapFolding.beDRY import (
+	getConnectionGraph as getConnectionGraph,
+	getLeavesTotal as getLeavesTotal,
+	getTaskDivisions as getTaskDivisions,
+	makeDataContainer as makeDataContainer,
+	setProcessorLimit as setProcessorLimit,
+	validateListDimensions as validateListDimensions,
+)
+
+from mapFolding.dataBaskets import MapFoldingState as MapFoldingState
+
+from mapFolding.filesystemToolkit import (
+	getFilenameFoldsTotal as getFilenameFoldsTotal,
+	getPathFilenameFoldsTotal as getPathFilenameFoldsTotal,
+	getPathRootJobDEFAULT as getPathRootJobDEFAULT,
+	saveFoldsTotal as saveFoldsTotal,
+	saveFoldsTotalFAILearly as saveFoldsTotalFAILearly,
+)
+
+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.12.2/mapFolding/_theSSOT.py

@@ -0,0 +1,137 @@
+"""
+Foundation layer for the map folding computational ecosystem.
+
+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 importlib import import_module as importlib_import_module
+from inspect import getfile as inspect_getfile
+from pathlib import Path
+from tomli import load as tomli_load
+import dataclasses
+
+packageNamePACKAGING_HARDCODED = "mapFolding"
+"""
+Hardcoded package name used as fallback when dynamic resolution fails.
+
+This constant serves as the ultimate fallback for package name resolution,
+ensuring the package can function even when pyproject.toml is not accessible
+during packaging or when module introspection fails during installation.
+"""
+
+concurrencyPackageHARDCODED = 'multiprocessing'
+"""
+Default package identifier for concurrent execution operations.
+
+Specifies which Python concurrency package should be used as the default
+for parallel computations. This can be overridden through PackageSettings
+to use alternative packages like 'numba' for specialized performance scenarios.
+"""
+
+# Evaluate When Packaging
+# https://github.com/hunterhogan/mapFolding/issues/18
+try:
+	packageNamePACKAGING: str = tomli_load(Path("../pyproject.toml").open('rb'))["project"]["name"]
+	"""
+	Package name dynamically resolved from pyproject.toml during packaging.
+
+	This value is determined by reading the project configuration file during
+	the packaging process, ensuring consistency between the package metadata
+	and runtime identification. Falls back to hardcoded value if resolution fails.
+	"""
+except Exception:
+	packageNamePACKAGING = packageNamePACKAGING_HARDCODED
+
+# Evaluate When Installing
+# https://github.com/hunterhogan/mapFolding/issues/18
+def getPathPackageINSTALLING() -> Path:
+	"""
+	Resolve the absolute filesystem path to the installed package directory.
+
+	This function determines the package location at runtime by introspecting
+	the imported module's file location. It handles both regular Python files
+	and package directories, ensuring reliable path resolution across different
+	installation methods and environments.
+
+	Returns:
+		pathPackage: Absolute path to the package directory containing the module files.
+
+	Notes:
+		The function automatically handles the case where module introspection
+		returns a file path by extracting the parent directory, ensuring the
+		returned path always points to the package directory itself.
+	"""
+	pathPackage: Path = Path(inspect_getfile(importlib_import_module(packageNamePACKAGING)))
+	if pathPackage.is_file():
+		pathPackage = pathPackage.parent
+	return pathPackage
+
+@dataclasses.dataclass
+class PackageSettings:
+	"""
+	Centralized configuration container for all package-wide settings.
+
+	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 that can be determined during package creation
+	- Installing-time: Values that require filesystem access or module introspection
+
+	Attributes:
+		fileExtension: Standard file extension for Python modules in this package.
+		packageName: Canonical name of the package as defined in project configuration.
+		pathPackage: Absolute filesystem path to the installed package directory.
+		concurrencyPackage: Package to use for concurrent execution operations.
+	"""
+	fileExtension: str = dataclasses.field(default='.py', metadata={'evaluateWhen': 'installing'})
+	packageName: str = dataclasses.field(default = packageNamePACKAGING, metadata={'evaluateWhen': 'packaging'})
+	pathPackage: Path = dataclasses.field(default_factory=getPathPackageINSTALLING, metadata={'evaluateWhen': 'installing'})
+	concurrencyPackage: str | None = None
+	"""
+	Package identifier for concurrent execution operations.
+
+	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.
+
+This module-level variable holds the currently selected concurrency package
+identifier, initialized from the hardcoded default but available for runtime
+modification through the package settings system.
+"""
+
+packageSettings = PackageSettings(concurrencyPackage=concurrencyPackage)
+"""
+Global package settings instance providing access to all configuration values.
+
+This singleton instance serves as the primary interface for accessing package
+configuration throughout the codebase. It combines statically-defined defaults
+with dynamically-resolved values to provide a complete configuration profile
+for the current package installation and runtime environment.
+"""

{mapfolding-0.12.0 → mapfolding-0.12.2}/mapFolding/basecamp.py

@@ -1,22 +1,30 @@
 """
-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.
+
+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
@@ -129,7 +137,7 @@ def countFolds(listDimensions: Sequence[int] | None = None
 		mapFoldingState = doTheNeedful(mapFoldingState)
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif flow == 'theorem2' and any((dimension > 2 for dimension in mapShape)):
+	elif flow == 'theorem2' and any(dimension > 2 for dimension in mapShape):
 		from mapFolding.dataBaskets import MapFoldingState
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
@@ -141,7 +149,7 @@ def countFolds(listDimensions: Sequence[int] | None = None
 
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif flow == 'theorem2Trimmed' and any((dimension > 2 for dimension in mapShape)):
+	elif flow == 'theorem2Trimmed' and any(dimension > 2 for dimension in mapShape):
 		from mapFolding.dataBaskets import MapFoldingState
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
@@ -153,7 +161,7 @@ def countFolds(listDimensions: Sequence[int] | None = None
 
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif (flow == 'theorem2Numba' or taskDivisions == 0) and any((dimension > 2 for dimension in mapShape)):
+	elif (flow == 'theorem2Numba' or taskDivisions == 0) and any(dimension > 2 for dimension in mapShape):
 		from mapFolding.dataBaskets import MapFoldingState
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
@@ -170,7 +178,9 @@ def countFolds(listDimensions: Sequence[int] | None = None
 		parallelMapFoldingState: ParallelMapFoldingState = ParallelMapFoldingState(mapShape, taskDivisions=taskDivisions)
 
 		from mapFolding.syntheticModules.countParallel import doTheNeedful
-		foldsTotal, listStatesParallel = doTheNeedful(parallelMapFoldingState, concurrencyLimit)
+
+		# `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

{mapfolding-0.12.0 → mapfolding-0.12.2}/mapFolding/beDRY.py

@@ -1,30 +1,32 @@
 """
-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:
-
-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.
-3. Provide centralized resource allocation and system limits management.
-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.
-
-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.
+Core computational utilities implementing Lunnon's map folding algorithm.
+
+With the configuration foundation established and the type system defined, this
+module provides the essential building blocks that transform mathematical theory
+into executable computation. These utilities implement the fundamental operations
+required by Lunnon's 1971 algorithm, handling dimension validation, connection
+graph generation, and computational resource management.
+
+The connection graph generation represents the mathematical heart of the algorithm,
+calculating how leaves connect across dimensions using coordinate systems, parity
+rules, and boundary conditions. This graph becomes the foundation upon which the
+recursive folding analysis operates. Validation functions ensure computational
+of large-scale problems. Validation functions ensure computational
+integrity, while task division management enables experimental task division strategies.
+
+These utilities follow DRY and SSOT principles, providing reusable functions that
+serve as the computational assembly-line components. They prepare the essential
+data structures and computational parameters that the state management system
+requires to orchestrate the complex recursive algorithms.
 """
+
 from collections.abc import Sequence
-from mapFolding import Array1DElephino, Array1DFoldsTotal, Array1DLeavesTotal, Array3D, DatatypeElephino, DatatypeFoldsTotal, DatatypeLeavesTotal, NumPyIntegerType
+from mapFolding import NumPyIntegerType
 from numpy import dtype as numpy_dtype, int64 as numpy_int64, ndarray
 from sys import maxsize as sysMaxsize
 from typing import Any
 from Z0Z_tools import defineConcurrencyLimit, intInnit, oopsieKwargsie
 import numpy
-import dataclasses
 
 def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
 	"""