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

mapFolding/algorithms/matrixMeandersBeDry.py

@@ -0,0 +1,182 @@
+"""Be DRY."""
+from functools import cache
+from hunterMakesPy import raiseIfNone
+from mapFolding.dataBaskets import MatrixMeandersNumPyState
+from mapFolding.reference.A000682facts import A000682_n_boundary_buckets
+from mapFolding.reference.A005316facts import A005316_n_boundary_buckets
+import numpy
+import pandas
+
+"""Goals:
+- Extreme abstraction.
+- Find operations with latent intermediate arrays and make the intermediate array explicit.
+- Reduce or eliminate intermediate arrays and selector arrays.
+- Write formulas in prefix notation.
+- For each formula, find an equivalent prefix notation formula that never uses the same variable as input more than once: that
+	would allow the evaluation of the expression with only a single stack, which saves memory.
+- Standardize code as much as possible to create duplicate code.
+- Convert duplicate code to procedures.
+"""
+
+def areIntegersWide(state: MatrixMeandersNumPyState, *, dataframe: pandas.DataFrame | None = None, fixedSizeMAXIMUMarcCode: bool = False) -> bool:
+	"""Check if the largest values are wider than the maximum limits.
+
+	Parameters
+	----------
+	state : MatrixMeandersState
+		The current state of the computation, including `dictionaryMeanders`.
+	dataframe : pandas.DataFrame | None = None
+		Optional DataFrame containing 'analyzed' and 'crossings' columns. If provided, use this instead of `state.dictionaryMeanders`.
+	fixedSizeMAXIMUMarcCode : bool = False
+		Set this to `True` if you cast `state.MAXIMUMarcCode` to the same fixed size integer type as `state.datatypeArcCode`.
+
+	Returns
+	-------
+	wider : bool
+		True if at least one integer is too wide.
+
+	Notes
+	-----
+	Casting `state.MAXIMUMarcCode` to a fixed-size 64-bit unsigned integer might cause the flow to be a little more
+	complicated because `MAXIMUMarcCode` is usually 1-bit larger than the `max(arcCode)` value.
+
+	If you start the algorithm with very large `arcCode` in your `dictionaryMeanders` (*i.e.,* A000682), then the
+	flow will go to a function that does not use fixed size integers. When the integers are below the limits (*e.g.,*
+	`bitWidthArcCodeMaximum`), the flow will go to a function with fixed size integers. In that case, casting
+	`MAXIMUMarcCode` to a fixed size merely delays the transition from one function to the other by one iteration.
+
+	If you start with small values in `dictionaryMeanders`, however, then the flow goes to the function with fixed size
+	integers and usually stays there until `crossings` is huge, which is near the end of the computation. If you cast
+	`MAXIMUMarcCode` into a 64-bit unsigned integer, however, then around `state.boundary == 28`, the bit width of
+	`MAXIMUMarcCode` might exceed the limit. That will cause the flow to go to the function that does not have fixed size
+	integers for a few iterations before returning to the function with fixed size integers.
+	"""
+	if dataframe is not None:
+		arcCodeWidest = int(dataframe['analyzed'].max()).bit_length()
+		crossingsWidest = int(dataframe['crossings'].max()).bit_length()
+	elif not state.dictionaryMeanders:
+		arcCodeWidest = int(state.arrayArcCodes.max()).bit_length()
+		crossingsWidest = int(state.arrayCrossings.max()).bit_length()
+	else:
+		arcCodeWidest: int = max(state.dictionaryMeanders.keys()).bit_length()
+		crossingsWidest: int = max(state.dictionaryMeanders.values()).bit_length()
+
+	MAXIMUMarcCode: int = 0
+	if fixedSizeMAXIMUMarcCode:
+		MAXIMUMarcCode = state.MAXIMUMarcCode
+
+	return (arcCodeWidest > raiseIfNone(state.bitWidthLimitArcCode)
+		or crossingsWidest > raiseIfNone(state.bitWidthLimitCrossings)
+		or MAXIMUMarcCode > raiseIfNone(state.bitWidthLimitArcCode)
+		)
+
+@cache
+def _flipTheExtra_0b1(intWithExtra_0b1: numpy.uint64) -> numpy.uint64:
+	return numpy.uint64(intWithExtra_0b1 ^ walkDyckPath(int(intWithExtra_0b1)))
+
+flipTheExtra_0b1AsUfunc = numpy.frompyfunc(_flipTheExtra_0b1, 1, 1)
+"""Flip a bit based on Dyck path: element-wise ufunc (*u*niversal *func*tion) for a NumPy `ndarray` (*Num*erical *Py*thon *n-d*imensional array).
+
+Warning
+-------
+The function will loop infinitely if an element does not have a bit that needs flipping.
+
+Parameters
+----------
+arrayTarget : numpy.ndarray[tuple[int], numpy.dtype[numpy.unsignedinteger[Any]]]
+	An array with one axis of unsigned integers and unbalanced closures.
+
+Returns
+-------
+arrayFlipped : numpy.ndarray[tuple[int], numpy.dtype[numpy.unsignedinteger[Any]]]
+	An array with the same shape as `arrayTarget` but with one bit flipped in each element.
+"""
+
+def getBucketsTotal(state: MatrixMeandersNumPyState, safetyMultiplicand: float = 1.2) -> int:  # noqa: ARG001
+	"""Under renovation: Estimate the total number of non-unique arcCode that will be computed from the existing arcCode.
+
+	Warning
+	-------
+	Because `matrixMeandersPandas` does not store anything in `state.arrayArcCodes`, if `matrixMeandersPandas` requests
+	bucketsTotal for a value not in the dictionary, the returned value will be 0. But `matrixMeandersPandas` should have a safety
+	check that will allocate more space.
+
+	Notes
+	-----
+	TODO remake this function from scratch.
+
+	Factors:
+		- The starting quantity of `arcCode`.
+		- The value(s) of the starting `arcCode`.
+		- n
+		- boundary
+		- Whether this bucketsTotal is increasing, as compared to all of the prior bucketsTotal.
+		- If increasing, is it exponential or logarithmic?
+		- The maximum value.
+		- If decreasing, I don't really know the factors.
+		- If I know the actual value or if I must estimate it.
+
+	Figure out an intelligent flow for so many factors.
+	"""
+	theDictionary: dict[str, dict[int, dict[int, int]]] = {'A005316': A005316_n_boundary_buckets, 'A000682': A000682_n_boundary_buckets}
+	bucketsTotal: int = theDictionary.get(state.oeisID, {}).get(state.n, {}).get(state.boundary, 0)
+	if bucketsTotal <= 0:
+		bucketsTotal = int(3.55 * len(state.arrayArcCodes))
+
+	return bucketsTotal
+
+def getSignaturesTotal(state: MatrixMeandersNumPyState) -> int:
+	"""Get the total number of signatures for the current `n` and `boundary`.
+
+	Parameters
+	----------
+	state : MatrixMeandersState
+		The current state of the computation.
+
+	Returns
+	-------
+	signaturesTotal : int
+		The total number of signatures for the current `n` and `boundary`.
+
+	"""
+	from mapFolding.reference.matrixMeandersAnalysis.signatures import signatures  # noqa: PLC0415
+	return signatures[state.oeisID].get(state.n, {}).get(state.boundary, int(3.55 * len(state.arrayArcCodes)))
+
+@cache
+def walkDyckPath(intWithExtra_0b1: int) -> int:
+	"""Find the bit position for flipping paired curve endpoints in meander transfer matrices.
+
+	Parameters
+	----------
+	intWithExtra_0b1 : int
+		Binary representation of curve locations with an extra bit encoding parity information.
+
+	Returns
+	-------
+	flipExtra_0b1_Here : int
+		Bit mask indicating the position where the balance condition fails, formatted as 2^(2k).
+
+	3L33T H@X0R
+	------------
+	Binary search for first negative balance in shifted bit pairs. Returns 2^(2k) mask for
+	bit position k where cumulative balance counter transitions from non-negative to negative.
+
+	Mathematics
+	-----------
+	Implements the Dyck path balance verification algorithm from Jensen's transfer matrix
+	enumeration. Computes the position where ∑(i=0 to k) (-1)^b_i < 0 for the first time,
+	where b_i are the bits of the input at positions 2i.
+
+	"""
+	findTheExtra_0b1: int = 0
+	flipExtra_0b1_Here: int = 1
+	while True:
+		flipExtra_0b1_Here <<= 2
+		if intWithExtra_0b1 & flipExtra_0b1_Here == 0:
+			findTheExtra_0b1 += 1
+		else:
+			findTheExtra_0b1 -= 1
+		if findTheExtra_0b1 < 0:
+			break
+	return flipExtra_0b1_Here
+

mapFolding/algorithms/matrixMeandersNumPy.py

@@ -0,0 +1,333 @@
+from gc import collect as goByeBye
+from mapFolding import ShapeArray, ShapeSlicer
+from mapFolding.algorithms.matrixMeandersBeDry import areIntegersWide, flipTheExtra_0b1AsUfunc, getBucketsTotal
+from mapFolding.dataBaskets import MatrixMeandersNumPyState
+from mapFolding.syntheticModules.meanders.bigInt import countBigInt
+from numpy import (
+	bitwise_and, bitwise_left_shift, bitwise_or, bitwise_right_shift, bitwise_xor, greater, less_equal, multiply, subtract)
+from numpy.typing import NDArray
+from typing import Any, TYPE_CHECKING
+import numpy
+
+if TYPE_CHECKING:
+	from numpy.lib._arraysetops_impl import UniqueInverseResult
+
+"""More ideas for memory efficiency:
+- In `recordAnalysis`, use `numpy.unique_inverse` on the newly added `arcCode`.
+- In `recordAnalysis`, use `numpy.unique_inverse` on `arrayAnalyzed` after adding new `arcCode`.
+- By deduplicating more often, I can decrease the allocated size of `arrayAnalyzed`. However, that may reduce the usefulness of `makeStorage`.
+- I suspect that `makeStorage(numpy.flatnonzero(prepArea)...` contains a latent array.
+- In every case (or almost every case) I use a selector, I _feel_ like there is more memory efficient way I don't know about.
+- It's not clear to me whether or not I am instructing numpy to release _all_ memory I no longer need.
+- Hypothetically, `arcCode` might be compressible, but IDK no nothing.
+- `numpy.unique_inverse` uses a ton of memory, but I've failed to find a better way. BUT I might be able to improve
+	`aggregateAnalyzed` now that `arrayArcCodes` is a single axis.
+- For analyzeBitsAlpha and analyzeBitsZulu, find an equivalent formula that does not require a secondary stack.
+- analyzeAligned requires a ton of memory. By analyzing it before the other three analyses (therefore `arrayAnalyzed` is empty)
+	and using `makeStorage`, I've offset much of the usage, but I don't have confidence it's a good flow.
+
+To mitigate memory problems:
+- Put `arrayAnalyzed` in a `numpy.memmap`.
+"""
+
+indicesPrepArea: int = 1
+indexAnalysis = 0
+slicerAnalysis: ShapeSlicer = ShapeSlicer(length=..., indices=indexAnalysis)
+
+indicesAnalyzed: int = 2
+indexArcCode, indexCrossings = range(indicesAnalyzed)
+slicerArcCode: ShapeSlicer = ShapeSlicer(length=..., indices=indexArcCode)
+slicerCrossings: ShapeSlicer = ShapeSlicer(length=..., indices=indexCrossings)
+
+def countNumPy(state: MatrixMeandersNumPyState) -> MatrixMeandersNumPyState:
+	"""Count crossings with transfer matrix algorithm implemented in NumPy (*Num*erical *Py*thon).
+
+	Parameters
+	----------
+	state : MatrixMeandersState
+		The algorithm state.
+
+	Returns
+	-------
+	state : MatrixMeandersState
+		Updated state including `boundary` and `arrayMeanders`.
+	"""
+	while state.boundary > 0 and not areIntegersWide(state):
+		def aggregateAnalyzed(arrayAnalyzed: NDArray[numpy.uint64], state: MatrixMeandersNumPyState) -> MatrixMeandersNumPyState:
+			"""Create new `arrayMeanders` by deduplicating `arcCode` and summing `crossings`."""
+			unique: UniqueInverseResult[numpy.uint64] = numpy.unique_inverse(arrayAnalyzed[slicerArcCode])
+
+			state.arrayArcCodes = unique.values
+			state.arrayCrossings = numpy.zeros_like(state.arrayArcCodes, dtype=state.datatypeCrossings)
+			numpy.add.at(state.arrayCrossings, unique.inverse_indices, arrayAnalyzed[slicerCrossings])
+			del unique
+
+			return state
+
+		def makeStorage[个: numpy.integer[Any]](dataTarget: NDArray[个], state: MatrixMeandersNumPyState, storageTarget: NDArray[numpy.uint64], indexAssignment: int = indexArcCode) -> NDArray[个]:
+			"""Store `dataTarget` in `storageTarget` on `indexAssignment` if there is enough space, otherwise allocate a new array."""
+			lengthStorageTarget: int = len(storageTarget)
+			storageAvailable: int = lengthStorageTarget - state.indexTarget
+			lengthDataTarget: int = len(dataTarget)
+
+			if storageAvailable >= lengthDataTarget:
+				indexStart: int = lengthStorageTarget - lengthDataTarget
+				sliceStorage: slice = slice(indexStart, lengthStorageTarget)
+				del indexStart
+				slicerStorageAtIndex: ShapeSlicer = ShapeSlicer(length=sliceStorage, indices=indexAssignment)
+				del sliceStorage
+				storageTarget[slicerStorageAtIndex] = dataTarget.copy()
+				arrayStorage = storageTarget[slicerStorageAtIndex].view() # pyright: ignore[reportAssignmentType]
+				del slicerStorageAtIndex
+			else:
+				arrayStorage: NDArray[个] = dataTarget.copy()
+
+			del storageAvailable, lengthDataTarget, lengthStorageTarget
+
+			return arrayStorage
+
+		def recordAnalysis(arrayAnalyzed: NDArray[numpy.uint64], state: MatrixMeandersNumPyState, arcCode: NDArray[numpy.uint64]) -> MatrixMeandersNumPyState:
+			"""Record valid `arcCode` and corresponding `crossings` in `arrayAnalyzed`."""
+			selectorOverLimit = arcCode > state.MAXIMUMarcCode
+			arcCode[selectorOverLimit] = 0
+			del selectorOverLimit
+
+			selectorAnalysis: NDArray[numpy.intp] = numpy.flatnonzero(arcCode)
+
+			indexStop: int = state.indexTarget + len(selectorAnalysis)
+			sliceAnalysis: slice = slice(state.indexTarget, indexStop)
+			state.indexTarget = indexStop
+			del indexStop
+
+			slicerArcCodeAnalysis = ShapeSlicer(length=sliceAnalysis, indices=indexArcCode)
+			slicerCrossingsAnalysis = ShapeSlicer(length=sliceAnalysis, indices=indexCrossings)
+			del sliceAnalysis
+
+			arrayAnalyzed[slicerArcCodeAnalysis] = arcCode[selectorAnalysis]
+			del slicerArcCodeAnalysis
+
+			arrayAnalyzed[slicerCrossingsAnalysis] = state.arrayCrossings[selectorAnalysis]
+			del slicerCrossingsAnalysis, selectorAnalysis
+			goByeBye()
+			return state
+
+		state.bitWidth = int(state.arrayArcCodes.max()).bit_length()
+
+		lengthArrayAnalyzed: int = getBucketsTotal(state, 1.2)
+		shape = ShapeArray(length=lengthArrayAnalyzed, indices=indicesAnalyzed)
+		del lengthArrayAnalyzed
+		goByeBye()
+
+		arrayAnalyzed: NDArray[numpy.uint64] = numpy.zeros(shape, dtype=state.datatypeArcCode)
+		del shape
+
+		shape = ShapeArray(length=len(state.arrayArcCodes), indices=indicesPrepArea)
+		arrayPrepArea: NDArray[numpy.uint64] = numpy.zeros(shape, dtype=state.datatypeArcCode)
+		del shape
+
+		prepArea: NDArray[numpy.uint64] = arrayPrepArea[slicerAnalysis].view()
+
+		state.indexTarget = 0
+
+		state.boundary -= 1
+
+# =============== analyze aligned ===== if bitsAlpha > 1 and bitsZulu > 1 =============================================
+		arrayBitsAlpha: NDArray[numpy.uint64] = bitwise_and(state.arrayArcCodes, state.locatorBits)	# NOTE extra array
+# ======= > * > bitsAlpha 1 bitsZulu 1 ====================
+		greater(arrayBitsAlpha, 1, out=prepArea)
+		bitsZuluStack: NDArray[numpy.uint64] = makeStorage(state.arrayArcCodes, state, arrayAnalyzed, indexCrossings)
+		bitwise_right_shift(bitsZuluStack, 1, out=bitsZuluStack)					# O indexArcCode X indexCrossings
+		bitwise_and(bitsZuluStack, state.locatorBits, out=bitsZuluStack)
+		multiply(bitsZuluStack, prepArea, out=prepArea)
+		greater(prepArea, 1, out=prepArea)
+		selectorGreaterThan1: NDArray[numpy.uint64] = makeStorage(prepArea, state, arrayAnalyzed, indexArcCode)
+																					# X indexArcCode X indexCrossings
+# ======= if bitsAlphaAtEven and not bitsZuluAtEven =======
+# ======= ^ & | ^ & bitsZulu 1 1 bitsAlpha 1 1 ============
+		bitwise_and(bitsZuluStack, 1, out=prepArea)
+		del bitsZuluStack 															# X indexArcCode O indexCrossings
+		bitwise_xor(prepArea, 1, out=prepArea)
+		bitwise_or(arrayBitsAlpha, prepArea, out=prepArea)
+		bitwise_and(prepArea, 1, out=prepArea)
+		bitwise_xor(prepArea, 1, out=prepArea)
+
+		bitwise_and(selectorGreaterThan1, prepArea, out=prepArea)
+		selectorAlignAlpha: NDArray[numpy.intp] = makeStorage(numpy.flatnonzero(prepArea), state, arrayAnalyzed, indexCrossings)
+																					# X indexArcCode X indexCrossings
+		arrayBitsAlpha[selectorAlignAlpha] = flipTheExtra_0b1AsUfunc(arrayBitsAlpha[selectorAlignAlpha])
+		del selectorAlignAlpha 														# X indexArcCode O indexCrossings
+
+# ======= if bitsZuluAtEven and not bitsAlphaAtEven =======
+# ======= ^ & | ^ & bitsAlpha 1 1 bitsZulu 1 1 ============
+		bitsAlphaStack: NDArray[numpy.uint64] = makeStorage(state.arrayArcCodes, state, arrayAnalyzed, indexCrossings)
+		bitwise_and(bitsAlphaStack, state.locatorBits, out=bitsAlphaStack)
+		bitwise_and(bitsAlphaStack, 1, out=prepArea)
+		del bitsAlphaStack 															# X indexArcCode O indexCrossings
+		bitwise_xor(prepArea, 1, out=prepArea)
+		bitsZuluStack: NDArray[numpy.uint64] = makeStorage(state.arrayArcCodes, state, arrayAnalyzed, indexCrossings)
+		bitwise_right_shift(bitsZuluStack, 1, out=bitsZuluStack)
+		bitwise_and(bitsZuluStack, state.locatorBits, out=bitsZuluStack)
+		bitwise_or(bitsZuluStack, prepArea, out=prepArea)
+		del bitsZuluStack 															# X indexArcCode O indexCrossings
+		bitwise_and(prepArea, 1, out=prepArea)
+		bitwise_xor(prepArea, 1, out=prepArea)
+
+		bitwise_and(selectorGreaterThan1, prepArea, out=prepArea)
+		selectorAlignZulu: NDArray[numpy.intp] = makeStorage(numpy.flatnonzero(prepArea), state, arrayAnalyzed, indexCrossings)
+																					# X indexArcCode X indexCrossings
+# ======= bitsAlphaAtEven or bitsZuluAtEven ===============
+		bitwise_and(state.arrayArcCodes, state.locatorBits, out=prepArea)
+# ======= ^ & & bitsAlpha 1 bitsZulu 1 ====================
+		bitwise_and(prepArea, 1, out=prepArea)
+		sherpaBitsZulu: NDArray[numpy.uint64] = bitwise_right_shift(state.arrayArcCodes, 1) # NOTE 2° extra array
+		bitwise_and(sherpaBitsZulu, state.locatorBits, out=sherpaBitsZulu)
+		bitwise_and(sherpaBitsZulu, prepArea, out=prepArea)
+		del sherpaBitsZulu															# NOTE del 2° extra array
+		bitwise_xor(prepArea, 1, out=prepArea)
+
+		bitwise_and(selectorGreaterThan1, prepArea, out=prepArea) # selectorBitsAtEven
+		del selectorGreaterThan1 													# O indexArcCode X indexCrossings
+		bitwise_xor(prepArea, 1, out=prepArea)
+		selectorDisqualified: NDArray[numpy.intp] = makeStorage(numpy.flatnonzero(prepArea), state, arrayAnalyzed, indexArcCode)
+																					# X indexArcCode X indexCrossings
+		bitwise_right_shift(state.arrayArcCodes, 1, out=prepArea)
+		bitwise_and(prepArea, state.locatorBits, out=prepArea)
+
+		prepArea[selectorAlignZulu] = flipTheExtra_0b1AsUfunc(prepArea[selectorAlignZulu])
+		del selectorAlignZulu 														# X indexArcCode O indexCrossings
+
+		bitsZuluStack: NDArray[numpy.uint64] = makeStorage(prepArea, state, arrayAnalyzed, indexCrossings)
+
+# ======= (((bitsZulu >> 2) << 3) | bitsAlpha) >> 2 =======
+# ======= >> | << >> bitsZulu 2 3 bitsAlpha 2 =============
+		bitwise_right_shift(bitsZuluStack, 2, out=prepArea)
+		del bitsZuluStack 															# X indexArcCode O indexCrossings
+		bitwise_left_shift(prepArea, 3, out=prepArea)
+		bitwise_or(arrayBitsAlpha, prepArea, out=prepArea)
+		del arrayBitsAlpha															# NOTE del extra array
+		bitwise_right_shift(prepArea, 2, out=prepArea)
+
+		prepArea[selectorDisqualified] = 0
+		del selectorDisqualified 													# O indexArcCode O indexCrossings
+
+		state = recordAnalysis(arrayAnalyzed, state, prepArea)
+
+# ----------------- analyze bitsAlpha ------- (bitsAlpha >> 2) | (bitsZulu << 3) | ((1 - (bitsAlpha & 1)) << 1) ---------
+		bitsAlphaStack: NDArray[numpy.uint64] = makeStorage(state.arrayArcCodes, state, arrayAnalyzed, indexArcCode)
+		bitwise_and(bitsAlphaStack, state.locatorBits, out=bitsAlphaStack)			# X indexArcCode O indexCrossings
+# ------- >> | << | (<< - 1 & bitsAlpha 1 1) << bitsZulu 3 2 bitsAlpha 2 ----------
+		bitwise_and(bitsAlphaStack, 1, out=bitsAlphaStack)
+		subtract(1, bitsAlphaStack, out=bitsAlphaStack)
+		bitwise_left_shift(bitsAlphaStack, 1, out=bitsAlphaStack)
+		bitsZuluStack: NDArray[numpy.uint64] = makeStorage(state.arrayArcCodes, state, arrayAnalyzed, indexCrossings)
+		bitwise_right_shift(bitsZuluStack, 1, out=bitsZuluStack)
+		bitwise_and(bitsZuluStack, state.locatorBits, out=bitsZuluStack)
+		bitwise_left_shift(bitsZuluStack, 3, out=prepArea)
+		del bitsZuluStack 															# X indexArcCode O indexCrossings
+		bitwise_or(bitsAlphaStack, prepArea, out=prepArea)
+		del bitsAlphaStack 															# O indexArcCode O indexCrossings
+		bitwise_left_shift(prepArea, 2, out=prepArea)
+		bitsAlphaStack: NDArray[numpy.uint64] = makeStorage(state.arrayArcCodes, state, arrayAnalyzed, indexCrossings)
+		bitwise_and(bitsAlphaStack, state.locatorBits, out=bitsAlphaStack)			# O indexArcCode X indexCrossings
+		bitwise_or(bitsAlphaStack, prepArea, out=prepArea)
+		bitwise_right_shift(prepArea, 2, out=prepArea)
+
+# ------- if bitsAlpha > 1 ------------ > bitsAlpha 1 -----
+		less_equal(bitsAlphaStack, 1, out=bitsAlphaStack)
+		selectorUnderLimit: NDArray[numpy.intp] = makeStorage(numpy.flatnonzero(bitsAlphaStack), state, arrayAnalyzed, indexArcCode)
+		del bitsAlphaStack 															# X indexArcCode O indexCrossings
+		prepArea[selectorUnderLimit] = 0
+		del selectorUnderLimit 														# O indexArcCode O indexCrossings
+
+		state = recordAnalysis(arrayAnalyzed, state, prepArea)
+
+# ----------------- analyze bitsZulu ---------- (bitsZulu >> 1) | (bitsAlpha << 2) | (1 - (bitsZulu & 1)) -------------
+		arrayBitsZulu: NDArray[numpy.uint64] = makeStorage(state.arrayArcCodes, state, arrayAnalyzed, indexCrossings)
+		arrayBitsZulu = bitwise_right_shift(arrayBitsZulu, 1)						# O indexArcCode X indexCrossings
+		arrayBitsZulu = bitwise_and(arrayBitsZulu, state.locatorBits)
+# ------- >> | << | (- 1 & bitsZulu 1) << bitsAlpha 2 1 bitsZulu 1 ----------
+		bitwise_and(arrayBitsZulu, 1, out=arrayBitsZulu)
+		subtract(1, arrayBitsZulu, out=arrayBitsZulu)
+		bitsAlphaStack: NDArray[numpy.uint64] = makeStorage(state.arrayArcCodes, state, arrayAnalyzed, indexArcCode)
+		bitwise_and(bitsAlphaStack, state.locatorBits, out=bitsAlphaStack)			# X indexArcCode X indexCrossings
+		bitwise_left_shift(bitsAlphaStack, 2, out=prepArea)
+		del bitsAlphaStack 															# O indexArcCode X indexCrossings
+		bitwise_or(arrayBitsZulu, prepArea, out=prepArea)
+		del arrayBitsZulu 															# O indexArcCode O indexCrossings
+		bitwise_left_shift(prepArea, 1, out=prepArea)
+		bitsZuluStack: NDArray[numpy.uint64] = makeStorage(state.arrayArcCodes, state, arrayAnalyzed, indexCrossings)
+		bitwise_right_shift(bitsZuluStack, 1, out=bitsZuluStack)					# O indexArcCode X indexCrossings
+		bitwise_and(bitsZuluStack, state.locatorBits, out=bitsZuluStack)
+		bitwise_or(bitsZuluStack, prepArea, out=prepArea)
+		bitwise_right_shift(prepArea, 1, out=prepArea)
+
+# ------- if bitsZulu > 1 ------------- > bitsZulu 1 ------
+		less_equal(bitsZuluStack, 1, out=bitsZuluStack)
+		selectorUnderLimit = makeStorage(numpy.flatnonzero(bitsZuluStack), state, arrayAnalyzed, indexArcCode)
+		del bitsZuluStack 															# X indexArcCode O indexCrossings
+		prepArea[selectorUnderLimit] = 0
+		del selectorUnderLimit 														# O indexArcCode O indexCrossings
+
+		state = recordAnalysis(arrayAnalyzed, state, prepArea)
+
+# ----------------- analyze simple ------------------------ ((bitsAlpha | (bitsZulu << 1)) << 2) | 3 ------------------
+		bitsZuluStack: NDArray[numpy.uint64] = makeStorage(state.arrayArcCodes, state, arrayAnalyzed, indexCrossings)
+		bitwise_right_shift(bitsZuluStack, 1, out=bitsZuluStack)					# O indexArcCode X indexCrossings
+		bitwise_and(bitsZuluStack, state.locatorBits, out=bitsZuluStack)
+# ------- | << | bitsAlpha << bitsZulu 1 2 3 --------------
+		bitwise_left_shift(bitsZuluStack, 1, out=prepArea)
+		del bitsZuluStack 															# O indexArcCode O indexCrossings
+		bitsAlphaStack: NDArray[numpy.uint64] = makeStorage(state.arrayArcCodes, state, arrayAnalyzed, indexArcCode)
+		bitwise_and(bitsAlphaStack, state.locatorBits, out=bitsAlphaStack)			# X indexArcCode O indexCrossings
+		bitwise_or(bitsAlphaStack, prepArea, out=prepArea)
+		del bitsAlphaStack 															# O indexArcCode O indexCrossings
+		bitwise_left_shift(prepArea, 2, out=prepArea)
+		bitwise_or(prepArea, 3, out=prepArea)
+
+		state = recordAnalysis(arrayAnalyzed, state, prepArea)
+
+		del prepArea, arrayPrepArea
+# ----------------------------------------------- aggregation ---------------------------------------------------------
+		state.arrayArcCodes = numpy.zeros((0,), dtype=state.datatypeArcCode)
+		arrayAnalyzed.resize((state.indexTarget, indicesAnalyzed))
+
+		goByeBye()
+		state = aggregateAnalyzed(arrayAnalyzed, state)
+
+		del arrayAnalyzed
+
+		if state.n >= 45:
+		# oeisID,n,boundary,buckets,arcCodes,arcCodeBitWidth,crossingsBitWidth
+			print(state.oeisID, state.n, state.boundary+1, state.indexTarget, len(state.arrayArcCodes), int(state.arrayArcCodes.max()).bit_length(), int(state.arrayCrossings.max()).bit_length(), sep=',')  # noqa: T201
+	return state
+
+def doTheNeedful(state: MatrixMeandersNumPyState) -> int:
+	"""Compute `crossings` with a transfer matrix algorithm implemented in NumPy.
+
+	Parameters
+	----------
+	state : MatrixMeandersState
+		The algorithm state.
+
+	Returns
+	-------
+	crossings : int
+		The computed value of `crossings`.
+
+	Notes
+	-----
+	Citation: https://github.com/hunterhogan/mapFolding/blob/main/citations/Jensen.bibtex
+
+	See Also
+	--------
+	https://oeis.org/A000682
+	https://oeis.org/A005316
+	"""
+	while state.boundary > 0:
+		if areIntegersWide(state):
+			state = countBigInt(state)
+		else:
+			state.makeArray()
+			state = countNumPy(state)
+			state.makeDictionary()
+	return sum(state.dictionaryMeanders.values())