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

mapFolding/dataBaskets.py

@@ -24,6 +24,7 @@ from mapFolding import (
 	Array1DElephino, Array1DLeavesTotal, Array3DLeavesTotal, DatatypeElephino, DatatypeFoldsTotal, DatatypeLeavesTotal,
 	getConnectionGraph, getLeavesTotal, makeDataContainer)
 import dataclasses
+import numpy
 
 @dataclasses.dataclass
 class MapFoldingState:
@@ -268,3 +269,76 @@ class LeafSequenceState(MapFoldingState):
 		if self.leafSequence is None: # pyright: ignore[reportUnnecessaryComparison]
 			self.leafSequence = makeDataContainer(groupsOfFoldsKnown, self.__dataclass_fields__['leafSequence'].metadata['dtype'])
 			self.leafSequence[self.groupsOfFolds] = self.leaf1ndex
+
+
+@dataclasses.dataclass
+class MatrixMeandersState:
+	"""State."""
+
+	n: int
+	oeisID: str
+	kOfMatrix: int
+	dictionaryCurveLocations: dict[int, int]
+
+	datatypeCurveLocations: type = numpy.uint64
+	datatypeDistinctCrossings: type = numpy.uint64
+
+	bitWidthCurveLocationsMaximum: int | None = None
+	bitWidthDistinctCrossingsMaximum: int | None = None
+
+	bitWidth: int = 0
+	indexStartAnalyzed: int = 0
+
+	def __post_init__(self) -> None:
+		"""Post init."""
+		if self.bitWidthCurveLocationsMaximum is None:
+			_bitWidthOfFixedSizeInteger: int = numpy.dtype(self.datatypeCurveLocations).itemsize * 8 # bits
+
+			_offsetNecessary: int = 3 # For example, `groupZulu << 3`.
+			_offsetSafety: int = 1 # I don't have mathematical proof of how many extra bits I need.
+			_offset: int = _offsetNecessary + _offsetSafety
+
+			self.bitWidthCurveLocationsMaximum = _bitWidthOfFixedSizeInteger - _offset
+
+			del _bitWidthOfFixedSizeInteger, _offsetNecessary, _offsetSafety, _offset
+
+		if self.bitWidthDistinctCrossingsMaximum is None:
+			_bitWidthOfFixedSizeInteger: int = numpy.dtype(self.datatypeDistinctCrossings).itemsize * 8 # bits
+
+			_offsetNecessary: int = 0 # I don't know of any.
+			_offsetEstimation: int = 3 # See reference directory.
+			_offsetSafety: int = 1
+			_offset: int = _offsetNecessary + _offsetEstimation + _offsetSafety
+
+			self.bitWidthDistinctCrossingsMaximum = _bitWidthOfFixedSizeInteger - _offset
+
+			del _bitWidthOfFixedSizeInteger, _offsetNecessary, _offsetEstimation, _offsetSafety, _offset
+
+	@property
+	def MAXIMUMcurveLocations(self) -> int:
+		"""Compute the maximum value of `curveLocations` for the current iteration of the transfer matrix."""
+		return 1 << (2 * self.kOfMatrix + 4)
+
+	@property
+	def locatorGroupAlpha(self) -> int:
+		"""Compute an odd-parity bit-mask with `bitWidth` bits.
+
+		Notes
+		-----
+		In binary, `locatorGroupAlpha` has alternating 0s and 1s and ends with a 1, such as '101', '0101', and '10101'. The last
+		digit is in the 1's column, but programmers usually call it the "least significant bit" (LSB). If we count the columns
+		from the right, the 1's column is column 1, the 2's column is column 2, the 4's column is column 3, and so on. When
+		counting this way, `locatorGroupAlpha` has 1s in the columns with odd index numbers. Mathematicians and programmers,
+		therefore, tend to call `locatorGroupAlpha` something like the "odd bit-mask", the "odd-parity numbers", or simply "odd
+		mask" or "odd numbers". In addition to "odd" being inherently ambiguous in this context, this algorithm also segregates
+		odd numbers from even numbers, so I avoid using "odd" and "even" in the names of these bit-masks.
+
+		"""
+		return sum(1 << one for one in range(0, self.bitWidth, 2))
+
+	@property
+	def locatorGroupZulu(self) -> int:
+		"""Compute an even-parity bit-mask with `bitWidth` bits."""
+		return sum(1 << one for one in range(1, self.bitWidth, 2))
+
+

mapFolding/oeis.py

@@ -24,41 +24,20 @@ redundant computation, or extending mathematical knowledge, this integration
 completes the journey from configuration foundation to mathematical discovery.
 """
 
-from collections.abc import Callable
 from datetime import datetime, timedelta, UTC
 from hunterMakesPy import writeStringToHere
 from itertools import chain
-from mapFolding import countFolds
-from mapFolding._theSSOT import cacheDays, pathCache, settingsOEISManuallySelected
+from mapFolding import countFolds, MetadataOEISidMapFolding, MetadataOEISidMeanders, packageSettings
+from mapFolding._theSSOT import pathCache
 from pathlib import Path
-from typing import Final, TypedDict
+from typing import Final
 from urllib.request import urlopen
 import argparse
 import sys
 import time
 import warnings
 
-class MetadataOEISid(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."""
-
-oeisIDsImplemented: Final[list[str]]  = sorted([oeisID.upper().strip() for oeisID in settingsOEISManuallySelected])
+oeisIDsImplemented: Final[list[str]]  = sorted([oeisID.upper().strip() for oeisID in packageSettings.OEISidMapFoldingManuallySet])
 """Directly implemented OEIS IDs; standardized, e.g., 'A001415'."""
 
 def _standardizeOEISid(oeisID: str) -> str:
@@ -134,13 +113,7 @@ def _parseBFileOEIS(OEISbFile: str) -> dict[int, int]:
 	return OEISsequence
 
 def _getOEISofficial(pathFilenameCache: Path, url: str) -> None | str:
-	"""Retrieve OEIS sequence data from cache or online source with intelligent caching.
-
-	(AI generated docstring)
-
-	This function implements a caching strategy that prioritizes local cached data when it exists and
-	has not expired. Fresh data is retrieved from the OEIS website when the cache is stale or missing,
-	and the cache is updated for future use.
+	"""Retrieve OEIS ID data from oeis.org or local cache.
 
 	Parameters
 	----------
@@ -154,16 +127,11 @@ def _getOEISofficial(pathFilenameCache: Path, url: str) -> None | str:
 	oeisInformation : str | None
 		The retrieved OEIS sequence information as a string, or `None` if retrieval failed.
 
-	Notes
-	-----
-	Cache expiration is controlled by the module-level `cacheDays` variable. The function validates
-	URL schemes and issues warnings for failed retrievals.
-
 	"""
 	tryCache: bool = False
 	if pathFilenameCache.exists():
 		fileAge: timedelta = datetime.now(tz=UTC) - datetime.fromtimestamp(pathFilenameCache.stat().st_mtime, tz=UTC)
-		tryCache = fileAge < timedelta(days=cacheDays)
+		tryCache = fileAge < timedelta(days=packageSettings.cacheDays)
 
 	oeisInformation: str | None = None
 	if tryCache:
@@ -176,7 +144,8 @@ def _getOEISofficial(pathFilenameCache: Path, url: str) -> None | str:
 		if not url.startswith(("http:", "https:")):
 			message = "URL must start with 'http:' or 'https:'"
 			raise ValueError(message)
-		with urlopen(url) as response:
+
+		with urlopen(url) as response:  # noqa: S310
 			oeisInformationRaw = response.read().decode('utf-8')
 		oeisInformation = str(oeisInformationRaw)
 		writeStringToHere(oeisInformation, pathFilenameCache)
@@ -279,7 +248,7 @@ def getOEISidInformation(oeisID: str) -> tuple[str, int]:
 	description: str = ' '.join(listDescriptionDeconstructed)
 	return description, offset
 
-def _makeDictionaryOEIS() -> dict[str, MetadataOEISid]:
+def _makeDictionaryOEIS() -> dict[str, MetadataOEISidMapFolding]:
 	"""Construct the comprehensive settings dictionary for all implemented OEIS sequences.
 
 	(AI generated docstring)
@@ -302,23 +271,23 @@ def _makeDictionaryOEIS() -> dict[str, MetadataOEISid]:
 		objects, containing all metadata and known values needed for computation and validation.
 
 	"""
-	dictionaryOEIS: dict[str, MetadataOEISid] = {}
+	dictionaryOEIS: dict[str, MetadataOEISidMapFolding] = {}
 	for oeisID in oeisIDsImplemented:
 		valuesKnownSherpa: dict[int, int] = getOEISidValues(oeisID)
 		descriptionSherpa, offsetSherpa = getOEISidInformation(oeisID)
-		dictionaryOEIS[oeisID] = MetadataOEISid(
+		dictionaryOEIS[oeisID] = MetadataOEISidMapFolding(
 			description=descriptionSherpa,
 			offset=offsetSherpa,
-			getMapShape=settingsOEISManuallySelected[oeisID]['getMapShape'],
-			valuesBenchmark=settingsOEISManuallySelected[oeisID]['valuesBenchmark'],
-			valuesTestParallelization=settingsOEISManuallySelected[oeisID]['valuesTestParallelization'],
-			valuesTestValidation=settingsOEISManuallySelected[oeisID]['valuesTestValidation'] + list(range(offsetSherpa, 2)),
+			getMapShape=packageSettings.OEISidMapFoldingManuallySet[oeisID]['getMapShape'],
+			valuesBenchmark=packageSettings.OEISidMapFoldingManuallySet[oeisID]['valuesBenchmark'],
+			valuesTestParallelization=packageSettings.OEISidMapFoldingManuallySet[oeisID]['valuesTestParallelization'],
+			valuesTestValidation=packageSettings.OEISidMapFoldingManuallySet[oeisID]['valuesTestValidation'] + list(range(offsetSherpa, 2)),
 			valuesKnown=valuesKnownSherpa,
 			valueUnknown=max(valuesKnownSherpa.keys(), default=0) + 1
 		)
 	return dictionaryOEIS
 
-dictionaryOEIS: dict[str, MetadataOEISid] = _makeDictionaryOEIS()
+dictionaryOEISMapFolding: dict[str, MetadataOEISidMapFolding] = _makeDictionaryOEIS()
 """Metadata for each OEIS sequence ID."""
 
 def makeDictionaryFoldsTotalKnown() -> dict[tuple[int, ...], int]:
@@ -332,7 +301,7 @@ def makeDictionaryFoldsTotalKnown() -> dict[tuple[int, ...], int]:
 
 	"""
 	return dict(chain.from_iterable(zip(map(oeisIDmetadata['getMapShape'], oeisIDmetadata['valuesKnown'].keys())
-	, oeisIDmetadata['valuesKnown'].values(), strict=True) for oeisID, oeisIDmetadata in dictionaryOEIS.items() if oeisID != 'A007822'))
+	, oeisIDmetadata['valuesKnown'].values(), strict=True) for oeisID, oeisIDmetadata in dictionaryOEISMapFolding.items() if oeisID != 'A007822'))
 
 def getFoldsTotalKnown(mapShape: tuple[int, ...]) -> int:
 	"""Retrieve the known total number of distinct folding patterns for a given map shape.
@@ -378,7 +347,7 @@ def _formatHelpText() -> str:
 
 	"""
 	exampleOEISid: str = oeisIDsImplemented[0]
-	exampleN: int = dictionaryOEIS[exampleOEISid]['valuesTestValidation'][-1]
+	exampleN: int = dictionaryOEISMapFolding[exampleOEISid]['valuesTestValidation'][-1]
 
 	return (
 		"\nAvailable OEIS sequences:\n"
@@ -406,7 +375,7 @@ def _formatOEISsequenceInfo() -> str:
 
 	"""
 	return "\n".join(
-		f"  {oeisID}: {dictionaryOEIS[oeisID]['description']}"
+		f"  {oeisID}: {dictionaryOEISMapFolding[oeisID]['description']}"
 		for oeisID in oeisIDsImplemented
 	)
 
@@ -441,17 +410,18 @@ def oeisIDfor_n(oeisID: str, n: int) -> int:
 		message = f"I received `{n = }` in the form of `{type(n) = }`, but it must be non-negative integer in the form of `{int}`."
 		raise ValueError(message)
 
-	mapShape = dictionaryOEIS[oeisID]['getMapShape'](n)
+	mapShape = dictionaryOEISMapFolding[oeisID]['getMapShape'](n)
 
 	if n <= 1 or len(mapShape) < 2:
-		offset: int = dictionaryOEIS[oeisID]['offset']
+		offset: int = dictionaryOEISMapFolding[oeisID]['offset']
 		if n < offset:
 			message = f"OEIS sequence {oeisID} is not defined at {n = }."
 			raise ArithmeticError(message)
-		foldsTotal: int = dictionaryOEIS[oeisID]['valuesKnown'][n]
-		return foldsTotal
+		foldsTotal: int = dictionaryOEISMapFolding[oeisID]['valuesKnown'][n]
+	else:
+		foldsTotal = countFolds(oeisID=oeisID, oeis_n=n)
 
-	return countFolds(mapShape, oeisID=oeisID)
+	return foldsTotal
 
 def OEIS_for_n() -> None:
 	"""Command-line interface for calculating OEIS sequence values.
@@ -513,7 +483,7 @@ def clearOEIScache() -> None:
 	if not pathCache.exists():
 		print(f"Cache directory, {pathCache}, not found - nothing to clear.")  # noqa: T201
 		return
-	for oeisID in dictionaryOEIS:
+	for oeisID in dictionaryOEISMapFolding:
 		( pathCache / f"{oeisID}.txt" ).unlink(missing_ok=True)
 		( pathCache / _getFilenameOEISbFile(oeisID) ).unlink(missing_ok=True)
 	print(f"Cache cleared from {pathCache}")  # noqa: T201
@@ -534,5 +504,22 @@ def getOEISids() -> None:
 	"""
 	print(_formatHelpText())  # noqa: T201
 
+def _makeDictionaryOEISMeanders() -> dict[str, MetadataOEISidMeanders]:
+	dictionary: dict[str, MetadataOEISidMeanders] = {}
+	for oeisID in packageSettings.OEISidMeandersManuallySet:
+		valuesKnownSherpa: dict[int, int] = getOEISidValues(oeisID)
+		descriptionSherpa, offsetSherpa = getOEISidInformation(oeisID)
+		dictionary[oeisID] = MetadataOEISidMeanders(
+			description=descriptionSherpa,
+			offset=offsetSherpa,
+			valuesKnown=valuesKnownSherpa,
+			valuesTestValidation=packageSettings.OEISidMeandersManuallySet[oeisID]['valuesTestValidation'],
+			valueUnknown=max(valuesKnownSherpa.keys(), default=0) + 1,
+		)
+	return dictionary
+
+dictionaryOEISMeanders: dict[str, MetadataOEISidMeanders] = _makeDictionaryOEISMeanders()
+
 if __name__ == "__main__":
 	getOEISids()
+