mapFolding 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

mapFolding/__init__.py

@@ -1,13 +1,5 @@
-"""Test concept: Import priority levels. Larger priority values should be imported before smaller priority values.
-This seems to be a little silly: no useful information is encoded in the priority value, so I don't know if a
-new import should have a lower or higher priority.
-Crazy concept: Python doesn't cram at least two import roles into one system, call it `import` and tell us how
-awesome Python is. Alternatively, I learn about the secret system for mapping physical names to logical names."""
-
-# TODO Across the entire package, restructure computationDivisions.
-# test modules need updating still
-
 from .theSSOT import *
+from Z0Z_tools import defineConcurrencyLimit, intInnit, oopsieKwargsie
 from .beDRY import getTaskDivisions, makeConnectionGraph, outfitFoldings, setCPUlimit
 from .beDRY import getLeavesTotal, parseDimensions, validateListDimensions
 from .startHere import countFolds

mapFolding/babbage.py

@@ -6,7 +6,25 @@ import numba
 import numpy
 
 @numba.jit(cache=True)
-def _countFolds(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]]):
+def _countFolds(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]]) -> int:
+    """
+    What in tarnation is this stupid module and function?
+
+    - This function is not in the same module as `countFolds` so that we can delay Numba just-in-time (jit) compilation of this function and the finalization of its settings until we are ready.
+    - This function is not in the same module as `countFoldsCompiled`, which is the function that does the hard, so that we can delay `numba.jit` compilation of `countFoldsCompiled`.
+    - `countFoldsCompiled` is not merely "jitted", it is super jitted, which makes it too arrogant to talk to plebian Python functions. It will, however, reluctantly talk to basic jitted functions.
+    - The function in this module is jitted, so it can talk to `countFoldsCompiled`, and because it isn't so arrogant, it will talk to the low-class `countFolds` with only a few restrictions, such as:
+        - No `TypedDict`
+        - No Python v 3.13
+        - The plebs must clean up their own memory problems
+        - No oversized integers
+        - No global variables, only global constants
+        - They don't except pleb nonlocal variables either
+        - Python "class": they are all inferior to a jit
+        - No `**kwargs`
+        - and just a few dozen-jillion other things.
+
+    """
     # TODO learn if I really must change this jitted function to get the super jit to recompile
     # print('babbage')
     return countFoldsCompiled(connectionGraph, foldsTotal, my, gapsWhere, the, track)

mapFolding/beDRY.py

@@ -1,22 +1,24 @@
 """A relatively stable API for oft-needed functionality."""
-from mapFolding.importPackages import intInnit, defineConcurrencyLimit, oopsieKwargsie
+from mapFolding import intInnit, defineConcurrencyLimit, oopsieKwargsie
 from mapFolding import indexMy, indexThe, indexTrack, computationState
+from mapFolding import dtypeDefault, dtypeLarge, dtypeSmall
 from typing import Any, List, Optional, Sequence, Type, Union
 import numpy
 import numba
-import numba.extending
-import numpy.typing
+from numpy.typing import NDArray
+from numpy import integer
 import sys
+import operator
 
 def getLeavesTotal(listDimensions: Sequence[int]) -> int:
     """
-    Calculate the product of non-zero, non-negative integers in the given list.
+    How many leaves are in the map.
 
     Parameters:
         listDimensions: A list of integers representing dimensions.
 
     Returns:
-        productDimensions: The product of all positive integer dimensions. Returns 0 if all dimensions are 0.
+        productDimensions: The product of all positive integer dimensions.
     """
     listNonNegative = parseDimensions(listDimensions, 'listDimensions')
     listPositive = [dimension for dimension in listNonNegative if dimension > 0]
@@ -27,57 +29,82 @@ def getLeavesTotal(listDimensions: Sequence[int]) -> int:
         productDimensions = 1
         for dimension in listPositive:
             if dimension > sys.maxsize // productDimensions:
-                raise OverflowError("Product would exceed maximum integer size")
+                raise OverflowError(f"I received {dimension=} in {listDimensions=}, but the product of the dimensions exceeds the maximum size of an integer on this system.")
             productDimensions *= dimension
 
         return productDimensions
 
-def getTaskDivisions(CPUlimit, computationDivisions: Optional[Union[int, str]], concurrencyLimit: int, listDimensions, the: numpy.typing.NDArray[numpy.integer[Any]], ):
-    # TODO remove after restructuring the tests
-    if isinstance(computationDivisions, bool) and computationDivisions:
-        computationDivisions = "maximum"
-
+def getTaskDivisions(computationDivisions: Optional[Union[int, str]], concurrencyLimit: int, CPUlimit: Optional[Union[bool, float, int]], listDimensions: Sequence[int]):
+    """
+    Determines whether or how to divide the computation into tasks.
+
+    Parameters
+    ----------
+    computationDivisions (None):
+        Specifies how to divide computations:
+        - None: no division of the computation into tasks; sets task divisions to 0
+        - int: direct set the number of task divisions; cannot exceed the map's total leaves
+        - "maximum": divides into `leavesTotal`-many `taskDivisions`
+        - "cpu": limits the divisions to the number of available CPUs, i.e. `concurrencyLimit`
+    concurrencyLimit:
+        Maximum number of concurrent tasks allowed
+    listDimensions: for error reporting
+    CPUlimit: for error reporting
+
+    Returns
+    -------
+    taskDivisions:
+
+    Raises
+    ------
+    ValueError
+        If computationDivisions is an unsupported type or if resulting task divisions exceed total leaves
+
+    Notes
+    -----
+    Task divisions cannot exceed total leaves to prevent duplicate counting of folds.
+    """
     if not computationDivisions:
-        # Coding it this way should cover `None`, `False`, and `0`.
-        the[indexThe.taskDivisions] = 0
-    elif isinstance(computationDivisions, int):
-        the[indexThe.taskDivisions] = computationDivisions
+        return 0
+    else:
+        leavesTotal = getLeavesTotal(listDimensions)
+    if isinstance(computationDivisions, int):
+        taskDivisions = computationDivisions
     elif isinstance(computationDivisions, str):
         computationDivisions = computationDivisions.lower()
         if computationDivisions == "maximum":
-            the[indexThe.taskDivisions] = the[indexThe.leavesTotal]
+            taskDivisions = leavesTotal
         elif computationDivisions == "cpu":
-            the[indexThe.taskDivisions] = min(concurrencyLimit, the[indexThe.leavesTotal])
+            taskDivisions = min(concurrencyLimit, leavesTotal)
     else:
         raise ValueError(f"I received {computationDivisions} for the parameter, `computationDivisions`, but the so-called programmer didn't implement code for that.")
 
-    if the[indexThe.taskDivisions] > the[indexThe.leavesTotal]:
-        raise ValueError(f"Problem: `taskDivisions`, ({the[indexThe.taskDivisions]}), is greater than `leavesTotal`, ({the[indexThe.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.\n\nFor those parameters, I received {computationDivisions=}, {CPUlimit=}, and {listDimensions=}.\n\nPotential solutions: get a different hobby or set `computationDivisions` to a different value.")
+    if taskDivisions > leavesTotal:
+        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.\n\nFor those parameters, I received {computationDivisions=}, {CPUlimit=}, and {listDimensions=}.\n\nPotential solutions: get a different hobby or set `computationDivisions` to a different value.")
 
-    return the
+    return taskDivisions
 
-def makeConnectionGraph(listDimensions: Sequence[int], dtype: Optional[Type] = numpy.int64) -> numpy.typing.NDArray[numpy.integer[Any]]:
+def makeConnectionGraph(listDimensions: Sequence[int], **keywordArguments: Optional[Type]) -> NDArray[integer[Any]]:
     """
-    Constructs a connection graph for a given list of dimensions.
-    This function generates a multi-dimensional connection graph based on the provided list of dimensions.
-    The graph represents the connections between leaves in a Cartesian product decomposition or dimensional product mapping.
+    Constructs a multi-dimensional connection graph representing the connections between the leaves of a map with the given dimensions.
+    Also called a Cartesian product decomposition or dimensional product mapping.
 
     Parameters:
-        listDimensions: A validated sequence of integers representing the dimensions of the map.
+        listDimensions: A sequence of integers representing the dimensions of the map.
     Returns:
         connectionGraph: A 3D numpy array with shape of (dimensionsTotal + 1, leavesTotal + 1, leavesTotal + 1).
     """
-    leavesTotal = getLeavesTotal(listDimensions)
-    arrayDimensions = numpy.array(listDimensions, dtype=dtype)
+    datatype = keywordArguments.get('datatype', dtypeDefault)
+    mapShape = validateListDimensions(listDimensions)
+    leavesTotal = getLeavesTotal(mapShape)
+    arrayDimensions = numpy.array(mapShape, dtype=datatype)
     dimensionsTotal = len(arrayDimensions)
 
     # Step 1: find the cumulative product of the map's dimensions
-    cumulativeProduct = numpy.ones(dimensionsTotal + 1, dtype=dtype)
-    for index in range(1, dimensionsTotal + 1):
-        cumulativeProduct[index] = cumulativeProduct[index - 1] * arrayDimensions[index - 1]
+    cumulativeProduct = numpy.multiply.accumulate([1] + mapShape, dtype=datatype)
 
     # Step 2: create a coordinate system
-    coordinateSystem = numpy.zeros((dimensionsTotal + 1, leavesTotal + 1), dtype=dtype)
+    coordinateSystem = numpy.zeros((dimensionsTotal + 1, leavesTotal + 1), dtype=datatype)
 
     for dimension1ndex in range(1, dimensionsTotal + 1):
         for leaf1ndex in range(1, leavesTotal + 1):
@@ -87,7 +114,7 @@ def makeConnectionGraph(listDimensions: Sequence[int], dtype: Optional[Type] = n
             )
 
     # Step 3: create and fill the connection graph
-    connectionGraph = numpy.zeros((dimensionsTotal + 1, leavesTotal + 1, leavesTotal + 1), dtype=dtype)
+    connectionGraph = numpy.zeros((dimensionsTotal + 1, leavesTotal + 1, leavesTotal + 1), dtype=datatype)
 
     for dimension1ndex in range(1, dimensionsTotal + 1):
         for activeLeaf1ndex in range(1, leavesTotal + 1):
@@ -113,30 +140,56 @@ def makeConnectionGraph(listDimensions: Sequence[int], dtype: Optional[Type] = n
 
     return connectionGraph
 
-def outfitFoldings(
-    listDimensions: Sequence[int],
-    computationDivisions: Optional[Union[int, str]] = None,
-    CPUlimit: Optional[Union[int, float, bool]] = None,
-    dtypeDefault: Optional[Type] = numpy.int64, # TODO consider allowing a type or a "signal", such as "minimum", "safe", "maximum"
-    dtypeLarge: Optional[Type] = numpy.int64, # Can/should I use numba types?
-    ) -> computationState:
-    the = numpy.zeros(len(indexThe), dtype=dtypeDefault)
+def makeDataContainer(shape, datatype: Optional[Type] = None):
+    """Create a container, probably numpy.ndarray, with the given shape and datatype."""
+    if datatype is None:
+        datatype = dtypeDefault
+    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:
+    """
+    Initializes and configures the computation state for map folding computations.
+
+    Parameters
+    ----------
+    listDimensions:
+        The dimensions of the map to be folded
+    computationDivisions (None):
+        Specifies how to divide the computation tasks
+    CPUlimit (None):
+        Limits the CPU usage for computations
+
+    Returns
+    -------
+    computationState
+        An initialized computation state containing:
+        - connectionGraph: Graph representing connections in the map
+        - foldsTotal: Array tracking total folds
+        - mapShape: Validated and sorted dimensions of the map
+        - my: Array for internal state tracking
+        - gapsWhere: Array tracking gap positions
+        - the: Static settings and metadata
+        - track: Array for tracking computation progress
+    """
+    datatypeDefault = keywordArguments.get('datatypeDefault', dtypeDefault)
+    datatypeLarge = keywordArguments.get('datatypeLarge', dtypeLarge)
+
+    the = makeDataContainer(len(indexThe), datatypeDefault)
 
     mapShape = tuple(sorted(validateListDimensions(listDimensions)))
     the[indexThe.leavesTotal] = getLeavesTotal(mapShape)
     the[indexThe.dimensionsTotal] = len(mapShape)
     concurrencyLimit = setCPUlimit(CPUlimit)
-
-    the = getTaskDivisions(CPUlimit, computationDivisions, concurrencyLimit, listDimensions, the)
-
+    the[indexThe.taskDivisions] = getTaskDivisions(computationDivisions, concurrencyLimit, CPUlimit, listDimensions)
+    
     stateInitialized = computationState(
-        connectionGraph = makeConnectionGraph(mapShape, dtype=dtypeDefault),
-        foldsTotal = numpy.zeros(the[indexThe.leavesTotal], dtype=numpy.int64),
+        connectionGraph = makeConnectionGraph(mapShape, datatype=datatypeDefault),
+        foldsTotal = makeDataContainer(the[indexThe.leavesTotal], datatypeLarge),
         mapShape = mapShape,
-        my = numpy.zeros(len(indexMy), dtype=dtypeLarge),
-        gapsWhere = numpy.zeros(int(the[indexThe.leavesTotal]) * int(the[indexThe.leavesTotal]) + 1, dtype=dtypeDefault),
+        my = makeDataContainer(len(indexMy), datatypeLarge),
+        gapsWhere = makeDataContainer(int(the[indexThe.leavesTotal]) * int(the[indexThe.leavesTotal]) + 1, datatypeDefault),
         the = the,
-        track = numpy.zeros((len(indexTrack), the[indexThe.leavesTotal] + 1), dtype=dtypeLarge)
+        track = makeDataContainer((len(indexTrack), the[indexThe.leavesTotal] + 1), datatypeLarge)
         )
 
     stateInitialized['my'][indexMy.leaf1ndex.value] = 1
@@ -145,10 +198,10 @@ def outfitFoldings(
 
 def parseDimensions(dimensions: Sequence[int], parameterName: str = 'unnamed parameter') -> List[int]:
     """
-    Parse and validate a list of dimensions.
+    Parse and validate dimensions are non-negative integers.
 
     Parameters:
-        listDimensions: List of integers representing dimensions
+        dimensions: Sequence of integers representing dimensions
         parameterName ('unnamed parameter'): Name of the parameter for error messages. Defaults to 'unnamed parameter'
     Returns:
         listNonNegative: List of validated non-negative integers
@@ -168,43 +221,41 @@ def parseDimensions(dimensions: Sequence[int], parameterName: str = 'unnamed par
 
     return listNonNegative
 
-def setCPUlimit(CPUlimit: Union[int, float, bool, None]):
-    """Sets CPU limit for concurrent operations using Numba.
-    This function configures the number of CPU threads that Numba can use for parallel execution.
-    Note that this setting only affects Numba-jitted functions that have not yet been imported.
+def setCPUlimit(CPUlimit: Union[bool, float, int, None]) -> int:
+    """Sets CPU limit for Numba concurrent operations. Note that it can only affect Numba-jitted functions that have not yet been imported.
+
     Parameters:
-        CPUlimit (Union[int, float, bool, None]): The CPU limit to set.
-            - If int/float: Specifies number of CPU threads to use
-            - If bool: True uses all available CPUs, False uses 1 CPU
-            - If None: Uses system default
+        CPUlimit: whether and how to limit the CPU usage. See notes for details.
     Returns:
         concurrencyLimit: The actual concurrency limit that was set
     Raises:
         TypeError: If CPUlimit is not of the expected types
+
+    Limits on CPU usage `CPUlimit`:
+        - `False`, `None`, or `0`: No limits on CPU usage; uses all available CPUs. All other values will potentially limit CPU usage.
+        - `True`: Yes, limit the CPU usage; limits to 1 CPU.
+        - Integer `>= 1`: Limits usage to the specified number of CPUs.
+        - Decimal value (`float`) between 0 and 1: Fraction of total CPUs to use.
+        - Decimal value (`float`) between -1 and 0: Fraction of CPUs to *not* use.
+        - Integer `<= -1`: Subtract the absolute value from total CPUs.
     """
     if not (CPUlimit is None or isinstance(CPUlimit, (bool, int, float))):
         CPUlimit = oopsieKwargsie(CPUlimit)
 
     concurrencyLimit = defineConcurrencyLimit(CPUlimit)
-    # NOTE `set_num_threads` only affects "jitted" functions that have _not_ yet been "imported"
     numba.set_num_threads(concurrencyLimit)
 
     return concurrencyLimit
 
 def validateListDimensions(listDimensions: Sequence[int]) -> List[int]:
     """
-    Validates and processes a list of dimensions.
-
-    This function ensures that the input list of dimensions is not None,
-    parses it to ensure all dimensions are non-negative, and then filters
-    out any dimensions that are not greater than zero. If the resulting
-    list has fewer than two dimensions, a NotImplementedError is raised.
+    Validates and sorts a sequence of at least two positive dimensions.
 
     Parameters:
-        listDimensions: A list of integer dimensions to be validated.
+        listDimensions: A sequence of integer dimensions to be validated.
 
     Returns:
-        validDimensions: A list, with at least two elements, of only positive integers.
+        dimensionsValidSorted: A list, with at least two elements, of only positive integers.
 
     Raises:
         ValueError: If the input listDimensions is None.
@@ -213,7 +264,7 @@ def validateListDimensions(listDimensions: Sequence[int]) -> List[int]:
     if not listDimensions:
         raise ValueError(f"listDimensions is a required parameter.")
     listNonNegative = parseDimensions(listDimensions, 'listDimensions')
-    validDimensions = [dimension for dimension in listNonNegative if dimension > 0]
-    if len(validDimensions) < 2:
+    dimensionsValid = [dimension for dimension in listNonNegative if dimension > 0]
+    if len(dimensionsValid) < 2:
         raise NotImplementedError(f"This function requires listDimensions, {listDimensions}, to have at least two dimensions greater than 0. You may want to look at https://oeis.org/.")
-    return validDimensions
+    return sorted(dimensionsValid)

mapFolding/lovelace.py

@@ -1,27 +1,43 @@
+"""
+The algorithm for counting folds.
+
+Starting from established data structures, the algorithm initializes some baseline values. The initialization uses a loop that is not used after the first fold is counted.
+
+After initialization, the folds are either counted sequentially or counted with inefficiently divided parallel tasks.
+
+All three of these actions--initialization, sequential counting, and parallel counting--use nearly identical logic. Without Numba, all of the logic is in one function with exactly one additional
+conditional statement for initialization and exactly one additional conditional statement for parallel counting.
+
+Numba's just-in-time (jit) compiler, especially super jit, is capable of radically increasing throughput and dramatically reducing the size of the compiled code, especially by ejecting unused code.
+
+The complexity of this module is due to me allegedly applying Numba's features. Allegedly.
+
+(The flow starts with the last function.)
+"""
 from mapFolding import indexMy, indexThe, indexTrack
 from numpy import integer
 from numpy.typing import NDArray
-from typing import Any, Optional
+from typing import Any, Tuple, Optional
 import numba
 import numpy
 
 @numba.jit(parallel=False, _nrt=True, boundscheck=False, error_model='numpy', fastmath=True, forceinline=True, looplift=False, no_cfunc_wrapper=True, no_cpython_wrapper=True, nogil=True, nopython=True)
-def ifComputationDivisions(my: NDArray[integer[Any]], the: NDArray[integer[Any]]):
+def ifComputationDivisions(my: NDArray[integer[Any]], the: NDArray[integer[Any]]) -> bool:
     if the[indexThe.taskDivisions.value] == 0:
         return True
     return my[indexMy.leaf1ndex.value] != the[indexThe.taskDivisions.value] or \
             (my[indexMy.leafConnectee.value] % the[indexThe.taskDivisions.value]) == my[indexMy.taskIndex.value]
 
 @numba.jit(parallel=False, _nrt=True, boundscheck=False, error_model='numpy', fastmath=True, forceinline=True, looplift=False, no_cfunc_wrapper=True, no_cpython_wrapper=True, nogil=True, nopython=True)
-def insertUnconstrainedLeaf(my: NDArray[integer[Any]], the: NDArray[integer[Any]], Z0Z_initializeUnconstrainedLeaf: Optional[bool]):
-    if Z0Z_initializeUnconstrainedLeaf:
+def insertUnconstrainedLeaf(my: NDArray[integer[Any]], the: NDArray[integer[Any]], initializeUnconstrainedLeaf: Optional[bool]) -> bool:
+    if initializeUnconstrainedLeaf:
         return my[indexMy.dimensionsUnconstrained.value] == the[indexThe.dimensionsTotal.value]
     else:
         return False
 
 @numba.jit(parallel=False, _nrt=True, boundscheck=False, error_model='numpy', fastmath=True, forceinline=True, looplift=False, no_cfunc_wrapper=True, no_cpython_wrapper=True, nogil=True, nopython=True)
-def initializationConditionUnconstrainedLeaf(my: NDArray[integer[Any]], Z0Z_initializeUnconstrainedLeaf: Optional[bool]):
-    if Z0Z_initializeUnconstrainedLeaf is None or Z0Z_initializeUnconstrainedLeaf is False:
+def initializationConditionUnconstrainedLeaf(my: NDArray[integer[Any]], initializeUnconstrainedLeaf: Optional[bool]) -> bool:
+    if initializeUnconstrainedLeaf is None or initializeUnconstrainedLeaf is False:
         return False
     else:
         if my[indexMy.gap1ndex.value] > 0:
@@ -30,7 +46,7 @@ def initializationConditionUnconstrainedLeaf(my: NDArray[integer[Any]], Z0Z_init
             return False
 
 @numba.jit(parallel=False, _nrt=True, boundscheck=False, error_model='numpy', fastmath=True, forceinline=True, looplift=False, no_cfunc_wrapper=True, no_cpython_wrapper=True, nogil=True, nopython=True)
-def doWhile(connectionGraph: NDArray[integer[Any]], foldsTotal: NDArray[integer[Any]], my: NDArray[integer[Any]], gapsWhere: NDArray[integer[Any]], the: NDArray[integer[Any]], track: NDArray[integer[Any]], Z0Z_initializeUnconstrainedLeaf: Optional[bool] ):
+def doWhile(connectionGraph: NDArray[integer[Any]], foldsTotal: NDArray[integer[Any]], my: NDArray[integer[Any]], gapsWhere: NDArray[integer[Any]], the: NDArray[integer[Any]], track: NDArray[integer[Any]], initializeUnconstrainedLeaf: Optional[bool]) -> Tuple[NDArray[integer[Any]], NDArray[integer[Any]], NDArray[integer[Any]], NDArray[integer[Any]]]:
     while my[indexMy.leaf1ndex.value] > 0:
         if my[indexMy.leaf1ndex.value] <= 1 or track[indexTrack.leafBelow.value, 0] == 1:
             if my[indexMy.leaf1ndex.value] > the[indexThe.leavesTotal.value]:
@@ -45,6 +61,7 @@ def doWhile(connectionGraph: NDArray[integer[Any]], foldsTotal: NDArray[integer[
                     else:
                         my[indexMy.leafConnectee.value] = connectionGraph[my[indexMy.dimension1ndex.value], my[indexMy.leaf1ndex.value], my[indexMy.leaf1ndex.value]]
                         while my[indexMy.leafConnectee.value] != my[indexMy.leaf1ndex.value]:
+                            # NOTE This conditional check should only be in the parallel counting branch
                             if ifComputationDivisions(my, the):
                                 gapsWhere[my[indexMy.gap1ndexCeiling.value]] = my[indexMy.leafConnectee.value]
                                 if track[indexTrack.countDimensionsGapped.value, my[indexMy.leafConnectee.value]] == 0:
@@ -52,7 +69,8 @@ def doWhile(connectionGraph: NDArray[integer[Any]], foldsTotal: NDArray[integer[
                                 track[indexTrack.countDimensionsGapped.value, my[indexMy.leafConnectee.value]] += 1
                             my[indexMy.leafConnectee.value] = connectionGraph[my[indexMy.dimension1ndex.value], my[indexMy.leaf1ndex.value], track[indexTrack.leafBelow.value, my[indexMy.leafConnectee.value]]]
                     my[indexMy.dimension1ndex.value] += 1
-                if insertUnconstrainedLeaf(my, the, Z0Z_initializeUnconstrainedLeaf):
+                # NOTE This `if` statement and `while` loop should be absent from the code that does the counting
+                if insertUnconstrainedLeaf(my, the, initializeUnconstrainedLeaf):
                     my[indexMy.indexLeaf.value] = 0
                     while my[indexMy.indexLeaf.value] < my[indexMy.leaf1ndex.value]:
                         gapsWhere[my[indexMy.gap1ndexCeiling.value]] = my[indexMy.indexLeaf.value]
@@ -77,13 +95,16 @@ def doWhile(connectionGraph: NDArray[integer[Any]], foldsTotal: NDArray[integer[
             track[indexTrack.leafAbove.value, track[indexTrack.leafBelow.value, my[indexMy.leaf1ndex.value]]] = my[indexMy.leaf1ndex.value]
             track[indexTrack.gapRangeStart.value, my[indexMy.leaf1ndex.value]] = my[indexMy.gap1ndex.value]
             my[indexMy.leaf1ndex.value] += 1
-        if initializationConditionUnconstrainedLeaf(my, Z0Z_initializeUnconstrainedLeaf):
+        # NOTE This check and break should be absent from the code that does the counting
+        if initializationConditionUnconstrainedLeaf(my, initializeUnconstrainedLeaf):
             break
     return foldsTotal, my, gapsWhere, track
 
 @numba.jit(parallel=True, _nrt=True, boundscheck=False, error_model='numpy', fastmath=True, forceinline=True, looplift=False, no_cfunc_wrapper=True, no_cpython_wrapper=True, nogil=True, nopython=True)
-def doTaskIndices(connectionGraph: NDArray[integer[Any]], foldsTotal: NDArray[integer[Any]], my: NDArray[integer[Any]], gapsWhere: NDArray[integer[Any]], the: NDArray[integer[Any]], track: NDArray[integer[Any]]):
-
+def doTaskIndices(connectionGraph: NDArray[integer[Any]], foldsTotal: NDArray[integer[Any]], my: NDArray[integer[Any]], gapsWhere: NDArray[integer[Any]], the: NDArray[integer[Any]], track: NDArray[integer[Any]]) -> NDArray[integer[Any]]:
+    """This is the only function with the `parallel=True` option.
+    Make a copy of the initialized state because all task divisions can start from this baseline.
+    Run the counting algorithm but with conditional execution of a few lines of code, so each task has an incomplete count that does not overlap with other tasks."""
     stateFoldsSubTotal = foldsTotal.copy()
     stateMy = my.copy()
     statePotentialGaps = gapsWhere.copy()
@@ -92,18 +113,17 @@ def doTaskIndices(connectionGraph: NDArray[integer[Any]], foldsTotal: NDArray[in
     for indexSherpa in numba.prange(the[indexThe.taskDivisions.value]):
         my = stateMy.copy()
         my[indexMy.taskIndex.value] = indexSherpa
-        foldsSubTotal, _1, _2, _3 = doWhile(connectionGraph, stateFoldsSubTotal.copy(), my, statePotentialGaps.copy(), the, stateTrack.copy(), Z0Z_initializeUnconstrainedLeaf=False)
+        foldsSubTotal, _1, _2, _3 = doWhile(connectionGraph, stateFoldsSubTotal.copy(), my, statePotentialGaps.copy(), the, stateTrack.copy(), initializeUnconstrainedLeaf=False)
 
         foldsTotal[indexSherpa] = foldsSubTotal[indexSherpa]
 
     return foldsTotal
 
 @numba.jit(parallel=False, _nrt=True, boundscheck=False, error_model='numpy', fastmath=True, forceinline=True, looplift=False, no_cfunc_wrapper=True, no_cpython_wrapper=True, nogil=True, nopython=True)
-def countFoldsCompileBranch(connectionGraph: NDArray[integer[Any]], foldsTotal: NDArray[integer[Any]],
-                            my: NDArray[integer[Any]], gapsWhere: NDArray[integer[Any]], the: NDArray[integer[Any]], track: NDArray[integer[Any]],
-                            obviousFlagForNumba: bool):
+def countFoldsCompileBranch(connectionGraph: NDArray[integer[Any]], foldsTotal: NDArray[integer[Any]], my: NDArray[integer[Any]], gapsWhere: NDArray[integer[Any]], the: NDArray[integer[Any]], track: NDArray[integer[Any]], obviousFlagForNumba: bool) -> NDArray[integer[Any]]:
+    """Allegedly, `obviousFlagForNumba` allows Numba to compile two versions: one for parallel execution and one leaner version for sequential execution."""
     if obviousFlagForNumba:
-        foldsTotal, _1, _2, _3 = doWhile(connectionGraph, foldsTotal, my, gapsWhere, the, track, Z0Z_initializeUnconstrainedLeaf=False)
+        foldsTotal, _1, _2, _3 = doWhile(connectionGraph, foldsTotal, my, gapsWhere, the, track, initializeUnconstrainedLeaf=False)
     else:
         foldsTotal = doTaskIndices(connectionGraph, foldsTotal, my, gapsWhere, the, track)
 
@@ -111,11 +131,15 @@ def countFoldsCompileBranch(connectionGraph: NDArray[integer[Any]], foldsTotal:
 
 @numba.jit(parallel=False, _nrt=True, boundscheck=False, error_model='numpy', fastmath=True, forceinline=True, looplift=False, no_cfunc_wrapper=True, no_cpython_wrapper=True, nogil=True, nopython=True)
 def countFoldsCompiled(connectionGraph: NDArray[integer[Any]], foldsTotal: NDArray[integer[Any]], my: NDArray[integer[Any]], gapsWhere: NDArray[integer[Any]], the: NDArray[integer[Any]], track: NDArray[integer[Any]]) -> int:
+    # ^ Receive the data structures.
 
-    _0, my, gapsWhere, track = doWhile(connectionGraph, foldsTotal, my, gapsWhere, the, track, Z0Z_initializeUnconstrainedLeaf=True)
+    # Initialize baseline values primarily to eliminate the need for the logic of `insertUnconstrainedLeaf`
+    _0, my, gapsWhere, track = doWhile(connectionGraph, foldsTotal, my, gapsWhere, the, track, initializeUnconstrainedLeaf=True)
 
     obviousFlagForNumba = the[indexThe.taskDivisions.value] == int(False)
 
+    # Call the function that will branch to sequential or parallel counting
     foldsTotal = countFoldsCompileBranch(connectionGraph, foldsTotal, my, gapsWhere, the, track, obviousFlagForNumba)
 
+    # Return an `int` integer
     return numpy.sum(foldsTotal).item()

mapFolding/oeis.py

@@ -65,6 +65,40 @@ settingsOEIShardcodedValues = {
 oeisIDsImplemented: Final[List[str]]  = sorted([oeisID.upper().strip() for oeisID in settingsOEIShardcodedValues.keys()])
 """Directly implemented OEIS IDs; standardized, e.g., 'A001415'."""
 
+def _validateOEISid(oeisIDcandidate: str):
+    """
+    Validates an OEIS sequence ID against implemented sequences.
+
+    If the provided ID is recognized within the application's implemented
+    OEIS sequences, the function returns the verified ID in uppercase.
+    Otherwise, a KeyError is raised indicating that the sequence is not
+    directly supported.
+
+    Parameters:
+        oeisIDcandidate: The OEIS sequence identifier to validate.
+
+    Returns:
+        oeisID: The validated and possibly modified OEIS sequence ID, if recognized.
+
+    Raises:
+        KeyError: If the provided sequence ID is not directly implemented.
+    """
+    if oeisIDcandidate in oeisIDsImplemented:
+        return oeisIDcandidate
+    else:
+        oeisIDcleaned = str(oeisIDcandidate).upper().strip()
+        if oeisIDcleaned in oeisIDsImplemented:
+            return oeisIDcleaned
+        else:
+            raise KeyError(
+                f"OEIS ID {oeisIDcandidate} is not directly implemented.\n"
+                f"Available sequences:\n{_formatOEISsequenceInfo()}"
+            )
+
+def _getFilenameOEISbFile(oeisID: str) -> str:
+    oeisID = _validateOEISid(oeisID)
+    return f"b{oeisID[1:]}.txt"
+
 def _parseBFileOEIS(OEISbFile: str, oeisID: str) -> Dict[int, int]:
     """
     Parses the content of an OEIS b-file for a given sequence ID.
@@ -101,8 +135,6 @@ try:
 except NameError:
     _pathCache = pathlib.Path.home() / ".mapFoldingCache"
 
-_formatFilenameCache = "{oeisID}.txt"
-
 def _getOEISidValues(oeisID: str) -> Dict[int, int]:
     """
     Retrieves the specified OEIS sequence as a dictionary mapping integer indices
@@ -122,7 +154,7 @@ def _getOEISidValues(oeisID: str) -> Dict[int, int]:
         IOError: If there is an error reading from or writing to the local cache.
     """
 
-    pathFilenameCache = _pathCache / _formatFilenameCache.format(oeisID=oeisID)
+    pathFilenameCache = _pathCache / _getFilenameOEISbFile(oeisID)
     cacheDays = 7
 
     tryCache = False
@@ -137,7 +169,7 @@ def _getOEISidValues(oeisID: str) -> Dict[int, int]:
         except (ValueError, IOError):
             tryCache = False
 
-    urlOEISbFile = f"https://oeis.org/{oeisID}/b{oeisID[1:]}.txt"
+    urlOEISbFile = f"https://oeis.org/{oeisID}/{_getFilenameOEISbFile(oeisID)}"
     httpResponse: urllib.response.addinfourl = urllib.request.urlopen(urlOEISbFile)
     OEISbFile = httpResponse.read().decode('utf-8')
 
@@ -148,6 +180,28 @@ def _getOEISidValues(oeisID: str) -> Dict[int, int]:
     return _parseBFileOEIS(OEISbFile, oeisID)
 
 def makeSettingsOEIS() -> Dict[str, SettingsOEIS]:
+    """
+    Creates a dictionary mapping OEIS IDs to their corresponding settings.
+
+    This function initializes settings for each implemented OEIS sequence by combining
+    hardcoded values with dynamically retrieved OEIS sequence values.
+
+    Returns:
+        Dict[str, SettingsOEIS]: A dictionary where:
+            - Keys are OEIS sequence IDs (str)
+            - Values are SettingsOEIS objects containing:
+                - description: Text description of the sequence
+                - getDimensions: Function to get dimensions
+                - valuesBenchmark: Benchmark values
+                - valuesKnown: Known values from OEIS
+                - valuesTestValidation: Values for test validation
+                - valueUnknown: First unknown value in sequence
+
+    Note:
+        Relies on global variables:
+        - oeisIDsImplemented: List of implemented OEIS sequence IDs
+        - settingsOEIShardcodedValues: Dictionary of hardcoded settings per sequence
+    """
     settingsTarget = {}
     for oeisID in oeisIDsImplemented:
         valuesKnownSherpa = _getOEISidValues(oeisID)
@@ -190,36 +244,6 @@ def _formatOEISsequenceInfo() -> str:
         for oeisID in oeisIDsImplemented
     )
 
-def _validateOEISid(oeisIDcandidate: str):
-    """
-    Validates an OEIS sequence ID against implemented sequences.
-
-    If the provided ID is recognized within the application's implemented
-    OEIS sequences, the function returns the verified ID in uppercase.
-    Otherwise, a KeyError is raised indicating that the sequence is not
-    directly supported.
-
-    Parameters:
-        oeisIDcandidate: The OEIS sequence identifier to validate.
-
-    Returns:
-        oeisID: The validated and possibly modified OEIS sequence ID, if recognized.
-
-    Raises:
-        KeyError: If the provided sequence ID is not directly implemented.
-    """
-    if oeisIDcandidate in oeisIDsImplemented:
-        return oeisIDcandidate
-    else:
-        oeisIDcleaned = str(oeisIDcandidate).upper().strip()
-        if oeisIDcleaned in oeisIDsImplemented:
-            return oeisIDcleaned
-        else:
-            raise KeyError(
-                f"OEIS ID {oeisIDcandidate} is not directly implemented.\n"
-                f"Available sequences:\n{_formatOEISsequenceInfo()}"
-            )
-
 """
 Section: public functions"""
 
@@ -286,7 +310,7 @@ def clearOEIScache() -> None:
         return
     else:
         for oeisID in settingsOEIS:
-            pathFilenameCache = _pathCache / _formatFilenameCache.format(oeisID=oeisID)
+            pathFilenameCache = _pathCache / _getFilenameOEISbFile(oeisID)
             pathFilenameCache.unlink(missing_ok=True)
 
     print(f"Cache cleared from {_pathCache}")