mapFolding 0.8.1__tar.gz → 0.8.2__tar.gz

{mapfolding-0.8.1 → mapfolding-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapFolding
-Version: 0.8.1
+Version: 0.8.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
@@ -99,51 +99,75 @@ Available OEIS sequences:
   A195646: Number of ways of folding a 3 X 3 X ... X 3 n-dimensional map.
 ```
 
-### 2. **Algorithm Zoo** 🦒
+### 2. **Algorithm Zoo: A Historical and Performance Journey** 🦒
 
-- **Lunnon's 1971 Algorithm**: A painstakingly debugged version of [the original typo-riddled code](https://github.com/hunterhogan/mapFolding/blob/mapFolding/reference/foldings.txt)
-- The /reference directory.
-- **Numba-JIT Accelerated**: Up to 1000× faster than pure Python ([benchmarks](https://github.com/hunterhogan/mapFolding/blob/mapFolding/notes/Speed%20highlights.md))
+This package offers a comprehensive collection of map folding algorithm implementations that showcase its evolution from historical origins to high-performance computation:
 
-### 3. **For Researchers and Power Users** 🔬
+- **Historical Implementations**:
+  - Carefully restored versions of Lunnon's 1971 original [algorithm](https://github.com/hunterhogan/mapFolding/blob/mapFolding/reference/foldings.txt) with corrections
+  - Atlas Autocode reconstruction in the `reference/foldings.AA` file
 
-This package provides a sophisticated code transformation framework that can turn readable algorithm implementations into highly-optimized computational engines:
+- **Direct Translations**:
+  - Python translations following the original control flow (`lunnanWhile.py`)
+  - NumPy-based vectorized implementations (`lunnanNumpy.py`)
 
-- **Algorithmic Exploration**: Study the core algorithm in `theDao.py`, which uses a functional state-transformation approach with clear, isolated functions
-- **Performance Optimization**: Generate specialized implementations with the `someAssemblyRequired` transformation pipeline:
-  - AST-based code analysis and manipulation
-  - Dataclass "shattering" to decompose complex state objects into primitive components
-  - Just-in-time compilation with Numba and various optimization profiles
-  - LLVM IR extraction for low-level algorithmic analysis
+- **Modern Implementations**:
+  - Java port adaptations (`irvineJavaPort.py`) providing cleaner procedural implementations
+  - Experimental JAX version (`jaxCount.py`) exploring GPU acceleration potential
+  - Semantically decomposed version (`flattened.py`) with clear function boundaries
 
-- **Extensible Design**: The transformation framework is abstract and generic, enabling:
-  - Creation of new optimization targets beyond the included Numba implementation
-  - Customization of compilation parameters and optimization levels
-  - Development of specialized algorithms for specific map dimensions
+- **Performance Optimized**:
+  - Numba-JIT accelerated implementations up to 1000× faster than pure Python (see [benchmarks](https://github.com/hunterhogan/mapFolding/blob/mapFolding/notes/Speed%20highlights.md))
+  - Algorithmic optimizations showcasing subtle yet powerful performance differences (`total_countPlus1vsPlusN.py`)
 
-### 4. **Customization and Extension Guide**
+The `reference` directory serves as both a historical archive and an educational resource for understanding algorithm evolution.
 
-The package architecture supports multiple levels of customization:
+### 3. **Algorithmic Transformation: From Readability to Speed** 🔬
 
-- **Basic Usage**: Work with the high-level API in `basecamp.py` for standard computations
-- **Algorithm Modification**:
+The package provides a sophisticated transformation framework that bridges the gap between human-readable algorithms and high-performance computation:
+
+- **Core Algorithm Understanding**:
+  - Study the functional state-transformation approach in `theDao.py` with clear, isolated functions
+  - Explore the semantic decomposition in `reference/flattened.py` to understand algorithm sections
+
+- **Code Transformation Pipeline**:
+  - **AST Manipulation**: Analyzes and transforms the algorithm's abstract syntax tree
+  - **Dataclass "Shattering"**: Decomposes complex state objects into primitive components
+  - **Optimization Applications**: Applies domain-specific optimizations for numerical computation
+  - **LLVM Integration**: Extracts LLVM IR for low-level algorithmic analysis
+
+- **Performance Breakthroughs**:
+  - Learn why nearly identical algorithms can have dramatically different performance (`total_countPlus1vsPlusN.py`)
+  - See how memory layout and increment strategy impact computation speed
+  - Understand the batching technique that yields order-of-magnitude improvements
+
+### 4. **Multi-Level Architecture: From Simple API to Full Customization**
+
+The package's architecture supports multiple levels of engagement:
+
+- **Basic Usage**:
+  - Work with the high-level API in `basecamp.py` for standard computations
+  - Access OEIS sequence calculations with minimal code
+
+- **Algorithm Exploration**:
+  - Compare different implementations in the `reference` directory to understand trade-offs
   - Modify the core algorithm in `theDao.py` while preserving its functional approach
   - Configure system-wide settings in `theSSOT.py` to adjust data types and performance characteristics
-  - Use utility functions in `beDRY.py` for common operations
 
 - **Advanced Transformation**:
-  - The `someAssemblyRequired` package provides tools to transform code at the AST level:
-    - `transformationTools.py` contains utilities for AST manipulation and code generation
-    - `transformDataStructures.py` handles complex data structure transformations
-    - `ingredientsNumba.py` provides Numba-specific configuration profiles
-    - `synthesizeNumbaFlow.py` orchestrates the transformation process
+  - Use the `someAssemblyRequired` package to transform algorithms at the AST level
+  - Create optimized variants with different compilation settings using:
+    - `transformationTools.py` for AST manipulation
+    - `transformDataStructures.py` for complex data structure transformations
+    - `ingredientsNumba.py` for Numba-specific optimization profiles
+    - `synthesizeNumbaFlow.py` to orchestrate the transformation process
 
 - **Custom Deployment**:
   - Generate specialized implementations for specific dimensions
-  - Create optimized modules that can be executed as standalone scripts
-  - Extract LLVM IR for further analysis or optimization
+  - Create optimized standalone modules for production use
+  - Extract LLVM IR for further analysis and optimization
 
-The package's multi-level design allows you to start with simple API calls and progressively delve deeper into optimization as your computational needs grow.
+The package's multi-level design allows you to start with simple API calls and progressively explore deeper optimization techniques as your computational needs grow.
 
 ## Map-folding Video
 

mapfolding-0.8.2/README.md

@@ -0,0 +1,138 @@
+# mapFolding: Algorithms for enumerating distinct map/stamp folding patterns 🗺️
+
+[![pip install mapFolding](https://img.shields.io/badge/pip%20install-mapFolding-gray.svg?colorB=3b434b)](https://pypi.org/project/mapFolding/)
+[![Static Badge](https://img.shields.io/badge/stinkin'%20badges-don't%20need-b98e5e)](https://youtu.be/g6f_miE91mk&t=4)
+[![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
+![Static Badge](https://img.shields.io/badge/issues-I%20have%20them-brightgreen)
+[![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/)
+
+---
+
+## Quick start
+
+```sh
+pip install mapFolding
+```
+
+`OEIS_for_n` will run a computation from the command line.
+
+```cmd
+(mapFolding) C:\apps\mapFolding> OEIS_for_n A001418 5
+186086600 distinct folding patterns.
+Time elapsed: 1.605 seconds
+```
+
+Use `mapFolding.oeisIDfor_n()` to compute a(n) for an OEIS ID.
+
+```python
+from mapFolding import oeisIDfor_n
+foldsTotal = oeisIDfor_n( 'A001418', 4 )
+```
+
+---
+
+## Features
+
+### 1. Simple, easy usage based on OEIS IDs
+
+`mapFolding` directly implements some IDs from [_The On-Line Encyclopedia of Integer Sequences_](https://oeis.org/) ([BibTex](https://github.com/hunterhogan/mapFolding/blob/main/citations/oeis.bibtex) citation).
+
+Use `getOEISids` to get the most up-to-date list of available OEIS IDs.
+
+```cmd
+(mapFolding) C:\apps\mapFolding> getOEISids
+
+Available OEIS sequences:
+  A001415: Number of ways of folding a 2 X n strip of stamps.
+  A001416: Number of ways of folding a 3 X n strip of stamps.
+  A001417: Number of ways of folding a 2 X 2 X ... X 2 n-dimensional map.
+  A001418: Number of ways of folding an n X n sheet of stamps.
+  A195646: Number of ways of folding a 3 X 3 X ... X 3 n-dimensional map.
+```
+
+### 2. **Algorithm Zoo: A Historical and Performance Journey** 🦒
+
+This package offers a comprehensive collection of map folding algorithm implementations that showcase its evolution from historical origins to high-performance computation:
+
+- **Historical Implementations**:
+  - Carefully restored versions of Lunnon's 1971 original [algorithm](https://github.com/hunterhogan/mapFolding/blob/mapFolding/reference/foldings.txt) with corrections
+  - Atlas Autocode reconstruction in the `reference/foldings.AA` file
+
+- **Direct Translations**:
+  - Python translations following the original control flow (`lunnanWhile.py`)
+  - NumPy-based vectorized implementations (`lunnanNumpy.py`)
+
+- **Modern Implementations**:
+  - Java port adaptations (`irvineJavaPort.py`) providing cleaner procedural implementations
+  - Experimental JAX version (`jaxCount.py`) exploring GPU acceleration potential
+  - Semantically decomposed version (`flattened.py`) with clear function boundaries
+
+- **Performance Optimized**:
+  - Numba-JIT accelerated implementations up to 1000× faster than pure Python (see [benchmarks](https://github.com/hunterhogan/mapFolding/blob/mapFolding/notes/Speed%20highlights.md))
+  - Algorithmic optimizations showcasing subtle yet powerful performance differences (`total_countPlus1vsPlusN.py`)
+
+The `reference` directory serves as both a historical archive and an educational resource for understanding algorithm evolution.
+
+### 3. **Algorithmic Transformation: From Readability to Speed** 🔬
+
+The package provides a sophisticated transformation framework that bridges the gap between human-readable algorithms and high-performance computation:
+
+- **Core Algorithm Understanding**:
+  - Study the functional state-transformation approach in `theDao.py` with clear, isolated functions
+  - Explore the semantic decomposition in `reference/flattened.py` to understand algorithm sections
+
+- **Code Transformation Pipeline**:
+  - **AST Manipulation**: Analyzes and transforms the algorithm's abstract syntax tree
+  - **Dataclass "Shattering"**: Decomposes complex state objects into primitive components
+  - **Optimization Applications**: Applies domain-specific optimizations for numerical computation
+  - **LLVM Integration**: Extracts LLVM IR for low-level algorithmic analysis
+
+- **Performance Breakthroughs**:
+  - Learn why nearly identical algorithms can have dramatically different performance (`total_countPlus1vsPlusN.py`)
+  - See how memory layout and increment strategy impact computation speed
+  - Understand the batching technique that yields order-of-magnitude improvements
+
+### 4. **Multi-Level Architecture: From Simple API to Full Customization**
+
+The package's architecture supports multiple levels of engagement:
+
+- **Basic Usage**:
+  - Work with the high-level API in `basecamp.py` for standard computations
+  - Access OEIS sequence calculations with minimal code
+
+- **Algorithm Exploration**:
+  - Compare different implementations in the `reference` directory to understand trade-offs
+  - Modify the core algorithm in `theDao.py` while preserving its functional approach
+  - Configure system-wide settings in `theSSOT.py` to adjust data types and performance characteristics
+
+- **Advanced Transformation**:
+  - Use the `someAssemblyRequired` package to transform algorithms at the AST level
+  - Create optimized variants with different compilation settings using:
+    - `transformationTools.py` for AST manipulation
+    - `transformDataStructures.py` for complex data structure transformations
+    - `ingredientsNumba.py` for Numba-specific optimization profiles
+    - `synthesizeNumbaFlow.py` to orchestrate the transformation process
+
+- **Custom Deployment**:
+  - Generate specialized implementations for specific dimensions
+  - Create optimized standalone modules for production use
+  - Extract LLVM IR for further analysis and optimization
+
+The package's multi-level design allows you to start with simple API calls and progressively explore deeper optimization techniques as your computational needs grow.
+
+## Map-folding Video
+
+~~This caused my neurosis:~~ I enjoyed the following video, which is what introduced me to map folding.
+
+"How Many Ways Can You Fold a Map?" by Physics for the Birds, 2024 November 13 ([BibTex](https://github.com/hunterhogan/mapFolding/blob/main/citations/Physics_for_the_Birds.bibtex) citation)
+
+[![How Many Ways Can You Fold a Map?](https://i.ytimg.com/vi/sfH9uIY3ln4/hq720.jpg)](https://www.youtube.com/watch?v=sfH9uIY3ln4)
+
+---
+
+## 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)
+
+[![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.8.1 → mapfolding-0.8.2}/mapFolding/basecamp.py

@@ -15,7 +15,7 @@ implementation, and optional persistence of results.
 from collections.abc import Sequence
 from mapFolding.beDRY import outfitCountFolds, setCPUlimit, validateListDimensions
 from mapFolding.filesystem import getPathFilenameFoldsTotal, saveFoldsTotal
-from mapFolding.theSSOT import ComputationState, getPackageDispatcher
+from mapFolding.theSSOT import ComputationState, getPackageDispatcher, The
 from os import PathLike
 from pathlib import Path
 
@@ -54,7 +54,7 @@ def countFolds(listDimensions: Sequence[int]
 		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 = setCPUlimit(CPUlimit)
+	concurrencyLimit: int = setCPUlimit(CPUlimit, The.concurrencyPackage)
 	computationStateInitialized: ComputationState = outfitCountFolds(mapShape, computationDivisions, concurrencyLimit)
 
 	dispatcherCallableProxy = getPackageDispatcher()

{mapfolding-0.8.1 → mapfolding-0.8.2}/mapFolding/beDRY.py

@@ -15,12 +15,15 @@ particularly for initializing computation state, validating inputs, and creating
 structures needed by the folding algorithms.
 """
 from collections.abc import Sequence
-from mapFolding.theSSOT import Array3D, ComputationState, getDatatypePackage, getNumpyDtypeDefault
+from mapFolding.theSSOT import ComputationState
+from numpy import dtype as numpy_dtype, integer, ndarray
 from sys import maxsize as sysMaxsize
-from typing import Any
+from typing import Any, TypeVar
 from Z0Z_tools import defineConcurrencyLimit, intInnit, oopsieKwargsie
 import numpy
 
+numpyIntegerType = TypeVar('numpyIntegerType', bound=integer[Any])
+
 def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
 	productDimensions = 1
 	for dimension in mapShape:
@@ -81,25 +84,16 @@ def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: i
 		raise ValueError(f"Problem: `taskDivisions`, ({taskDivisions}), is greater than `leavesTotal`, ({leavesTotal}), which will cause duplicate counting of the folds.\n\nChallenge: you cannot directly set `taskDivisions` or `leavesTotal`. They are derived from parameters that may or may not still be named `computationDivisions`, `CPUlimit` , and `listDimensions` and from dubious-quality Python code.")
 	return int(max(0, taskDivisions))
 
-def interpretParameter_datatype(datatype: type[numpy.signedinteger[Any]] | None = None) -> type[numpy.signedinteger[Any]]:
-	"""An imperfect way to reduce code duplication."""
-	if 'numpy' == getDatatypePackage():
-		numpyDtype = datatype or getNumpyDtypeDefault()
-	else:
-		raise NotImplementedError("Somebody done broke it.")
-	return numpyDtype
-
-def makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: type[numpy.signedinteger[Any]] | None = None) -> Array3D:
-	numpyDtype = interpretParameter_datatype(datatype)
+def makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: type[numpyIntegerType]) -> ndarray[tuple[int, int, int], numpy_dtype[numpyIntegerType]]:
 	dimensionsTotal = len(mapShape)
-	cumulativeProduct = numpy.multiply.accumulate([1] + list(mapShape), dtype=numpyDtype)
-	arrayDimensions = numpy.array(mapShape, dtype=numpyDtype)
-	coordinateSystem = numpy.zeros((dimensionsTotal, leavesTotal + 1), dtype=numpyDtype)
+	cumulativeProduct = numpy.multiply.accumulate([1] + list(mapShape), dtype=datatype)
+	arrayDimensions = numpy.array(mapShape, dtype=datatype)
+	coordinateSystem = numpy.zeros((dimensionsTotal, leavesTotal + 1), dtype=datatype)
 	for indexDimension in range(dimensionsTotal):
 		for leaf1ndex in range(1, leavesTotal + 1):
 			coordinateSystem[indexDimension, leaf1ndex] = (((leaf1ndex - 1) // cumulativeProduct[indexDimension]) % arrayDimensions[indexDimension] + 1)
 
-	connectionGraph = numpy.zeros((dimensionsTotal, leavesTotal + 1, leavesTotal + 1), dtype=numpyDtype)
+	connectionGraph = numpy.zeros((dimensionsTotal, leavesTotal + 1, leavesTotal + 1), dtype=datatype)
 	for indexDimension in range(dimensionsTotal):
 		for activeLeaf1ndex in range(1, leavesTotal + 1):
 			for connectee1ndex in range(1, activeLeaf1ndex + 1):
@@ -116,9 +110,8 @@ def makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: t
 					connectionGraph[indexDimension, activeLeaf1ndex, connectee1ndex] = connectee1ndex + cumulativeProduct[indexDimension]
 	return connectionGraph
 
-def makeDataContainer(shape: int | tuple[int, ...], datatype: type[numpy.signedinteger[Any]] | None = None) -> numpy.ndarray[Any, numpy.dtype[numpy.signedinteger[Any]]]:
-	numpyDtype = interpretParameter_datatype(datatype)
-	return numpy.zeros(shape, dtype=numpyDtype)
+def makeDataContainer(shape: int | tuple[int, ...], datatype: type[numpyIntegerType]) -> ndarray[Any, numpy_dtype[numpyIntegerType]]:
+	return numpy.zeros(shape, dtype=datatype)
 
 def outfitCountFolds(mapShape: tuple[int, ...], computationDivisions: int | str | None = None, concurrencyLimit: int = 1) -> ComputationState:
 	leavesTotal = getLeavesTotal(mapShape)
@@ -126,7 +119,7 @@ def outfitCountFolds(mapShape: tuple[int, ...], computationDivisions: int | str
 	computationStateInitialized = ComputationState(mapShape, leavesTotal, taskDivisions, concurrencyLimit)
 	return computationStateInitialized
 
-def setCPUlimit(CPUlimit: Any | None) -> int:
+def setCPUlimit(CPUlimit: Any | None, concurrencyPackage: str | None = None) -> int:
 	"""Sets CPU limit for concurrent operations.
 
 	If the concurrency is managed by `numba`, the maximum number of CPUs is retrieved from `numba.get_num_threads()` and not by polling the hardware. Therefore, if there are
@@ -154,17 +147,17 @@ def setCPUlimit(CPUlimit: Any | None) -> int:
 	if not (CPUlimit is None or isinstance(CPUlimit, (bool, int, float))):
 		CPUlimit = oopsieKwargsie(CPUlimit)
 
-	from mapFolding.theSSOT import concurrencyPackage
-	if concurrencyPackage == 'numba':
-		from numba import get_num_threads, set_num_threads
-		concurrencyLimit: int = defineConcurrencyLimit(CPUlimit, get_num_threads())
-		set_num_threads(concurrencyLimit)
-		concurrencyLimit = get_num_threads()
-	elif concurrencyPackage == 'multiprocessing':
-		# When to use multiprocessing.set_start_method https://github.com/hunterhogan/mapFolding/issues/6
-		concurrencyLimit = defineConcurrencyLimit(CPUlimit)
-	else:
-		raise NotImplementedError(f"I received {concurrencyPackage=} but I don't know what to do with that.")
+	match concurrencyPackage:
+		case 'multiprocessing' | None:
+			# When to use multiprocessing.set_start_method https://github.com/hunterhogan/mapFolding/issues/6
+			concurrencyLimit: int = defineConcurrencyLimit(CPUlimit)
+		case 'numba':
+			from numba import get_num_threads, set_num_threads
+			concurrencyLimit = defineConcurrencyLimit(CPUlimit, get_num_threads())
+			set_num_threads(concurrencyLimit)
+			concurrencyLimit = get_num_threads()
+		case _:
+			raise NotImplementedError(f"I received {concurrencyPackage=} but I don't know what to do with that.")
 	return concurrencyLimit
 
 def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:

{mapfolding-0.8.1 → mapfolding-0.8.2}/mapFolding/oeis.py

@@ -16,7 +16,7 @@ literature and extend sequences beyond their currently known terms.
 """
 from collections.abc import Callable
 from datetime import datetime, timedelta
-from mapFolding.theSSOT import thePathPackage
+from mapFolding.theSSOT import The
 from pathlib import Path
 from typing import Any, Final, TYPE_CHECKING
 import argparse
@@ -38,7 +38,7 @@ cacheDays = 7
 """
 Section: make `settingsOEIS`"""
 
-pathCache: Path = thePathPackage / ".cache"
+pathCache: Path = The.pathPackage / ".cache"
 
 class SettingsOEIS(TypedDict):
 	description: str

mapfolding-0.8.2/mapFolding/reference/__init__.py

@@ -0,0 +1,38 @@
+"""
+Historical and reference implementations of map-folding algorithms.
+
+This directory contains various implementations of the map-folding algorithm,
+serving both as historical references and as benchmarks for performance comparison.
+These implementations range from direct translations of Lunnon's original 1971 code
+to highly specialized versions using modern optimization techniques.
+
+Categories of reference implementations:
+
+1. Historical transcripts:
+   - foldings.txt - Original algorithm from Lunnon's 1971 paper
+   - foldings.AA - Reconstructed Atlas Autocode version with corrections
+
+2. Direct translations:
+   - lunnanWhile.py - Python translation using while loops
+   - lunnanNumpy.py - NumPy-based translation with array operations
+
+3. Alternative implementations:
+   - irvineJavaPort.py - Port from Sean A. Irvine's Java implementation
+   - hunterNumba.py - Numba-optimized implementation
+   - jaxCount.py - JAX implementation for GPU acceleration
+   - flattened.py - Semantically decomposed version with operation grouping
+
+4. Specialized variants:
+   - total_countPlus1vsPlusN.py - Optimized counting with different increment strategies
+   - rotatedEntryPoint.py - Alternative entry point implementation (demonstration)
+
+These reference implementations are valuable for:
+- Understanding the algorithm's historical development
+- Comparing performance characteristics across implementation strategies
+- Studying optimization techniques and their effects
+- Verifying the correctness of the core algorithm against known solutions
+
+Note: These implementations are for reference only and not used in the production
+code path of the package. The active implementation resides in theDao.py with
+optimized variants generated by the someAssemblyRequired framework.
+"""

{mapfolding-0.8.1 → mapfolding-0.8.2}/mapFolding/reference/flattened.py

@@ -1,5 +1,23 @@
-"""The algorithm flattened into semantic sections.
-This version is not maintained, so you may see differences from the current version."""
+"""
+Semantically decomposed implementation of Lunnon's algorithm with operation grouping.
+
+This implementation restructures the map folding algorithm into semantic sections with
+clear function boundaries, making the algorithm more readable and understandable. Each
+operation is isolated into its own named function, providing a clear mapping between
+the mathematical concepts and their implementation.
+
+Key characteristics:
+- Breaks down the algorithm into small, single-purpose functions
+- Uses descriptive function names that explain what each part does
+- Clearly separates logical sections of the algorithm
+- Provides a more maintainable and educational view of the algorithm
+- Uses Python's type hints for better code understanding
+
+This implementation serves as a bridge between the historical implementations and the
+modern functional approach used in the main package. It's particularly valuable for
+understanding the algorithm's operation before diving into the highly optimized versions.
+"""
+
 from collections.abc import Sequence
 from numpy import integer
 from numpy.typing import NDArray

{mapfolding-0.8.1 → mapfolding-0.8.2}/mapFolding/reference/hunterNumba.py

@@ -1,3 +1,27 @@
+"""
+High-performance Numba-accelerated implementation of Lunnon's algorithm.
+
+This implementation focuses on maximum computational performance by leveraging Numba's
+just-in-time (JIT) compilation capabilities to generate native machine code. It represents
+a manually optimized version that served as inspiration for the automated transformation
+framework in the someAssemblyRequired package.
+
+Key characteristics:
+- Optimized data structures using NumPy typed arrays with appropriate data types
+- Function decorators for Numba JIT compilation with performance-oriented settings
+- Memory-efficient implementation with careful type management
+- Reduced Python overhead through native code execution
+- Algorithmic optimizations tailored for numerical computation
+
+Performance considerations:
+- Up to 1000× faster than pure Python implementations
+- Optimized for larger map dimensions where computational demands increase exponentially
+- Incorporates lessons from multiple implementation strategies
+
+Note: This serves as a reference for manually-optimized code before the development of
+the automated transformation pipeline in the main package.
+"""
+
 from typing import Any
 import numba
 import numpy

{mapfolding-0.8.1 → mapfolding-0.8.2}/mapFolding/reference/irvineJavaPort.py

@@ -2,8 +2,20 @@
 Ported from the Java version by Sean A. Irvine:
 https://github.com/archmageirvine/joeis/blob/80e3e844b11f149704acbab520bc3a3a25ac34ff/src/irvine/oeis/a001/A001415.java
 
+This implementation is a conversion from a well-known Java implementation of Lunnon's algorithm
+by Sean A. Irvine, a contributor to the OEIS project. It provides a clean, procedural implementation
+with straightforward variable naming and control flow that may be more approachable for
+programmers familiar with modern languages.
+
+Key characteristics:
+- Clear variable naming following modern programming conventions
+- Procedural implementation style similar to Java but adapted for Python
+- Follows the same algorithmic structure as Lunnon's original but with cleaner organization
+- Uses primitive Python data structures (lists) without NumPy dependencies
+
 Citation: https://github.com/hunterhogan/mapFolding/blob/134f2e6ecdf59fb6f6829c775475544a6aaaa800/citations/jOEIS.bibtex
 """
+
 def foldings(p: list[int], res: int = 0, mod: int = 0) -> int:
 	"""
 	Compute the total number of foldings for a map with dimensions specified in p.