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

mapFolding/reference/flattened.py

@@ -1,14 +1,33 @@
-"""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
-from typing import List, Any, Final, Optional, Union, Sequence, Tuple, Type, TypedDict
+from typing import Any, Final, TypedDict
 import enum
 import numpy
 import sys
 
-def countFolds(listDimensions: Sequence[int], computationDivisions = None, CPUlimit: Optional[Union[int, float, bool]] = None):
-	def doWhile():
+def countFolds(listDimensions: Sequence[int], computationDivisions: int | str | None = None, CPUlimit: int | float | bool | None = None) -> int:
+	def doWhile() -> None:
 
 		while activeLeafGreaterThan0Condition():
 
@@ -49,99 +68,99 @@ def countFolds(listDimensions: Sequence[int], computationDivisions = None, CPUli
 			if placeLeafCondition():
 				placeLeaf()
 
-	def activeGapIncrement():
+	def activeGapIncrement() -> None:
 		my[indexMy.gap1ndex] += 1
 
-	def activeLeafGreaterThan0Condition():
+	def activeLeafGreaterThan0Condition() -> bool:
 		return my[indexMy.leaf1ndex] > 0
 
-	def activeLeafGreaterThanLeavesTotalCondition():
+	def activeLeafGreaterThanLeavesTotalCondition() -> bool:
 		return my[indexMy.leaf1ndex] > the[indexThe.leavesTotal]
 
-	def activeLeafIsTheFirstLeafCondition():
+	def activeLeafIsTheFirstLeafCondition() -> bool:
 		return my[indexMy.leaf1ndex] <= 1
 
-	def activeLeafNotEqualToTaskDivisionsCondition():
+	def activeLeafNotEqualToTaskDivisionsCondition() -> bool:
 		return my[indexMy.leaf1ndex] != the[indexThe.taskDivisions]
 
-	def allDimensionsAreUnconstrained():
+	def allDimensionsAreUnconstrained() -> bool:
 		return my[indexMy.dimensionsUnconstrained] == the[indexThe.dimensionsTotal]
 
-	def backtrack():
+	def backtrack() -> None:
 		my[indexMy.leaf1ndex] -= 1
 		track[indexTrack.leafBelow, track[indexTrack.leafAbove, my[indexMy.leaf1ndex]]] = track[indexTrack.leafBelow, my[indexMy.leaf1ndex]]
 		track[indexTrack.leafAbove, track[indexTrack.leafBelow, my[indexMy.leaf1ndex]]] = track[indexTrack.leafAbove, my[indexMy.leaf1ndex]]
 
-	def backtrackCondition():
+	def backtrackCondition() -> bool:
 		return my[indexMy.leaf1ndex] > 0 and my[indexMy.gap1ndex] == track[indexTrack.gapRangeStart, my[indexMy.leaf1ndex] - 1]
 
-	def computationDivisionsCondition():
+	def computationDivisionsCondition() -> bool:
 		return the[indexThe.taskDivisions] == int(False)
 
-	def countGaps():
+	def countGaps() -> None:
 		gapsWhere[my[indexMy.gap1ndexCeiling]] = my[indexMy.leafConnectee]
 		if track[indexTrack.countDimensionsGapped, my[indexMy.leafConnectee]] == 0:
 			gap1ndexCeilingIncrement()
 		track[indexTrack.countDimensionsGapped, my[indexMy.leafConnectee]] += 1
 
-	def dimension1ndexIncrement():
+	def dimension1ndexIncrement() -> None:
 		my[indexMy.dimension1ndex] += 1
 
-	def dimensionsUnconstrainedCondition():
+	def dimensionsUnconstrainedCondition() -> bool:
 		return connectionGraph[my[indexMy.dimension1ndex], my[indexMy.leaf1ndex], my[indexMy.leaf1ndex]] == my[indexMy.leaf1ndex]
 
-	def dimensionsUnconstrainedIncrement():
+	def dimensionsUnconstrainedIncrement() -> None:
 		my[indexMy.dimensionsUnconstrained] += 1
 
-	def filterCommonGaps():
+	def filterCommonGaps() -> None:
 		gapsWhere[my[indexMy.gap1ndex]] = gapsWhere[my[indexMy.indexMiniGap]]
 		if track[indexTrack.countDimensionsGapped, gapsWhere[my[indexMy.indexMiniGap]]] == the[indexThe.dimensionsTotal] - my[indexMy.dimensionsUnconstrained]:
 			activeGapIncrement()
 		track[indexTrack.countDimensionsGapped, gapsWhere[my[indexMy.indexMiniGap]]] = 0
 
-	def findGapsInitializeVariables():
+	def findGapsInitializeVariables() -> None:
 		my[indexMy.dimensionsUnconstrained] = 0
 		my[indexMy.gap1ndexCeiling] = track[indexTrack.gapRangeStart, my[indexMy.leaf1ndex] - 1]
 		my[indexMy.dimension1ndex] = 1
 
-	def foldsSubTotalsIncrement():
+	def foldsSubTotalsIncrement() -> None:
 		foldsSubTotals[my[indexMy.taskIndex]] += the[indexThe.leavesTotal]
 
-	def gap1ndexCeilingIncrement():
+	def gap1ndexCeilingIncrement() -> None:
 		my[indexMy.gap1ndexCeiling] += 1
 
-	def indexMiniGapIncrement():
+	def indexMiniGapIncrement() -> None:
 		my[indexMy.indexMiniGap] += 1
 
-	def indexMiniGapInitialization():
+	def indexMiniGapInitialization() -> None:
 		my[indexMy.indexMiniGap] = my[indexMy.gap1ndex]
 
-	def insertUnconstrainedLeaf():
+	def insertUnconstrainedLeaf() -> None:
 		my[indexMy.indexLeaf] = 0
 		while my[indexMy.indexLeaf] < my[indexMy.leaf1ndex]:
 			gapsWhere[my[indexMy.gap1ndexCeiling]] = my[indexMy.indexLeaf]
 			my[indexMy.gap1ndexCeiling] += 1
 			my[indexMy.indexLeaf] += 1
 
-	def leafBelowSentinelIs1Condition():
+	def leafBelowSentinelIs1Condition() -> bool:
 		return track[indexTrack.leafBelow, 0] == 1
 
-	def leafConnecteeInitialization():
+	def leafConnecteeInitialization() -> None:
 		my[indexMy.leafConnectee] = connectionGraph[my[indexMy.dimension1ndex], my[indexMy.leaf1ndex], my[indexMy.leaf1ndex]]
 
-	def leafConnecteeUpdate():
+	def leafConnecteeUpdate() -> None:
 		my[indexMy.leafConnectee] = connectionGraph[my[indexMy.dimension1ndex], my[indexMy.leaf1ndex], track[indexTrack.leafBelow, my[indexMy.leafConnectee]]]
 
-	def loopingLeavesConnectedToActiveLeaf():
+	def loopingLeavesConnectedToActiveLeaf() -> bool:
 		return my[indexMy.leafConnectee] != my[indexMy.leaf1ndex]
 
-	def loopingTheDimensions():
+	def loopingTheDimensions() -> bool:
 		return my[indexMy.dimension1ndex] <= the[indexThe.dimensionsTotal]
 
-	def loopingToActiveGapCeiling():
+	def loopingToActiveGapCeiling() -> bool:
 		return my[indexMy.indexMiniGap] < my[indexMy.gap1ndexCeiling]
 
-	def placeLeaf():
+	def placeLeaf() -> None:
 		my[indexMy.gap1ndex] -= 1
 		track[indexTrack.leafAbove, my[indexMy.leaf1ndex]] = gapsWhere[my[indexMy.gap1ndex]]
 		track[indexTrack.leafBelow, my[indexMy.leaf1ndex]] = track[indexTrack.leafBelow, track[indexTrack.leafAbove, my[indexMy.leaf1ndex]]]
@@ -150,13 +169,13 @@ def countFolds(listDimensions: Sequence[int], computationDivisions = None, CPUli
 		track[indexTrack.gapRangeStart, my[indexMy.leaf1ndex]] = my[indexMy.gap1ndex]
 		my[indexMy.leaf1ndex] += 1
 
-	def placeLeafCondition():
+	def placeLeafCondition() -> bool:
 		return my[indexMy.leaf1ndex] > 0
 
-	def taskIndexCondition():
+	def taskIndexCondition() -> bool:
 		return my[indexMy.leafConnectee] % the[indexThe.taskDivisions] == my[indexMy.taskIndex]
 
-	def thereAreComputationDivisionsYouMightSkip():
+	def thereAreComputationDivisionsYouMightSkip() -> bool:
 		if computationDivisionsCondition():
 			return True
 		if activeLeafNotEqualToTaskDivisionsCondition():
@@ -166,11 +185,11 @@ def countFolds(listDimensions: Sequence[int], computationDivisions = None, CPUli
 		return False
 
 	stateUniversal = outfitFoldings(listDimensions, computationDivisions=computationDivisions, CPUlimit=CPUlimit)
-	connectionGraph: Final[numpy.ndarray] = stateUniversal['connectionGraph']
+	connectionGraph: Final[NDArray[numpy.integer[Any]]] = stateUniversal['connectionGraph']
 	foldsSubTotals = stateUniversal['foldsSubTotals']
 	gapsWhere = stateUniversal['gapsWhere']
 	my = stateUniversal['my']
-	the: Final[numpy.ndarray] = stateUniversal['the']
+	the: Final[NDArray[numpy.integer[Any]]] = stateUniversal['the']
 	track = stateUniversal['track']
 
 	if the[indexThe.taskDivisions] == int(False):
@@ -192,7 +211,7 @@ def countFolds(listDimensions: Sequence[int], computationDivisions = None, CPUli
 class EnumIndices(enum.IntEnum):
 	"""Base class for index enums."""
 	@staticmethod
-	def _generate_next_value_(name, start, count, last_values):
+	def _generate_next_value_(name: str, start: int, count: int, last_values: list[int]) -> int:
 		"""0-indexed."""
 		return count
 
@@ -229,7 +248,7 @@ class indexTrack(EnumIndices):
 class computationState(TypedDict):
 	connectionGraph: NDArray[integer[Any]]
 	foldsSubTotals: NDArray[integer[Any]]
-	mapShape: Tuple[int, ...]
+	mapShape: tuple[int, ...]
 	my: NDArray[integer[Any]]
 	gapsWhere: NDArray[integer[Any]]
 	the: NDArray[integer[Any]]
@@ -262,7 +281,7 @@ def getLeavesTotal(listDimensions: Sequence[int]) -> int:
 
 		return productDimensions
 
-def getTaskDivisions(computationDivisions: Optional[Union[int, str]], concurrencyLimit: int, CPUlimit: Optional[Union[bool, float, int]], listDimensions: Sequence[int]):
+def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: int, CPUlimit: bool | float | int | None, listDimensions: Sequence[int]) -> int:
 	if not computationDivisions:
 		return 0
 	else:
@@ -284,7 +303,7 @@ def getTaskDivisions(computationDivisions: Optional[Union[int, str]], concurrenc
 
 	return taskDivisions
 
-def makeConnectionGraph(listDimensions: Sequence[int], **keywordArguments: Optional[Type]) -> NDArray[integer[Any]]:
+def makeConnectionGraph(listDimensions: Sequence[int], **keywordArguments: type | None) -> NDArray[integer[Any]]:
 	datatype = keywordArguments.get('datatype', dtypeMedium)
 	mapShape = validateListDimensions(listDimensions)
 	leavesTotal = getLeavesTotal(mapShape)
@@ -316,12 +335,12 @@ def makeConnectionGraph(listDimensions: Sequence[int], **keywordArguments: Optio
 					connectionGraph[dimension1ndex, activeLeaf1ndex, connectee1ndex] = connectee1ndex
 	return connectionGraph
 
-def makeDataContainer(shape, datatype: Optional[Type] = None):
+def makeDataContainer(shape: int | Sequence[int], datatype: type | None = None) -> NDArray[integer[Any]]:
 	if datatype is None:
 		datatype = dtypeMedium
 	return numpy.zeros(shape, dtype=datatype)
 
-def outfitFoldings(listDimensions: Sequence[int], computationDivisions: Optional[Union[int, str]] = None, CPUlimit: Optional[Union[bool, float, int]] = None, **keywordArguments: Optional[Type]) -> computationState:
+def outfitFoldings(listDimensions: Sequence[int], computationDivisions: int | str | None = None, CPUlimit: bool | float | int | None = None, **keywordArguments: type | None) -> computationState:
 	datatypeMedium = keywordArguments.get('datatypeMedium', dtypeMedium)
 	datatypeLarge = keywordArguments.get('datatypeLarge', dtypeLarge)
 
@@ -346,10 +365,10 @@ def outfitFoldings(listDimensions: Sequence[int], computationDivisions: Optional
 	stateInitialized['my'][indexMy.leaf1ndex] = 1
 	return stateInitialized
 
-def parseDimensions(dimensions: Sequence[int], parameterName: str = 'unnamed parameter') -> List[int]:
+def parseDimensions(dimensions: Sequence[int], parameterName: str = 'unnamed parameter') -> list[int]:
 	# listValidated = intInnit(dimensions, parameterName)
 	listNOTValidated = dimensions if isinstance(dimensions, (list, tuple)) else list(dimensions)
-	listNonNegative = []
+	listNonNegative: list[int] = []
 	for dimension in listNOTValidated:
 		if dimension < 0:
 			raise ValueError(f"Dimension {dimension} must be non-negative")
@@ -358,7 +377,7 @@ def parseDimensions(dimensions: Sequence[int], parameterName: str = 'unnamed par
 		raise ValueError("At least one dimension must be non-negative")
 	return listNonNegative
 
-def setCPUlimit(CPUlimit: Union[bool, float, int, None]) -> int:
+def setCPUlimit(CPUlimit: bool | float | int | None) -> int:
 	# if not (CPUlimit is None or isinstance(CPUlimit, (bool, int, float))):
 	#	 CPUlimit = oopsieKwargsie(CPUlimit)
 	# concurrencyLimit = defineConcurrencyLimit(CPUlimit)
@@ -367,7 +386,7 @@ def setCPUlimit(CPUlimit: Union[bool, float, int, None]) -> int:
 	concurrencyLimit = concurrencyLimitHARDCODED
 	return concurrencyLimit
 
-def validateListDimensions(listDimensions: Sequence[int]) -> List[int]:
+def validateListDimensions(listDimensions: Sequence[int]) -> list[int]:
 	if not listDimensions:
 		raise ValueError(f"listDimensions is a required parameter.")
 	listNonNegative = parseDimensions(listDimensions, 'listDimensions')

mapFolding/reference/hunterNumba.py

@@ -1,9 +1,33 @@
-from typing import List
+"""
+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
 
 @numba.jit(cache=True, nopython=True, fastmath=True)
-def countFolds(listDimensions: List[int]) -> int:
+def countFolds(listDimensions: list[int]) -> int:
 	"""
 	Count the number of distinct ways to fold a map with at least two positive dimensions.
 
@@ -13,10 +37,10 @@ def countFolds(listDimensions: List[int]) -> int:
 	Returns:
 		foldsTotal: The total number of distinct folds for the given map dimensions.
 	"""
-	def integerSmall(value) -> numpy.uint8:
+	def integerSmall(value: numpy.integer[Any] | Any) -> numpy.uint8:
 		return numpy.uint8(value)
 
-	def integerLarge(value) -> numpy.uint64:
+	def integerLarge(value: numpy.integer[Any] | Any) -> numpy.uint64:
 		return numpy.uint64(value)
 
 	dtypeMedium = numpy.uint8

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
 
-Citation: mapFolding/citations/jOEIS.bibtex
+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,11 +1,25 @@
 """
 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
 """
-from typing import List
+
 import numpy
 
-def foldings(p: List[int]) -> int:
+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.
 
@@ -66,7 +80,7 @@ def foldings(p: List[int]) -> int:
 	# D[i][l][m] = leaf connected to m in section i when inserting l;
 
 	G: int = 0
-	l: int = 1
+	l = 1
 
 	# kick off with null folding
 	while l > 0:
@@ -86,7 +100,7 @@ def foldings(p: List[int]) -> int:
 					if D[i][l][l] == l:
 						dd = dd + 1
 					else:
-						m: int = D[i][l][l]
+						m = D[i][l][l]
 						while m != l:
 							gap[gg] = m
 							if count[m] == 0:

mapFolding/reference/lunnanWhile.py

@@ -1,10 +1,22 @@
 """
 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
 """
-from typing import Sequence
 
-def foldings(p: Sequence[int]) -> int:
+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.
 
@@ -38,8 +50,8 @@ def foldings(p: Sequence[int]) -> int:
 	# and later gap[gapter[l]] is the gap where leaf l is currently inserted
 
 	P = [1] * (d + 1)
-	C = [[0] * (n + 1) for dimension1 in range(d + 1)]
-	D = [[[0] * (n + 1) for dimension2 in range(n + 1)] for dimension1 in range(d + 1)]
+	C = [[0] * (n + 1) for _dimension1 in range(d + 1)]
+	D = [[[0] * (n + 1) for _dimension2 in range(n + 1)] for _dimension1 in range(d + 1)]
 
 	for i in range(1, d + 1):
 		P[i] = P[i - 1] * p[i - 1]
@@ -65,7 +77,7 @@ def foldings(p: Sequence[int]) -> int:
 	# D[i][l][m] = leaf connected to m in section i when inserting l;
 
 	G: int = 0
-	l: int = 1
+	l = 1
 
 	# kick off with null folding
 	while l > 0:
@@ -84,7 +96,7 @@ def foldings(p: Sequence[int]) -> int:
 				if D[i][l][l] == l:
 					dd = dd + 1
 				else:
-					m: int = D[i][l][l]
+					m = D[i][l][l]
 					while m != l:
 						gap[gg] = m
 						if count[m] == 0:

mapFolding/reference/rotatedEntryPoint.py

@@ -1,6 +1,23 @@
+"""
+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
-from typing import List
 import numpy
 from numpy.typing import NDArray
 
@@ -42,7 +59,7 @@ tricky = [
 
 COUNTindicesStatic = len(tricky)
 
-def countFolds(listDimensions: List[int]):
+def countFolds(listDimensions: list[int]):
 	static = numpy.zeros(COUNTindicesStatic, dtype=numpy.int64)
 
 	listDimensions, static[leavesTotal], D, track,gapsWhere = outfitFoldings(listDimensions)
@@ -55,7 +72,7 @@ def countFolds(listDimensions: List[int]):
 	return foldingsTotal
 
 # @recordBenchmarks()
-def _sherpa(track: NDArray, gap: NDArray, static: NDArray, D: NDArray, p: List[int]):
+def _sherpa(track: NDArray, gap: NDArray, static: NDArray, D: NDArray, p: list[int]):
 	"""Performance critical section that counts foldings.
 
 	Parameters: