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

mapFolding/dataBaskets.py

@@ -21,10 +21,10 @@ integrity throughout the recursive analysis while providing the structured data
 access patterns that enable efficient result persistence and retrieval.
 """
 from mapFolding import (
-	Array1DElephino, Array1DLeavesTotal, Array3DLeavesTotal, DatatypeElephino, DatatypeFoldsTotal, DatatypeLeavesTotal,
-	getConnectionGraph, getLeavesTotal, makeDataContainer, ShapeArray, ShapeSlicer)
+	Array1DElephino, Array1DLeavesTotal, Array2DLeavesTotal, Array3DLeavesTotal, DatatypeElephino, DatatypeFoldsTotal,
+	DatatypeLeavesTotal, getConnectionGraph, getLeavesTotal, makeDataContainer)
 from numpy.typing import NDArray
-from typing import Final, TypeAlias
+from typing import TypeAlias
 import dataclasses
 import numpy
 
@@ -111,8 +111,6 @@ class MapFoldingState:
 	"""Array tracking the leaves above to the current leaf, `leaf1ndex`, during computation."""
 	leafBelow: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
 	"""Array tracking the leaves below to the current leaf, `leaf1ndex`, during computation."""
-	leafComparison: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
-	"""Array for finding symmetric folds."""
 
 	connectionGraph: Array3DLeavesTotal = dataclasses.field(init=False, metadata={'dtype': Array3DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
 	"""Unchanging array representing connections between all leaves."""
@@ -126,7 +124,7 @@ class MapFoldingState:
 
 		Returns
 		-------
-		totalFoldings : DatatypeFoldsTotal
+		foldsTotal : DatatypeFoldsTotal
 			The complete count of distinct folding patterns achievable with the current map configuration.
 
 		"""
@@ -154,6 +152,126 @@ class MapFoldingState:
 		if self.gapRangeStart is None: self.gapRangeStart = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['gapRangeStart'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
 		if self.leafAbove is None: self.leafAbove = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafAbove'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
 		if self.leafBelow is None: self.leafBelow = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafBelow'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
+
+@dataclasses.dataclass(slots=True)
+class SymmetricFoldsState:
+	"""Core computational state for symmetric map folding algorithms.
+
+	Attributes
+	----------
+	mapShape : tuple[DatatypeLeavesTotal, ...]
+		Dimensions of the map being analyzed for folding patterns.
+	groupsOfFolds : DatatypeFoldsTotal = DatatypeFoldsTotal(0)
+		Current count of distinct folding pattern groups: each group has `leavesTotal`-many foldings.
+	gap1ndex : DatatypeElephino = DatatypeElephino(0)
+		The current 1-indexed position of the 'gap' during computation: 1-indexed as opposed to 0-indexed.
+	gap1ndexCeiling : DatatypeElephino = DatatypeElephino(0)
+		The upper bound of `gap1ndex`.
+	indexDimension : DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+		The current 0-indexed position of the dimension during computation.
+	indexLeaf : DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+		The current 0-indexed position of a leaf in a loop during computation: not to be confused with `leaf1ndex`.
+	indexMiniGap : DatatypeElephino = DatatypeElephino(0)
+		The current 0-indexed position of a 'gap' in a loop during computation.
+	leaf1ndex : DatatypeLeavesTotal = DatatypeLeavesTotal(1)
+		The current 1-indexed position of the leaf during computation: 1-indexed as opposed to 0-indexed.
+	leafConnectee : DatatypeLeavesTotal = DatatypeLeavesTotal(0)
+		Target leaf for connection operations.
+	dimensionsUnconstrained : DatatypeLeavesTotal = None
+		Count of dimensions not subject to folding constraints.
+	countDimensionsGapped : Array1DLeavesTotal = None
+		Array tracking computed number of dimensions with gaps.
+	gapRangeStart : Array1DElephino = None
+		Array tracking computed starting positions of gap ranges.
+	gapsWhere : Array1DLeavesTotal = None
+		Array indicating locations of gaps in the folding pattern.
+	leafAbove : Array1DLeavesTotal = None
+		Array tracking the leaves above to the current leaf, `leaf1ndex`, during computation.
+	leafBelow : Array1DLeavesTotal = None
+		Array tracking the leaves below to the current leaf, `leaf1ndex`, during computation.
+	leafComparison : Array1DLeavesTotal = None
+		Array for finding symmetric folds.
+	connectionGraph : Array3DLeavesTotal
+		Unchanging array representing connections between all leaves.
+	dimensionsTotal : DatatypeLeavesTotal
+		Unchanging total number of dimensions in the map.
+	leavesTotal : DatatypeLeavesTotal
+		Unchanging total number of leaves in the map.
+
+	"""
+
+	mapShape: tuple[DatatypeLeavesTotal, ...] = dataclasses.field(init=True, metadata={'elementConstructor': 'DatatypeLeavesTotal'})
+	"""Dimensions of the map being analyzed for folding patterns."""
+
+	groupsOfFolds: DatatypeFoldsTotal = dataclasses.field(default=DatatypeFoldsTotal(0), metadata={'theCountingIdentifier': True})
+	"""Current count of symmetric folds."""
+
+	gap1ndex: DatatypeElephino = DatatypeElephino(0)  # noqa: RUF009
+	"""The current 1-indexed position of the 'gap' during computation: 1-indexed as opposed to 0-indexed."""
+	gap1ndexCeiling: DatatypeElephino = DatatypeElephino(0)  # noqa: RUF009
+	"""The upper bound of `gap1ndex`."""
+	indexDimension: DatatypeLeavesTotal = DatatypeLeavesTotal(0)  # noqa: RUF009
+	"""The current 0-indexed position of the dimension during computation."""
+	indexLeaf: DatatypeLeavesTotal = DatatypeLeavesTotal(0)  # noqa: RUF009
+	"""The current 0-indexed position of a leaf in a loop during computation: not to be confused with `leaf1ndex`."""
+	indexMiniGap: DatatypeElephino = DatatypeElephino(0)  # noqa: RUF009
+	"""The current 0-indexed position of a 'gap' in a loop during computation."""
+	leaf1ndex: DatatypeLeavesTotal = DatatypeLeavesTotal(1)  # noqa: RUF009
+	"""The current 1-indexed position of the leaf during computation: 1-indexed as opposed to 0-indexed."""
+	leafConnectee: DatatypeLeavesTotal = DatatypeLeavesTotal(0)  # noqa: RUF009
+	"""Target leaf for connection operations."""
+
+	dimensionsUnconstrained: DatatypeLeavesTotal = dataclasses.field(default=None, init=True) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Count of dimensions not subject to folding constraints."""
+
+	countDimensionsGapped: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Array tracking computed number of dimensions with gaps."""
+	gapRangeStart: Array1DElephino = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DElephino.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Array tracking computed starting positions of gap ranges."""
+	gapsWhere: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Array indicating locations of gaps in the folding pattern."""
+	leafAbove: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Array tracking the leaves above to the current leaf, `leaf1ndex`, during computation."""
+	leafBelow: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Array tracking the leaves below to the current leaf, `leaf1ndex`, during computation."""
+	leafComparison: Array1DLeavesTotal = dataclasses.field(default=None, init=True, metadata={'dtype': Array1DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportAssignmentType, reportAttributeAccessIssue, reportUnknownMemberType]
+	"""Array for finding symmetric folds."""
+
+	arrayGroupOfFolds: Array2DLeavesTotal = dataclasses.field(init=False, metadata={'dtype': Array2DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
+	connectionGraph: Array3DLeavesTotal = dataclasses.field(init=False, metadata={'dtype': Array3DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
+	"""Unchanging array representing connections between all leaves."""
+	dimensionsTotal: DatatypeLeavesTotal = dataclasses.field(init=False)
+	"""Unchanging total number of dimensions in the map."""
+	indicesArrayGroupOfFolds: Array2DLeavesTotal = dataclasses.field(init=False, metadata={'dtype': Array2DLeavesTotal.__args__[1].__args__[0]}) # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
+	leavesTotal: DatatypeLeavesTotal = dataclasses.field(init=False)
+	"""Unchanging total number of leaves in the map."""
+
+	def __post_init__(self) -> None:
+		"""Ensure all fields have a value.
+
+		Notes
+		-----
+		Arrays that are not explicitly provided (None) are automatically allocated with appropriate sizes based on the map
+		dimensions. `dimensionsTotal`, `leavesTotal`, and `connectionGraph` cannot be set: they are calculated.
+
+		"""
+		self.dimensionsTotal = DatatypeLeavesTotal(len(self.mapShape))
+		self.leavesTotal = DatatypeLeavesTotal(getLeavesTotal(self.mapShape))
+
+		leavesTotalAsInt = int(self.leavesTotal)
+
+		self.connectionGraph = getConnectionGraph(self.mapShape, leavesTotalAsInt, self.__dataclass_fields__['connectionGraph'].metadata['dtype'])
+
+		self.indicesArrayGroupOfFolds = (numpy.arange(leavesTotalAsInt + 1)[:, None] + numpy.arange(leavesTotalAsInt)[None, :]) % (leavesTotalAsInt + 1)
+		self.indicesArrayGroupOfFolds[..., leavesTotalAsInt // 2:None] = self.indicesArrayGroupOfFolds[..., leavesTotalAsInt - 1: leavesTotalAsInt - leavesTotalAsInt // 2 - 1: -1]
+		self.arrayGroupOfFolds = numpy.zeros_like(self.indicesArrayGroupOfFolds)
+
+		if self.dimensionsUnconstrained is None: self.dimensionsUnconstrained = DatatypeLeavesTotal(int(self.dimensionsTotal)) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
+		if self.gapsWhere is None: self.gapsWhere = makeDataContainer(leavesTotalAsInt * leavesTotalAsInt + 1, self.__dataclass_fields__['gapsWhere'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
+		if self.countDimensionsGapped is None: self.countDimensionsGapped = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['countDimensionsGapped'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
+		if self.gapRangeStart is None: self.gapRangeStart = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['gapRangeStart'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
+		if self.leafAbove is None: self.leafAbove = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafAbove'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
+		if self.leafBelow is None: self.leafBelow = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafBelow'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
 		if self.leafComparison is None: self.leafComparison = makeDataContainer(leavesTotalAsInt + 1, self.__dataclass_fields__['leafComparison'].metadata['dtype']) # pyright: ignore[reportUnnecessaryComparison]  # noqa: E701
 
 @dataclasses.dataclass
@@ -280,21 +398,21 @@ class MatrixMeandersState:
 	"""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."""
+	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)."""
 
 	bitWidth: int = 0
-	"""At the start of an iteration enumerated by `kOfMatrix`, the number of bits of the largest value `arcCode`. The
+	"""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`."""
 
 	@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)
+		return 1 << (2 * self.boundary + 4)
 
 	@property
 	def locatorBits(self) -> int:
@@ -317,7 +435,8 @@ class MatrixMeandersState:
 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))
+	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
@@ -330,20 +449,6 @@ class MatrixMeandersNumPyState(MatrixMeandersState):
 	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:
@@ -371,16 +476,13 @@ class MatrixMeandersNumPyState(MatrixMeandersState):
 
 	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)
+		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)."""
-		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.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/filesystemToolkit.py

@@ -56,12 +56,10 @@ def getFilenameFoldsTotal(mapShape: tuple[int, ...]) -> str:
 	return 'p' + 'x'.join(str(dimension) for dimension in sorted(mapShape)) + '.foldsTotal'
 
 def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal: PathLike[str] | PurePath | None = None) -> Path:
-	"""Get a standardized path and filename for the computed `foldsTotal` value.
+	"""Get a standardized filename and create a configurable path to store the computed `foldsTotal` value.
 
-	(AI generated docstring)
-
-	This function resolves paths for storing computation results, handling different input types including directories,
-	absolute paths, or relative paths. It ensures that all parent directories exist in the resulting path.
+	To help reduce duplicate code and to increase predictability, this function creates a standardized filename, has a default but
+	configurable path, and creates the path.
 
 	Parameters
 	----------
@@ -78,10 +76,9 @@ def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal
 	Notes
 	-----
 	The function creates any necessary directories in the path if they don't exist.
-
 	"""
 	if pathLikeWriteFoldsTotal is None:
-		pathFilenameFoldsTotal = getPathRootJobDEFAULT() / getFilenameFoldsTotal(mapShape)
+		pathFilenameFoldsTotal: Path = getPathRootJobDEFAULT() / getFilenameFoldsTotal(mapShape)
 	else:
 		pathLikeSherpa = Path(pathLikeWriteFoldsTotal)
 		if pathLikeSherpa.is_dir():
@@ -237,28 +234,3 @@ def saveFoldsTotalFAILearly(pathFilename: PathLike[str] | PurePath) -> None:
 	if foldsTotalRead != foldsTotal:
 		message = f"I wrote a test file to `{pathFilename = }` with contents of `{str(foldsTotal) = }`, but I read `{foldsTotalRead = }` from the file. Python says the values are not equal. Fix that now, so your computation doesn't get corrupted later. And be pro-social."
 		raise FileNotFoundError(message)
-
-def writeStringToHere(this: str, pathFilename: PathLike[str] | PurePath) -> None:
-	"""Write a string to a file, creating parent directories if needed.
-
-	(AI generated docstring)
-
-	This utility function provides a consistent interface for writing string content to files across the package. It
-	handles path creation and ensures proper string conversion.
-
-	Parameters
-	----------
-	this : str
-		The string content to write to the file.
-	pathFilename : PathLike[str] | PurePath
-		The target file path where the string should be written.
-
-	Notes
-	-----
-	This function creates all parent directories in the path if they don't exist, making it safe to use with newly
-	created directory structures.
-
-	"""
-	pathFilename = Path(pathFilename)
-	pathFilename.parent.mkdir(parents=True, exist_ok=True)
-	pathFilename.write_text(str(this))

mapFolding/oeis.py

@@ -306,12 +306,6 @@ def makeDictionaryFoldsTotalKnown() -> dict[tuple[int, ...], int]:
 def getFoldsTotalKnown(mapShape: tuple[int, ...]) -> int:
 	"""Retrieve the known total number of distinct folding patterns for a given map shape.
 
-	(AI generated docstring)
-
-	This function provides rapid access to precalculated folding totals from OEIS sequences without
-	requiring computation. It serves as a validation reference for algorithm results and enables
-	quick lookup of known values across all implemented sequences.
-
 	Parameters
 	----------
 	mapShape : tuple[int, ...]
@@ -320,17 +314,16 @@ def getFoldsTotalKnown(mapShape: tuple[int, ...]) -> int:
 	Returns
 	-------
 	foldingsTotal : int
-		The known total number of distinct folding patterns for the given map shape,
-		or -1 if the map shape does not match any known values in the OEIS sequences.
+		The known total number of distinct folding patterns for the given map shape, or 0 if the map shape does not match any
+		known values in the OEIS sequences.
 
 	Notes
 	-----
-	The function uses a cached dictionary for efficient retrieval without repeatedly processing
-	OEIS data. Map shapes are matched exactly as provided without internal sorting or normalization.
+	Map shapes are matched exactly as provided without internal sorting or normalization.
 
 	"""
-	lookupFoldsTotal = makeDictionaryFoldsTotalKnown()
-	return lookupFoldsTotal.get(tuple(mapShape), -1)
+	lookupFoldsTotal: dict[tuple[int, ...], int] = makeDictionaryFoldsTotalKnown()
+	return lookupFoldsTotal.get(tuple(mapShape), 0)
 
 def _formatHelpText() -> str:
 	"""Format comprehensive help text for both command-line and interactive use.