Skip to main content

mapFolding

PyPI Python versions Python Tests License: CC BY-NC 4.0

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

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

Calculate an OEIS term

from mapFolding.oeis import oeisIDfor_n

folds_total = oeisIDfor_n('A001415', 6)
print(folds_total)  # 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.foldsTotal; 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/syntheticModules/ Generated implementations; regenerate these instead of editing them directly
mapFolding/someAssemblyRequired/ 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

A map-folding problem

Folding a strip of stamps

Multi-dimensional map-folding

A transfer matrix approach to the enumeration of plane meanders

A new transfer-matrix algorithm for exact enumerations: self-avoiding polygons on the square lattice

Stamp Foldings, Semi-Meanders, and Open Meanders: Fast Generation Algorithms

Foldings and meanders

Valid Orderings of Layers When Simple-Folding a Map

jOEIS: Java Online Encyclopedia of Integer Sequences

The Online Encyclopedia of Integer Sequences

Extending OEIS sequences

OEIS limits my proposed changes to a sequence to three sequences at a time. I have values to extend the following sequences, but I cannot submit them all at the same time.

  • A060206, submitted.
  • A077460
  • A085973
  • A208357
  • A217310
  • A217318
  • A223093
  • A223094
  • A223095
  • A333971
  • A334615
  • A337581, submitted.

My recovery

2011 August: Homeless since YouTube channel subscribers

CC-BY-NC-4.0

Metadata

Release files for mapFolding 0.30.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.30.0
File Size Uploaded Provenance Actions
mapfolding-0.30.0.tar.gz 315.5 kB Without provenance Details for mapfolding-0.30.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mapFolding 0.30.0
File Interpreter ABI Platform Actions
mapfolding-0.30.0-py3-none-any.whl Python 3 none any Details for mapfolding-0.30.0-py3-none-any.whl

Total release size: 715.1 kB

Release files / mapfolding-0.30.0.tar.gz

Download URL mapfolding-0.30.0.tar.gz
Size 315.5 kB
Tags Source
SHA-256 checksum
How to use checksums
15e6a859c18435a91f371c79e0f5f220ea3e5d7115dbc7164490c2de956ef3e0
BLAKE2b-256 checksum
How to use checksums
3969b42ef657f893c5b1cee647ec6d65614a6ab2625a70d6b8a727edcb813a8d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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

Download URL mapfolding-0.30.0-py3-none-any.whl
Size 399.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4f56336b9f8f03577c264815f14d85c27b48544b34982aa5f3cd1cdcc2f4ef83
BLAKE2b-256 checksum
How to use checksums
b1f884a27883d2f9df5c1fd0474cec044bda0a3145dac6b400d170cda5eed506
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Security for mapFolding 0.30.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.30.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page