mapFolding 0.2.0__tar.gz → 0.2.2__tar.gz

{mapfolding-0.2.0 → mapfolding-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: mapFolding
-Version: 0.2.0
+Version: 0.2.2
 Summary: Algorithm(s) for counting distinct ways to fold a map (or a strip of stamps)
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 Project-URL: homepage, https://github.com/hunterhogan/mapFolding
@@ -32,11 +32,11 @@ from mapFolding import countFolds
 foldsTotal = countFolds( [2,10] )
 ```
 
-The directory `mapFolding/reference` has
+The directory [mapFolding/reference](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/reference) has
 
 - a verbatim transcription of the "procedure" published in _The Computer Journal_,
 - multiple referential versions of the procedure with explanatory comments including
-- `hunterNumba.py` a one-size-fits-all, self-contained, reasonably fast, contemporary algorithm that is nevertheless infected by _noobaceae ignorancium_, and
+- [hunterNumba.py](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/reference), a one-size-fits-all, self-contained, reasonably fast, contemporary algorithm that is nevertheless infected by _noobaceae ignorancium_, and
 - miscellaneous notes.
 
 [![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/unittests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/unittests.yml)
@@ -97,13 +97,13 @@ Cache cleared from C:\apps\mapFolding\mapFolding\.cache
 
 ### The typo-laden algorithm published in 1971
 
-The full paper, 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](https://doi.org/10.1093/comjnl/14.1.75) ([BibTex](mapFolding/citations/Lunnon.bibtex) citation) is available at the DOI link. (As of 3 January 2025, the paper is a PDF of images, not text, and can be accessed without cost or login.)
+The full paper, 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](https://doi.org/10.1093/comjnl/14.1.75) ([BibTex](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/citations/Lunnon.bibtex) citation) is available at the DOI link. (As of 3 January 2025, the paper is a PDF of images, not text, and can be accessed without cost or login.)
 
-In [`foldings.txt`](mapFolding/reference/foldings.txt), you can find a text transcription of the algorithm as it was printed in 1971. In [`foldings.AA`](mapFolding/reference/foldings.AA), I have corrected obvious transcription errors, documented with comments, and I have reformatted line breaks and indentation. For contemporary readers, the result is likely easier to read than the text transcription or the original paper are easy to read. This is especially true if you view the document with semantic highlighting, such as with [Algol 60 syntax highlighter](https://github.com/PolariTOON/language-algol60).
+In [`foldings.txt`](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/reference/foldings.txt), you can find a text transcription of the algorithm as it was printed in 1971. In [`foldings.AA`](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/reference/foldings.AA), I have corrected obvious transcription errors, documented with comments, and I have reformatted line breaks and indentation. For contemporary readers, the result is likely easier to read than the text transcription or the original paper are easy to read. This is especially true if you view the document with semantic highlighting, such as with [Algol 60 syntax highlighter](https://github.com/PolariTOON/language-algol60).
 
 ### Java implementation(s) and improvements
 
-[archmageirvine](https://github.com/archmageirvine/joeis/blob/80e3e844b11f149704acbab520bc3a3a25ac34ff/src/irvine/oeis/a001/A001415.java) ([BibTex](mapFolding/citations/jOEIS.bibtex) citation) says about the Java code:
+[archmageirvine](https://github.com/archmageirvine/joeis/blob/80e3e844b11f149704acbab520bc3a3a25ac34ff/src/irvine/oeis/a001/A001415.java) ([BibTex](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/citations/jOEIS.bibtex) citation) says about the Java code:
 
 ```java
 /**
@@ -122,49 +122,12 @@ In [`foldings.txt`](mapFolding/reference/foldings.txt), you can find a text tran
 
 ~~This caused my neurosis:~~ I enjoyed the following video, which is what introduced me to map folding.
 
-"How Many Ways Can You Fold a Map?" by Physics for the Birds, 2024 November 13 ([BibTex](mapFolding/citations/Physics_for_the_Birds.bibtex) citation)
+"How Many Ways Can You Fold a Map?" by Physics for the Birds, 2024 November 13 ([BibTex](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/citations/Physics_for_the_Birds.bibtex) citation)
 
 [![How Many Ways Can You Fold a Map?](https://i.ytimg.com/vi/sfH9uIY3ln4/hq720.jpg)](https://www.youtube.com/watch?v=sfH9uIY3ln4)
 
-## Install this package
-
-### From Github
-
-```sh
-pip install mapFolding@git+https://github.com/hunterhogan/mapFolding.git
-```
-
-### From a local directory
-
-#### Windows
-
-```powershell
-git clone https://github.com/hunterhogan/mapFolding.git \path\to\mapFolding
-pip install mapFolding@file:\path\to\mapFolding
-```
-
-#### POSIX
-
-```bash
-git clone https://github.com/hunterhogan/mapFolding.git /path/to/mapFolding
-pip install mapFolding@file:/path/to/mapFolding
-```
-
-## Install updates
-
-```sh
-pip install --upgrade mapFolding@git+https://github.com/hunterhogan/mapFolding.git
-```
-
-## Creating a virtual environment before installation
-
-You can isolate `mapFolding` in a virtual environment. For example, use the following commands to create a directory for the virtual environment, activate the virtual environment, and install the package. In the future, you will likely need to activate the virtual environment before using `mapFolding` again. From the command line, in a directory you want to install in.
+## Installation
 
 ```sh
-py -m venv mapFolding
-cd mapFolding
-cd Scripts
-activate
-cd ..
-pip install mapFolding@git+https://github.com/hunterhogan/mapFolding.git
+pip install mapFolding
 ```

{mapfolding-0.2.0 → mapfolding-0.2.2}/README.md

@@ -7,11 +7,11 @@ from mapFolding import countFolds
 foldsTotal = countFolds( [2,10] )
 ```
 
-The directory `mapFolding/reference` has
+The directory [mapFolding/reference](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/reference) has
 
 - a verbatim transcription of the "procedure" published in _The Computer Journal_,
 - multiple referential versions of the procedure with explanatory comments including
-- `hunterNumba.py` a one-size-fits-all, self-contained, reasonably fast, contemporary algorithm that is nevertheless infected by _noobaceae ignorancium_, and
+- [hunterNumba.py](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/reference), a one-size-fits-all, self-contained, reasonably fast, contemporary algorithm that is nevertheless infected by _noobaceae ignorancium_, and
 - miscellaneous notes.
 
 [![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/unittests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/unittests.yml)
@@ -72,13 +72,13 @@ Cache cleared from C:\apps\mapFolding\mapFolding\.cache
 
 ### The typo-laden algorithm published in 1971
 
-The full paper, 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](https://doi.org/10.1093/comjnl/14.1.75) ([BibTex](mapFolding/citations/Lunnon.bibtex) citation) is available at the DOI link. (As of 3 January 2025, the paper is a PDF of images, not text, and can be accessed without cost or login.)
+The full paper, 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](https://doi.org/10.1093/comjnl/14.1.75) ([BibTex](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/citations/Lunnon.bibtex) citation) is available at the DOI link. (As of 3 January 2025, the paper is a PDF of images, not text, and can be accessed without cost or login.)
 
-In [`foldings.txt`](mapFolding/reference/foldings.txt), you can find a text transcription of the algorithm as it was printed in 1971. In [`foldings.AA`](mapFolding/reference/foldings.AA), I have corrected obvious transcription errors, documented with comments, and I have reformatted line breaks and indentation. For contemporary readers, the result is likely easier to read than the text transcription or the original paper are easy to read. This is especially true if you view the document with semantic highlighting, such as with [Algol 60 syntax highlighter](https://github.com/PolariTOON/language-algol60).
+In [`foldings.txt`](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/reference/foldings.txt), you can find a text transcription of the algorithm as it was printed in 1971. In [`foldings.AA`](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/reference/foldings.AA), I have corrected obvious transcription errors, documented with comments, and I have reformatted line breaks and indentation. For contemporary readers, the result is likely easier to read than the text transcription or the original paper are easy to read. This is especially true if you view the document with semantic highlighting, such as with [Algol 60 syntax highlighter](https://github.com/PolariTOON/language-algol60).
 
 ### Java implementation(s) and improvements
 
-[archmageirvine](https://github.com/archmageirvine/joeis/blob/80e3e844b11f149704acbab520bc3a3a25ac34ff/src/irvine/oeis/a001/A001415.java) ([BibTex](mapFolding/citations/jOEIS.bibtex) citation) says about the Java code:
+[archmageirvine](https://github.com/archmageirvine/joeis/blob/80e3e844b11f149704acbab520bc3a3a25ac34ff/src/irvine/oeis/a001/A001415.java) ([BibTex](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/citations/jOEIS.bibtex) citation) says about the Java code:
 
 ```java
 /**
@@ -97,49 +97,12 @@ In [`foldings.txt`](mapFolding/reference/foldings.txt), you can find a text tran
 
 ~~This caused my neurosis:~~ I enjoyed the following video, which is what introduced me to map folding.
 
-"How Many Ways Can You Fold a Map?" by Physics for the Birds, 2024 November 13 ([BibTex](mapFolding/citations/Physics_for_the_Birds.bibtex) citation)
+"How Many Ways Can You Fold a Map?" by Physics for the Birds, 2024 November 13 ([BibTex](https://github.com/hunterhogan/mapFolding/blob/main/mapFolding/citations/Physics_for_the_Birds.bibtex) citation)
 
 [![How Many Ways Can You Fold a Map?](https://i.ytimg.com/vi/sfH9uIY3ln4/hq720.jpg)](https://www.youtube.com/watch?v=sfH9uIY3ln4)
 
-## Install this package
-
-### From Github
-
-```sh
-pip install mapFolding@git+https://github.com/hunterhogan/mapFolding.git
-```
-
-### From a local directory
-
-#### Windows
-
-```powershell
-git clone https://github.com/hunterhogan/mapFolding.git \path\to\mapFolding
-pip install mapFolding@file:\path\to\mapFolding
-```
-
-#### POSIX
-
-```bash
-git clone https://github.com/hunterhogan/mapFolding.git /path/to/mapFolding
-pip install mapFolding@file:/path/to/mapFolding
-```
-
-## Install updates
-
-```sh
-pip install --upgrade mapFolding@git+https://github.com/hunterhogan/mapFolding.git
-```
-
-## Creating a virtual environment before installation
-
-You can isolate `mapFolding` in a virtual environment. For example, use the following commands to create a directory for the virtual environment, activate the virtual environment, and install the package. In the future, you will likely need to activate the virtual environment before using `mapFolding` again. From the command line, in a directory you want to install in.
+## Installation
 
 ```sh
-py -m venv mapFolding
-cd mapFolding
-cd Scripts
-activate
-cd ..
-pip install mapFolding@git+https://github.com/hunterhogan/mapFolding.git
+pip install mapFolding
 ```

mapfolding-0.2.2/mapFolding/__init__.py

@@ -0,0 +1,13 @@
+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
+from .oeis import oeisIDfor_n, getOEISids, clearOEIScache
+
+__all__ = [
+    'clearOEIScache',
+    'countFolds',
+    'getOEISids',
+    'oeisIDfor_n',
+]

mapfolding-0.2.2/mapFolding/babbage.py

@@ -0,0 +1,30 @@
+from mapFolding.lovelace import countFoldsCompiled
+from numpy import integer
+from numpy.typing import NDArray
+from typing import Any, Tuple
+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]]) -> 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-0.2.2/mapFolding/beDRY.py

@@ -0,0 +1,270 @@
+"""A relatively stable API for oft-needed functionality."""
+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
+from numpy.typing import NDArray
+from numpy import integer
+import sys
+import operator
+
+def getLeavesTotal(listDimensions: Sequence[int]) -> int:
+    """
+    How many leaves are in the map.
+
+    Parameters:
+        listDimensions: A list of integers representing dimensions.
+
+    Returns:
+        productDimensions: The product of all positive integer dimensions.
+    """
+    listNonNegative = parseDimensions(listDimensions, 'listDimensions')
+    listPositive = [dimension for dimension in listNonNegative if dimension > 0]
+
+    if not listPositive:
+        return 0
+    else:
+        productDimensions = 1
+        for dimension in listPositive:
+            if dimension > sys.maxsize // productDimensions:
+                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(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:
+        return 0
+    else:
+        leavesTotal = getLeavesTotal(listDimensions)
+    if isinstance(computationDivisions, int):
+        taskDivisions = computationDivisions
+    elif isinstance(computationDivisions, str):
+        computationDivisions = computationDivisions.lower()
+        if computationDivisions == "maximum":
+            taskDivisions = leavesTotal
+        elif computationDivisions == "cpu":
+            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 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 taskDivisions
+
+def makeConnectionGraph(listDimensions: Sequence[int], **keywordArguments: Optional[Type]) -> NDArray[integer[Any]]:
+    """
+    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 sequence of integers representing the dimensions of the map.
+    Returns:
+        connectionGraph: A 3D numpy array with shape of (dimensionsTotal + 1, leavesTotal + 1, leavesTotal + 1).
+    """
+    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.multiply.accumulate([1] + mapShape, dtype=datatype)
+
+    # Step 2: create a coordinate system
+    coordinateSystem = numpy.zeros((dimensionsTotal + 1, leavesTotal + 1), dtype=datatype)
+
+    for dimension1ndex in range(1, dimensionsTotal + 1):
+        for leaf1ndex in range(1, leavesTotal + 1):
+            coordinateSystem[dimension1ndex, leaf1ndex] = (
+                ((leaf1ndex - 1) // cumulativeProduct[dimension1ndex - 1]) %
+                arrayDimensions[dimension1ndex - 1] + 1
+            )
+
+    # Step 3: create and fill the connection graph
+    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):
+            for connectee1ndex in range(1, activeLeaf1ndex + 1):
+                # Base coordinate conditions
+                isFirstCoord = coordinateSystem[dimension1ndex, connectee1ndex] == 1
+                isLastCoord = coordinateSystem[dimension1ndex, connectee1ndex] == arrayDimensions[dimension1ndex - 1]
+                exceedsActive = connectee1ndex + cumulativeProduct[dimension1ndex - 1] > activeLeaf1ndex
+
+                # Parity check
+                isEvenParity = (coordinateSystem[dimension1ndex, activeLeaf1ndex] & 1) == \
+                                (coordinateSystem[dimension1ndex, connectee1ndex] & 1)
+
+                # Determine connection value
+                if (isEvenParity and isFirstCoord) or (not isEvenParity and (isLastCoord or exceedsActive)):
+                    connectionGraph[dimension1ndex, activeLeaf1ndex, connectee1ndex] = connectee1ndex
+                elif isEvenParity and not isFirstCoord:
+                    connectionGraph[dimension1ndex, activeLeaf1ndex, connectee1ndex] = connectee1ndex - cumulativeProduct[dimension1ndex - 1]
+                elif not isEvenParity and not (isLastCoord or exceedsActive):
+                    connectionGraph[dimension1ndex, activeLeaf1ndex, connectee1ndex] = connectee1ndex + cumulativeProduct[dimension1ndex - 1]
+                else:
+                    connectionGraph[dimension1ndex, activeLeaf1ndex, connectee1ndex] = connectee1ndex
+
+    return connectionGraph
+
+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[indexThe.taskDivisions] = getTaskDivisions(computationDivisions, concurrencyLimit, CPUlimit, listDimensions)
+    
+    stateInitialized = computationState(
+        connectionGraph = makeConnectionGraph(mapShape, datatype=datatypeDefault),
+        foldsTotal = makeDataContainer(the[indexThe.leavesTotal], datatypeLarge),
+        mapShape = mapShape,
+        my = makeDataContainer(len(indexMy), datatypeLarge),
+        gapsWhere = makeDataContainer(int(the[indexThe.leavesTotal]) * int(the[indexThe.leavesTotal]) + 1, datatypeDefault),
+        the = the,
+        track = makeDataContainer((len(indexTrack), the[indexThe.leavesTotal] + 1), datatypeLarge)
+        )
+
+    stateInitialized['my'][indexMy.leaf1ndex.value] = 1
+
+    return stateInitialized
+
+def parseDimensions(dimensions: Sequence[int], parameterName: str = 'unnamed parameter') -> List[int]:
+    """
+    Parse and validate dimensions are non-negative integers.
+
+    Parameters:
+        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
+    Raises:
+        ValueError: If any dimension is negative or if the list is empty
+        TypeError: If any element cannot be converted to integer (raised by intInnit)
+    """
+    listValidated = intInnit(dimensions, parameterName)
+    listNonNegative = []
+    for dimension in listValidated:
+        if dimension < 0:
+            raise ValueError(f"Dimension {dimension} must be non-negative")
+        listNonNegative.append(dimension)
+
+    if not listNonNegative:
+        raise ValueError("At least one dimension must be non-negative")
+
+    return listNonNegative
+
+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: 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)
+    numba.set_num_threads(concurrencyLimit)
+
+    return concurrencyLimit
+
+def validateListDimensions(listDimensions: Sequence[int]) -> List[int]:
+    """
+    Validates and sorts a sequence of at least two positive dimensions.
+
+    Parameters:
+        listDimensions: A sequence of integer dimensions to be validated.
+
+    Returns:
+        dimensionsValidSorted: A list, with at least two elements, of only positive integers.
+
+    Raises:
+        ValueError: If the input listDimensions is None.
+        NotImplementedError: If the resulting list of positive dimensions has fewer than two elements.
+    """
+    if not listDimensions:
+        raise ValueError(f"listDimensions is a required parameter.")
+    listNonNegative = parseDimensions(listDimensions, 'listDimensions')
+    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 sorted(dimensionsValid)

{mapfolding-0.2.0 → mapfolding-0.2.2}/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()