๐๏ธ Dtypes Module Reference
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โ
| Group | Objects | Purpose |
|---|---|---|
| Constants | VALID_QMODES, VALID_OMODES | Supported HLS-style rounding and overflow mode names. |
| Module-level helper functions | _fraction_bits, _scale, _round_by_qmode, _clip_int, _wrap_int, _quantize_np | Shared NumPy-side implementation details. |
| Base class | HLSDataType | Common parser/interface for dtype descriptors. |
| Fixed-point descriptors | ap_fixed, ap_ufixed | Signed and unsigned fixed-point formats. |
| Integer descriptors | ap_int, ap_uint | Signed 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:
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:
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:
Unsigned:
_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.
- if
return_intthen - return
- end if
- return
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,QMODEis supported,OMODEis 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:
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:
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:
Use this for integer counters or raw integer-domain tests.
ap_uintโ
Unsigned integer type. Range:
Extension Notesโ
When extending this file:
- Add NumPy behavior in
_round_by_qmode()or_quantize_np(). - Add matching TensorFlow behavior in
quantization.py. - Add
value_range()if a new dtype class is introduced. - Keep dtype objects immutable with
frozen=True. - Avoid putting experiment-specific policy in this file. This module should describe numeric formats only.