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

mapFolding/dataBaskets.py

@@ -23,10 +23,12 @@ access patterns that enable efficient result persistence and retrieval.
 from mapFolding import (
 	Array1DElephino, Array1DLeavesTotal, Array3DLeavesTotal, DatatypeElephino, DatatypeFoldsTotal, DatatypeLeavesTotal,
 	getConnectionGraph, getLeavesTotal, makeDataContainer)
+from numpy.typing import NDArray
+from typing import TypeAlias
 import dataclasses
 import numpy
 
-@dataclasses.dataclass
+@dataclasses.dataclass(slots=True)
 class MapFoldingState:
 	"""Core computational state for map folding algorithms.
 
@@ -155,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)
 
@@ -270,75 +272,99 @@ class LeafSequenceState(MapFoldingState):
 			self.leafSequence = makeDataContainer(groupsOfFoldsKnown, self.__dataclass_fields__['leafSequence'].metadata['dtype'])
 			self.leafSequence[self.groupsOfFolds] = self.leaf1ndex
 
-
-@dataclasses.dataclass
+@dataclasses.dataclass(slots=True)
 class MatrixMeandersState:
-	"""State."""
+	"""Hold the state of a meanders transfer matrix algorithm computation."""
 
 	n: int
+	"""The index of the meanders problem being solved."""
 	oeisID: str
-	kOfMatrix: int
-	dictionaryCurveLocations: dict[int, int]
+	"""'A000682', semi-meanders, or 'A005316', meanders."""
+	boundary: int
+	"""The algorithm analyzes `n` boundaries starting at `boundary = n - 1`."""
+	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)."""
 
-	datatypeCurveLocations: type = numpy.uint64
-	datatypeDistinctCrossings: type = numpy.uint64
+	bitWidth: int = 0
+	"""At the start of an iteration enumerated by `boundary`, the number of bits of the largest value `arcCode`. The
+	`dataclass` computes a `property` from `bitWidth`."""
 
-	bitWidthCurveLocationsMaximum: int | None = None
-	bitWidthDistinctCrossingsMaximum: int | None = None
+	@property
+	def MAXIMUMarcCode(self) -> int:
+		"""Compute the maximum value of `arcCode` for the current iteration of the transfer matrix."""
+		return 1 << (2 * self.boundary + 4)
 
-	bitWidth: int = 0
-	indexStartAnalyzed: int = 0
+	@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."""
+
+	arrayArcCodes: NDArray[numpy.uint64] = dataclasses.field(default_factory=lambda: numpy.empty((0,), dtype=numpy.uint64))
+	arrayCrossings: 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."""
 
 	def __post_init__(self) -> None:
 		"""Post init."""
-		if self.bitWidthCurveLocationsMaximum is None:
-			_bitWidthOfFixedSizeInteger: int = numpy.dtype(self.datatypeCurveLocations).itemsize * 8 # bits
+		if self.bitWidthLimitArcCode is None:
+			_bitWidthOfFixedSizeInteger: int = numpy.dtype(self.datatypeArcCode).itemsize * 8 # bits
 
-			_offsetNecessary: int = 3 # For example, `groupZulu << 3`.
+			_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.bitWidthCurveLocationsMaximum = _bitWidthOfFixedSizeInteger - _offset
+			self.bitWidthLimitArcCode = _bitWidthOfFixedSizeInteger - _offset
 
 			del _bitWidthOfFixedSizeInteger, _offsetNecessary, _offsetSafety, _offset
 
-		if self.bitWidthDistinctCrossingsMaximum is None:
-			_bitWidthOfFixedSizeInteger: int = numpy.dtype(self.datatypeDistinctCrossings).itemsize * 8 # bits
+		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.bitWidthDistinctCrossingsMaximum = _bitWidthOfFixedSizeInteger - _offset
+			self.bitWidthLimitCrossings = _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))
-
-
+	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.arrayArcCodes, self.arrayCrossings, strict=True)}
+		self.arrayArcCodes = numpy.empty((0,), dtype=self.datatypeArcCode)
+		self.arrayCrossings = numpy.empty((0,), dtype=self.datatypeCrossings)
+
+	def makeArray(self) -> None:
+		"""Convert from Python `dict` (*dict*ionary) to NumPy `ndarray` (*Num*erical *Py*thon *n-d*imensional array)."""
+		self.arrayArcCodes = numpy.array(list(self.dictionaryMeanders.keys()), dtype=self.datatypeArcCode)
+		self.arrayCrossings = numpy.array(list(self.dictionaryMeanders.values()), dtype=self.datatypeCrossings)
+		self.bitWidth = int(self.arrayArcCodes.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.
@@ -419,7 +419,7 @@ def oeisIDfor_n(oeisID: str, n: int) -> int:
 			raise ArithmeticError(message)
 		foldsTotal: int = dictionaryOEISMapFolding[oeisID]['valuesKnown'][n]
 	else:
-		foldsTotal = countFolds(oeisID=oeisID, oeis_n=n)
+		foldsTotal = countFolds(mapShape=mapShape)
 
 	return foldsTotal
 
@@ -467,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.
 
@@ -504,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()