mapFolding 0.15.3__py3-none-any.whl → 0.16.0__py3-none-any.whl

mapFolding/__init__.py

@@ -15,17 +15,17 @@ The computational framework integrates type safety, persistent result storage,
 and mathematical validation through OEIS sequence integration.
 
 Core Transformation Tools:
-    countFolds: Primary interface for computing folding pattern counts
-    MapFoldingState: Computational state management for recursive analysis
-    Connection graph generation: Mathematical foundation for folding relationships
-    Task division utilities: Experimental parallel computation options
-    OEIS integration: Mathematical validation and sequence discovery
+	countFolds: Primary interface for computing folding pattern counts
+	MapFoldingState: Computational state management for recursive analysis
+	Connection graph generation: Mathematical foundation for folding relationships
+	Task division utilities: Experimental parallel computation options
+	OEIS integration: Mathematical validation and sequence discovery
 
 Primary Use Cases:
-    Mathematical research into folding pattern properties and relationships
-    Educational exploration of combinatorial mathematics concepts
-    Computational validation of theoretical results
-    Extension of known mathematical sequences through new discoveries
+	Mathematical research into folding pattern properties and relationships
+	Educational exploration of combinatorial mathematics concepts
+	Computational validation of theoretical results
+	Extension of known mathematical sequences through new discoveries
 
 The package handles the full spectrum of map folding analysis, from simple
 educational examples to research-grade computations requiring multi-day processing
@@ -50,11 +50,14 @@ from mapFolding._theTypes import (
 	DatatypeElephino as DatatypeElephino,
 	DatatypeFoldsTotal as DatatypeFoldsTotal,
 	DatatypeLeavesTotal as DatatypeLeavesTotal,
+	MetadataOEISidMapFolding as MetadataOEISidMapFolding,
+	MetadataOEISidMapFoldingManuallySet as MetadataOEISidMapFoldingManuallySet,
+	MetadataOEISidMeanders as MetadataOEISidMeanders,
+	MetadataOEISidMeandersManuallySet as MetadataOEISidMeandersManuallySet,
 	NumPyElephino as NumPyElephino,
 	NumPyFoldsTotal as NumPyFoldsTotal,
 	NumPyIntegerType as NumPyIntegerType,
-	NumPyLeavesTotal as NumPyLeavesTotal,
-)
+	NumPyLeavesTotal as NumPyLeavesTotal)
 
 from mapFolding._theSSOT import packageSettings as packageSettings
 
@@ -64,26 +67,25 @@ from mapFolding.beDRY import (
 	getTaskDivisions as getTaskDivisions,
 	makeDataContainer as makeDataContainer,
 	setProcessorLimit as setProcessorLimit,
-	validateListDimensions as validateListDimensions,
-)
+	validateListDimensions as validateListDimensions)
 
-from mapFolding.dataBaskets import MapFoldingState as MapFoldingState
+from mapFolding.dataBaskets import (
+    MapFoldingState as MapFoldingState,
+    MatrixMeandersState as MatrixMeandersState)
 
 from mapFolding.filesystemToolkit import (
 	getFilenameFoldsTotal as getFilenameFoldsTotal,
 	getPathFilenameFoldsTotal as getPathFilenameFoldsTotal,
 	getPathRootJobDEFAULT as getPathRootJobDEFAULT,
 	saveFoldsTotal as saveFoldsTotal,
-	saveFoldsTotalFAILearly as saveFoldsTotalFAILearly,
-)
+	saveFoldsTotalFAILearly as saveFoldsTotalFAILearly)
 
 from mapFolding.basecamp import countFolds as countFolds
 
 from mapFolding.oeis import (
-	clearOEIScache as clearOEIScache,
+	dictionaryOEISMapFolding as dictionaryOEISMapFolding,
+	dictionaryOEISMeanders as dictionaryOEISMeanders,
 	getFoldsTotalKnown as getFoldsTotalKnown,
 	getOEISids as getOEISids,
 	OEIS_for_n as OEIS_for_n,
-	oeisIDfor_n as oeisIDfor_n,
-    dictionaryOEIS as dictionaryOEIS,
-)
+	oeisIDfor_n as oeisIDfor_n)

mapFolding/_theSSOT.py

@@ -1,80 +1,50 @@
-"""Primary goal: access and configure package settings and metadata.
+"""Access and configure package settings and metadata."""
 
-Secondary goal: store hardcoded values until I implement a dynamic solution.
-"""
-
-from collections.abc import Callable
 from hunterMakesPy import PackageSettings
+from mapFolding._theTypes import MetadataOEISidMapFoldingManuallySet, MetadataOEISidMeandersManuallySet
 from pathlib import Path
-from typing import TypedDict
 import dataclasses
 import random
 
-# TODO eliminate hardcoding
-concurrencyPackageHARDCODED = 'multiprocessing'
-"""Default package identifier for concurrent execution operations."""
-
-class MetadataOEISidManuallySet(TypedDict):
-	"""Settings that are best selected by a human instead of algorithmically."""
-
-	getMapShape: Callable[[int], tuple[int, ...]]
-	"""Function to convert the OEIS sequence index, 'n', to its `mapShape` tuple."""
-	valuesBenchmark: list[int]
-	"""List of index values, 'n', to use when benchmarking the algorithm performance."""
-	valuesTestParallelization: list[int]
-	"""List of index values, 'n', to use when testing parallelization performance."""
-	valuesTestValidation: list[int]
-	"""List of index values, 'n', to use when testing validation performance."""
-
 @dataclasses.dataclass
 class mapFoldingPackageSettings(PackageSettings):
-	"""Centralized configuration container for all package-wide settings.
-
-	(AI generated docstring)
-
-	This dataclass serves as the single source of truth for package configuration,
-	providing both static and dynamically-resolved values needed throughout the
-	package lifecycle. The metadata on each field indicates when that value is
-	determined - either during packaging or at installation/runtime.
-
-	The design supports different evaluation phases to optimize performance and
-	reliability. Packaging-time values can be determined during package creation,
-	while installing-time values require filesystem access or module introspection.
+	"""Widely used settings that are especially useful for map folding algorithms.
 
 	Attributes
 	----------
+	identifierPackageFALLBACK : str = ''
+		Fallback package identifier used only during initialization when automatic discovery fails.
+	pathPackage : Path = Path()
+		Absolute path to the installed package directory. Automatically resolved from `identifierPackage` if not provided.
+	identifierPackage : str = ''
+		Canonical name of the package. Automatically extracted from `pyproject.toml`.
 	fileExtension : str = '.py'
-		Standard file extension for Python modules in this package.
-	packageName : str
-		Canonical name of the package as defined in project configuration.
-	pathPackage : Path
-		Absolute filesystem path to the installed package directory.
-	concurrencyPackage : str | None = None
-		Package identifier for concurrent execution operations.
+		Default file extension.
 
+	cacheDays : int = 30
+		Number of days to retain cached OEIS data before refreshing from the online source.
+	concurrencyPackage : str = 'multiprocessing'
+		Package identifier for concurrent execution operations.
+	OEISidMapFoldingManuallySet : dict[str, MetadataOEISidMapFoldingManuallySet]
+		Settings that are best selected by a human instead of algorithmically.
+	OEISidMeandersManuallySet : dict[str, MetadataOEISidMeandersManuallySet]
+		Settings that are best selected by a human instead of algorithmically for meander sequences.
 	"""
 
-	concurrencyPackage: str | None = None
-	"""
-	Package identifier for concurrent execution operations.
-
-	(AI generated docstring)
+	OEISidMapFoldingManuallySet: dict[str, MetadataOEISidMapFoldingManuallySet] = dataclasses.field(default_factory=dict[str, MetadataOEISidMapFoldingManuallySet])
+	"""Settings that are best selected by a human instead of algorithmically."""
 
-	Specifies which Python package should be used for parallel processing
-	in computationally intensive operations. When None, the default concurrency
-	package specified in the module constants is used. Accepted values include
-	'multiprocessing' for standard parallel processing and 'numba' for
-	specialized numerical computations.
-	"""
+	OEISidMeandersManuallySet: dict[str, MetadataOEISidMeandersManuallySet] = dataclasses.field(default_factory=dict[str, MetadataOEISidMeandersManuallySet])
+	"""Settings that are best selected by a human instead of algorithmically for meander sequences."""
 
-identifierPackageFALLBACK = "mapFolding"
-"""Hardcoded package name used as fallback when dynamic resolution fails."""
+	cacheDays: int = 30
+	"""Number of days to retain cached OEIS data before refreshing from the online source."""
 
-concurrencyPackage = concurrencyPackageHARDCODED
-"""Active concurrency package configuration for the current session."""
+	concurrencyPackage: str = 'multiprocessing'
+	"""Package identifier for concurrent execution operations."""
 
 # TODO I made a `TypedDict` before I knew how to make dataclasses and classes. Think about other data structures.
-settingsOEISManuallySelected: dict[str, MetadataOEISidManuallySet] = {
+OEISidMapFoldingManuallySet: dict[str, MetadataOEISidMapFoldingManuallySet] = {
 	'A000136': {
 		'getMapShape': lambda n: (1, n),
 		'valuesBenchmark': [14],
@@ -119,11 +89,35 @@ settingsOEISManuallySelected: dict[str, MetadataOEISidManuallySet] = {
 	},
 }
 
-packageSettings = mapFoldingPackageSettings(
-	identifierPackageFALLBACK=identifierPackageFALLBACK
-	, concurrencyPackage=concurrencyPackage)
+identifierPackageFALLBACK = "mapFolding"
+"""Manually entered package name used as fallback when dynamic resolution fails."""
+
+packageSettings = mapFoldingPackageSettings(identifierPackageFALLBACK=identifierPackageFALLBACK, OEISidMapFoldingManuallySet=OEISidMapFoldingManuallySet)
 """Global package settings."""
-cacheDays = 30
-"""Number of days to retain cached OEIS data before refreshing from the online source."""
+
+# TODO integrate into packageSettings
 pathCache: Path = packageSettings.pathPackage / ".cache"
 """Local directory path for storing cached OEIS sequence data and metadata."""
+OEISidMeandersManuallySet: dict[str, MetadataOEISidMeandersManuallySet] = {
+	'A000560': {'valuesTestValidation': [*range(3, 12)]},
+	'A000682': {'valuesTestValidation': [*range(3, 12)]},
+	'A001010': {'valuesTestValidation': [*range(3, 11)]},
+	'A001011': {'valuesTestValidation': [*range(3, 7)]},
+	'A005315': {'valuesTestValidation': [*range(3, 9)]},
+	'A005316': {'valuesTestValidation': [*range(3, 13)]},
+	'A060206': {'valuesTestValidation': [*range(3, 9)]},
+	'A077460': {'valuesTestValidation': [*range(3, 8)]},
+	'A078591': {'valuesTestValidation': [*range(3, 10)]},
+	'A178961': {'valuesTestValidation': [*range(3, 11)]},
+	'A223094': {'valuesTestValidation': [*range(3, 11)]},
+	'A259702': {'valuesTestValidation': [*range(3, 13)]},
+	'A301620': {'valuesTestValidation': [*range(3, 11)]},
+}
+
+# Recreate packageSettings with meanders settings included
+packageSettings = mapFoldingPackageSettings(
+	identifierPackageFALLBACK=identifierPackageFALLBACK,
+	OEISidMapFoldingManuallySet=OEISidMapFoldingManuallySet,
+	OEISidMeandersManuallySet=OEISidMeandersManuallySet,
+)
+"""Global package settings."""

mapFolding/_theTypes.py

@@ -1,7 +1,8 @@
 """Types for defensive coding and for computation optimization."""
 
+from collections.abc import Callable
 from numpy import dtype, int_ as numpy_int, integer, ndarray, uint64 as numpy_uint64
-from typing import Any, TypeAlias, TypeVar
+from typing import Any, TypeAlias, TypedDict, TypeVar
 
 NumPyIntegerType = TypeVar('NumPyIntegerType', bound=integer[Any], covariant=True)
 """Any NumPy integer type, which is usually between 8-bit signed and 64-bit unsigned."""
@@ -19,9 +20,9 @@ Note well
 ---------
 Colossal values are found with the cross humpy inequality:
 
-    ⎡ el  ⎤   ⎡     ⎤
-    ⎢ eph ⎥ X ⎢ rhi ⎥ <= elephino
-    ⎣ ant ⎦   ⎣ no  ⎦
+	⎡ el  ⎤   ⎡     ⎤
+	⎢ eph ⎥ X ⎢ rhi ⎥ <= elephino
+	⎣ ant ⎦   ⎣ no  ⎦
 
 """
 
@@ -50,3 +51,64 @@ Array1DElephino: TypeAlias = ndarray[tuple[int], dtype[NumPyElephino]]  # noqa:
 
 Array1DFoldsTotal: TypeAlias = ndarray[tuple[int], dtype[NumPyFoldsTotal]]  # noqa: UP040 The TypeAlias may be used to construct ("cast") a value to the type. And the identifier may be changed to a different type.
 """A `numpy.ndarray` with one axis and elements of type `NumPyFoldsTotal`."""
+
+class MetadataOEISidMapFoldingManuallySet(TypedDict):
+	"""Settings that are best selected by a human instead of algorithmically."""
+
+	getMapShape: Callable[[int], tuple[int, ...]]
+	"""Function to convert the OEIS sequence index, 'n', to its `mapShape` tuple."""
+	valuesBenchmark: list[int]
+	"""List of index values, 'n', to use when benchmarking the algorithm performance."""
+	valuesTestParallelization: list[int]
+	"""List of index values, 'n', to use when testing parallelization performance."""
+	valuesTestValidation: list[int]
+	"""List of index values, 'n', to use when testing validation performance."""
+
+class MetadataOEISidMapFolding(TypedDict):
+	"""Settings for an implemented OEIS sequence."""
+
+	description: str
+	"""The OEIS.org description of the integer sequence."""
+	getMapShape: Callable[[int], tuple[int, ...]]
+	"""Function to convert the OEIS sequence index, 'n', to its `mapShape` tuple."""
+	offset: int
+	"""The starting index, 'n', of the sequence, typically 0 or 1."""
+	valuesBenchmark: list[int]
+	"""List of index values, 'n', to use when benchmarking the algorithm performance."""
+	valuesKnown: dict[int, int]
+	"""Dictionary of sequence indices, 'n', to their known values, `foldsTotal`."""
+	valuesTestParallelization: list[int]
+	"""List of index values, 'n', to use when testing parallelization performance."""
+	valuesTestValidation: list[int]
+	"""List of index values, 'n', to use when testing validation performance."""
+	valueUnknown: int
+	"""The smallest value of 'n' for for which `foldsTotal` is unknown."""
+
+# ruff: noqa: ERA001
+class MetadataOEISidMeandersManuallySet(TypedDict):
+	"""Settings that are best selected by a human instead of algorithmically."""
+
+	# valuesBenchmark: list[int]
+	"""List of index values, 'n', to use when benchmarking the algorithm performance."""
+	# valuesTestParallelization: list[int]
+	"""List of index values, 'n', to use when testing parallelization performance."""
+	valuesTestValidation: list[int]
+	"""List of index values, 'n', to use when testing validation performance."""
+
+class MetadataOEISidMeanders(TypedDict):
+	"""Settings for an implemented OEIS sequence."""
+
+	description: str
+	"""The OEIS.org description of the integer sequence."""
+	offset: int
+	"""The starting index, 'n', of the sequence, typically 0 or 1."""
+	# valuesBenchmark: list[int]
+	"""List of index values, 'n', to use when benchmarking the algorithm performance."""
+	valuesKnown: dict[int, int]
+	"""Dictionary of sequence indices, 'n', to their known values, `foldsTotal`."""
+	# valuesTestParallelization: list[int]
+	"""List of index values, 'n', to use when testing parallelization performance."""
+	valuesTestValidation: list[int]
+	"""List of index values, 'n', to use when testing validation performance."""
+	valueUnknown: int
+	"""The smallest value of 'n' for for which `foldsTotal` is unknown."""

mapFolding/algorithms/__init__.py

@@ -0,0 +1 @@
+"""Hand-made algorithms."""

mapFolding/{daoOfMapFolding.py → algorithms/daoOfMapFolding.py}

@@ -1,4 +1,3 @@
-# ruff: noqa: D100 D103
 from mapFolding.dataBaskets import MapFoldingState
 
 def activeLeafGreaterThan0(state: MapFoldingState) -> bool:
@@ -140,4 +139,4 @@ def count(state: MapFoldingState) -> MapFoldingState:
 
 def doTheNeedful(state: MapFoldingState) -> MapFoldingState:
 	state = count(state)
-	return state  # noqa: RET504
+	return state

mapFolding/algorithms/getBucketsTotal.py

@@ -0,0 +1,137 @@
+"""Buckets."""
+from mapFolding import MatrixMeandersState
+from mapFolding.reference.A005316facts import bucketsIf_k_EVEN_by_nLess_k, bucketsIf_k_ODD_by_nLess_k
+from math import exp, log
+from typing import NamedTuple
+import math
+
+class ImaKey(NamedTuple):
+	"""keys for dictionaries."""
+
+	oeisID: str
+	kIsOdd: bool
+	nLess_kIsOdd: bool
+
+def getBucketsTotal(state: MatrixMeandersState, safetyMultiplicand: float = 1.2) -> int:
+	"""Estimate the total number of non-unique curveLocations that will be computed from the existing curveLocations.
+
+	Notes
+	-----
+	Subexponential bucketsTotal unified estimator parameters (derived in reference notebook).
+
+	The model is: log(buckets) = intercept + bN*log(n) + bK*log(k) + bD*log(n-k) + g_r*(k/n) + g_r2*(k/n)^2 + g_s*((n-k)/n) + offset(subseries)
+	Subseries key: f"{oeisID}_kOdd={int(kIsOdd)}_dOdd={int(nLess_kIsOdd)}" with a reference subseries offset of zero.
+	These coefficients intentionally remain in-source (SSOT) to avoid runtime JSON parsing overhead and to support reproducibility.
+	"""
+	dictionaryExponentialCoefficients: dict[ImaKey, float] = {
+		(ImaKey(oeisID='', kIsOdd=False, nLess_kIsOdd=True)): 0.834,
+		(ImaKey(oeisID='', kIsOdd=False, nLess_kIsOdd=False)): 1.5803,
+		(ImaKey(oeisID='', kIsOdd=True, nLess_kIsOdd=True)): 1.556,
+		(ImaKey(oeisID='', kIsOdd=True, nLess_kIsOdd=False)): 1.8047,
+	}
+
+	logarithmicOffsets: dict[ImaKey, float] ={
+		(ImaKey('A000682', kIsOdd=False, nLess_kIsOdd=False)): 0.0,
+		(ImaKey('A000682', kIsOdd=False, nLess_kIsOdd=True)): -0.07302547148212568,
+		(ImaKey('A000682', kIsOdd=True, nLess_kIsOdd=False)): -0.00595307513938792,
+		(ImaKey('A000682', kIsOdd=True, nLess_kIsOdd=True)): -0.012201222865243722,
+		(ImaKey('A005316', kIsOdd=False, nLess_kIsOdd=False)): -0.6392728422078733,
+		(ImaKey('A005316', kIsOdd=False, nLess_kIsOdd=True)): -0.6904925299923548,
+		(ImaKey('A005316', kIsOdd=True, nLess_kIsOdd=False)): 0.0,
+		(ImaKey('A005316', kIsOdd=True, nLess_kIsOdd=True)): 0.0,
+	}
+
+	logarithmicParameters: dict[str, float] = {
+		'intercept': -166.1750299793178,
+		'log(n)': 1259.0051001675547,
+		'log(k)': -396.4306071056408,
+		'log(nLess_k)': -854.3309503739766,
+		'k/n': 716.530410654819,
+		'(k/n)^2': -2527.035113444166,
+		'normalized k': -882.7054406339189,
+	}
+
+	bucketsTotalMaximumBy_kOfMatrix: dict[int, int] = {1:3, 2:12, 3:40, 4:125, 5:392, 6:1254, 7:4087, 8:13623, 9:46181, 10:159137, 11:555469, 12:1961369, 13:6991893, 14:25134208}
+
+	xCommon = 1.57
+
+	nLess_k: int = state.n - state.kOfMatrix
+	kIsOdd: bool = bool(state.kOfMatrix & 1)
+	nLess_kIsOdd: bool = bool(nLess_k & 1)
+	kIsEven: bool = not kIsOdd
+	bucketsTotal: int = -8
+
+	"""NOTE temporary notes
+	I have a fault in my thinking. bucketsTotal increases as k decreases until ~0.4k, then bucketsTotal decreases rapidly to 1. I
+	have ignored the decreasing side. In the formulas for estimation, I didn't differentiate between increasing and decreasing.
+	So, I probably need to refine the formulas. I guess I need to add checks to the if/else monster, too.
+
+	While buckets is increasing:
+		3 types of estimates:
+			1. Exponential growth.
+			2. Logarithmic growth.
+			3. Hard ceiling.
+	While buckets is decreasing:
+		1. Hard ceiling, same as increasing side.
+		2. ???
+		3. buckets = 1.
+
+	The formula for exponential growth _never_ underestimates. I haven't measured by how much it overestimates.
+
+	"""
+
+	bucketsTotalAtMaximum: bool = state.kOfMatrix <= ((state.n - 1 - (state.kOfMatrix % 2)) // 3)
+	bucketsTotalGrowsExponentially: bool = state.kOfMatrix > nLess_k
+	bucketsTotalGrowsLogarithmically: bool = state.kOfMatrix > ((state.n - (state.n % 3)) // 3)
+
+	if bucketsTotalAtMaximum:
+		if state.kOfMatrix in bucketsTotalMaximumBy_kOfMatrix:
+			bucketsTotal = bucketsTotalMaximumBy_kOfMatrix[state.kOfMatrix]
+		else:
+			c = 0.95037
+			r = 3.3591258254
+			if kIsOdd:
+				c = 0.92444
+				r = 3.35776
+			bucketsTotal = int(c * r**state.kOfMatrix * safetyMultiplicand)
+
+	elif bucketsTotalGrowsExponentially:
+		if (state.oeisID == 'A005316') and kIsOdd and (nLess_k in bucketsIf_k_ODD_by_nLess_k):
+			# If I already know bucketsTotal.
+			bucketsTotal = bucketsIf_k_ODD_by_nLess_k[nLess_k]
+		elif (state.oeisID == 'A005316') and kIsEven and (nLess_k in bucketsIf_k_EVEN_by_nLess_k):
+			# If I already know bucketsTotal.
+			bucketsTotal = bucketsIf_k_EVEN_by_nLess_k[nLess_k]
+		else: # I estimate bucketsTotal during exponential growth.
+			xInstant: int = math.ceil(nLess_k / 2)
+			A000682adjustStartingCurveLocations: float = 0.25
+			startingConditionsCoefficient: float = dictionaryExponentialCoefficients[ImaKey('', kIsOdd, nLess_kIsOdd)]
+			if kIsOdd and nLess_kIsOdd:
+				A000682adjustStartingCurveLocations = 0.0
+			if state.oeisID == 'A000682': # NOTE Net effect is between `*= n` and `*= n * 2.2` if n=46.
+				startingConditionsCoefficient *= state.n * (((state.n // 2) + 2) ** A000682adjustStartingCurveLocations)
+			bucketsTotal = int(startingConditionsCoefficient * math.exp(xCommon * xInstant))
+
+	elif state.kOfMatrix <= max(bucketsTotalMaximumBy_kOfMatrix.keys()):
+		# If `kOfMatrix` is low, use maximum bucketsTotal. 1. Can't underestimate. 2. Skip computation that can underestimate.
+		# 3. The potential difference in memory use is relatively small.
+		bucketsTotal = bucketsTotalMaximumBy_kOfMatrix[state.kOfMatrix]
+
+	elif bucketsTotalGrowsLogarithmically:
+		xPower: float = (0
+			+ logarithmicParameters['intercept']
+			+ logarithmicParameters['log(n)'] * log(state.n)
+			+ logarithmicParameters['log(k)'] * log(state.kOfMatrix)
+			+ logarithmicParameters['log(nLess_k)'] * log(nLess_k)
+			+ logarithmicParameters['k/n'] * (state.kOfMatrix / state.n)
+			+ logarithmicParameters['(k/n)^2'] * (state.kOfMatrix / state.n)**2
+			+ logarithmicParameters['normalized k'] * nLess_k / state.n
+			+ logarithmicOffsets[ImaKey(state.oeisID, kIsOdd, nLess_kIsOdd)]
+		)
+
+		bucketsTotal = int(exp(xPower * safetyMultiplicand))
+
+	else:
+		message = "I shouldn't be here."
+		raise SystemError(message)
+	return bucketsTotal