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

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/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/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/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/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/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/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.

mapFolding/reference/{jax.py → jaxCount.py}

@@ -1,20 +1,39 @@
-"""I was able to implement the algorithm with JAX, but I didn't see an advantage and it's a pain in the ass.
-I don't maintain this module."""
-from mapFolding import validateListDimensions, getLeavesTotal, makeConnectionGraph
-from typing import List, Tuple
+"""
+I was able to implement the algorithm with JAX, but I didn't see an advantage and it's a pain in the ass.
+
+Experimental JAX implementation of Lunnon's algorithm for potential GPU acceleration.
+
+This implementation explores the use of JAX (Just After eXecution) for potential GPU acceleration
+of the map folding algorithm. It represents an experimental approach that attempts to leverage
+JAX's transformation capabilities and hardware acceleration through XLA compilation.
+
+Key characteristics:
+- Uses JAX's functional programming model with lax control flow primitives
+- Attempts to leverage GPU acceleration for numerical operations
+- Demonstrates JAX-specific patterns for handling loops and conditions
+- Supports jit compilation for performance optimization
+
+As noted in the file's comment, this implementation didn't demonstrate significant advantages
+over other approaches and presented additional complexity. It serves as a valuable reference
+for exploring alternative acceleration strategies and understanding the limitations of
+different computational frameworks for this specific algorithm.
+"""
+from flattened import validateListDimensions, getLeavesTotal, makeConnectionGraph
+from numpy.typing import NDArray
+from typing import Any
 import jax
 import jaxtyping
+import numpy
 
 dtypeMedium = jax.numpy.uint32
 dtypeMaximum = jax.numpy.uint32
 
-def countFolds(listDimensions: List[int]) -> int:
-	listDimensionsPositive: List[int] = validateListDimensions(listDimensions)
+def countFolds(listDimensions: list[int]) -> int:
+	listDimensionsPositive: list[int] = validateListDimensions(listDimensions)
 
 	n: int = getLeavesTotal(listDimensionsPositive)
 	d: int = len(listDimensions)
-	import numpy
-	D: numpy.ndarray = makeConnectionGraph(listDimensionsPositive)
+	D: NDArray[numpy.integer[Any]] = makeConnectionGraph(listDimensionsPositive)
 	connectionGraph = jax.numpy.asarray(D, dtype=dtypeMedium)
 	del listDimensionsPositive
 
@@ -22,14 +41,14 @@ def countFolds(listDimensions: List[int]) -> int:
 
 def foldingsJAX(leavesTotal: jaxtyping.UInt32, dimensionsTotal: jaxtyping.UInt32, connectionGraph: jaxtyping.Array) -> jaxtyping.UInt32:
 
-	def doNothing(argument):
+	def doNothing(argument: Any):
 		return argument
 
-	def while_activeLeaf1ndex_greaterThan_0(comparisonValues: Tuple):
+	def while_activeLeaf1ndex_greaterThan_0(comparisonValues: tuple):
 		comparand = comparisonValues[6]
 		return comparand > 0
 
-	def countFoldings(allValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32, jaxtyping.UInt32]):
+	def countFoldings(allValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32, jaxtyping.UInt32]):
 		_0, leafBelow, _2, _3, _4, _5, activeLeaf1ndex, _7 = allValues
 
 		sentinel = leafBelow.at[0].get().astype(jax.numpy.uint32)
@@ -44,24 +63,24 @@ def foldingsJAX(leavesTotal: jaxtyping.UInt32, dimensionsTotal: jaxtyping.UInt32
 	def findGapsCondition(leafBelowSentinel, activeLeafNumber):
 		return jax.numpy.logical_or(jax.numpy.logical_and(leafBelowSentinel == 1, activeLeafNumber <= leavesTotal), activeLeafNumber <= 1)
 
-	def findGapsDo(allValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32, jaxtyping.UInt32]):
-		def for_dimension1ndex_in_range_1_to_dimensionsTotalPlus1(comparisonValues: Tuple):
+	def findGapsDo(allValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32, jaxtyping.UInt32]):
+		def for_dimension1ndex_in_range_1_to_dimensionsTotalPlus1(comparisonValues: tuple):
 			return comparisonValues[-1] <= dimensionsTotal
 
-		def for_dimension1ndex_in_range_1_to_dimensionsTotalPlus1_do(for_dimension1ndex_in_range_1_to_dimensionsTotalPlus1Values: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32, jaxtyping.UInt32]):
+		def for_dimension1ndex_in_range_1_to_dimensionsTotalPlus1_do(for_dimension1ndex_in_range_1_to_dimensionsTotalPlus1Values: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32, jaxtyping.UInt32]):
 			def ifLeafIsUnconstrainedCondition(comparand):
 				return jax.numpy.equal(connectionGraph[comparand, activeLeaf1ndex, activeLeaf1ndex], activeLeaf1ndex)
 
-			def ifLeafIsUnconstrainedDo(unconstrainedValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
+			def ifLeafIsUnconstrainedDo(unconstrainedValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
 				unconstrained_unconstrainedLeaf = unconstrainedValues[3]
 				unconstrained_unconstrainedLeaf = 1 + unconstrained_unconstrainedLeaf
 				return (unconstrainedValues[0], unconstrainedValues[1], unconstrainedValues[2], unconstrained_unconstrainedLeaf)
 
-			def ifLeafIsUnconstrainedElse(unconstrainedValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
-				def while_leaf1ndexConnectee_notEquals_activeLeaf1ndex(comparisonValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
+			def ifLeafIsUnconstrainedElse(unconstrainedValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
+				def while_leaf1ndexConnectee_notEquals_activeLeaf1ndex(comparisonValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
 					return comparisonValues[-1] != activeLeaf1ndex
 
-				def countGaps(countGapsDoValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
+				def countGaps(countGapsDoValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
 					countGapsCountDimensionsGapped, countGapsPotentialGaps, countGapsGap1ndexLowerBound, countGapsLeaf1ndexConnectee = countGapsDoValues
 
 					countGapsPotentialGaps = countGapsPotentialGaps.at[countGapsGap1ndexLowerBound].set(countGapsLeaf1ndexConnectee)
@@ -93,11 +112,11 @@ def foldingsJAX(leavesTotal: jaxtyping.UInt32, dimensionsTotal: jaxtyping.UInt32
 		def almostUselessCondition(comparand):
 			return comparand == dimensionsTotal
 
-		def almostUselessConditionDo(for_leaf1ndex_in_range_activeLeaf1ndexValues: Tuple[jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
+		def almostUselessConditionDo(for_leaf1ndex_in_range_activeLeaf1ndexValues: tuple[jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
 			def for_leaf1ndex_in_range_activeLeaf1ndex(comparisonValues):
 				return comparisonValues[-1] < activeLeaf1ndex
 
-			def for_leaf1ndex_in_range_activeLeaf1ndex_do(for_leaf1ndex_in_range_activeLeaf1ndexValues: Tuple[jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
+			def for_leaf1ndex_in_range_activeLeaf1ndex_do(for_leaf1ndex_in_range_activeLeaf1ndexValues: tuple[jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
 				leafInRangePotentialGaps, gapNumberLowerBound, leafNumber = for_leaf1ndex_in_range_activeLeaf1ndexValues
 				leafInRangePotentialGaps = leafInRangePotentialGaps.at[gapNumberLowerBound].set(leafNumber)
 				gapNumberLowerBound = 1 + gapNumberLowerBound
@@ -105,10 +124,10 @@ def foldingsJAX(leavesTotal: jaxtyping.UInt32, dimensionsTotal: jaxtyping.UInt32
 				return (leafInRangePotentialGaps, gapNumberLowerBound, leafNumber)
 			return jax.lax.while_loop(for_leaf1ndex_in_range_activeLeaf1ndex, for_leaf1ndex_in_range_activeLeaf1ndex_do, for_leaf1ndex_in_range_activeLeaf1ndexValues)
 
-		def for_range_from_activeGap1ndex_to_gap1ndexCeiling(comparisonValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
+		def for_range_from_activeGap1ndex_to_gap1ndexCeiling(comparisonValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
 			return comparisonValues[-1] < gap1ndexCeiling
 
-		def miniGapDo(gapToGapValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
+		def miniGapDo(gapToGapValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
 			gapToGapCountDimensionsGapped, gapToGapPotentialGaps, activeGapNumber, index = gapToGapValues
 			gapToGapPotentialGaps = gapToGapPotentialGaps.at[activeGapNumber].set(gapToGapPotentialGaps.at[index].get())
 			activeGapNumber = jax.numpy.where(jax.numpy.equal(gapToGapCountDimensionsGapped.at[gapToGapPotentialGaps.at[index].get()].get(), dimensionsTotal - unconstrainedLeaf), activeGapNumber + 1, activeGapNumber).astype(jax.numpy.uint32)
@@ -144,17 +163,17 @@ def foldingsJAX(leavesTotal: jaxtyping.UInt32, dimensionsTotal: jaxtyping.UInt32
 	def incrementCondition(leafBelowSentinel, activeLeafNumber):
 		return jax.numpy.logical_and(activeLeafNumber > leavesTotal, leafBelowSentinel == 1)
 
-	def incrementDo(allValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32, jaxtyping.UInt32]):
+	def incrementDo(allValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32, jaxtyping.UInt32]):
 		foldingsSubTotal = allValues[5]
 		foldingsSubTotal = leavesTotal + foldingsSubTotal
 		return (allValues[0], allValues[1], allValues[2], allValues[3], allValues[4], foldingsSubTotal, allValues[6], allValues[7])
 
-	def dao(allValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32, jaxtyping.UInt32]):
-		def whileBacktrackingCondition(backtrackingValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32]):
+	def dao(allValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32, jaxtyping.UInt32]):
+		def whileBacktrackingCondition(backtrackingValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32]):
 			comparand = backtrackingValues[2]
 			return jax.numpy.logical_and(comparand > 0, jax.numpy.equal(activeGap1ndex, gapRangeStart.at[comparand - 1].get()))
 
-		def whileBacktrackingDo(backtrackingValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32]):
+		def whileBacktrackingDo(backtrackingValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32]):
 			backtrackAbove, backtrackBelow, activeLeafNumber = backtrackingValues
 
 			activeLeafNumber = activeLeafNumber - 1
@@ -166,7 +185,7 @@ def foldingsJAX(leavesTotal: jaxtyping.UInt32, dimensionsTotal: jaxtyping.UInt32
 		def if_activeLeaf1ndex_greaterThan_0(activeLeafNumber):
 			return activeLeafNumber > 0
 
-		def if_activeLeaf1ndex_greaterThan_0_do(leafPlacementValues: Tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
+		def if_activeLeaf1ndex_greaterThan_0_do(leafPlacementValues: tuple[jaxtyping.Array, jaxtyping.Array, jaxtyping.Array, jaxtyping.UInt32, jaxtyping.UInt32]):
 			placeLeafAbove, placeLeafBelow, placeGapRangeStart, activeLeafNumber, activeGapNumber = leafPlacementValues
 			activeGapNumber = activeGapNumber - 1
 			placeLeafAbove = placeLeafAbove.at[activeLeafNumber].set(gapsWhere.at[activeGapNumber].get())

mapFolding/reference/lunnanNumpy.py

@@ -1,7 +1,22 @@
 """
 A generally faithful translation of the original Atlas Autocode code by W. F. Lunnon to Python using NumPy.
-W. F. Lunnon, Multi-dimensional map-folding, The Computer Journal, Volume 14, Issue 1, 1971, Pages 75-80, https://doi.org/10.1093/comjnl/14.1.75
+
+This implementation transforms Lunnon's 1971 algorithm to leverage NumPy's array operations for improved
+performance while maintaining algorithmic fidelity. It preserves the core logic and variable naming
+conventions of the original algorithm but benefits from NumPy's vectorized operations and efficient
+memory management.
+
+Key characteristics:
+- Uses NumPy arrays instead of Python lists for better memory efficiency
+- Maintains the original algorithm structure and control flow
+- Preserves variable naming for algorithmic clarity
+- Offers significant performance improvements over pure Python implementations
+
+Reference:
+W. F. Lunnon, Multi-dimensional map-folding, The Computer Journal, Volume 14, Issue 1, 1971,
+Pages 75-80, https://doi.org/10.1093/comjnl/14.1.75
 """
+
 import numpy
 
 def foldings(p: list[int]) -> int:

mapFolding/reference/lunnanWhile.py

@@ -1,7 +1,21 @@
 """
 A largely faithful translation of the original Atlas Autocode code by W. F. Lunnon to Python using `while`.
-W. F. Lunnon, Multi-dimensional map-folding, The Computer Journal, Volume 14, Issue 1, 1971, Pages 75-80, https://doi.org/10.1093/comjnl/14.1.75
+
+This implementation closely follows the structure and logic of Lunnon's 1971 paper, preserving the
+variable names and core algorithm design. It uses while loops instead of Atlas Autocode's procedural
+control structures, maintaining the imperative programming style of the original.
+
+Key characteristics:
+- Preserves original algorithm structure for historical accuracy
+- Uses primarily scalar operations and explicit loops
+- Maintains the original variable naming from Lunnon's work
+- Provides a baseline for comparison against optimized implementations
+
+Reference:
+W. F. Lunnon, Multi-dimensional map-folding, The Computer Journal, Volume 14, Issue 1, 1971,
+Pages 75-80, https://doi.org/10.1093/comjnl/14.1.75
 """
+
 def foldings(p: list[int]) -> int:
 	"""
 	Run loop with (A, B) on each folding of a p[1] x ... x p[d] map, where A and B are the above and below vectors.

mapFolding/reference/rotatedEntryPoint.py

@@ -1,3 +1,21 @@
+"""
+Alternative algorithm entry point implementation for Lunnon's map folding algorithm.
+
+This implementation demonstrates an interesting algorithmic variation where the main processing
+loop is "rotated" to enter at a different point in the execution flow. Specifically, it's
+structured to enter at the modulo operator rather than the traditional starting point.
+
+Key characteristics:
+- Restructures the control flow by reorganizing the entry point of the algorithm
+- Separates preparation work from the main computational loop
+- Uses explicit variable naming with index constants for clarity
+- Demonstrates how the same algorithm can be approached from different entry points
+
+Note: This implementation is intentionally incomplete and requires supporting code from
+other modules to function. It serves primarily as a demonstration of how algorithmic
+structure can be creatively redesigned while maintaining the core computational approach.
+"""
+
 from mapFolding import outfitFoldings
 from numba import njit
 import numpy