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

mapFolding/beDRY.py

@@ -1,45 +1,50 @@
 """
-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.
+
+(AI generated docstring)
+
+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 hunterMakesPy import defineConcurrencyLimit, intInnit, oopsieKwargsie
+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:
-	"""
-	Calculate the total number of leaves in a map with the given dimensions.
+	"""Calculate the total number of leaves in a map with the given dimensions.
+
+	(AI generated docstring)
 
 	The total number of leaves is the product of all dimensions in the map shape.
 
 	Parameters
 	----------
-	mapShape
+	mapShape : tuple[int, ...]
 		A tuple of integers representing the dimensions of the map.
 
 	Returns
 	-------
-	leavesTotal
+	leavesTotal : int
 		The total number of leaves in the map, calculated as the product of all dimensions.
 
 	Raises
@@ -47,31 +52,36 @@ def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
 	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.")
+			message = f"I received `{dimension = }` in `{mapShape = }`, but the product of the dimensions exceeds the maximum size of an integer on this system."
+			raise OverflowError(message)
 		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.
+	"""Determine whether to divide the computation into tasks and how many divisions.
+
+	(AI generated docstring)
 
 	Parameters
 	----------
-	computationDivisions: None
-		Specifies how to divide computations: Please see the documentation in `countFolds` for details. I know it is
+	computationDivisions : int | str | None
+		Specifies how to divide computations. Please see the documentation in `countFolds` for details. I know it is
 		annoying, but I want to be sure you have the most accurate information.
-	concurrencyLimit
+	concurrencyLimit : int
 		Maximum number of concurrent tasks allowed.
+	leavesTotal : int
+		Total number of leaves in the map.
 
 	Returns
 	-------
-	taskDivisions
-		How many tasks must finish before the job can compute the total number of folds; `0` means no tasks, only job.
+	taskDivisions : int
+		How many tasks must finish before the job can compute the total number of folds. `0` means no tasks, only job.
 
 	Raises
 	------
@@ -81,6 +91,7 @@ def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: i
 	Notes
 	-----
 	Task divisions should not exceed total leaves or the folds will be over-counted.
+
 	"""
 	taskDivisions = 0
 	match computationDivisions:
@@ -96,17 +107,21 @@ def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: i
 				case 'cpu':
 					taskDivisions = min(concurrencyLimit, leavesTotal)
 				case _:
-					raise ValueError(f"I received '{strComputationDivisions}' for the parameter, `computationDivisions`, but the string value is not supported.")
+					message = f"I received '{strComputationDivisions}' for the parameter, `computationDivisions`, but the string value is not supported."
+					raise ValueError(message)
 		case _:
-			raise ValueError(f"I received {computationDivisions} for the parameter, `computationDivisions`, but the type {type(computationDivisions).__name__} is not supported.")
+			message = f"I received {computationDivisions} for the parameter, `computationDivisions`, but the type {type(computationDivisions).__name__} is not supported."
+			raise ValueError(message)
 
 	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.")
+		message = 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."  # noqa: E501
+		raise ValueError(message)
 	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.
+	"""Implement connection graph generation for map folding.
+
+	(AI generated docstring)
 
 	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
@@ -114,14 +129,14 @@ def _makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int) -> ndarray
 
 	Parameters
 	----------
-	mapShape
+	mapShape : tuple[int, ...]
 		A tuple of integers representing the dimensions of the map.
-	leavesTotal
+	leavesTotal : int
 		The total number of leaves in the map.
 
 	Returns
 	-------
-	connectionGraph
+	connectionGraph : ndarray[tuple[int, int, int], numpy_dtype[numpy_int64]]
 		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.
 
@@ -132,9 +147,10 @@ def _makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int) -> ndarray
 
 	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)
+	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):
@@ -159,8 +175,9 @@ def _makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int) -> ndarray
 	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.
+	"""Create a properly typed connection graph for the map folding algorithm.
+
+	(AI generated docstring)
 
 	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
@@ -168,63 +185,66 @@ def getConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: ty
 
 	Parameters
 	----------
-	mapShape
+	mapShape : tuple[int, ...]
 		A tuple of integers representing the dimensions of the map.
-	leavesTotal
+	leavesTotal : int
 		The total number of leaves in the map.
-	datatype
+	datatype : type[NumPyIntegerType]
 		The NumPy integer type to use for the array elements, ensuring proper memory usage and compatibility with the
 		computation state.
 
 	Returns
 	-------
-	connectionGraph
+	connectionGraph : ndarray[tuple[int, int, int], numpy_dtype[NumPyIntegerType]]
 		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
+	return connectionGraph.astype(datatype)
 
 def makeDataContainer(shape: int | tuple[int, ...], datatype: type[NumPyIntegerType]) -> ndarray[Any, numpy_dtype[NumPyIntegerType]]:
-	"""
-	Create a typed NumPy array container with initialized values.
+	"""Create a typed NumPy array container with initialized values.
+
+	(AI generated docstring)
 
 	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
+	shape : int | tuple[int, ...]
 		Either an integer (for 1D arrays) or a tuple of integers (for multi-dimensional arrays) specifying the
 		dimensions of the array.
-	datatype
+	datatype : type[NumPyIntegerType]
 		The NumPy integer type to use for the array elements, ensuring proper type consistency and memory efficiency.
 
 	Returns
 	-------
-	container
+	container : ndarray[Any, numpy_dtype[NumPyIntegerType]]
 		A NumPy array of zeros with the specified shape and `datatype`.
+
 	"""
 	return numpy.zeros(shape, dtype=datatype)
 
 def setProcessorLimit(CPUlimit: Any | None, concurrencyPackage: str | None = None) -> int:
-	"""
-	Whether and how to limit the CPU usage.
+	"""Set the CPU usage limit for concurrent operations.
+
+	(AI generated docstring)
 
 	Parameters
 	----------
-	CPUlimit: None
+	CPUlimit : Any | None
 		Please see the documentation for in `countFolds` for details. I know it is annoying, but I want to be sure you
 		have the most accurate information.
-	concurrencyPackage: None
-		Specifies which concurrency package to use:
+	concurrencyPackage : str | None = None
+		Specifies which concurrency package to use.
 		- `None` or `'multiprocessing'`: Uses standard `multiprocessing`.
 		- `'numba'`: Uses Numba's threading system.
 
 	Returns
 	-------
-	concurrencyLimit
+	concurrencyLimit : int
 		The actual concurrency limit that was set.
 
 	Raises
@@ -242,6 +262,7 @@ def setProcessorLimit(CPUlimit: Any | None, concurrencyPackage: str | None = Non
 
 	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)
@@ -249,20 +270,22 @@ def setProcessorLimit(CPUlimit: Any | None, concurrencyPackage: str | None = Non
 	match concurrencyPackage:
 		case 'multiprocessing' | None:
 			# When to use multiprocessing.set_start_method
-			# https://github.com/hunterhogan/mapFolding/issues/6
-			concurrencyLimit: int = defineConcurrencyLimit(CPUlimit)
+			# https://github.com/hunterhogan/mapFolding/issues/6  # noqa: ERA001
+			concurrencyLimit: int = defineConcurrencyLimit(limit=CPUlimit)
 		case 'numba':
-			from numba import get_num_threads, set_num_threads
-			concurrencyLimit = defineConcurrencyLimit(CPUlimit, get_num_threads())
+			from numba import get_num_threads, set_num_threads  # noqa: PLC0415
+			concurrencyLimit = defineConcurrencyLimit(limit=CPUlimit, cpuTotal=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.")
+			message = f"I received `{concurrencyPackage = }` but I don't know what to do with that."
+			raise NotImplementedError(message)
 	return concurrencyLimit
 
 def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
-	"""
-	Validate and normalize dimensions for a map folding problem.
+	"""Validate and normalize dimensions for a map folding problem.
+
+	(AI generated docstring)
 
 	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
@@ -270,12 +293,12 @@ def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
 
 	Parameters
 	----------
-	listDimensions
+	listDimensions : Sequence[int]
 		A sequence of integers representing the dimensions of the map.
 
 	Returns
 	-------
-	mapShape
+	mapShape : tuple[int, ...]
 		An _unsorted_ tuple of positive integers representing the validated dimensions.
 
 	Raises
@@ -284,17 +307,21 @@ def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
 		If the input is empty or contains negative values.
 	NotImplementedError
 		If fewer than two positive dimensions are provided.
+
 	"""
 	if not listDimensions:
-		raise ValueError("`listDimensions` is a required parameter.")
+		message = "`listDimensions` is a required parameter."
+		raise ValueError(message)
 	listOFint: list[int] = intInnit(listDimensions, 'listDimensions')
 	mapDimensions: list[int] = []
 	for dimension in listOFint:
 		if dimension <= 0:
-			raise ValueError(f"I received `{dimension = }` in `{listDimensions = }`, but all dimensions must be a non-negative integer.")
+			message = f"I received `{dimension = }` in `{listDimensions = }`, but all dimensions must be a non-negative integer."
+			raise ValueError(message)
 		mapDimensions.append(dimension)
-	if len(mapDimensions) < 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/.")
+	if len(mapDimensions) < 2:  # noqa: PLR2004
+		message = f"This function requires `{listDimensions = }` to have at least two dimensions greater than 0. You may want to look at https://oeis.org/."
+		raise NotImplementedError(message)
 
 	"""
 	I previously sorted the dimensions for a few reasons that may or may not be valid:

mapFolding/dataBaskets.py

@@ -1,29 +1,103 @@
+"""
+Computational state orchestration for map folding analysis.
+
+(AI generated docstring)
+
+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.
+
+	(AI generated docstring)
+
+	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 include automatic array sizing based on map dimensions,
+	type-safe access to computational data, lazy initialization of expensive arrays,
+	integration with NumPy for performance, and metadata preservation for code generation.
+
+	Attributes
+	----------
+	mapShape : tuple[DatatypeLeavesTotal, ...]
+		Dimensions of the map being analyzed for folding patterns.
+	groupsOfFolds : DatatypeFoldsTotal = DatatypeFoldsTotal(0)
+		Current count of distinct folding pattern groups discovered.
+	gap1ndex : DatatypeElephino = DatatypeElephino(0)
+		Current position in gap enumeration algorithms.
+	gap1ndexCeiling : DatatypeElephino = DatatypeElephino(0)
+		Upper bound for gap enumeration operations.
+	indexDimension : DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+		Current dimension being processed in multi-dimensional algorithms.
+	indexLeaf : DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+		Current leaf being processed in sequential algorithms.
+	indexMiniGap : DatatypeElephino = DatatypeElephino(0)
+		Current position within a gap subdivision.
+	leaf1ndex : DatatypeLeavesTotal = DatatypeLeavesTotal(1)
+		One-based leaf index for algorithmic compatibility.
+	leafConnectee : DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+		Target leaf for connection operations.
+	dimensionsUnconstrained : DatatypeLeavesTotal = None
+		Count of dimensions not subject to folding constraints.
+	countDimensionsGapped : Array1DLeavesTotal = None
+		Array tracking gap counts across dimensions.
+	gapRangeStart : Array1DElephino = None
+		Array of starting positions for gap ranges.
+	gapsWhere : Array1DLeavesTotal = None
+		Array indicating locations of gaps in the folding pattern.
+	leafAbove : Array1DLeavesTotal = None
+		Array mapping each leaf to the leaf above it in the folding.
+	leafBelow : Array1DLeavesTotal = None
+		Array mapping each leaf to the leaf below it in the folding.
+	connectionGraph : Array3D
+		Three-dimensional representation of leaf connectivity.
+	dimensionsTotal : DatatypeLeavesTotal
+		Total number of dimensions in the map.
+	leavesTotal : DatatypeLeavesTotal
+		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})
 
-	gap1ndex: DatatypeElephino = DatatypeElephino(0)
-	gap1ndexCeiling: DatatypeElephino = DatatypeElephino(0)
-	indexDimension: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
-	indexLeaf: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
-	indexMiniGap: DatatypeElephino = DatatypeElephino(0)
-	leaf1ndex: DatatypeLeavesTotal = DatatypeLeavesTotal(1)
-	leafConnectee: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+	gap1ndex: DatatypeElephino = DatatypeElephino(0)  # noqa: RUF009
+	gap1ndexCeiling: DatatypeElephino = DatatypeElephino(0)  # noqa: RUF009
+	indexDimension: DatatypeLeavesTotal = DatatypeLeavesTotal(0)  # noqa: RUF009
+	indexLeaf: DatatypeLeavesTotal = DatatypeLeavesTotal(0)  # noqa: RUF009
+	indexMiniGap: DatatypeElephino = DatatypeElephino(0)  # noqa: RUF009
+	leaf1ndex: DatatypeLeavesTotal = DatatypeLeavesTotal(1)  # noqa: RUF009
+	leafConnectee: DatatypeLeavesTotal = DatatypeLeavesTotal(0)  # noqa: RUF009
 
 	dimensionsUnconstrained: DatatypeLeavesTotal = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
 
@@ -36,13 +110,43 @@ 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:
-		_foldsTotal = DatatypeFoldsTotal(self.leavesTotal) * self.groupsOfFolds
-		return _foldsTotal
+		"""Calculate the total number of possible folding patterns for this map.
+
+		(AI generated docstring)
+
+		Returns
+		-------
+		totalFoldingPatterns : DatatypeFoldsTotal
+			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.
+
+		"""
+		return DatatypeFoldsTotal(self.leavesTotal) * self.groupsOfFolds
 
 	def __post_init__(self) -> None:
+		"""Initialize all computational arrays and derived values after dataclass construction.
+
+		(AI generated docstring)
+
+		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,33 +154,124 @@ 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):
-	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`."""
+	"""Experimental computational state for task division operations.
+
+	(AI generated docstring)
 
-	taskIndex: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
-	"""Index of the current task when using task divisions."""
+	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 : DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+		Number of tasks into which the computation is divided.
+	taskIndex : DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+		Current task identifier when processing in task division mode.
+
+	"""
+
+	taskDivisions: DatatypeLeavesTotal = DatatypeLeavesTotal(0)  # noqa: RUF009
+	"""
+	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)  # noqa: RUF009
+	"""
+	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.
+
+		(AI generated docstring)
+
+		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.
+
+	(AI generated docstring)
+
+	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 : Array1DLeavesTotal = None
+		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.
+
+		(AI generated docstring)
+
+		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
+		from mapFolding.oeis import getFoldsTotalKnown  # noqa: PLC0415
 		groupsOfFoldsKnown = getFoldsTotalKnown(self.mapShape) // self.leavesTotal
 		if self.leafSequence is None: # pyright: ignore[reportUnnecessaryComparison]
 			self.leafSequence = makeDataContainer(groupsOfFoldsKnown, self.__dataclass_fields__['leafSequence'].metadata['dtype'])