mapFolding 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

mapFolding/reference/total_countPlus1vsPlusN.py

@@ -1,211 +1,234 @@
+"""
+Comparison of two nearly identical counting implementations with vastly different performance.
+
+This file provides a direct comparison between two variants of the map folding algorithm
+that differ only in their approach to incrementing the folding counter. Despite their apparent
+similarity, one implementation demonstrates orders of magnitude better performance than the other.
+
+Key characteristics:
+- Both implementations use Numba for performance optimization
+- Both use identical data structures and array initializations
+- `foldings_plus_1`: Increments the counter by 1 for each valid folding
+- `foldings`: Increments the counter by n (total leaves) when certain conditions are met
+
+The performance difference illustrates how subtle algorithmic changes can dramatically
+impact computational efficiency, even when the overall algorithm structure remains unchanged.
+This example serves as a compelling demonstration of the importance of algorithm analysis
+and optimization for combinatorial problems.
+
+Note: These functions are isolated for educational purposes to highlight the specific
+optimization technique. The main package uses more comprehensive optimizations derived
+from this and other lessons.
+"""
+
 from numba import njit
 import numpy
 
 @njit(cache=True)
 def foldings_plus_1(p: list[int], computationDivisions: int = 0, computationIndex: int = 0) -> int:
-	n: int = 1  # Total number of leaves
-	for dimension in p:
-		n *= dimension
-
-	d = len(p)  # Number of dimensions
-	# Compute arrays P, C, D as per the algorithm
-	P = numpy.ones(d + 1, dtype=numpy.int64)
-	for i in range(1, d + 1):
-		P[i] = P[i - 1] * p[i - 1]
-
-	# C[i][m] holds the i-th coordinate of leaf m
-	C = numpy.zeros((d + 1, n + 1), dtype=numpy.int64)
-	for i in range(1, d + 1):
-		for m in range(1, n + 1):
-			C[i][m] = ((m - 1) // P[i - 1]) - ((m - 1) // P[i]) * p[i - 1] + 1
-
-	# D[i][l][m] computes the leaf connected to m in section i when inserting l
-	D = numpy.zeros((d + 1, n + 1, n + 1), dtype=numpy.int64)
-	for i in range(1, d + 1):
-		for l in range(1, n + 1):
-			for m in range(1, l + 1):
-				delta = C[i][l] - C[i][m]
-				if delta % 2 == 0:
-					# If delta is even
-					if C[i][m] == 1:
-						D[i][l][m] = m
-					else:
-						D[i][l][m] = m - P[i - 1]
-				else:
-					# If delta is odd
-					if C[i][m] == p[i - 1] or m + P[i - 1] > l:
-						D[i][l][m] = m
-					else:
-						D[i][l][m] = m + P[i - 1]
-	# Initialize arrays/lists
-	A = numpy.zeros(n + 1, dtype=numpy.int64)	   # Leaf above leaf m
-	B = numpy.zeros(n + 1, dtype=numpy.int64)	   # Leaf below leaf m
-	count = numpy.zeros(n + 1, dtype=numpy.int64)   # Counts for potential gaps
-	gapter = numpy.zeros(n + 1, dtype=numpy.int64)  # Indices for gap stack per leaf
-	gap = numpy.zeros(n * n + 1, dtype=numpy.int64) # Stack of potential gaps
-
-
-	# Initialize variables for backtracking
-	total_count = 0  # Total number of foldings
-	g = 0			# Gap index
-	l = 1			# Current leaf
-
-	# Start backtracking loop
-	while l > 0:
-		# If we have processed all leaves, increment total count
-		if l > n:
-			total_count += 1
-		else:
-			dd = 0	 # Number of sections where leaf l is unconstrained
-			gg = g	 # Temporary gap index
-			g = gapter[l - 1]  # Reset gap index for current leaf
-
-			# Count possible gaps for leaf l in each section
-			for i in range(1, d + 1):
-				if D[i][l][l] == l:
-					dd += 1
-				else:
-					m = D[i][l][l]
-					while m != l:
-						if computationDivisions == 0 or l != computationDivisions or m % computationDivisions == computationIndex:
-							gap[gg] = m
-							if count[m] == 0:
-								gg += 1
-							count[m] += 1
-						m = D[i][l][B[m]]
-
-			# If leaf l is unconstrained in all sections, it can be inserted anywhere
-			if dd == d:
-				for m in range(l):
-					gap[gg] = m
-					gg += 1
-
-			# Filter gaps that are common to all sections
-			for j in range(g, gg):
-				gap[g] = gap[j]
-				if count[gap[j]] == d - dd:
-					g += 1
-				count[gap[j]] = 0  # Reset count for next iteration
-
-		# Recursive backtracking steps
-		while l > 0 and g == gapter[l - 1]:
-			l -= 1
-			B[A[l]] = B[l]
-			A[B[l]] = A[l]
-
-		if l > 0:
-			g -= 1
-			A[l] = gap[g]
-			B[l] = B[A[l]]
-			B[A[l]] = l
-			A[B[l]] = l
-			gapter[l] = g  # Save current gap index
-			l += 1		 # Move to next leaf
-
-	return total_count
+    n: int = 1  # Total number of leaves
+    for dimension in p:
+        n *= dimension
+
+    d = len(p)  # Number of dimensions
+    # Compute arrays P, C, D as per the algorithm
+    P = numpy.ones(d + 1, dtype=numpy.int64)
+    for i in range(1, d + 1):
+        P[i] = P[i - 1] * p[i - 1]
+
+    # C[i][m] holds the i-th coordinate of leaf m
+    C = numpy.zeros((d + 1, n + 1), dtype=numpy.int64)
+    for i in range(1, d + 1):
+        for m in range(1, n + 1):
+            C[i][m] = ((m - 1) // P[i - 1]) - ((m - 1) // P[i]) * p[i - 1] + 1
+
+    # D[i][l][m] computes the leaf connected to m in section i when inserting l
+    D = numpy.zeros((d + 1, n + 1, n + 1), dtype=numpy.int64)
+    for i in range(1, d + 1):
+        for l in range(1, n + 1):
+            for m in range(1, l + 1):
+                delta = C[i][l] - C[i][m]
+                if delta % 2 == 0:
+                    # If delta is even
+                    if C[i][m] == 1:
+                        D[i][l][m] = m
+                    else:
+                        D[i][l][m] = m - P[i - 1]
+                else:
+                    # If delta is odd
+                    if C[i][m] == p[i - 1] or m + P[i - 1] > l:
+                        D[i][l][m] = m
+                    else:
+                        D[i][l][m] = m + P[i - 1]
+    # Initialize arrays/lists
+    A = numpy.zeros(n + 1, dtype=numpy.int64)	   # Leaf above leaf m
+    B = numpy.zeros(n + 1, dtype=numpy.int64)	   # Leaf below leaf m
+    count = numpy.zeros(n + 1, dtype=numpy.int64)   # Counts for potential gaps
+    gapter = numpy.zeros(n + 1, dtype=numpy.int64)  # Indices for gap stack per leaf
+    gap = numpy.zeros(n * n + 1, dtype=numpy.int64) # Stack of potential gaps
+
+
+    # Initialize variables for backtracking
+    total_count = 0  # Total number of foldings
+    g = 0            # Gap index
+    l = 1            # Current leaf
+
+    # Start backtracking loop
+    while l > 0:
+        # If we have processed all leaves, increment total count
+        if l > n:
+            total_count += 1
+        else:
+            dd = 0    # Number of sections where leaf l is unconstrained
+            gg = g    # Temporary gap index
+            g = gapter[l - 1]  # Reset gap index for current leaf
+
+            # Count possible gaps for leaf l in each section
+            for i in range(1, d + 1):
+                if D[i][l][l] == l:
+                    dd += 1
+                else:
+                    m = D[i][l][l]
+                    while m != l:
+                        if computationDivisions == 0 or l != computationDivisions or m % computationDivisions == computationIndex:
+                            gap[gg] = m
+                            if count[m] == 0:
+                                gg += 1
+                            count[m] += 1
+                        m = D[i][l][B[m]]
+
+            # If leaf l is unconstrained in all sections, it can be inserted anywhere
+            if dd == d:
+                for m in range(l):
+                    gap[gg] = m
+                    gg += 1
+
+            # Filter gaps that are common to all sections
+            for j in range(g, gg):
+                gap[g] = gap[j]
+                if count[gap[j]] == d - dd:
+                    g += 1
+                count[gap[j]] = 0  # Reset count for next iteration
+
+        # Recursive backtracking steps
+        while l > 0 and g == gapter[l - 1]:
+            l -= 1
+            B[A[l]] = B[l]
+            A[B[l]] = A[l]
+
+        if l > 0:
+            g -= 1
+            A[l] = gap[g]
+            B[l] = B[A[l]]
+            B[A[l]] = l
+            A[B[l]] = l
+            gapter[l] = g  # Save current gap index
+            l += 1		 # Move to next leaf
+
+    return total_count
 
 @njit(cache=True)
 def foldings(p: list[int], computationDivisions: int = 0, computationIndex: int = 0) -> int:
-	n: int = 1  # Total number of leaves
-	for dimension in p:
-		n *= dimension
-
-	d = len(p)  # Number of dimensions
-	# Compute arrays P, C, D as per the algorithm
-	P = numpy.ones(d + 1, dtype=numpy.int64)
-	for i in range(1, d + 1):
-		P[i] = P[i - 1] * p[i - 1]
-
-	# C[i][m] holds the i-th coordinate of leaf m
-	C = numpy.zeros((d + 1, n + 1), dtype=numpy.int64)
-	for i in range(1, d + 1):
-		for m in range(1, n + 1):
-			C[i][m] = ((m - 1) // P[i - 1]) - ((m - 1) // P[i]) * p[i - 1] + 1
-			# C[i][m] = ((m - 1) // P[i - 1]) % p[i - 1] + 1 # NOTE different, but either one works
-
-	# D[i][l][m] computes the leaf connected to m in section i when inserting l
-	D = numpy.zeros((d + 1, n + 1, n + 1), dtype=numpy.int64)
-	for i in range(1, d + 1):
-		for l in range(1, n + 1):
-			for m in range(1, l + 1):
-				delta = C[i][l] - C[i][m]
-				if delta % 2 == 0:
-					# If delta is even
-					if C[i][m] == 1:
-						D[i][l][m] = m
-					else:
-						D[i][l][m] = m - P[i - 1]
-				else:
-					# If delta is odd
-					if C[i][m] == p[i - 1] or m + P[i - 1] > l:
-						D[i][l][m] = m
-					else:
-						D[i][l][m] = m + P[i - 1]
-	# Initialize arrays/lists
-	A = numpy.zeros(n + 1, dtype=numpy.int64)	   # Leaf above leaf m
-	B = numpy.zeros(n + 1, dtype=numpy.int64)	   # Leaf below leaf m
-	count = numpy.zeros(n + 1, dtype=numpy.int64)   # Counts for potential gaps
-	gapter = numpy.zeros(n + 1, dtype=numpy.int64)  # Indices for gap stack per leaf
-	gap = numpy.zeros(n * n + 1, dtype=numpy.int64) # Stack of potential gaps
-
-
-	# Initialize variables for backtracking
-	total_count = 0  # Total number of foldings
-	g = 0			# Gap index
-	l = 1			# Current leaf
-
-	# Start backtracking loop
-	while l > 0:
-		if l <= 1 or B[0] == 1: # NOTE different
-			# NOTE the above `if` statement encloses the the if/else block below
-			# NOTE these changes increase the throughput by more than an order of magnitude
-			if l > n:
-				total_count += n
-			else:
-				dd = 0	 # Number of sections where leaf l is unconstrained
-				gg = gapter[l - 1]  # Track possible gaps # NOTE different, but not important
-				g = gg # NOTE different, but not important
-
-				# Count possible gaps for leaf l in each section
-				for i in range(1, d + 1):
-					if D[i][l][l] == l:
-						dd += 1
-					else:
-						m = D[i][l][l]
-						while m != l:
-							if computationDivisions == 0 or l != computationDivisions or m % computationDivisions == computationIndex:
-								gap[gg] = m
-								if count[m] == 0:
-									gg += 1
-								count[m] += 1
-							m = D[i][l][B[m]]
-
-				# If leaf l is unconstrained in all sections, it can be inserted anywhere
-				if dd == d:
-					for m in range(l):
-						gap[gg] = m
-						gg += 1
-
-				# Filter gaps that are common to all sections
-				for j in range(g, gg):
-					gap[g] = gap[j]
-					if count[gap[j]] == d - dd:
-						g += 1
-					count[gap[j]] = 0  # Reset count for next iteration
-
-		# Recursive backtracking steps
-		while l > 0 and g == gapter[l - 1]:
-			l -= 1
-			B[A[l]] = B[l]
-			A[B[l]] = A[l]
-
-		if l > 0:
-			g -= 1
-			A[l] = gap[g]
-			B[l] = B[A[l]]
-			B[A[l]] = l
-			A[B[l]] = l
-			gapter[l] = g  # Save current gap index
-			l += 1		 # Move to next leaf
-
-	return total_count
+    n: int = 1  # Total number of leaves
+    for dimension in p:
+        n *= dimension
+
+    d = len(p)  # Number of dimensions
+    # Compute arrays P, C, D as per the algorithm
+    P = numpy.ones(d + 1, dtype=numpy.int64)
+    for i in range(1, d + 1):
+        P[i] = P[i - 1] * p[i - 1]
+
+    # C[i][m] holds the i-th coordinate of leaf m
+    C = numpy.zeros((d + 1, n + 1), dtype=numpy.int64)
+    for i in range(1, d + 1):
+        for m in range(1, n + 1):
+            C[i][m] = ((m - 1) // P[i - 1]) - ((m - 1) // P[i]) * p[i - 1] + 1
+            # C[i][m] = ((m - 1) // P[i - 1]) % p[i - 1] + 1 # NOTE different, but either one works
+
+    # D[i][l][m] computes the leaf connected to m in section i when inserting l
+    D = numpy.zeros((d + 1, n + 1, n + 1), dtype=numpy.int64)
+    for i in range(1, d + 1):
+        for l in range(1, n + 1):
+            for m in range(1, l + 1):
+                delta = C[i][l] - C[i][m]
+                if delta % 2 == 0:
+                    # If delta is even
+                    if C[i][m] == 1:
+                        D[i][l][m] = m
+                    else:
+                        D[i][l][m] = m - P[i - 1]
+                else:
+                    # If delta is odd
+                    if C[i][m] == p[i - 1] or m + P[i - 1] > l:
+                        D[i][l][m] = m
+                    else:
+                        D[i][l][m] = m + P[i - 1]
+    # Initialize arrays/lists
+    A = numpy.zeros(n + 1, dtype=numpy.int64)       # Leaf above leaf m
+    B = numpy.zeros(n + 1, dtype=numpy.int64)       # Leaf below leaf m
+    count = numpy.zeros(n + 1, dtype=numpy.int64)   # Counts for potential gaps
+    gapter = numpy.zeros(n + 1, dtype=numpy.int64)  # Indices for gap stack per leaf
+    gap = numpy.zeros(n * n + 1, dtype=numpy.int64) # Stack of potential gaps
+
+
+    # Initialize variables for backtracking
+    total_count = 0  # Total number of foldings
+    g = 0            # Gap index
+    l = 1            # Current leaf
+
+    # Start backtracking loop
+    while l > 0:
+        if l <= 1 or B[0] == 1: # NOTE different
+            # NOTE the above `if` statement encloses the the if/else block below
+            # NOTE these changes increase the throughput by more than an order of magnitude
+            if l > n:
+                total_count += n
+            else:
+                dd = 0    # Number of sections where leaf l is unconstrained
+                gg = gapter[l - 1]  # Track possible gaps # NOTE different, but not important
+                g = gg # NOTE different, but not important
+
+                # Count possible gaps for leaf l in each section
+                for i in range(1, d + 1):
+                    if D[i][l][l] == l:
+                        dd += 1
+                    else:
+                        m = D[i][l][l]
+                        while m != l:
+                            if computationDivisions == 0 or l != computationDivisions or m % computationDivisions == computationIndex:
+                                gap[gg] = m
+                                if count[m] == 0:
+                                    gg += 1
+                                count[m] += 1
+                            m = D[i][l][B[m]]
+
+                # If leaf l is unconstrained in all sections, it can be inserted anywhere
+                if dd == d:
+                    for m in range(l):
+                        gap[gg] = m
+                        gg += 1
+
+                # Filter gaps that are common to all sections
+                for j in range(g, gg):
+                    gap[g] = gap[j]
+                    if count[gap[j]] == d - dd:
+                        g += 1
+                    count[gap[j]] = 0  # Reset count for next iteration
+
+        # Recursive backtracking steps
+        while l > 0 and g == gapter[l - 1]:
+            l -= 1
+            B[A[l]] = B[l]
+            A[B[l]] = A[l]
+
+        if l > 0:
+            g -= 1
+            A[l] = gap[g]
+            B[l] = B[A[l]]
+            B[A[l]] = l
+            A[B[l]] = l
+            gapter[l] = g  # Save current gap index
+            l += 1         # Move to next leaf
+
+    return total_count

mapFolding/someAssemblyRequired/__init__.py

@@ -1,3 +1,29 @@
+"""
+Code transformation framework for algorithmic optimization.
+
+This package implements a comprehensive framework for programmatically analyzing,
+transforming, and generating Python code. It enables sophisticated algorithm optimization
+through abstract syntax tree (AST) manipulation, allowing algorithms to be transformed
+from a readable, functional implementation into highly-optimized variants tailored for
+different execution environments or specific computational tasks.
+
+Core capabilities:
+1. AST Pattern Recognition - Precisely identify and match code patterns using composable predicates
+2. Algorithm Transformation - Convert functional state-based implementations to primitive operations
+3. Dataclass "Shattering" - Decompose complex state objects into primitive components
+4. Performance Optimization - Apply domain-specific optimizations for numerical computation
+5. Code Generation - Generate specialized implementations with appropriate imports and syntax
+
+The transformation pipeline supports multiple optimization targets, from general-purpose
+acceleration to generating highly-specialized variants optimized for specific input parameters.
+This multi-level transformation approach allows for both development flexibility and
+runtime performance, preserving algorithm readability in the source while enabling
+maximum execution speed in production.
+
+These tools were developed for map folding computation optimization but are designed as
+general-purpose utilities applicable to a wide range of code transformation scenarios,
+particularly for numerically-intensive algorithms that benefit from just-in-time compilation.
+"""
 from mapFolding.someAssemblyRequired.transformationTools import (
 	ast_Identifier as ast_Identifier,
 	extractClassDef as extractClassDef,
@@ -5,6 +31,7 @@ from mapFolding.someAssemblyRequired.transformationTools import (
 	ifThis as ifThis,
 	IngredientsFunction as IngredientsFunction,
 	IngredientsModule as IngredientsModule,
+	inlineThisFunctionWithTheseValues as inlineThisFunctionWithTheseValues,
 	LedgerOfImports as LedgerOfImports,
 	Make as Make,
 	makeDictionaryReplacementStatements as makeDictionaryReplacementStatements,
@@ -13,5 +40,7 @@ from mapFolding.someAssemblyRequired.transformationTools import (
 	RecipeSynthesizeFlow as RecipeSynthesizeFlow,
 	strDotStrCuzPyStoopid as strDotStrCuzPyStoopid,
 	Then as Then,
+	write_astModule as write_astModule,
 	Z0Z_executeActionUnlessDescendantMatches as Z0Z_executeActionUnlessDescendantMatches,
+	Z0Z_replaceMatchingASTnodes as Z0Z_replaceMatchingASTnodes,
 	)

mapFolding/someAssemblyRequired/getLLVMforNoReason.py

@@ -1,20 +1,38 @@
+"""
+Utility for extracting LLVM IR from compiled Python modules.
+
+This module provides functionality to extract and save the LLVM Intermediate Representation (IR)
+generated when Numba compiles Python functions. It implements a simple interface that:
+
+1. Imports a specified Python module from its file path
+2. Extracts the LLVM IR from a specified function within that module
+3. Writes the IR to a file with the same base name but with the .ll extension
+
+The extracted LLVM IR can be valuable for debugging, optimization analysis, or educational
+purposes, as it provides a view into how high-level Python code is translated into
+lower-level representations for machine execution.
+
+While originally part of a tighter integration with the code generation pipeline,
+this module now operates as a standalone utility that can be applied to any module
+containing Numba-compiled functions.
+"""
 from importlib.machinery import ModuleSpec
+from pathlib import Path
 from types import ModuleType
 import importlib.util
 import llvmlite.binding
-import pathlib
 
-def writeModuleLLVM(pathFilename: pathlib.Path, identifierCallable: str) -> pathlib.Path:
-	"""Import the generated module directly and get its LLVM IR."""
-	specTarget: ModuleSpec | None = importlib.util.spec_from_file_location("generatedModule", pathFilename)
-	if specTarget is None or specTarget.loader is None:
-		raise ImportError(f"Could not create module spec or loader for {pathFilename}")
-	moduleTarget: ModuleType = importlib.util.module_from_spec(specTarget)
-	specTarget.loader.exec_module(moduleTarget)
+def writeModuleLLVM(pathFilename: Path, identifierCallable: str) -> Path:
+    """Import the generated module directly and get its LLVM IR."""
+    specTarget: ModuleSpec | None = importlib.util.spec_from_file_location("generatedModule", pathFilename)
+    if specTarget is None or specTarget.loader is None:
+        raise ImportError(f"Could not create module spec or loader for {pathFilename}")
+    moduleTarget: ModuleType = importlib.util.module_from_spec(specTarget)
+    specTarget.loader.exec_module(moduleTarget)
 
-	# Get LLVM IR and write to file
-	linesLLVM = moduleTarget.__dict__[identifierCallable].inspect_llvm()[()]
-	moduleLLVM: llvmlite.binding.ModuleRef = llvmlite.binding.module.parse_assembly(linesLLVM)
-	pathFilenameLLVM: pathlib.Path = pathFilename.with_suffix(".ll")
-	pathFilenameLLVM.write_text(str(moduleLLVM))
-	return pathFilenameLLVM
+    # Get LLVM IR and write to file
+    linesLLVM = moduleTarget.__dict__[identifierCallable].inspect_llvm()[()]
+    moduleLLVM: llvmlite.binding.ModuleRef = llvmlite.binding.module.parse_assembly(linesLLVM)
+    pathFilenameLLVM: Path = pathFilename.with_suffix(".ll")
+    pathFilenameLLVM.write_text(str(moduleLLVM))
+    return pathFilenameLLVM

mapFolding/someAssemblyRequired/ingredientsNumba.py

@@ -1,7 +1,28 @@
+"""
+Numba-specific ingredients for optimized code generation.
+
+This module provides specialized tools, constants, and types specifically designed
+for transforming Python code into Numba-accelerated implementations. It implements:
+
+1. A range of Numba jit decorator configurations for different optimization scenarios
+2. Functions to identify and manipulate Numba decorators in abstract syntax trees
+3. Utilities for applying appropriate Numba typing to transformed code
+4. Parameter management for Numba compilation options
+
+The configurations range from conservative options that prioritize compatibility and
+error detection to aggressive optimizations that maximize performance at the cost of
+flexibility. While this module specifically targets Numba, its design follows the pattern
+of generic code transformation tools in the package, allowing similar approaches to be
+applied to other acceleration technologies.
+
+This module works in conjunction with transformation tools to convert the general-purpose
+algorithm implementation into a highly-optimized Numba version.
+"""
+
 from collections.abc import Callable, Sequence
 from mapFolding.someAssemblyRequired import ifThis, IngredientsFunction, Make
 from numba.core.compiler import CompilerBase as numbaCompilerBase
-from typing import Any, TYPE_CHECKING, Final, cast
+from typing import Any, cast, Final, TYPE_CHECKING
 import ast
 
 try: