mapFolding 0.12.3__tar.gz → 0.13.1__tar.gz

{mapfolding-0.12.3 → mapfolding-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapFolding
-Version: 0.12.3
+Version: 0.13.1
 Summary: Map folding algorithm with code transformation framework for optimizing numerical computations.
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 License: CC-BY-NC-4.0
@@ -8,42 +8,49 @@ Project-URL: Donate, https://www.patreon.com/integrated
 Project-URL: Homepage, https://github.com/hunterhogan/mapFolding
 Project-URL: Issues, https://github.com/hunterhogan/mapFolding/issues
 Project-URL: Repository, https://github.com/hunterhogan/mapFolding.git
-Keywords: A000136,A001415,A001416,A001417,A001418,A195646,AST manipulation,Numba optimization,OEIS,algorithmic optimization,code generation,code transformation,combinatorics,computational geometry,dataclass transformation,folding pattern enumeration,just-in-time compilation,map folding,performance optimization,source code analysis,stamp folding
+Keywords: A000136,A001415,A001416,A001417,A001418,A195646,AST manipulation,Numba optimization,OEIS,algorithmic optimization,code generation,code transformation,codon optimization,combinatorics,computational geometry,dataclass transformation,folding pattern enumeration,just-in-time compilation,map folding,performance optimization,source code analysis,stamp folding
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
 Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Classifier: Topic :: Software Development :: Code Generators
 Classifier: Topic :: Software Development :: Compilers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Pre-processors
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: astToolkit>=0.5.0
+Requires-Dist: astToolkit
 Requires-Dist: hunterMakesPy
-Requires-Dist: numba
-Requires-Dist: numba_progress
 Requires-Dist: numpy
 Requires-Dist: platformdirs
 Provides-Extra: development
 Requires-Dist: mypy; extra == "development"
 Requires-Dist: pyupgrade; extra == "development"
 Requires-Dist: setuptools-scm; extra == "development"
+Provides-Extra: numba
+Requires-Dist: numba; extra == "numba"
+Requires-Dist: numba_progress; extra == "numba"
 Provides-Extra: testing
-Requires-Dist: pytest; extra == "testing"
+Requires-Dist: numba; extra == "testing"
 Requires-Dist: pytest-cov; extra == "testing"
 Requires-Dist: pytest-env; extra == "testing"
 Requires-Dist: pytest-xdist; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
 Dynamic: license-file
 
 # mapFolding
@@ -94,6 +101,7 @@ For larger maps, these calculations require hours or days to complete. A 2×20 s
 - **Automatic code generation** that produces standalone, highly optimized computation modules
 - **Dataclass decomposition** to enable Numba compatibility while preserving readable source code
 - **Comprehensive optimization** including dead code elimination, static value embedding, and aggressive compilation settings
+- **codon code generation**: compile map folding computation modules using [Codon](https://docs.exaloop.io/start/install/), enabling high-performance native binaries from Python source code.
 
 ### Educational Resources
 
@@ -106,35 +114,18 @@ For larger maps, these calculations require hours or days to complete. A 2×20 s
 
 **Mathematical Research**: Explore folding pattern properties, extend known sequences, or validate theoretical results against computed values.
 
-**Algorithm Optimization Learning**: Study a complete transformation pipeline that converts high-level algorithms into production-ready optimized code.
+**Algorithm Optimization Learning**: Study a complete transformation assembly line that converts high-level algorithms into production-ready optimized code.
 
 **Performance Computing Education**: Examine techniques for achieving maximum Python performance through Numba integration, AST manipulation, and specialized code generation.
 
 **Combinatorial Problem Solving**: Use the framework as a template for optimizing other recursive combinatorial algorithms.
 
-## Example Usage
-
-```python
-from mapFolding import countFolds
-
-# Count folding patterns for a 3×3 square
-result = countFolds([3, 3])
-
-# Access OEIS sequences directly
-from mapFolding import oeisIDfor_n
-strip_foldings = oeisIDfor_n('A001415', 6)  # 2×6 strip
-
-# Generate optimized code for specific dimensions
-from mapFolding.someAssemblyRequired import makeJobTheorem2Numba
-# Creates specialized modules for maximum performance
-```
-
 ## Repository Structure
 
 - `mapFolding/`: Core implementation with modular architecture
 - `reference/`: Historical algorithm implementations and performance studies
 - `someAssemblyRequired/`: AST transformation framework
-- `tests/`: Comprehensive validation suite
+- `mapFolding/tests/`: Comprehensive validation suite
 - `jobs/`: Generated optimized modules for specific calculations
 
 ## Performance Characteristics

{mapfolding-0.12.3 → mapfolding-0.13.1}/README.md

@@ -46,6 +46,7 @@ For larger maps, these calculations require hours or days to complete. A 2×20 s
 - **Automatic code generation** that produces standalone, highly optimized computation modules
 - **Dataclass decomposition** to enable Numba compatibility while preserving readable source code
 - **Comprehensive optimization** including dead code elimination, static value embedding, and aggressive compilation settings
+- **codon code generation**: compile map folding computation modules using [Codon](https://docs.exaloop.io/start/install/), enabling high-performance native binaries from Python source code.
 
 ### Educational Resources
 
@@ -58,35 +59,18 @@ For larger maps, these calculations require hours or days to complete. A 2×20 s
 
 **Mathematical Research**: Explore folding pattern properties, extend known sequences, or validate theoretical results against computed values.
 
-**Algorithm Optimization Learning**: Study a complete transformation pipeline that converts high-level algorithms into production-ready optimized code.
+**Algorithm Optimization Learning**: Study a complete transformation assembly line that converts high-level algorithms into production-ready optimized code.
 
 **Performance Computing Education**: Examine techniques for achieving maximum Python performance through Numba integration, AST manipulation, and specialized code generation.
 
 **Combinatorial Problem Solving**: Use the framework as a template for optimizing other recursive combinatorial algorithms.
 
-## Example Usage
-
-```python
-from mapFolding import countFolds
-
-# Count folding patterns for a 3×3 square
-result = countFolds([3, 3])
-
-# Access OEIS sequences directly
-from mapFolding import oeisIDfor_n
-strip_foldings = oeisIDfor_n('A001415', 6)  # 2×6 strip
-
-# Generate optimized code for specific dimensions
-from mapFolding.someAssemblyRequired import makeJobTheorem2Numba
-# Creates specialized modules for maximum performance
-```
-
 ## Repository Structure
 
 - `mapFolding/`: Core implementation with modular architecture
 - `reference/`: Historical algorithm implementations and performance studies
 - `someAssemblyRequired/`: AST transformation framework
-- `tests/`: Comprehensive validation suite
+- `mapFolding/tests/`: Comprehensive validation suite
 - `jobs/`: Generated optimized modules for specific calculations
 
 ## Performance Characteristics

{mapfolding-0.12.3 → mapfolding-0.13.1}/mapFolding/basecamp.py

@@ -31,11 +31,11 @@ from os import PathLike
 from pathlib import PurePath
 import contextlib
 
-def countFolds(listDimensions: Sequence[int] | None = None  # noqa: C901
+def countFolds(listDimensions: Sequence[int] | None = None  # noqa: C901, PLR0912, PLR0915
 				, pathLikeWriteFoldsTotal: PathLike[str] | PurePath | None = None
 				, computationDivisions: int | str | None = None
-				, CPUlimit: int | float | bool | None = None
-				# , * I need to improve `standardizedEqualToCallableReturn` so it will work with keyword arguments
+				# , * # TODO improve `standardizedEqualToCallableReturn` so it will work with keyword arguments
+				, CPUlimit: int | float | bool | None = None  # noqa: FBT001
 				, mapShape: tuple[int, ...] | None = None
 				, oeisID: str | None = None
 				, oeis_n: int | None = None
@@ -142,7 +142,7 @@ def countFolds(listDimensions: Sequence[int] | None = None  # noqa: C901
 		mapFoldingState = doTheNeedful(mapFoldingState)
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif flow == 'theorem2' and any(dimension > 2 for dimension in mapShape):  # noqa: PLR2004
+	elif flow == 'theorem2' and any(dimension > 2 for dimension in mapShape):
 		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
@@ -154,7 +154,7 @@ def countFolds(listDimensions: Sequence[int] | None = None  # noqa: C901
 
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif flow == 'theorem2Trimmed' and any(dimension > 2 for dimension in mapShape):  # noqa: PLR2004
+	elif flow == 'theorem2Trimmed' and any(dimension > 2 for dimension in mapShape):
 		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 
@@ -166,7 +166,7 @@ def countFolds(listDimensions: Sequence[int] | None = None  # noqa: C901
 
 		foldsTotal = mapFoldingState.foldsTotal
 
-	elif (flow == 'theorem2Numba' or taskDivisions == 0) and any(dimension > 2 for dimension in mapShape):  # noqa: PLR2004
+	elif (flow == 'theorem2Numba' or taskDivisions == 0) and any(dimension > 2 for dimension in mapShape):
 		from mapFolding.dataBaskets import MapFoldingState  # noqa: PLC0415
 		mapFoldingState: MapFoldingState = MapFoldingState(mapShape)
 

{mapfolding-0.12.3 → mapfolding-0.13.1}/mapFolding/dataBaskets.py

@@ -29,122 +29,109 @@ import dataclasses
 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.
+	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 discovered.
+		Current count of distinct folding pattern groups: each group has `leavesTotal`-many foldings.
 	gap1ndex : DatatypeElephino = DatatypeElephino(0)
-		Current position in gap enumeration algorithms.
+		The current 1-indexed position of the 'gap' during computation: 1-indexed as opposed to 0-indexed.
 	gap1ndexCeiling : DatatypeElephino = DatatypeElephino(0)
-		Upper bound for gap enumeration operations.
+		The upper bound of `gap1ndex`.
 	indexDimension : DatatypeLeavesTotal = DatatypeLeavesTotal(0)
-		Current dimension being processed in multi-dimensional algorithms.
+		The current 0-indexed position of the dimension during computation.
 	indexLeaf : DatatypeLeavesTotal = DatatypeLeavesTotal(0)
-		Current leaf being processed in sequential algorithms.
+		The current 0-indexed position of a leaf in a loop during computation: not to be confused with `leaf1ndex`.
 	indexMiniGap : DatatypeElephino = DatatypeElephino(0)
-		Current position within a gap subdivision.
+		The current 0-indexed position of a 'gap' in a loop during computation.
 	leaf1ndex : DatatypeLeavesTotal = DatatypeLeavesTotal(1)
-		One-based leaf index for algorithmic compatibility.
+		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 gap counts across dimensions.
+		Array tracking computed number of dimensions with gaps.
 	gapRangeStart : Array1DElephino = None
-		Array of starting positions for gap ranges.
+		Array tracking computed starting positions of 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.
+		Array tracking the leaves above to the current leaf, `leaf1ndex`, during computation.
 	leafBelow : Array1DLeavesTotal = None
-		Array mapping each leaf to the leaf below it in the folding.
+		Array tracking the leaves below to the current leaf, `leaf1ndex`, during computation.
 	connectionGraph : Array3D
-		Three-dimensional representation of leaf connectivity.
+		Unchanging array representing connections between all leaves.
 	dimensionsTotal : DatatypeLeavesTotal
-		Total number of dimensions in the map.
+		Unchanging total number of dimensions in the map.
 	leavesTotal : DatatypeLeavesTotal
-		Total number of individual leaves in the map.
+		Unchanging total number of 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})
+	"""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.
-
-		(AI generated docstring)
+		"""The total number of possible folding patterns for this map.
 
 		Returns
 		-------
-		totalFoldingPatterns : DatatypeFoldsTotal
+		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.
-
 		"""
 		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.
+		"""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.
-		The connection graph is always regenerated to ensure consistency
-		with the provided map shape.
+		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))

{mapfolding-0.12.3 → mapfolding-0.13.1}/mapFolding/oeis.py

@@ -8,7 +8,7 @@ folding ecosystem into the broader mathematical community through comprehensive
 integration with the Online Encyclopedia of Integer Sequences (OEIS). This bridge
 enables validation of computational results against established mathematical
 knowledge while supporting the discovery of new sequence values through the
-sophisticated computational pipeline.
+sophisticated computational assembly line.
 
 The integration provides multiple pathways for mathematical verification: direct
 computation of OEIS sequences using the complete algorithmic implementation,

{mapfolding-0.12.3 → mapfolding-0.13.1}/mapFolding/someAssemblyRequired/RecipeJob.py

@@ -1,31 +1,4 @@
-"""
-Map folding AST transformation system: Configuration management and transformation orchestration.
-
-This module provides the configuration orchestration layer of the map folding AST transformation
-system, implementing comprehensive recipes that coordinate the entire transformation process from
-abstract mathematical algorithms to optimized computational modules. The `RecipeJobTheorem2Numba`
-dataclass serves as the central configuration blueprint that bridges pattern recognition, dataclass
-decomposition, function optimization, and Numba compilation into a unified transformation process.
-
-The recipe system addresses the complexity of managing transformation parameters across multiple
-stages while maintaining consistency between source algorithm metadata and target optimization
-requirements. The orchestration layer coordinates the systematic extraction of mathematical
-functions from source modules, embedding of concrete parameter values, elimination of dead code
-paths, and generation of standalone Python modules optimized for specific map dimensions through
-the complete transformation process.
-
-Configuration management separates source analysis capabilities from target generation parameters,
-enabling systematic exploration of computational spaces through automated generation of optimized
-solvers. Source analysis encompasses parsing and analysis of abstract syntax trees from generic
-algorithm modules, extraction of specific mathematical functions for specialization, and
-identification of dataclass structures for parameter embedding. Target generation coordinates
-creation of standalone Python modules with optimized implementations, integration of Numba
-optimization directives, and preservation of mathematical correctness throughout optimization.
-
-The recipe system enables the broader map folding research framework by providing systematic
-control over the transformation process while ensuring that generated modules achieve maximum
-performance through compile-time specialization and runtime optimization strategies.
-"""
+"""Configuration by dataclass."""
 
 from ast import Module
 from astToolkit import identifierDotAttribute, parseLogicalPath2astModule
@@ -36,24 +9,21 @@ from mapFolding import (
 from mapFolding.someAssemblyRequired import dataclassInstanceIdentifierDEFAULT, ShatteredDataclass
 from mapFolding.someAssemblyRequired.transformationTools import shatter_dataclassesDOTdataclass
 from pathlib import Path, PurePosixPath
-from typing import TypeAlias
 import dataclasses
 
 @dataclasses.dataclass
-class RecipeJobTheorem2Numba:
-	"""Configuration recipe for generating Numba-optimized map folding computation jobs.
+class RecipeJobTheorem2:
+	"""Configuration recipe for generating map folding computation jobs.
 
 	This dataclass serves as the central configuration hub for the code transformation
-	pipeline that converts generic map folding algorithms into highly optimized,
+	assembly line that converts generic map folding algorithms into highly optimized,
 	specialized computation modules. The recipe encapsulates all parameters required
 	for source code analysis, target file generation, datatype mapping, and compilation
 	optimization settings.
 
 	The transformation process operates by extracting functions from source modules,
 	embedding concrete parameter values, eliminating dead code paths, and generating
-	standalone Python modules optimized for specific map dimensions. These generated
-	modules achieve maximum performance through Numba just-in-time compilation and
-	embedded compile-time constants.
+	standalone Python modules optimized for specific map dimensions.
 
 	The recipe maintains both source configuration (where to find the generic algorithm)
 	and target configuration (where to write the optimized module), along with the
@@ -61,84 +31,118 @@ class RecipeJobTheorem2Numba:
 
 	Attributes
 	----------
-	state: The map folding computation state containing dimensions and initial values.
-	foldsTotalEstimated: Estimated total number of folds for progress tracking (0).
-	shatteredDataclass: Deconstructed dataclass metadata for code transformation.
-	source_astModule: Parsed AST of the source module containing the generic algorithm.
-	sourceCountCallable: Name of the counting function to extract ('count').
-	sourceLogicalPathModuleDataclass: Logical path to the dataclass module.
-	sourceDataclassIdentifier: Name of the source dataclass ('MapFoldingState').
-	sourceDataclassInstance: Instance identifier for the dataclass.
-	sourcePathPackage: Path to the source package.
-	sourcePackageIdentifier: Name of the source package.
-	pathPackage: Override path for the target package (None).
-	pathModule: Override path for the target module directory.
-	fileExtension: File extension for generated modules.
-	pathFilenameFoldsTotal: Path for writing fold count results.
-	packageIdentifier: Target package identifier (None).
-	logicalPathRoot: Logical path root corresponding to filesystem directory.
-	moduleIdentifier: Target module identifier.
-	countCallable: Name of the counting function in generated module.
-	dataclassIdentifier: Target dataclass identifier.
-	dataclassInstance: Target dataclass instance identifier.
-	logicalPathModuleDataclass: Logical path to target dataclass module.
-	DatatypeFoldsTotal: Type alias for fold count datatype.
-	DatatypeElephino: Type alias for intermediate computation datatype.
-	DatatypeLeavesTotal: Type alias for leaf count datatype.
+	state : MapFoldingState
+		The map folding computation state containing dimensions and initial values.
+	foldsTotalEstimated : int = 0
+		Estimated total number of folds for progress tracking.
+	shatteredDataclass : ShatteredDataclass = None
+		Deconstructed dataclass metadata for code transformation.
+	source_astModule : Module
+		Parsed AST of the source module containing the generic algorithm.
+	sourceCountCallable : str = 'count'
+		Name of the counting function to extract.
+	sourceLogicalPathModuleDataclass : identifierDotAttribute
+		Logical path to the dataclass module.
+	sourceDataclassIdentifier : str = 'MapFoldingState'
+		Name of the source dataclass.
+	sourceDataclassInstance : str
+		Instance identifier for the dataclass.
+	sourcePathPackage : PurePosixPath | None
+		Path to the source package.
+	sourcePackageIdentifier : str | None
+		Name of the source package.
+	pathPackage : PurePosixPath | None = None
+		Override path for the target package.
+	pathModule : PurePosixPath | None
+		Override path for the target module directory.
+	fileExtension : str
+		File extension for generated modules.
+	pathFilenameFoldsTotal : PurePosixPath = None
+		Path for writing fold count results.
+	packageIdentifier : str | None = None
+		Target package identifier.
+	logicalPathRoot : identifierDotAttribute | None = None
+		Logical path root; probably corresponds to physical filesystem directory.
+	moduleIdentifier : str = None
+		Target module identifier.
+	countCallable : str
+		Name of the counting function in generated module.
+	dataclassIdentifier : str | None
+		Target dataclass identifier.
+	dataclassInstance : str | None
+		Target dataclass instance identifier.
+	logicalPathModuleDataclass : identifierDotAttribute | None
+		Logical path to target dataclass module.
+	DatatypeFoldsTotal : TypeAlias
+		Type alias for fold count datatype.
+	DatatypeElephino : TypeAlias
+		Type alias for intermediate computation datatype.
+	DatatypeLeavesTotal : TypeAlias
+		Type alias for leaf count datatype.
 	"""
 
 	state: MapFoldingState
-	# TODO create function to calculate `foldsTotalEstimated`
+	"""The map folding computation state containing dimensions and initial values."""
 	foldsTotalEstimated: int = 0
+	"""Estimated total number of folds for progress tracking."""
 	shatteredDataclass: ShatteredDataclass = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType]
+	"""Deconstructed dataclass metadata for code transformation."""
 
 	# Source -----------------------------------------
 	source_astModule: Module = parseLogicalPath2astModule('mapFolding.syntheticModules.theorem2Numba')  # noqa: RUF009
+	"""Parsed AST of the source module containing the generic algorithm."""
 	sourceCountCallable: str = 'count'
+	"""Name of the counting function to extract."""
 
 	sourceLogicalPathModuleDataclass: identifierDotAttribute = 'mapFolding.dataBaskets'
+	"""Logical path to the dataclass module."""
 	sourceDataclassIdentifier: str = 'MapFoldingState'
+	"""Name of the source dataclass."""
 	sourceDataclassInstance: str = dataclassInstanceIdentifierDEFAULT
+	"""Instance identifier for the dataclass."""
 
 	sourcePathPackage: PurePosixPath | None = PurePosixPath(packageSettings.pathPackage)  # noqa: RUF009
+	"""Path to the source package."""
 	sourcePackageIdentifier: str | None = packageSettings.identifierPackage
+	"""Name of the source package."""
 
 	# Filesystem, names of physical objects ------------------------------------------
 	pathPackage: PurePosixPath | None = None
+	"""Override path for the target package."""
 	pathModule: PurePosixPath | None = PurePosixPath(getPathRootJobDEFAULT())  # noqa: RUF009
-	""" `pathModule` will override `pathPackage` and `logicalPathRoot`."""
+	"""Override path for the target module directory."""
 	fileExtension: str = packageSettings.fileExtension
+	"""File extension for generated modules."""
 	pathFilenameFoldsTotal: PurePosixPath = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType]
+	"""Path for writing fold count results."""
 
 	# Logical identifiers, as opposed to physical identifiers ------------------------
 	packageIdentifier: str | None = None
+	"""Target package identifier."""
 	logicalPathRoot: identifierDotAttribute | None = None
-	""" `logicalPathRoot` likely corresponds to a physical filesystem directory."""
+	"""Logical path root; probably corresponds to physical filesystem directory."""
 	moduleIdentifier: str = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType]
+	"""Target module identifier."""
 	countCallable: str = sourceCountCallable
+	"""Name of the counting function in generated module."""
 	dataclassIdentifier: str | None = sourceDataclassIdentifier
+	"""Target dataclass identifier."""
 	dataclassInstance: str | None = sourceDataclassInstance
+	"""Target dataclass instance identifier."""
 	logicalPathModuleDataclass: identifierDotAttribute | None = sourceLogicalPathModuleDataclass
+	"""Logical path to target dataclass module."""
 
 	# Datatypes ------------------------------------------
-	DatatypeFoldsTotal: TypeAlias = TheDatatypeFoldsTotal
-	DatatypeElephino: TypeAlias = TheDatatypeElephino
-	DatatypeLeavesTotal: TypeAlias = TheDatatypeLeavesTotal
-
-	def _makePathFilename(self,
-			pathRoot: PurePosixPath | None = None,
-			logicalPathINFIX: identifierDotAttribute | None = None,
-			filenameStem: str | None = None,
-			fileExtension: str | None = None,
-			) -> PurePosixPath:
+	type DatatypeFoldsTotal = TheDatatypeFoldsTotal
+	"""Type alias for datatype linked to the magnitude of `foldsTotal`."""
+	type DatatypeElephino = TheDatatypeElephino
+	"""Type alias for intermediate computation datatype."""
+	type DatatypeLeavesTotal = TheDatatypeLeavesTotal
+	"""Type alias for datatype linked to the magnitude of `leavesTotal`."""
+
+	def _makePathFilename(self, pathRoot: PurePosixPath | None = None, logicalPathINFIX: identifierDotAttribute | None = None, filenameStem: str | None = None, fileExtension: str | None = None) -> PurePosixPath:
 		"""Construct a complete file path from component parts.
 
-		(AI generated docstring)
-
-		This helper method builds filesystem paths by combining a root directory,
-		optional subdirectory structure, filename stem, and file extension. It provides
-		sensible defaults for missing components based on the recipe configuration.
-
 		Parameters
 		----------
 		pathRoot : PurePosixPath | None = None
@@ -172,8 +176,6 @@ class RecipeJobTheorem2Numba:
 	def pathFilenameModule(self) -> PurePosixPath:
 		"""Generate the complete path and filename for the output module.
 
-		(AI generated docstring)
-
 		This property computes the target location where the generated computation
 		module will be written. It respects the `pathModule` override if specified,
 		otherwise constructs the path using the default package structure.
@@ -192,8 +194,6 @@ class RecipeJobTheorem2Numba:
 	def __post_init__(self) -> None:
 		"""Initialize computed fields and validate configuration after dataclass creation.
 
-		(AI generated docstring)
-
 		This method performs post-initialization setup including deriving module
 		identifier from map shape if not explicitly provided, setting default paths
 		for fold total output files, and creating shattered dataclass metadata for

{mapfolding-0.12.3 → mapfolding-0.13.1}/mapFolding/someAssemblyRequired/_toolkitContainers.py

@@ -217,10 +217,10 @@ class DeReConstructField2ast:
 		self.ast_keyword_field__field = Make.keyword(self.name, self.astName)
 		self.ast_nameDOTname = Make.Attribute(Make.Name(dataclassesDOTdataclassInstanceIdentifier), self.name)
 
-		self.astAnnotation = raiseIfNone(NodeTourist[ast.AnnAssign, ast.Name | None](
+		self.astAnnotation = cast('ast.Name', raiseIfNone(NodeTourist(
 			findThis = Be.AnnAssign.targetIs(IfThis.isNameIdentifier(self.name))
-			, doThat = Then.extractIt(cast("Callable[[ast.AnnAssign], ast.Name | None]", DOT.annotation))
-			).captureLastMatch(dataclassClassDef))
+			, doThat = Then.extractIt(DOT.annotation)
+			).captureLastMatch(dataclassClassDef)))
 
 		self.ast_argAnnotated = Make.arg(self.name, self.astAnnotation)