mapFolding 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

mapFolding/reference/lunnanWhile.py

@@ -0,0 +1,121 @@
+"""
+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
+"""
+from typing import Sequence
+
+def foldings(p: Sequence[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.
+
+	Parameters:
+		p: An array of integers representing the dimensions of the map.
+
+	Returns:
+		G: The number of distinct foldings for the given map dimensions.
+
+	NOTE If there are fewer than two dimensions, any dimensions are not positive, or any dimensions are not integers, the output will be unreliable.
+	"""
+
+	g: int = 0
+	d: int = len(p)
+	n: int = 1
+	for i in range(d):
+		n = n * p[i]
+
+	# d dimensions and n leaves
+
+	A = [0] * (n + 1)
+	B = [0] * (n + 1)
+	count = [0] * (n + 1)
+	gapter = [0] * (n + 1)
+	gap = [0] * (n * n + 1)
+
+	# B[m] is the leaf below leaf m in the current folding,
+	# A[m] the leaf above. count[m] is the no. of sections in which
+	# there is a gap for the new leaf l below leaf m,
+	# gap[gapter[l - 1] + j] is the j-th (possible or actual) gap for leaf l,
+	# 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)]
+
+	for i in range(1, d + 1):
+		P[i] = P[i - 1] * p[i - 1]
+
+	for i in range(1, d + 1):
+		for m in range(1, n + 1):
+			C[i][m] = ((m - 1) // P[i - 1]) - ((m - 1) // P[i]) * p[i - 1] + 1
+
+	for i in range(1, d + 1):
+		for l in range(1, n + 1):
+			for m in range(1, l + 1):
+				if C[i][l] - C[i][m] == (C[i][l] - C[i][m]) // 2 * 2: # !
+					if C[i][m] == 1:
+						D[i][l][m] = m
+					else:
+						D[i][l][m] = m - P[i - 1]
+				else:
+					if C[i][m] == p[i - 1] or m + P[i - 1] > l:
+						D[i][l][m] = m
+					else:
+						D[i][l][m] = m + P[i - 1]
+	# P[i] = p[1] x ... x p[i], C[i][m] = i-th co-ordinate of leaf m,
+	# D[i][l][m] = leaf connected to m in section i when inserting l;
+
+	G: int = 0
+	l: int = 1
+
+	# kick off with null folding
+	while l > 0:
+		if l > n:
+			G = G + 1
+		else:
+			dd: int = 0
+			gg: int = gapter[l - 1]
+			g = gg
+			# dd is the no. of sections in which l is unconstrained,
+			# gg the no. of possible and g the no. of actual gaps for l, + gapter[l - 1]
+
+			# find the possible gaps for leaf l in each section,
+			# then discard those not common to all. All possible if dd = d
+			for i in range(1, d + 1):
+				if D[i][l][l] == l:
+					dd = dd + 1
+				else:
+					m: int = D[i][l][l]
+					while m != l:
+						gap[gg] = m
+						if count[m] == 0:
+							gg = gg + 1
+						count[m] += 1
+						m = D[i][l][B[m]]
+
+			if dd == d:
+				for m in range(l):
+					gap[gg] = m
+					gg = gg + 1
+
+			for j in range(g, gg):
+				gap[g] = gap[j]
+				if count[gap[j]] == d - dd:
+					g = g + 1
+				count[gap[j]] = 0
+
+		# for each gap insert leaf l, [the main while loop shall progress],
+		# remove leaf l
+		while l > 0 and g == gapter[l - 1]:
+			l = l - 1
+			B[A[l]] = B[l]
+			A[B[l]] = A[l]
+
+		if l > 0:
+			g = g - 1
+			A[l] = gap[g]
+			B[l] = B[A[l]]
+			B[A[l]] = l
+			A[B[l]] = l
+			gapter[l] = g
+			l = l + 1
+	return G

mapFolding/reference/rotatedEntryPoint.py

@@ -0,0 +1,240 @@
+from mapFolding import outfitFoldings
+from numba import njit
+from typing import List
+import numpy
+from numpy.typing import NDArray
+
+"""
+It is possible to enter the main `while` loop from an arbitrary point. This version is "rotated" to effectively enter at the modulo operator.
+"""
+
+# Indices of array `track`, which is a collection of one-dimensional arrays each of length `the[leavesTotal] + 1`.
+# The values in the array cells are dynamic, small, unsigned integers.
+A = leafAbove = 0
+"""Leaf above leaf m"""
+B = leafBelow = 1
+"""Leaf below leaf m"""
+count = countDimensionsGapped = 2
+"""Number of gaps available for leaf l"""
+gapter = gapRangeStart = 3
+"""Index of gap stack for leaf l"""
+
+# Indices of array `my`, which holds dynamic, small, unsigned, integer values.
+tricky = [
+(leaf1ndex := 0),
+(gap1ndex := 1),
+(unconstrainedLeaf := 2),
+(gap1ndexCeiling := 3),
+(leafConnectee := 4),
+(taskIndex := 5),
+(dimension1ndex := 6),
+(foldingsSubtotal := 7),
+]
+
+COUNTindicesDynamic = len(tricky)
+
+# Indices of array `the`, which holds unchanging, small, unsigned, integer values.
+tricky = [
+(dimensionsPlus1 := 0),
+(dimensionsTotal := 1),
+(leavesTotal := 2),
+]
+
+COUNTindicesStatic = len(tricky)
+
+def countFolds(listDimensions: List[int]):
+	static = numpy.zeros(COUNTindicesStatic, dtype=numpy.int64)
+
+	listDimensions, static[leavesTotal], D, track,gapsWhere = outfitFoldings(listDimensions)
+
+	static[dimensionsTotal] = len(listDimensions)
+	static[dimensionsPlus1] = static[dimensionsTotal] + 1
+
+	# Pass listDimensions and taskDivisions to _sherpa for benchmarking
+	foldingsTotal = _sherpa(track, gapsWhere, static, D, listDimensions)
+	return foldingsTotal
+
+# @recordBenchmarks()
+def _sherpa(track: NDArray, gap: NDArray, static: NDArray, D: NDArray, p: List[int]):
+	"""Performance critical section that counts foldings.
+
+	Parameters:
+		track: Array tracking folding state
+		gap: Array for potential gaps
+		static: Array containing static configuration values
+		D: Array of leaf connections
+		p: List of dimensions for benchmarking
+	"""
+	foldingsTotal = countFoldings(track, gap, static, D)
+	return foldingsTotal
+
+@njit(cache=True, parallel=False, fastmath=False)
+def countFoldings(TEMPLATEtrack: NDArray,
+					TEMPLATEgapsWhere: NDArray,
+					the: NDArray,
+					connectionGraph: NDArray
+					):
+
+	TEMPLATEmy = numpy.zeros(COUNTindicesDynamic, dtype=numpy.int64)
+	TEMPLATEmy[leaf1ndex] = 1
+
+	taskDivisions = 0
+	# taskDivisions = the[leavesTotal]
+	TEMPLATEmy[taskIndex] = taskDivisions - 1 # the first modulo is leavesTotal - 1
+
+	def prepareWork(track: NDArray,
+					gapsWhere: NDArray,
+					my: NDArray) -> tuple[NDArray, NDArray, NDArray]:
+		foldingsTotal = 0
+		while True:
+			if my[leaf1ndex] <= 1 or track[leafBelow][0] == 1:
+				if my[leaf1ndex] > the[leavesTotal]:
+					foldingsTotal += the[leavesTotal]
+				else:
+					my[unconstrainedLeaf] = 0
+					my[gap1ndexCeiling] = track[gapRangeStart][my[leaf1ndex] - 1]
+					my[gap1ndex] = my[gap1ndexCeiling]
+
+					for PREPAREdimension1ndex in range(1, the[dimensionsPlus1]):
+						if connectionGraph[PREPAREdimension1ndex][my[leaf1ndex]][my[leaf1ndex]] == my[leaf1ndex]:
+							my[unconstrainedLeaf] += 1
+						else:
+							my[leafConnectee] = connectionGraph[PREPAREdimension1ndex][my[leaf1ndex]][my[leaf1ndex]]
+							while my[leafConnectee] != my[leaf1ndex]:
+
+								if my[leafConnectee] != my[leaf1ndex]:
+									my[dimension1ndex] = PREPAREdimension1ndex
+									return track, gapsWhere, my
+
+								if my[leaf1ndex] != the[leavesTotal]:
+									gapsWhere[my[gap1ndexCeiling]] = my[leafConnectee]
+									if track[countDimensionsGapped][my[leafConnectee]] == 0:
+										my[gap1ndexCeiling] += 1
+									track[countDimensionsGapped][my[leafConnectee]] += 1
+								else:
+									print("else")
+									my[dimension1ndex] = PREPAREdimension1ndex
+									return track, gapsWhere, my
+									# PREPAREmy[leafConnectee] % the[leavesTotal] == PREPAREmy[taskIndex]
+								my[leafConnectee] = connectionGraph[dimension1ndex][my[leaf1ndex]][track[leafBelow][my[leafConnectee]]]
+
+					if my[unconstrainedLeaf] == the[dimensionsTotal]:
+						for indexLeaf in range(my[leaf1ndex]):
+							gapsWhere[my[gap1ndexCeiling]] = indexLeaf
+							my[gap1ndexCeiling] += 1
+
+					for indexMiniGap in range(my[gap1ndex], my[gap1ndexCeiling]):
+						gapsWhere[my[gap1ndex]] = gapsWhere[indexMiniGap]
+						if track[countDimensionsGapped][gapsWhere[indexMiniGap]] == the[dimensionsTotal] - my[unconstrainedLeaf]:
+							my[gap1ndex] += 1
+						track[countDimensionsGapped][gapsWhere[indexMiniGap]] = 0
+
+			while my[leaf1ndex] > 0 and my[gap1ndex] == track[gapRangeStart][my[leaf1ndex] - 1]:
+				my[leaf1ndex] -= 1
+				track[leafBelow][track[leafAbove][my[leaf1ndex]]] = track[leafBelow][my[leaf1ndex]]
+				track[leafAbove][track[leafBelow][my[leaf1ndex]]] = track[leafAbove][my[leaf1ndex]]
+
+			if my[leaf1ndex] > 0:
+				my[gap1ndex] -= 1
+				track[leafAbove][my[leaf1ndex]] = gapsWhere[my[gap1ndex]]
+				track[leafBelow][my[leaf1ndex]] = track[leafBelow][track[leafAbove][my[leaf1ndex]]]
+				track[leafBelow][track[leafAbove][my[leaf1ndex]]] = my[leaf1ndex]
+				track[leafAbove][track[leafBelow][my[leaf1ndex]]] = my[leaf1ndex]
+				track[gapRangeStart][my[leaf1ndex]] = my[gap1ndex]
+				my[leaf1ndex] += 1
+
+	RETURNtrack, RETURNgapsWhere, RETURNmy = prepareWork(TEMPLATEtrack.copy(), TEMPLATEgapsWhere.copy(), TEMPLATEmy.copy())
+
+	foldingsTotal = doWork(RETURNtrack.copy(), RETURNgapsWhere.copy(), RETURNmy.copy(), the, connectionGraph, taskDivisions)
+
+	return foldingsTotal
+
+@njit(cache=True, parallel=False, fastmath=False)
+def doWork(track: NDArray,
+				gapsWhere: NDArray,
+				my: NDArray,
+				the: NDArray,
+				connectionGraph: NDArray,
+				taskDivisions: int = 0
+				):
+
+	papasGotABrandNewBag = True
+	if_activeLeaf1ndex_LTE_1_or_leafBelow_index_0_equals_1 = True
+	for_dimension1ndex_in_range_1_to_dimensionsPlus1 = True
+	while_leaf1ndexConnectee_notEquals_activeLeaf1ndex = True
+
+	thisIsNotTheFirstPass = False
+
+	while papasGotABrandNewBag:
+		if my[leaf1ndex] <= 1 or track[leafBelow][0] == 1 or if_activeLeaf1ndex_LTE_1_or_leafBelow_index_0_equals_1 == True:
+			if_activeLeaf1ndex_LTE_1_or_leafBelow_index_0_equals_1 = False
+			if my[leaf1ndex] > the[leavesTotal] and thisIsNotTheFirstPass:
+				my[foldingsSubtotal] += the[leavesTotal]
+			else:
+				if thisIsNotTheFirstPass:
+					my[unconstrainedLeaf] = 0
+					my[gap1ndexCeiling] = track[gapRangeStart][my[leaf1ndex] - 1]
+					my[gap1ndex] = my[gap1ndexCeiling]
+
+				for_dimension1ndex_in_range_1_to_dimensionsPlus1 = True
+				while for_dimension1ndex_in_range_1_to_dimensionsPlus1 == True:
+					for_dimension1ndex_in_range_1_to_dimensionsPlus1 = False
+					if connectionGraph[my[dimension1ndex]][my[leaf1ndex]][my[leaf1ndex]] == my[leaf1ndex] and thisIsNotTheFirstPass:
+						my[unconstrainedLeaf] += 1
+					else:
+						if thisIsNotTheFirstPass:
+							my[leafConnectee] = connectionGraph[my[dimension1ndex]][my[leaf1ndex]][my[leaf1ndex]]
+						if my[leafConnectee] != my[leaf1ndex]:
+							while_leaf1ndexConnectee_notEquals_activeLeaf1ndex = True
+
+						while while_leaf1ndexConnectee_notEquals_activeLeaf1ndex == True:
+							while_leaf1ndexConnectee_notEquals_activeLeaf1ndex = False
+							thisIsNotTheFirstPass = True
+							if taskDivisions==0 or my[leaf1ndex] != taskDivisions:
+								myTask = True
+							else:
+								modulo = my[leafConnectee] % the[leavesTotal]
+								if modulo == my[taskIndex]: myTask = True
+								else:
+									myTask = False
+							if myTask:
+								gapsWhere[my[gap1ndexCeiling]] = my[leafConnectee]
+								if track[countDimensionsGapped][my[leafConnectee]] == 0:
+									my[gap1ndexCeiling] += 1
+								track[countDimensionsGapped][my[leafConnectee]] += 1
+							my[leafConnectee] = connectionGraph[my[dimension1ndex]][my[leaf1ndex]][track[leafBelow][my[leafConnectee]]]
+							if my[leafConnectee] != my[leaf1ndex]:
+								while_leaf1ndexConnectee_notEquals_activeLeaf1ndex = True
+					my[dimension1ndex] += 1
+					if my[dimension1ndex] < the[dimensionsPlus1]:
+						for_dimension1ndex_in_range_1_to_dimensionsPlus1 = True
+					else:
+						my[dimension1ndex] = 1
+
+				if my[unconstrainedLeaf] == the[dimensionsTotal]:
+					for leaf1ndex in range(my[leaf1ndex]):
+						gapsWhere[my[gap1ndexCeiling]] = leaf1ndex
+						my[gap1ndexCeiling] += 1
+
+				for indexMiniGap in range(my[gap1ndex], my[gap1ndexCeiling]):
+					gapsWhere[my[gap1ndex]] = gapsWhere[indexMiniGap]
+					if track[countDimensionsGapped][gapsWhere[indexMiniGap]] == the[dimensionsTotal] - my[unconstrainedLeaf]:
+						my[gap1ndex] += 1
+					track[countDimensionsGapped][gapsWhere[indexMiniGap]] = 0
+
+		while my[leaf1ndex] > 0 and my[gap1ndex] == track[gapRangeStart][my[leaf1ndex] - 1]:
+			my[leaf1ndex] -= 1
+			track[leafBelow][track[leafAbove][my[leaf1ndex]]] = track[leafBelow][my[leaf1ndex]]
+			track[leafAbove][track[leafBelow][my[leaf1ndex]]] = track[leafAbove][my[leaf1ndex]]
+
+		if my[leaf1ndex] > 0:
+			my[gap1ndex] -= 1
+			track[leafAbove][my[leaf1ndex]] = gapsWhere[my[gap1ndex]]
+			track[leafBelow][my[leaf1ndex]] = track[leafBelow][track[leafAbove][my[leaf1ndex]]]
+			track[leafBelow][track[leafAbove][my[leaf1ndex]]] = my[leaf1ndex]
+			track[leafAbove][track[leafBelow][my[leaf1ndex]]] = my[leaf1ndex]
+			track[gapRangeStart][my[leaf1ndex]] = my[gap1ndex]
+			my[leaf1ndex] += 1
+
+		if my[leaf1ndex] <= 0:
+			return my[foldingsSubtotal]

mapFolding/reference/total_countPlus1vsPlusN.py

@@ -0,0 +1,211 @@
+from numba import njit
+import numpy
+
+@njit(cache=True)
+def foldings_plus_1(p: list[int], computationDivisions: int = 0, computationIndex: int = 0) -> int:
+	n: int = 1  # Total number of leaves
+	for dimension in p:
+		n *= dimension
+
+	d = len(p)  # Number of dimensions
+	# Compute arrays P, C, D as per the algorithm
+	P = numpy.ones(d + 1, dtype=numpy.int64)
+	for i in range(1, d + 1):
+		P[i] = P[i - 1] * p[i - 1]
+
+	# C[i][m] holds the i-th coordinate of leaf m
+	C = numpy.zeros((d + 1, n + 1), dtype=numpy.int64)
+	for i in range(1, d + 1):
+		for m in range(1, n + 1):
+			C[i][m] = ((m - 1) // P[i - 1]) - ((m - 1) // P[i]) * p[i - 1] + 1
+
+	# D[i][l][m] computes the leaf connected to m in section i when inserting l
+	D = numpy.zeros((d + 1, n + 1, n + 1), dtype=numpy.int64)
+	for i in range(1, d + 1):
+		for l in range(1, n + 1):
+			for m in range(1, l + 1):
+				delta = C[i][l] - C[i][m]
+				if delta % 2 == 0:
+					# If delta is even
+					if C[i][m] == 1:
+						D[i][l][m] = m
+					else:
+						D[i][l][m] = m - P[i - 1]
+				else:
+					# If delta is odd
+					if C[i][m] == p[i - 1] or m + P[i - 1] > l:
+						D[i][l][m] = m
+					else:
+						D[i][l][m] = m + P[i - 1]
+	# Initialize arrays/lists
+	A = numpy.zeros(n + 1, dtype=numpy.int64)	   # Leaf above leaf m
+	B = numpy.zeros(n + 1, dtype=numpy.int64)	   # Leaf below leaf m
+	count = numpy.zeros(n + 1, dtype=numpy.int64)   # Counts for potential gaps
+	gapter = numpy.zeros(n + 1, dtype=numpy.int64)  # Indices for gap stack per leaf
+	gap = numpy.zeros(n * n + 1, dtype=numpy.int64) # Stack of potential gaps
+
+
+	# Initialize variables for backtracking
+	total_count = 0  # Total number of foldings
+	g = 0			# Gap index
+	l = 1			# Current leaf
+
+	# Start backtracking loop
+	while l > 0:
+		# If we have processed all leaves, increment total count
+		if l > n:
+			total_count += 1
+		else:
+			dd = 0	 # Number of sections where leaf l is unconstrained
+			gg = g	 # Temporary gap index
+			g = gapter[l - 1]  # Reset gap index for current leaf
+
+			# Count possible gaps for leaf l in each section
+			for i in range(1, d + 1):
+				if D[i][l][l] == l:
+					dd += 1
+				else:
+					m = D[i][l][l]
+					while m != l:
+						if computationDivisions == 0 or l != computationDivisions or m % computationDivisions == computationIndex:
+							gap[gg] = m
+							if count[m] == 0:
+								gg += 1
+							count[m] += 1
+						m = D[i][l][B[m]]
+
+			# If leaf l is unconstrained in all sections, it can be inserted anywhere
+			if dd == d:
+				for m in range(l):
+					gap[gg] = m
+					gg += 1
+
+			# Filter gaps that are common to all sections
+			for j in range(g, gg):
+				gap[g] = gap[j]
+				if count[gap[j]] == d - dd:
+					g += 1
+				count[gap[j]] = 0  # Reset count for next iteration
+
+		# Recursive backtracking steps
+		while l > 0 and g == gapter[l - 1]:
+			l -= 1
+			B[A[l]] = B[l]
+			A[B[l]] = A[l]
+
+		if l > 0:
+			g -= 1
+			A[l] = gap[g]
+			B[l] = B[A[l]]
+			B[A[l]] = l
+			A[B[l]] = l
+			gapter[l] = g  # Save current gap index
+			l += 1		 # Move to next leaf
+
+	return total_count
+
+@njit(cache=True)
+def foldings(p: list[int], computationDivisions: int = 0, computationIndex: int = 0) -> int:
+	n: int = 1  # Total number of leaves
+	for dimension in p:
+		n *= dimension
+
+	d = len(p)  # Number of dimensions
+	# Compute arrays P, C, D as per the algorithm
+	P = numpy.ones(d + 1, dtype=numpy.int64)
+	for i in range(1, d + 1):
+		P[i] = P[i - 1] * p[i - 1]
+
+	# C[i][m] holds the i-th coordinate of leaf m
+	C = numpy.zeros((d + 1, n + 1), dtype=numpy.int64)
+	for i in range(1, d + 1):
+		for m in range(1, n + 1):
+			C[i][m] = ((m - 1) // P[i - 1]) - ((m - 1) // P[i]) * p[i - 1] + 1
+			# C[i][m] = ((m - 1) // P[i - 1]) % p[i - 1] + 1 # NOTE different, but either one works
+
+	# D[i][l][m] computes the leaf connected to m in section i when inserting l
+	D = numpy.zeros((d + 1, n + 1, n + 1), dtype=numpy.int64)
+	for i in range(1, d + 1):
+		for l in range(1, n + 1):
+			for m in range(1, l + 1):
+				delta = C[i][l] - C[i][m]
+				if delta % 2 == 0:
+					# If delta is even
+					if C[i][m] == 1:
+						D[i][l][m] = m
+					else:
+						D[i][l][m] = m - P[i - 1]
+				else:
+					# If delta is odd
+					if C[i][m] == p[i - 1] or m + P[i - 1] > l:
+						D[i][l][m] = m
+					else:
+						D[i][l][m] = m + P[i - 1]
+	# Initialize arrays/lists
+	A = numpy.zeros(n + 1, dtype=numpy.int64)	   # Leaf above leaf m
+	B = numpy.zeros(n + 1, dtype=numpy.int64)	   # Leaf below leaf m
+	count = numpy.zeros(n + 1, dtype=numpy.int64)   # Counts for potential gaps
+	gapter = numpy.zeros(n + 1, dtype=numpy.int64)  # Indices for gap stack per leaf
+	gap = numpy.zeros(n * n + 1, dtype=numpy.int64) # Stack of potential gaps
+
+
+	# Initialize variables for backtracking
+	total_count = 0  # Total number of foldings
+	g = 0			# Gap index
+	l = 1			# Current leaf
+
+	# Start backtracking loop
+	while l > 0:
+		if l <= 1 or B[0] == 1: # NOTE different
+			# NOTE the above `if` statement encloses the the if/else block below
+			# NOTE these changes increase the throughput by more than an order of magnitude
+			if l > n:
+				total_count += n
+			else:
+				dd = 0	 # Number of sections where leaf l is unconstrained
+				gg = gapter[l - 1]  # Track possible gaps # NOTE different, but not important
+				g = gg # NOTE different, but not important
+
+				# Count possible gaps for leaf l in each section
+				for i in range(1, d + 1):
+					if D[i][l][l] == l:
+						dd += 1
+					else:
+						m = D[i][l][l]
+						while m != l:
+							if computationDivisions == 0 or l != computationDivisions or m % computationDivisions == computationIndex:
+								gap[gg] = m
+								if count[m] == 0:
+									gg += 1
+								count[m] += 1
+							m = D[i][l][B[m]]
+
+				# If leaf l is unconstrained in all sections, it can be inserted anywhere
+				if dd == d:
+					for m in range(l):
+						gap[gg] = m
+						gg += 1
+
+				# Filter gaps that are common to all sections
+				for j in range(g, gg):
+					gap[g] = gap[j]
+					if count[gap[j]] == d - dd:
+						g += 1
+					count[gap[j]] = 0  # Reset count for next iteration
+
+		# Recursive backtracking steps
+		while l > 0 and g == gapter[l - 1]:
+			l -= 1
+			B[A[l]] = B[l]
+			A[B[l]] = A[l]
+
+		if l > 0:
+			g -= 1
+			A[l] = gap[g]
+			B[l] = B[A[l]]
+			B[A[l]] = l
+			A[B[l]] = l
+			gapter[l] = g  # Save current gap index
+			l += 1		 # Move to next leaf
+
+	return total_count

mapFolding/someAssemblyRequired/Z0Z_workbench.py

@@ -0,0 +1,34 @@
+from mapFolding.someAssemblyRequired.synthesizeDataConverters import makeStateJob
+from mapFolding.someAssemblyRequired.synthesizeDataConverters import makeDataclassConverter
+from mapFolding.someAssemblyRequired.whatWillBe import IngredientsFunction, IngredientsModule, numbaFlow
+from mapFolding.someAssemblyRequired.synthesizeCountingFunctions import Z0Z_makeCountingFunction
+import ast
+
+if __name__ == '__main__':
+	ingredientsFunctionDataConverter = makeDataclassConverter(
+		dataclassIdentifierAsStr=numbaFlow.dataclassIdentifierAsStr
+		, logicalPathModuleDataclass=numbaFlow.logicalPathModuleDataclass
+		, dataclassInstanceAsStr=numbaFlow.dataclassInstanceAsStr
+
+		, dispatcherCallableAsStr=numbaFlow.dispatcherCallableAsStr
+		, logicalPathModuleDispatcher=numbaFlow.logicalPathModuleDispatcher
+		, dataConverterCallableAsStr=numbaFlow.dataConverterCallableAsStr
+		)
+
+	# initialize with theDao
+	dataInitializationHack = "state=makeStateJob(state.mapShape,writeJob=False)"
+	ingredientsFunctionDataConverter.FunctionDef.body.insert(0, ast.parse(dataInitializationHack).body[0])
+	ingredientsFunctionDataConverter.imports.addImportFromStr('mapFolding.someAssemblyRequired', 'makeStateJob')
+
+	ingredientsSequential = Z0Z_makeCountingFunction(numbaFlow.sequentialCallableAsStr
+													, numbaFlow.sourceAlgorithm
+													, inline=True
+													, dataclass=False)
+
+	ingredientsModuleDataConverter = IngredientsModule(
+		name=numbaFlow.dataConverterModule,
+		ingredientsFunction=ingredientsFunctionDataConverter,
+		logicalPathINFIX=numbaFlow.moduleOfSyntheticModules,
+	)
+
+	ingredientsModuleDataConverter.writeModule()

mapFolding/someAssemblyRequired/__init__.py

@@ -0,0 +1,16 @@
+from mapFolding.someAssemblyRequired.whatWillBe import (
+	ast_Identifier as ast_Identifier,
+	extractClassDef as extractClassDef,
+	extractFunctionDef as extractFunctionDef,
+	executeActionUnlessDescendantMatches as executeActionUnlessDescendantMatches,
+	ifThis as ifThis,
+	IngredientsFunction as IngredientsFunction,
+	IngredientsModule as IngredientsModule,
+	LedgerOfImports as LedgerOfImports,
+	listNumbaCallableDispatchees as listNumbaCallableDispatchees,
+	Make as Make,
+	NodeCollector as NodeCollector,
+	NodeReplacer as NodeReplacer,
+	strDotStrCuzPyStoopid as strDotStrCuzPyStoopid,
+	Then as Then,
+	)

mapFolding/someAssemblyRequired/getLLVMforNoReason.py

@@ -0,0 +1,21 @@
+import importlib
+from importlib.machinery import ModuleSpec
+from types import ModuleType
+import importlib.util
+import llvmlite.binding
+import pathlib
+
+def writeModuleLLVM(pathFilename: pathlib.Path, identifierCallable: str) -> pathlib.Path:
+	"""Import the generated module directly and get its LLVM IR."""
+	specTarget: ModuleSpec | None = importlib.util.spec_from_file_location("generatedModule", pathFilename)
+	if specTarget is None or specTarget.loader is None:
+		raise ImportError(f"Could not create module spec or loader for {pathFilename}")
+	moduleTarget: ModuleType = importlib.util.module_from_spec(specTarget)
+	specTarget.loader.exec_module(moduleTarget)
+
+	# Get LLVM IR and write to file
+	linesLLVM = moduleTarget.__dict__[identifierCallable].inspect_llvm()[()]
+	moduleLLVM: llvmlite.binding.ModuleRef = llvmlite.binding.module.parse_assembly(linesLLVM)
+	pathFilenameLLVM: pathlib.Path = pathFilename.with_suffix(".ll")
+	pathFilenameLLVM.write_text(str(moduleLLVM))
+	return pathFilenameLLVM