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

mapFolding/beDRY.py

@@ -1,6 +1,8 @@
 """
 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
@@ -21,27 +23,28 @@ requires to orchestrate the complex recursive algorithms.
 """
 
 from collections.abc import Sequence
+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
 
 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
@@ -49,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
 	------
@@ -83,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:
@@ -98,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
@@ -116,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.
 
@@ -134,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):
@@ -161,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
@@ -170,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
@@ -244,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)
@@ -251,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
@@ -272,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
@@ -286,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,6 +1,8 @@
 """
 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
@@ -19,107 +21,118 @@ 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 and metadata useful for code transformations.
+
+	Attributes
+	----------
+	mapShape : tuple[DatatypeLeavesTotal, ...]
+		Dimensions of the map being analyzed for folding patterns.
+	groupsOfFolds : DatatypeFoldsTotal = DatatypeFoldsTotal(0)
+		Current count of distinct folding pattern groups: each group has `leavesTotal`-many foldings.
+	gap1ndex : DatatypeElephino = DatatypeElephino(0)
+		The current 1-indexed position of the 'gap' during computation: 1-indexed as opposed to 0-indexed.
+	gap1ndexCeiling : DatatypeElephino = DatatypeElephino(0)
+		The upper bound of `gap1ndex`.
+	indexDimension : DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+		The current 0-indexed position of the dimension during computation.
+	indexLeaf : DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+		The current 0-indexed position of a leaf in a loop during computation: not to be confused with `leaf1ndex`.
+	indexMiniGap : DatatypeElephino = DatatypeElephino(0)
+		The current 0-indexed position of a 'gap' in a loop during computation.
+	leaf1ndex : DatatypeLeavesTotal = DatatypeLeavesTotal(1)
+		The current 1-indexed position of the leaf during computation: 1-indexed as opposed to 0-indexed.
+	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 computed number of dimensions with gaps.
+	gapRangeStart : Array1DElephino = None
+		Array tracking computed starting positions of gap ranges.
+	gapsWhere : Array1DLeavesTotal = None
+		Array indicating locations of gaps in the folding pattern.
+	leafAbove : Array1DLeavesTotal = None
+		Array tracking the leaves above to the current leaf, `leaf1ndex`, during computation.
+	leafBelow : Array1DLeavesTotal = None
+		Array tracking the leaves below to the current leaf, `leaf1ndex`, during computation.
+	connectionGraph : Array3D
+		Unchanging array representing connections between all leaves.
+	dimensionsTotal : DatatypeLeavesTotal
+		Unchanging total number of dimensions in the map.
+	leavesTotal : DatatypeLeavesTotal
+		Unchanging total number of leaves in the map.
+
 	"""
-	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'})
+	"""Dimensions of the map being analyzed for folding patterns."""
 
 	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)
+	"""Current count of distinct folding pattern groups: each group has `leavesTotal`-many foldings."""
+
+	gap1ndex: DatatypeElephino = DatatypeElephino(0)  # noqa: RUF009
+	"""The current 1-indexed position of the 'gap' during computation: 1-indexed as opposed to 0-indexed."""
+	gap1ndexCeiling: DatatypeElephino = DatatypeElephino(0)  # noqa: RUF009
+	"""The upper bound of `gap1ndex`."""
+	indexDimension: DatatypeLeavesTotal = DatatypeLeavesTotal(0)  # noqa: RUF009
+	"""The current 0-indexed position of the dimension during computation."""
+	indexLeaf: DatatypeLeavesTotal = DatatypeLeavesTotal(0)  # noqa: RUF009
+	"""The current 0-indexed position of a leaf in a loop during computation: not to be confused with `leaf1ndex`."""
+	indexMiniGap: DatatypeElephino = DatatypeElephino(0)  # noqa: RUF009
+	"""The current 0-indexed position of a 'gap' in a loop during computation."""
+	leaf1ndex: DatatypeLeavesTotal = DatatypeLeavesTotal(1)  # noqa: RUF009
+	"""The current 1-indexed position of the leaf during computation: 1-indexed as opposed to 0-indexed."""
+	leafConnectee: DatatypeLeavesTotal = DatatypeLeavesTotal(0)  # noqa: RUF009
+	"""Target leaf for connection operations."""
 
 	dimensionsUnconstrained: DatatypeLeavesTotal = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Count of dimensions not subject to folding constraints."""
 
 	countDimensionsGapped: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Array tracking computed number of dimensions with gaps."""
 	gapRangeStart: Array1DElephino = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DElephino.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Array tracking computed starting positions of gap ranges."""
 	gapsWhere: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Array indicating locations of gaps in the folding pattern."""
 	leafAbove: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Array tracking the leaves above to the current leaf, `leaf1ndex`, during computation."""
 	leafBelow: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Array tracking the leaves below to the current leaf, `leaf1ndex`, during computation."""
 
 	connectionGraph: Array3D = dataclasses.field(init=False, metadata={'dtype': Array3D.__args__[1].__args__[0]}) # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
+	"""Unchanging array representing connections between all leaves."""
 	dimensionsTotal: DatatypeLeavesTotal = dataclasses.field(init=False)
+	"""Unchanging total number of dimensions in the map."""
 	leavesTotal: DatatypeLeavesTotal = dataclasses.field(init=False)
+	"""Unchanging total number of leaves in the map."""
 	@property
 	def foldsTotal(self) -> DatatypeFoldsTotal:
-		"""
-		Calculate the total number of possible folding patterns for this map.
+		"""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.
+		Returns
+		-------
+		totalFoldings : 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.
 		"""
-		_foldsTotal = DatatypeFoldsTotal(self.leavesTotal) * self.groupsOfFolds
-		return _foldsTotal
+		return DatatypeFoldsTotal(self.leavesTotal) * self.groupsOfFolds
 
 	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.
+		"""Ensure all fields have a value.
+
+		Notes
+		-----
+		Arrays that are not explicitly provided (None) are automatically allocated with appropriate sizes based on the map
+		dimensions. `dimensionsTotal`, `leavesTotal`, and `connectionGraph` cannot be set: they are calculated.
+
 		"""
 		self.dimensionsTotal = DatatypeLeavesTotal(len(self.mapShape))
 		self.leavesTotal = DatatypeLeavesTotal(getLeavesTotal(self.mapShape))
@@ -137,8 +150,9 @@ class MapFoldingState:
 
 @dataclasses.dataclass
 class ParallelMapFoldingState(MapFoldingState):
-	"""
-	Experimental computational state for task division operations.
+	"""Experimental computational state for task division operations.
+
+	(AI generated docstring)
 
 	This class extends the base MapFoldingState with additional attributes
 	needed for experimental task division of map folding computations. It manages
@@ -151,11 +165,16 @@ class ParallelMapFoldingState(MapFoldingState):
 	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.
+	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)
+
+	taskDivisions: DatatypeLeavesTotal = DatatypeLeavesTotal(0)  # noqa: RUF009
 	"""
 	Number of tasks into which to divide the computation.
 
@@ -164,7 +183,7 @@ class ParallelMapFoldingState(MapFoldingState):
 	`leavesTotal` during initialization, providing optimal task granularity.
 	"""
 
-	taskIndex: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+	taskIndex: DatatypeLeavesTotal = DatatypeLeavesTotal(0)  # noqa: RUF009
 	"""
 	Index of the current task when using task divisions.
 
@@ -175,12 +194,15 @@ class ParallelMapFoldingState(MapFoldingState):
 	"""
 
 	def __post_init__(self) -> None:
-		"""
-		Initialize parallel-specific state after base initialization.
+		"""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:
@@ -188,8 +210,9 @@ class ParallelMapFoldingState(MapFoldingState):
 
 @dataclasses.dataclass
 class LeafSequenceState(MapFoldingState):
-	"""
-	Specialized computational state for tracking leaf sequences during analysis.
+	"""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
@@ -201,9 +224,13 @@ class LeafSequenceState(MapFoldingState):
 	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.
+	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.
@@ -215,20 +242,23 @@ class LeafSequenceState(MapFoldingState):
 	"""
 
 	def __post_init__(self) -> None:
-		"""
-		Initialize sequence tracking arrays with OEIS integration.
+		"""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.
+		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'])