Refined the PDF layout for Appendix B (appendix_data.qmd) (#1831)

Author: hzeljko

book/quarto/contents/vol1/backmatter/appendix_data.qmd

@@ -185,12 +185,12 @@ Even after data arrives at the machine, we face one final hurdle: the serializat
 [^fn-serialization]: **Serialization**: From Latin *serialis* (forming a series). The process of converting in-memory data structures into a byte stream for storage or transmission, and the reverse (*deserialization*). In ML pipelines, the choice of serialization format can dominate end-to-end training time; @sec-data-engineering covers pipeline design strategies that minimize this overhead.
 
 | **Format**        |                           **Decoding Speed (MB/s)** |                    **Relative CPU Decode Cost** | **Suitability**     |
-|:------------------|----------------------------------------------------:|------------------------------------------------:|:--------------------|
+|:------------------|:---------------------------------------------------:|:-----------------------------------------------:|:--------------------|
 | **CSV/JSON**      |     `{python} SerializationCost.csv_speed_mb_s_str` |     `{python} SerializationCost.csv_cycles_str` | Debugging only      |
 | **Protobuf**      |   `{python} SerializationCost.proto_speed_mb_s_str` |   `{python} SerializationCost.proto_cycles_str` | RPC/Messages        |
 | **Parquet/Arrow** | `{python} SerializationCost.parquet_speed_mb_s_str` | `{python} SerializationCost.parquet_cycles_str` | High-Scale Training |
 
-: **Serialization Overhead**: Zero-copy formats like Arrow are at least 10$\times$ faster than row-based text formats in this representative comparison because they align directly with internal memory structures. {#tbl-serialization-cost tbl-colwidths="[25,25,25,25]"}
+: **Serialization Overhead**: Zero-copy formats like Arrow are at least 10$\times$ faster than row-based text formats in this representative comparison because they align directly with internal memory structures. {#tbl-serialization-cost tbl-colwidths="[21,27,27,25]"}
 
 ### Row vs. columnar formats {#sec-appdx-data-foundations-row-vs-columnar-formats-bca2}
 
@@ -546,40 +546,54 @@ class KLDrift:
     Pt_vec_str = MarkdownStr(f"[{Pt_fmt[0]}, {Pt_fmt[1]}, {Pt_fmt[2]}]")
 
     # Renamed from kl_pq_formula → kl_pq_eq (canonical _eq suffix for fmt_math expression)
-    kl_pq_eq = fmt_math(
+    kl_pq_eq = (
+        "\\begin{gather*}\n"
         f"\\mathcal{{D}}_{{\\text{{KL}}}}(P_0 \\lVert P_t) = {P0_fmt[0]} \\log\\frac{{{P0_fmt[0]}}}{{{Pt_fmt[0]}}} "
         f"+ {P0_fmt[1]} \\log\\frac{{{P0_fmt[1]}}}{{{Pt_fmt[1]}}} "
         f"+ {P0_fmt[2]} \\log\\frac{{{P0_fmt[2]}}}{{{Pt_fmt[2]}}}"
+        "\\end{gather*}"
     )
     # Renamed from kl_pq_calc → kl_pq_calc_eq
-    kl_pq_calc_eq = fmt_math(
+    kl_pq_calc_eq = (
+        "\\begin{gather*}\n"
         f"= {P0_fmt[0]} \\times {lr_fmt[0]} "
         f"+ {P0_fmt[1]} \\times ({lr_fmt[1]}) "
         f"+ {P0_fmt[2]} \\times ({lr_fmt[2]}) "
+        "\\\\[-1pt]\n"
         f"= {kl_pq_t_fmt[0]} + ({kl_pq_t_fmt[1]}) + ({kl_pq_t_fmt[2]}) "
-        f"= {kl_pq_str}"
+        f"= {kl_pq_str}\\text{{ nats}}"
+        "\\end{gather*}"
     )
     # Renamed from kl_qp_formula → kl_qp_eq
-    kl_qp_eq = fmt_math(
+    kl_qp_eq = (
+        "\\begin{gather*}\n"
         f"\\mathcal{{D}}_{{\\text{{KL}}}}(P_t \\lVert P_0) = {Pt_fmt[0]} \\log\\frac{{{Pt_fmt[0]}}}{{{P0_fmt[0]}}} "
         f"+ {Pt_fmt[1]} \\log\\frac{{{Pt_fmt[1]}}}{{{P0_fmt[1]}}} "
         f"+ {Pt_fmt[2]} \\log\\frac{{{Pt_fmt[2]}}}{{{P0_fmt[2]}}}"
+        "\\end{gather*}"
     )
     # Renamed from kl_qp_calc → kl_qp_calc_eq
-    kl_qp_calc_eq = fmt_math(
+    kl_qp_calc_eq = (
+        "\\begin{gather*}\n"
         f"= {Pt_fmt[0]} \\times ({-lr[0]:.4f}) "
         f"+ {Pt_fmt[1]} \\times ({-lr[1]:.4f}) "
         f"+ {Pt_fmt[2]} \\times ({-lr[2]:.4f}) "
+        "\\\\[-1pt]\n"
         f"= {kl_qp_t_fmt[0]} + {kl_qp_t_fmt[1]} + {kl_qp_t_fmt[2]} "
-        f"= {kl_qp_str}"
+        f"= {kl_qp_str}\\text{{ nats}}"
+        "\\end{gather*}"
     )
-    psi_eq = fmt_math(
-        f"\\text{{PSI}} = \\sum (P_{{0,i}} - P_{{t,i}}) \\log\\frac{{P_{{0,i}}}}{{P_{{t,i}}}} "
+    psi_eq = (
+        "\\begin{gather*}\n"
+        f"\\text{{PSI}} = \\sum (P_{{0,i}} - P_{{t,i}}) "
+        f"\\log\\frac{{P_{{0,i}}}}{{P_{{t,i}}}} "
         f"= ({diff_fmt[0]})({lr_fmt[0]}) "
         f"+ ({diff_fmt[1]})({lr_fmt[1]}) "
         f"+ ({diff_fmt[2]})({lr_fmt[2]}) "
+        "\\\\[-1pt]\n"
         f"= {psi_t_fmt[0]} + {psi_t_fmt[1]} + {psi_t_fmt[2]} "
-        f"= {psi_str}"
+        f"= {psi_str}\n"
+        "\\end{gather*}"
     )
 ```
 
@@ -588,19 +602,27 @@ class KLDrift:
 **Scenario**: A sentiment classifier was trained on data where `{python} KLDrift.scenario_str`.
 
 Training distribution $P_0$: `{python} KLDrift.P0_vec_str`. Serving distribution $P_t$: `{python} KLDrift.Pt_vec_str`.
-
-`{python} KLDrift.kl_qp_eq`
-
-`{python} KLDrift.kl_qp_calc_eq` nats
-
-`{python} KLDrift.kl_pq_eq`
-
-`{python} KLDrift.kl_pq_calc_eq` nats
+```{python}
+#| echo: false
+#| output: asis
+print(r"\vspace{-4mm}")
+print(KLDrift.kl_qp_eq)
+print(r"\vspace{-6mm}")
+print(KLDrift.kl_qp_calc_eq)
+print(r"\vspace{-4mm}")
+print(KLDrift.kl_pq_eq)
+print(r"\vspace{-6mm}")
+print(KLDrift.kl_pq_calc_eq)
+```
 
 Notice the asymmetry: $\mathcal{D}_{\text{KL}}(P_0 \lVert P_t) \neq \mathcal{D}_{\text{KL}}(P_t \lVert P_0)$. The Population Stability Index (PSI) symmetrizes this:
-
-`{python} KLDrift.psi_eq`
-
+```{python}
+#| echo: false
+#| output: asis
+print(r"\vspace{-4mm}")
+print(KLDrift.psi_eq)
+```
+ 
 ```{python}
 #| echo: false
 #| label: psi-threshold
@@ -662,12 +684,11 @@ class LogitOverflowExample:
 Neural networks output *logits*[^fn-logit] (unnormalized scores), not probabilities. We convert them using Softmax:
 
 [^fn-logit]: **Logit**: From *log* + *unit*, coined by Joseph Berkson in 1944. The logit function is the inverse of the logistic (sigmoid) function: $\text{logit}(p) = \log(p/(1-p))$. In deep learning, "logits" refers more loosely to the raw, unnormalized output of the final linear layer before any activation function is applied.
-
 $$ \text{Softmax}(z_i) = \frac{e^{z_i}}{\sum e^{z_j}} $$
 
-The problem is that if $z_i$ is large (for example, `{python} LogitOverflowExample.logit_val_str`), the exponential $e^{z_i}$ overflows common training and inference formats such as FP32, BF16, and FP16. FP64 can represent this specific value, but production ML kernels rarely use FP64 for softmax. The solution is to compute in log-space: the "Log-Sum-Exp" trick allows us to compute $\log(\sum e^{z_j})$ without ever calculating the massive exponentials directly, preserving numerical precision.[^fn-logsumexp]
+The problem is that if $z_i$ is large (for example, `{python} LogitOverflowExample.logit_val_str`), the exponential $e^{z_i}$ overflows common training and inference formats such as FP32, BF16, and FP16. FP64 can represent this specific value, but production ML kernels rarely use FP64 for softmax. The solution is to compute in log-space: the "Log-Sum-Exp" trick allows us to compute $\log\left(\sum e^{z_j}\right)$ without ever calculating the massive exponentials directly, preserving numerical precision.[^fn-logsumexp]
 
-[^fn-logsumexp]: **Log-Sum-Exp**: Implemented as `torch.logsumexp` in PyTorch and `scipy.special.logsumexp` in SciPy. It relies on the identity $\log(\sum e^{x_i}) = a + \log(\sum e^{x_i - a})$, where $a = \max(x_i)$. Shifted values $x_i - a$ are $\le 0$, ensuring exponentials never overflow.
+[^fn-logsumexp]: **Log-Sum-Exp**: Implemented as `torch.logsumexp` in PyTorch and `scipy.special.logsumexp` in SciPy. It relies on the identity $\log\left(\sum e^{x_i}\right) = a + \log\left(\sum e^{x_i - a}\right)$, where $a = \max(x_i)$. Shifted values $x_i - a$ are $\le 0$, ensuring exponentials never overflow.
 
 A small softmax calculation shows why this trick matters in practice, even for large but realistic logit values:
 
@@ -778,16 +799,18 @@ class LogSumExp:
 **The setup**: A three-class classifier outputs logits $z =$ `{python} LogSumExp.z_math`.
 
 **Without the trick (naive softmax)**:
-
-`{python} LogSumExp.naive_exp0_eq`, `{python} LogSumExp.naive_exp1_eq`, `{python} LogSumExp.naive_exp2_eq`
+$$
+\text{`{python} LogSumExp.naive_exp0_eq`},\quad \text{`{python} LogSumExp.naive_exp1_eq`}, \quad \text{`{python} LogSumExp.naive_exp2_eq`}
+$$
 
 These numbers are representable in FP64 but overflow FP32 (max $\approx 3.4 \times 10^{38}$). With FP16 (max $\approx 65{,}504$), even $e^{12}$ overflows. In practice, logits of magnitude 100 are not unusual in deep networks, and FP16/BF16 is the standard training precision—so naive softmax fails routinely.
 
 **With the trick**: Subtract $a = \max(z) =$ `{python} LogSumExp.a_str`:
-
-$z - a =$ `{python} LogSumExp.shifted_math`
-
-`{python} LogSumExp.stable_exp0_eq`, `{python} LogSumExp.stable_exp1_eq`, `{python} LogSumExp.stable_exp2_eq`
+\begin{gather*}
+\text{$z - a =$ `{python} LogSumExp.shifted_math`}
+\\
+\text{`{python} LogSumExp.stable_exp0_eq`,}\quad \text{`{python} LogSumExp.stable_exp1_eq`,}\quad \text{`{python} LogSumExp.stable_exp2_eq`}
+\end{gather*}
 
 Sum = `{python} LogSumExp.sum_str`. LogSumExp = `{python} LogSumExp.a_str` `{python} LogSumExp.log_sum_eq`.