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

mapFolding/someAssemblyRequired/RecipeJob.py

@@ -1,6 +1,39 @@
-from astToolkit import parseLogicalPath2astModule, str_nameDOTname
-from mapFolding import getPathFilenameFoldsTotal, getPathRootJobDEFAULT, MapFoldingState, packageSettings
-from mapFolding import DatatypeElephino as TheDatatypeElephino, DatatypeFoldsTotal as TheDatatypeFoldsTotal, DatatypeLeavesTotal as TheDatatypeLeavesTotal
+"""
+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.
+"""
+
+from ast import Module
+from astToolkit import identifierDotAttribute, parseLogicalPath2astModule
+from mapFolding import (
+	DatatypeElephino as TheDatatypeElephino, DatatypeFoldsTotal as TheDatatypeFoldsTotal,
+	DatatypeLeavesTotal as TheDatatypeLeavesTotal, getPathFilenameFoldsTotal, getPathRootJobDEFAULT,
+	MapFoldingState, packageSettings,
+)
 from mapFolding.someAssemblyRequired import dataclassInstanceIdentifierDEFAULT, ShatteredDataclass
 from mapFolding.someAssemblyRequired.transformationTools import shatter_dataclassesDOTdataclass
 from pathlib import Path, PurePosixPath
@@ -9,6 +42,50 @@ import dataclasses
 
 @dataclasses.dataclass
 class RecipeJobTheorem2Numba:
+	"""Configuration recipe for generating Numba-optimized 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,
+	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.
+
+	The recipe maintains both source configuration (where to find the generic algorithm)
+	and target configuration (where to write the optimized module), along with the
+	computational state that provides concrete values for the transformation process.
+
+	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
 	# TODO create function to calculate `foldsTotalEstimated`
 	foldsTotalEstimated: int = 0
@@ -16,10 +93,10 @@ class RecipeJobTheorem2Numba:
 
 	# ========================================
 	# Source
-	source_astModule = parseLogicalPath2astModule('mapFolding.syntheticModules.theorem2Numba')
+	source_astModule: Module = parseLogicalPath2astModule('mapFolding.syntheticModules.theorem2Numba')
 	sourceCountCallable: str = 'count'
 
-	sourceLogicalPathModuleDataclass: str_nameDOTname = 'mapFolding.dataBaskets'
+	sourceLogicalPathModuleDataclass: identifierDotAttribute = 'mapFolding.dataBaskets'
 	sourceDataclassIdentifier: str = 'MapFoldingState'
 	sourceDataclassInstance: str = dataclassInstanceIdentifierDEFAULT
 
@@ -37,13 +114,13 @@ class RecipeJobTheorem2Numba:
 	# ========================================
 	# Logical identifiers (as opposed to physical identifiers)
 	packageIdentifier: str | None = None
-	logicalPathRoot: str_nameDOTname | None = None
+	logicalPathRoot: identifierDotAttribute | None = None
 	""" `logicalPathRoot` likely corresponds to a physical filesystem directory."""
 	moduleIdentifier: str = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType]
 	countCallable: str = sourceCountCallable
 	dataclassIdentifier: str | None = sourceDataclassIdentifier
 	dataclassInstance: str | None = sourceDataclassInstance
-	logicalPathModuleDataclass: str_nameDOTname | None = sourceLogicalPathModuleDataclass
+	logicalPathModuleDataclass: identifierDotAttribute | None = sourceLogicalPathModuleDataclass
 
 	# ========================================
 	# Datatypes
@@ -53,10 +130,25 @@ class RecipeJobTheorem2Numba:
 
 	def _makePathFilename(self,
 			pathRoot: PurePosixPath | None = None,
-			logicalPathINFIX: str_nameDOTname | None = None,
+			logicalPathINFIX: identifierDotAttribute | None = None,
 			filenameStem: str | None = None,
 			fileExtension: str | None = None,
 			) -> PurePosixPath:
+		"""Construct a complete file path from component parts.
+
+		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: Base directory path. Defaults to package path or current directory.
+			logicalPathINFIX: Dot-separated path segments to insert between root and filename.
+			filenameStem: Base filename without extension. Defaults to module identifier.
+			fileExtension: File extension including dot. Defaults to configured extension.
+
+		Returns:
+			Complete file path as a PurePosixPath object.
+		"""
 		if pathRoot is None:
 			pathRoot = self.pathPackage or PurePosixPath(Path.cwd())
 		if logicalPathINFIX:
@@ -71,12 +163,31 @@ class RecipeJobTheorem2Numba:
 
 	@property
 	def pathFilenameModule(self) -> PurePosixPath:
+		"""Generate the complete path and filename for the output module.
+
+		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.
+
+		Returns:
+			Complete path to the target module file.
+		"""
 		if self.pathModule is None:
 			return self._makePathFilename()
 		else:
 			return self._makePathFilename(pathRoot=self.pathModule, logicalPathINFIX=None)
 
-	def __post_init__(self):
+	def __post_init__(self) -> None:
+		"""Initialize computed fields and validate configuration after dataclass creation.
+
+		This method performs post-initialization setup including:
+		1. Deriving module identifier from map shape if not explicitly provided
+		2. Setting default paths for fold total output files
+		3. Creating shattered dataclass metadata for code transformations
+
+		The initialization ensures all computed fields are properly set based on
+		the provided configuration and sensible defaults.
+		"""
 		pathFilenameFoldsTotal = PurePosixPath(getPathFilenameFoldsTotal(self.state.mapShape))
 
 		if self.moduleIdentifier is None: # pyright: ignore[reportUnnecessaryComparison]

mapFolding/someAssemblyRequired/__init__.py

@@ -1,52 +1,54 @@
 """
-Code Transformation Framework for Algorithm Optimization and Testing
+Map folding AST transformation system: Comprehensive framework for converting dataclass-based algorithms to optimized implementations.
 
-This package implements a comprehensive framework for programmatically analyzing, transforming, and generating optimized
-Python code. It serves as the algorithmic optimization engine for the mapFolding package, enabling the conversion of
-readable, functional implementations into highly-optimized variants with verified correctness.
+This subpackage implements a sophisticated Abstract Syntax Tree (AST) transformation system specifically designed to convert high-level dataclass-based map folding algorithms into highly optimized, Numba-compatible implementations. The transformation system addresses a fundamental challenge in high-performance scientific computing: bridging the gap between maintainable, object-oriented algorithm implementations and the performance requirements of computationally intensive mathematical research.
 
-## Core Architecture Components
+The map folding problem domain involves complex combinatorial calculations that can require hours or days to complete for specific dimensional configurations. While dataclass-based implementations provide clean, maintainable interfaces for managing complex mathematical state, these objects cannot be directly processed by Numba's just-in-time compiler, which excels at optimizing operations on primitive values and tuples. This subpackage resolves this architectural tension through systematic AST manipulation that preserves algorithmic correctness while enabling dramatic performance improvements.
 
-1. **AST Manipulation Tools**
-	- Pattern recognition with composable predicates (ifThis)
-	- Node access with consistent interfaces (DOT)
-	- AST traversal and transformation (NodeChanger, NodeTourist)
-	- AST construction with sane defaults (Make)
-	- Node transformation operations (grab, Then)
+## System Architecture
 
-2. **Container and Organization**
-	- Import tracking and management (LedgerOfImports)
-	- Function packaging with dependencies (IngredientsFunction)
-	- Module assembly with structured components (IngredientsModule)
-	- Recipe configuration for generating optimized code (RecipeSynthesizeFlow)
-	- Dataclass decomposition for compatibility (ShatteredDataclass)
+The transformation system operates through a carefully orchestrated sequence of specialized modules, each contributing essential capabilities to the complete transformation process:
 
-3. **Optimization assembly lines**
-	- General-purpose Numba acceleration (makeNumbaFlow)
-	- Job-specific optimization for concrete parameters (makeJobNumba)
-	- Specialized component transformation (decorateCallableWithNumba)
+### Foundation Layer: Pattern Recognition and Structural Analysis
+- `_toolIfThis`: Extended predicate functions for identifying specific code patterns in AST nodes, particularly conditional expressions and control flow structures essential to map folding computations
+- `_toolkitContainers`: Dataclass decomposition containers that extract individual fields, type annotations, and reconstruction logic from dataclass definitions into manipulatable AST components
 
-## Integration with Testing Framework
+### Operational Core: Transformation Implementation
+- `transformationTools`: Core functions executing dataclass decomposition, function signature transformation, and calling convention adaptation that convert dataclass-accepting functions into primitive-parameter equivalents
+- `toolkitNumba`: Numba integration tools providing just-in-time compilation optimization with configurable performance parameters and strategic compiler directive application
 
-The transformation components are extensively tested through the package's test suite, which provides specialized
-fixtures and utilities for validating both the transformation process and the resulting optimized code:
+### Configuration and Orchestration
+- `infoBooth`: Configuration constants, computational complexity estimates, and default identifiers for systematic module generation and optimization decision-making
+- `RecipeJob`: Configuration management dataclasses that coordinate transformation parameters across multiple stages while maintaining consistency between source algorithms and target optimizations
+- `makeAllModules`: Comprehensive transformation orchestration tools that execute complete transformation processes for diverse computational strategies and performance characteristics
+- `makeJobTheorem2Numba`: Specialized job generation implementing the complete transformation sequence to produce standalone, highly optimized computation modules
 
-- **syntheticDispatcherFixture**: Creates and tests a complete Numba-optimized module using RecipeSynthesizeFlow
-	configuration
+### Utility Extensions
+- `getLLVMforNoReason`: Standalone utility for extracting LLVM Intermediate Representation from compiled modules for debugging and optimization analysis
 
-- **test_writeJobNumba**: Tests the job-specific optimization process with RecipeJob
+## Transformation Process
 
-These fixtures enable users to test their own custom recipes and job configurations with minimal effort. See the
-documentation in tests/__init__.py for details on extending the test suite for custom implementations.
+The complete transformation follows a systematic three-stage pattern:
 
-The framework balances multiple optimization levels - from general algorithmic improvements to parameter-specific
-optimizations - while maintaining the ability to verify correctness at each transformation stage through the integrated
-test suite.
+1. **Analysis and Decomposition**: Pattern recognition identifies dataclass structures and dependencies, followed by decomposition into constituent AST components including field definitions, type annotations, and initialization patterns.
+
+2. **Function Optimization**: Core transformations convert functions accepting dataclass parameters into functions accepting individual primitive parameters, with systematic updates to signatures, return types, and calling conventions.
+
+3. **Compilation Integration**: Numba decorators with carefully configured optimization parameters are applied to transformed functions, enabling aggressive just-in-time compilation with performance characteristics suitable for large-scale computational research.
+
+## Generated Module Characteristics
+
+The transformation system produces standalone Python modules with embedded constants replacing parameterized values, eliminated dead code paths, optimized data structures, Numba compilation directives, progress feedback for long-running calculations, and consistent naming conventions with systematic filesystem organization. These modules maintain mathematical correctness while providing significant performance improvements essential to map folding research computational demands.
+
+## Usage Guidance
+
+Begin exploration with `infoBooth` for understanding configuration options and complexity estimates. Proceed to `transformationTools` for core transformation capabilities, then examine `RecipeJob` for orchestration patterns. Advanced users developing custom transformations should study `_toolIfThis` and `_toolkitContainers` for foundational pattern recognition and structural manipulation capabilities.
+
+The transformation system represents the culmination of systematic AST manipulation research, enabling previously intractable calculations through the strategic application of compiler optimization techniques to abstract mathematical algorithms.
 """
 
 from mapFolding.someAssemblyRequired.infoBooth import (
 	dataclassInstanceIdentifierDEFAULT as dataclassInstanceIdentifierDEFAULT,
-	raiseIfNoneGitHubIssueNumber3 as raiseIfNoneGitHubIssueNumber3,
 	sourceCallableDispatcherDEFAULT as sourceCallableDispatcherDEFAULT,
 )
 
@@ -56,8 +58,3 @@ from mapFolding.someAssemblyRequired._toolkitContainers import (
 	DeReConstructField2ast as DeReConstructField2ast,
 	ShatteredDataclass as ShatteredDataclass,
 )
-
-def raiseIfNone[TypeSansNone](returnTarget: TypeSansNone | None) -> TypeSansNone:
-	if returnTarget is None:
-		raise ValueError('Return is None.')
-	return returnTarget

mapFolding/someAssemblyRequired/_toolIfThis.py

@@ -1,22 +1,27 @@
 """
-AST Node Predicate and Access Utilities for Pattern Matching and Traversal
+Map folding AST transformation system: Foundation pattern matching and filtering predicates.
 
-This module provides utilities for accessing and matching AST nodes in a consistent way. It contains three primary
-classes:
+This module establishes the foundational layer of the map folding AST transformation system by
+providing specialized predicate functions for identifying specific code patterns in Abstract
+Syntax Trees. The transformation system converts high-level dataclass-based map folding algorithms
+into optimized computational modules through systematic AST manipulation, beginning with precise
+pattern recognition capabilities defined here.
 
-1. DOT: Provides consistent accessor methods for AST node attributes across different node types, simplifying the access
-	to node properties.
+The predicates extend `astToolkit.IfThis` with domain-specific functions that recognize conditional
+expressions and control flow structures essential to map folding computations. These patterns include
+attribute comparisons against specific values, loop termination conditions based on counting variables,
+and bounds checking operations that characterize map folding algorithm structures.
 
-2. be: Offers type-guard functions that verify AST node types, enabling safe type narrowing for static type checking and
-	improving code safety.
+Pattern recognition serves as the entry point for the broader transformation system that decomposes
+dataclass-dependent algorithms, applies performance optimizations, and generates specialized modules
+optimized for Numba just-in-time compilation. The precise identification of these structural patterns
+enables subsequent transformation stages to apply targeted optimizations while preserving mathematical
+correctness.
 
-3. ifThis: Contains predicate functions for matching AST nodes based on various criteria, enabling precise targeting of
-	nodes for analysis or transformation.
-
-These utilities form the foundation of the pattern-matching component in the AST manipulation framework, working in
-conjunction with the NodeChanger and NodeTourist classes to enable precise and targeted code transformations. Together,
-they implement a declarative approach to AST manipulation that separates node identification (ifThis), type verification
-(be), and data access (DOT).
+Classes:
+    IfThis: Extended predicate class with specialized methods for matching attribute comparisons
+            and control flow patterns involving namespaced identifiers essential to map folding
+            algorithm transformations.
 """
 
 from astToolkit import Be, DOT, IfThis as astToolkit_IfThis
@@ -28,31 +33,88 @@ class IfThis(astToolkit_IfThis):
 	"""
 	Provide predicate functions for matching and filtering AST nodes based on various criteria.
 
-	The ifThis class contains static methods that generate predicate functions used to test whether AST nodes match
+	The IfThis class contains static methods that generate predicate functions used to test whether AST nodes match
 	specific criteria. These predicates can be used with NodeChanger and NodeTourist to identify and process specific
 	patterns in the AST.
 
 	The class provides predicates for matching various node types, attributes, identifiers, and structural patterns,
 	enabling precise targeting of AST elements for analysis or transformation.
 	"""
+
 	@staticmethod
 	def isAttributeNamespaceIdentifierGreaterThan0(namespace: str, identifier: str) -> Callable[[ast.AST], TypeGuard[ast.Compare] | bool]:
+		"""
+		Generate a predicate that matches comparison expressions testing if a namespaced attribute is greater than 0.
+
+		This function creates a predicate that identifies AST nodes representing comparisons
+		of the form `namespace.identifier > 0`. It's commonly used to identify conditional
+		expressions that test positive values of counting variables or similar constructs.
+
+		Parameters:
+			namespace: The namespace or object name containing the attribute
+			identifier: The attribute name to test
+
+		Returns:
+			A predicate function that returns True for Compare nodes matching the pattern
+		"""
 		return lambda node: (Be.Compare(node)
-					and IfThis.isAttributeNamespace_Identifier(namespace, identifier)(DOT.left(node))
+					and IfThis.isAttributeNamespaceIdentifier(namespace, identifier)(DOT.left(node))
 					and Be.Gt(node.ops[0])
 					and IfThis.isConstant_value(0)(node.comparators[0]))
+
 	@staticmethod
 	def isIfAttributeNamespaceIdentifierGreaterThan0(namespace: str, identifier: str) -> Callable[[ast.AST], TypeGuard[ast.If] | bool]:
+		"""
+		Generate a predicate that matches If statements testing if a namespaced attribute is greater than 0.
+
+		This function creates a predicate that identifies AST nodes representing conditional
+		statements of the form `if namespace.identifier > 0:`. It's used to find control
+		flow structures that depend on positive values of specific attributes.
+
+		Parameters:
+			namespace: The namespace or object name containing the attribute
+			identifier: The attribute name to test
+
+		Returns:
+			A predicate function that returns True for If nodes with the specified test condition
+		"""
 		return lambda node: (Be.If(node)
 					and IfThis.isAttributeNamespaceIdentifierGreaterThan0(namespace, identifier)(DOT.test(node)))
 
 	@staticmethod
 	def isWhileAttributeNamespaceIdentifierGreaterThan0(namespace: str, identifier: str) -> Callable[[ast.AST], TypeGuard[ast.While] | bool]:
+		"""
+		Generate a predicate that matches While loops testing if a namespaced attribute is greater than 0.
+
+		This function creates a predicate that identifies AST nodes representing loop
+		statements of the form `while namespace.identifier > 0:`. It's used to find
+		iteration constructs that continue while specific attributes remain positive.
+
+		Parameters:
+			namespace: The namespace or object name containing the attribute
+			identifier: The attribute name to test
+
+		Returns:
+			A predicate function that returns True for While nodes with the specified test condition
+		"""
 		return lambda node: (Be.While(node)
 					and IfThis.isAttributeNamespaceIdentifierGreaterThan0(namespace, identifier)(DOT.test(node)))
-
 	@staticmethod
 	def isAttributeNamespaceIdentifierLessThanOrEqual0(namespace: str, identifier: str) -> Callable[[ast.AST], TypeGuard[ast.Compare] | bool]:
+		"""
+		Generate a predicate that matches comparison expressions testing if a namespaced attribute is less than or equal to 0.
+
+		This function creates a predicate that identifies AST nodes representing comparisons
+		of the form `namespace.identifier <= 0`. It's used to identify conditional
+		expressions that test non-positive values of counting variables or similar constructs.
+
+		Parameters:
+			namespace: The namespace or object name containing the attribute
+			identifier: The attribute name to test
+
+		Returns:
+			A predicate function that returns True for Compare nodes matching the pattern
+		"""
 		return lambda node: (Be.Compare(node)
-					and IfThis.isAttributeNamespace_Identifier(namespace, identifier)(DOT.left(node))
+					and IfThis.isAttributeNamespaceIdentifier(namespace, identifier)(DOT.left(node))
 					and Be.LtE(node.ops[0]))