mapFolding 0.7.0__tar.gz → 0.8.0__tar.gz

{mapfolding-0.7.0 → mapfolding-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: mapFolding
-Version: 0.7.0
+Version: 0.8.0
 Summary: Count distinct ways to fold a map (or a strip of stamps)
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 License: CC-BY-NC-4.0
@@ -38,12 +38,11 @@ Requires-Dist: tomli
 Requires-Dist: Z0Z_tools
 Provides-Extra: testing
 Requires-Dist: mypy; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
 Requires-Dist: pytest-cov; extra == "testing"
 Requires-Dist: pytest-env; extra == "testing"
 Requires-Dist: pytest-xdist; extra == "testing"
-Requires-Dist: pytest; extra == "testing"
 Requires-Dist: pyupgrade; extra == "testing"
-Requires-Dist: updateCitation; extra == "testing"
 
 # mapFolding: Algorithms for enumerating distinct map/stamp folding patterns 🗺️
 
@@ -113,14 +112,14 @@ Available OEIS sequences:
 
 ### 4. **Customizing your algorithm**
 
-- mapFolding\someAssemblyRequired\synthesizeNumbaJob.py (and/or synthesizeNumba____.py, as applicable)
+- Renovations in progress: ~~mapFolding\someAssemblyRequired\synthesizeNumbaJob.py (and/or synthesizeNumba____.py, as applicable)~~
   - Synthesize a Numba-optimized module for a specific mapShape
   - Synthesize _from_ a module in mapFolding\syntheticModules or from any source you select
   - Use the existing transformation options
   - Or create new ways of transforming the algorithm from its source to a specific job
-- mapFolding\someAssemblyRequired\makeJob.py
+- Renovations in progress: ~~mapFolding\someAssemblyRequired\makeJob.py~~
   - Initialize data for a specific mapShape
-- mapFolding\someAssemblyRequired\synthesizeNumbaModules.py (and/or synthesizeNumba____.py, as applicable)
+- Renovations in progress: ~~mapFolding\someAssemblyRequired\synthesizeNumbaModules.py (and/or synthesizeNumba____.py, as applicable)~~
   - Synthesize one or more Numba-optimized modules for parallel or sequential computation
   - Overwrite the modules in mapFolding\syntheticModules or save the module(s) to a custom path
   - Synthesize _from_ the algorithm(s) in mapFolding\theDao.py or from any source you select
@@ -131,7 +130,7 @@ Available OEIS sequences:
   - Modify the algorithms for initializing values, parallel computation, and/or sequential computation
   - Use the modified algorithm(s) in synthesizeNumbaModules.py, above, to create Numba-optimized version(s)
   - Then use a Numba-optimized version in synthesizeNumbaJob.py, above, to create a hyper-optimized version for a specific mapShape
-- mapFolding\theSSOT.py (and/or theSSOTnumba.py and/ or theSSOT____.py, if they exist)
+- mapFolding\theSSOT.py
   - Modify broad settings or find functions to modify broad settings, such as data structures and their data types
   - Create new settings or groups of settings
 - mapFolding\beDRY.py

{mapfolding-0.7.0 → mapfolding-0.8.0}/README.md

@@ -66,14 +66,14 @@ Available OEIS sequences:
 
 ### 4. **Customizing your algorithm**
 
-- mapFolding\someAssemblyRequired\synthesizeNumbaJob.py (and/or synthesizeNumba____.py, as applicable)
+- Renovations in progress: ~~mapFolding\someAssemblyRequired\synthesizeNumbaJob.py (and/or synthesizeNumba____.py, as applicable)~~
   - Synthesize a Numba-optimized module for a specific mapShape
   - Synthesize _from_ a module in mapFolding\syntheticModules or from any source you select
   - Use the existing transformation options
   - Or create new ways of transforming the algorithm from its source to a specific job
-- mapFolding\someAssemblyRequired\makeJob.py
+- Renovations in progress: ~~mapFolding\someAssemblyRequired\makeJob.py~~
   - Initialize data for a specific mapShape
-- mapFolding\someAssemblyRequired\synthesizeNumbaModules.py (and/or synthesizeNumba____.py, as applicable)
+- Renovations in progress: ~~mapFolding\someAssemblyRequired\synthesizeNumbaModules.py (and/or synthesizeNumba____.py, as applicable)~~
   - Synthesize one or more Numba-optimized modules for parallel or sequential computation
   - Overwrite the modules in mapFolding\syntheticModules or save the module(s) to a custom path
   - Synthesize _from_ the algorithm(s) in mapFolding\theDao.py or from any source you select
@@ -84,7 +84,7 @@ Available OEIS sequences:
   - Modify the algorithms for initializing values, parallel computation, and/or sequential computation
   - Use the modified algorithm(s) in synthesizeNumbaModules.py, above, to create Numba-optimized version(s)
   - Then use a Numba-optimized version in synthesizeNumbaJob.py, above, to create a hyper-optimized version for a specific mapShape
-- mapFolding\theSSOT.py (and/or theSSOTnumba.py and/ or theSSOT____.py, if they exist)
+- mapFolding\theSSOT.py
   - Modify broad settings or find functions to modify broad settings, such as data structures and their data types
   - Create new settings or groups of settings
 - mapFolding\beDRY.py

{mapfolding-0.7.0 → mapfolding-0.8.0}/mapFolding/__init__.py

@@ -1,4 +1,4 @@
-from mapFolding.basecamp import countFolds
+from mapFolding.basecamp import countFolds as countFolds
 from mapFolding.oeis import clearOEIScache, getOEISids, OEIS_for_n
 
 __all__ = [

{mapfolding-0.7.0 → mapfolding-0.8.0}/mapFolding/basecamp.py

@@ -43,8 +43,8 @@ def countFolds(listDimensions: Sequence[int]
 	concurrencyLimit: int = setCPUlimit(CPUlimit)
 	computationStateInitialized: ComputationState = outfitCountFolds(mapShape, computationDivisions, concurrencyLimit)
 
-	dispatcher = getPackageDispatcher()
-	computationStateComplete: ComputationState = dispatcher(computationStateInitialized)
+	dispatcherCallableProxy = getPackageDispatcher()
+	computationStateComplete: ComputationState = dispatcherCallableProxy(computationStateInitialized)
 
 	computationStateComplete.getFoldsTotal()
 

{mapfolding-0.7.0 → mapfolding-0.8.0}/mapFolding/beDRY.py

@@ -1,30 +1,11 @@
 """A relatively stable API for oft-needed functionality."""
-from mapFolding.theSSOT import (
-	Array3D,
-	ComputationState,
-	getDatatypePackage,
-	getNumpyDtypeDefault,
-)
 from collections.abc import Sequence
+from mapFolding.theSSOT import Array3D, ComputationState, getDatatypePackage, getNumpyDtypeDefault
 from sys import maxsize as sysMaxsize
 from typing import Any
 from Z0Z_tools import defineConcurrencyLimit, intInnit, oopsieKwargsie
 import numpy
 
-def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
-	if not listDimensions:
-		raise ValueError("listDimensions is a required parameter.")
-	listValidated: list[int] = intInnit(listDimensions, 'listDimensions')
-	listNonNegative: list[int] = []
-	for dimension in listValidated:
-		if dimension < 0:
-			raise ValueError(f"Dimension {dimension} must be non-negative")
-		listNonNegative.append(dimension)
-	dimensionsValid = [dimension for dimension in listNonNegative if dimension > 0]
-	if len(dimensionsValid) < 2:
-		raise NotImplementedError(f"This function requires listDimensions, {listDimensions}, to have at least two dimensions greater than 0. You may want to look at https://oeis.org/.")
-	return tuple(sorted(dimensionsValid))
-
 def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
 	productDimensions = 1
 	for dimension in mapShape:
@@ -33,7 +14,59 @@ def getLeavesTotal(mapShape: tuple[int, ...]) -> int:
 		productDimensions *= dimension
 	return productDimensions
 
-def getNumpyDtype(datatype: type[numpy.signedinteger[Any]] | None = None) -> type[numpy.signedinteger[Any]]:
+def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: int, leavesTotal: int) -> int:
+	"""
+	Determines whether to divide the computation into tasks and how many divisions.
+
+	Parameters
+	----------
+	computationDivisions (None)
+		Specifies how to divide computations:
+		- `None`: no division of the computation into tasks; sets task divisions to 0.
+		- int: direct set the number of task divisions; cannot exceed the map's total leaves.
+		- `'maximum'`: divides into `leavesTotal`-many `taskDivisions`.
+		- `'cpu'`: limits the divisions to the number of available CPUs, i.e. `concurrencyLimit`.
+	concurrencyLimit
+		Maximum number of concurrent tasks allowed.
+	CPUlimit
+		for error reporting.
+	listDimensions
+		for error reporting.
+
+	Returns
+	-------
+	taskDivisions
+		How many tasks must finish before the job can compute the total number of folds; `0` means no tasks, only job.
+
+	Raises
+	------
+	ValueError
+		If computationDivisions is an unsupported type or if resulting task divisions exceed total leaves.
+
+	Notes
+	-----
+	Task divisions should not exceed total leaves or the folds will be over-counted.
+	"""
+	taskDivisions = 0
+	if not computationDivisions:
+		pass
+	elif isinstance(computationDivisions, int):
+		taskDivisions = computationDivisions
+	elif isinstance(computationDivisions, str): # type: ignore
+		# 'Unnecessary isinstance call; "str" is always an instance of "str", so sayeth Pylance'. Yeah, well "User is not always an instance of "correct input" so sayeth the programmer.
+		computationDivisions = computationDivisions.lower()
+		if computationDivisions == 'maximum':
+			taskDivisions = leavesTotal
+		elif computationDivisions == 'cpu':
+			taskDivisions = min(concurrencyLimit, leavesTotal)
+	else:
+		raise ValueError(f"I received {computationDivisions} for the parameter, `computationDivisions`, but the so-called programmer didn't implement code for that.")
+
+	if taskDivisions > leavesTotal:
+		raise ValueError(f"Problem: `taskDivisions`, ({taskDivisions}), is greater than `leavesTotal`, ({leavesTotal}), which will cause duplicate counting of the folds.\n\nChallenge: you cannot directly set `taskDivisions` or `leavesTotal`. They are derived from parameters that may or may not still be named `computationDivisions`, `CPUlimit` , and `listDimensions` and from dubious-quality Python code.")
+	return int(max(0, taskDivisions))
+
+def interpretParameter_datatype(datatype: type[numpy.signedinteger[Any]] | None = None) -> type[numpy.signedinteger[Any]]:
 	"""An imperfect way to reduce code duplication."""
 	if 'numpy' == getDatatypePackage():
 		numpyDtype = datatype or getNumpyDtypeDefault()
@@ -42,7 +75,7 @@ def getNumpyDtype(datatype: type[numpy.signedinteger[Any]] | None = None) -> typ
 	return numpyDtype
 
 def makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: type[numpy.signedinteger[Any]] | None = None) -> Array3D:
-	numpyDtype = getNumpyDtype(datatype)
+	numpyDtype = interpretParameter_datatype(datatype)
 	dimensionsTotal = len(mapShape)
 	cumulativeProduct = numpy.multiply.accumulate([1] + list(mapShape), dtype=numpyDtype)
 	arrayDimensions = numpy.array(mapShape, dtype=numpyDtype)
@@ -69,11 +102,24 @@ def makeConnectionGraph(mapShape: tuple[int, ...], leavesTotal: int, datatype: t
 	return connectionGraph
 
 def makeDataContainer(shape: int | tuple[int, ...], datatype: type[numpy.signedinteger[Any]] | None = None) -> numpy.ndarray[Any, numpy.dtype[numpy.signedinteger[Any]]]:
-	numpyDtype = getNumpyDtype(datatype)
+	numpyDtype = interpretParameter_datatype(datatype)
 	return numpy.zeros(shape, dtype=numpyDtype)
 
+def outfitCountFolds(mapShape: tuple[int, ...], computationDivisions: int | str | None = None, concurrencyLimit: int = 1) -> ComputationState:
+	leavesTotal = getLeavesTotal(mapShape)
+	taskDivisions = getTaskDivisions(computationDivisions, concurrencyLimit, leavesTotal)
+	computationStateInitialized = ComputationState(mapShape, leavesTotal, taskDivisions, concurrencyLimit)
+	return computationStateInitialized
+
 def setCPUlimit(CPUlimit: Any | None) -> int:
-	"""Sets CPU limit for Numba concurrent operations. Note that it can only affect Numba-jitted functions that have not yet been imported.
+	"""Sets CPU limit for concurrent operations.
+
+	If the concurrency is managed by `numba`, the maximum number of CPUs is retrieved from `numba.get_num_threads()` and not by polling the hardware. Therefore, if there are
+	numba environment variables limiting the number of available CPUs, that will effect this function. That _should_ be a good thing: you control the number of CPUs available
+	to numba. But if you're not aware of that, you might be surprised by the results.
+
+	If you are designing custom modules that use numba, note that you must call `numba.set_num_threads()` (i.e., this function) before executing an `import` statement
+	on a Numba-jitted function. Otherwise, the `numba.set_num_threads()` call will have no effect on the imported function.
 
 	Parameters:
 		CPUlimit: whether and how to limit the CPU usage. See notes for details.
@@ -93,72 +139,29 @@ def setCPUlimit(CPUlimit: Any | None) -> int:
 	if not (CPUlimit is None or isinstance(CPUlimit, (bool, int, float))):
 		CPUlimit = oopsieKwargsie(CPUlimit)
 
-	concurrencyLimit: int = int(defineConcurrencyLimit(CPUlimit))
 	from mapFolding.theSSOT import concurrencyPackage
 	if concurrencyPackage == 'numba':
 		from numba import get_num_threads, set_num_threads
+		concurrencyLimit: int = defineConcurrencyLimit(CPUlimit, get_num_threads())
 		set_num_threads(concurrencyLimit)
 		concurrencyLimit = get_num_threads()
-	elif concurrencyPackage == 'algorithm':
-		concurrencyLimit = 1
+	elif concurrencyPackage == 'multiprocessing':
+		# When to use multiprocessing.set_start_method https://github.com/hunterhogan/mapFolding/issues/6
+		concurrencyLimit = defineConcurrencyLimit(CPUlimit)
 	else:
-		raise NotImplementedError("This function only supports the 'numba' concurrency package.")
-
+		raise NotImplementedError(f"I received {concurrencyPackage=} but I don't know what to do with that.")
 	return concurrencyLimit
 
-def getTaskDivisions(computationDivisions: int | str | None, concurrencyLimit: int, leavesTotal: int) -> int:
-	"""
-	Determines whether to divide the computation into tasks and how many divisions.
-
-	Parameters
-	----------
-	computationDivisions (None)
-		Specifies how to divide computations:
-		- `None`: no division of the computation into tasks; sets task divisions to 0.
-		- int: direct set the number of task divisions; cannot exceed the map's total leaves.
-		- `'maximum'`: divides into `leavesTotal`-many `taskDivisions`.
-		- `'cpu'`: limits the divisions to the number of available CPUs, i.e. `concurrencyLimit`.
-	concurrencyLimit
-		Maximum number of concurrent tasks allowed.
-	CPUlimit
-		for error reporting.
-	listDimensions
-		for error reporting.
-
-	Returns
-	-------
-	taskDivisions
-		How many tasks must finish before the job can compute the total number of folds; `0` means no tasks, only job.
-
-	Raises
-	------
-	ValueError
-		If computationDivisions is an unsupported type or if resulting task divisions exceed total leaves.
-
-	Notes
-	-----
-	Task divisions should not exceed total leaves or the folds will be over-counted.
-	"""
-	taskDivisions = 0
-	if not computationDivisions:
-		pass
-	elif isinstance(computationDivisions, int):
-		taskDivisions = computationDivisions
-	elif isinstance(computationDivisions, str): # type: ignore 'Unnecessary isinstance call; "str" is always an instance of "str", so sayeth Pylance'. Yeah, well "User is not always an instance of "correct input" so sayeth the programmer.
-		computationDivisions = computationDivisions.lower()
-		if computationDivisions == 'maximum':
-			taskDivisions = leavesTotal
-		elif computationDivisions == 'cpu':
-			taskDivisions = min(concurrencyLimit, leavesTotal)
-	else:
-		raise ValueError(f"I received {computationDivisions} for the parameter, `computationDivisions`, but the so-called programmer didn't implement code for that.")
-
-	if taskDivisions > leavesTotal:
-		raise ValueError(f"Problem: `taskDivisions`, ({taskDivisions}), is greater than `leavesTotal`, ({leavesTotal}), which will cause duplicate counting of the folds.\n\nChallenge: you cannot directly set `taskDivisions` or `leavesTotal`. They are derived from parameters that may or may not still be named `computationDivisions`, `CPUlimit` , and `listDimensions` and from dubious-quality Python code.")
-	return int(max(0, taskDivisions))
-
-def outfitCountFolds(mapShape: tuple[int, ...], computationDivisions: int | str | None = None, concurrencyLimit: int = 1) -> ComputationState:
-	leavesTotal = getLeavesTotal(mapShape)
-	taskDivisions = getTaskDivisions(computationDivisions, concurrencyLimit, leavesTotal)
-	computationStateInitialized = ComputationState(mapShape, leavesTotal, taskDivisions)
-	return computationStateInitialized
+def validateListDimensions(listDimensions: Sequence[int]) -> tuple[int, ...]:
+	if not listDimensions:
+		raise ValueError("listDimensions is a required parameter.")
+	listValidated: list[int] = intInnit(listDimensions, 'listDimensions')
+	listNonNegative: list[int] = []
+	for dimension in listValidated:
+		if dimension < 0:
+			raise ValueError(f"Dimension {dimension} must be non-negative")
+		listNonNegative.append(dimension)
+	dimensionsValid = [dimension for dimension in listNonNegative if dimension > 0]
+	if len(dimensionsValid) < 2:
+		raise NotImplementedError(f"This function requires listDimensions, {listDimensions}, to have at least two dimensions greater than 0. You may want to look at https://oeis.org/.")
+	return tuple(sorted(dimensionsValid))

{mapfolding-0.7.0 → mapfolding-0.8.0}/mapFolding/filesystem.py

@@ -1,35 +1,8 @@
 """Filesystem functions for mapFolding package."""
-from pathlib import Path
+from pathlib import Path, PurePath
+from typing import Any
 import os
 
-def saveFoldsTotal(pathFilename: str | os.PathLike[str], foldsTotal: int) -> None:
-	"""
-	Save foldsTotal with multiple fallback mechanisms.
-
-	Parameters:
-		pathFilename: Target save location
-		foldsTotal: Critical computed value to save
-	"""
-	try:
-		pathFilenameFoldsTotal = Path(pathFilename)
-		pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
-		pathFilenameFoldsTotal.write_text(str(foldsTotal))
-	except Exception as ERRORmessage:
-		try:
-			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
-			print(ERRORmessage)
-			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
-			randomnessPlanB = (int(str(foldsTotal).strip()[-1]) + 1) * ['YO_']
-			filenameInfixUnique = ''.join(randomnessPlanB)
-			pathFilenamePlanB = os.path.join(os.getcwd(), 'foldsTotal' + filenameInfixUnique + '.txt')
-			writeStreamFallback = open(pathFilenamePlanB, 'w')
-			writeStreamFallback.write(str(foldsTotal))
-			writeStreamFallback.close()
-			print(str(pathFilenamePlanB))
-		except Exception:
-			print(foldsTotal)
-	return None
-
 def getFilenameFoldsTotal(mapShape: tuple[int, ...]) -> str:
 	"""Imagine your computer has been counting folds for 9 days, and when it tries to save your newly discovered value,
 	the filename is invalid. I bet you think this function is more important after that thought experiment.
@@ -85,3 +58,38 @@ def getPathFilenameFoldsTotal(mapShape: tuple[int, ...], pathLikeWriteFoldsTotal
 
 	pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
 	return pathFilenameFoldsTotal
+
+def saveFoldsTotal(pathFilename: str | os.PathLike[str], foldsTotal: int) -> None:
+	"""
+	Save foldsTotal with multiple fallback mechanisms.
+
+	Parameters:
+		pathFilename: Target save location
+		foldsTotal: Critical computed value to save
+	"""
+	try:
+		pathFilenameFoldsTotal = Path(pathFilename)
+		pathFilenameFoldsTotal.parent.mkdir(parents=True, exist_ok=True)
+		pathFilenameFoldsTotal.write_text(str(foldsTotal))
+	except Exception as ERRORmessage:
+		try:
+			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+			print(ERRORmessage)
+			print(f"\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n\n{foldsTotal=}\n\nfoldsTotal foldsTotal foldsTotal foldsTotal foldsTotal\n")
+			randomnessPlanB = (int(str(foldsTotal).strip()[-1]) + 1) * ['YO_']
+			filenameInfixUnique = ''.join(randomnessPlanB)
+			pathFilenamePlanB = os.path.join(os.getcwd(), 'foldsTotal' + filenameInfixUnique + '.txt')
+			writeStreamFallback = open(pathFilenamePlanB, 'w')
+			writeStreamFallback.write(str(foldsTotal))
+			writeStreamFallback.close()
+			print(str(pathFilenamePlanB))
+		except Exception:
+			print(foldsTotal)
+	return None
+
+def writeStringToHere(this: str, pathFilename: str | os.PathLike[Any] | PurePath) -> None:
+	"""Write the string `this` to the file at `pathFilename`."""
+	pathFilename = Path(pathFilename)
+	pathFilename.parent.mkdir(parents=True, exist_ok=True)
+	pathFilename.write_text(str(this))
+	return None

{mapfolding-0.7.0 → mapfolding-0.8.0}/mapFolding/noHomeYet.py

@@ -11,8 +11,8 @@ def makeDictionaryFoldsTotalKnown() -> dict[tuple[int, ...], int]:
 
 		for n, foldingsTotal in sequence.items():
 			mapShape = settings['getMapShape'](n)
-			mapShape = sorted(mapShape)
-			dictionaryMapDimensionsToFoldsTotalKnown[tuple(mapShape)] = foldingsTotal
+			mapShape = tuple(sorted(mapShape))
+			dictionaryMapDimensionsToFoldsTotalKnown[mapShape] = foldingsTotal
 	return dictionaryMapDimensionsToFoldsTotalKnown
 
 def getFoldsTotalKnown(mapShape: tuple[int, ...]) -> int:

{mapfolding-0.7.0 → mapfolding-0.8.0}/mapFolding/oeis.py

@@ -144,10 +144,10 @@ def _parseBFileOEIS(OEISbFile: str, oeisID: str) -> dict[int, int]:
 	return OEISsequence
 
 def getOEISofficial(pathFilenameCache: pathlib.Path, url: str) -> None | str:
-	tryCache = False
+	tryCache: bool = False
 	if pathFilenameCache.exists():
 		fileAge: timedelta = datetime.now() - datetime.fromtimestamp(pathFilenameCache.stat().st_mtime)
-		tryCache: bool = fileAge < timedelta(days=cacheDays)
+		tryCache = fileAge < timedelta(days=cacheDays)
 
 	oeisInformation: str | None = None
 	if tryCache: