mapFolding 0.12.0__py3-none-any.whl → 0.12.2__py3-none-any.whl

mapFolding/datatypes.py

@@ -1,18 +1,126 @@
-from numpy import dtype, uint8 as numpy_uint8, uint16 as numpy_uint16, uint64 as numpy_uint64, integer, ndarray
+"""
+Type system architecture for map folding computational domains.
+
+Building upon the configuration foundation, this module defines the complete type
+hierarchy that ensures type safety and semantic clarity throughout the map folding
+computational framework. The type system recognizes three distinct computational
+domains, each with specific data characteristics and performance requirements
+that emerge from Lunnon's algorithm implementation.
+
+The Leaves domain handles map sections, their indices, and dimensional parameters.
+The Elephino domain manages internal computational state, gap calculations, and
+temporary indices used during the recursive folding analysis. The Folds domain
+represents final pattern counts and computation results. Each domain employs both
+Python types for general computation and NumPy types for performance-critical
+array operations.
+
+This dual-type strategy enables the core utility functions to operate with type
+safety while maintaining the computational efficiency required for analyzing
+complex multi-dimensional folding patterns. The array types built from these
+base types provide the structured data containers that computational state
+management depends upon.
+"""
+from numpy import (
+	dtype, integer, ndarray, uint8 as numpy_uint8, uint16 as numpy_uint16, uint64 as numpy_uint64,
+)
 from typing import Any, TypeAlias, TypeVar
 
 NumPyIntegerType = TypeVar('NumPyIntegerType', bound=integer[Any], covariant=True)
+"""
+Generic type variable for NumPy integer types used in computational operations.
+
+This type variable enables generic programming with NumPy integer types while
+maintaining type safety. It supports covariant relationships between different
+NumPy integer types and their array containers.
+"""
 
 DatatypeLeavesTotal: TypeAlias = int
+"""
+Python type for leaf-related counts and indices in map folding computations.
+
+Represents quantities related to individual map sections (leaves), including
+total leaf counts, leaf indices, and dimensional parameters. Uses standard
+Python integers for compatibility with general computations while enabling
+conversion to NumPy types when performance optimization is needed.
+"""
+
 NumPyLeavesTotal: TypeAlias = numpy_uint8
+"""
+NumPy type for efficient leaf-related computations and array operations.
+
+Corresponds to `DatatypeLeavesTotal` but optimized for NumPy operations.
+Uses 8-bit unsigned integers since leaf counts in practical map folding
+scenarios typically remain small (under 256).
+"""
 
 DatatypeElephino: TypeAlias = int
+"""
+Python type for internal computational indices and intermediate values.
+
+Used for temporary variables, gap indices, and other internal computational
+state that doesn't directly correspond to leaves or final fold counts. The
+name follows the package convention for internal computational domains.
+"""
+
 NumPyElephino: TypeAlias = numpy_uint16
+"""
+NumPy type for internal computational operations requiring moderate value ranges.
+
+Corresponds to `DatatypeElephino` with 16-bit unsigned integer storage,
+providing sufficient range for internal computations while maintaining
+memory efficiency in array operations.
+"""
 
 DatatypeFoldsTotal: TypeAlias = int
+"""
+Python type for final fold counts and pattern totals.
+
+Represents the ultimate results of map folding computations - the total number
+of distinct folding patterns possible for a given map configuration. These
+values can grow exponentially with map size, requiring flexible integer types.
+"""
+
 NumPyFoldsTotal: TypeAlias = numpy_uint64
+"""
+NumPy type for large fold count computations and high-precision results.
+
+Corresponds to `DatatypeFoldsTotal` using 64-bit unsigned integers to
+accommodate the exponentially large values that can result from map folding
+computations on even moderately-sized maps.
+"""
 
 Array3D: TypeAlias = ndarray[tuple[int, int, int], dtype[NumPyLeavesTotal]]
+"""
+Three-dimensional NumPy array type for connection graph representations.
+
+Used to store the connectivity relationships between map leaves in a
+3D array structure. The array uses `NumPyLeavesTotal` element type since
+the stored values represent leaf indices and connection states.
+"""
+
 Array1DLeavesTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyLeavesTotal]]
+"""
+One-dimensional NumPy array type for leaf-related data sequences.
+
+Stores sequences of leaf counts, indices, or related values in efficient
+array format. Common uses include leaf sequences, gap locations, and
+dimensional data where each element relates to the leaves domain.
+"""
+
 Array1DElephino: TypeAlias = ndarray[tuple[int], dtype[NumPyElephino]]
+"""
+One-dimensional NumPy array type for internal computational sequences.
+
+Used for storing sequences of internal computational values such as
+gap range starts, temporary indices, and other intermediate results
+that require the elephino computational domain's value range.
+"""
+
 Array1DFoldsTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyFoldsTotal]]
+"""
+One-dimensional NumPy array type for sequences of fold count results.
+
+Stores sequences of fold totals and pattern counts, using the large
+integer type to accommodate the potentially enormous values that
+result from complex map folding computations.
+"""

mapFolding/filesystemToolkit.py

@@ -1,26 +1,24 @@
 """
-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 standardized interface between the computational components of the package and the filesystem,
-abstracting away the details of file operations and path management. It provides robust fallback mechanisms to preserve
-computation results even in the face of filesystem errors, which is critical for long-running computations that may take
-days to complete.
-
-The functions here adhere to a consistent approach to path handling:
-- Cross-platform compatibility through the use of `pathlib`.
-- Default locations determined intelligently based on the runtime environment.
-- Progressive fallback strategies for saving critical computation results.
-- Preemptive filesystem validation to detect issues before computation begins.
+Persistent storage infrastructure for map folding computation results.
+
+As computational state management orchestrates the complex recursive analysis,
+this module ensures that the valuable results of potentially multi-day computations
+are safely preserved and reliably retrievable. Map folding problems can require
+extensive computational time, making robust result persistence critical for
+practical research and application.
+
+The storage system provides standardized filename generation, platform-independent
+path resolution, and multiple fallback strategies to prevent data loss. Special
+attention is given to environments like Google Colab and cross-platform deployment
+scenarios. The storage patterns integrate with the configuration foundation to
+provide consistent behavior across different installation contexts.
+
+This persistence layer serves as the crucial bridge between the computational
+framework and the user interface, ensuring that computation results are available
+for the main interface to retrieve, validate, and present to users seeking
+solutions to their map folding challenges.
 """
+
 from mapFolding import packageSettings
 from os import PathLike
 from pathlib import Path, PurePath
@@ -58,10 +56,9 @@ def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal
 
 	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
+		mapShape: A sequence of integers representing the map dimensions.
+		pathLikeWriteFoldsTotal (getPathRootJobDEFAULT): Path, filename, or relative path and filename. If None, uses
 			default path. If a directory, appends standardized filename.
 
 	Returns:
@@ -109,11 +106,19 @@ def getPathRootJobDEFAULT() -> Path:
 
 def _saveFoldsTotal(pathFilename: PathLike[str] | PurePath, foldsTotal: int) -> None:
 	"""
-	Standardized function to save a `foldsTotal` value to a file.
+	Internal function to save a `foldsTotal` value to a file.
+
+	This function provides the core file writing functionality used by the public `saveFoldsTotal` function. It handles
+	the basic operations of creating parent directories and writing the integer value as text to the specified file
+	location.
 
 	Parameters:
-		pathFilename: Path where the `foldsTotal` value should be saved
-		foldsTotal: The integer value to save
+		pathFilename: Path where the `foldsTotal` value should be saved.
+		foldsTotal: The integer value to save.
+
+	Notes:
+		This is an internal function that doesn't include error handling or fallback mechanisms. Use `saveFoldsTotal`
+		for production code that requires robust error handling.
 	"""
 	pathFilenameFoldsTotal = Path(pathFilename)
 	pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
@@ -125,16 +130,16 @@ def saveFoldsTotal(pathFilename: PathLike[str] | PurePath, foldsTotal: int) -> N
 
 	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
-
+		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.
+
+		The fallback filename includes a unique identifier based on the value itself to prevent conflicts.
 	"""
 	try:
 		_saveFoldsTotal(pathFilename, foldsTotal)
@@ -172,10 +177,10 @@ def saveFoldsTotalFAILearly(pathFilename: PathLike[str] | PurePath) -> None:
 	Raises:
 		FileExistsError: If the target file already exists.
 		FileNotFoundError: If parent directories don't exist or if write tests fail.
-
 	Notes:
 		This function helps prevent a situation where a computation runs for hours or days only to discover at the end
-		that results cannot be saved.
+		that results cannot be saved. The test value used is a large integer that exercises both the writing and
+		reading mechanisms thoroughly.
 	"""
 	if Path(pathFilename).exists():
 		raise FileExistsError(f"`{pathFilename = }` exists: a battle of overwriting might cause tears.")