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

mapFolding/__init__.py

@@ -1,20 +1,44 @@
-from typing import Any, TypeAlias
-import sys
-
-yourPythonIsOld: TypeAlias = Any
-# ruff: noqa: E402
-
-if sys.version_info >= (3, 11):
-	from typing import TypedDict as TypedDict
-	from typing import NotRequired as NotRequired
-else:
-	try:
-		from typing_extensions import TypedDict as TypedDict
-		from typing_extensions import NotRequired as NotRequired
-	except Exception:
-		TypedDict = dict[yourPythonIsOld, yourPythonIsOld]
-		from collections.abc import Iterable
-		NotRequired: TypeAlias = Iterable
+"""Computational toolkit for analyzing multi-dimensional map folding patterns.
+
+The mapFolding package provides a complete implementation of Lunnon's 1971 algorithm
+for counting distinct folding patterns in multi-dimensional maps. This toolkit
+transforms the complex combinatorial mathematics of map folding into accessible
+computational tools, enabling researchers and practitioners to analyze folding
+patterns across dimensions from simple 2D strips to complex multi-dimensional
+hypercubes.
+
+The package architecture follows Domain-Driven Design principles, organizing
+functionality around mathematical concepts rather than implementation details.
+The computational framework integrates type safety, persistent result storage,
+and mathematical validation through OEIS sequence integration.
+
+Core Transformation Tools:
+    countFolds: Primary interface for computing folding pattern counts
+    MapFoldingState: Computational state management for recursive analysis
+    Connection graph generation: Mathematical foundation for folding relationships
+    Task division utilities: Experimental parallel computation options
+    OEIS integration: Mathematical validation and sequence discovery
+
+Primary Use Cases:
+    Mathematical research into folding pattern properties and relationships
+    Educational exploration of combinatorial mathematics concepts
+    Computational validation of theoretical results
+    Extension of known mathematical sequences through new discoveries
+
+The package handles the full spectrum of map folding analysis, from simple
+educational examples to research-grade computations requiring multi-day processing
+time. Results integrate seamlessly with the mathematical community through
+comprehensive OEIS connectivity and standardized result persistence.
+
+For researchers: The computational foundation supports both replication of
+established results and discovery of new mathematical relationships.
+
+For educators: The clear interfaces and type safety enable confident exploration
+of combinatorial concepts without computational complexity barriers.
+
+For practitioners: The robust result persistence and type safety ensure
+reliable completion of complex analytical tasks.
+"""
 
 from mapFolding.datatypes import (
 	Array1DElephino as Array1DElephino,
@@ -30,7 +54,7 @@ from mapFolding.datatypes import (
 	NumPyLeavesTotal as NumPyLeavesTotal,
 )
 
-from mapFolding.theSSOT import PackageSettings as PackageSettings, packageSettings as packageSettings
+from mapFolding._theSSOT import PackageSettings as PackageSettings, packageSettings as packageSettings
 
 from mapFolding.beDRY import (
 	getConnectionGraph as getConnectionGraph,

mapFolding/_theSSOT.py

@@ -0,0 +1,137 @@
+"""
+Foundation layer for the map folding computational ecosystem.
+
+This module establishes the fundamental configuration infrastructure that underpins
+all map folding operations. Map folding, as defined by Lunnon's 1971 algorithm,
+requires precise coordination of computational resources, type systems, and data
+flow management to solve the complex combinatorial problem of counting distinct
+folding patterns across multi-dimensional maps.
+
+The Single Source Of Truth (SSOT) principle governs this foundation, ensuring that
+package identity, filesystem locations, and concurrency configuration remain
+consistent across all computational phases. During packaging, static metadata is
+resolved from pyproject.toml. During installation, filesystem-dependent paths are
+dynamically discovered. During runtime, the `packageSettings` instance provides
+unified access to all configuration values, enabling the sophisticated computational
+framework that follows.
+
+This configuration foundation supports the type system definition, core utility
+functions, computational state management, result persistence, and ultimately the
+main computational interface that users interact with to solve map folding problems.
+"""
+
+from importlib import import_module as importlib_import_module
+from inspect import getfile as inspect_getfile
+from pathlib import Path
+from tomli import load as tomli_load
+import dataclasses
+
+packageNamePACKAGING_HARDCODED = "mapFolding"
+"""
+Hardcoded package name used as fallback when dynamic resolution fails.
+
+This constant serves as the ultimate fallback for package name resolution,
+ensuring the package can function even when pyproject.toml is not accessible
+during packaging or when module introspection fails during installation.
+"""
+
+concurrencyPackageHARDCODED = 'multiprocessing'
+"""
+Default package identifier for concurrent execution operations.
+
+Specifies which Python concurrency package should be used as the default
+for parallel computations. This can be overridden through PackageSettings
+to use alternative packages like 'numba' for specialized performance scenarios.
+"""
+
+# Evaluate When Packaging
+# https://github.com/hunterhogan/mapFolding/issues/18
+try:
+	packageNamePACKAGING: str = tomli_load(Path("../pyproject.toml").open('rb'))["project"]["name"]
+	"""
+	Package name dynamically resolved from pyproject.toml during packaging.
+
+	This value is determined by reading the project configuration file during
+	the packaging process, ensuring consistency between the package metadata
+	and runtime identification. Falls back to hardcoded value if resolution fails.
+	"""
+except Exception:
+	packageNamePACKAGING = packageNamePACKAGING_HARDCODED
+
+# Evaluate When Installing
+# https://github.com/hunterhogan/mapFolding/issues/18
+def getPathPackageINSTALLING() -> Path:
+	"""
+	Resolve the absolute filesystem path to the installed package directory.
+
+	This function determines the package location at runtime by introspecting
+	the imported module's file location. It handles both regular Python files
+	and package directories, ensuring reliable path resolution across different
+	installation methods and environments.
+
+	Returns:
+		pathPackage: Absolute path to the package directory containing the module files.
+
+	Notes:
+		The function automatically handles the case where module introspection
+		returns a file path by extracting the parent directory, ensuring the
+		returned path always points to the package directory itself.
+	"""
+	pathPackage: Path = Path(inspect_getfile(importlib_import_module(packageNamePACKAGING)))
+	if pathPackage.is_file():
+		pathPackage = pathPackage.parent
+	return pathPackage
+
+@dataclasses.dataclass
+class PackageSettings:
+	"""
+	Centralized configuration container for all package-wide settings.
+
+	This dataclass serves as the single source of truth for package configuration,
+	providing both static and dynamically-resolved values needed throughout the
+	package lifecycle. The metadata on each field indicates when that value is
+	determined - either during packaging or at installation/runtime.
+
+	The design supports different evaluation phases to optimize performance and
+	reliability:
+	- Packaging-time: Values that can be determined during package creation
+	- Installing-time: Values that require filesystem access or module introspection
+
+	Attributes:
+		fileExtension: Standard file extension for Python modules in this package.
+		packageName: Canonical name of the package as defined in project configuration.
+		pathPackage: Absolute filesystem path to the installed package directory.
+		concurrencyPackage: Package to use for concurrent execution operations.
+	"""
+	fileExtension: str = dataclasses.field(default='.py', metadata={'evaluateWhen': 'installing'})
+	packageName: str = dataclasses.field(default = packageNamePACKAGING, metadata={'evaluateWhen': 'packaging'})
+	pathPackage: Path = dataclasses.field(default_factory=getPathPackageINSTALLING, metadata={'evaluateWhen': 'installing'})
+	concurrencyPackage: str | None = None
+	"""
+	Package identifier for concurrent execution operations.
+
+	Specifies which Python package should be used for parallel processing
+	in computationally intensive operations. When None, the default concurrency
+	package specified in the module constants is used. Accepted values include
+	'multiprocessing' for standard parallel processing and 'numba' for
+	specialized numerical computations.
+	"""
+
+concurrencyPackage = concurrencyPackageHARDCODED
+"""
+Active concurrency package configuration for the current session.
+
+This module-level variable holds the currently selected concurrency package
+identifier, initialized from the hardcoded default but available for runtime
+modification through the package settings system.
+"""
+
+packageSettings = PackageSettings(concurrencyPackage=concurrencyPackage)
+"""
+Global package settings instance providing access to all configuration values.
+
+This singleton instance serves as the primary interface for accessing package
+configuration throughout the codebase. It combines statically-defined defaults
+with dynamically-resolved values to provide a complete configuration profile
+for the current package installation and runtime environment.
+"""

mapFolding/basecamp.py

@@ -1,22 +1,30 @@
 """
-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.
+Unified interface for map folding computation orchestration.
+
+This module represents the culmination of the computational ecosystem, providing
+the primary entry point where users interact with the complete map folding analysis
+system. It orchestrates all preceding layers: the configuration foundation,
+type system, core utilities, state management, and persistent storage to deliver
+a seamless computational experience.
+
+The interface handles multiple computation flows including sequential algorithms,
+experimental task division strategies, and various mathematical theorem implementations.
+It provides flexible parameter validation, computation method selection, task
+division management, processor utilization control, and automatic result persistence.
+Integration with OEIS sequences enables research validation and mathematical
+verification of computed results.
+
+Through this unified interface, researchers and practitioners can access the full
+power of Lunnon's algorithm implementation while the underlying computational
+complexity remains elegantly abstracted. The interface ensures that whether
+solving simple 2D problems or complex multi-dimensional challenges, users receive
+consistent, reliable, and efficiently computed folding pattern counts.
 """
 
 from collections.abc import Sequence
 from mapFolding import (
-	getPathFilenameFoldsTotal,
-	packageSettings,
-	saveFoldsTotal,
-	saveFoldsTotalFAILearly,
-	setProcessorLimit,
-	validateListDimensions,
+	getPathFilenameFoldsTotal, packageSettings, saveFoldsTotal, saveFoldsTotalFAILearly,
+	setProcessorLimit, validateListDimensions,
 )
 from os import PathLike
 from pathlib import PurePath
@@ -129,7 +137,7 @@ def countFolds(listDimensions: Sequence[int] | None = None
 		mapFoldingState = doTheNeedful(mapFoldingState)
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif flow == 'theorem2' and any((dimension > 2 for dimension in mapShape)):
+	elif flow == 'theorem2' and any(dimension > 2 for dimension in mapShape):
 		from mapFolding.dataBaskets import MapFoldingState
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
@@ -141,7 +149,7 @@ def countFolds(listDimensions: Sequence[int] | None = None
 
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif flow == 'theorem2Trimmed' and any((dimension > 2 for dimension in mapShape)):
+	elif flow == 'theorem2Trimmed' and any(dimension > 2 for dimension in mapShape):
 		from mapFolding.dataBaskets import MapFoldingState
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
@@ -153,7 +161,7 @@ def countFolds(listDimensions: Sequence[int] | None = None
 
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif (flow == 'theorem2Numba' or taskDivisions == 0) and any((dimension > 2 for dimension in mapShape)):
+	elif (flow == 'theorem2Numba' or taskDivisions == 0) and any(dimension > 2 for dimension in mapShape):
 		from mapFolding.dataBaskets import MapFoldingState
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
@@ -170,7 +178,9 @@ def countFolds(listDimensions: Sequence[int] | None = None
 		parallelMapFoldingState: ParallelMapFoldingState = ParallelMapFoldingState(mapShape, taskDivisions=taskDivisions)
 
 		from mapFolding.syntheticModules.countParallel import doTheNeedful
-		foldsTotal, listStatesParallel = doTheNeedful(parallelMapFoldingState, concurrencyLimit)
+
+		# `listStatesParallel` exists in case you want to research the parallel computation.
+		foldsTotal, listStatesParallel = doTheNeedful(parallelMapFoldingState, concurrencyLimit) # pyright: ignore[reportUnusedVariable]
 
 	else:
 		from mapFolding.dataBaskets import MapFoldingState

mapFolding/beDRY.py

@@ -1,30 +1,32 @@
 """
-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.
+Core computational utilities implementing Lunnon's map folding algorithm.
+
+With the configuration foundation established and the type system defined, this
+module provides the essential building blocks that transform mathematical theory
+into executable computation. These utilities implement the fundamental operations
+required by Lunnon's 1971 algorithm, handling dimension validation, connection
+graph generation, and computational resource management.
+
+The connection graph generation represents the mathematical heart of the algorithm,
+calculating how leaves connect across dimensions using coordinate systems, parity
+rules, and boundary conditions. This graph becomes the foundation upon which the
+recursive folding analysis operates. Validation functions ensure computational
+of large-scale problems. Validation functions ensure computational
+integrity, while task division management enables experimental task division strategies.
+
+These utilities follow DRY and SSOT principles, providing reusable functions that
+serve as the computational assembly-line components. They prepare the essential
+data structures and computational parameters that the state management system
+requires to orchestrate the complex recursive algorithms.
 """
+
 from collections.abc import Sequence
-from mapFolding import Array1DElephino, Array1DFoldsTotal, Array1DLeavesTotal, Array3D, DatatypeElephino, DatatypeFoldsTotal, DatatypeLeavesTotal, NumPyIntegerType
+from mapFolding import 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
-import dataclasses
 
 def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
 	"""

mapFolding/dataBaskets.py

@@ -1,18 +1,72 @@
+"""
+Computational state orchestration for map folding analysis.
+
+Building upon the core utilities and their generated data structures, this module
+orchestrates the complex computational state required for Lunnon's recursive
+algorithm execution. The state classes serve as both data containers and computational
+interfaces, managing the intricate arrays, indices, and control structures that
+guide the folding pattern discovery process.
+
+Each state class encapsulates a specific computational scenario: sequential processing
+for standard analysis, experimental task division for research applications, and specialized
+leaf sequence tracking for mathematical exploration. The automatic initialization
+integrates seamlessly with the type system and core utilities, ensuring proper
+array allocation and connection graph integration.
+
+These state management classes bridge the gap between the foundational computational
+building blocks and the persistent storage system. They maintain computational
+integrity throughout the recursive analysis while providing the structured data
+access patterns that enable efficient result persistence and retrieval.
+"""
 from mapFolding import (
-	Array1DElephino,
-	Array1DLeavesTotal,
-	Array3D,
-	DatatypeElephino,
-	DatatypeFoldsTotal,
-	DatatypeLeavesTotal,
-	getConnectionGraph,
-	getLeavesTotal,
-	makeDataContainer,
+	Array1DElephino, Array1DLeavesTotal, Array3D, DatatypeElephino, DatatypeFoldsTotal,
+	DatatypeLeavesTotal, getConnectionGraph, getLeavesTotal, makeDataContainer,
 )
 import dataclasses
 
 @dataclasses.dataclass
 class MapFoldingState:
+	"""
+	Core computational state for map folding algorithms.
+
+	This class encapsulates all data needed to perform map folding computations,
+	from the basic map dimensions through the complex internal arrays needed
+	for efficient algorithmic processing. It serves as both a data container
+	and a computational interface, providing properties and methods that
+	abstract the underlying complexity.
+
+	The class handles automatic initialization of all computational arrays
+	based on the map dimensions, ensuring consistent sizing and type usage
+	throughout the computation. It also manages the relationship between
+	different data domains (leaves, elephino, folds) defined in the type system.
+
+	Key Design Features:
+	- Automatic array sizing based on map dimensions
+	- Type-safe access to computational data
+	- Lazy initialization of expensive arrays
+	- Integration with NumPy for performance
+	- Metadata preservation for code generation
+
+	Attributes:
+		mapShape: Dimensions of the map being analyzed for folding patterns.
+		groupsOfFolds: Current count of distinct folding pattern groups discovered.
+		gap1ndex: Current position in gap enumeration algorithms.
+		gap1ndexCeiling: Upper bound for gap enumeration operations.
+		indexDimension: Current dimension being processed in multi-dimensional algorithms.
+		indexLeaf: Current leaf being processed in sequential algorithms.
+		indexMiniGap: Current position within a gap subdivision.
+		leaf1ndex: One-based leaf index for algorithmic compatibility.
+		leafConnectee: Target leaf for connection operations.
+		dimensionsUnconstrained: Count of dimensions not subject to folding constraints.
+		countDimensionsGapped: Array tracking gap counts across dimensions.
+		gapRangeStart: Array of starting positions for gap ranges.
+		gapsWhere: Array indicating locations of gaps in the folding pattern.
+		leafAbove: Array mapping each leaf to the leaf above it in the folding.
+		leafBelow: Array mapping each leaf to the leaf below it in the folding.
+		connectionGraph: Three-dimensional representation of leaf connectivity.
+		dimensionsTotal: Total number of dimensions in the map.
+		leavesTotal: Total number of individual leaves in the map.
+	"""
 	mapShape: tuple[DatatypeLeavesTotal, ...] = dataclasses.field(init=True, metadata={'elementConstructor': 'DatatypeLeavesTotal'})
 
 	groupsOfFolds: DatatypeFoldsTotal = dataclasses.field(default=DatatypeFoldsTotal(0), metadata={'theCountingIdentifier': True})
@@ -36,13 +90,37 @@ class MapFoldingState:
 	connectionGraph: Array3D = dataclasses.field(init=False, metadata={'dtype': Array3D.__args__[1].__args__[0]}) # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
 	dimensionsTotal: DatatypeLeavesTotal = dataclasses.field(init=False)
 	leavesTotal: DatatypeLeavesTotal = dataclasses.field(init=False)
-
 	@property
 	def foldsTotal(self) -> DatatypeFoldsTotal:
+		"""
+		Calculate the total number of possible folding patterns for this map.
+
+		Returns:
+			totalFoldingPatterns: The complete count of distinct folding patterns
+				achievable with the current map configuration.
+
+		Notes:
+			This represents the fundamental result of map folding analysis - the total
+			number of unique ways a map can be folded given its dimensional constraints.
+		"""
 		_foldsTotal = DatatypeFoldsTotal(self.leavesTotal) * self.groupsOfFolds
 		return _foldsTotal
 
 	def __post_init__(self) -> None:
+		"""
+		Initialize all computational arrays and derived values after dataclass construction.
+
+		This method performs the expensive operations needed to prepare the state
+		for computation, including array allocation, dimension calculation, and
+		connection graph generation. It runs automatically after the dataclass
+		constructor completes.
+
+		Notes:
+			Arrays that are not explicitly provided (None) are automatically
+			allocated with appropriate sizes based on the map dimensions.
+			The connection graph is always regenerated to ensure consistency
+			with the provided map shape.
+		"""
 		self.dimensionsTotal = DatatypeLeavesTotal(len(self.mapShape))
 		self.leavesTotal = DatatypeLeavesTotal(getLeavesTotal(self.mapShape))
 
@@ -50,31 +128,105 @@ class MapFoldingState:
 
 		self.connectionGraph = getConnectionGraph(self.mapShape, leavesTotalAsInt, self.__dataclass_fields__['connectionGraph'].metadata['dtype'])
 
-		if self.dimensionsUnconstrained is None: self.dimensionsUnconstrained = DatatypeLeavesTotal(int(self.dimensionsTotal)) # pyright: ignore[reportUnnecessaryComparison]
-		if self.gapsWhere is None: self.gapsWhere = makeDataContainer(leavesTotalAsInt * leavesTotalAsInt + 1, self.__dataclass_fields__['gapsWhere'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
-		if self.countDimensionsGapped is None: self.countDimensionsGapped = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['countDimensionsGapped'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
-		if self.gapRangeStart is None: self.gapRangeStart = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['gapRangeStart'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
-		if self.leafAbove is None: self.leafAbove = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafAbove'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
-		if self.leafBelow is None: self.leafBelow = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafBelow'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]
+		if self.dimensionsUnconstrained is None: self.dimensionsUnconstrained = DatatypeLeavesTotal(int(self.dimensionsTotal)) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
+		if self.gapsWhere is None: self.gapsWhere = makeDataContainer(leavesTotalAsInt * leavesTotalAsInt + 1, self.__dataclass_fields__['gapsWhere'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
+		if self.countDimensionsGapped is None: self.countDimensionsGapped = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['countDimensionsGapped'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
+		if self.gapRangeStart is None: self.gapRangeStart = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['gapRangeStart'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
+		if self.leafAbove is None: self.leafAbove = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafAbove'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
+		if self.leafBelow is None: self.leafBelow = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafBelow'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
 
 @dataclasses.dataclass
 class ParallelMapFoldingState(MapFoldingState):
+	"""
+	Experimental computational state for task division operations.
+
+	This class extends the base MapFoldingState with additional attributes
+	needed for experimental task division of map folding computations. It manages
+	task division state while inheriting all the core computational arrays and
+	properties from the base class.
+
+	The task division model attempts to divide the total computation space into
+	discrete tasks that can be processed independently, then combined to
+	produce the final result. However, the map folding problem is inherently
+	sequential and task division typically results in significant computational
+	overhead due to work overlap between tasks.
+
+	Attributes:
+		taskDivisions: Number of tasks into which the computation is divided.
+		taskIndex: Current task identifier when processing in task division mode.
+	"""
 	taskDivisions: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
-	"""Number of tasks into which to divide the computation. If the value is greater than `leavesTotal`, the computation will be wrong. Default is `leavesTotal`."""
+	"""
+	Number of tasks into which to divide the computation.
+
+	If this value exceeds `leavesTotal`, the computation will produce incorrect
+	results. When set to 0 (default), the value is automatically set to
+	`leavesTotal` during initialization, providing optimal task granularity.
+	"""
 
 	taskIndex: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
-	"""Index of the current task when using task divisions."""
+	"""
+	Index of the current task when using task divisions.
+
+	This value identifies which specific task is being processed in the
+	parallel computation. It ranges from 0 to `taskDivisions - 1` and
+	determines which portion of the total computation space this instance
+	is responsible for analyzing.
+	"""
 
 	def __post_init__(self) -> None:
+		"""
+		Initialize parallel-specific state after base initialization.
+		This method calls the parent initialization to set up all base
+		computational arrays, then configures the task division
+		parameters. If `taskDivisions` is 0, it automatically sets the
+		value to `leavesTotal` for optimal parallelization.
+		"""
 		super().__post_init__()
 		if self.taskDivisions == 0:
 			self.taskDivisions = DatatypeLeavesTotal(int(self.leavesTotal))
 
 @dataclasses.dataclass
 class LeafSequenceState(MapFoldingState):
+	"""
+	Specialized computational state for tracking leaf sequences during analysis.
+
+	This class extends the base MapFoldingState with additional capability
+	for recording and analyzing the sequence of leaf connections discovered
+	during map folding computations. It integrates with the OEIS (Online
+	Encyclopedia of Integer Sequences) system to leverage known sequence
+	data for optimization and validation.
+
+	The leaf sequence tracking is particularly valuable for research and
+	verification purposes, allowing detailed analysis of how folding patterns
+	emerge and enabling comparison with established mathematical sequences.
+
+	Attributes:
+		leafSequence: Array storing the sequence of leaf connections discovered.
+	"""
 	leafSequence: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""
+	Array storing the sequence of leaf connections discovered during computation.
+
+	This array records the order in which leaf connections are established
+	during the folding analysis. The sequence provides insights into the
+	algorithmic progression and can be compared against known mathematical
+	sequences for validation and optimization purposes.
+	"""
 
 	def __post_init__(self) -> None:
+		"""
+		Initialize sequence tracking arrays with OEIS integration.
+
+		This method performs base initialization then sets up the leaf sequence
+		tracking array. It queries the OEIS system for known fold totals
+		corresponding to the current map shape, using this information to
+		optimally size the sequence tracking array.
+
+		Notes:
+			The sequence array is automatically initialized to record the starting
+			leaf connection, providing a foundation for subsequent sequence tracking.
+		"""
 		super().__post_init__()
 		from mapFolding.oeis import getFoldsTotalKnown
 		groupsOfFoldsKnown = getFoldsTotalKnown(self.mapShape) // self.leavesTotal