Skip to main content

๐ŸŽฏ PrecisionDict Module Reference

Status:ValidIn progress
Tags:ImplementationPrecisionQuantization
Last modified:

What this page covers

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.

Precision relationship rules

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โ€‹

GroupObjectsPurpose
ConstantsRESERVED_NAMESSemantic scopes that should not be ordinary layer names.
ConstantsSTANDARD_LAYER_PRECISION_FIELDS, TRAINABLE_PRECISION_FIELDS, DEFAULT_TRAINABLE_PRECISIONhls4ml precision mapping tables and bring-up defaults.
ClassPrecisionDictExplicit layer/field precision map.
Module-level functionsensure_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:

NamePurpose
inputPrecision for raw input tensors.
lossPrecision 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 fieldhls4ml field
weightPrecision.weight
biasPrecision.bias
activation / resultPrecision.result
accumulator / accumPrecision.accum

Trainable precision maps to explicit training fields:

ENABOL fieldhls4ml trainable field(s)
loss.valueModel.Training.Precision.loss
gradientgrad_in, grad_out, weight_grad, bias_grad, loss_grad
updateraw_update, update, optimizer_state
accumulatorgradient_accum, controller_metric
explicit trainable fieldssame 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:

precision map
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:

  • None stays None,
  • 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:

  1. Exact layer and field:
precisions["dense0"]["weight"]
  1. Default field:
precisions["__default__"]["weight"]
  1. 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:

  1. No Keras layer is named loss.
  2. No Keras layer is named input.
  3. Non-reserved precision entries match model layer names.
  4. 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.