Livt.ML

src/numeric/ScheduledRequantizeUInt8.lvt

namespace Livt.ML.Numeric

using Livt.Math.Arithmetic

/**
 * Runtime division is scheduled; completion latency increases with work.
 * Serialize operations and keep inputs stable until the call or handshake completes.
 *
 * Provides ONNX-compatible rational requantization into unsigned int8 range.
 *
 * The multiplier and divisor must be non-negative, and their product must fit
 * in a signed Livt int. Division rounds to nearest with exact ties going to
 * the even result. Invalid scale parameters return the clamped zero point.
 */
component ScheduledRequantizeUInt8
{
	// Owned divider; calls complete before this component advances.
	divider: IntegerDivision<32>

	/**
	 * Owns the scheduled arithmetic worker; serialize public operations.
	 */
	new()
	{
		divider = new IntegerDivision<32>()
	}

	/**
	 * Computes round(value * multiplier / divisor) plus outputZeroPoint.
	 */
	public fn ApplyRational(
		value: int,
		multiplier: int,
		divisor: int,
		outputZeroPoint: int) int
	{
		if (multiplier < 0) {
			return this.Clamp(outputZeroPoint)
		}

		if (divisor <= 0) {
			return this.Clamp(outputZeroPoint)
		}

		var negative = value < 0
		var magnitude = value

		if (negative) {
			magnitude = 0 - value
		}

		// Splitting the value before multiplication avoids int32 overflow.
		divider.Compute(magnitude, divisor)
		var whole = divider.GetQuotient() * multiplier
		var remainder = divider.GetRemainder()
		var remainderProduct = remainder * multiplier
		divider.Compute(remainderProduct, divisor)
		var fraction = divider.GetQuotient()
		var fractionRemainder = divider.GetRemainder()
		var roundedMagnitude = whole + fraction
		var doubledRemainder = fractionRemainder * 2

		if (doubledRemainder > divisor) {
			roundedMagnitude++
		}

		if (doubledRemainder == divisor) {
			var parity = roundedMagnitude % 2

			if (parity != 0) {
				roundedMagnitude++
			}
		}

		var rounded = roundedMagnitude

		if (negative) {
			rounded = 0 - roundedMagnitude
		}

		var shifted = rounded + outputZeroPoint
		return this.Clamp(shifted)
	}

	/**
	 * Clamps one integer to the ONNX uint8 tensor range.
	 */
	public fn Clamp(value: int) int
	{
		if (value < 0) {
			return 0
		}

		if (value > 255) {
			return 255
		}

		return value
	}
}