Skip to content

scripts.md

Latest commit

 

History

History
128 lines (92 loc) · 13.6 KB

scripts.md

File metadata and controls

128 lines (92 loc) · 13.6 KB
Raw

Scripts

This document describes the scripts contained in src/scripts and its subfolders. For each script we list the relative path, a verbose description of behavior, inputs/outputs, and notes on where results are written.

Summary

  • Location root: src/scripts
  • Subfolders: dynamic_selection_sims/ (orbit simulation — see also continuous_dynamic.md for the math behind the control policy), hardware_characterization/ (with plotting/), and utils/
  • Common outputs:
    • Saleae captures and raw CSVs (digital/analog) → results/captures/*/saleae_raw
    • Processed plots → results/plots or script-specific output_dir
    • Measurement CSVs (e.g., inference results) → inference_results.csv or user-specified file
    • Merged model performance map → data/compiled_characterization.json (produced by utils/characterization_ouput.py, consumed by dynamic_selection_sims/selection_case_studies.py)

hardware_characterization/

hardware_characterization/bench_mark_sweep.py

  • Purpose: Full automation of firmware build, board flash, and capture collection for EdgeTPU-compiled models.
  • Behavior: For each compiled _edgetpu.tflite model it can (optionally) build the coralmicro firmware (via CMake + Make), flash the target board using the coralmicro flashtool, and then call the Saleae Logic 2 automation API to perform a timed capture. After capture it uses the SaleaeOutputParsing helper to compute average inference time and energy metrics.
  • Inputs: model directory (--model_dir, defaults to ~/Coral-TPU-Characterization/data/models/edgeTPU_acc — a path from an earlier name of this project; pass --model_dir explicitly to point at e.g. data/models/coral_target), capture directory, serial port (--port, default /dev/ttyACM0), shunt resistance and supply voltage, build/test flags.
  • Outputs: One capture folder per run (default results/captures/<model_stem>_<timestamp>/saleae_raw) and an inference_results.csv with rows: model, avg inference time (ms), average energy per inference (J or mJ), category.
  • Notes: Relies on the saleae.automation package and a local Saleae Manager; requires correct serial port and coralmicro flashtool available on PATH.

hardware_characterization/plotting/model_stats_plotting.py

  • Purpose: Generate comparative plots across model sweeps (image classification, object detection, etc.) using Saleae-derived power/latency metrics and spreadsheet metadata.
  • Behavior: Collects measured latency/power using SaleaeOutputParsing, combines these with Excel metadata (accuracy, quoted latency), computes derived metrics (Inf/s, Inf/J, Correct Inf metrics) and produces multi-panel figures (parameter count, latency, accuracy, combined quoted vs measured plots) written to a user-specified plotdir or results/plots.
  • Inputs: Excel metadata workbook + run directories under results/captures or an explicit directory pointer.
  • Outputs: PNG plots (e.g., img_class_plot.png, img_class_combined.png) and optionally appended Excel sheets with collected/derived values.
  • Notes: Exposes ModelStatsPlotting class for programmatic use and helper functions for quick analyses (e.g., jacknet_sweep_plot).

hardware_characterization/plotting/tpunet_plotting.py

  • Purpose: Aggregate grid sweep JSON metrics and Saleae measurements for the custom Grid/TpuNet model family and produce rich plotting tools and champion-finding helpers.
  • Behavior: GridStatsPlotting loads JSON evaluation files (e.g., Grid_A0.25_D02_quant_eval.json), finds corresponding Saleae captures (searching saleae_raw locations), uses ParamCounts to attach parameter counts, derives efficiency/throughput metrics and provides several plotting methods (standard metrics, grouped metrics by alpha/depth, efficiency overviews, 3D surfaces).
  • Inputs: Directory of JSON metric files, saleae_root pointing to the base captures directory, and an output_dir for plots.
  • Outputs: Multiple PNGs (grid metrics, grouped metrics, 3D surfaces) saved under the provided output_dir.
  • Notes: Designed to be robust to missing JSONs or missing Saleae runs (will warn and skip missing entries).

hardware_characterization/model_swaps.py

  • Purpose: Parse Saleae captures produced by the model_swaps.cc firmware application (see ../model_swaps.cc) into the model-switching cost dataset used by the switching-cost case studies.
  • Behavior: Expects each capture to expose digital channels CH0 (Inference) and CH1 (Switching) and analog channels CH2/CH3/CH4 (voltage before/after shunt, VSYS). Walks a directory of per-alpha/per-depth capture subfolders (see RUN_CONFIG), computes average inference time and average model-switch energy/time per model, and writes the aggregated result to model_switching_results.json.
  • Inputs: A local directory of raw Saleae captures, one subfolder per (alpha, depth) run.
  • Outputs: model_switching_results.json at the repository root.
  • Notes: BASE_DIR and RUN_CONFIG at the top of the script are hardcoded to the author's local capture layout — edit them to point at your own capture directory and folder names before running.

dynamic_selection_sims/

dynamic_selection_sims/selection_case_studies.py

  • Purpose: Core continuous-time satellite simulation engine used by all per-orbit case studies. Implements ContinuousSatSim, whose control policy, energy budgeting, and workload model are described in detail in continuous_dynamic.md.
  • Behavior: Loads STK orbit/lighting data (via stk_utils.load_orbit_data), loads the compiled model performance map (data/compiled_characterization.json), and time-steps through an orbit computing per-frame imaging demand, a predictive energy budget (targeting a full battery at eclipse entry and a safe floor at eclipse exit), and a greedy model choice that maximizes (inferences possible) × accuracy within that budget. Also runs a naive hysteresis baseline and a static (single fixed model) baseline for comparison, and produces plots/CSVs per case study via run_case_study(...).
  • Inputs: STK CSV directory (data/stk), compiled characterization JSON, per-orbit configuration (battery capacity, solar generation, baseload, thresholds — see get_sso_config() / get_heo_config()), and optional events (transient demand/power perturbations, e.g. a data-collection burst).
  • Outputs: Per case study, writes plots and CSVs under results/case_studies/<orbit>/ (cumulative yield, delivered yield, energy margin, throughput margin, orbit dynamics, frame budgets CSV) and prints a summary to stdout.
  • Notes: Not meant to be run directly — invoked by the per-orbit case study scripts below.

dynamic_selection_sims/eLEO_Cases.py, SSO_Cases.py, HEO_Cases.py

  • Purpose: Entry-point scripts that configure and run ContinuousSatSim case studies for the equatorial-LEO, sun-synchronous, and highly-elliptical orbit regimes respectively.
  • Behavior: Each constructs a ContinuousSatSim for its orbit (sat_prefix='eLEO' | 'SSO' | 'HEO'), applies that orbit's baseline config, and calls run_case_study(...) one or more times — including some orbit-specific perturbation scenarios (e.g. a perigee data-collection burst or a power-starved perigee pass for HEO) that are commented out by default.
  • Inputs: data/compiled_characterization.json, data/stk.
  • Outputs: results/case_studies/eleo/, results/case_studies/sso/, and results/case_studies/heo/ respectively (the heo output directory does not exist yet under results/case_studies — it is created on first run).
  • Notes: Run directly, e.g. python SSO_Cases.py, from within dynamic_selection_sims/. Each script's try/except fallback to resolve ROOT_DIR references an old package path (libs.coral_tpu_characterization...) that no longer exists in this repository; the except ImportError branch (resolve relative to the current working directory) is what actually runs today.

dynamic_selection_sims/stk_utils.py

  • Purpose: Load and clean STK-exported orbit/lighting CSVs for use by ContinuousSatSim.
  • Behavior: parse_lighting_schedule() extracts sunlight start/stop intervals from an STK lighting-times export; load_orbit_data() merges the position/velocity, classical orbital elements, and LLA position exports for a given satellite prefix (e.g. SSO, HEO, eLEO) into a single DataFrame, plus an interpolate_orbit() helper for resampling onto the simulation's time step.
  • Inputs: Directory of STK CSV exports (data/stk) and a satellite prefix matching the STK filenames.
  • Outputs: A cleaned pandas DataFrame plus a list of sunlight intervals, ready for simulation.

dynamic_selection_sims/plotting_utils.py

  • Purpose: Shared plotting helpers for the case study outputs produced by selection_case_studies.py.
  • Behavior: Sets a consistent small-multiples plot style (set_plot_style()), assigns consistent per-model colors from a perceptually-uniform colormap while keeping non-compute states (idle/recharge/blind/blocked) a fixed gray (_get_model_colors()), and provides the figure-generating functions run_case_study() calls for each plot type (cumulative yield, delivered yield, energy margin, throughput margin, orbit dynamics, static-vs-dynamic comparison).
  • Inputs: The per-step decision DataFrame produced by a ContinuousSatSim run.
  • Outputs: PNG/PDF figures saved to the case study's output directory.

utils/

utils/saleae_parsing.py

  • Purpose: Core parser for Saleae Logic 2 raw CSV outputs (digital and analog channels).
  • Behavior: SaleaeOutputParsing locates digital.csv and analog.csv (in saleae_raw folders), extracts rising/falling edge times, computes average inference time, average power and energy per inference (with optional idle subtraction), and provides plotting helpers such as plot_saleae_trace() for diagnostics.
  • Inputs: Directory containing digital.csv and analog.csv; parameters for PSU voltage and shunt resistance.
  • Outputs: Programmatic metrics (avg inference time [s], avg power [W], energy per inference [J]) and optional diagnostic PNGs.
  • Notes: Saves/loads computed idle power at results/captures/idle_power/idle.csv to allow subtracting idle consumption across runs.

utils/ParamCounts.py

  • Purpose: Count model parameters from .tflite files using FlatBuffers and the TFLite schema.
  • Behavior: Walks a provided directory, loads each .tflite model, inspects buffers and tensor types, and calculates total parameter count (raw element counts) while handling different tensor data types (float32, int8, etc.).
  • Inputs: Directory root to scan for .tflite files.
  • Outputs: A tuple (list_of_counts, dict_name_to_count) and optionally a param_counts.json when run directly in a script context.
  • Notes: Intended for CPU .tflite models — when using EdgeTPU compiled models, parameter arrays may differ or be fused; interpret with care.

utils/model_data_manager.py

  • Purpose: Produce a clean, merged DataFrame combining Excel metadata (accuracies, quoted latencies) with Saleae-collected measurements for downstream plotting or simulations.
  • Behavior: ModelDataManager scans a results/captures-like directory for Saleae runs, loads the referenced Excel sheet (Img_Class by default), aligns measured runs with metadata, coalesces measured vs quoted accuracy, drops invalid rows, and computes derived metrics (Inf_per_Sec, Inf_per_Joule, Correct_Inf_per_Sec, Correct_Inf_per_Joule).
  • Inputs: Path to Excel workbook and results directory containing Saleae captures.
  • Outputs: A tidy pandas DataFrame ready for plotting or simulation.

utils/characterization_ouput.py

  • Purpose: Build data/compiled_characterization.json — the single merged dataset (pretrained + custom models) that selection_case_studies.py reads as its model performance map.
  • Behavior: Defines its own ModelDataManager (a variant of the one in model_data_manager.py) to compile pretrained-model Saleae/Excel data, uses GridStatsPlotting (from hardware_characterization/plotting/tpunet_plotting.py) to compile the custom Grid/TpuNet models, unifies both into a common schema (Model name, inference time, energy per inference, accuracy, Source), drops rows with missing numeric data, and writes the result as JSON via generate_unified_dataset(...).
  • Inputs: Excel metadata workbook, pretrained-model Saleae capture directory, custom-model JSON directory (data/tpunet_acc), custom-model Saleae capture directory.
  • Outputs: data/compiled_characterization.json.
  • Notes: The __main__ block hardcodes the author's local absolute paths (under ~/CoralGUI/...) for the Excel workbook and Saleae capture directories — treat it as a template and edit those paths (or call generate_unified_dataset() directly with your own paths) rather than running it as-is. The filename keeps its original spelling (ouput).

utils/path_utils.py

  • Purpose: Locate the repository root and provide a single canonical method to build absolute paths within scripts.
  • Behavior: get_repo_root() prefers the CORAL_REPO environment variable if set, then climbs parent directories from the calling file location looking for a .git directory or a sibling libs/ + results/ pair, then falls back to a few hardcoded personal directory names from earlier iterations of this project. In a normal git checkout the .git marker always matches first, so the legacy fallbacks are effectively dead code.
  • Inputs: None (auto-detects from file location); optional env var CORAL_REPO can set path explicitly.
  • Outputs: pathlib.Path pointing to the repository root.
  • Notes: This function is used widely in scripts to build paths independent of the current working directory.