mapFolding 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

mapFolding/__init__.py

@@ -1,9 +1,38 @@
+"""
+Map folding enumeration and counting algorithms with optimization capabilities.
+
+This package implements algorithms to count and enumerate the various 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 low-level 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: Utility functions for common operations and parameter management
+- theSSOT: Single Source of Truth for configuration, types, and state management
+- 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
+
+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
+
+This package strives to balance algorithm readability and understandability with
+high-performance computation capabilities, allowing users to compute map folding
+totals for larger dimensions than previously feasible.
+"""
 from mapFolding.basecamp import countFolds as countFolds
 from mapFolding.oeis import clearOEIScache, getOEISids, OEIS_for_n
 
 __all__ = [
-	'clearOEIScache',
-	'countFolds',
-	'getOEISids',
-	'OEIS_for_n',
+    'clearOEIScache',
+    'countFolds',
+    'getOEISids',
+    'OEIS_for_n',
 ]

mapFolding/basecamp.py

@@ -1,7 +1,21 @@
+"""
+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.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
 
@@ -40,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/beDRY.py

@@ -1,11 +1,29 @@
-"""A relatively stable API for oft-needed functionality."""
+"""
+Utility functions for maintaining DRY (Don't Repeat Yourself) principles in the mapFolding package.
+
+This module provides a collection of helper functions that abstract common operations needed
+throughout the package, preventing code duplication and ensuring consistency. The functions
+manage core aspects of the computation process, including:
+
+1. Resource allocation and system limits management
+2. Data structure initialization and manipulation
+3. Parameter validation and interpretation
+4. Construction of specialized arrays and matrices for the folding algorithm
+
+The functions in this module serve as a relatively stable API for other modules to use,
+particularly for initializing computation state, validating inputs, and creating data
+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:
@@ -66,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):
@@ -101,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)
@@ -111,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
@@ -139,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/filesystem.py

@@ -1,95 +1,129 @@
-"""Filesystem functions for mapFolding package."""
+"""
+Filesystem utilities for managing map folding computation results.
+
+This module provides functions for standardized handling of files related to the mapFolding
+package, with a focus on saving, retrieving, and naming computation results. It implements
+consistent naming conventions and path resolution strategies to ensure that:
+
+1. Computation results are stored in a predictable location
+2. Filenames follow a consistent pattern based on map dimensions
+3. Results can be reliably retrieved for future reference
+4. The system handles file operations safely with appropriate error handling
+
+The module serves as the interface between the computational components of the package
+and the filesystem, abstracting away the details of file operations and path management.
+"""
 from pathlib import Path, PurePath
 from typing import Any
+from os import PathLike
 import os
 
 def getFilenameFoldsTotal(mapShape: tuple[int, ...]) -> str:
-	"""Imagine your computer has been counting folds for 9 days, and when it tries to save your newly discovered value,
-	the filename is invalid. I bet you think this function is more important after that thought experiment.
-
-	Make a standardized filename for the computed value `foldsTotal`.
-
-	The filename takes into account
-		- the dimensions of the map, aka `mapShape`, aka `listDimensions`
-		- no spaces in the filename
-		- safe filesystem characters
-		- unique extension
-		- Python-safe strings:
-			- no starting with a number
-			- no reserved words
-			- no dashes or other special characters
-			- uh, I can't remember, but I found some other frustrating limitations
-		- if 'p' is still the first character of the filename, I picked that because it was the original identifier for the map shape in Lunnan's code
-
-	Parameters:
-		mapShape: A sequence of integers representing the dimensions of the map.
-
-	Returns:
-		filenameFoldsTotal: A filename string in format 'pMxN.foldsTotal' where M,N are sorted dimensions
-	"""
-	return 'p' + 'x'.join(str(dimension) for dimension in sorted(mapShape)) + '.foldsTotal'
-
-def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal: str | os.PathLike[str] | None = None) -> Path:
-	"""Get a standardized path and filename for the computed value `foldsTotal`.
-
-	If you provide a directory, the function will append a standardized filename. If you provide a filename
-	or a relative path and filename, the function will prepend the default path.
-
-	Parameters:
-		mapShape: List of dimensions for the map folding problem.
-		pathLikeWriteFoldsTotal (pathJobRootDEFAULT): Path, filename, or relative path and filename. If None, uses default path.
-			Defaults to None.
-
-	Returns:
-		pathFilenameFoldsTotal: Absolute path and filename.
-	"""
-	from mapFolding.theSSOT import getPathJobRootDEFAULT
-
-	if pathLikeWriteFoldsTotal is None:
-		pathFilenameFoldsTotal = getPathJobRootDEFAULT() / getFilenameFoldsTotal(mapShape)
-	else:
-		pathLikeSherpa = Path(pathLikeWriteFoldsTotal)
-		if pathLikeSherpa.is_dir():
-			pathFilenameFoldsTotal = pathLikeSherpa / getFilenameFoldsTotal(mapShape)
-		elif pathLikeSherpa.is_file() and pathLikeSherpa.is_absolute():
-			pathFilenameFoldsTotal = pathLikeSherpa
-		else:
-			pathFilenameFoldsTotal = getPathJobRootDEFAULT() / pathLikeSherpa
-
-	pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
-	return pathFilenameFoldsTotal
-
-def saveFoldsTotal(pathFilename: str | os.PathLike[str], foldsTotal: int) -> None:
-	"""
-	Save foldsTotal with multiple fallback mechanisms.
-
-	Parameters:
-		pathFilename: Target save location
-		foldsTotal: Critical computed value to save
-	"""
-	try:
-		pathFilenameFoldsTotal = Path(pathFilename)
-		pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
-		pathFilenameFoldsTotal.write_text(str(foldsTotal))
-	except Exception as ERRORmessage:
-		try:
-			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
-			print(ERRORmessage)
-			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
-			randomnessPlanB = (int(str(foldsTotal).strip()[-1]) + 1) * ['YO_']
-			filenameInfixUnique = ''.join(randomnessPlanB)
-			pathFilenamePlanB = os.path.join(os.getcwd(), 'foldsTotal' + filenameInfixUnique + '.txt')
-			writeStreamFallback = open(pathFilenamePlanB, 'w')
-			writeStreamFallback.write(str(foldsTotal))
-			writeStreamFallback.close()
-			print(str(pathFilenamePlanB))
-		except Exception:
-			print(foldsTotal)
-	return None
-
-def writeStringToHere(this: str, pathFilename: str | os.PathLike[Any] | PurePath) -> None:
-	"""Write the string `this` to the file at `pathFilename`."""
-	pathFilename = Path(pathFilename)
-	pathFilename.parent.mkdir(parents=True, exist_ok=True)
-	pathFilename.write_text(str(this))
-	return None
+    """
+    Create a standardized filename for a computed `foldsTotal` value.
+
+    This function generates a consistent, filesystem-safe filename based on map dimensions.
+    Standardizing filenames ensures that results can be reliably stored and retrieved,
+    avoiding potential filesystem incompatibilities or Python naming restrictions.
+
+    Parameters:
+        mapShape: A sequence of integers representing the dimensions of the map.
+
+    Returns:
+        filenameFoldsTotal: A filename string in format 'pMxN.foldsTotal' where M,N are sorted dimensions.
+
+    Notes:
+        The filename format ensures:
+        - No spaces in the filename
+        - Safe filesystem characters
+        - Unique extension (.foldsTotal)
+        - Python-safe strings (no starting with numbers, no reserved words)
+        - The 'p' prefix preserves compatibility with Lunnan's original code.
+    """
+    return 'p' + 'x'.join(str(dimension) for dimension in sorted(mapShape)) + '.foldsTotal'
+
+def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal: str | PathLike[str] | None = None) -> Path:
+    """
+    Get a standardized path and filename for the computed foldsTotal value.
+
+    This function resolves paths for storing computation results, handling different
+    input types including directories, absolute paths, or relative paths. It ensures
+    that all parent directories exist in the resulting path.
+
+    Parameters:
+        mapShape: List of dimensions for the map folding problem.
+        pathLikeWriteFoldsTotal (getPathJobRootDEFAULT): Path, filename, or relative path and filename.
+            If None, uses default path. If a directory, appends standardized filename.
+
+    Returns:
+        pathFilenameFoldsTotal: Absolute path and filename for storing the foldsTotal value.
+
+    Notes:
+        The function creates any necessary directories in the path if they don't exist.
+    """
+    from mapFolding.theSSOT import getPathJobRootDEFAULT
+
+    if pathLikeWriteFoldsTotal is None:
+        pathFilenameFoldsTotal = getPathJobRootDEFAULT() / getFilenameFoldsTotal(mapShape)
+    else:
+        pathLikeSherpa = Path(pathLikeWriteFoldsTotal)
+        if pathLikeSherpa.is_dir():
+            pathFilenameFoldsTotal = pathLikeSherpa / getFilenameFoldsTotal(mapShape)
+        elif pathLikeSherpa.is_file() and pathLikeSherpa.is_absolute():
+            pathFilenameFoldsTotal = pathLikeSherpa
+        else:
+            pathFilenameFoldsTotal = getPathJobRootDEFAULT() / pathLikeSherpa
+
+    pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
+    return pathFilenameFoldsTotal
+
+def saveFoldsTotal(pathFilename: str | PathLike[str], foldsTotal: int) -> None:
+    """
+    Save `foldsTotal` value to disk with multiple fallback mechanisms.
+
+    This function attempts to save the computed `foldsTotal` value to the specified
+    location, with backup strategies in case the primary save attempt fails.
+    The robustness is critical since these computations may take days to complete.
+
+    Parameters:
+        pathFilename: Target save location for the `foldsTotal` value
+        foldsTotal: The computed value to save
+
+    Notes:
+        If the primary save fails, the function will attempt alternative save methods:
+        1. Print the value prominently to stdout
+        2. Create a fallback file in the current working directory
+        3. As a last resort, simply print the value
+    """
+    try:
+        pathFilenameFoldsTotal = Path(pathFilename)
+        pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
+        pathFilenameFoldsTotal.write_text(str(foldsTotal))
+    except Exception as ERRORmessage:
+        try:
+            print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+            print(ERRORmessage)
+            print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+            randomnessPlanB = (int(str(foldsTotal).strip()[-1]) + 1) * ['YO_']
+            filenameInfixUnique = ''.join(randomnessPlanB)
+            pathFilenamePlanB = os.path.join(os.getcwd(), 'foldsTotal' + filenameInfixUnique + '.txt')
+            writeStreamFallback = open(pathFilenamePlanB, 'w')
+            writeStreamFallback.write(str(foldsTotal))
+            writeStreamFallback.close()
+            print(str(pathFilenamePlanB))
+        except Exception:
+            print(foldsTotal)
+    return None
+
+def writeStringToHere(this: str, pathFilename: str | PathLike[Any] | PurePath) -> None:
+    """
+    Write a string to a file, creating parent directories if needed.
+
+    Parameters:
+        this: The string content to write to the file
+        pathFilename: The target file path where the string should be written
+    """
+    pathFilename = Path(pathFilename)
+    pathFilename.parent.mkdir(parents=True, exist_ok=True)
+    pathFilename.write_text(str(this))
+    return None

mapFolding/noHomeYet.py

@@ -1,3 +1,15 @@
+"""
+Interface for retrieving known map folding totals from OEIS (Online Encyclopedia of Integer Sequences).
+
+This module provides utilities for accessing pre-computed map folding totals that are known
+from mathematical literature and stored in the OEIS. The functions cache results for
+performance and provide lookups based on map dimensions.
+
+The main functions are:
+- makeDictionaryFoldsTotalKnown: Creates a dictionary of known folding totals indexed by map dimensions
+- getFoldsTotalKnown: Retrieves the folding total for a specific map shape, returning -1 if unknown
+"""
+
 from functools import cache
 from mapFolding.oeis import settingsOEIS
 

mapFolding/oeis.py

@@ -1,7 +1,22 @@
-"""Everything implementing the The Online Encyclopedia of Integer Sequences (OEIS); _only_ things that implement _only_ the OEIS."""
+"""
+Interface to The Online Encyclopedia of Integer Sequences (OEIS) for map folding sequences.
+
+This module provides a comprehensive interface for accessing and utilizing integer sequences
+from the OEIS that relate to map folding problems. It implements functionality to:
+
+1. Retrieve sequence data from OEIS with local caching for performance
+2. Map sequence indices to corresponding map shapes based on sequence definitions
+3. Provide a command-line interface for sequence lookups
+4. Execute map folding computations for sequence terms not available in OEIS
+
+The module maintains a registry of implemented OEIS sequences (A001415-A001418, A195646)
+with their metadata, known values, and functions to convert between sequence indices and
+map dimensions. This allows the package to validate results against established mathematical
+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
@@ -23,7 +38,7 @@ cacheDays = 7
 """
 Section: make `settingsOEIS`"""
 
-pathCache: Path = thePathPackage / ".cache"
+pathCache: Path = The.pathPackage / ".cache"
 
 class SettingsOEIS(TypedDict):
 	description: str

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.
+"""