# mapFolding
[](https://pypi.org/project/mapFolding/)
[](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
[](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
- **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
- **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 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.
## Repository Structure
- `mapFolding/`: Core implementation with modular architecture
- `reference/`: Historical algorithm implementations and performance studies
- `someAssemblyRequired/`: AST transformation framework
- `mapFolding/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
[](https://HunterThinks.com/support)
[](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.
[](https://creativecommons.org/licenses/by-nc/4.0/)
Raw data
{
"_id": null,
"home_page": null,
"name": "mapFolding",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"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",
"author": null,
"author_email": "Hunter Hogan <HunterHogan@pm.me>",
"download_url": "https://files.pythonhosted.org/packages/32/0e/e662ea77f3d994549da503f08a446c8f3dc7fd8faf9d344d69f2bc0ec4d1/mapfolding-0.13.1.tar.gz",
"platform": null,
"description": "# mapFolding\n\n[](https://pypi.org/project/mapFolding/)\n[](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)\n[](https://creativecommons.org/licenses/by-nc/4.0/)\n\nA 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.\n\n(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.)\n\n## The Mathematical Problem\n\nMap 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.\n\nThe calculations extend the Online Encyclopedia of Integer Sequences (OEIS):\n\n- **A001415**: 2\u00d7n strips (computed through n=20 for the first time)\n- **A001418**: n\u00d7n squares\n- **A001416**: 3\u00d7n strips\n- **A001417**: n-dimensional hypercubes\n- **A195646**: 3\u00d73\u00d7...\u00d73 hypercubes\n\n```python\nfrom mapFolding import oeisIDfor_n\n\n# How many ways can you fold a 2\u00d74 strip?\nfoldsTotal = oeisIDfor_n('A001415', 4)\n```\n\n## The Computational Challenge\n\nFor larger maps, these calculations require hours or days to complete. A 2\u00d720 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.\n\n## What This Package Provides\n\n### Core Functionality\n\n- **Complete implementation** of Lunnon's recursive algorithm\n- **Mathematical validation** through OEIS integration and caching\n- **Type-safe computational state** management with automatic initialization\n- **Result persistence** for long-running calculations\n\n### Algorithm Transformation System\n\n- **AST manipulation framework** for converting dataclass-based algorithms to optimized implementations\n- **Automatic code generation** that produces standalone, highly optimized computation modules\n- **Dataclass decomposition** to enable Numba compatibility while preserving readable source code\n- **Comprehensive optimization** including dead code elimination, static value embedding, and aggressive compilation settings\n- **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.\n\n### Educational Resources\n\n- **Historical implementations** showing algorithm evolution from 1971 to present\n- **Performance comparison** studies demonstrating optimization techniques\n- **Complete test suite** with patterns for validating custom implementations\n- **Reference documentation** for extending the transformation framework\n\n## Use Cases\n\n**Mathematical Research**: Explore folding pattern properties, extend known sequences, or validate theoretical results against computed values.\n\n**Algorithm Optimization Learning**: Study a complete transformation assembly line that converts high-level algorithms into production-ready optimized code.\n\n**Performance Computing Education**: Examine techniques for achieving maximum Python performance through Numba integration, AST manipulation, and specialized code generation.\n\n**Combinatorial Problem Solving**: Use the framework as a template for optimizing other recursive combinatorial algorithms.\n\n## Repository Structure\n\n- `mapFolding/`: Core implementation with modular architecture\n- `reference/`: Historical algorithm implementations and performance studies\n- `someAssemblyRequired/`: AST transformation framework\n- `mapFolding/tests/`: Comprehensive validation suite\n- `jobs/`: Generated optimized modules for specific calculations\n\n## Performance Characteristics\n\n- **Pure Python baseline**: Educational implementations for understanding\n- **NumPy optimization**: ~10\u00d7 improvement through vectorized operations\n- **Numba compilation**: ~100\u00d7 improvement through native code generation\n- **Specialized modules**: ~1000\u00d7 improvement through static optimization and embedded constants\n\nActual performance varies by map dimensions and available hardware.\n\n## My recovery\n\n[](https://HunterThinks.com/support)\n[](https://www.youtube.com/@HunterHogan)\n\n## How to code\n\nCoding One Step at a Time:\n\n0. WRITE CODE.\n1. Don't write stupid code that's hard to revise.\n2. Write good code.\n3. When revising, write better code.\n\n[](https://creativecommons.org/licenses/by-nc/4.0/)\n",
"bugtrack_url": null,
"license": "CC-BY-NC-4.0",
"summary": "Map folding algorithm with code transformation framework for optimizing numerical computations.",
"version": "0.13.1",
"project_urls": {
"Donate": "https://www.patreon.com/integrated",
"Homepage": "https://github.com/hunterhogan/mapFolding",
"Issues": "https://github.com/hunterhogan/mapFolding/issues",
"Repository": "https://github.com/hunterhogan/mapFolding.git"
},
"split_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"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3b79b1db1689dcfc924e403336b153a4a3d0b81ea9602a5e2fc2c1699f95dcbd",
"md5": "93662bbc1a1a6e2355607eb2bc1d7ba9",
"sha256": "af72a742745c3254c3a84e7fa171052d890b183883a8c020cd6acefb903e4256"
},
"downloads": -1,
"filename": "mapfolding-0.13.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "93662bbc1a1a6e2355607eb2bc1d7ba9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 127285,
"upload_time": "2025-07-18T18:35:41",
"upload_time_iso_8601": "2025-07-18T18:35:41.237563Z",
"url": "https://files.pythonhosted.org/packages/3b/79/b1db1689dcfc924e403336b153a4a3d0b81ea9602a5e2fc2c1699f95dcbd/mapfolding-0.13.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "320ee662ea77f3d994549da503f08a446c8f3dc7fd8faf9d344d69f2bc0ec4d1",
"md5": "2f7a43062884fae02a3a7a387dac15cf",
"sha256": "87a9a491c35fdbdd3b0184afcd179aa4a1e34adcb99b71adbfc34bc5844567f9"
},
"downloads": -1,
"filename": "mapfolding-0.13.1.tar.gz",
"has_sig": false,
"md5_digest": "2f7a43062884fae02a3a7a387dac15cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 103281,
"upload_time": "2025-07-18T18:35:42",
"upload_time_iso_8601": "2025-07-18T18:35:42.653788Z",
"url": "https://files.pythonhosted.org/packages/32/0e/e662ea77f3d994549da503f08a446c8f3dc7fd8faf9d344d69f2bc0ec4d1/mapfolding-0.13.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 18:35:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hunterhogan",
"github_project": "mapFolding",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mapfolding"
}
JSON
