๐บ๏ธ Code Map
What this page covers
This page maps the active package, experiment workspace, documentation site, and external reference code. Use it as the first stop when deciding where new implementation, notes, or generated outputs should live.
This repository is the new implementation and documentation home for the kappa-budgeting ablations. Related legacy/generated code currently lives outside this repository and should be treated as reference material.
Main Repositoryโ
| Path | Purpose |
|---|---|
enabol/ | Python package for reusable kappa-budgeting simulation code. |
workspace/ablations/ | Reproducible experiment workspaces, notebooks, configs, notes, and results. |
site/docs/ | Docusaurus documentation for methodology, experiment logs, and handoff. |
site/blog/ | Short lab-log entries for chronological updates. |
.github/workflows/deploy-docs.yml | GitHub Pages deployment for the Docusaurus site. |
Reference Code Outside This Repoโ
| Path | Purpose |
|---|---|
/Users/mbvalentin/enabol/budgeting.py | Current rail-driven kappa budget estimator used for the paper workflow. |
/Users/mbvalentin/firmware/autograd/nnet_dense_backprop.h | Generated dense backprop implementation with active column scaling and throttling, and disabled dense RowScale. |
/Users/mbvalentin/firmware/autograd/optimizers.h | Throttled SGD/Adam update implementations. |
/Users/mbvalentin/firmware/parameters.h | Generated layer configs, precision aliases, and kappa_row_log2 / kappa_col_log2 values. |
/Users/mbvalentin/firmware/defines.h | Generated fixed-point type definitions and accumulator precision. |
Workspace Conventionโ
Each ablation gets its own folder:
workspace/
ablations/
001_affine_single_dense/
config.yaml
notes.md
notebooks/
analysis.ipynb
results/
.gitkeep
002_two_layer_relu/
config.yaml
notes.md
notebooks/
analysis.ipynb
results/
.gitkeep
The recommended workflow is notebook-first, script-second:
- Use
notebooks/analysis.ipynbwhile exploring, because plots, tensor dumps, and commentary are part of the reasoning. - Keep experiment settings in
config.yaml, even when the run is launched from a notebook. - Store exported plots, CSV logs, and summaries in
results/. - Add a
run.pylater only after a notebook workflow becomes stable enough to rerun automatically.
This keeps exploration easy while preserving enough structure for handoff and reproducibility.
Python Package Shapeโ
The current enabol/ package separates concerns as follows:
enabol/
dataset.py # synthetic affine datasets and plotting/export helpers
dtypes.py # HLS-style ap_fixed/ap_ufixed/ap_int/ap_uint descriptors
precision.py # layer-indexed PrecisionDict
quantization.py # TensorFlow/NumPy quantization and rail statistics
nn/
__init__.py # public neural-network/training exports
models.py # dense models and BaseModel public entry points
controller.py # global-throttle controllers and Controller.from_str
training.py # InstrumentedTrainer online loop
optimizer.py # optimizer-style raw update rules
telemetry.py # tensor-native sensors and history recorder
applier.py # applies controller-approved updates
history.py # FitHistory container and default plots
testbench.py # hls4ml CSIM tb_data readers and plots
utils.py # norms, Hessian helpers, stability metrics
The future ๐ENABOL comparison work may add:
enabol/
budgeting.py # kappa allocation and projection policies
metrics.py # richer per-layer saturation and recovery metrics
metrics.py # additional aggregate metrics if telemetry grows too large