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

mapfolding-0.12.2.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: mapFolding
+Version: 0.12.2
+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
+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
+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 :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Z0Z_tools
+Requires-Dist: astToolkit>=0.5.0
+Requires-Dist: autoflake
+Requires-Dist: numba
+Requires-Dist: numba_progress
+Requires-Dist: numpy
+Requires-Dist: platformdirs
+Requires-Dist: python_minifier
+Requires-Dist: sympy
+Requires-Dist: tomli
+Provides-Extra: testing
+Requires-Dist: mypy; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: pytest-env; extra == "testing"
+Requires-Dist: pytest-xdist; extra == "testing"
+Requires-Dist: pyupgrade; extra == "testing"
+Requires-Dist: ruff; extra == "testing"
+Requires-Dist: setuptools-scm; extra == "testing"
+Dynamic: license-file
+
+# mapFolding
+
+[![pip install mapFolding](https://img.shields.io/badge/pip%20install-mapFolding-gray.svg?colorB=3b434b)](https://pypi.org/project/mapFolding/)
+[![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
+[![License: CC-BY-NC-4.0](https://img.shields.io/badge/License-CC_BY--NC_4.0-3b434b)](https://creativecommons.org/licenses/by-nc/4.0/)
+
+A computational framework that starts with Lunnon's 1971 algorithm for counting distinct ways to fold maps and improves it. Plus there is a comprehensive AST transformation system for transforming algorithms for optimization and research.
+
+(Yo, the rest is AI generated and I don't have the energy to proofread it. This package helped me compute two previously unknown values: I'm sure others can improve it.)
+
+## The Mathematical Problem
+
+Map folding is a combinatorial problem: given a rectangular grid of unit squares, how many distinct ways can you fold it? "Distinct" means that foldings producing identical final shapes are counted as one. This problem connects to combinatorial geometry, integer sequences, and computational complexity theory.
+
+The calculations extend the Online Encyclopedia of Integer Sequences (OEIS):
+
+- **A001415**: 2×n strips (computed through n=20 for the first time)
+- **A001418**: n×n squares
+- **A001416**: 3×n strips
+- **A001417**: n-dimensional hypercubes
+- **A195646**: 3×3×...×3 hypercubes
+
+```python
+from mapFolding import oeisIDfor_n
+
+# How many ways can you fold a 2×4 strip?
+foldsTotal = oeisIDfor_n('A001415', 4)
+```
+
+## The Computational Challenge
+
+For larger maps, these calculations require hours or days to complete. A 2×20 strip requires processing leaves through billions of recursive operations. The package addresses this through systematic algorithm transformation: converting readable Python implementations into specialized, Numba-optimized modules that achieve order-of-magnitude performance improvements.
+
+## What This Package Provides
+
+### Core Functionality
+
+- **Complete implementation** of Lunnon's recursive algorithm
+- **Mathematical validation** through OEIS integration and caching
+- **Type-safe computational state** management with automatic initialization
+- **Result persistence** for long-running calculations
+
+### Algorithm Transformation System
+
+- **AST manipulation framework** for converting dataclass-based algorithms to optimized implementations
+- **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
+
+### Educational Resources
+
+- **Historical implementations** showing algorithm evolution from 1971 to present
+- **Performance comparison** studies demonstrating optimization techniques
+- **Complete test suite** with patterns for validating custom implementations
+- **Reference documentation** for extending the transformation framework
+
+## Use Cases
+
+**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.
+
+**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
+- `jobs/`: Generated optimized modules for specific calculations
+
+## Performance Characteristics
+
+- **Pure Python baseline**: Educational implementations for understanding
+- **NumPy optimization**: ~10× improvement through vectorized operations
+- **Numba compilation**: ~100× improvement through native code generation
+- **Specialized modules**: ~1000× improvement through static optimization and embedded constants
+
+Actual performance varies by map dimensions and available hardware.
+
+## My recovery
+
+[![Static Badge](https://img.shields.io/badge/2011_August-Homeless_since-blue?style=flat)](https://HunterThinks.com/support)
+[![YouTube Channel Subscribers](https://img.shields.io/youtube/channel/subscribers/UC3Gx7kz61009NbhpRtPP7tw)](https://www.youtube.com/@HunterHogan)
+
+## How to code
+
+Coding One Step at a Time:
+
+0. WRITE CODE.
+1. Don't write stupid code that's hard to revise.
+2. Write good code.
+3. When revising, write better code.
+
+[![CC-BY-NC-4.0](https://github.com/hunterhogan/mapFolding/blob/main/CC-BY-NC-4.0.svg)](https://creativecommons.org/licenses/by-nc/4.0/)

mapfolding-0.12.2.dist-info/RECORD

@@ -0,0 +1,53 @@
+mapFolding/__init__.py,sha256=wXJ0dhpZUfiXPvh4RQ11FKDJEzV5OYUs8USKFaEXqQ0,3653
+mapFolding/_theSSOT.py,sha256=JNoyZ86gym5z0DS2kruidDJ3zdYAShuqnCLJ85t2TVM,6168
+mapFolding/basecamp.py,sha256=6jLA_41BB86CJD6E3vLr-SV0BiGEfwzcfeOLgujlyZM,9008
+mapFolding/beDRY.py,sha256=S0HO2bX8afDR6mV0xyIsEGBeG4-pRC3YH9jMAWSHpCM,13891
+mapFolding/daoOfMapFolding.py,sha256=ncTIiBfTsM8SNVx9qefZ0bBcBtviWLSk4iPv3Z9nGiE,5442
+mapFolding/dataBaskets.py,sha256=oO9f0PUf3AdNguaKEYnBpk31VhK8NPFMK5GiBSDVFIw,13101
+mapFolding/datatypes.py,sha256=5BLjUv5S6A_0Q23erRGIN8MMm2WD3BVKnH2gfEdZlcs,5189
+mapFolding/filesystemToolkit.py,sha256=ACiNUE7L5MKjllBbUVvzdgYdILXGiOVyl81fDGPwaNc,10254
+mapFolding/oeis.py,sha256=hf3AgQOiFf2Gs0WbS3JYIVNgfPfVlp0T0ZLDvfvi4Lg,21978
+mapFolding/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mapFolding/reference/__init__.py,sha256=GKcSgYE49NcTISx-JZbELXyq-eRkMeTL5g4DXInWFw0,2206
+mapFolding/reference/flattened.py,sha256=QK1xG9SllqCoi68e86Hyl9d9ATUAAFNpTQI-3zmcp5I,16072
+mapFolding/reference/hunterNumba.py,sha256=iLfyqwGdAh6c5GbapnKsWhAsNsR3O-fyGGHAdohluLw,7258
+mapFolding/reference/irvineJavaPort.py,sha256=UEfIX4QbPLl5jnyfYIyX5YRR3_rYvPUikK8jLehsFko,4076
+mapFolding/reference/jaxCount.py,sha256=TuDNKOnyhQfuixKmIxO9Algv7dvy7KMGhgsV3h96FGE,14853
+mapFolding/reference/lunnonNumpy.py,sha256=mMgrgbrBpe4nmo72ThEI-MGH0OwEHmfMPczSXHp2qKo,4357
+mapFolding/reference/lunnonWhile.py,sha256=ZL8GAQtPs5nJZSgoDl5USrLSS_zs03y98y1Z9E4jOmQ,3799
+mapFolding/reference/rotatedEntryPoint.py,sha256=5ughpKUT2JQhoAKgoDUdYNjgWQYPGV8v-7dWEAdDmfE,10274
+mapFolding/reference/total_countPlus1vsPlusN.py,sha256=yJZAVLVdoXqHag2_N6_6CT-Q6HXBgRro-eny93-Rlpw,9307
+mapFolding/reference/jobsCompleted/__init__.py,sha256=TU93ZGUW1xEkT6d9mQFn_rp5DvRy0ZslEB2Q6MF5ZDc,2596
+mapFolding/reference/jobsCompleted/[2x19]/p2x19.py,sha256=_tvYtfzMWVo2VtUbIAieoscb4N8FFflgTdW4-ljBUuA,19626
+mapFolding/reference/jobsCompleted/p2x19/p2x19.py,sha256=eZEw4Me4ocTt6VXoK2-Sbd5SowZtxRIbN9dZmc7OCVg,6395
+mapFolding/someAssemblyRequired/RecipeJob.py,sha256=kFn27dMWg1k5q5RsU2kw5zXT3TRmUzYHE9EIUdAGvfM,10641
+mapFolding/someAssemblyRequired/__init__.py,sha256=F3MMU6QciBqL8G4cjn_ELCHEnpjytorUQn-vG9t696Q,5769
+mapFolding/someAssemblyRequired/_toolIfThis.py,sha256=mqIZQ_HLkR-5z3_gIghIeQ_WY1XkjVHp9iC1TrPiI9Y,5923
+mapFolding/someAssemblyRequired/_toolkitContainers.py,sha256=ZAwfH6yRunUzSVzl2VZDvJD7lyN7WL6Md7F6Q7suW30,13682
+mapFolding/someAssemblyRequired/getLLVMforNoReason.py,sha256=9RPU6vK_eUg64GtVFI_nZnvUryXw8gfHJs9NyDYHIvg,2745
+mapFolding/someAssemblyRequired/infoBooth.py,sha256=GWiqnHbqk7te_pvVuk4G_gbFa_W2aeSx19w4pakvqfM,2300
+mapFolding/someAssemblyRequired/makeAllModules.py,sha256=RC4FmWyue2reiPttfLEtc7kFGYgp7dR4qBHnOREuYpo,42770
+mapFolding/someAssemblyRequired/makeJobTheorem2Numba.py,sha256=658vw0JZk-9dMIE_18Op8xY1vxwoLc2K-TQaslGtw58,18372
+mapFolding/someAssemblyRequired/toolkitNumba.py,sha256=nHLkGZ9P0p3NJkiqJFTxej9z0H1BvWWvmSN27rTExqU,14563
+mapFolding/someAssemblyRequired/transformationTools.py,sha256=gveR9Gqgo3JJhMXtHIFTyu0RbgwoTkH-5X7dwiA4jpM,11476
+mapFolding/syntheticModules/__init__.py,sha256=evVFqhCGa-WZKDiLcnQWjs-Bj34eRnfSLqz_d7dFYZY,83
+mapFolding/syntheticModules/countParallel.py,sha256=OK_IB9w4yy9MMAiGvkei5ezPm_00v2nYjPrQZ_IlELg,7733
+mapFolding/syntheticModules/daoOfMapFolding.py,sha256=cfWPABtXyCxJ0BwPI7rhfLh_2UYV_XKAL8lJ4GLNXaQ,5896
+mapFolding/syntheticModules/dataPacking.py,sha256=m_eOZ7sMXIQ9jY5EvC3qgitQTY60n6rksy0ACMJOIC8,2292
+mapFolding/syntheticModules/initializeCount.py,sha256=nWSlJMMfIM3DvZxMn6ISQusUJqRYAjKQyLF5hwLEdBQ,3119
+mapFolding/syntheticModules/theorem2.py,sha256=9jrbZNNX4BWYZW1S0JjvRY2k7RU7I1RNUMV7JdCt1ZY,3017
+mapFolding/syntheticModules/theorem2Numba.py,sha256=-cKjNyxgUMFhEyFVs0VJ7hw4LfrV0WSNK5tPYbQ1oNU,3369
+mapFolding/syntheticModules/theorem2Trimmed.py,sha256=DHW3NxBdtABQYBKm2WRvfQ5kzc2_UwGI2h4ePuYEJoM,2685
+mapfolding-0.12.2.dist-info/licenses/LICENSE,sha256=NxH5Y8BdC-gNU-WSMwim3uMbID2iNDXJz7fHtuTdXhk,19346
+tests/__init__.py,sha256=5RdiZYAl8nPIM1sxB_D0CsN6J8173LOZ0hpR3geTHAU,1312
+tests/conftest.py,sha256=eBo0IIm98402hl_XW5nT06cUvW25ciItv1_zZdM152E,11126
+tests/test_computations.py,sha256=NDOT1kUdY2w-hbxdGhUsr4N4yFjwJW30AnfrDiYYKM0,5184
+tests/test_filesystem.py,sha256=IXTeyfifXe6vLizCo8BiSn5Yx9DEKYEc_hoJRKhQFNk,3899
+tests/test_oeis.py,sha256=KjG10lH5vVLPG5bicdsVt373QeMrHirFJUpO1BR_sos,6272
+tests/test_other.py,sha256=a42U3KB5IlrQNj63nRyg-KLdvF1QTH2aAsH9JpQnl3Q,4933
+tests/test_tasks.py,sha256=-OrpXAlkPMP4pRCW-wAYPd_olf3L_a9dMsJZCOlSUNE,4041
+mapfolding-0.12.2.dist-info/METADATA,sha256=6URs4ApQHjsH3bN7QniWEvCBioRrz0y0h6q9qI6YI28,7977
+mapfolding-0.12.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mapfolding-0.12.2.dist-info/entry_points.txt,sha256=F3OUeZR1XDTpoH7k3wXuRb3KF_kXTTeYhu5AGK1SiOQ,146
+mapfolding-0.12.2.dist-info/top_level.txt,sha256=1gP2vFaqPwHujGwb3UjtMlLEGN-943VSYFR7V4gDqW8,17
+mapfolding-0.12.2.dist-info/RECORD,,

{mapfolding-0.12.1.dist-info → mapfolding-0.12.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.7.1)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

tests/__init__.py

@@ -1,44 +1,28 @@
-"""
-Map Folding Test Suite and Validation Framework
-
-This test suite provides comprehensive testing capabilities for the mapFolding package
-and its optimization framework. It is specifically designed to enable both package
-maintenance and custom extension testing, making it easy for users to validate their
-own recipe configurations and job implementations.
-
-## Key Testing Capabilities
-
-1. **Algorithm Validation**
-   - Tests core algorithm correctness against known OEIS sequence values
-   - Validates both sequential and parallel execution paths
-   - Ensures consistency across different implementation strategies
-
-2. **Code Generation Testing**
-   - Tests the AST transformation assembly line from source to optimized implementations
-   - Validates that generated Numba-accelerated modules produce correct results
-   - Ensures robust code generation across different parameter sets
-
-3. **Job-Specific Testing**
-   - Tests specialized job module generation for specific map shapes
-   - Validates execution of the generated modules
-   - Verifies correct output file creation and value storage
-
-## Testing Your Own Implementations
-
-This suite is designed to make it easy to test your custom recipes and jobs:
-
-### For Custom Recipes (RecipeSynthesizeFlow):
-Copy and adapt the `syntheticDispatcherFixture` and associated tests from
-`test_computations.py` to validate your customized code transformation assembly lines.
-
-### For Custom Jobs (RecipeJob):
-Copy and adapt the `test_writeJobNumba` function to test specialized job modules
-for specific map shapes with your custom configurations.
-
-The entire test infrastructure is built on fixtures and utilities that handle
-complex setup and validation, allowing you to focus on your implementation details
-while leveraging the existing validation framework.
-
-See the module docstrings in `test_computations.py` and `conftest.py` for detailed
-guidance on adapting these tests for your own purposes.
-"""
+"""Test suite for the mapFolding package.
+
+This test suite provides comprehensive validation of map folding computations,
+file system operations, OEIS integration, task division, and foundational
+utilities. The tests are designed to support multiple audiences and use cases.
+
+Test Module Organization:
+- conftest.py: Testing infrastructure and shared fixtures
+- test_computations.py: Core mathematical validation and algorithm testing
+- test_filesystem.py: File operations and path management
+- test_oeis.py: OEIS sequence integration and caching
+- test_other.py: Foundational utilities and data validation
+- test_tasks.py: Task division and work distribution
+
+For Contributors:
+The test suite follows Domain-Driven Design principles, organizing tests around
+mathematical concepts rather than implementation details. Use the existing
+patterns as templates when adding new functionality.
+
+For Users Adding Custom Modules:
+The test_computations.py module provides the most relevant examples for testing
+custom computational approaches. The standardized testing functions in conftest.py
+ensure consistent error reporting across all tests.
+
+For AI Assistants:
+The testing framework emphasizes readable, predictable patterns that maintain
+mathematical correctness while supporting code evolution and optimization.
+"""

tests/conftest.py

@@ -1,62 +1,30 @@
-"""
-Test Configuration and Shared Fixtures
-
-This module provides the foundation for the mapFolding test suite, offering fixtures and
-utilities that enable consistent, reliable testing across the package. It's particularly
-valuable for users who want to test their own customizations.
-
-## Key Testing Facilities
-
-### File System Management
-
-The module implements a robust temporary file system management approach:
-- Creates a registry of temporary files and directories
-- Ensures proper cleanup after tests
-- Provides fixtures that automatically handle cleanup
-
-### Test-Specific Fixtures
-
-Several fixtures enable specialized testing scenarios:
-
-1. **Dispatcher Fixtures**:
-   - `useThisDispatcher`: Core fixture for patching the algorithm dispatcher
-   - `useAlgorithmSourceDispatcher`: Tests with the source algorithm implementation
-   - `syntheticDispatcherFixture`: Tests with generated Numba-optimized implementation
-
-2. **Test Data Fixtures**:
-   - `oeisID`, `oeisID_1random`: Provide OEIS sequence identifiers for testing
-   - `listDimensionsTestCountFolds`: Provides dimensions suitable for algorithm testing
-   - `listDimensionsTestParallelization`: Provides dimensions suitable for parallel testing
-   - `mapShapeTestFunctionality`: Provides map shapes suitable for functional testing
-
-3. **Path Fixtures**:
-   - `pathTmpTesting`: Creates a temporary directory for test-specific files
-   - `pathFilenameTmpTesting`: Creates a temporary file with appropriate extension
-   - `pathCacheTesting`: Creates a temporary OEIS cache directory
-
-### Standardized Test Utilities
-
-The module provides utilities that create consistent test outputs:
-
-- `standardizedEqualToCallableReturn`: Core utility that handles testing function return values
-  or exceptions with uniform error messages
-- `standardizedSystemExit`: Tests code that should exit the program with specific status codes
-- `uniformTestMessage`: Creates consistent error messages for test failures
-
-## Using These Fixtures for Custom Tests
-
-The most important fixtures for testing custom implementations are:
-
-1. `syntheticDispatcherFixture`: Creates and patches a Numba-optimized module from a recipe
-2. `pathTmpTesting`: Provides a clean temporary directory for test files
-3. `standardizedEqualToCallableReturn`: Simplifies test assertions with clear error messages
-
-These can be adapted by copying and modifying them to test custom recipes and jobs.
-See the examples in `test_computations.py` for guidance on adapting these fixtures.
+"""Test framework infrastructure and shared fixtures for mapFolding.
+
+This module serves as the foundation for the entire test suite, providing standardized
+fixtures, temporary file management, and testing utilities. It implements the Single
+Source of Truth principle for test configuration and establishes consistent patterns
+that make the codebase easier to extend and maintain.
+
+The testing framework is designed for multiple audiences:
+- Contributors who need to understand the test patterns
+- AI assistants that help maintain or extend the codebase
+- Users who want to test custom modules they create
+- Future maintainers who need to debug or modify tests
+
+Key Components:
+- Temporary file management with automatic cleanup
+- Standardized assertion functions with uniform error messages
+- Test data generation from OEIS sequences for reproducible results
+- Mock objects for external dependencies and timing-sensitive operations
+
+The module follows Domain-Driven Design principles, organizing test concerns around
+the mathematical concepts of map folding rather than technical implementation details.
+This makes tests more meaningful and easier to understand in the context of the
+research domain.
 """
 
 from collections.abc import Callable, Generator, Sequence
-from mapFolding import getLeavesTotal, validateListDimensions, makeDataContainer
+from mapFolding import getLeavesTotal, makeDataContainer, validateListDimensions
 from mapFolding.oeis import oeisIDsImplemented, settingsOEIS
 from pathlib import Path
 from typing import Any
@@ -68,7 +36,7 @@ import unittest.mock
 import uuid
 
 # SSOT for test data paths and filenames
-pathDataSamples = Path("tests/dataSamples").absolute()
+pathDataSamples: Path = Path("tests/dataSamples").absolute()
 pathTmpRoot: Path = pathDataSamples / "tmp"
 pathTmpRoot.mkdir(parents=True, exist_ok=True)
 
@@ -102,7 +70,7 @@ def setupTeardownTmpObjects() -> Generator[None, None, None]:
 @pytest.fixture
 def pathTmpTesting(request: pytest.FixtureRequest) -> Path:
 	# "Z0Z_" ensures the directory name does not start with a number, which would make it an invalid Python identifier
-	pathTmp = pathTmpRoot / ("Z0Z_" + str(uuid.uuid4().hex))
+	pathTmp: Path = pathTmpRoot / ("Z0Z_" + str(uuid.uuid4().hex))
 	pathTmp.mkdir(parents=True, exist_ok=False)
 
 	registrarRecordsTmpObject(pathTmp)
@@ -153,7 +121,15 @@ def setupWarningsAsErrors() -> Generator[None, Any, None]:
 @pytest.fixture
 def oneTestCuzTestsOverwritingTests(oeisID_1random: str) -> tuple[int, ...]:
 	"""For each `oeisID_1random` from the `pytest.fixture`, returns `listDimensions` from `valuesTestValidation`
-	if `validateListDimensions` approves. Each `listDimensions` is suitable for testing counts."""
+	if `validateListDimensions` approves. Each `listDimensions` is suitable for testing counts.
+
+	This fixture provides a single test case to avoid issues with tests that write to the same
+	output files. It's particularly useful when testing code generation or file output functions
+	where multiple concurrent tests could interfere with each other.
+
+	The returned map shape is guaranteed to be computationally feasible for testing purposes,
+	avoiding cases that would take excessive time to complete during test runs.
+	"""
 	while True:
 		n = random.choice(settingsOEIS[oeisID_1random]['valuesTestValidation'])
 		if n < 2:
@@ -235,13 +211,42 @@ def oeisID_1random() -> str:
 	return random.choice(oeisIDsImplemented)
 
 def uniformTestMessage(expected: Any, actual: Any, functionName: str, *arguments: Any) -> str:
-	"""Format assertion message for any test comparison."""
+	"""Format assertion message for any test comparison.
+
+	Creates standardized, machine-parsable error messages that clearly display
+	what was expected versus what was received. This uniform formatting makes
+	test failures easier to debug and maintains consistency across the entire
+	test suite.
+
+	Parameters
+		expected: The value or exception type that was expected
+		actual: The value or exception type that was actually received
+		functionName: Name of the function being tested
+		arguments: Arguments that were passed to the function
+
+	Returns
+		formattedMessage: A formatted string showing the test context and comparison
+	"""
 	return (f"\nTesting: `{functionName}({', '.join(str(parameter) for parameter in arguments)})`\n"
 			f"Expected: {expected}\n"
 			f"Got: {actual}")
 
 def standardizedEqualToCallableReturn(expected: Any, functionTarget: Callable[..., Any], *arguments: Any) -> None:
-	"""Use with callables that produce a return or an error."""
+	"""Use with callables that produce a return or an error.
+
+	This is the primary testing function for validating both successful returns
+	and expected exceptions. It provides consistent error messaging and handles
+	the comparison logic that most tests in the suite rely on.
+
+	When testing a function that should raise an exception, pass the exception
+	type as the `expected` parameter. For successful returns, pass the expected
+	return value.
+
+	Parameters
+		expected: Expected return value or exception type
+		functionTarget: The function to test
+		arguments: Arguments to pass to the function
+	"""
 	if type(expected) is type[Exception]:
 		messageExpected = expected.__name__
 	else:

tests/test_computations.py

@@ -1,88 +1,26 @@
-"""
-Core Algorithm and Module Generation Testing
-
-This module provides tests for validating algorithm correctness and testing
-code generation functionality. It's designed not only to test the package's
-functionality but also to serve as a template for users testing their own
-custom implementations.
-
-## Key Testing Categories
-
-1. Algorithm Validation Tests
-   - `test_algorithmSourceParallel` - Tests the source algorithm in parallel mode
-   - `test_algorithmSourceSequential` - Tests the source algorithm in sequential mode
-   - `test_aOFn_calculate_value` - Tests OEIS sequence value calculations
-
-2. Synthetic Module Tests
-   - `test_syntheticParallel` - Tests generated Numba-optimized code in parallel mode
-   - `test_syntheticSequential` - Tests generated Numba-optimized code in sequential mode
-
-3. Job Testing
-   - `test_writeJobNumba` - Tests job-specific module generation and execution
-
-## How to Test Your Custom Implementations
-
-### Testing Custom Recipes (RecipeSynthesizeFlow):
-
-1. Copy the `syntheticDispatcherFixture` from conftest.py
-2. Modify it to use your custom recipe configuration
-3. Copy and adapt `test_syntheticParallel` and `test_syntheticSequential`
-
-Example:
-
-```python
-@pytest.fixture
-def myCustomRecipeFixture(useThisDispatcher, pathTmpTesting):
-    # Create your custom recipe configuration
-    myRecipe = RecipeSynthesizeFlow(
-        pathPackage=PurePosixPath(pathTmpTesting.absolute()),
-        # Add your custom configuration
-    )
-
-    # Generate the module
-    makeNumbaFlow(myRecipe)
+"""Core computational verification and algorithm validation tests.
 
-    # Import and patch the dispatcher
-    # ... (similar to syntheticDispatcherFixture)
+This module validates the mathematical correctness of map folding computations and
+serves as the primary testing ground for new computational approaches. It's the most
+important module for users who create custom folding algorithms or modify existing ones.
 
-    return customDispatcher
+The tests here verify that different computational flows produce identical results,
+ensuring mathematical consistency across implementation strategies. This is critical
+for maintaining confidence in results as the codebase evolves and new optimization
+techniques are added.
 
-def test_myCustomRecipeParallel(myCustomRecipeFixture, listDimensionsTestParallelization):
-    # Test with the standardized validation utility
-    standardizedEqualToCallableReturn(
-        getFoldsTotalKnown(tuple(listDimensionsTestParallelization)),
-        countFolds,
-        listDimensionsTestParallelization,
-        None,
-        'maximum'
-    )
-```
+Key Testing Areas:
+- Flow control validation across different algorithmic approaches
+- OEIS sequence value verification against known mathematical results
+- Code generation and execution for dynamically created computational modules
+- Numerical accuracy and consistency checks
 
-### Testing Custom Jobs (RecipeJob):
+For users implementing new computational methods: use the `test_flowControl` pattern
+as a template. It demonstrates how to validate that your algorithm produces results
+consistent with the established mathematical foundation.
 
-1. Copy and adapt `test_writeJobNumba`
-2. Modify it to use your custom job configuration
-
-Example:
-
-```python
-def test_myCustomJob(oneTestCuzTestsOverwritingTests, pathFilenameTmpTesting):
-    # Create your custom job configuration
-    myJob = RecipeJob(
-        state=makeInitializedComputationState(validateListDimensions(oneTestCuzTestsOverwritingTests)),
-        # Add your custom configuration
-    )
-
-    spices = SpicesJobNumba()
-    # Customize spices if needed
-
-    # Generate and test the job
-    makeJobNumba(myJob, spices)
-    # Test execution similar to test_writeJobNumba
-```
-
-All tests leverage standardized utilities like `standardizedEqualToCallableReturn`
-that provide consistent, informative error messages and simplify test validation.
+The `test_writeJobNumba` function shows how to test dynamically generated code,
+which is useful if you're working with the code synthesis features of the package.
 """
 
 from mapFolding import countFolds, getFoldsTotalKnown, oeisIDfor_n
@@ -91,7 +29,7 @@ from mapFolding.oeis import settingsOEIS
 from mapFolding.someAssemblyRequired.RecipeJob import RecipeJobTheorem2Numba
 from mapFolding.syntheticModules.initializeCount import initializeGroupsOfFolds
 from pathlib import Path, PurePosixPath
-from tests.conftest import standardizedEqualToCallableReturn, registrarRecordsTmpObject
+from tests.conftest import registrarRecordsTmpObject, standardizedEqualToCallableReturn
 from typing import Literal
 import importlib.util
 import multiprocessing
@@ -104,6 +42,15 @@ if __name__ == '__main__':
 
 @pytest.mark.parametrize('flow', ['daoOfMapFolding', 'theorem2', 'theorem2Trimmed', 'theorem2numba'])
 def test_flowControl(mapShapeTestCountFolds: tuple[int, ...], flow: Literal['daoOfMapFolding'] | Literal['theorem2'] | Literal['theorem2numba']) -> None:
+	"""Validate that different computational flows produce identical results.
+
+	This is the primary test for ensuring mathematical consistency across different
+	algorithmic implementations. When adding a new computational approach, include
+	it in the parametrized flow list to verify it produces correct results.
+
+	The test compares the output of each flow against known correct values from
+	OEIS sequences, ensuring that optimization techniques don't compromise accuracy.
+	"""
 	standardizedEqualToCallableReturn(getFoldsTotalKnown(mapShapeTestCountFolds), countFolds, None, None, None, None, mapShapeTestCountFolds, None, None, flow)
 
 def test_aOFn_calculate_value(oeisID: str) -> None:
@@ -112,8 +59,18 @@ def test_aOFn_calculate_value(oeisID: str) -> None:
 
 @pytest.mark.parametrize('pathFilenameTmpTesting', ['.py'], indirect=True)
 def test_writeJobNumba(oneTestCuzTestsOverwritingTests: tuple[int, ...], pathFilenameTmpTesting: Path) -> None:
-	from mapFolding.someAssemblyRequired.toolkitNumba import SpicesJobNumba
+	"""Test dynamic code generation and execution for computational modules.
+
+	This test validates the package's ability to generate, compile, and execute
+	optimized computational code at runtime. It's essential for users working with
+	the code synthesis features or implementing custom optimization strategies.
+
+	The test creates a complete computational module, executes it, and verifies
+	that the generated code produces mathematically correct results. This pattern
+	can be adapted for testing other dynamically generated computational approaches.
+	"""
 	from mapFolding.someAssemblyRequired.makeJobTheorem2Numba import makeJobNumba
+	from mapFolding.someAssemblyRequired.toolkitNumba import SpicesJobNumba
 	mapShape = oneTestCuzTestsOverwritingTests
 	state = MapFoldingState(mapShape)
 	state = initializeGroupsOfFolds(state)

tests/test_filesystem.py

@@ -1,5 +1,29 @@
+"""File system operations and path management validation.
+
+This module tests the package's interaction with the file system, ensuring that
+results are correctly saved, paths are properly constructed, and fallback mechanisms
+work when file operations fail. These tests are essential for maintaining data
+integrity during long-running computations.
+
+The file system abstraction allows the package to work consistently across different
+operating systems and storage configurations. These tests verify that abstraction
+works correctly and handles edge cases gracefully.
+
+Key Testing Areas:
+- Filename generation following consistent naming conventions
+- Path construction and directory creation
+- Fallback file creation when primary save operations fail
+- Cross-platform path handling
+
+Most users won't need to modify these tests unless they're changing how the package
+stores computational results or adding new file formats.
+"""
+
 from contextlib import redirect_stdout
-from mapFolding import validateListDimensions, getPathRootJobDEFAULT, getPathFilenameFoldsTotal, saveFoldsTotal, getFilenameFoldsTotal
+from mapFolding import (
+	getFilenameFoldsTotal, getPathFilenameFoldsTotal, getPathRootJobDEFAULT, saveFoldsTotal,
+	validateListDimensions,
+)
 from pathlib import Path
 import io
 import pytest