numdaplot 0.1.0__py3-none-any.whl

numdaplot/arrays/operations/integer_bounds.py

@@ -0,0 +1,175 @@
+"""
+Bounds of an integer result, found from the lowest and the highest values of its operands.
+
+.. versionadded:: 0.1.0
+"""
+
+import math
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+# A power above this number of bits fits no integer type, and is not worth computing exactly.
+LARGEST_COMPUTED_BITS = 65
+BEYOND_EVERY_INTEGER = 2**LARGEST_COMPUTED_BITS
+
+
+def find_value_bounds(values: NDArray[Any]) -> tuple[int, int]:
+	"""
+	Return the lowest and the highest values of integers or booleans, as Python integers.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		At least one integer or boolean.
+
+	Returns
+	-------
+	tuple[int, int]
+		The lowest and the highest values.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.integer_bounds import find_value_bounds
+	>>> find_value_bounds(numpy.array([3, -1, 2]))
+	(-1, 3)
+	"""
+	lowest_value = values.min()
+	highest_value = values.max()
+	low_bound = int(lowest_value)
+	high_bound = int(highest_value)
+
+	return low_bound, high_bound
+
+
+def find_result_bounds(left: tuple[int, int], right: tuple[int, int], function: numpy.ufunc) -> tuple[int, int]:
+	"""
+	Return bounds that every result of an integer function stays within.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	left
+		The bounds of the left operand.
+	right
+		The bounds of the right operand. No divisor is 0 and no power is negative.
+	function
+		``numpy.add``, ``numpy.subtract``, ``numpy.multiply``, ``numpy.floor_divide`` or ``numpy.power``.
+
+	Returns
+	-------
+	tuple[int, int]
+		The low and the high bounds.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.integer_bounds import find_result_bounds
+	>>> find_result_bounds((-2, 3), (4, 5), numpy.multiply)
+	(-10, 15)
+	"""
+	left_low, left_high = left
+	right_low, right_high = right
+	if function == numpy.add:
+		sum_bounds = (left_low + right_low, left_high + right_high)
+		return sum_bounds
+
+	if function == numpy.subtract:
+		difference_bounds = (left_low - right_high, left_high - right_low)
+		return difference_bounds
+
+	if function == numpy.multiply:
+		products = [left_low * right_low, left_low * right_high, left_high * right_low, left_high * right_high]
+		lowest_product = min(products)
+		highest_product = max(products)
+		return lowest_product, highest_product
+
+	left_magnitude = max(abs(left_low), abs(left_high))
+	if function == numpy.floor_divide:
+		has_negative = left_low < 0 or right_low < 0
+		lowest_quotient = -left_magnitude if has_negative else 0
+		return lowest_quotient, left_magnitude
+
+	highest_power = find_power_bound(left_magnitude, right_high)
+	lowest_power = -highest_power if left_low < 0 else 0
+
+	return lowest_power, highest_power
+
+
+def find_power_bound(magnitude: int, power: int) -> int:
+	"""
+	Return a bound of the absolute value of integers raised to a power.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	magnitude
+		The highest absolute value of the integers.
+	power
+		The highest power, 0 or more.
+
+	Returns
+	-------
+	int
+		The bound, or a number beyond every integer type when the exact bound would be huge.
+
+	Examples
+	--------
+	>>> from numdaplot.arrays.operations.integer_bounds import find_power_bound
+	>>> find_power_bound(2, 10)
+	1024
+	>>> find_power_bound(3, 10**18) > 2**64
+	True
+	"""
+	if magnitude <= 1:
+		return 1
+
+	magnitude_bits = math.log2(magnitude)
+	power_bits = power * magnitude_bits
+	if power_bits > LARGEST_COMPUTED_BITS:
+		return BEYOND_EVERY_INTEGER
+
+	power_bound = magnitude**power
+
+	return power_bound
+
+
+def find_sum_bounds(values: NDArray[Any], axis: int | None) -> tuple[int, int]:
+	"""
+	Return bounds that every sum of integers or booleans stays within.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		At least one integer or boolean.
+	axis
+		The numpy axis reduced, or ``None`` for the whole Array.
+
+	Returns
+	-------
+	tuple[int, int]
+		The low and the high bounds.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.integer_bounds import find_sum_bounds
+	>>> find_sum_bounds(numpy.array([[1, 2], [-3, 4]]), None)
+	(-12, 16)
+	>>> find_sum_bounds(numpy.array([[1, 2], [-3, 4]]), 1)
+	(-6, 8)
+	"""
+	value_count = values.size if axis is None else values.shape[axis]
+	low_value, high_value = find_value_bounds(values)
+	low_bound = min(low_value, 0) * value_count
+	high_bound = max(high_value, 0) * value_count
+
+	return low_bound, high_bound

numdaplot/arrays/operations/integer_rules.py

@@ -0,0 +1,397 @@
+"""
+Refusal of integer calculations whose result numpy would silently write as a wrong number.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.operations.integer_bounds import find_result_bounds, find_sum_bounds, find_value_bounds
+from numdaplot.arrays.operations.operand import Operand
+from numdaplot.data_types.numpy_mapping import from_numpy_dtype
+from numdaplot.errors.integer_overflow_error import IntegerOverflowError
+from numdaplot.errors.out_of_domain_error import OutOfDomainError
+
+SIGNED_KIND = "i"
+UNSIGNED_KIND = "u"
+INTEGER_KINDS = frozenset({SIGNED_KIND, UNSIGNED_KIND})
+INTEGER_OR_BOOL_KINDS = frozenset({SIGNED_KIND, UNSIGNED_KIND, "b"})
+POWER_NAME = "Power"
+ZERO_DIVISION_NAMES = dict[numpy.ufunc, str](
+	{
+		numpy.floor_divide: "Floor division",
+		numpy.remainder: "Remainder",
+	}
+)
+OVERFLOWING_FUNCTIONS = frozenset({numpy.add, numpy.subtract, numpy.multiply, numpy.power, numpy.floor_divide})
+PYTHON_OBJECT_DTYPE = numpy.dtype(object)
+ESTIMATE_DTYPE = numpy.dtype(numpy.float64)
+IGNORE_MODE = "ignore"
+# A decimal estimate below half the limit cannot hide a result above it, and one above twice the limit cannot hide a
+# result below it. Exact integers are computed only between both, which also avoids computing huge powers.
+SAFE_ESTIMATE_RATIO = 0.5
+CERTAIN_ESTIMATE_RATIO = 2
+
+
+def require_defined_integers(left: Operand, right: Operand, function: numpy.ufunc) -> None:
+	"""
+	Check that an operation between integers has a result an integer can hold.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	left
+		The values of an Array, or a single value.
+	right
+		The values of an Array, or a single value.
+	function
+		The numpy function about to be applied.
+
+	Raises
+	------
+	OutOfDomainError
+		When integers are divided by 0 with ``//`` or ``%``, or raised to a negative power.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.operations.integer_rules import require_defined_integers
+	>>> try:
+	... 	require_defined_integers(numpy.array([1, 2]), 0, numpy.floor_divide)
+	... except ndp.OutOfDomainError as error:
+	... 	print(error)
+	Floor division is not defined for 0 between integers. Convert the values to FLOAT64 first.
+	"""
+	left_values = numpy.asarray(left)
+	right_values = numpy.asarray(right)
+	has_integers = left_values.dtype.kind in INTEGER_OR_BOOL_KINDS and right_values.dtype.kind in INTEGER_OR_BOOL_KINDS
+	if not has_integers:
+		return
+
+	if function in ZERO_DIVISION_NAMES:
+		zeros = right_values == 0
+		has_zero = bool(zeros.any())
+		if has_zero:
+			raise OutOfDomainError(ZERO_DIVISION_NAMES[function], 0, True)
+
+	if function == numpy.power:
+		negatives = right_values < 0
+		has_negative = bool(negatives.any())
+		if has_negative:
+			negative_values = right_values[negatives]
+			first_negative = negative_values[0].item()
+			raise OutOfDomainError(POWER_NAME, first_negative, True)
+
+
+def require_combination_fits(operands: list[Operand], function: numpy.ufunc, result: NDArray[Any], symbol: str) -> None:
+	"""
+	Check that the integers of a result were not wrapped around by numpy.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operands
+		The left and the right operands, each the values of an Array or a single value.
+	function
+		The numpy function that was applied.
+	result
+		Its result.
+	symbol
+		The operator shown in the error message.
+
+	Raises
+	------
+	IntegerOverflowError
+		When a result does not fit the integer type of ``result``.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.integer_rules import require_combination_fits
+	>>> require_combination_fits([numpy.array([1]), 2], numpy.add, numpy.array([3]), "+")
+	"""
+	if result.dtype.kind not in INTEGER_KINDS:
+		return
+
+	if function not in OVERFLOWING_FUNCTIONS:
+		return
+
+	left_operand, right_operand = operands
+	left_array = numpy.asarray(left_operand)
+	right_array = numpy.asarray(right_operand)
+	if left_array.size == 0 or right_array.size == 0:
+		return
+
+	left_bounds = find_value_bounds(left_array)
+	right_bounds = find_value_bounds(right_array)
+	result_bounds = find_result_bounds(left_bounds, right_bounds, function)
+	bounds_fit = do_bounds_fit(result_bounds, result)
+	if bounds_fit:
+		return
+
+	left_values, right_values = numpy.broadcast_arrays(left_array, right_array)
+	left_estimates = left_values.astype(ESTIMATE_DTYPE)
+	right_estimates = right_values.astype(ESTIMATE_DTYPE)
+	with numpy.errstate(all=IGNORE_MODE):
+		estimates = function(left_estimates, right_estimates)
+
+	doubtful = find_doubtful_estimates(estimates, result, symbol)
+	has_doubt = bool(doubtful.any())
+	if not has_doubt:
+		return
+
+	exact_left = left_values[doubtful].astype(PYTHON_OBJECT_DTYPE)
+	exact_right = right_values[doubtful].astype(PYTHON_OBJECT_DTYPE)
+	exact_values = function(exact_left, exact_right)
+	require_exact_values_fit(exact_values, result, symbol)
+
+
+def require_sum_fits(values: NDArray[Any], axis: int | None, result: NDArray[Any], statistic_name: str) -> None:
+	"""
+	Check that the integers of a sum were not wrapped around by numpy.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The summed values.
+	axis
+		The numpy axis reduced, or ``None`` for the whole Array.
+	result
+		The sum given by numpy.
+	statistic_name
+		Name of the statistic, shown in the error message.
+
+	Raises
+	------
+	IntegerOverflowError
+		When a sum does not fit the integer type of ``result``.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.operations.integer_rules import require_sum_fits
+	>>> values = numpy.array([2**62, 2**62])
+	>>> try:
+	... 	require_sum_fits(values, None, numpy.array([0]), "Sum")
+	... except ndp.IntegerOverflowError as error:
+	... 	print(error)
+	The operation Sum gives values too large for INT64. Convert the values to FLOAT64 first.
+	"""
+	if result.dtype.kind not in INTEGER_KINDS:
+		return
+
+	if values.size == 0:
+		return
+
+	sum_bounds = find_sum_bounds(values, axis)
+	bounds_fit = do_bounds_fit(sum_bounds, result)
+	if bounds_fit:
+		return
+
+	decimal_values = values.astype(ESTIMATE_DTYPE)
+	estimates = numpy.sum(decimal_values, axis=axis)
+	estimate_values = numpy.asarray(estimates)
+	doubtful = find_doubtful_estimates(estimate_values, result, statistic_name)
+	has_doubt = bool(doubtful.any())
+	if not has_doubt:
+		return
+
+	exact_integers = values.astype(PYTHON_OBJECT_DTYPE)
+	exact_values = numpy.sum(exact_integers, axis=axis)
+	exact_array = numpy.asarray(exact_values, dtype=PYTHON_OBJECT_DTYPE)
+	require_exact_values_fit(exact_array, result, statistic_name)
+
+
+def do_bounds_fit(bounds: tuple[int, int], result: NDArray[Any]) -> bool:
+	"""
+	Return whether bounds of a result stay within the limits of its integer type.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	bounds
+		The low and the high bounds of the result.
+	result
+		The result computed with integers, giving the integer type.
+
+	Returns
+	-------
+	bool
+		True when no value can have been wrapped around.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.integer_rules import do_bounds_fit
+	>>> do_bounds_fit((0, 127), numpy.array([0], dtype="int8"))
+	True
+	>>> do_bounds_fit((0, 128), numpy.array([0], dtype="int8"))
+	False
+	"""
+	limits = numpy.iinfo(result.dtype)
+	low_bound, high_bound = bounds
+	bounds_fit = limits.min <= low_bound and high_bound <= limits.max
+
+	return bounds_fit
+
+
+def require_absolute_fits(values: NDArray[Any], operation_name: str) -> None:
+	"""
+	Check that signed integers have an absolute value of their type: the lowest integer has none.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of a number Array.
+	operation_name
+		The operator or the function, shown in the error message.
+
+	Raises
+	------
+	IntegerOverflowError
+		When a value is the lowest integer of its type.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.integer_rules import require_absolute_fits
+	>>> require_absolute_fits(numpy.array([-1, 2]), "Absolute")
+	"""
+	if values.dtype.kind != SIGNED_KIND:
+		return
+
+	limits = numpy.iinfo(values.dtype)
+	is_lowest = values == limits.min
+	has_lowest = bool(is_lowest.any())
+	if has_lowest:
+		values_type = from_numpy_dtype(values.dtype)
+		raise IntegerOverflowError(operation_name, values_type.name)
+
+
+def require_opposite_fits(values: NDArray[Any], operation_name: str) -> None:
+	"""
+	Check that integers have an opposite of their type: unsigned integers only have the opposite of 0.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The values of a number Array.
+	operation_name
+		The operator, shown in the error message.
+
+	Raises
+	------
+	IntegerOverflowError
+		When a value has no opposite in its type.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.integer_rules import require_opposite_fits
+	>>> require_opposite_fits(numpy.array([0], dtype="uint8"), "-")
+	"""
+	require_absolute_fits(values, operation_name)
+	if values.dtype.kind != UNSIGNED_KIND:
+		return
+
+	has_value_above_zero = bool(values.any())
+	if has_value_above_zero:
+		values_type = from_numpy_dtype(values.dtype)
+		raise IntegerOverflowError(operation_name, values_type.name)
+
+
+def find_doubtful_estimates(estimates: NDArray[Any], result: NDArray[Any], operation_name: str) -> NDArray[numpy.bool_]:
+	"""
+	Return which decimal estimates of integers need an exact calculation.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	estimates
+		The result computed with decimals.
+	result
+		The result computed with integers, giving the integer type.
+	operation_name
+		The operator or the statistic, shown in the error message.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		True at each estimate too close to the limits of the type to conclude.
+
+	Raises
+	------
+	IntegerOverflowError
+		When an estimate is far above the limits of the type.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.integer_rules import find_doubtful_estimates
+	>>> find_doubtful_estimates(numpy.array([1.0, 100.0]), numpy.array([1, 100], dtype="int8"), "+")
+	array([False,  True])
+	"""
+	limits = numpy.iinfo(result.dtype)
+	magnitudes = numpy.abs(estimates)
+	is_certain = magnitudes >= limits.max * CERTAIN_ESTIMATE_RATIO
+	has_certain_overflow = bool(numpy.any(is_certain))
+	if has_certain_overflow:
+		result_type = from_numpy_dtype(result.dtype)
+		raise IntegerOverflowError(operation_name, result_type.name)
+
+	is_near_limit = magnitudes >= limits.max * SAFE_ESTIMATE_RATIO
+	is_below_lowest = estimates < limits.min
+	doubtful = is_near_limit | is_below_lowest
+
+	return doubtful
+
+
+def require_exact_values_fit(exact_values: NDArray[Any], result: NDArray[Any], operation_name: str) -> None:
+	"""
+	Check that exact Python integers fit an integer type.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	exact_values
+		Python integers, in a numpy array of objects.
+	result
+		The result computed with integers, giving the integer type.
+	operation_name
+		The operator or the statistic, shown in the error message.
+
+	Raises
+	------
+	IntegerOverflowError
+		When a value is outside the limits of the type.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.integer_rules import require_exact_values_fit
+	>>> require_exact_values_fit(numpy.array([100], dtype=object), numpy.array([100], dtype="int8"), "+")
+	"""
+	limits = numpy.iinfo(result.dtype)
+	is_above = exact_values > limits.max
+	is_below = exact_values < limits.min
+	is_outside = is_above | is_below
+	has_outside_value = bool(numpy.any(is_outside))
+	if has_outside_value:
+		result_type = from_numpy_dtype(result.dtype)
+		raise IntegerOverflowError(operation_name, result_type.name)

numdaplot/arrays/operations/operand.py

@@ -0,0 +1,139 @@
+"""
+Values an Array can be combined with.
+
+.. versionadded:: 0.1.0
+"""
+
+from datetime import date, time, timedelta
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.data_types.numpy_mapping import from_numpy_dtype
+from numdaplot.data_types.time_of_day import to_time_since_midnight
+from numdaplot.data_types.type import Type
+from numdaplot.data_types.value_type import find_value_type
+from numdaplot.rules.rule_values import ScalarValue
+
+MICROSECONDS_IN_COUNT = 2**63 - 1
+LONGEST_MICROSECOND_DURATION = timedelta(microseconds=MICROSECONDS_IN_COUNT)
+ONE_SECOND = timedelta(seconds=1)
+SECOND_CODE = "s"
+TIME_CODE = "us"
+
+type Operand = NDArray[Any] | ScalarValue
+"""The values of an Array, or a single value, on one side of an operation.
+
+.. versionadded:: 0.1.0
+"""
+
+
+def find_operand_type(operand: Operand) -> Type:
+	"""
+	Return the numdaplot type of the values on one side of an operation.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operand
+		The values of an Array, or a single value.
+
+	Returns
+	-------
+	Type
+		The type of the values.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.operand import find_operand_type
+	>>> find_operand_type(numpy.array([1.5]))
+	<Type.FLOAT64: 10>
+	"""
+	if isinstance(operand, numpy.ndarray):
+		array_type = from_numpy_dtype(operand.dtype)
+		return array_type
+
+	value_type = find_value_type(operand)
+
+	return value_type
+
+
+def find_operand_type_names(operands: list[Operand]) -> list[str]:
+	"""
+	Return the names of the numdaplot types of several operands, as shown in error messages.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operands
+		The values of Arrays, or single values.
+
+	Returns
+	-------
+	list[str]
+		The name of the type of each operand, in order.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.operations.operand import find_operand_type_names
+	>>> find_operand_type_names([numpy.array([1]), "euros"])
+	['INT64', 'TEXT']
+	"""
+	operand_types = [find_operand_type(operand) for operand in operands]
+	type_names = [operand_type.name for operand_type in operand_types]
+
+	return type_names
+
+
+def convert_time_value(value: ScalarValue) -> Any:
+	"""
+	Return a single value in the form numpy compares with Array values.
+
+	numpy compares a Python date with its own dates through Python objects, which fails on a missing date.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		A single value.
+
+	Returns
+	-------
+	Any
+		A ``numpy.datetime64`` for a date or a datetime, a ``numpy.timedelta64`` for a duration, in seconds when
+		microseconds cannot count it, the time since midnight in microseconds for a time of day, the value itself
+		otherwise.
+
+	Examples
+	--------
+	>>> from datetime import date
+	>>> from numdaplot.arrays.operations.operand import convert_time_value
+	>>> convert_time_value(date(2026, 1, 31))
+	np.datetime64('2026-01-31')
+	"""
+	if isinstance(value, date):
+		moment = numpy.datetime64(value)
+		return moment
+
+	if isinstance(value, time):
+		since_midnight = to_time_since_midnight(value)
+		time_of_day = numpy.timedelta64(since_midnight, TIME_CODE)
+		return time_of_day
+
+	if isinstance(value, timedelta):
+		is_too_long_for_microseconds = abs(value) > LONGEST_MICROSECOND_DURATION
+		if is_too_long_for_microseconds:
+			whole_seconds = value // ONE_SECOND
+			second_duration = numpy.timedelta64(whole_seconds, SECOND_CODE)
+			return second_duration
+
+		duration = numpy.timedelta64(value)
+		return duration
+
+	return value