Metadata-Version: 2.4
Name: mapFolding
Version: 0.9.0
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: Repository, https://github.com/hunterhogan/mapFolding.git
Project-URL: Issues, https://github.com/hunterhogan/mapFolding/issues
Keywords: A001415,A001416,A001417,A001418,A195646,algorithmic optimization,AST manipulation,code generation,code transformation,combinatorics,computational geometry,dataclass transformation,folding pattern enumeration,just-in-time compilation,map folding,Numba optimization,OEIS,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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Compilers
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: autoflake
Requires-Dist: more_itertools
Requires-Dist: numba_progress
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: platformdirs
Requires-Dist: python_minifier
Requires-Dist: tomli
Requires-Dist: Z0Z_tools
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"
Dynamic: license-file

# mapFolding: High-Performance Algorithm Playground for Computational Enthusiasts 🗺️

[![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/)

**This package is for you if:**

- You're fascinated by computational algorithms and their optimization
- You want to explore AST transformation techniques for Python performance tuning
- You're interested in solving mathematical puzzles through code
- You're learning about Numba and advanced Python optimization

**This package is NOT for you if:**

- You're looking for a general-purpose folding simulation tool
- You need commercial-ready mapping software
- You want simple visualization of folding patterns

## What Does This Package Actually Do?

`mapFolding` solves a specific mathematical problem: counting the number of distinct ways to fold a rectangular map. While this may sound niche, it's a fascinating computational challenge that demonstrates:

1. How to transform readable algorithms into blazingly fast implementations
2. Advanced techniques for Python optimization using AST manipulation
3. Numba acceleration with specialized compilation strategies
4. Algorithms for problems that grow combinatorially

The package has achieved new computational records, including first-ever calculations for large maps that were previously infeasible.

```python
# Compute the number of ways to fold a 5×5 grid:
from mapFolding import oeisIDfor_n
foldsTotal = oeisIDfor_n('A001418', 5)  # Returns 186,086,600
```

## Key Benefits for Computational Enthusiasts

### 1. Algorithm Transformation Laboratory

See how the same algorithm evolves from readable Python to highly-optimized implementations:

```python
# The intuitive, readable version:
def countFolds(mapShape):
    # ...implement readable algorithm...

# The transformed, optimized version (auto-generated):
@numba.jit(nopython=True, parallel=True, fastmath=True)
def countFolds_optimized(shape_param):
    # ...blazingly fast implementation...
```

### 2. Code Generation Framework

Study and extend a complete Python code transformation pipeline:

- AST analysis and manipulation
- Dataclass decomposition ("shattering")
- Automatic import management
- Type specialization for numerical computing

### 3. Exhaustive Test Framework

Leverage a sophisticated test suite for validating your own optimizations:

```python
# Test your own recipe implementation with just a few lines:
@pytest.fixture
def myCustomRecipeFixture(useThisDispatcher, pathTmpTesting):
    myRecipe = RecipeSynthesizeFlow(
        # Your custom configuration here
    )
    # ...transformation code...
    return customDispatcher

def test_myCustomImplementation(myCustomRecipeFixture):
    # Automatic validation against known values
```

## Installation and Getting Started

```sh
pip install mapFolding
```

Try a quick calculation:

```python
from mapFolding import oeisIDfor_n

# Calculate ways to fold a 2×4 map
result = oeisIDfor_n('A001415', 4)  # Returns 8
print(f"A 2×4 map can be folded {result} different ways")
```

## Mathematical Background (For the Curious)

The map folding problem was introduced by Lunnon in 1971 and connects to combinatorial geometry, computational complexity, and integer sequence analysis. The calculations provide entries to the Online Encyclopedia of Integer Sequences (OEIS).

This package implements several OEIS sequences, including:

- A001415: Number of ways to fold a 2×n strip (now calculated up to n=20!)
- A001418: Number of ways to fold an n×n square grid

## Explore the Repository

The repository structure reveals the package's educational value:

- `reference/`: Historical implementations and algorithm evolution
- `someAssemblyRequired/`: Code transformation framework
- `tests/`: Comprehensive test suite with fixtures for your own implementations

## Who Is This For, Really?

If you've read this far and are intrigued by computational puzzles, algorithm optimization, or Python performance techniques, this package offers a playground for exploration. It's particularly valuable for:

- Computer science students studying algorithm optimization
- Python developers exploring Numba and AST manipulation
- Computational mathematicians interested in combinatorial problems
- Anyone fascinated by the intersection of mathematics and computing

Whether you use it to solve map folding problems or to study its optimization techniques, `mapFolding` offers a unique window into advanced Python programming approaches.

[![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/)
