๐ฏ PrecisionDict Module Reference
This page is a coder-facing reference for enabol/precision.py: the explicit layer-indexed PrecisionDict, reserved precision scopes, dtype parsing, model validation, hls4ml precision translation, and usage patterns for per-layer quantization studies.
This page documents the PrecisionDict API. The evolving trainable precision dependency rules live in Trainable Precision Schema, including the first known controller rule for resolving squared update telemetry in controller_metric.
Module Mapโ
| Group | Objects | Purpose |
|---|---|---|
| Constants | RESERVED_NAMES | Semantic scopes that should not be ordinary layer names. |
| Constants | STANDARD_LAYER_PRECISION_FIELDS, TRAINABLE_PRECISION_FIELDS, DEFAULT_TRAINABLE_PRECISION | hls4ml precision mapping tables and bring-up defaults. |
| Class | PrecisionDict | Explicit layer/field precision map. |
| Module-level functions | ensure_precision_dict(...), dtype_to_hls(...), apply_hls_precision_config(...) | Normalize user input and apply ENABOL precision semantics to hls4ml config dictionaries. |
Imports And Dependenciesโ
from collections.abc import Mapping
from typing import Any
import tensorflow as tf
from .dtypes import HLSDataType
The only package-level dependencies are HLSDataType and concrete dtype constructors such as ap_fixed, which parse strings and define default precision policies.
Constantsโ
RESERVED_NAMES = {"loss", "input", "__default__"}
These names are semantic precision scopes, not ordinary Keras layers.
Meaning:
| Name | Purpose |
|---|---|
input | Precision for raw input tensors. |
loss | Precision for loss value or loss-side signals. |
__default__ | Optional fallback precision fields. |
No Keras layer should be named input or loss.
hls4ml Translationโ
precision.py owns the translation from ENABOL semantic fields into hls4ml config fields. compile.py should not duplicate these maps.
Ordinary layer precision maps to hls4ml layer precision:
| ENABOL field | hls4ml field |
|---|---|
weight | Precision.weight |
bias | Precision.bias |
activation / result | Precision.result |
accumulator / accum | Precision.accum |
Trainable precision maps to explicit training fields:
| ENABOL field | hls4ml trainable field(s) |
|---|---|
loss.value | Model.Training.Precision.loss |
gradient | grad_in, grad_out, weight_grad, bias_grad, loss_grad |
update | raw_update, update, optimizer_state |
accumulator | gradient_accum, controller_metric |
| explicit trainable fields | same named hls4ml field, when recognized |
The public helper for the compile bridge is:
apply_hls_precision_config(hls_config, precision_dict)
It mutates the hls4ml config in place and fills missing model-level trainable fields from DEFAULT_TRAINABLE_PRECISION. These defaults are conservative bring-up placeholders, not the final deployment policy.
Classesโ
PrecisionDictโ
class PrecisionDict(dict[str, dict[str, HLSDataType | None]]):
...
The top-level key is a layer or semantic scope:
dense0
activation0
input
loss
The second-level key is a tensor family:
weight
bias
activation
accumulator
gradient
update
value
Example:
from enabol import dtypes, PrecisionDict
precisions = PrecisionDict({
"input": {
"value": "ap_fixed<12,4,AP_RND,AP_SAT>",
},
"dense0": {
"weight": dtypes.ap_fixed(12, 4, "AP_RND", "AP_SAT"),
"gradient": dtypes.ap_fixed(16, 6, "AP_RND", "AP_SAT"),
"update": dtypes.ap_fixed(16, 4, "AP_RND", "AP_SAT"),
},
"loss": {
"value": "ap_fixed<24,12,AP_RND,AP_SAT>",
},
})
print(precisions)
should print:
PrecisionDict(
input:
value: ap_fixed<12,4,AP_RND,AP_SAT>
dense0:
weight: ap_fixed<12,4,AP_RND,AP_SAT>
gradient: ap_fixed<16,6,AP_RND,AP_SAT>
update: ap_fixed<16,4,AP_RND,AP_SAT>
loss:
value: ap_fixed<24,12,AP_RND,AP_SAT>
)Strings and dtype objects can be mixed. None means explicitly float/no quantization.
__init__(data)โ
def __init__(self, data: Mapping[str, Mapping[str, Any]] | None = None):
...
Builds the nested dictionary and parses all dtype entries.
Input:
{
"dense0": {
"weight": "ap_fixed<12,4,AP_RND,AP_SAT>",
"bias": None,
}
}
Stored internally as:
{
"dense0": {
"weight": ap_fixed(...),
"bias": None,
}
}
_parse_dtype(dtype)โ
@staticmethod
def _parse_dtype(dtype: Any) -> HLSDataType | None:
...
Rules:
NonestaysNone,- dtype objects pass through,
- strings are parsed with
HLSDataType.from_dtype().
This is why notebook configs can be concise:
"weight": "ap_fixed<12,4,AP_RND,AP_SAT>"
dtype(layer_name, field, default=None)โ
def dtype(self, layer_name: str, field: str, default=None):
...
Main lookup method.
Lookup order:
- Exact layer and field:
precisions["dense0"]["weight"]
- Default field:
precisions["__default__"]["weight"]
- Provided default, usually
None.
Usage:
weight_t = precisions.dtype("dense0", "weight")
update_t = precisions.dtype("dense0", "update")
loss_t = precisions.dtype("loss", "value")
Missing fields default to floating point in the training loop because the returned dtype is None.
has(layer_name, field)โ
def has(self, layer_name: str, field: str) -> bool:
return self.dtype(layer_name, field) is not None
Boolean convenience method.
Usage:
if precisions.has("dense0", "update"):
...
layers()โ
def layers(self) -> list[str]:
return [name for name in self.keys() if name != "__default__"]
Returns the non-default scopes.
Example:
["input", "dense0", "loss"]
fields(layer_name)โ
def fields(self, layer_name: str) -> list[str]:
return list(self.get(layer_name, {}).keys())
Useful for debugging:
print(precisions.fields("dense0"))
validate_model(model, allow_missing=True)โ
def validate_model(self, model: tf.keras.Model, *, allow_missing: bool = True) -> None:
...
Checks that:
- No Keras layer is named
loss. - No Keras layer is named
input. - Non-reserved precision entries match model layer names.
- Optionally, every model layer has a precision entry.
Usage:
precisions.validate_model(model.model)
For ablations, keep:
allow_missing=True
because staged experiments intentionally quantize only selected paths.
Use:
allow_missing=False
only when you want a fully specified hardware-style precision map.
describe()โ
def describe(self) -> str:
...
Returns a readable multi-line summary:
print(precisions.describe())
Useful in notebooks so the exact precision map appears next to the plots.
Module-Level Functionsโ
ensure_precision_dict(precision)โ
def ensure_precision_dict(precision):
...
Accepts:
None,- an existing
PrecisionDict, - a nested mapping.
Returns either:
None, or- a
PrecisionDict.
This is used by train_instrumented() so callers can pass either:
precision_dict=precisions
or:
precision_dict={
"dense0": {
"weight": "ap_fixed<12,4,AP_RND,AP_SAT>",
},
}
Extension Notesโ
Add new fields freely when the trainer supports them:
"momentum"
"adam_m"
"adam_v"
"batchnorm_mean"
"batchnorm_variance"
The object is intentionally schema-light. Enforcement should live in the training/firmware path, not here, because different optimizers and layers require different fields.