88 lines
3.8 KiB
TeX
88 lines
3.8 KiB
TeX
%% SCRAP: architecture/getting-started/quick-start/optimization-doe
|
|
%% SOURCE: docs/working/architecture/getting-started/quick-start/optimization-doe.md
|
|
%% STATUS: CURRENT
|
|
%% FITS: cookbook/ch-doe
|
|
%% EDITORIAL: lifted — prose rewritten to press voice
|
|
|
|
\section{Quick Start: The Optimization DoE}
|
|
|
|
The Optimization DoE refines individual runtime parameters one at a time. It
|
|
runs five focused experiments --- each called an ``opportunity'' --- that test a
|
|
handful of parameter variations and report which value performs best. The full
|
|
set completes in roughly nine minutes.
|
|
|
|
\subsection{The Five Opportunities}
|
|
|
|
Each opportunity is launched with \texttt{--opportunity N} and a label; piping
|
|
an empty line past the confirmation prompt lets them run unattended.
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
echo "" | ./scripts/run_optimization_doe.sh --opportunity 1 OPP_01_DECAY_SLOPE
|
|
echo "" | ./scripts/run_optimization_doe.sh --opportunity 2 OPP_02_WINDOW_WIDTH
|
|
echo "" | ./scripts/run_optimization_doe.sh --opportunity 3 OPP_03_DECAY_RATE
|
|
echo "" | ./scripts/run_optimization_doe.sh --opportunity 4 OPP_04_WINDOW_SIZING
|
|
echo "" | ./scripts/run_optimization_doe.sh --opportunity 5 OPP_05_THRESHOLD
|
|
\end{lstlisting}
|
|
|
|
Each script tests three or four parameter variations, runs two iterations of
|
|
thirty samples per configuration (sixty samples in total), emits metrics in
|
|
\Qtype{} fixed-point integer math, and writes a CSV of results.
|
|
|
|
\subsection{Picking a Winner}
|
|
|
|
For each opportunity, the winning configuration is the one with the highest
|
|
\texttt{cache\_hit\_percent} and the lowest
|
|
\texttt{vm\_workload\_duration\_ns\_q48}. Results can be inspected directly by
|
|
sorting the CSV on the workload-duration column (lower is better) or analyzed in
|
|
R with the load-and-explore script.
|
|
|
|
\begin{lstlisting}[language=bash]
|
|
tail -n +2 .../OPP_01_DECAY_SLOPE/experiment_results.csv | \
|
|
sort -t',' -k27 -n | head -5
|
|
\end{lstlisting}
|
|
|
|
\subsection{Reading \Qtype{} Metrics}
|
|
|
|
All metrics are \Qtype{} fixed-point integers: a 48-bit integer part and a
|
|
16-bit fraction. To recover a decimal value, divide by 65536. For example, a
|
|
\texttt{vm\_workload\_duration\_ns\_q48} of $315{,}797{,}667{,}840$ corresponds
|
|
to $315{,}797{,}667{,}840 / 65536 = 4{,}822{,}021$ nanoseconds, and a
|
|
\texttt{cpu\_freq\_delta\_mhz\_q48} of $-6{,}356{,}992$ corresponds to
|
|
$-6{,}356{,}992 / 65536 = -97.07$\,MHz.
|
|
|
|
\subsection{Recommended Sequencing}
|
|
|
|
The opportunities are best run in order, reviewing results between each so that
|
|
a chosen value can be locked before moving on. Opportunities 1 through 3 each
|
|
pick and lock a single winner; opportunity 4 analyzes interactions; and
|
|
opportunity 5 applies the final refinement. The findings then aggregate into an
|
|
optimized baseline.
|
|
|
|
\begin{table}[h]
|
|
\centering
|
|
\begin{tabular}{lll}
|
|
\toprule
|
|
Opportunity & Expected impact & Expected winner \\
|
|
\midrule
|
|
\#1 Decay slope & 8--15\% & \texttt{DECAY\_SLOPE\_0.33} or \texttt{0.5} \\
|
|
\#2 Window width & 6--12\% & \texttt{WINDOW\_SIZE\_4096} or \texttt{8192} \\
|
|
\#3 Decay rate & 3--6\% & Likely \texttt{NORMAL} (baseline) \\
|
|
\#4 Window sizing & 5--8\% & Likely \texttt{WINDOW\_8K\_DECAY\_0.33} \\
|
|
\#5 Threshold & 2--4\% & Likely \texttt{THRESHOLD\_10} (baseline) \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\caption{Expected impact and likely winner per opportunity.}
|
|
\end{table}
|
|
|
|
\subsection{Troubleshooting}
|
|
|
|
\begin{itemize}
|
|
\item \emph{Hangs at the confirmation prompt} --- press Enter, or pipe an
|
|
empty line in with \texttt{echo "" |}.
|
|
\item \emph{Binary not found} --- rebuild with \texttt{make test}.
|
|
\item \emph{No CSV data} --- inspect the per-run logs in the experiment's
|
|
\texttt{run\_logs/} directory.
|
|
\end{itemize}
|
|
|
|
%% TODO(bob): source uses absolute developer paths (/home/rajames/...) and references OPTIMIZATION_DoE_GUIDE.md and OPTIMIZATION_OPPORTUNITIES.md. Confirm canonical paths for the published edition.
|