mapFolding 0.7.1__py3-none-any.whl → 0.8.1__py3-none-any.whl

mapFolding/__init__.py

@@ -1,9 +1,38 @@
+"""
+Map folding enumeration and counting algorithms with optimization capabilities.
+
+This package implements algorithms to count and enumerate the various 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
+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
+- theSSOT: Single Source of Truth for configuration, types, and state management
+- oeis: Interface to the Online Encyclopedia of Integer Sequences for known results
+
+Extended functionality:
+- someAssemblyRequired: Code transformation framework that optimizes the core algorithm
+  through AST manipulation, dataclass transformation, and compilation techniques
+
+Special directories:
+- .cache/: Stores cached data from external sources like OEIS to improve performance
+- syntheticModules/: Contains dynamically generated, optimized implementations of the
+  core algorithm created by the code transformation framework
+
+This package strives to balance algorithm readability and understandability with
+high-performance computation capabilities, allowing users to compute map folding
+totals for larger dimensions than previously feasible.
+"""
 from mapFolding.basecamp import countFolds as countFolds
 from mapFolding.oeis import clearOEIScache, getOEISids, OEIS_for_n
 
 __all__ = [
-	'clearOEIScache',
-	'countFolds',
-	'getOEISids',
-	'OEIS_for_n',
+    'clearOEIScache',
+    'countFolds',
+    'getOEISids',
+    'OEIS_for_n',
 ]

mapFolding/basecamp.py

@@ -1,3 +1,17 @@
+"""
+Public API for the map folding algorithm with simplified interface.
+
+This module provides the main entry point for users of the mapFolding package,
+abstracting away the complexities of the computational algorithm. It offers
+a high-level interface to count the total number of possible ways to fold
+a rectangular map of specified dimensions, with options for customizing the
+computation process and saving results.
+
+The primary function is countFolds, which handles parameter validation,
+computation state management, dispatching to the appropriate algorithm
+implementation, and optional persistence of results.
+"""
+
 from collections.abc import Sequence
 from mapFolding.beDRY import outfitCountFolds, setCPUlimit, validateListDimensions
 from mapFolding.filesystem import getPathFilenameFoldsTotal, saveFoldsTotal

mapFolding/beDRY.py

@@ -1,30 +1,26 @@
-"""A relatively stable API for oft-needed functionality."""
-from mapFolding.theSSOT import (
-	Array3D,
-	ComputationState,
-	getDatatypePackage,
-	getNumpyDtypeDefault,
-)
+"""
+Utility functions for maintaining DRY (Don't Repeat Yourself) principles in the mapFolding package.
+
+This module provides a collection of helper functions that abstract common operations needed
+throughout the package, preventing code duplication and ensuring consistency. The functions
+manage core aspects of the computation process, including:
+
+1. Resource allocation and system limits management
+2. Data structure initialization and manipulation
+3. Parameter validation and interpretation
+4. Construction of specialized arrays and matrices for the folding algorithm
+
+The functions in this module serve as a relatively stable API for other modules to use,
+particularly for initializing computation state, validating inputs, and creating data
+structures needed by the folding algorithms.
+"""
 from collections.abc import Sequence
+from mapFolding.theSSOT import Array3D, ComputationState, getDatatypePackage, getNumpyDtypeDefault
 from sys import maxsize as sysMaxsize
 from typing import Any
 from Z0Z_tools import defineConcurrencyLimit, intInnit, oopsieKwargsie
 import numpy
 
-def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
-	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 {dimension} must be non-negative")
-		listNonNegative.append(dimension)
-	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 tuple(sorted(dimensionsValid))
-
 def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
 	productDimensions = 1
 	for dimension in mapShape:
@@ -33,7 +29,59 @@ def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
 		productDimensions *= dimension
 	return productDimensions
 
-def getNumpyDtype(datatype: type[numpy.signedinteger[Any]] | None = None) -> type[numpy.signedinteger[Any]]:
+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: 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.
+	CPUlimit
+		for error reporting.
+	listDimensions
+		for error reporting.
+
+	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
+	if not computationDivisions:
+		pass
+	elif isinstance(computationDivisions, int):
+		taskDivisions = computationDivisions
+	elif isinstance(computationDivisions, str): # type: ignore
+		# 'Unnecessary isinstance call; "str" is always an instance of "str", so sayeth Pylance'. Yeah, well "User is not always an instance of "correct input" so sayeth the programmer.
+		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.")
+	return int(max(0, taskDivisions))
+
+def interpretParameter_datatype(datatype: type[numpy.signedinteger[Any]] | None = None) -> type[numpy.signedinteger[Any]]:
 	"""An imperfect way to reduce code duplication."""
 	if 'numpy' == getDatatypePackage():
 		numpyDtype = datatype or getNumpyDtypeDefault()
@@ -42,7 +90,7 @@ def getNumpyDtype(datatype: type[numpy.signedinteger[Any]] | None = None) -> typ
 	return numpyDtype
 
 def makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: type[numpy.signedinteger[Any]] | None = None) -> Array3D:
-	numpyDtype = getNumpyDtype(datatype)
+	numpyDtype = interpretParameter_datatype(datatype)
 	dimensionsTotal = len(mapShape)
 	cumulativeProduct = numpy.multiply.accumulate([1] + list(mapShape), dtype=numpyDtype)
 	arrayDimensions = numpy.array(mapShape, dtype=numpyDtype)
@@ -69,9 +117,15 @@ def makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: t
 	return connectionGraph
 
 def makeDataContainer(shape: int | tuple[int, ...], datatype: type[numpy.signedinteger[Any]] | None = None) -> numpy.ndarray[Any, numpy.dtype[numpy.signedinteger[Any]]]:
-	numpyDtype = getNumpyDtype(datatype)
+	numpyDtype = interpretParameter_datatype(datatype)
 	return numpy.zeros(shape, dtype=numpyDtype)
 
+def outfitCountFolds(mapShape: tuple[int, ...], computationDivisions: int | str | None = None, concurrencyLimit: int = 1) -> ComputationState:
+	leavesTotal = getLeavesTotal(mapShape)
+	taskDivisions = getTaskDivisions(computationDivisions, concurrencyLimit, leavesTotal)
+	computationStateInitialized = ComputationState(mapShape, leavesTotal, taskDivisions, concurrencyLimit)
+	return computationStateInitialized
+
 def setCPUlimit(CPUlimit: Any | None) -> int:
 	"""Sets CPU limit for concurrent operations.
 
@@ -106,66 +160,23 @@ def setCPUlimit(CPUlimit: Any | None) -> int:
 		concurrencyLimit: int = defineConcurrencyLimit(CPUlimit, get_num_threads())
 		set_num_threads(concurrencyLimit)
 		concurrencyLimit = get_num_threads()
-	elif concurrencyPackage == 'algorithm':
+	elif concurrencyPackage == 'multiprocessing':
 		# When to use multiprocessing.set_start_method https://github.com/hunterhogan/mapFolding/issues/6
-		concurrencyLimit: int = defineConcurrencyLimit(CPUlimit)
+		concurrencyLimit = defineConcurrencyLimit(CPUlimit)
 	else:
 		raise NotImplementedError(f"I received {concurrencyPackage=} but I don't know what to do with that.")
 	return concurrencyLimit
 
-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: 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.
-	CPUlimit
-		for error reporting.
-	listDimensions
-		for error reporting.
-
-	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
-	if not computationDivisions:
-		pass
-	elif isinstance(computationDivisions, int):
-		taskDivisions = computationDivisions
-	elif isinstance(computationDivisions, str): # type: ignore 'Unnecessary isinstance call; "str" is always an instance of "str", so sayeth Pylance'. Yeah, well "User is not always an instance of "correct input" so sayeth the programmer.
-		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.")
-	return int(max(0, taskDivisions))
-
-def outfitCountFolds(mapShape: tuple[int, ...], computationDivisions: int | str | None = None, concurrencyLimit: int = 1) -> ComputationState:
-	leavesTotal = getLeavesTotal(mapShape)
-	taskDivisions = getTaskDivisions(computationDivisions, concurrencyLimit, leavesTotal)
-	computationStateInitialized = ComputationState(mapShape, leavesTotal, taskDivisions, concurrencyLimit)
-	return computationStateInitialized
+def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
+	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 {dimension} must be non-negative")
+		listNonNegative.append(dimension)
+	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 tuple(sorted(dimensionsValid))

mapFolding/filesystem.py

@@ -1,95 +1,129 @@
-"""Filesystem functions for mapFolding package."""
+"""
+Filesystem utilities for managing map folding computation results.
+
+This module provides functions for standardized handling of files related to the mapFolding
+package, with a focus on saving, retrieving, and naming computation results. It implements
+consistent naming conventions and path resolution strategies to ensure that:
+
+1. Computation results are stored in a predictable location
+2. Filenames follow a consistent pattern based on map dimensions
+3. Results can be reliably retrieved for future reference
+4. The system handles file operations safely with appropriate error handling
+
+The module serves as the interface between the computational components of the package
+and the filesystem, abstracting away the details of file operations and path management.
+"""
 from pathlib import Path, PurePath
 from typing import Any
+from os import PathLike
 import os
 
 def getFilenameFoldsTotal(mapShape: tuple[int, ...]) -> str:
-	"""Imagine your computer has been counting folds for 9 days, and when it tries to save your newly discovered value,
-	the filename is invalid. I bet you think this function is more important after that thought experiment.
-
-	Make a standardized filename for the computed value `foldsTotal`.
-
-	The filename takes into account
-		- the dimensions of the map, aka `mapShape`, aka `listDimensions`
-		- no spaces in the filename
-		- safe filesystem characters
-		- unique extension
-		- Python-safe strings:
-			- no starting with a number
-			- no reserved words
-			- no dashes or other special characters
-			- uh, I can't remember, but I found some other frustrating limitations
-		- if 'p' is still the first character of the filename, I picked that because it was the original identifier for the map shape in Lunnan's code
-
-	Parameters:
-		mapShape: A sequence of integers representing the dimensions of the map.
-
-	Returns:
-		filenameFoldsTotal: A filename string in format 'pMxN.foldsTotal' where M,N are sorted dimensions
-	"""
-	return 'p' + 'x'.join(str(dimension) for dimension in sorted(mapShape)) + '.foldsTotal'
-
-def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal: str | os.PathLike[str] | None = None) -> Path:
-	"""Get a standardized path and filename for the computed value `foldsTotal`.
-
-	If you provide a directory, the function will append a standardized filename. If you provide a filename
-	or a relative path and filename, the function will prepend the default path.
-
-	Parameters:
-		mapShape: List of dimensions for the map folding problem.
-		pathLikeWriteFoldsTotal (pathJobRootDEFAULT): Path, filename, or relative path and filename. If None, uses default path.
-			Defaults to None.
-
-	Returns:
-		pathFilenameFoldsTotal: Absolute path and filename.
-	"""
-	from mapFolding.theSSOT import getPathJobRootDEFAULT
-
-	if pathLikeWriteFoldsTotal is None:
-		pathFilenameFoldsTotal = getPathJobRootDEFAULT() / getFilenameFoldsTotal(mapShape)
-	else:
-		pathLikeSherpa = Path(pathLikeWriteFoldsTotal)
-		if pathLikeSherpa.is_dir():
-			pathFilenameFoldsTotal = pathLikeSherpa / getFilenameFoldsTotal(mapShape)
-		elif pathLikeSherpa.is_file() and pathLikeSherpa.is_absolute():
-			pathFilenameFoldsTotal = pathLikeSherpa
-		else:
-			pathFilenameFoldsTotal = getPathJobRootDEFAULT() / pathLikeSherpa
-
-	pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
-	return pathFilenameFoldsTotal
-
-def saveFoldsTotal(pathFilename: str | os.PathLike[str], foldsTotal: int) -> None:
-	"""
-	Save foldsTotal with multiple fallback mechanisms.
-
-	Parameters:
-		pathFilename: Target save location
-		foldsTotal: Critical computed value to save
-	"""
-	try:
-		pathFilenameFoldsTotal = Path(pathFilename)
-		pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
-		pathFilenameFoldsTotal.write_text(str(foldsTotal))
-	except Exception as ERRORmessage:
-		try:
-			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
-			print(ERRORmessage)
-			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
-			randomnessPlanB = (int(str(foldsTotal).strip()[-1]) + 1) * ['YO_']
-			filenameInfixUnique = ''.join(randomnessPlanB)
-			pathFilenamePlanB = os.path.join(os.getcwd(), 'foldsTotal' + filenameInfixUnique + '.txt')
-			writeStreamFallback = open(pathFilenamePlanB, 'w')
-			writeStreamFallback.write(str(foldsTotal))
-			writeStreamFallback.close()
-			print(str(pathFilenamePlanB))
-		except Exception:
-			print(foldsTotal)
-	return None
-
-def writeStringToHere(this: str, pathFilename: str | os.PathLike[Any] | PurePath) -> None:
-	"""Write the string `this` to the file at `pathFilename`."""
-	pathFilename = Path(pathFilename)
-	pathFilename.parent.mkdir(parents=True, exist_ok=True)
-	pathFilename.write_text(str(this))
-	return None
+    """
+    Create a standardized filename for a computed `foldsTotal` value.
+
+    This function generates a consistent, filesystem-safe filename based on map dimensions.
+    Standardizing filenames ensures that results can be reliably stored and retrieved,
+    avoiding potential filesystem incompatibilities or Python naming restrictions.
+
+    Parameters:
+        mapShape: A sequence of integers representing the dimensions of the map.
+
+    Returns:
+        filenameFoldsTotal: A filename string in format 'pMxN.foldsTotal' where M,N are sorted dimensions.
+
+    Notes:
+        The filename format ensures:
+        - No spaces in the filename
+        - Safe filesystem characters
+        - Unique extension (.foldsTotal)
+        - Python-safe strings (no starting with numbers, no reserved words)
+        - The 'p' prefix preserves compatibility with Lunnan's original code.
+    """
+    return 'p' + 'x'.join(str(dimension) for dimension in sorted(mapShape)) + '.foldsTotal'
+
+def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal: str | PathLike[str] | None = None) -> Path:
+    """
+    Get a standardized path and filename for the computed foldsTotal value.
+
+    This function resolves paths for storing computation results, handling different
+    input types including directories, absolute paths, or relative paths. It ensures
+    that all parent directories exist in the resulting path.
+
+    Parameters:
+        mapShape: List of dimensions for the map folding problem.
+        pathLikeWriteFoldsTotal (getPathJobRootDEFAULT): Path, filename, or relative path and filename.
+            If None, uses default path. If a directory, appends standardized filename.
+
+    Returns:
+        pathFilenameFoldsTotal: Absolute path and filename for storing the foldsTotal value.
+
+    Notes:
+        The function creates any necessary directories in the path if they don't exist.
+    """
+    from mapFolding.theSSOT import getPathJobRootDEFAULT
+
+    if pathLikeWriteFoldsTotal is None:
+        pathFilenameFoldsTotal = getPathJobRootDEFAULT() / getFilenameFoldsTotal(mapShape)
+    else:
+        pathLikeSherpa = Path(pathLikeWriteFoldsTotal)
+        if pathLikeSherpa.is_dir():
+            pathFilenameFoldsTotal = pathLikeSherpa / getFilenameFoldsTotal(mapShape)
+        elif pathLikeSherpa.is_file() and pathLikeSherpa.is_absolute():
+            pathFilenameFoldsTotal = pathLikeSherpa
+        else:
+            pathFilenameFoldsTotal = getPathJobRootDEFAULT() / pathLikeSherpa
+
+    pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
+    return pathFilenameFoldsTotal
+
+def saveFoldsTotal(pathFilename: str | PathLike[str], foldsTotal: int) -> None:
+    """
+    Save `foldsTotal` value to disk with multiple fallback mechanisms.
+
+    This function attempts to save the computed `foldsTotal` value to the specified
+    location, with backup strategies in case the primary save attempt fails.
+    The robustness is critical since these computations may take days to complete.
+
+    Parameters:
+        pathFilename: Target save location for the `foldsTotal` value
+        foldsTotal: The computed value to save
+
+    Notes:
+        If the primary save fails, the function will attempt alternative save methods:
+        1. Print the value prominently to stdout
+        2. Create a fallback file in the current working directory
+        3. As a last resort, simply print the value
+    """
+    try:
+        pathFilenameFoldsTotal = Path(pathFilename)
+        pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
+        pathFilenameFoldsTotal.write_text(str(foldsTotal))
+    except Exception as ERRORmessage:
+        try:
+            print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+            print(ERRORmessage)
+            print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+            randomnessPlanB = (int(str(foldsTotal).strip()[-1]) + 1) * ['YO_']
+            filenameInfixUnique = ''.join(randomnessPlanB)
+            pathFilenamePlanB = os.path.join(os.getcwd(), 'foldsTotal' + filenameInfixUnique + '.txt')
+            writeStreamFallback = open(pathFilenamePlanB, 'w')
+            writeStreamFallback.write(str(foldsTotal))
+            writeStreamFallback.close()
+            print(str(pathFilenamePlanB))
+        except Exception:
+            print(foldsTotal)
+    return None
+
+def writeStringToHere(this: str, pathFilename: str | PathLike[Any] | PurePath) -> None:
+    """
+    Write a string to a file, creating parent directories if needed.
+
+    Parameters:
+        this: The string content to write to the file
+        pathFilename: The target file path where the string should be written
+    """
+    pathFilename = Path(pathFilename)
+    pathFilename.parent.mkdir(parents=True, exist_ok=True)
+    pathFilename.write_text(str(this))
+    return None

mapFolding/noHomeYet.py

@@ -1,3 +1,15 @@
+"""
+Interface for retrieving known map folding totals from OEIS (Online Encyclopedia of Integer Sequences).
+
+This module provides utilities for accessing pre-computed map folding totals that are known
+from mathematical literature and stored in the OEIS. The functions cache results for
+performance and provide lookups based on map dimensions.
+
+The main functions are:
+- makeDictionaryFoldsTotalKnown: Creates a dictionary of known folding totals indexed by map dimensions
+- getFoldsTotalKnown: Retrieves the folding total for a specific map shape, returning -1 if unknown
+"""
+
 from functools import cache
 from mapFolding.oeis import settingsOEIS
 
@@ -11,8 +23,8 @@ def makeDictionaryFoldsTotalKnown() -> dict[tuple[int, ...], int]:
 
 		for n, foldingsTotal in sequence.items():
 			mapShape = settings['getMapShape'](n)
-			mapShape = sorted(mapShape)
-			dictionaryMapDimensionsToFoldsTotalKnown[tuple(mapShape)] = foldingsTotal
+			mapShape = tuple(sorted(mapShape))
+			dictionaryMapDimensionsToFoldsTotalKnown[mapShape] = foldingsTotal
 	return dictionaryMapDimensionsToFoldsTotalKnown
 
 def getFoldsTotalKnown(mapShape: tuple[int, ...]) -> int:

mapFolding/oeis.py

@@ -1,4 +1,19 @@
-"""Everything implementing the The Online Encyclopedia of Integer Sequences (OEIS); _only_ things that implement _only_ the OEIS."""
+"""
+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:
+
+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
+
+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
+map dimensions. This allows the package to validate results against established mathematical
+literature and extend sequences beyond their currently known terms.
+"""
 from collections.abc import Callable
 from datetime import datetime, timedelta
 from mapFolding.theSSOT import thePathPackage
@@ -144,10 +159,10 @@ def _parseBFileOEIS(OEISbFile: str, oeisID: str) -> dict[int, int]:
 	return OEISsequence
 
 def getOEISofficial(pathFilenameCache: pathlib.Path, url: str) -> None | str:
-	tryCache = False
+	tryCache: bool = False
 	if pathFilenameCache.exists():
 		fileAge: timedelta = datetime.now() - datetime.fromtimestamp(pathFilenameCache.stat().st_mtime)
-		tryCache: bool = fileAge < timedelta(days=cacheDays)
+		tryCache = fileAge < timedelta(days=cacheDays)
 
 	oeisInformation: str | None = None
 	if tryCache: