mapFolding


NamemapFolding JSON
Version 0.13.1 PyPI version JSON
download
home_pageNone
SummaryMap folding algorithm with code transformation framework for optimizing numerical computations.
upload_time2025-07-18 18:35:42
maintainerNone
docs_urlNone
authorNone
requires_python>=3.12
licenseCC-BY-NC-4.0
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
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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
- **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

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

            

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[![pip install mapFolding](https://img.shields.io/badge/pip%20install-mapFolding-gray.svg?colorB=3b434b)](https://pypi.org/project/mapFolding/)\n[![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)\n[![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/)\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[![Static Badge](https://img.shields.io/badge/2011_August-Homeless_since-blue?style=flat)](https://HunterThinks.com/support)\n[![YouTube Channel Subscribers](https://img.shields.io/youtube/channel/subscribers/UC3Gx7kz61009NbhpRtPP7tw)](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[![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/)\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"
}
        
Elapsed time: 1.89670s