mapFolding 0.15.4__py3-none-any.whl → 0.16.1__py3-none-any.whl

mapFolding/dataBaskets.py

@@ -22,10 +22,13 @@ access patterns that enable efficient result persistence and retrieval.
 """
 from mapFolding import (
 	Array1DElephino, Array1DLeavesTotal, Array3DLeavesTotal, DatatypeElephino, DatatypeFoldsTotal, DatatypeLeavesTotal,
-	getConnectionGraph, getLeavesTotal, makeDataContainer)
+	getConnectionGraph, getLeavesTotal, makeDataContainer, ShapeArray, ShapeSlicer)
+from numpy.typing import NDArray
+from typing import Final, TypeAlias
 import dataclasses
+import numpy
 
-@dataclasses.dataclass
+@dataclasses.dataclass(slots=True)
 class MapFoldingState:
 	"""Core computational state for map folding algorithms.
 
@@ -154,8 +157,8 @@ class MapFoldingState:
 		if self.leafComparison is None: self.leafComparison = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafComparison'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
 
 @dataclasses.dataclass
-class ParallelMapFoldingState(MapFoldingState):
-	"""Experimental computational state for task division operations.
+class ParallelMapFoldingState(MapFoldingState): # This identifier because of `dataclassIdentifierParallel: identifierDotAttribute = 'Parallel' + dataclassIdentifier`.
+	"""Computational state for task division operations.
 
 	(AI generated docstring)
 
@@ -268,3 +271,116 @@ 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(slots=True)
+class MatrixMeandersState:
+	"""Hold the state of a meanders transfer matrix algorithm computation."""
+
+	n: int
+	"""The index of the meanders problem being solved."""
+	oeisID: str
+	"""'A000682', semi-meanders, or 'A005316', meanders."""
+	kOfMatrix: int
+	"""The number of iterations remaining in the transfer matrix algorithm."""
+	dictionaryMeanders: dict[int, int]
+	"""A Python `dict` (*dict*ionary) of `arcCode` to `crossings`. The values are stored as Python `int`
+	(*int*eger), which may be arbitrarily large. Because of that property, `int` may also be called a 'bignum' (big *num*ber) or
+	'bigint' (big *int*eger)."""
+
+	bitWidth: int = 0
+	"""At the start of an iteration enumerated by `kOfMatrix`, the number of bits of the largest value `arcCode`. The
+	`dataclass` computes a `property` from `bitWidth`."""
+
+	@property
+	def MAXIMUMarcCode(self) -> int:
+		"""Compute the maximum value of `arcCode` for the current iteration of the transfer matrix."""
+		return 1 << (2 * self.kOfMatrix + 4)
+
+	@property
+	def locatorBits(self) -> int:
+		"""Compute an odd-parity bit-mask with `bitWidth` bits.
+
+		Notes
+		-----
+		In binary, `locatorBitsAlpha` 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, `locatorBitsAlpha` has 1s in the columns with odd index numbers. Mathematicians and programmers,
+		therefore, tend to call `locatorBitsAlpha` 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))
+
+@dataclasses.dataclass(slots=True)
+class MatrixMeandersNumPyState(MatrixMeandersState):
+	"""Hold the state of a meanders transfer matrix algorithm computation."""
+
+	arrayMeanders: NDArray[numpy.uint64] = dataclasses.field(default_factory=lambda: numpy.empty((0,), dtype=numpy.uint64))
+
+	bitWidthLimitArcCode: int | None = None
+	bitWidthLimitCrossings: int | None = None
+
+	datatypeArcCode: TypeAlias = numpy.uint64  # noqa: UP040
+	"""The fixed-size integer type used to store `arcCode`."""
+	datatypeCrossings: TypeAlias = numpy.uint64  # noqa: UP040
+	"""The fixed-size integer type used to store `crossings`."""
+
+	indexTarget: int = 0
+	"""What is being indexed depends on the algorithm flavor."""
+
+# TODO Integrate this better into the dataclasses paradigm.
+	indicesMeanders: Final[int] = 2
+	indexArcCode, indexCrossings = range(indicesMeanders)
+
+	@property
+	def slicerArcCode(self) -> ShapeSlicer:
+		"""Get a `ShapeSlicer` to extract the `arcCode` column from `arrayMeanders`."""
+		return ShapeSlicer(length=..., indices=self.indexArcCode)
+
+	@property
+	def slicerCrossings(self) -> ShapeSlicer:
+		"""Get a `ShapeSlicer` to extract the `crossings` column from `arrayMeanders`."""
+		return ShapeSlicer(length=..., indices=self.indexCrossings)
+
+	def __post_init__(self) -> None:
+		"""Post init."""
+		if self.bitWidthLimitArcCode is None:
+			_bitWidthOfFixedSizeInteger: int = numpy.dtype(self.datatypeArcCode).itemsize * 8 # bits
+
+			_offsetNecessary: int = 3 # For example, `bitsZulu << 3`.
+			_offsetSafety: int = 1 # I don't have mathematical proof of how many extra bits I need.
+			_offset: int = _offsetNecessary + _offsetSafety
+
+			self.bitWidthLimitArcCode = _bitWidthOfFixedSizeInteger - _offset
+
+			del _bitWidthOfFixedSizeInteger, _offsetNecessary, _offsetSafety, _offset
+
+		if self.bitWidthLimitCrossings is None:
+			_bitWidthOfFixedSizeInteger: int = numpy.dtype(self.datatypeCrossings).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.bitWidthLimitCrossings = _bitWidthOfFixedSizeInteger - _offset
+
+			del _bitWidthOfFixedSizeInteger, _offsetNecessary, _offsetEstimation, _offsetSafety, _offset
+
+	def makeDictionary(self) -> None:
+		"""Convert from NumPy `ndarray` (*Num*erical *Py*thon *n-d*imensional array) to Python `dict` (*dict*ionary)."""
+		self.dictionaryMeanders = {int(key): int(value) for key, value in zip(
+			self.arrayMeanders[self.slicerArcCode], self.arrayMeanders[self.slicerCrossings]
+			, strict=True)}
+		self.arrayMeanders = numpy.empty((0,), dtype=self.datatypeArcCode)
+
+	def makeArray(self) -> None:
+		"""Convert from Python `dict` (*dict*ionary) to NumPy `ndarray` (*Num*erical *Py*thon *n-d*imensional array)."""
+		shape = ShapeArray(length=len(self.dictionaryMeanders), indices=self.indicesMeanders)
+		self.arrayMeanders = numpy.zeros(shape, dtype=self.datatypeArcCode)
+		self.arrayMeanders[self.slicerArcCode] = list(self.dictionaryMeanders.keys())
+		self.arrayMeanders[self.slicerCrossings] = list(self.dictionaryMeanders.values())
+		self.bitWidth = int(self.arrayMeanders[self.slicerArcCode].max()).bit_length()
+		self.dictionaryMeanders = {}

mapFolding/oeis.py

@@ -27,7 +27,7 @@ completes the journey from configuration foundation to mathematical discovery.
 from datetime import datetime, timedelta, UTC
 from hunterMakesPy import writeStringToHere
 from itertools import chain
-from mapFolding import countFolds, MetadataOEISidMapFolding, MetadataOEISidMeanders, packageSettings
+from mapFolding import countFolds, MetadataOEISid, MetadataOEISidMapFolding, packageSettings
 from mapFolding._theSSOT import pathCache
 from pathlib import Path
 from typing import Final
@@ -248,7 +248,7 @@ def getOEISidInformation(oeisID: str) -> tuple[str, int]:
 	description: str = ' '.join(listDescriptionDeconstructed)
 	return description, offset
 
-def _makeDictionaryOEIS() -> dict[str, MetadataOEISidMapFolding]:
+def _makeDictionaryOEISMapFolding() -> dict[str, MetadataOEISidMapFolding]:
 	"""Construct the comprehensive settings dictionary for all implemented OEIS sequences.
 
 	(AI generated docstring)
@@ -287,8 +287,8 @@ def _makeDictionaryOEIS() -> dict[str, MetadataOEISidMapFolding]:
 		)
 	return dictionaryOEIS
 
-dictionaryOEISMapFolding: dict[str, MetadataOEISidMapFolding] = _makeDictionaryOEIS()
-"""Metadata for each OEIS sequence ID."""
+dictionaryOEISMapFolding: dict[str, MetadataOEISidMapFolding] = _makeDictionaryOEISMapFolding()
+"""Metadata for each MapFolding OEIS ID."""
 
 def makeDictionaryFoldsTotalKnown() -> dict[tuple[int, ...], int]:
 	"""Make a `mapShape` to known `foldsTotal` dictionary.
@@ -418,9 +418,10 @@ def oeisIDfor_n(oeisID: str, n: int) -> int:
 			message = f"OEIS sequence {oeisID} is not defined at {n = }."
 			raise ArithmeticError(message)
 		foldsTotal: int = dictionaryOEISMapFolding[oeisID]['valuesKnown'][n]
-		return foldsTotal
+	else:
+		foldsTotal = countFolds(mapShape=mapShape)
 
-	return countFolds(mapShape, oeisID=oeisID)
+	return foldsTotal
 
 def OEIS_for_n() -> None:
 	"""Command-line interface for calculating OEIS sequence values.
@@ -466,27 +467,6 @@ def OEIS_for_n() -> None:
 	timeElapsed: float = time.perf_counter() - timeStart
 	print(f"Time elapsed: {timeElapsed:.3f} seconds")  # noqa: T201
 
-def clearOEIScache() -> None:
-	"""Delete all cached OEIS sequence files from the local cache directory.
-
-	(AI generated docstring)
-
-	This function removes all cached OEIS data files, including both sequence value files (b-files)
-	and metadata files, forcing fresh retrieval from the OEIS website on the next access. This is
-	useful for clearing stale cache data or troubleshooting network-related issues.
-
-	The function safely handles missing files and provides user feedback about the cache clearing
-	operation. If the cache directory does not exist, an informative message is displayed.
-
-	"""
-	if not pathCache.exists():
-		print(f"Cache directory, {pathCache}, not found - nothing to clear.")  # noqa: T201
-		return
-	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
-
 def getOEISids() -> None:
 	"""Display comprehensive information about all implemented OEIS sequences.
 
@@ -503,21 +483,21 @@ def getOEISids() -> None:
 	"""
 	print(_formatHelpText())  # noqa: T201
 
-def _makeDictionaryOEISMeanders() -> dict[str, MetadataOEISidMeanders]:
-	dictionary: dict[str, MetadataOEISidMeanders] = {}
-	for oeisID in packageSettings.OEISidMeandersManuallySet:
+def _makeDictionaryOEIS() -> dict[str, MetadataOEISid]:
+	dictionary: dict[str, MetadataOEISid] = {}
+	for oeisID in packageSettings.OEISidManuallySet:
 		valuesKnownSherpa: dict[int, int] = getOEISidValues(oeisID)
 		descriptionSherpa, offsetSherpa = getOEISidInformation(oeisID)
-		dictionary[oeisID] = MetadataOEISidMeanders(
+		dictionary[oeisID] = MetadataOEISid(
 			description=descriptionSherpa,
 			offset=offsetSherpa,
 			valuesKnown=valuesKnownSherpa,
-			valuesTestValidation=packageSettings.OEISidMeandersManuallySet[oeisID]['valuesTestValidation'],
+			valuesTestValidation=[*(packageSettings.OEISidManuallySet[oeisID]['valuesTestValidation']), offsetSherpa],
 			valueUnknown=max(valuesKnownSherpa.keys(), default=0) + 1,
 		)
 	return dictionary
 
-dictionaryOEISMeanders: dict[str, MetadataOEISidMeanders] = _makeDictionaryOEISMeanders()
+dictionaryOEIS: dict[str, MetadataOEISid] = _makeDictionaryOEIS()
 
 if __name__ == "__main__":
 	getOEISids()