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.

Installation

mapFolding requires Python 3.13 or newer.

pip install mapFolding

Install an optional backend only when you need its corresponding implementation:

Extra	Purpose
`numba`	Numba-compiled map-folding implementations
`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[numba,pandas]"

Quick start

Count map foldings

Each positive integer in mapShape is the length of one dimension. A (2, 3) map has six leaves.

from mapFolding.basecamp import countFolds

totalFolds = countFolds((2, 3))
print(totalFolds)  # 60

Calculate an OEIS term

from mapFolding.oeis import oeisIDfor_n

totalFolds = oeisIDfor_n('A001415', 6)
print(totalFolds)  # 10512

The installed commands expose the same sequence registry:

getOEISids
OEIS_for_n A001415 6

The second command prints:

10512 distinct folding patterns.
Time elapsed: ... seconds

Count semi-meanders and meanders

from mapFolding.basecamp import countMeanders

print(countMeanders('semi', 5))      # 10; OEIS A000682
print(countMeanders('meanders', 4))  # 3; OEIS A005316

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

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

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.

Development

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

PowerShell:

.venv\Scripts\Activate.ps1

POSIX shells:

source .venv/bin/activate

Install and test:

pip install -e ".[development,testing]"
pytest

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.

My recovery

Release files for mapFolding 0.34.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.34.0
File	Size	Uploaded
mapfolding-0.34.0.tar.gz	325.3 kB	Aug 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mapFolding 0.34.0
File	Interpreter	ABI	Platform	Reset
mapfolding-0.34.0-py3-none-any.whl 409.2 kB Aug 30, 2026	Python 3	none	any	Details

Total release size:734.5 kB

Release files / mapfolding-0.34.0.tar.gz

Download URL	mapfolding-0.34.0.tar.gz
Size	325.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`119b2db93f4b683fd649842a7ccb45bccb8f516f8fc962d1c20cf85b56a8bef7`
BLAKE2b-256 checksum How to use checksums	`34c164ced0bd331c91da3fefd0b503bc3aeebb157646fea6e4d8cfce7bbb6a40`
Upload date	Aug 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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

Download URL	mapfolding-0.34.0-py3-none-any.whl
Size	409.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`40aaef7273083eab8464f0e369ceb7ea745eac6e8a673474f2bde306aa6d63a0`
BLAKE2b-256 checksum How to use checksums	`71d62a01a20ed538c60ed32f6e31008c03379ca76edb36f4c465a095d1554da6`
Upload date	Aug 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`