mapFolding 0.8.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

mapFolding/theDao.py

@@ -1,14 +1,28 @@
-from concurrent.futures import Future as ConcurrentFuture, ProcessPoolExecutor
-from copy import deepcopy
-from mapFolding.theSSOT import ComputationState
-from multiprocessing import set_start_method as multiprocessing_set_start_method
-
 """
+Core computational algorithm for map folding counting and enumeration.
+
+This module implements the core algorithms for enumerating and counting the various ways
+a rectangular map can be folded. It uses a functional state-transformation approach, where
+each function performs a specific state mutation and returns the updated state. The module
+provides three main counting algorithms:
+
+1. countInitialize: Sets up the initial state for computation
+2. countSequential: Processes the folding computation sequentially
+3. countParallel: Distributes the computation across multiple processes
+
+All algorithms operate on a ComputationState object that tracks the folding process, including:
 - A "leaf" is a unit square in the map
 - A "gap" is a potential position where a new leaf can be folded
 - Connections track how leaves can connect above/below each other
 - Leaves are enumerated starting from 1, not 0; hence, leaf1ndex not leafIndex
+
+The doTheNeedful function is the main entry point that orchestrates the computation strategy
+based on task divisions and concurrency parameters.
 """
+from concurrent.futures import Future as ConcurrentFuture, ProcessPoolExecutor
+from copy import deepcopy
+from mapFolding.theSSOT import ComputationState
+from multiprocessing import set_start_method as multiprocessing_set_start_method
 
 # When to use multiprocessing.set_start_method https://github.com/hunterhogan/mapFolding/issues/6
 if __name__ == '__main__':

mapFolding/theSSOT.py

@@ -1,3 +1,21 @@
+"""
+Single Source of Truth module for configuration, types, and computational state management.
+
+This module defines the core data structures, type definitions, and configuration settings
+used throughout the mapFolding package. It implements the Single Source of Truth (SSOT)
+principle to ensure consistency across the package's components.
+
+Key features:
+1. The ComputationState dataclass, which encapsulates the state of the folding computation
+2. Unified type definitions for integers and arrays used in the computation
+3. Configuration settings for synthetic module generation and dispatching
+4. Path resolution and management for package resources and job output
+5. Dynamic dispatch functionality for algorithm implementations
+
+The module differentiates between "the" identifiers (package defaults) and other identifiers
+to avoid namespace collisions when transforming algorithms.
+"""
+
 from collections.abc import Callable
 from importlib import import_module as importlib_import_module
 from inspect import getfile as inspect_getfile
@@ -149,7 +167,7 @@ class ComputationState:
 	foldsTotal: DatatypeFoldsTotal = DatatypeFoldsTotal(0)
 	gap1ndex: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
 	gap1ndexCeiling: DatatypeElephino = DatatypeElephino(0)
-	groupsOfFolds: DatatypeFoldsTotal = DatatypeFoldsTotal(0)
+	groupsOfFolds: DatatypeFoldsTotal = dataclasses.field(default=DatatypeFoldsTotal(0), metadata={'theCountingIdentifier': True})
 	indexDimension: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
 	indexLeaf: DatatypeLeavesTotal = DatatypeLeavesTotal(0)
 	indexMiniGap: DatatypeElephino = DatatypeElephino(0)

{mapfolding-0.8.0.dist-info → mapfolding-0.8.1.dist-info}/METADATA

@@ -1,18 +1,17 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: mapFolding
-Version: 0.8.0
-Summary: Count distinct ways to fold a map (or a strip of stamps)
+Version: 0.8.1
+Summary: Map folding algorithm with code transformation framework for optimizing numerical computations
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 License: CC-BY-NC-4.0
 Project-URL: Donate, https://www.patreon.com/integrated
 Project-URL: Homepage, https://github.com/hunterhogan/mapFolding
 Project-URL: Repository, https://github.com/hunterhogan/mapFolding.git
-Keywords: A001415,A001416,A001417,A001418,A195646,combinatorics,folding,map folding,OEIS,optimization,stamp folding
+Keywords: A001415,A001416,A001417,A001418,A195646,algorithmic optimization,AST manipulation,code generation,code transformation,combinatorics,computational geometry,dataclass transformation,folding pattern enumeration,just-in-time compilation,map folding,Numba optimization,OEIS,performance optimization,source code analysis,stamp folding
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
-Classifier: Intended Audience :: End Users/Desktop
-Classifier: Intended Audience :: Other Audience
 Classifier: Intended Audience :: Science/Research
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
@@ -23,7 +22,10 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Code Generators
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Compilers
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -43,6 +45,7 @@ Requires-Dist: pytest-cov; extra == "testing"
 Requires-Dist: pytest-env; extra == "testing"
 Requires-Dist: pytest-xdist; extra == "testing"
 Requires-Dist: pyupgrade; extra == "testing"
+Dynamic: license-file
 
 # mapFolding: Algorithms for enumerating distinct map/stamp folding patterns 🗺️
 
@@ -51,8 +54,6 @@ Requires-Dist: pyupgrade; extra == "testing"
 [![Python Tests](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml/badge.svg)](https://github.com/hunterhogan/mapFolding/actions/workflows/pythonTests.yml)
 ![Static Badge](https://img.shields.io/badge/issues-I%20have%20them-brightgreen)
 [![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/)
-![PyPI - Downloads](https://img.shields.io/pypi/dd/mapFolding)
-![GitHub repo size](https://img.shields.io/github/repo-size/hunterhogan/mapFolding)
 
 ---
 
@@ -100,44 +101,49 @@ Available OEIS sequences:
 
 ### 2. **Algorithm Zoo** 🦒
 
-- **Lunnon’s 1971 Algorithm**: A painstakingly debugged version of [the original typo-riddled code](https://github.com/hunterhogan/mapFolding/blob/mapFolding/reference/foldings.txt)
+- **Lunnon's 1971 Algorithm**: A painstakingly debugged version of [the original typo-riddled code](https://github.com/hunterhogan/mapFolding/blob/mapFolding/reference/foldings.txt)
 - The /reference directory.
 - **Numba-JIT Accelerated**: Up to 1000× faster than pure Python ([benchmarks](https://github.com/hunterhogan/mapFolding/blob/mapFolding/notes/Speed%20highlights.md))
 
-### 3. **For Researchers** 🔬
-
-- Change multiple minute settings, such as the bit width of the data types.
-- Transform the algorithm using AST
-- Create hyper-optimized modules to compute a specific map.
-
-### 4. **Customizing your algorithm**
-
-- Renovations in progress: ~~mapFolding\someAssemblyRequired\synthesizeNumbaJob.py (and/or synthesizeNumba____.py, as applicable)~~
-  - Synthesize a Numba-optimized module for a specific mapShape
-  - Synthesize _from_ a module in mapFolding\syntheticModules or from any source you select
-  - Use the existing transformation options
-  - Or create new ways of transforming the algorithm from its source to a specific job
-- Renovations in progress: ~~mapFolding\someAssemblyRequired\makeJob.py~~
-  - Initialize data for a specific mapShape
-- Renovations in progress: ~~mapFolding\someAssemblyRequired\synthesizeNumbaModules.py (and/or synthesizeNumba____.py, as applicable)~~
-  - Synthesize one or more Numba-optimized modules for parallel or sequential computation
-  - Overwrite the modules in mapFolding\syntheticModules or save the module(s) to a custom path
-  - Synthesize _from_ the algorithm(s) in mapFolding\theDao.py or from any source you select
-  - Use the existing transformation options
-  - Or create new ways of transforming the algorithm from its source to a new module
-  - Use your new module in synthesizeNumbaJob.py, above, as the source to create a mapShape-specific job module
-- mapFolding\theDao.py
-  - Modify the algorithms for initializing values, parallel computation, and/or sequential computation
-  - Use the modified algorithm(s) in synthesizeNumbaModules.py, above, to create Numba-optimized version(s)
-  - Then use a Numba-optimized version in synthesizeNumbaJob.py, above, to create a hyper-optimized version for a specific mapShape
-- mapFolding\theSSOT.py
-  - Modify broad settings or find functions to modify broad settings, such as data structures and their data types
-  - Create new settings or groups of settings
-- mapFolding\beDRY.py
-  - Functions to handle common tasks, such as parsing parameters or creating the `connectionGraph` for a mapShape (a Cartesian product decomposition)
-- mapFolding\someAssemblyRequired
-  - Create new transformations to optimize the algorithm, such as for JAX, CuPy, or CUDA
-  - (mapFolding\reference\jax.py has a once-functional JAX implementation, and synthesizeModuleJAX.py might be a useful starting point)
+### 3. **For Researchers and Power Users** 🔬
+
+This package provides a sophisticated code transformation framework that can turn readable algorithm implementations into highly-optimized computational engines:
+
+- **Algorithmic Exploration**: Study the core algorithm in `theDao.py`, which uses a functional state-transformation approach with clear, isolated functions
+- **Performance Optimization**: Generate specialized implementations with the `someAssemblyRequired` transformation pipeline:
+  - AST-based code analysis and manipulation
+  - Dataclass "shattering" to decompose complex state objects into primitive components
+  - Just-in-time compilation with Numba and various optimization profiles
+  - LLVM IR extraction for low-level algorithmic analysis
+
+- **Extensible Design**: The transformation framework is abstract and generic, enabling:
+  - Creation of new optimization targets beyond the included Numba implementation
+  - Customization of compilation parameters and optimization levels
+  - Development of specialized algorithms for specific map dimensions
+
+### 4. **Customization and Extension Guide**
+
+The package architecture supports multiple levels of customization:
+
+- **Basic Usage**: Work with the high-level API in `basecamp.py` for standard computations
+- **Algorithm Modification**:
+  - Modify the core algorithm in `theDao.py` while preserving its functional approach
+  - Configure system-wide settings in `theSSOT.py` to adjust data types and performance characteristics
+  - Use utility functions in `beDRY.py` for common operations
+
+- **Advanced Transformation**:
+  - The `someAssemblyRequired` package provides tools to transform code at the AST level:
+    - `transformationTools.py` contains utilities for AST manipulation and code generation
+    - `transformDataStructures.py` handles complex data structure transformations
+    - `ingredientsNumba.py` provides Numba-specific configuration profiles
+    - `synthesizeNumbaFlow.py` orchestrates the transformation process
+
+- **Custom Deployment**:
+  - Generate specialized implementations for specific dimensions
+  - Create optimized modules that can be executed as standalone scripts
+  - Extract LLVM IR for further analysis or optimization
+
+The package's multi-level design allows you to start with simple API calls and progressively delve deeper into optimization as your computational needs grow.
 
 ## Map-folding Video
 
@@ -154,4 +160,4 @@ Available OEIS sequences:
 [![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)
 
-[![CC-BY-NC-4.0](https://github.com/hunterhogan/mapFolding/blob/main/CC-BY-NC-4.0.png)](https://creativecommons.org/licenses/by-nc/4.0/)
+[![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/)

mapfolding-0.8.1.dist-info/RECORD

@@ -0,0 +1,39 @@
+mapFolding/__init__.py,sha256=hYxPUBU6A1_XCbKEseSDamooTsb1mzN_XHqaRLPvpGk,1701
+mapFolding/basecamp.py,sha256=7ghnbEcgMaGJYCy08GpOg0O28gY5P36ZibJkjs_r-Rg,4481
+mapFolding/beDRY.py,sha256=WRbvissfUGAmYbj1o0ZpGvq_9hwllDqpNwuC2_yxFyM,9785
+mapFolding/filesystem.py,sha256=-pYpWugd0p3TrAz7xf9YIJW-pn1X-iRCGtJgEAF9Rns,5923
+mapFolding/noHomeYet.py,sha256=UKZeWlyn0SKlF9dhYoud7E6gWXpiSEekZOOoJp88WeI,1362
+mapFolding/oeis.py,sha256=xArJ8X3HqzopKIKYdKwxk7Y62vtXZFxvZ0jEqv-8GO0,12625
+mapFolding/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mapFolding/theDao.py,sha256=Blzm5j24x1BE2nvgXjdzHEeuc2na6kAH9b_eP6PcwlI,9836
+mapFolding/theSSOT.py,sha256=pyetKz_Yuofm_z2XhNaQT_CWTatuAykZO2bxEPy9wS4,13670
+mapFolding/reference/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mapFolding/reference/flattened.py,sha256=KEIR8hhOW0NHDX52LHJrrTUY5QaCzexZF0S6P2wvogY,15209
+mapFolding/reference/hunterNumba.py,sha256=9MEy2szRSENZc9l1_VnRqBnnd71z4KjoPwOWnOwb9Pw,6105
+mapFolding/reference/irvineJavaPort.py,sha256=UkOSX0_dkKR84hp8aqHPuf7KLz_nVnji9M0IF_hRVm8,3418
+mapFolding/reference/jax.py,sha256=7ji9YWia6Kof0cjcNdiS1GG1rMbC5SBjcyVr_07AeUk,13845
+mapFolding/reference/lunnanNumpy.py,sha256=isI0dOYZM1CZi1P4NEojl9L2Kh45mOYtc2C8yXUit8E,3731
+mapFolding/reference/lunnanWhile.py,sha256=z1hcE6SeK0CFJSS4LggmzzsLNjU3dU26LsL5y_ZGBxM,3231
+mapFolding/reference/rotatedEntryPoint.py,sha256=S3y5hSUTYOR_lKBnd5SwufvjNvg3UP-Je4wpYRB-_78,9328
+mapFolding/reference/total_countPlus1vsPlusN.py,sha256=wpgay-uqPOBd64Z4Pg6tg40j7-4pzWHGMM6v0bnmjhE,6288
+mapFolding/someAssemblyRequired/__init__.py,sha256=xA5a-nZjXIwcqEOig5PEZSxde4_m3JJ5Pb0CN4aiRjw,2488
+mapFolding/someAssemblyRequired/getLLVMforNoReason.py,sha256=bGI8RZY-RnyR9TNF0r0OXwA6fm4TYH2cHy7WzhsnddQ,1895
+mapFolding/someAssemblyRequired/ingredientsNumba.py,sha256=g6Z7t35NpoDskzm0OLwTQhHw5CYiYktVYxI2NhCQHww,8435
+mapFolding/someAssemblyRequired/synthesizeNumbaFlow.py,sha256=EtzULVeivQ_4G2E2UKqXoZLx6XwRcbBDzhtzwCTOEfs,10627
+mapFolding/someAssemblyRequired/synthesizeNumbaJobVESTIGIAL.py,sha256=RBSrtr7US2P7mkY-EA-b2WIOxjs2b0WJaCln1ERxOcI,22314
+mapFolding/someAssemblyRequired/transformDataStructures.py,sha256=0qtILOuH8I4CWFog64SPAyOWTylCa2Yh7L_hILrQY9Q,8279
+mapFolding/someAssemblyRequired/transformationTools.py,sha256=vLRKAtaXa9RmoISUbFvQIWHDHor6CYctm7NEgU11T_E,40743
+mapFolding/syntheticModules/numbaCount_doTheNeedful.py,sha256=52RuwJVH2fROvWU2dT8wYcQvLgRuvkNZPq01kujCC_U,15725
+mapfolding-0.8.1.dist-info/licenses/LICENSE,sha256=NxH5Y8BdC-gNU-WSMwim3uMbID2iNDXJz7fHtuTdXhk,19346
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/conftest.py,sha256=rRlXOhihwheHyQ8ggjRBbmgPVERxWjupajguVBzBkVE,10783
+tests/test_computations.py,sha256=YhadlskBh_r5RiefHRy0FlrYQ0FelYbqcSNNSkSJMIY,3368
+tests/test_filesystem.py,sha256=Kou0gj5T72oISao6umYfU6L_W5Hi7QS9_IxTv2hU0Pw,3147
+tests/test_oeis.py,sha256=uxvwmgbnylSDdsVJfuAT0LuYLbIVFwSgdLxHm-xUGBM,5043
+tests/test_other.py,sha256=1uuApByNWPiTf0zaro2dETkvyWQFfMweU_ge4aJuVgM,4244
+tests/test_tasks.py,sha256=hkZygihT8bCEO2zc-2VcxReQrZJBwgLNbYx0YP4lTDg,2853
+mapfolding-0.8.1.dist-info/METADATA,sha256=Upa7kSAeKLeSk33CiII-W08xLugqgnqwIBVQu4VLEQg,7892
+mapfolding-0.8.1.dist-info/WHEEL,sha256=tTnHoFhvKQHCh4jz3yCn0WPTYIy7wXx3CJtJ7SJGV7c,91
+mapfolding-0.8.1.dist-info/entry_points.txt,sha256=F3OUeZR1XDTpoH7k3wXuRb3KF_kXTTeYhu5AGK1SiOQ,146
+mapfolding-0.8.1.dist-info/top_level.txt,sha256=1gP2vFaqPwHujGwb3UjtMlLEGN-943VSYFR7V4gDqW8,17
+mapfolding-0.8.1.dist-info/RECORD,,

{mapfolding-0.8.0.dist-info → mapfolding-0.8.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (76.1.0)
+Generator: setuptools (77.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

mapFolding/reference/lunnan.py

@@ -1,153 +0,0 @@
-"""
-An unnecessarily literal translation of the original Atlas Autocode code by W. F. Lunnon to Python.
-W. F. Lunnon, Multi-dimensional map-folding, The Computer Journal, Volume 14, Issue 1, 1971, Pages 75-80, https://doi.org/10.1093/comjnl/14.1.75
-"""# NOTE not functional yet
-def foldings(p, job=None):
-	"""An unnecessarily literal translation of the original Atlas Autocode code."""
-	p = list(p)
-	p.append(None)  # NOTE mimics Atlas `array` type
-	p.insert(0, None)  # NOTE mimics Atlas `array` type
-
-	if job is None:
-		global G
-		G = 0
-		def job(A, B):
-			global G
-			G = G + 1
-		return foldings(p, job)
-	# perform job (A, B) on each folding of a p[1] x ... x p[d] map,
-	# where A and B are the above and below vectors. p[d + 1] < 0 terminates p;
-
-	d: int
-	n: int
-	j: int
-	i: int
-	m: int
-	l: int
-	g: int
-	gg: int
-	dd: int
-
-	n = 1
-	i, d = 0, 0
-
-	while (i := i + 1) and p[i] is not None:
-		d = i
-		n = n * p[i]
-
-	# d dimensions and n leaves;
-
-	# A: list[int] = [None] * (n + 1) # type: ignore
-	# B: list[int] = [None] * (n + 1) # type: ignore
-	# count: list[int] = [None] * (n + 1) # type: ignore
-	# gapter: list[int] = [None] * (n + 1) # type: ignore
-	# gap: list[int] = [None] * (n * n + 1) # type: ignore
-	A: list[int] = [0] * (n + 1) # type: ignore
-	B: list[int] = [0] * (n + 1) # type: ignore
-	count: list[int] = [0] * (n + 1) # type: ignore
-	gapter: list[int] = [0] * (n + 1) # type: ignore
-	gap: list[int] = [0] * (n * n + 1) # type: ignore
-
-	# B[m] is the leaf below leaf m in the current folding,
-	# A[m] the leaf above. count[m] is the no. of sections in which
-	# there is a gap for the new leaf l below leaf m,
-	# gap[gapter[l - 1] + j] is the j-th (possible or actual) gap for leaf l,
-	# and later gap[gapter[l]] is the gap where leaf l is currently inserted;
-
-	P: list[int] = [0] * (d + 1) # type: ignore
-	C: list[list[int]] = [[0] * (n + 1) for dimension1 in range(d + 1)] # type: ignore
-	# D: list[list[list[int]]] = [[[None] * (n + 1) for dimension2 in range(n + 1)] for dimension1 in range(d + 1)] # type: ignore
-	D: list[list[list[int]]] = [[[0] * (n + 1) for dimension2 in range(n + 1)] for dimension1 in range(d + 1)]
-
-	P[0] = 1
-	for i in range(1, d + 1):
-		P[i] = P[i - 1] * p[i]
-
-	for i in range(1, d + 1):
-		for m in range(1, n + 1):
-			C[i][m] = ((m - 1) // P[i - 1]) - ((m - 1) // P[i]) * p[i] + 1
-
-	for i in range(1, d + 1):
-		for l in range(1, n + 1):
-			for m in range(1, l + 1):
-				D[i][l][m] = (0 if m == 0
-								else
-										((m if C[i][m] == 1
-											else m - P[i - 1])
-									if C[i][l] - C[i][m] == (C[i][l] - C[i][m]) // 2 * 2
-									else
-										(m if C[i][m] == p[i] or m + P[i - 1] > l
-											else m + P[i - 1])))
-	# P[i] = p[1] x ... x p[i], C[i][m] = i-th co-ordinate of leaf m,
-	# D[i][l][m] = leaf connected to m in section i when inserting l;
-
-	for m in range(n + 1):
-		count[m] = 0
-
-	A[0], B[0], g, l = 0, 0, 0, 0
-
-	state = 'entry'
-	while True:
-		if state == 'entry':
-			gapter[l] = g
-			l = l + 1
-			if l <= n:
-				state = 'down'
-				continue
-			else:
-				job(A, B)
-				state = 'up'
-				continue
-
-		elif state == 'down':
-			dd = 0
-			gg = gapter[l - 1]
-			g = gg
-			for i in range(1, d + 1):
-				if D[i][l][l] == l:
-					dd = dd + 1
-				else:
-					m = D[i][l][l]
-					while m != l:
-						gap[gg] = m
-						if count[m] == 0:
-							gg = gg + 1
-						count[m] = count[m] + 1
-						m = D[i][l][B[m]]
-
-			if dd == d:
-				for m in range(l):
-					gap[gg] = m
-					gg = gg + 1
-
-			for j in range(g, gg):
-				gap[g] = gap[j]
-				if count[gap[j]] == d - dd:
-					g = g + 1
-				count[gap[j]] = 0
-			state = 'along'
-			continue
-
-		elif state == 'along':
-			if g == gapter[l - 1]:
-				state = 'up'
-				continue
-			g = g - 1
-			A[l] = gap[g]
-			B[l] = B[A[l]]
-			B[A[l]] = l
-			A[B[l]] = l
-			state = 'entry'
-			continue
-
-		elif state == 'up':
-			l = l - 1
-			B[A[l]] = B[l]
-			A[B[l]] = A[l]
-			if l > 0:
-				state = 'along'
-				continue
-			else:
-				break
-
-	return G #if job.__closure__ else None