mapFolding 0.8.4__tar.gz → 0.8.6__tar.gz

{mapfolding-0.8.4 → mapfolding-0.8.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapFolding
-Version: 0.8.4
+Version: 0.8.6
 Summary: Map folding algorithm with code transformation framework for optimizing numerical computations
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 License: CC-BY-NC-4.0
@@ -35,6 +35,7 @@ Requires-Dist: more_itertools
 Requires-Dist: numba_progress
 Requires-Dist: numba
 Requires-Dist: numpy
+Requires-Dist: platformdirs
 Requires-Dist: python_minifier
 Requires-Dist: tomli
 Requires-Dist: Z0Z_tools
@@ -132,7 +133,7 @@ The package provides a sophisticated transformation framework that bridges the g
   - Study the functional state-transformation approach in `theDao.py` with clear, isolated functions
   - Explore the semantic decomposition in `reference/flattened.py` to understand algorithm sections
 
-- **Code Transformation Pipeline**:
+- **Code Transformation Assembly-line**:
   - **AST Manipulation**: Analyzes and transforms the algorithm's abstract syntax tree
   - **Dataclass "Shattering"**: Decomposes complex state objects into primitive components
   - **Optimization Applications**: Applies domain-specific optimizations for numerical computation

{mapfolding-0.8.4 → mapfolding-0.8.6}/README.md

@@ -82,7 +82,7 @@ The package provides a sophisticated transformation framework that bridges the g
   - Study the functional state-transformation approach in `theDao.py` with clear, isolated functions
   - Explore the semantic decomposition in `reference/flattened.py` to understand algorithm sections
 
-- **Code Transformation Pipeline**:
+- **Code Transformation Assembly-line**:
   - **AST Manipulation**: Analyzes and transforms the algorithm's abstract syntax tree
   - **Dataclass "Shattering"**: Decomposes complex state objects into primitive components
   - **Optimization Applications**: Applies domain-specific optimizations for numerical computation

{mapfolding-0.8.4 → mapfolding-0.8.6}/mapFolding/__init__.py

@@ -1,17 +1,20 @@
 """
-Map folding enumeration and counting algorithms with optimization capabilities.
+Map folding enumeration and counting algorithms with advanced optimization capabilities.
 
-This package implements algorithms to count and enumerate the various ways
+This package implements algorithms to count and enumerate the distinct ways
 a rectangular map can be folded, based on the mathematical problem described
 in Lunnon's 1971 paper. It provides multiple layers of functionality, from
-high-level user interfaces to low-level algorithmic optimizations and code
+high-level user interfaces to sophisticated algorithmic optimizations and code
 transformation tools.
 
 Core modules:
 - basecamp: Public API with simplified interfaces for end users
 - theDao: Core computational algorithm using a functional state-transformation approach
-- beDRY: Utility functions for common operations and parameter management
+- beDRY: Core utility functions implementing consistent data handling, validation, and
+  resource management across the package's computational assembly-line
 - theSSOT: Single Source of Truth for configuration, types, and state management
+- toolboxFilesystem: Cross-platform file management services for storing and retrieving
+  computation results with robust error handling and fallback mechanisms
 - oeis: Interface to the Online Encyclopedia of Integer Sequences for known results
 
 Extended functionality:
@@ -26,9 +29,10 @@ Special directories:
   - reference/jobsCompleted/: Contains successful computations for previously unknown values,
     including first-ever calculations for 2x19 and 2x20 maps (OEIS A001415)
 
-This package strives to balance algorithm readability and understandability with
+This package balances algorithm readability and understandability with
 high-performance computation capabilities, allowing users to compute map folding
-totals for larger dimensions than previously feasible.
+totals for larger dimensions than previously feasible while also providing
+a foundation for exploring advanced code transformation techniques.
 """
 from mapFolding.basecamp import countFolds
 from mapFolding.oeis import clearOEIScache, getOEISids, OEIS_for_n, oeisIDfor_n

{mapfolding-0.8.4 → mapfolding-0.8.6}/mapFolding/basecamp.py

@@ -13,9 +13,9 @@ implementation, and optional persistence of results.
 """
 
 from collections.abc import Sequence
-from mapFolding.beDRY import outfitCountFolds, setCPUlimit, validateListDimensions
-from mapFolding.filesystem import getPathFilenameFoldsTotal, saveFoldsTotal, saveFoldsTotalFAILearly
 from mapFolding.theSSOT import ComputationState, getPackageDispatcher, The
+from mapFolding.beDRY import outfitCountFolds, setProcessorLimit, validateListDimensions
+from mapFolding.toolboxFilesystem import getPathFilenameFoldsTotal, saveFoldsTotal, saveFoldsTotalFAILearly
 from os import PathLike
 from pathlib import PurePath
 
@@ -54,7 +54,7 @@ def countFolds(listDimensions: Sequence[int]
 		If you want to compute a large `foldsTotal`, dividing the computation into tasks is usually a bad idea. Dividing the algorithm into tasks is inherently inefficient: efficient division into tasks means there would be no overlap in the work performed by each task. When dividing this algorithm, the amount of overlap is between 50% and 90% by all tasks: at least 50% of the work done by every task must be done by _all_ tasks. If you improve the computation time, it will only change by -10 to -50% depending on (at the very least) the ratio of the map dimensions and the number of leaves. If an undivided computation would take 10 hours on your computer, for example, the computation will still take at least 5 hours but you might reduce the time to 9 hours. Most of the time, however, you will increase the computation time. If logicalCores >= leavesTotal, it will probably be faster. If logicalCores <= 2 * leavesTotal, it will almost certainly be slower for all map dimensions.
 	"""
 	mapShape: tuple[int, ...] = validateListDimensions(listDimensions)
-	concurrencyLimit: int = setCPUlimit(CPUlimit, The.concurrencyPackage)
+	concurrencyLimit: int = setProcessorLimit(CPUlimit, The.concurrencyPackage)
 	computationStateInitialized: ComputationState = outfitCountFolds(mapShape, computationDivisions, concurrencyLimit)
 
 	if pathLikeWriteFoldsTotal is not None:

mapfolding-0.8.6/mapFolding/beDRY.py

@@ -0,0 +1,348 @@
+"""
+Core utility functions implementing DRY (Don't Repeat Yourself) principles for the mapFolding package.
+
+This module serves as the foundation for consistent data management and parameter validation
+across the entire mapFolding computation assembly-line. It provides critical utility functions that:
+
+1. Calculate and validate fundamental computational parameters such as leaves total and task divisions.
+2. Generate specialized connection graphs that define the folding algorithm's constraints.
+3. Provide centralized resource allocation and system limits management.
+4. Construct and manage uniform data structures for the computation state.
+5. Ensure parameter validation and safe type conversion.
+
+The functions in this module maintain a clear separation between data initialization and algorithm
+implementation, enabling the package to support multiple computational strategies (sequential,
+parallel, and JIT-compiled) while ensuring consistent input handling and state management.
+
+These utilities form a stable internal API that other modules depend on, particularly theSSOT
+(Single Source of Truth), theDao (core algorithm), and the synthetic module generators that
+produce optimized implementations.
+"""
+from collections.abc import Sequence
+from mapFolding.theSSOT import ComputationState, numpyIntegerType
+from numpy import dtype as numpy_dtype, int64 as numpy_int64, ndarray
+from sys import maxsize as sysMaxsize
+from typing import Any
+from Z0Z_tools import defineConcurrencyLimit, intInnit, oopsieKwargsie
+import numpy
+
+def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
+	"""
+	Calculate the total number of leaves in a map with the given dimensions.
+
+	The total number of leaves is the product of all dimensions in the map shape.
+	This value is foundational for initializing the computation state and determining
+	task divisions.
+
+	Parameters
+	----------
+	mapShape
+		A tuple of integers representing the dimensions of the map.
+
+	Returns
+	-------
+	leavesTotal
+		The total number of leaves in the map, calculated as the product of all dimensions.
+
+	Raises
+	------
+	OverflowError
+		If the product of dimensions would exceed the system's maximum integer size.
+		This check prevents silent numeric overflow issues that could lead to incorrect results.
+	"""
+	productDimensions = 1
+	for dimension in mapShape:
+		# NOTE this check is one-degree short of absurd, but three lines of early absurdity is better than invalid output later. I'd add more checks if I could think of more.
+		if dimension > sysMaxsize // productDimensions:
+			raise OverflowError(f"I received `{dimension = }` in `{mapShape = }`, but the product of the dimensions exceeds the maximum size of an integer on this system.")
+		productDimensions *= dimension
+	return productDimensions
+
+def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: int, leavesTotal: int) -> int:
+	"""
+	Determines whether to divide the computation into tasks and how many divisions.
+
+	Parameters
+	----------
+	computationDivisions: None
+		Specifies how to divide computations:
+		- `None`: no division of the computation into tasks; sets task divisions to 0.
+		- int: directly 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.
+
+	Returns
+	-------
+	taskDivisions
+		How many tasks must finish before the job can compute the total number of folds; `0` means no tasks, only job.
+
+	Raises
+	------
+	ValueError
+		If `computationDivisions` is an unsupported type or if resulting task divisions exceed total leaves.
+
+	Notes
+	-----
+	Task divisions should not exceed total leaves or the folds will be over-counted.
+	"""
+	taskDivisions = 0
+	match computationDivisions:
+		case None | 0 | False:
+			pass
+		case int() as intComputationDivisions:
+			taskDivisions = intComputationDivisions
+		case str() as strComputationDivisions:
+			strComputationDivisions = strComputationDivisions.lower()
+			match strComputationDivisions:
+				case 'maximum':
+					taskDivisions = leavesTotal
+				case 'cpu':
+					taskDivisions = min(concurrencyLimit, leavesTotal)
+				case _:
+					raise ValueError(f"I received '{strComputationDivisions}' for the parameter, `computationDivisions`, but the string value is not supported.")
+		case _:
+			raise ValueError(f"I received {computationDivisions} for the parameter, `computationDivisions`, but the type {type(computationDivisions).__name__} is not supported.")
+
+	if taskDivisions > leavesTotal:
+		raise ValueError(f"Problem: `{taskDivisions = }`, is greater than `{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 be named `computationDivisions`, `CPUlimit` , and `listDimensions` and from my dubious-quality Python code.")
+	return int(max(0, taskDivisions))
+
+def _makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int) -> ndarray[tuple[int, int, int], numpy_dtype[numpy_int64]]:
+	"""
+	Implementation of connection graph generation for map folding.
+
+	This is the internal implementation that calculates all possible connections between
+	leaves in a map folding problem based on Lunnon's algorithm. The function constructs a
+	three-dimensional array representing which leaves can be connected to each other for each
+	dimension of the map.
+
+	Parameters
+	----------
+	mapShape
+		A tuple of integers representing the dimensions of the map.
+	leavesTotal
+		The total number of leaves in the map.
+
+	Returns
+	-------
+	connectionGraph
+		A 3D NumPy array with shape (`dimensionsTotal`, `leavesTotal`+1, `leavesTotal`+1)
+		where each entry [d,i,j] represents the leaf that would be connected to leaf j
+		when inserting leaf i in dimension d.
+
+	Notes
+	-----
+	This is an implementation detail and shouldn't be called directly by external code.
+	Use `getConnectionGraph` instead, which applies proper typing.
+
+	The algorithm calculates a coordinate system first, then determines connections
+	based on parity rules, boundary conditions, and dimensional constraints.
+	"""
+	dimensionsTotal = len(mapShape)
+	cumulativeProduct = numpy.multiply.accumulate([1] + list(mapShape), dtype=numpy_int64)
+	arrayDimensions = numpy.array(mapShape, dtype=numpy_int64)
+	coordinateSystem = numpy.zeros((dimensionsTotal, leavesTotal + 1), dtype=numpy_int64)
+	for indexDimension in range(dimensionsTotal):
+		for leaf1ndex in range(1, leavesTotal + 1):
+			coordinateSystem[indexDimension, leaf1ndex] = (((leaf1ndex - 1) // cumulativeProduct[indexDimension]) % arrayDimensions[indexDimension] + 1)
+
+	connectionGraph = numpy.zeros((dimensionsTotal, leavesTotal + 1, leavesTotal + 1), dtype=numpy_int64)
+	for indexDimension in range(dimensionsTotal):
+		for activeLeaf1ndex in range(1, leavesTotal + 1):
+			for connectee1ndex in range(1, activeLeaf1ndex + 1):
+				isFirstCoord = coordinateSystem[indexDimension, connectee1ndex] == 1
+				isLastCoord = coordinateSystem[indexDimension, connectee1ndex] == arrayDimensions[indexDimension]
+				exceedsActive = connectee1ndex + cumulativeProduct[indexDimension] > activeLeaf1ndex
+				isEvenParity = (coordinateSystem[indexDimension, activeLeaf1ndex] & 1) == (coordinateSystem[indexDimension, connectee1ndex] & 1)
+
+				if (isEvenParity and isFirstCoord) or (not isEvenParity and (isLastCoord or exceedsActive)):
+					connectionGraph[indexDimension, activeLeaf1ndex, connectee1ndex] = connectee1ndex
+				elif isEvenParity and not isFirstCoord:
+					connectionGraph[indexDimension, activeLeaf1ndex, connectee1ndex] = connectee1ndex - cumulativeProduct[indexDimension]
+				elif not isEvenParity and not (isLastCoord or exceedsActive):
+					connectionGraph[indexDimension, activeLeaf1ndex, connectee1ndex] = connectee1ndex + cumulativeProduct[indexDimension]
+	return connectionGraph
+
+def getConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: type[numpyIntegerType]) -> ndarray[tuple[int, int, int], numpy_dtype[numpyIntegerType]]:
+	"""
+	Create a properly typed connection graph for the map folding algorithm.
+
+	This function serves as a typed wrapper around the internal implementation that
+	generates connection graphs. It provides the correct type information for the
+	returned array, ensuring consistency throughout the computation assembly-line.
+
+	Parameters
+	----------
+	mapShape
+		A tuple of integers representing the dimensions of the map.
+	leavesTotal
+		The total number of leaves in the map.
+	datatype
+		The NumPy integer type to use for the array elements, ensuring proper
+		memory usage and compatibility with the computation state.
+
+	Returns
+	-------
+	connectionGraph
+		A 3D NumPy array with shape (`dimensionsTotal`, `leavesTotal`+1, `leavesTotal`+1)
+		with the specified `datatype`, representing all possible connections between leaves.
+	"""
+	connectionGraph = _makeConnectionGraph(mapShape, leavesTotal)
+	connectionGraph = connectionGraph.astype(datatype)
+	return connectionGraph
+
+def makeDataContainer(shape: int | tuple[int, ...], datatype: type[numpyIntegerType]) -> ndarray[Any, numpy_dtype[numpyIntegerType]]:
+	"""
+	Create a typed NumPy array container with initialized values.
+
+	This function centralizes the creation of data containers used throughout the
+	computation assembly-line, enabling easy switching between different container types
+	or implementation strategies if needed in the future.
+
+	Parameters
+	----------
+	shape
+		Either an integer (for 1D arrays) or a tuple of integers (for multi-dimensional arrays)
+		specifying the dimensions of the array.
+	datatype
+		The NumPy integer type to use for the array elements, ensuring proper type
+		consistency and memory efficiency.
+
+	Returns
+	-------
+	container
+		A NumPy array of zeros with the specified shape and `datatype`.
+	"""
+	return numpy.zeros(shape, dtype=datatype)
+
+def outfitCountFolds(mapShape: tuple[int, ...], computationDivisions: int | str | None = None, concurrencyLimit: int = 1) -> ComputationState:
+	"""
+	Initialize a `ComputationState` with validated parameters for map folding calculation.
+
+	This function serves as the central initialization point for creating a properly
+	configured `ComputationState` object, ensuring consistent calculation of the fundamental
+	parameters (`leavesTotal` and `taskDivisions`) across the entire package.
+
+	Parameters
+	----------
+	mapShape
+		A tuple of integers representing the dimensions of the map.
+	computationDivisions: None
+		Controls how to divide the computation into parallel tasks. I know it is annoying,
+		but please see `getTaskDivisions` for details, so that you and I both know you have the most
+		accurate information.
+	concurrencyLimit: 1
+		Maximum number of concurrent processes to use during computation.
+
+	Returns
+	-------
+	computationStateInitialized
+		A fully initialized `ComputationState` object that's ready for computation.
+
+	Notes
+	-----
+	This function maintains the Single Source of Truth principle for `leavesTotal`
+	and `taskDivisions` calculation, ensuring these values are derived consistently
+	throughout the package.
+	"""
+	leavesTotal = getLeavesTotal(mapShape)
+	taskDivisions = getTaskDivisions(computationDivisions, concurrencyLimit, leavesTotal)
+	computationStateInitialized = ComputationState(mapShape, leavesTotal, taskDivisions, concurrencyLimit)
+	return computationStateInitialized
+
+def setProcessorLimit(CPUlimit: Any | None, concurrencyPackage: str | None = None) -> int:
+	"""
+	Sets processor limit for concurrent operations.
+
+	Parameters
+	----------
+	CPUlimit: None
+		Controls processor usage limits:
+		- `False`, `None`, or `0`: No limits on processor usage; uses all available processors. All other values will potentially limit processor usage.
+		- `True`: Yes, limit the processor usage; limits to 1 processor.
+		- Integer `>= 1`: Limits usage to the specified number of processors.
+		- Decimal value (`float`) between 0 and 1: Fraction of total processors to use.
+		- Decimal value (`float`) between -1 and 0: Fraction of processors to _not_ use.
+		- Integer `<= -1`: Subtract the absolute value from total processors.
+	concurrencyPackage: None
+		Specifies which concurrency package to use:
+		- `None` or `'multiprocessing'`: Uses standard `multiprocessing`.
+		- `'numba'`: Uses Numba's threading system.
+
+	Returns
+	-------
+	concurrencyLimit
+		The actual concurrency limit that was set.
+
+	Raises
+	------
+	TypeError
+		If `CPUlimit` is not of the expected types.
+	NotImplementedError
+		If `concurrencyPackage` is not supported.
+
+	Notes
+	-----
+	If using `'numba'` as the concurrency package, the maximum number of processors is
+	retrieved from `numba.get_num_threads()` rather than by polling the hardware.
+	If Numba environment variables limit available processors, that will affect this function.
+
+	When using Numba, this function must be called before importing any Numba-jitted
+	function for this processor limit to affect the Numba-jitted function.
+	"""
+	if not (CPUlimit is None or isinstance(CPUlimit, (bool, int, float))):
+		CPUlimit = oopsieKwargsie(CPUlimit)
+
+	match concurrencyPackage:
+		case 'multiprocessing' | None:
+			# When to use multiprocessing.set_start_method https://github.com/hunterhogan/mapFolding/issues/6
+			concurrencyLimit: int = defineConcurrencyLimit(CPUlimit)
+		case 'numba':
+			from numba import get_num_threads, set_num_threads
+			concurrencyLimit = defineConcurrencyLimit(CPUlimit, get_num_threads())
+			set_num_threads(concurrencyLimit)
+			concurrencyLimit = get_num_threads()
+		case _:
+			raise NotImplementedError(f"I received `{concurrencyPackage = }` but I don't know what to do with that.")
+	return concurrencyLimit
+
+def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
+	"""
+	Validate and normalize dimensions for a map folding problem.
+
+	This function serves as the gatekeeper for dimension inputs, ensuring that all
+	map dimensions provided to the package meet the requirements for valid computation.
+	It performs multiple validation steps and normalizes the dimensions into a consistent format.
+
+	Parameters
+	----------
+	listDimensions
+		A sequence of integers representing the dimensions of the map.
+
+	Returns
+	-------
+	tuple[int, ...]
+		A sorted tuple of positive integers representing the validated dimensions.
+
+	Raises
+	------
+	ValueError
+		If the input is empty or contains negative values.
+	NotImplementedError
+		If fewer than two positive dimensions are provided, as this would not
+		represent a valid map folding problem.
+	"""
+	if not listDimensions:
+		raise ValueError("`listDimensions` is a required parameter.")
+	listValidated: list[int] = intInnit(listDimensions, 'listDimensions')
+	listNonNegative: list[int] = []
+	for dimension in listValidated:
+		if dimension < 0:
+			raise ValueError(f"`{dimension = }` in `{listDimensions = }`, must be a non-negative integer.")
+		listNonNegative.append(dimension)
+	dimensionsValid = [dimension for dimension in listNonNegative if dimension > 0]
+	if len(dimensionsValid) < 2:
+		raise NotImplementedError(f"This function requires `{listDimensions = }` to have at least two dimensions greater than 0. You may want to look at https://oeis.org/.")
+	return tuple(sorted(dimensionsValid))

{mapfolding-0.8.4 → mapfolding-0.8.6}/mapFolding/oeis.py

@@ -2,25 +2,31 @@
 Interface to The Online Encyclopedia of Integer Sequences (OEIS) for map folding sequences.
 
 This module provides a comprehensive interface for accessing and utilizing integer sequences
-from the OEIS that relate to map folding problems. It implements functionality to:
+from the OEIS that relate to map folding problems. It serves as the bridge between
+mathematical sequence definitions and the computational algorithm, implementing:
 
-1. Retrieve sequence data from OEIS with local caching for performance
-2. Map sequence indices to corresponding map shapes based on sequence definitions
-3. Provide a command-line interface for sequence lookups
-4. Execute map folding computations for sequence terms not available in OEIS
+1. Retrieval of sequence data from OEIS with local caching for performance optimization.
+2. Mapping of sequence indices to corresponding map shapes based on sequence definitions.
+3. Command-line and programmatic interfaces for sequence lookups and validation.
+4. Computation of sequence terms not available in the OEIS database.
 
 The module maintains a registry of implemented OEIS sequences (A001415-A001418, A195646)
-with their metadata, known values, and functions to convert between sequence indices and
+with their metadata, known values, and conversion functions between sequence indices and
 map dimensions. This allows the package to validate results against established mathematical
-literature and extend sequences beyond their currently known terms.
+literature while also extending sequences beyond their currently known terms.
+
+Each sequence is carefully mapped to its corresponding map folding problem, enabling
+seamless integration between the mathematical definition in OEIS and the computational
+implementation in the package.
 """
 from collections.abc import Callable
 from datetime import datetime, timedelta
+from functools import cache
 from mapFolding.theSSOT import The
+from mapFolding.toolboxFilesystem import writeStringToHere
 from pathlib import Path
 from typing import Any, Final, TYPE_CHECKING
 import argparse
-import pathlib
 import random
 import sys
 import time
@@ -31,13 +37,10 @@ import warnings
 if TYPE_CHECKING:
 	from typing import TypedDict
 else:
-	TypedDict = dict
+	TypedDict = dict[Any, Any]
 
 cacheDays = 30
 
-"""
-Section: make `settingsOEIS`"""
-
 pathCache: Path = The.pathPackage / ".cache"
 
 class SettingsOEIS(TypedDict):
@@ -158,7 +161,7 @@ def _parseBFileOEIS(OEISbFile: str, oeisID: str) -> dict[int, int]:
 		OEISsequence[n] = aOFn
 	return OEISsequence
 
-def getOEISofficial(pathFilenameCache: pathlib.Path, url: str) -> None | str:
+def getOEISofficial(pathFilenameCache: Path, url: str) -> None | str:
 	tryCache: bool = False
 	if pathFilenameCache.exists():
 		fileAge: timedelta = datetime.now() - datetime.fromtimestamp(pathFilenameCache.stat().st_mtime)
@@ -174,8 +177,7 @@ def getOEISofficial(pathFilenameCache: pathlib.Path, url: str) -> None | str:
 	if not tryCache:
 		httpResponse: urllib.response.addinfourl = urllib.request.urlopen(url)
 		oeisInformation = httpResponse.read().decode('utf-8')
-		pathFilenameCache.parent.mkdir(parents=True, exist_ok=True)
-		pathFilenameCache.write_text(oeisInformation)
+		writeStringToHere(oeisInformation, pathFilenameCache)
 
 	if not oeisInformation:
 		warnings.warn(f"Failed to retrieve OEIS sequence information for {pathFilenameCache.stem}.")
@@ -186,6 +188,7 @@ 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
@@ -195,7 +198,7 @@ def getOEISidValues(oeisID: str) -> dict[int, int]:
 		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.
+		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.
@@ -259,8 +262,23 @@ def makeSettingsOEIS() -> dict[str, SettingsOEIS]:
 settingsOEIS: dict[str, SettingsOEIS] = makeSettingsOEIS()
 """All values and settings for `oeisIDsImplemented`."""
 
-"""
-Section: private functions"""
+@cache
+def makeDictionaryFoldsTotalKnown() -> dict[tuple[int, ...], int]:
+	"""Returns a dictionary mapping dimension tuples to their known folding totals."""
+	dictionaryMapDimensionsToFoldsTotalKnown: dict[tuple[int, ...], int] = {}
+
+	for settings in settingsOEIS.values():
+		sequence = settings['valuesKnown']
+
+		for n, foldingsTotal in sequence.items():
+			mapShape = settings['getMapShape'](n)
+			mapShape = tuple(sorted(mapShape))
+			dictionaryMapDimensionsToFoldsTotalKnown[mapShape] = foldingsTotal
+	return dictionaryMapDimensionsToFoldsTotalKnown
+
+def getFoldsTotalKnown(mapShape: tuple[int, ...]) -> int:
+	lookupFoldsTotal = makeDictionaryFoldsTotalKnown()
+	return lookupFoldsTotal.get(tuple(mapShape), -1)
 
 def _formatHelpText() -> str:
 	"""Format standardized help text for both CLI and interactive use."""
@@ -285,35 +303,32 @@ def _formatOEISsequenceInfo() -> str:
 		for oeisID in oeisIDsImplemented
 	)
 
-"""
-Section: public functions"""
-
 def oeisIDfor_n(oeisID: str, n: int | Any) -> int:
 	"""
-	Calculate a(n) of a sequence from "The On-Line Encyclopedia of Integer Sequences" (OEIS).
+	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.
+		sequenceValue: `a(n)` of the OEIS sequence.
 
 	Raises:
-		ValueError: If n is negative.
+		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.")
+		raise ValueError(f"I received `{n = }` in the form of `{type(n) = }`, but it must be non-negative integer in the form of `{int}`.")
 
 	mapShape: tuple[int, ...] = settingsOEIS[oeisID]['getMapShape'](n)
 
 	if n <= 1 or len(mapShape) < 2:
 		offset: int = settingsOEIS[oeisID]['offset']
 		if n < offset:
-			raise ArithmeticError(f"OEIS sequence {oeisID} is not defined at n={n}.")
+			raise ArithmeticError(f"OEIS sequence {oeisID} is not defined at {n = }.")
 		foldsTotal: int = settingsOEIS[oeisID]['valuesKnown'][n]
 		return foldsTotal
 	from mapFolding.basecamp import countFolds

{mapfolding-0.8.4 → mapfolding-0.8.6}/mapFolding/reference/hunterNumba.py

@@ -19,7 +19,7 @@ Performance considerations:
 - Incorporates lessons from multiple implementation strategies
 
 Note: This serves as a reference for manually-optimized code before the development of
-the automated transformation pipeline in the main package.
+the automated transformation assembly-line in the main package.
 """
 
 from typing import Any

{mapfolding-0.8.4 → mapfolding-0.8.6}/mapFolding/someAssemblyRequired/__init__.py

@@ -14,7 +14,7 @@ Core capabilities:
 4. Performance Optimization - Apply domain-specific optimizations for numerical computation
 5. Code Generation - Generate specialized implementations with appropriate imports and syntax
 
-The transformation pipeline supports multiple optimization targets, from general-purpose
+The transformation assembly-line supports multiple optimization targets, from general-purpose
 acceleration to generating highly-specialized variants optimized for specific input parameters.
 This multi-level transformation approach allows for both development flexibility and
 runtime performance, preserving algorithm readability in the source while enabling
@@ -27,17 +27,21 @@ particularly for numerically-intensive algorithms that benefit from just-in-time
 from mapFolding.someAssemblyRequired._theTypes import (
 	ast_expr_Slice,
 	ast_Identifier,
-	ImaAnnotationType,
 	astClassHasDOTnameNotName,
-	astClassHasDOTnameNotNameOptional,
 	astClassHasDOTtarget,
 	astClassHasDOTvalue,
+	astClassOptionallyHasDOTnameNotName,
 	astMosDef,
+	Ima_funcTypeUNEDITED,
+	Ima_targetTypeUNEDITED,
+	ImaAnnotationType,
+	ImaAnnotationTypeVar,
 	intORlist_ast_type_paramORstr_orNone,
 	intORstr_orNone,
 	list_ast_type_paramORstr_orNone,
 	str_nameDOTname,
-	typeCertified,
+	TypeCertified,
+	个,
 	)
 
 from mapFolding.someAssemblyRequired._toolboxPython import (
@@ -49,17 +53,14 @@ from mapFolding.someAssemblyRequired._toolboxPython import (
 	parsePathFilename2astModule,
 	)
 
-from mapFolding.someAssemblyRequired._toolboxAntecedents import be, ifThis, 又
+from mapFolding.someAssemblyRequired._toolboxAntecedents import be, DOT, ifThis, 又
 from mapFolding.someAssemblyRequired._tool_Make import Make
 from mapFolding.someAssemblyRequired._tool_Then import Then
 
-from mapFolding.someAssemblyRequired.transformationTools import (
-	dictionaryEstimates,
-	extractClassDef,
-	extractFunctionDef,
-	write_astModule,
-	Z0Z_executeActionUnlessDescendantMatches,
-	Z0Z_inlineThisFunctionWithTheseValues,
-	Z0Z_lameFindReplace,
-	Z0Z_makeDictionaryReplacementStatements,
-	)
+from mapFolding.someAssemblyRequired._toolboxContainers import (
+	IngredientsFunction,
+	IngredientsModule,
+	LedgerOfImports,
+	RecipeSynthesizeFlow,
+	ShatteredDataclass,
+)