mapFolding 0.2.0__py3-none-any.whl

mapFolding/oeis.py

@@ -0,0 +1,299 @@
+"""Everything implementing the The Online Encyclopedia of Integer Sequences (OEIS);
+_only_ things that implement _only_ the OEIS."""
+from datetime import datetime, timedelta
+from mapFolding import countFolds
+from typing import TYPE_CHECKING, List, Callable, Dict, Final
+import pathlib
+import random
+import sys
+import time
+import urllib.request
+import urllib.response
+
+if TYPE_CHECKING:
+    from typing import TypedDict
+else:
+    TypedDict = dict
+
+"""
+Section: make `settingsOEIS`"""
+class SettingsOEIS(TypedDict):
+    # I would prefer to load description dynamically from OEIS, but it's a pita for me
+    # to learn how to efficiently implement right now.
+    description: str
+    getDimensions: Callable[[int], List[int]]
+    valuesBenchmark: List[int]
+    valuesKnown: Dict[int, int]
+    valuesTestValidation: List[int]
+    valueUnknown: int
+
+settingsOEIShardcodedValues = {
+    'A001415': {
+        'description': 'Number of ways of folding a 2 X n strip of stamps.',
+        'getDimensions': lambda n: sorted([2, n]),
+        'valuesBenchmark': [14],
+        'valuesTestValidation': [0, 1, random.randint(2, 9)],
+    },
+    'A001416': {
+        'description': 'Number of ways of folding a 3 X n strip of stamps.',
+        'getDimensions': lambda n: sorted([3, n]),
+        'valuesBenchmark': [9],
+        'valuesTestValidation': [0, 1, random.randint(2, 6)],
+    },
+    'A001417': {
+        'description': 'Number of ways of folding a 2 X 2 X ... X 2 n-dimensional map.',
+        'getDimensions': lambda n: [2] * n,
+        'valuesBenchmark': [6],
+        'valuesTestValidation': [0, 1, random.randint(2, 4)],
+    },
+    'A195646': {
+        'description': 'Number of ways of folding a 3 X 3 X ... X 3 n-dimensional map.',
+        'getDimensions': lambda n: [3] * n,
+        'valuesBenchmark': [3],
+        'valuesTestValidation': [0, 1, 2],
+    },
+    'A001418': {
+        'description': 'Number of ways of folding an n X n sheet of stamps.',
+        'getDimensions': lambda n: [n, n],
+        'valuesBenchmark': [5],
+        # offset 1: hypothetically, if I were to load the offset from OEIS, I could use it to
+        # determine if a sequence is defined at n=0, which would affect, for example, the valuesTestValidation.
+        'valuesTestValidation': [1, random.randint(2, 4)],
+    },
+}
+
+oeisIDsImplemented: Final[List[str]]  = sorted([oeisID.upper().strip() for oeisID in settingsOEIShardcodedValues.keys()])
+"""Directly implemented OEIS IDs; standardized, e.g., 'A001415'."""
+
+def _parseBFileOEIS(OEISbFile: str, oeisID: str) -> Dict[int, int]:
+    """
+    Parses the content of an OEIS b-file for a given sequence ID.
+    This function processes a multiline string representing an OEIS b-file and
+    creates a dictionary mapping integer indices to their corresponding sequence
+    values. The first line of the b-file is expected to contain a comment that
+    matches the given sequence ID. If it does not match, a ValueError is raised.
+
+    Parameters:
+        OEISbFile: A multiline string representing an OEIS b-file.
+        oeisID: The expected OEIS sequence identifier.
+    Returns:
+        OEISsequence: A dictionary where each key is an integer index `n` and
+        each value is the sequence value `a(n)` corresponding to that index.
+    Raises:
+        ValueError: If the first line of the file does not indicate the expected
+        sequence ID or if the content format is invalid.
+    """
+    bFileLines = OEISbFile.strip().splitlines()
+    # The first line has the sequence ID
+    if not bFileLines.pop(0).startswith(f"# {oeisID}"):
+        raise ValueError(f"Content does not match sequence {oeisID}")
+
+    OEISsequence = {}
+    for line in bFileLines:
+        if line.startswith('#'):
+            continue
+        n, aOFn = map(int, line.split())
+        OEISsequence[n] = aOFn
+    return OEISsequence
+
+try:
+    _pathCache = pathlib.Path(__file__).parent / ".cache"
+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
+    to their corresponding values.
+    This function checks for a cached local copy of the sequence data, using it if
+    it has not expired. Otherwise, it fetches the sequence data from the OEIS
+    website and writes it to the cache. The parsed data is returned as a dictionary
+    mapping each index to its sequence value.
+
+    Parameters:
+        oeisID: The identifier of the OEIS sequence to retrieve.
+    Returns:
+        OEISsequence: A dictionary where each key is an integer index, `n`, and each
+        value is the corresponding "a(n)" from the OEIS entry.
+    Raises:
+        ValueError: If the cached or downloaded file format is invalid.
+        IOError: If there is an error reading from or writing to the local cache.
+    """
+
+    pathFilenameCache = _pathCache / _formatFilenameCache.format(oeisID=oeisID)
+    cacheDays = 7
+
+    tryCache = False
+    if pathFilenameCache.exists():
+        fileAge = datetime.now() - datetime.fromtimestamp(pathFilenameCache.stat().st_mtime)
+        tryCache = fileAge < timedelta(days=cacheDays)
+
+    if tryCache:
+        try:
+            OEISbFile = pathFilenameCache.read_text()
+            return _parseBFileOEIS(OEISbFile, oeisID)
+        except (ValueError, IOError):
+            tryCache = False
+
+    urlOEISbFile = f"https://oeis.org/{oeisID}/b{oeisID[1:]}.txt"
+    httpResponse: urllib.response.addinfourl = urllib.request.urlopen(urlOEISbFile)
+    OEISbFile = httpResponse.read().decode('utf-8')
+
+    if not tryCache:
+        pathFilenameCache.parent.mkdir(parents=True, exist_ok=True)
+        pathFilenameCache.write_text(OEISbFile)
+
+    return _parseBFileOEIS(OEISbFile, oeisID)
+
+def makeSettingsOEIS() -> Dict[str, SettingsOEIS]:
+    settingsTarget = {}
+    for oeisID in oeisIDsImplemented:
+        valuesKnownSherpa = _getOEISidValues(oeisID)
+        settingsTarget[oeisID] = SettingsOEIS(
+            description = settingsOEIShardcodedValues[oeisID]['description'],
+            getDimensions = settingsOEIShardcodedValues[oeisID]['getDimensions'],
+            valuesBenchmark = settingsOEIShardcodedValues[oeisID]['valuesBenchmark'],
+            valuesKnown = valuesKnownSherpa,
+            valuesTestValidation = settingsOEIShardcodedValues[oeisID]['valuesTestValidation'],
+            valueUnknown = max(valuesKnownSherpa.keys(), default=0) + 1
+        )
+    return settingsTarget
+
+settingsOEIS: Dict[str, SettingsOEIS] = makeSettingsOEIS()
+"""All values and settings for `oeisIDsImplemented`."""
+
+"""
+Section: private functions"""
+
+def _formatHelpText() -> str:
+    """Format standardized help text for both CLI and interactive use."""
+    exampleOEISid = oeisIDsImplemented[0]
+    exampleN = settingsOEIS[exampleOEISid]['valuesTestValidation'][-1]
+
+    return (
+        "\nAvailable OEIS sequences:\n"
+        f"{_formatOEISsequenceInfo()}\n"
+        "\nUsage examples:\n"
+        "  Command line:\n"
+        f"    OEIS_for_n {exampleOEISid} {exampleN}\n"
+        "  Python:\n"
+        "    from mapFolding import oeisIDfor_n\n"
+        f"    foldsTotal = oeisIDfor_n('{exampleOEISid}', {exampleN})"
+    )
+
+def _formatOEISsequenceInfo() -> str:
+    """Format information about available OEIS sequences for display or error messages."""
+    return "\n".join(
+        f"  {oeisID}: {settingsOEIS[oeisID]['description']}"
+        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"""
+
+def oeisIDfor_n(oeisID: str, n: int) -> int:
+    """
+    Calculate a(n) of a sequence from "The On-Line Encyclopedia of Integer Sequences" (OEIS).
+
+    Parameters:
+        oeisID: The ID of the OEIS sequence.
+        n: A non-negative integer for which to calculate the sequence value.
+
+    Returns:
+        sequenceValue: a(n) of the OEIS sequence.
+
+    Raises:
+        ValueError: If n is negative.
+        KeyError: If the OEIS sequence ID is not directly implemented.
+    """
+    oeisID = _validateOEISid(oeisID)
+
+    if not isinstance(n, int) or n < 0:
+        raise ValueError("`n` must be non-negative integer.")
+
+    listDimensions = settingsOEIS[oeisID]['getDimensions'](n)
+
+    if n <= 1 or len(listDimensions) < 2:
+        foldsTotal = settingsOEIS[oeisID]['valuesKnown'].get(n, None)
+        if foldsTotal is not None:
+            return foldsTotal
+        else:
+            raise ArithmeticError(f"OEIS sequence {oeisID} is not defined at n={n}.")
+
+    return countFolds(listDimensions)
+
+def OEIS_for_n() -> None:
+    """Command-line interface for oeisIDfor_n."""
+    import argparse
+
+    parserCLI = argparse.ArgumentParser(
+        description="Calculate a(n) for an OEIS sequence.",
+        epilog=_formatHelpText(),
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parserCLI.add_argument('oeisID', help="OEIS sequence identifier")
+    parserCLI.add_argument('n', type=int, help="Calculate a(n) for this n")
+
+    argumentsCLI = parserCLI.parse_args()
+
+    timeStart = time.perf_counter()
+
+    try:
+        print(oeisIDfor_n(argumentsCLI.oeisID, argumentsCLI.n), "distinct folding patterns.")
+    except (KeyError, ValueError, ArithmeticError) as ERRORmessage:
+        print(f"Error: {ERRORmessage}", file=sys.stderr)
+        sys.exit(1)
+
+    timeElapsed = time.perf_counter() - timeStart
+    print(f"Time elapsed: {timeElapsed:.3f} seconds")
+
+def clearOEIScache() -> None:
+    """Delete all cached OEIS sequence files."""
+    if not _pathCache.exists():
+        print(f"Cache directory, {_pathCache}, not found - nothing to clear.")
+        return
+    else:
+        for oeisID in settingsOEIS:
+            pathFilenameCache = _pathCache / _formatFilenameCache.format(oeisID=oeisID)
+            pathFilenameCache.unlink(missing_ok=True)
+
+    print(f"Cache cleared from {_pathCache}")
+
+def getOEISids() -> None:
+    """Print all available OEIS sequence IDs that are directly implemented."""
+    print(_formatHelpText())
+
+if __name__ == "__main__":
+    getOEISids()

mapFolding/reference/hunterNumba.py

@@ -0,0 +1,132 @@
+from typing import List
+import numba
+import numpy
+
+@numba.jit(cache=True, nopython=True, fastmath=True)
+def countFolds(listDimensions: List[int]) -> int:
+    """
+    Count the number of distinct ways to fold a map with at least two positive dimensions.
+
+    Parameters:
+        listDimensions: A list of integers representing the dimensions of the map. Error checking and DRY code are impermissible in the numba and jax universes. Validate the list yourself before passing here. There might be some tools for that in this package unless I have become a pyL33t coder.
+
+    Returns:
+        foldsTotal: The total number of distinct folds for the given map dimensions.
+    """
+    def integerSmall(value) -> numpy.uint8:
+        return numpy.uint8(value)
+
+    def integerLarge(value) -> numpy.uint64:
+        return numpy.uint64(value)
+
+    dtypeDefault = numpy.uint8
+    dtypeMaximum = numpy.uint16
+
+    leavesTotal = integerSmall(1)
+    for 个 in listDimensions:
+        leavesTotal = leavesTotal * integerSmall(个)
+    dimensionsTotal = integerSmall(len(listDimensions))
+
+    """How to build a leaf connection graph, also called a "Cartesian Product Decomposition"
+    or a "Dimensional Product Mapping", with sentinels:
+    Step 1: find the cumulative product of the map's dimensions"""
+    cumulativeProduct = numpy.ones(dimensionsTotal + 1, dtype=dtypeDefault)
+    for dimension1ndex in range(1, dimensionsTotal + 1):
+        cumulativeProduct[dimension1ndex] = cumulativeProduct[dimension1ndex - 1] * listDimensions[dimension1ndex - 1]
+
+    """Step 2: for each dimension, create a coordinate system """
+    """coordinateSystem[dimension1ndex, leaf1ndex] holds the dimension1ndex-th coordinate of leaf leaf1ndex"""
+    coordinateSystem = numpy.zeros((dimensionsTotal + 1, leavesTotal + 1), dtype=dtypeDefault)
+    for dimension1ndex in range(1, dimensionsTotal + 1):
+        for leaf1ndex in range(1, leavesTotal + 1):
+            coordinateSystem[dimension1ndex, leaf1ndex] = ((leaf1ndex - 1) // cumulativeProduct[dimension1ndex - 1]) % listDimensions[dimension1ndex - 1] + 1
+
+    """Step 3: create a huge empty connection graph"""
+    connectionGraph = numpy.zeros((dimensionsTotal + 1, leavesTotal + 1, leavesTotal + 1), dtype=dtypeDefault)
+
+    """Step for... for... for...: fill the connection graph"""
+    for dimension1ndex in range(1, dimensionsTotal + 1):
+        for activeLeaf1ndex in range(1, leavesTotal + 1):
+            for leaf1ndexConnectee in range(1, activeLeaf1ndex + 1):
+                connectionGraph[dimension1ndex, activeLeaf1ndex, leaf1ndexConnectee] = (0 if leaf1ndexConnectee == 0
+                                else ((leaf1ndexConnectee if coordinateSystem[dimension1ndex, leaf1ndexConnectee] == 1
+                                            else leaf1ndexConnectee - cumulativeProduct[dimension1ndex - 1])
+                                    if (coordinateSystem[dimension1ndex, activeLeaf1ndex] & 1) == (coordinateSystem[dimension1ndex, leaf1ndexConnectee] & 1)
+                                    else (leaf1ndexConnectee if coordinateSystem[dimension1ndex, leaf1ndexConnectee] == listDimensions[dimension1ndex-1]
+                                            or leaf1ndexConnectee + cumulativeProduct[dimension1ndex - 1] > activeLeaf1ndex
+                                            else leaf1ndexConnectee + cumulativeProduct[dimension1ndex - 1])))
+
+    """Indices of array `track` (to "track" the execution state), which is a collection of one-dimensional arrays each of length `leavesTotal + 1`."""
+    leafAbove = numba.literally(0)
+    leafBelow = numba.literally(1)
+    countDimensionsGapped = numba.literally(2)
+    gapRangeStart = numba.literally(3)
+    track = numpy.zeros((4, leavesTotal + 1), dtype=dtypeDefault)
+
+    gapsWhere = numpy.zeros(integerLarge(integerLarge(leavesTotal) * integerLarge(leavesTotal) + 1), dtype=dtypeMaximum)
+
+    foldsTotal = integerLarge(0)
+    activeLeaf1ndex = integerSmall(1)
+    activeGap1ndex = integerSmall(0)
+
+    while activeLeaf1ndex > 0:
+        if activeLeaf1ndex <= 1 or track[leafBelow, 0] == 1:
+            if activeLeaf1ndex > leavesTotal:
+                foldsTotal += leavesTotal
+            else:
+                dimensionsUnconstrained = integerSmall(0)
+                """Track possible gaps for activeLeaf1ndex in each section"""
+                gap1ndexCeiling = track[gapRangeStart, activeLeaf1ndex - 1]
+
+                """Count possible gaps for activeLeaf1ndex in each section"""
+                dimension1ndex = integerSmall(1)
+                while dimension1ndex <= dimensionsTotal:
+                    if connectionGraph[dimension1ndex, activeLeaf1ndex, activeLeaf1ndex] == activeLeaf1ndex:
+                        dimensionsUnconstrained += 1
+                    else:
+                        leaf1ndexConnectee = connectionGraph[dimension1ndex, activeLeaf1ndex, activeLeaf1ndex]
+                        while leaf1ndexConnectee != activeLeaf1ndex:
+                            gapsWhere[gap1ndexCeiling] = leaf1ndexConnectee
+                            if track[countDimensionsGapped, leaf1ndexConnectee] == 0:
+                                gap1ndexCeiling += 1
+                            track[countDimensionsGapped, leaf1ndexConnectee] += 1
+                            leaf1ndexConnectee = connectionGraph[dimension1ndex, activeLeaf1ndex, track[leafBelow, leaf1ndexConnectee]]
+                    dimension1ndex += 1
+
+                """If activeLeaf1ndex is unconstrained in all sections, it can be inserted anywhere"""
+                if dimensionsUnconstrained == dimensionsTotal:
+                    leaf1ndex = integerSmall(0)
+                    while leaf1ndex < activeLeaf1ndex:
+                        gapsWhere[gap1ndexCeiling] = leaf1ndex
+                        gap1ndexCeiling += 1
+                        leaf1ndex += 1
+
+                """Filter gaps that are common to all sections"""
+                indexMiniGap = activeGap1ndex
+                while indexMiniGap < gap1ndexCeiling:
+                    gapsWhere[activeGap1ndex] = gapsWhere[indexMiniGap]
+                    if track[countDimensionsGapped, gapsWhere[indexMiniGap]] == dimensionsTotal - dimensionsUnconstrained:
+                        activeGap1ndex += 1
+                    """Reset track[countDimensionsGapped] for next iteration"""
+                    track[countDimensionsGapped, gapsWhere[indexMiniGap]] = 0
+                    indexMiniGap += 1
+
+        """Recursive backtracking steps"""
+        while activeLeaf1ndex > 0 and activeGap1ndex == track[gapRangeStart, activeLeaf1ndex - 1]:
+            activeLeaf1ndex -= 1
+            track[leafBelow, track[leafAbove, activeLeaf1ndex]] = track[leafBelow, activeLeaf1ndex]
+            track[leafAbove, track[leafBelow, activeLeaf1ndex]] = track[leafAbove, activeLeaf1ndex]
+
+        """Place leaf in valid position"""
+        if activeLeaf1ndex > 0:
+            activeGap1ndex -= 1
+            track[leafAbove, activeLeaf1ndex] = gapsWhere[activeGap1ndex]
+            track[leafBelow, activeLeaf1ndex] = track[leafBelow, track[leafAbove, activeLeaf1ndex]]
+            track[leafBelow, track[leafAbove, activeLeaf1ndex]] = activeLeaf1ndex
+            track[leafAbove, track[leafBelow, activeLeaf1ndex]] = activeLeaf1ndex
+            """Save current gap index"""
+            track[gapRangeStart, activeLeaf1ndex] = activeGap1ndex
+            """Move to next leaf"""
+            activeLeaf1ndex += 1
+
+    return int(foldsTotal)

mapFolding/reference/irvineJavaPort.py

@@ -0,0 +1,120 @@
+"""
+Ported from the Java version by Sean A. Irvine:
+https://github.com/archmageirvine/joeis/blob/80e3e844b11f149704acbab520bc3a3a25ac34ff/src/irvine/oeis/a001/A001415.java
+
+Citation: mapFolding/citations/jOEIS.bibtex
+"""
+def foldings(p: list[int], res: int = 0, mod: int = 0) -> int:
+    """
+    Compute the total number of foldings for a map with dimensions specified in p.
+
+    Parameters:
+        p: List of integers representing the dimensions of the map.
+        res: Residue for modulo operation (integer).
+        mod: Modulus for modulo operation (integer).
+
+    Returns:
+        total_count: The total number of foldings (integer).
+    """
+    n = 1  # Total number of leaves
+    d = len(p)  # Number of dimensions
+    for dimension in p:
+        n *= dimension
+
+    # Initialize arrays/lists
+    A = [0] * (n + 1)       # Leaf above leaf m
+    B = [0] * (n + 1)       # Leaf below leaf m
+    count = [0] * (n + 1)   # Counts for potential gaps
+    gapter = [0] * (n + 1)  # Indices for gap stack per leaf
+    gap = [0] * (n * n + 1) # Stack of potential gaps
+
+    # Compute arrays P, C, D as per the algorithm
+    P = [1] * (d + 1)
+    for i in range(1, d + 1):
+        P[i] = P[i - 1] * p[i - 1]
+
+    # C[i][m] holds the i-th coordinate of leaf m
+    C = [[0] * (n + 1) for _ in range(d + 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
+
+    # D[i][l][m] computes the leaf connected to m in section i when inserting l
+    D = [[[0] * (n + 1) for _ in range(n + 1)] for _ in range(d + 1)]
+    for i in range(1, d + 1):
+        for l in range(1, n + 1):
+            for m in range(1, l + 1):
+                delta = C[i][l] - C[i][m]
+                if delta % 2 == 0:
+                    # If delta is even
+                    if C[i][m] == 1:
+                        D[i][l][m] = m
+                    else:
+                        D[i][l][m] = m - P[i - 1]
+                else:
+                    # If delta is odd
+                    if C[i][m] == p[i - 1] or m + P[i - 1] > l:
+                        D[i][l][m] = m
+                    else:
+                        D[i][l][m] = m + P[i - 1]
+
+    # Initialize variables for backtracking
+    total_count = 0  # Total number of foldings
+    g = 0            # Gap index
+    l = 1            # Current leaf
+
+    # Start backtracking loop
+    while l > 0:
+        # If we have processed all leaves, increment total count
+        if l > n:
+            total_count += 1
+        else:
+            dd = 0     # Number of sections where leaf l is unconstrained
+            gg = g     # Temporary gap index
+            g = gapter[l - 1]  # Reset gap index for current leaf
+
+            # Count possible gaps for leaf l in each section
+            for i in range(1, d + 1):
+                if D[i][l][l] == l:
+                    dd += 1
+                else:
+                    m = D[i][l][l]
+                    while m != l:
+                        if mod == 0 or l != mod or m % mod == res:
+                            gap[gg] = m
+                            if count[m] == 0:
+                                gg += 1
+                            count[m] += 1
+                        m = D[i][l][B[m]]
+
+            # If leaf l is unconstrained in all sections, it can be inserted anywhere
+            if dd == d:
+                for m in range(l):
+                    gap[gg] = m
+                    gg += 1
+
+            # Filter gaps that are common to all sections
+            for j in range(g, gg):
+                gap[g] = gap[j]
+                if count[gap[j]] == d - dd:
+                    g += 1
+                count[gap[j]] = 0  # Reset count for next iteration
+
+        # Recursive backtracking steps
+        while l > 0 and g == gapter[l - 1]:
+            # No more gaps to try, backtrack to previous leaf
+            l -= 1
+            B[A[l]] = B[l]
+            A[B[l]] = A[l]
+
+        if l > 0:
+            # Try next gap for leaf l
+            g -= 1
+            A[l] = gap[g]
+            B[l] = B[A[l]]
+            B[A[l]] = l
+            A[B[l]] = l
+            gapter[l] = g  # Save current gap index
+            l += 1         # Move to next leaf
+
+    return total_count