111 lines
4.8 KiB
TeX
111 lines
4.8 KiB
TeX
%% SCRAP: architecture/03-architecture/heartbeat-system/implementation-plan
|
|
%% SOURCE: docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md
|
|
%% STATUS: HISTORICAL
|
|
%% FITS: dev-guide/ch-heartbeat
|
|
%% EDITORIAL: lifted — prose rewritten to press voice
|
|
|
|
\section{Implementation Plan: Heartbeat Rate Logging}
|
|
|
|
This plan captures the \lstinline{tick_ns} trajectory---the heartbeat rate as
|
|
it actually changes during execution---so that each configuration can be
|
|
analyzed for how well it modulates heartrate in response to workload. The work
|
|
was scoped as a prerequisite to the Phase 2 DoE and touches four files.
|
|
|
|
\subsection{Data Structures}
|
|
|
|
A per-sample record and a buffer carried on the VM hold the trajectory.
|
|
|
|
\begin{lstlisting}[language=C]
|
|
#define HEARTBEAT_RATE_SAMPLE_MAX 100000
|
|
|
|
typedef struct {
|
|
uint64_t tick_number; /* absolute tick count */
|
|
uint64_t tick_ns; /* heartbeat rate (ns) */
|
|
uint64_t workload_ops_this_tick; /* dictionary lookups this tick */
|
|
uint64_t timestamp_ns; /* wall-clock timestamp */
|
|
uint64_t hot_word_count; /* physics state */
|
|
uint64_t total_heat; /* physics state */
|
|
} HeartbeatRateSample;
|
|
|
|
/* in VM */
|
|
HeartbeatRateSample *heartbeat_rate_samples;
|
|
uint64_t heartbeat_rate_sample_count;
|
|
uint64_t workload_ops_current_tick;
|
|
\end{lstlisting}
|
|
|
|
The buffer is allocated with \lstinline{calloc} in \lstinline{vm_init()} and
|
|
released in \lstinline{vm_cleanup()}.
|
|
|
|
\subsection{Capturing a Sample Per Tick}
|
|
|
|
A lightweight helper writes one sample per tick, halting once the buffer is
|
|
full so sampling never overruns its allocation.
|
|
|
|
\begin{lstlisting}[language=C]
|
|
static void capture_heartbeat_rate_sample(VM *vm, uint64_t tick_ns,
|
|
uint64_t workload_ops)
|
|
{
|
|
if (!vm || !vm->heartbeat_rate_samples) return;
|
|
if (vm->heartbeat_rate_sample_count >= HEARTBEAT_RATE_SAMPLE_MAX) return;
|
|
|
|
HeartbeatRateSample *s =
|
|
&vm->heartbeat_rate_samples[vm->heartbeat_rate_sample_count];
|
|
s->tick_number = vm->heartbeat.tick_count;
|
|
s->tick_ns = tick_ns;
|
|
s->workload_ops_this_tick = workload_ops;
|
|
s->timestamp_ns = platform_monotonic_ns();
|
|
s->hot_word_count = vm->hot_word_count_at_check;
|
|
s->total_heat = vm->total_heat_at_last_check;
|
|
vm->heartbeat_rate_sample_count++;
|
|
}
|
|
\end{lstlisting}
|
|
|
|
The interpreter increments \lstinline{workload_ops_current_tick} on each
|
|
successful dictionary lookup; \lstinline{vm_heartbeat_run_cycle()} latches and
|
|
resets that counter per tick; and \lstinline{heartbeat_thread_main()} calls the
|
|
capture helper immediately before sleeping for \lstinline{tick_ns}.
|
|
|
|
\subsection{Derived Metrics}
|
|
|
|
The DoE metrics structure gains heartrate fields covering rate statistics
|
|
(mean frequency, standard deviation, coefficient of variation, min/max
|
|
interval, modulation range), load response (correlation, response direction,
|
|
adaptation and settling latency), convergence (convergence time, a converged
|
|
flag, oscillation amplitude), and two composite scores for responsiveness and
|
|
stability.
|
|
|
|
The analysis routine \lstinline{analyze_heartbeat_rate_trajectory()} walks the
|
|
captured samples to compute these. Frequency is
|
|
$f_{\text{Hz}} = 10^{9} / \mathtt{tick\_ns}$. The coefficient of variation is
|
|
|
|
\begin{equation}
|
|
\mathrm{CV} = \frac{\sigma_{f}}{\bar{f}},
|
|
\end{equation}
|
|
|
|
and the headline figure is the Pearson correlation between per-tick workload
|
|
and heartrate. A correlation above a small positive threshold marks the
|
|
configuration as responding in the desired direction. The responsiveness score
|
|
rewards strong correlation and penalizes high CV; the stability score rewards
|
|
low CV and convergence. \Qtype{} fixed-point is used elsewhere in the runtime,
|
|
but this offline analysis runs in floating point.
|
|
|
|
\subsection{CSV Schema and Downstream Analysis}
|
|
|
|
The CSV writers gain columns for the new heartrate fields so each run emits one
|
|
augmented row. A revised R analysis then ranks configurations primarily by mean
|
|
load--heartrate correlation, blended with the responsiveness and stability
|
|
scores into a single golden score, and renders correlation and responsiveness
|
|
box plots across configurations.
|
|
|
|
\subsection{Build and Verification}
|
|
|
|
After editing \lstinline{include/vm.h}, \lstinline{include/doe_metrics.h},
|
|
\lstinline{src/vm.c}, and \lstinline{src/doe_metrics.c}, the build is
|
|
\lstinline{make clean && make fastest}. Verification confirms a clean compile,
|
|
a non-zero sample count after a run, the presence of the new CSV columns,
|
|
computed correlation metrics, and an R ranking ordered by load response.
|
|
|
|
%% TODO(bob): confirm whether this logging was implemented as written, or
|
|
%% superseded by the heartbeat_export.c / HeartbeatTickSnapshot path; the two
|
|
%% plans overlap and status should be reconciled.
|