Skip to main content

๐Ÿ—บ๏ธ Code Map

Status:Preliminary
Tags:UnassignedPlaceholderImplementation
Last modified:

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

PathPurpose
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.ymlGitHub Pages deployment for the Docusaurus site.

Reference Code Outside This Repoโ€‹

PathPurpose
/Users/mbvalentin/enabol/budgeting.pyCurrent rail-driven kappa budget estimator used for the paper workflow.
/Users/mbvalentin/firmware/autograd/nnet_dense_backprop.hGenerated dense backprop implementation with active column scaling and throttling, and disabled dense RowScale.
/Users/mbvalentin/firmware/autograd/optimizers.hThrottled SGD/Adam update implementations.
/Users/mbvalentin/firmware/parameters.hGenerated layer configs, precision aliases, and kappa_row_log2 / kappa_col_log2 values.
/Users/mbvalentin/firmware/defines.hGenerated 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.ipynb while 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.py later 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