mapFolding

Exact enumeration tools for map folding, stamp folding, semi-meanders, and meanders.

mapFolding is a typed Python research package for counting distinct foldings of one- and multidimensional maps. It provides:

stable dispatch functions for ordinary, rotationally symmetric, and divided computations;
native algorithms for map folding, semi-meanders, and meanders;
a unified interface to 33 implemented OEIS sequences, including exact formula relationships;
readable source algorithms, generated optimized implementations, and optional NumPy, Numba, Pandas, and Codon routes; and
cross-implementation tests against known sequence values.

Earlier versions of this project were used to compute new terms for OEIS A001415, the number of ways to fold a 2 × n strip of stamps.

This is exact combinatorial enumeration: running time and memory requirements grow quickly. Start with small inputs. The supported high-level interfaces are in mapFolding.basecamp and mapFolding.oeis; other modules include evolving research code.

Quick start

Quick start your exploration of a new-to-you algorithm? Quick start your idea for improving an algorithm? Quick start your dissection of an algorithm's states?

Considering the versatility and sophistication of this package, you can accomplish many things quickly, but a "Quick start" section doesn't make sense.

Public interfaces

Goal	Interface
Count all foldings of a map	`mapFolding.basecamp.countFolds(mapShape, ...)`
Count rotationally symmetric foldings	`mapFolding.basecamp.countFoldsSymmetric(mapShape, ...)`
Count semi-meanders or meanders	`mapFolding.basecamp.countMeanders(kind, n, ...)`
Calculate any implemented OEIS term	`mapFolding.oeis.oeisIDfor_n(oeisID, n, ...)`
Convert a map-folding OEIS index to dimensions	`mapFolding.oeis.makeMapShape(oeisID, n)`
Retrieve cached known values	`mapFolding.oeis.getValuesKnown(oeisID)`
List implemented sequences	`getOEISids`

oeisIDfor_n dispatches to the appropriate folding algorithm, meander algorithm, symmetric-folding algorithm, or exact formula. Run getOEISids for the current list and descriptions of all supported sequences.

The map-folding sequence mappings are:

OEIS ID	Problem	`mapShape` for index `n`
A000136	Strip of `n` labeled stamps	`(1, n)`
A001415	`2 × n` strip	`(2, n)`
A001416	`3 × n` strip	`(3, n)`
A001417	`n`-dimensional `2 × ⋯ × 2` map	`(2,) * n`
A195646	`n`-dimensional `3 × ⋯ × 3` map	`(3,) * n`
A001418	`n × n` sheet	`(n, n)`
A007822	Symmetric foldings of `2n + 1` stamps	`(1, 2 * n)`

For A007822, pass (1, 2 * n) to countFoldsSymmetric; the function's computational shape differs from the 2n + 1 stamps in the sequence description.

OEIS metadata and b-files are cached locally for 30 days. Missing or stale entries are refreshed from oeis.org; stale cached data remains available if a refresh fails.

Algorithm selection and long computations

Assume this is always out of date.

Leave flow='' for the default implementation. The alternate selectors exist for research, validation, and performance comparisons:

Interface	Supported `flow` values
`countFolds`	`''`, `daoOfMapFolding`, `numba`, `theorem2`, `theorem2Codon`, `theorem2Numba`, `theorem2Trimmed`
`countFoldsSymmetric`	`''`, `asynchronous`, `theorem2`, `theorem2Codon`, `theorem2Numba`, `theorem2Trimmed`
`countMeanders`	`''`, `matrixMeanders`, `matrixNumPy`, `matrixPandas`

The Numba, Pandas, and Codon selectors require their corresponding extras. For OEIS sequences with multiple exact identities, the f argument to oeisIDfor_n selects a formula; leaving it empty uses the default route.

Pass pathLikeWrite to a counting function to preserve a result. An existing directory receives a generated filename such as p2x6.totalFolds; an explicit target file is also supported. The destination is write-tested before computation, and an existing target is not overwritten.

countFolds can split work with an integer, computationDivisions='cpu', or computationDivisions='maximum'. Dividing this algorithm repeats substantial work and is usually slower, so leave computationDivisions=None unless you are deliberately studying the parallel implementation.

Repository guide

This is a little out of date.

Path	Role
`mapFolding/basecamp.py`	Stable high-level dispatch for folding and meander computations
`mapFolding/oeis/`	OEIS dispatch, formulas, metadata, and cached values
`mapFolding/algorithms/`	Handwritten source algorithms
`mapFolding/synthesized/`	Generated implementations; regenerate these instead of editing them directly
`mapFolding/kitAST/`	Project-specific AST transformations and module generators
`mapFolding/_e/`	Experimental elimination-based algorithms and analysis
`mapFolding/tests/`	Main correctness, dispatch, filesystem, and parameter tests
`mapFolding/reference/`	Historical implementations, completed jobs, notes, and research artifacts
`easyRun/`	Benchmark and exploration harnesses

General-purpose transformation primitives developed alongside this project now live in astToolkit and astToolFactory. The transformation pipeline retained here is specific to generating and validating mapFolding implementations.

Installation

mapFolding requires Python 3.13 or newer.

pip install mapFolding

To avoid bloat, some packages are optional:

Extra	Purpose
`pandas`	Pandas and Arrow meander implementation
`codon`	Codon-compiled implementations on Linux
`ortools`	Experimental constraint-propagation work
`testing`	Test dependencies
`development`	Broader development and analysis dependencies

For example:

pip install "mapFolding[codon,pandas]"

Development, or to have the archives, notes, and other supplemental materials

Create and activate a virtual environment, then install both development extras:

git clone https://github.com/hunterhogan/mapFolding.git
cd mapFolding
python -m venv .venv
pip install -e ".[development,testing]"

The test suite compares independent implementations with known OEIS values and stored data samples. When adding an algorithm variant, begin with mapFolding/tests/test_computations.py and register the new flow beside the existing implementations.

Citation

To cite this software, use the metadata in CITATION.cff. BibTeX files for the mathematical literature are collected in citations/.

Research references

Sur les Chevauchements des Permutations

BibTeX citation.
PDF: OEIS

Folding a strip of stamps

A map-folding problem

Multi-dimensional map-folding

jOEIS: Java Online Encyclopedia of Integer Sequences

The Online Encyclopedia of Integer Sequences

Computing new values

Folds of multidimensional map (2, 2, 2, 2, 2, 2, 2, 2), which is A001417(8): estimated 14 days with my current hardware and a non-published algorithm.
Folds of multidimensional map (2, 21), which is A001415(21): estimated 6 days with my current hardware and one of the compiled "Theorem 2" algorithm versions.
Folds of multidimensional map (2, 22), which is A001415(22): estimated 15 days with my current hardware and one of the compiled "Theorem 2" algorithm versions.
Folds of multidimensional map (3, 15), which is A001416(15): estimated 11 days with my current hardware and one of the compiled "Theorem 2" algorithm versions.
Semi-meanders with 46 crossings, which is A000682(46): estimated 1–2 hours if I had 64 GB of system memory.

Computation times assume:

No power interruptions. (I don't have a UPS, and in the last two months the longest gap between power interruptions was 8 days 6 hours.)
No system crashes.
Single-core computations are given priority over other tasks.
The core of single-core computations is regularly boosted.
No heat issues.

Status reminders

Acceleration
1. Building Py 3.14z (tail-call) is not working.
2. Codon: new release, new features.
Remote execution
1. Google Colab: memmap causes everything to go to "disk" and the physical memory is unused.
2. GitHub Codespaces: ignores memmap and terminates on OOM.
astToolkit: figure out a better container system than Ingredients Module, Ingredients Function, etc.
Dao of map folding
1. Overhaul how I store and access type metadata for ndarray and other containers. Affects:
  1. StateMapFolding
  2. Shatter dataclass
  3. ast transformations
2. Run 2^8 without a crash or power outage.
3. Compute (2, 21), (2, 22), and (3, 15).
Symmetric 1xn
1. Symmetry algorithm is too slow.
2. Asynchronous + accelerated doesn't work yet.
Matrix Meanders
1. I need a lot more tools in kitAST.
2. I hate getTotalBuckets but it should be a brilliant function.
Permutations
1. The base algorithm is a dumpster fire.
2. Bilateral concurrent can't produce a folding, but uses too much memory and is too slow to count folds.
Reduce arches: slower than counting by hand.
_e
1. Constraint propagation or SAT
  1. ortools won't apply concurrency, and I don't know how to think about divisions of the problem space that actually reduce computation time.
  2. Understanding other packages is harder than a self-enema with a firehouse.
2. 2^n-dimensional (aka elimination by crease)
  1. Computation algorithms needed for: conditional predecessors, conditional successors, DomainLeaf首零Plus零 in dimension零, the range of a pile (aka pile options, aka choices leaf), pinPile二ByCrease, pinPile二Ante首ByCrease, and pinPile零Ante首零AfterDepth4.
  2. Acceleration.
  3. Bug in boxOfFunctionsReduction2上nDimensional.
  4. Finish collecting 2^7 data.
  5. Fastest algorithm for 2^5. Can't complete 2^6. I mean, wtf?
  6. PermutationSpace and its OOP structure: I don't really know what I am doing.
  7. The reduce-it concept is strong: reorient more code around it. Resolve the tension with PermutationSpace._solidifyLeafSpace().
3. Elimination: atrophied.
4. Insert leaves: But for the data storage, it would be powerful. IDK anything about data compression. I lost the code I wrote for the notation I created to store graphs, and it seems I am too stupid to recreate or reverse engineer my own code from my own files AND OTHER FUNCTIONS. fml. Ironically, LLMs can't figure it out either because I guess my idea was novel. F.M.L.

Hunter, this list is incomplete: you quit writing after you got upset. Resume at mapFolding.kitAST.

Research 1
1. Finish run D11.
2. Start partial runs in the R series.
3. Make NumPy version.
4. 2-sequence representation, 3-sequence representation, or something else?
5. Hypothesis: relationships are best described by the sum of n and hypothetical n, modulated by parity.

My recovery

Metadata

Release files for mapFolding 0.36.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mapFolding 0.36.0
File	Size	Uploaded
mapfolding-0.36.0.tar.gz	386.3 kB	Sep 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mapFolding 0.36.0
File	Interpreter	ABI	Platform	Reset
mapfolding-0.36.0-py3-none-any.whl 478.4 kB Sep 26, 2026	Python 3	none	any	Details

Total release size: 864.8 kB

Release files / mapfolding-0.36.0.tar.gz

Download URL	mapfolding-0.36.0.tar.gz
Size	386.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`19f65d60cc1e788ac0ec33effe6effee46129603838434ec88751bfca74fc725`
BLAKE2b-256 checksum How to use checksums	`07751064f2c0ff4a954e8213b89bd490dfd217660e757ad531bfa12a1dfe0566`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / mapfolding-0.36.0-py3-none-any.whl

Download URL	mapfolding-0.36.0-py3-none-any.whl
Size	478.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c46722702a938283f6622cfbb2c0cf85e886fde704e41e65f71933f93ab4bb70`
BLAKE2b-256 checksum How to use checksums	`205898e273c1e750b629486ffb398a253994341a0dfe2aba797c932059280bbd`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`