Skip to main content

๐Ÿ—„๏ธ Dtypes Module Reference

Status:ValidIn progress
Tags:ImplementationDtypesPrecision
Last modified:

What this page covers

This page is a coder-facing reference for enabol/dtypes.py: HLS-style numeric descriptors, NumPy quantization behavior, rounding modes, overflow modes, and extension points for future precision experiments.

Module Mapโ€‹

GroupObjectsPurpose
ConstantsVALID_QMODES, VALID_OMODESSupported HLS-style rounding and overflow mode names.
Module-level helper functions_fraction_bits, _scale, _round_by_qmode, _clip_int, _wrap_int, _quantize_npShared NumPy-side implementation details.
Base classHLSDataTypeCommon parser/interface for dtype descriptors.
Fixed-point descriptorsap_fixed, ap_ufixedSigned and unsigned fixed-point formats.
Integer descriptorsap_int, ap_uintSigned and unsigned integer formats.

TensorFlow fake quantization lives in enabol/quantization.py.

Constantsโ€‹

VALID_QMODESโ€‹

VALID_QMODES = {
"AP_RND",
"AP_TRN",
"AP_RND_CONV",
"AP_RND_ZERO",
"AP_RND_MIN_INF",
"AP_RND_INF",
}

Supported rounding modes. These names mirror HLS ap_fixed conventions.

VALID_OMODESโ€‹

VALID_OMODES = {
"AP_WRAP",
"AP_SAT",
"AP_SAT_ZERO",
"AP_SAT_SYM",
}

Supported overflow modes. The first quantization ablations should use AP_SAT because saturation is easier to interpret than wraparound.

Module-Level Helper Functionsโ€‹

These helpers are internal but important if you need to extend dtype behavior.

_fraction_bits(WL, IWL)โ€‹

def _fraction_bits(WL: int, IWL: int) -> int:
return max(WL - IWL, 0)

Computes:

F=WLโˆ’IWL.F = WL - IWL.

If IWL >= WL, the type has no fractional bits.

_scale(F)โ€‹

def _scale(F: int) -> float:
return float(1 << F) if F > 0 else 1.0

Returns:

2F.2^F.

Used to move between real values and integer fixed-point storage.

_round_by_qmode(x_scaled, qmode)โ€‹

def _round_by_qmode(x_scaled: np.ndarray, qmode: str) -> np.ndarray:
...

Applies the selected HLS-style rounding mode in the scaled integer domain.

Examples:

AP_TRN -> truncate toward zero
AP_RND -> NumPy round-to-nearest
AP_RND_CONV -> same as NumPy rint / banker rounding
AP_RND_ZERO -> ties toward zero

If a new rounding mode is needed, add it here and mirror it in quantization.py for TensorFlow tensors.

_clip_int(v, WL, signed)โ€‹

def _clip_int(v: np.ndarray, WL: int, signed: bool) -> np.ndarray:
...

Clips integer-domain values to the representable integer range.

Signed:

[โˆ’2WLโˆ’1,2WLโˆ’1โˆ’1].[-2^{WL-1}, 2^{WL-1}-1].

Unsigned:

[0,2WLโˆ’1].[0, 2^{WL}-1].

_wrap_int(v, WL, signed)โ€‹

def _wrap_int(v: np.ndarray, WL: int, signed: bool) -> np.ndarray:
...

Applies modulo wraparound in the integer domain. For signed types, values above the sign bit are interpreted as negative two's-complement values.

_quantize_np(...)โ€‹

def _quantize_np(
value,
WL,
IWL,
QMODE,
OMODE,
*,
signed,
return_int=False,
):
...

Shared NumPy quantization backend.

Algorithm: NumPyFixedPointQuantize
  1. xโ†asarrayโก(value,float)x \leftarrow \operatorname{asarray}(\texttt{value}, \texttt{float})
  2. Fโ†WLโˆ’IWLF \leftarrow WL - IWL
  3. xsโ†xโ‹…2Fx_s \leftarrow x \cdot 2^F
  4. zโ†roundโกQMODE(xs)z \leftarrow \operatorname{round}_{QMODE}(x_s)
  5. zqโ†overflowโกOMODE(z,WL,signed)z_q \leftarrow \operatorname{overflow}_{OMODE}(z, WL, \texttt{signed})
  6. if return_int then
  7. return zqz_q
  8. end if
  9. return zq/2Fz_q / 2^F
This is the NumPy reference path used by dtype objects such as ap_fixed(...).

Usage through a dtype object:

t = dtypes.ap_fixed(8, 3, "AP_RND", "AP_SAT")
real_values = t([0.1, 0.2, 12.0])
raw_ints = t([0.1, 0.2, 12.0], return_int=True)

Classesโ€‹

HLSDataTypeโ€‹

@dataclass(frozen=True)
class HLSDataType(ABC):
dtype: str = field(init=False)

Abstract base class for all dtype descriptors.

from_dtype(dtype, **kwargs)โ€‹

@staticmethod
def from_dtype(dtype: Any, **kwargs) -> "HLSDataType":
...

Factory method. Accepts either an existing dtype object or an HLS-style string.

Examples:

from enabol.dtypes import HLSDataType

t0 = HLSDataType.from_dtype("ap_fixed<12,4,AP_RND,AP_SAT>")
t1 = HLSDataType.from_dtype("ap_ufixed<10,3>")
t2 = HLSDataType.from_dtype("ap_int<16>")

Used by PrecisionDict, so YAML/string configs can become dtype objects automatically.

Abstract Methodsโ€‹

Every dtype must implement:

value_range()
double_precision()
signed()
unsigned()
__call__(value, return_int=False)

These methods let the rest of the package query rails, construct related dtypes, and quantize values without caring about the concrete dtype class.

ap_fixedโ€‹

@dataclass(frozen=True)
class ap_fixed(HLSDataType):
WL: int = 16
IWL: int = 6
QMODE: str = "AP_TRN"
OMODE: str = "AP_WRAP"
SAT_BITS: int = 0

Signed fixed-point type.

__post_init__()โ€‹

Validates:

  • IWL <= WL,
  • QMODE is supported,
  • OMODE is supported.

fractional_bitsโ€‹

@property
def fractional_bits(self) -> int:
return WL - IWL

quantumโ€‹

@property
def quantum(self) -> float:
return 2.0 ** (-self.fractional_bits)

This is the minimum representable spacing.

value_range()โ€‹

def value_range(self) -> Tuple[float, float]:
...

Returns:

[โˆ’2IWLโˆ’1,2IWLโˆ’1โˆ’2โˆ’F].[-2^{IWL-1}, 2^{IWL-1}-2^{-F}].

double_precision()โ€‹

Returns a wider signed fixed-point dtype with doubled word length and integer length.

signed() and unsigned()โ€‹

signed() returns itself. unsigned() returns the corresponding ap_ufixed.

__call__(value, return_int=False)โ€‹

Quantizes NumPy-compatible values.

t = dtypes.ap_fixed(12, 4, "AP_RND", "AP_SAT")
xq = t([0.1, 0.2, 32.0])

ap_ufixedโ€‹

Unsigned fixed-point type. Same fields as ap_fixed, but the range is:

[0,2IWLโˆ’2โˆ’F].[0, 2^{IWL}-2^{-F}].

Use this for nonnegative values such as ReLU activations when the sign bit is not needed.

Example:

act_t = dtypes.ap_ufixed(10, 4, "AP_RND", "AP_SAT")

ap_intโ€‹

@dataclass(frozen=True)
class ap_int(HLSDataType):
WL: int = 16

Signed integer type. Range:

[โˆ’2WLโˆ’1,2WLโˆ’1โˆ’1].[-2^{WL-1}, 2^{WL-1}-1].

Use this for integer counters or raw integer-domain tests.

ap_uintโ€‹

Unsigned integer type. Range:

[0,2WLโˆ’1].[0, 2^{WL}-1].

Extension Notesโ€‹

When extending this file:

  1. Add NumPy behavior in _round_by_qmode() or _quantize_np().
  2. Add matching TensorFlow behavior in quantization.py.
  3. Add value_range() if a new dtype class is introduced.
  4. Keep dtype objects immutable with frozen=True.
  5. Avoid putting experiment-specific policy in this file. This module should describe numeric formats only.