mapFolding 0.2.0__py3-none-any.whl

mapFolding/reference/lunnan.py

@@ -0,0 +1,153 @@
+"""
+An unnecessarily literal translation of the original Atlas Autocode code by W. F. Lunnon to Python.
+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
+"""# NOTE not functional yet
+def foldings(p, job=None):
+    """An unnecessarily literal translation of the original Atlas Autocode code."""
+    p = list(p)
+    p.append(None)  # NOTE mimics Atlas `array` type
+    p.insert(0, None)  # NOTE mimics Atlas `array` type
+
+    if job is None:
+        global f
+        f = 0
+        def job(A, B):
+            global f
+            f = f + 1
+        return foldings(p, job)
+    # perform job (A, B) on each folding of a p[1] x ... x p[d] map,
+    # where A and B are the above and below vectors. p[d + 1] < 0 terminates p;
+
+    d: int
+    n: int
+    j: int
+    i: int
+    m: int
+    l: int
+    g: int
+    gg: int
+    dd: int
+
+    n = 1
+    i, d = 0, 0
+
+    while (i := i + 1) and p[i] is not None:
+        d = i
+        n = n * p[i]
+
+    # d dimensions and n leaves;
+
+    # A: list[int] = [None] * (n + 1) # type: ignore
+    # B: list[int] = [None] * (n + 1) # type: ignore
+    # count: list[int] = [None] * (n + 1) # type: ignore
+    # gapter: list[int] = [None] * (n + 1) # type: ignore
+    # gap: list[int] = [None] * (n * n + 1) # type: ignore
+    A: list[int] = [0] * (n + 1) # type: ignore
+    B: list[int] = [0] * (n + 1) # type: ignore
+    count: list[int] = [0] * (n + 1) # type: ignore
+    gapter: list[int] = [0] * (n + 1) # type: ignore
+    gap: list[int] = [0] * (n * n + 1) # type: ignore
+
+    # 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: list[int] = [0] * (d + 1) # type: ignore
+    C: list[list[int]] = [[0] * (n + 1) for dimension1 in range(d + 1)] # type: ignore
+    # D: list[list[list[int]]] = [[[None] * (n + 1) for dimension2 in range(n + 1)] for dimension1 in range(d + 1)] # type: ignore
+    D: list[list[list[int]]] = [[[0] * (n + 1) for dimension2 in range(n + 1)] for dimension1 in range(d + 1)]
+
+    P[0] = 1
+    for i in range(1, d + 1):
+        P[i] = P[i - 1] * p[i]
+
+    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
+
+    for i in range(1, d + 1):
+        for l in range(1, n + 1):
+            for m in range(1, l + 1):
+                D[i][l][m] = (0 if m == 0
+                                else
+                                        ((m if C[i][m] == 1
+                                            else m - P[i - 1])
+                                    if C[i][l] - C[i][m] == (C[i][l] - C[i][m]) // 2 * 2
+                                    else
+                                        (m if C[i][m] == p[i] or m + P[i - 1] > l
+                                            else 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;
+
+    for m in range(n + 1):
+        count[m] = 0
+
+    A[0], B[0], g, l = 0, 0, 0, 0
+
+    state = 'entry'
+    while True:
+        if state == 'entry':
+            gapter[l] = g
+            l = l + 1
+            if l <= n:
+                state = 'down'
+                continue
+            else:
+                job(A, B)
+                state = 'up'
+                continue
+
+        elif state == 'down':
+            dd = 0
+            gg = gapter[l - 1]
+            g = gg
+            for i in range(1, d + 1):
+                if D[i][l][l] == l:
+                    dd = dd + 1
+                else:
+                    m = D[i][l][l]
+                    while m != l:
+                        gap[gg] = m
+                        if count[m] == 0:
+                            gg = gg + 1
+                        count[m] = 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
+            state = 'along'
+            continue
+
+        elif state == 'along':
+            if g == gapter[l - 1]:
+                state = 'up'
+                continue
+            g = g - 1
+            A[l] = gap[g]
+            B[l] = B[A[l]]
+            B[A[l]] = l
+            A[B[l]] = l
+            state = 'entry'
+            continue
+
+        elif state == 'up':
+            l = l - 1
+            B[A[l]] = B[l]
+            A[B[l]] = A[l]
+            if l > 0:
+                state = 'along'
+                continue
+            else:
+                break
+
+    return f #if job.__closure__ else None

mapFolding/reference/lunnanNumpy.py

@@ -0,0 +1,123 @@
+"""
+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
+"""
+from typing import List
+import numpy
+
+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.
+
+    Parameters:
+        p: A list of integers representing the dimensions of the map.
+
+    Returns:
+        f: 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 = numpy.zeros(n + 1, dtype=int)
+    B = numpy.zeros(n + 1, dtype=int)
+    count = numpy.zeros(n + 1, dtype=int)
+    gapter = numpy.zeros(n + 1, dtype=int)
+    gap = numpy.zeros(n * n + 1, dtype=int)
+
+    # 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 = numpy.ones(d + 1, dtype=int)
+    C = numpy.zeros((d + 1, n + 1), dtype=int)
+    D = numpy.zeros((d + 1, n + 1, n + 1), dtype=int)
+
+    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]) % p[i - 1] + 1 # NOTE Because modulo is available, this statement is simpler.
+
+    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;
+
+    f: int = 0
+    l: int = 1
+
+    # kick off with null folding
+    while l > 0:
+        if l <= 1 or B[0] == 1: # NOTE This statement is part of a significant divergence from the 1971 paper. As a result, this version is greater than one order of magnitude faster.
+            if l > n:
+                f = f + n # NOTE Due to `B[0] == 1`, this implementation increments the counted foldings in batches of `n`-many foldings, rather than immediately incrementing when a folding is found, i.e. `f = f + 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 f

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:
+        f: 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;
+
+    f: int = 0
+    l: int = 1
+
+    # kick off with null folding
+    while l > 0:
+        if l > n:
+            f = f + 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 f

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 = [
+(activeLeaf1ndex := 0),
+(activeGap1ndex := 1),
+(unconstrainedLeaf := 2),
+(gap1ndexCeiling := 3),
+(leaf1ndexConnectee := 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[activeLeaf1ndex] = 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[activeLeaf1ndex] <= 1 or track[leafBelow][0] == 1:
+                if my[activeLeaf1ndex] > the[leavesTotal]:
+                    foldingsTotal += the[leavesTotal]
+                else:
+                    my[unconstrainedLeaf] = 0
+                    my[gap1ndexCeiling] = track[gapRangeStart][my[activeLeaf1ndex] - 1]
+                    my[activeGap1ndex] = my[gap1ndexCeiling]
+
+                    for PREPAREdimension1ndex in range(1, the[dimensionsPlus1]):
+                        if connectionGraph[PREPAREdimension1ndex][my[activeLeaf1ndex]][my[activeLeaf1ndex]] == my[activeLeaf1ndex]:
+                            my[unconstrainedLeaf] += 1
+                        else:
+                            my[leaf1ndexConnectee] = connectionGraph[PREPAREdimension1ndex][my[activeLeaf1ndex]][my[activeLeaf1ndex]]
+                            while my[leaf1ndexConnectee] != my[activeLeaf1ndex]:
+
+                                if my[leaf1ndexConnectee] != my[activeLeaf1ndex]:
+                                    my[dimension1ndex] = PREPAREdimension1ndex
+                                    return track, gapsWhere, my
+
+                                if my[activeLeaf1ndex] != the[leavesTotal]:
+                                    gapsWhere[my[gap1ndexCeiling]] = my[leaf1ndexConnectee]
+                                    if track[countDimensionsGapped][my[leaf1ndexConnectee]] == 0:
+                                        my[gap1ndexCeiling] += 1
+                                    track[countDimensionsGapped][my[leaf1ndexConnectee]] += 1
+                                else:
+                                    print("else")
+                                    my[dimension1ndex] = PREPAREdimension1ndex
+                                    return track, gapsWhere, my
+                                    # PREPAREmy[leaf1ndexConnectee] % the[leavesTotal] == PREPAREmy[taskIndex]
+                                my[leaf1ndexConnectee] = connectionGraph[dimension1ndex][my[activeLeaf1ndex]][track[leafBelow][my[leaf1ndexConnectee]]]
+
+                    if my[unconstrainedLeaf] == the[dimensionsTotal]:
+                        for leaf1ndex in range(my[activeLeaf1ndex]):
+                            gapsWhere[my[gap1ndexCeiling]] = leaf1ndex
+                            my[gap1ndexCeiling] += 1
+
+                    for indexMiniGap in range(my[activeGap1ndex], my[gap1ndexCeiling]):
+                        gapsWhere[my[activeGap1ndex]] = gapsWhere[indexMiniGap]
+                        if track[countDimensionsGapped][gapsWhere[indexMiniGap]] == the[dimensionsTotal] - my[unconstrainedLeaf]:
+                            my[activeGap1ndex] += 1
+                        track[countDimensionsGapped][gapsWhere[indexMiniGap]] = 0
+
+            while my[activeLeaf1ndex] > 0 and my[activeGap1ndex] == track[gapRangeStart][my[activeLeaf1ndex] - 1]:
+                my[activeLeaf1ndex] -= 1
+                track[leafBelow][track[leafAbove][my[activeLeaf1ndex]]] = track[leafBelow][my[activeLeaf1ndex]]
+                track[leafAbove][track[leafBelow][my[activeLeaf1ndex]]] = track[leafAbove][my[activeLeaf1ndex]]
+
+            if my[activeLeaf1ndex] > 0:
+                my[activeGap1ndex] -= 1
+                track[leafAbove][my[activeLeaf1ndex]] = gapsWhere[my[activeGap1ndex]]
+                track[leafBelow][my[activeLeaf1ndex]] = track[leafBelow][track[leafAbove][my[activeLeaf1ndex]]]
+                track[leafBelow][track[leafAbove][my[activeLeaf1ndex]]] = my[activeLeaf1ndex]
+                track[leafAbove][track[leafBelow][my[activeLeaf1ndex]]] = my[activeLeaf1ndex]
+                track[gapRangeStart][my[activeLeaf1ndex]] = my[activeGap1ndex]
+                my[activeLeaf1ndex] += 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[activeLeaf1ndex] <= 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[activeLeaf1ndex] > the[leavesTotal] and thisIsNotTheFirstPass:
+                my[foldingsSubtotal] += the[leavesTotal]
+            else:
+                if thisIsNotTheFirstPass:
+                    my[unconstrainedLeaf] = 0
+                    my[gap1ndexCeiling] = track[gapRangeStart][my[activeLeaf1ndex] - 1]
+                    my[activeGap1ndex] = 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[activeLeaf1ndex]][my[activeLeaf1ndex]] == my[activeLeaf1ndex] and thisIsNotTheFirstPass:
+                        my[unconstrainedLeaf] += 1
+                    else:
+                        if thisIsNotTheFirstPass:
+                            my[leaf1ndexConnectee] = connectionGraph[my[dimension1ndex]][my[activeLeaf1ndex]][my[activeLeaf1ndex]]
+                        if my[leaf1ndexConnectee] != my[activeLeaf1ndex]:
+                            while_leaf1ndexConnectee_notEquals_activeLeaf1ndex = True
+
+                        while while_leaf1ndexConnectee_notEquals_activeLeaf1ndex == True:
+                            while_leaf1ndexConnectee_notEquals_activeLeaf1ndex = False
+                            thisIsNotTheFirstPass = True
+                            if taskDivisions==0 or my[activeLeaf1ndex] != taskDivisions:
+                                myTask = True
+                            else:
+                                modulo = my[leaf1ndexConnectee] % the[leavesTotal]
+                                if modulo == my[taskIndex]: myTask = True
+                                else:
+                                    myTask = False
+                            if myTask:
+                                gapsWhere[my[gap1ndexCeiling]] = my[leaf1ndexConnectee]
+                                if track[countDimensionsGapped][my[leaf1ndexConnectee]] == 0:
+                                    my[gap1ndexCeiling] += 1
+                                track[countDimensionsGapped][my[leaf1ndexConnectee]] += 1
+                            my[leaf1ndexConnectee] = connectionGraph[my[dimension1ndex]][my[activeLeaf1ndex]][track[leafBelow][my[leaf1ndexConnectee]]]
+                            if my[leaf1ndexConnectee] != my[activeLeaf1ndex]:
+                                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[activeLeaf1ndex]):
+                        gapsWhere[my[gap1ndexCeiling]] = leaf1ndex
+                        my[gap1ndexCeiling] += 1
+
+                for indexMiniGap in range(my[activeGap1ndex], my[gap1ndexCeiling]):
+                    gapsWhere[my[activeGap1ndex]] = gapsWhere[indexMiniGap]
+                    if track[countDimensionsGapped][gapsWhere[indexMiniGap]] == the[dimensionsTotal] - my[unconstrainedLeaf]:
+                        my[activeGap1ndex] += 1
+                    track[countDimensionsGapped][gapsWhere[indexMiniGap]] = 0
+
+        while my[activeLeaf1ndex] > 0 and my[activeGap1ndex] == track[gapRangeStart][my[activeLeaf1ndex] - 1]:
+            my[activeLeaf1ndex] -= 1
+            track[leafBelow][track[leafAbove][my[activeLeaf1ndex]]] = track[leafBelow][my[activeLeaf1ndex]]
+            track[leafAbove][track[leafBelow][my[activeLeaf1ndex]]] = track[leafAbove][my[activeLeaf1ndex]]
+
+        if my[activeLeaf1ndex] > 0:
+            my[activeGap1ndex] -= 1
+            track[leafAbove][my[activeLeaf1ndex]] = gapsWhere[my[activeGap1ndex]]
+            track[leafBelow][my[activeLeaf1ndex]] = track[leafBelow][track[leafAbove][my[activeLeaf1ndex]]]
+            track[leafBelow][track[leafAbove][my[activeLeaf1ndex]]] = my[activeLeaf1ndex]
+            track[leafAbove][track[leafBelow][my[activeLeaf1ndex]]] = my[activeLeaf1ndex]
+            track[gapRangeStart][my[activeLeaf1ndex]] = my[activeGap1ndex]
+            my[activeLeaf1ndex] += 1
+
+        if my[activeLeaf1ndex] <= 0:
+            return my[foldingsSubtotal]

mapFolding/startHere.py

@@ -0,0 +1,54 @@
+from numpy import integer
+from numpy.typing import NDArray
+from typing import Any, Tuple
+import numba
+import numpy
+from mapFolding import outfitFoldings
+# from mapFolding.benchmarks.benchmarking import recordBenchmarks
+from typing import Optional, Union, Sequence, Type
+import os
+import pathlib
+
+# TODO the current tests expect positional `listDimensions, computationDivisions`, so after restructuring you can arrange the parameters however you want.
+def countFolds(
+    listDimensions: Sequence[int],
+    computationDivisions: Optional[Union[int, str]] = None,
+    CPUlimit: Optional[Union[int, float, bool]] = None,
+    writeFoldsTotal: Optional[Union[str, os.PathLike[str]]] = None,
+    **keywordArguments: Optional[Type]
+    ):
+    """keywordArguments:
+    dtypeDefault: Optional[Type]
+    dtypeLarge: Optional[Type]
+
+    writeFoldsTotal: path, filename, or pathFilename
+    """
+    stateUniversal = outfitFoldings(listDimensions, computationDivisions=computationDivisions, CPUlimit=CPUlimit, **keywordArguments)
+
+    pathFilenameFoldsTotal = None
+    if writeFoldsTotal is not None:
+        pathFilenameFoldsTotal = pathlib.Path(writeFoldsTotal)
+        if pathFilenameFoldsTotal.is_dir():
+            filenameFoldsTotalDEFAULT = str(sorted(stateUniversal['mapShape'])).replace(' ', '') + '.foldsTotal'
+            pathFilenameFoldsTotal = pathFilenameFoldsTotal / filenameFoldsTotalDEFAULT
+        pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
+
+    from mapFolding.babbage import _countFolds
+    foldsTotal = _countFolds(**stateUniversal)
+    # foldsTotal = benchmarkSherpa(**stateUniversal)
+
+    if pathFilenameFoldsTotal is not None:
+        try:
+            pathFilenameFoldsTotal.write_text(str(foldsTotal))
+        except Exception as ERRORmessage:
+            print(ERRORmessage)
+            print("\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal")
+            print(f"{foldsTotal=}")
+            print("\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal")
+
+    return foldsTotal
+
+# @recordBenchmarks()
+# def benchmarkSherpa(connectionGraph: NDArray[integer[Any]], foldsTotal: NDArray[integer[Any]], mapShape: Tuple[int, ...], my: NDArray[integer[Any]], gapsWhere: NDArray[integer[Any]], the: NDArray[integer[Any]], track: NDArray[integer[Any]]):
+#     from mapFolding.babbage import _countFolds
+#     return _countFolds(connectionGraph, foldsTotal, mapShape, my, gapsWhere, the, track)