use crate::audit;
use crate::{analysis, clock, entropy, log};
use std::collections::BTreeMap;
use std::fs;
use std::hint::black_box;
use std::io;
use std::path::{Path, PathBuf};
pub const DEFAULT_TITLE: &str = "Radiation monitor";
pub const RANDOM_TITLE: &str = "Where the random comes from";
const VERSION: &str = env!("CARGO_PKG_VERSION");
const HOMEPAGE: &str = "https://github.com/vonglurt/radbeeper";
const TAGLINE: &str = "A GQ GMC Geiger-Muller counter on the desk";
const ENTROPY_BITS: i64 = entropy::ENTROPY_BITS as i64;
const SHOTS: [&str; 9] = [
"probe", "watch", "watch-filling", "watch-spectrum", "watch-plain",
"log-output", "log-tabs", "commands", "watch-20s",
];
fn f(places: usize, v: f64) -> String {
format!("{:.*}", places, v)
}
fn commas(n: i64) -> String {
let digits = n.unsigned_abs().to_string();
let mut out = String::new();
for (i, ch) in digits.chars().enumerate() {
if i > 0 && (digits.len() - i) % 3 == 0 {
out.push(',');
}
out.push(ch);
}
if n < 0 {
format!("-{}", out)
} else {
out
}
}
fn e0(v: f64) -> String {
let s = format!("{:.0e}", v);
match s.split_once('e') {
Some((m, e)) => {
let exp: i32 = e.parse().unwrap_or(0);
format!("{}e{}{:02}", m, if exp < 0 { '-' } else { '+' }, exp.abs())
}
None => s,
}
}
fn pymax(a: f64, b: f64) -> f64 {
if b > a {
b
} else {
a
}
}
fn pow(x: f64, y: f64) -> f64 {
black_box(x).powf(black_box(y))
}
fn log_2(x: f64) -> f64 {
x.ln() / 2.0f64.ln()
}
fn py_sum(values: impl Iterator<Item = f64>) -> f64 {
let (mut hi, mut lo) = (0.0f64, 0.0f64);
for x in values {
let t = hi + x;
if hi.abs() >= x.abs() {
lo += (hi - t) + x;
} else {
lo += (x - t) + hi;
}
hi = t;
}
if lo != 0.0 && lo.is_finite() {
hi + lo
} else {
hi
}
}
fn factorial(k: u32) -> f64 {
(1..=k as u64).product::<u64>() as f64
}
fn poisson_pmf(lam: f64, k: u32) -> f64 {
(-lam).exp() * pow(lam, k as f64) / factorial(k)
}
fn int_cell(s: &str) -> Option<i64> {
s.trim().parse().ok()
}
fn float_cell(s: &str) -> Option<f64> {
s.trim().parse().ok()
}
fn abspath(p: &str) -> String {
let joined = if p.starts_with('/') {
p.to_string()
} else {
let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("/"));
join(&cwd.to_string_lossy(), p)
};
let mut parts: Vec<&str> = Vec::new();
for part in joined.split('/') {
match part {
"" | "." => {}
".." => {
parts.pop();
}
other => parts.push(other),
}
}
format!("/{}", parts.join("/"))
}
fn join(a: &str, b: &str) -> String {
if b.starts_with('/') || a.is_empty() {
b.to_string()
} else if a.ends_with('/') {
format!("{}{}", a, b)
} else {
format!("{}/{}", a, b)
}
}
fn dirname(p: &str) -> String {
match p.rfind('/') {
Some(i) => {
let head = &p[..=i];
let trimmed = head.trim_end_matches('/');
if trimmed.is_empty() {
head.to_string()
} else {
trimmed.to_string()
}
}
None => String::new(),
}
}
fn basename(p: &str) -> &str {
match p.rfind('/') {
Some(i) => &p[i + 1..],
None => p,
}
}
fn relpath(path: &str, start: &str) -> String {
let s = abspath(start);
let p = abspath(path);
let sl: Vec<&str> = s.split('/').filter(|x| !x.is_empty()).collect();
let pl: Vec<&str> = p.split('/').filter(|x| !x.is_empty()).collect();
let common = sl.iter().zip(pl.iter()).take_while(|(a, b)| a == b).count();
let mut rel: Vec<&str> = vec![".."; sl.len() - common];
rel.extend(&pl[common..]);
if rel.is_empty() {
".".to_string()
} else {
rel.join("/")
}
}
fn path_str(p: &Path) -> String {
p.to_string_lossy().into_owned()
}
pub fn now() -> f64 {
std::env::var("SOURCE_DATE_EPOCH")
.ok()
.and_then(|v| v.trim().parse::<f64>().ok())
.unwrap_or_else(clock::now)
}
#[derive(Default)]
pub struct Day {
pub rows: u64,
pub counts: i64,
pub seconds: f64,
pub peak: Option<f64>,
}
#[derive(Default)]
pub struct Hour {
pub counts: i64,
pub seconds: f64,
pub peak: Option<f64>,
}
#[derive(Default)]
pub struct Counter {
pub serial: String,
pub rows: u64,
pub counts: i64,
pub seconds: f64,
pub first: Option<f64>,
pub last: Option<f64>,
pub peak: Option<f64>,
pub days: BTreeMap<String, Day>,
pub hours: BTreeMap<i64, Hour>,
pub latest: Vec<(f64, Vec<String>)>,
pub cpm: f64,
pub usvh: f64,
pub links: Vec<(String, String)>,
}
fn raise(slot: &mut Option<f64>, v: Option<f64>) {
if let Some(p) = v {
if slot.map(|s| p > s).unwrap_or(true) {
*slot = Some(p);
}
}
}
const PAGE_COLUMNS: [&str; 12] = [
"time", "cps", "counts", "seconds", "cpm_3", "cpm_30", "cpm_300",
"peak_3", "peak_30", "peak_300", "src", "site",
];
fn read_rows(path: &Path) -> Vec<(f64, Vec<String>)> {
let text = match fs::read_to_string(path) {
Ok(t) => t,
Err(_) => return Vec::new(),
};
let page: Vec<String> = PAGE_COLUMNS.iter().map(|s| s.to_string()).collect();
let mut names = page.clone();
let mut out = Vec::new();
for line in text.lines() {
if line.starts_with('#') {
let found = log::columns(line);
if !found.is_empty() {
names = found;
}
continue;
}
if let Some(when) = log::row_time(line) {
let cells: Vec<&str> = line.split('\t').collect();
out.push((when, log::align_row(&cells, &names, &page)));
}
}
out
}
pub fn summarise(directory: &Path, cpm_per_usvh: f64) -> BTreeMap<String, Counter> {
let mut counters: BTreeMap<String, Counter> = BTreeMap::new();
for (serial, path) in log::files(directory) {
let c = counters.entry(serial.clone()).or_insert_with(|| Counter {
serial: serial.clone(),
..Counter::default()
});
for (when, cells) in read_rows(&path) {
let (counts, seconds) = match (
cells.get(2).and_then(|s| int_cell(s)),
cells.get(3).and_then(|s| float_cell(s)),
) {
(Some(n), Some(s)) => (n, s),
_ => continue,
};
let peak = cells.get(7).filter(|s| !s.is_empty()).and_then(|s| float_cell(s));
c.rows += 1;
c.counts += counts;
c.seconds += seconds;
c.first = Some(c.first.map_or(when, |f| if when < f { when } else { f }));
c.last = Some(c.last.map_or(when, |l| if when > l { when } else { l }));
raise(&mut c.peak, peak);
let h = c.hours.entry((when / 3600.0).floor() as i64).or_default();
h.counts += counts;
h.seconds += seconds;
raise(&mut h.peak, peak);
let d = c.days.entry(clock::format(when, "%Y-%m-%d")).or_default();
d.rows += 1;
d.counts += counts;
d.seconds += seconds;
raise(&mut d.peak, peak);
c.latest.push((when, cells));
}
}
for c in counters.values_mut() {
c.latest.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(std::cmp::Ordering::Equal));
let keep = c.latest.len().saturating_sub(60);
c.latest.drain(..keep);
c.cpm = if c.seconds != 0.0 { c.counts as f64 * 60.0 / c.seconds } else { 0.0 };
c.usvh = if cpm_per_usvh != 0.0 { c.cpm / cpm_per_usvh } else { 0.0 };
}
counters
}
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Merged {
pub rows: u64,
pub counts: i64,
pub seconds: f64,
pub tube_seconds: f64,
pub tubes: usize,
pub cpm: f64,
pub usvh: f64,
pub sigma: f64,
pub interleave: Option<f64>,
pub first: Option<f64>,
pub last: Option<f64>,
pub latest: Vec<(f64, Vec<String>)>,
}
const MERGED_COLUMNS: [&str; 10] = [
"time", "tubes", "interleave", "counts", "seconds", "tube_seconds",
"cps", "cps_raw", "cpm_30", "sigma_30",
];
pub fn merged(directory: &Path, cpm_per_usvh: f64) -> Option<Merged> {
let names: Vec<String> = MERGED_COLUMNS.iter().map(|s| s.to_string()).collect();
let mut m = Merged::default();
let mut gap = (0.0f64, 0u64);
for path in log::merged_files(directory) {
for (when, cells) in log::read_table(&path, &names) {
let (counts, seconds) = match (
cells.get(3).and_then(|s| int_cell(s)),
cells.get(4).and_then(|s| float_cell(s)),
) {
(Some(n), Some(s)) => (n, s),
_ => continue,
};
m.rows += 1;
m.counts += counts;
m.seconds += seconds;
m.tube_seconds += cells.get(5).and_then(|s| float_cell(s)).unwrap_or(seconds);
if let Some(t) = cells.get(1).and_then(|s| int_cell(s)) {
m.tubes = m.tubes.max(t.max(0) as usize);
}
if let Some(g) = cells.get(2).filter(|c| !c.is_empty()).and_then(|s| float_cell(s)) {
gap.0 += g;
gap.1 += 1;
}
m.first = Some(m.first.map_or(when, |f| if when < f { when } else { f }));
m.last = Some(m.last.map_or(when, |l| if when > l { when } else { l }));
m.latest.push((when, cells));
}
}
if m.rows == 0 {
return None;
}
m.latest.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(std::cmp::Ordering::Equal));
let keep = m.latest.len().saturating_sub(20);
m.latest.drain(..keep);
m.cpm = if m.tube_seconds > 0.0 {
m.counts as f64 * 60.0 / m.tube_seconds
} else {
0.0
};
m.usvh = if cpm_per_usvh != 0.0 { m.cpm / cpm_per_usvh } else { 0.0 };
m.sigma = if m.counts > 0 { m.cpm / (m.counts as f64).sqrt() } else { 0.0 };
m.interleave = (gap.1 > 0).then(|| gap.0 / gap.1 as f64);
Some(m)
}
#[derive(Debug, Clone, PartialEq)]
pub struct Together {
pub tubes: usize,
pub counts: i64,
pub seconds: f64,
pub cpm: f64,
pub usvh: f64,
pub sigma: f64,
pub worst: Option<(f64, String, String)>,
}
fn rate_of(c: &Counter) -> Option<(f64, f64)> {
if c.seconds <= 0.0 || c.counts <= 0 {
return None;
}
let r = c.counts as f64 / c.seconds;
Some((r, r / (c.counts as f64).sqrt()))
}
pub fn together(counters: &BTreeMap<String, Counter>, cpm_per_usvh: f64) -> Option<Together> {
let live: Vec<(&String, &Counter)> = counters
.iter()
.filter(|(_, c)| c.seconds > 0.0 && c.counts > 0)
.collect();
if live.len() < 2 {
return None;
}
let counts: i64 = live.iter().map(|(_, c)| c.counts).sum();
let seconds: f64 = live.iter().map(|(_, c)| c.seconds).sum();
let cpm = counts as f64 * 60.0 / seconds;
let mut worst: Option<(f64, String, String)> = None;
for i in 0..live.len() {
for j in i + 1..live.len() {
let (Some((ra, sa)), Some((rb, sb))) = (rate_of(live[i].1), rate_of(live[j].1))
else {
continue;
};
let sd = (sa * sa + sb * sb).sqrt();
if sd <= 0.0 {
continue;
}
let z = ((ra - rb) / sd).abs();
if worst.as_ref().map_or(true, |(w, _, _)| z > *w) {
worst = Some((z, live[i].0.clone(), live[j].0.clone()));
}
}
}
Some(Together {
tubes: live.len(),
counts,
seconds,
cpm,
usvh: if cpm_per_usvh != 0.0 { cpm / cpm_per_usvh } else { 0.0 },
sigma: cpm / (counts as f64).sqrt(),
worst,
})
}
pub fn agreement(z: f64) -> &'static str {
if z < 2.0 {
"they agree"
} else if z < 4.0 {
"they differ -- watch it"
} else {
"they disagree -- not the same measurement"
}
}
pub fn nice_ceiling(value: f64) -> f64 {
if value <= 0.0 {
return 1.0;
}
let power = pow(10.0, value.log10().floor());
for step in [1.0, 1.5, 2.0, 2.5, 3.0, 4.0, 5.0, 6.0, 8.0, 10.0] {
if value <= step * power {
return step * power;
}
}
10.0 * power
}
pub fn hour_series(c: &Counter) -> Vec<(f64, f64, Option<f64>)> {
c.hours
.iter()
.filter(|(_, h)| h.seconds != 0.0)
.map(|(hour, h)| (*hour as f64 * 3600.0, h.counts as f64 * 60.0 / h.seconds, h.peak))
.collect()
}
pub fn svg_plot(series: &[(f64, f64, Option<f64>)]) -> String {
let (width, height, pad_l, pad_b, pad_t, pad_r) = (1120i64, 1200i64, 52i64, 26i64, 12i64, 10i64);
if series.len() < 2 {
return String::new();
}
let mut values: Vec<f64> = series.iter().map(|s| s.1).filter(|m| *m > 0.0).collect();
values.extend(series.iter().filter_map(|s| s.2).filter(|p| *p != 0.0));
if values.is_empty() {
return String::new();
}
let vmin = values.iter().copied().fold(values[0], |a, b| if b < a { b } else { a });
let vmax = values.iter().copied().fold(values[0], |a, b| if b > a { b } else { a });
let lo = pow(10.0, vmin.log10().floor());
let mut hi = pow(10.0, vmax.log10().ceil());
if hi <= lo {
hi = lo * 10.0;
}
let span_y = hi.log10() - lo.log10();
let t0 = series[0].0;
let t1 = series[series.len() - 1].0;
let span = if t1 - t0 != 0.0 { t1 - t0 } else { 1.0 };
let iw = width - pad_l - pad_r;
let ih = height - pad_t - pad_b;
let x_of = |t: f64| pad_l as f64 + iw as f64 * (t - t0) / span;
let y_of = |v: f64| {
pad_t as f64 + ih as f64 * (1.0 - (pymax(v, lo).log10() - lo.log10()) / span_y)
};
let step = 3600.0 * 1.5;
let path = |points: &[(f64, Option<f64>)]| -> String {
let mut d: Vec<String> = Vec::new();
let mut pen = false;
let mut last: Option<f64> = None;
for (t, v) in points {
let v = match v {
Some(v) => *v,
None => {
pen = false;
last = Some(*t);
continue;
}
};
let letter = if !pen || last.map(|l| t - l > step).unwrap_or(false) { "M" } else { "L" };
d.push(format!("{}{} {}", letter, f(1, x_of(*t)), f(1, y_of(v))));
pen = true;
last = Some(*t);
}
d.join(" ")
};
let mut out = vec![format!(
"<svg class=\"plot\" viewBox=\"0 0 {} {}\" width=\"100%\" \
preserveAspectRatio=\"xMidYMid meet\" role=\"img\" \
aria-label=\"counts per minute over time\">",
width, height
)];
let mut decade = lo;
while decade <= hi * 1.0001 {
let y = f(1, y_of(decade));
out.push(format!(
"<line class=\"grid\" x1=\"{}\" y1=\"{}\" x2=\"{}\" y2=\"{}\"/>",
pad_l, y, width - pad_r, y
));
out.push(format!(
"<text class=\"ylab\" x=\"{}\" y=\"{}\">{}</text>",
pad_l - 8,
f(1, y_of(decade) + 4.0),
commas(decade as i64)
));
for minor in [2.0, 5.0] {
let v = decade * minor;
if v < hi {
let ym = f(1, y_of(v));
out.push(format!(
"<line class=\"grid minor\" x1=\"{}\" y1=\"{}\" x2=\"{}\" y2=\"{}\"/>",
pad_l, ym, width - pad_r, ym
));
}
}
decade *= 10.0;
}
let day = 86400.0;
let mut t = t0 - t0.rem_euclid(day) + day;
while t < t1 {
let x = f(1, x_of(t));
out.push(format!(
"<line class=\"grid\" x1=\"{}\" y1=\"{}\" x2=\"{}\" y2=\"{}\"/>",
x, pad_t, x, pad_t + ih
));
out.push(format!(
"<text class=\"xlab\" x=\"{}\" y=\"{}\">{}</text>",
x,
height - 8,
clock::format(t, "%b %-d")
));
t += day;
}
let peaks: Vec<(f64, Option<f64>)> = series.iter().map(|s| (s.0, s.2)).collect();
let means: Vec<(f64, Option<f64>)> = series.iter().map(|s| (s.0, Some(s.1))).collect();
out.push(format!("<path class=\"peak\" d=\"{}\"/>", path(&peaks)));
out.push(format!("<path class=\"mean\" d=\"{}\"/>", path(&means)));
out.push(format!(
"<text class=\"ycap\" x=\"{}\" y=\"{}\">CPM, log</text>",
pad_l - 44,
pad_t + 10
));
out.push("</svg>".to_string());
out.concat()
}
pub fn svg_overlay(series: &[(String, Vec<(f64, f64, Option<f64>)>)]) -> String {
let (width, height, pad_l, pad_b, pad_t, pad_r) = (1120i64, 560i64, 52i64, 26i64, 12i64, 10i64);
let live: Vec<&(String, Vec<(f64, f64, Option<f64>)>)> =
series.iter().filter(|(_, s)| s.len() >= 2).collect();
if live.len() < 2 {
return String::new();
}
let values: Vec<f64> = live
.iter()
.flat_map(|(_, s)| s.iter().map(|p| p.1))
.filter(|m| *m > 0.0)
.collect();
if values.is_empty() {
return String::new();
}
let vmin = values.iter().copied().fold(values[0], |a, b| if b < a { b } else { a });
let vmax = values.iter().copied().fold(values[0], |a, b| if b > a { b } else { a });
let lo = pow(10.0, vmin.log10().floor());
let mut hi = pow(10.0, vmax.log10().ceil());
if hi <= lo {
hi = lo * 10.0;
}
let span_y = hi.log10() - lo.log10();
let t0 = live.iter().map(|(_, s)| s[0].0).fold(f64::INFINITY, f64::min);
let t1 = live
.iter()
.map(|(_, s)| s[s.len() - 1].0)
.fold(f64::NEG_INFINITY, f64::max);
let span = if t1 - t0 != 0.0 { t1 - t0 } else { 1.0 };
let iw = width - pad_l - pad_r;
let ih = height - pad_t - pad_b;
let x_of = |t: f64| pad_l as f64 + iw as f64 * (t - t0) / span;
let y_of = |v: f64| {
pad_t as f64 + ih as f64 * (1.0 - (pymax(v, lo).log10() - lo.log10()) / span_y)
};
let step = 3600.0 * 1.5;
let mut out = vec![format!(
"<svg class=\"plot\" viewBox=\"0 0 {} {}\" width=\"100%\" \
preserveAspectRatio=\"xMidYMid meet\" role=\"img\" \
aria-label=\"counts per minute over time, every counter\">",
width, height
)];
let mut decade = lo;
while decade <= hi * 1.0001 {
let y = f(1, y_of(decade));
out.push(format!(
"<line class=\"grid\" x1=\"{}\" y1=\"{}\" x2=\"{}\" y2=\"{}\"/>",
pad_l, y, width - pad_r, y
));
out.push(format!(
"<text class=\"ylab\" x=\"{}\" y=\"{}\">{}</text>",
pad_l - 8,
f(1, y_of(decade) + 4.0),
commas(decade as i64)
));
decade *= 10.0;
}
let day = 86400.0;
let mut t = t0 - t0.rem_euclid(day) + day;
while t < t1 {
let x = f(1, x_of(t));
out.push(format!(
"<line class=\"grid\" x1=\"{}\" y1=\"{}\" x2=\"{}\" y2=\"{}\"/>",
x, pad_t, x, pad_t + ih
));
out.push(format!(
"<text class=\"xlab\" x=\"{}\" y=\"{}\">{}</text>",
x,
height - 8,
clock::format(t, "%b %-d")
));
t += day;
}
for (i, (serial, points)) in live.iter().enumerate() {
let mut d: Vec<String> = Vec::new();
let mut last: Option<f64> = None;
for (when, mean, _) in points.iter() {
let letter = if last.map(|l| when - l > step).unwrap_or(true) { "M" } else { "L" };
d.push(format!("{}{} {}", letter, f(1, x_of(*when)), f(1, y_of(*mean))));
last = Some(*when);
}
out.push(format!(
"<path class=\"tube t{}\" d=\"{}\"/>",
i % 4,
d.join(" ")
));
out.push(format!(
"<text class=\"key t{}\" x=\"{}\" y=\"{}\">{}</text>",
i % 4,
pad_l + 8,
pad_t + 16 + 15 * i as i64,
esc(serial)
));
}
out.push(format!(
"<text class=\"ycap\" x=\"{}\" y=\"{}\">CPM, log</text>",
pad_l - 44,
pad_t + 10
));
out.push("</svg>".to_string());
out.concat()
}
pub fn esc(text: &str) -> String {
text.replace('&', "&")
.replace('<', "<")
.replace('>', ">")
.replace('"', """)
}
pub fn page_head(title: &str, extra: &[&str]) -> Vec<String> {
let mut out: Vec<String> = [
"<!doctype html>",
"<html lang=\"en\"><head><meta charset=\"utf-8\">",
"<meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">",
]
.iter()
.map(|s| s.to_string())
.collect();
out.push(format!("<title>{}</title>", esc(title)));
out.push("<style>".to_string());
for rule in STYLE.iter().chain(extra.iter()) {
out.push(rule.to_string());
}
out.push("</style></head><body><main>".to_string());
out
}
const STYLE: &[&str] = &[
":root{color-scheme:light dark;--fg:#181818;--bg:#faf9f7;\
--dim:#6b6b6b;--line:#e0ddd8;--card:#fff;--accent:#2f6f4f;\
--warn:#b0642a}",
"@media (prefers-color-scheme:dark){:root{--fg:#e8e6e3;--bg:#16161a;\
--dim:#9a9a9a;--line:#2e2e35;--card:#1e1e24;--accent:#6cc08c;\
--warn:#e0a06a}}",
"body{margin:0;padding:2rem 1rem;background:var(--bg);color:var(--fg);\
font:15px/1.55 system-ui,-apple-system,Segoe UI,sans-serif}",
"main{max-width:1100px;margin:0 auto}",
"h1{font-size:1.6rem;margin:0 0 .2rem}",
"h2{font-size:1.1rem;margin:2.2rem 0 .6rem;font-weight:600}",
".sub{color:var(--dim);margin:0 0 1rem}",
".lede{max-width:70ch;margin:0 0 2rem;font-size:1rem;line-height:1.6}",
".lede a{color:var(--accent)}",
".how{margin-top:2.6rem}",
".how h3{margin:1.6rem 0 .3rem;font-size:1rem}",
".how p{margin:.35rem 0;max-width:68ch}",
".how pre{background:var(--card);border:1px solid var(--line);\
border-radius:8px;padding:.6rem .9rem;overflow-x:auto;\
font-size:.84rem;margin:.5rem 0}",
".how img{border:1px solid var(--line);border-radius:8px;\
margin:.6rem 0;max-width:100%}",
".how figure{margin:.8rem 0 1.2rem}",
".how figcaption{color:var(--dim);font-size:.82rem;margin-top:.3rem}",
".cards{display:grid;gap:.9rem;\
grid-template-columns:repeat(auto-fit,minmax(190px,1fr))}",
".card{background:var(--card);border:1px solid var(--line);\
border-radius:10px;padding:.9rem 1rem}",
".card .k{color:var(--dim);font-size:.78rem;text-transform:uppercase;\
letter-spacing:.04em}",
".card .v{font-size:1.5rem;font-variant-numeric:tabular-nums;\
margin-top:.15rem}",
".card .n{color:var(--dim);font-size:.8rem}",
".plotwrap{background:var(--card);border:1px solid var(--line);\
border-radius:10px;padding:.9rem 1rem 0;margin-top:.9rem}",
".plot{display:block;height:auto}",
".plot .grid{stroke:var(--line);stroke-width:1}",
".plot .minor{opacity:.45}",
".plot .mean{fill:none;stroke:var(--accent);stroke-width:1.6;\
stroke-linejoin:round;stroke-linecap:round}",
".plot .peak{fill:none;stroke:var(--warn);stroke-width:1;opacity:.55}",
".plot .tube{fill:none;stroke-width:1.6;stroke-linejoin:round;\
stroke-linecap:round;opacity:.9}",
".plot .key{font-size:12px;text-anchor:start}",
".plot .t0{stroke:#6cc6ff;fill:#6cc6ff}",
".plot .t1{stroke:#c9a0ff;fill:#c9a0ff}",
".plot .t2{stroke:#7ee787;fill:#7ee787}",
".plot .t3{stroke:#ffa657;fill:#ffa657}",
".plot text{fill:var(--dim);font-size:11px;\
font-family:system-ui,sans-serif}",
".plot .ylab{text-anchor:end}",
".plot .xlab{text-anchor:middle}",
".plot .ycap{text-anchor:start;font-size:10px;letter-spacing:.05em;\
text-transform:uppercase}",
".legend{display:flex;gap:1.2rem;color:var(--dim);font-size:.8rem;\
padding:.1rem 0 .8rem}",
".legend i{display:inline-block;width:18px;height:0;\
border-top-width:2px;border-top-style:solid;vertical-align:middle;\
margin-right:.4rem}",
".about{background:var(--card);border:1px solid var(--line);\
border-radius:10px;padding:1.2rem 1.4rem;margin-top:2.6rem}",
".about h3{margin:0 0 .4rem;font-size:1.05rem}",
".about p{margin:.4rem 0;max-width:62ch}",
".about pre{background:var(--bg);border:1px solid var(--line);\
border-radius:6px;padding:.6rem .8rem;overflow-x:auto;font-size:.82rem}",
".windows{display:grid;gap:.7rem;margin:.9rem 0 0;padding:0;\
list-style:none;grid-template-columns:repeat(auto-fit,minmax(190px,1fr))}",
".windows li{border-left:2px solid var(--accent);padding-left:.7rem}",
".windows b{display:block;font-size:1.05rem}",
".windows span{color:var(--dim);font-size:.85rem}",
"table{border-collapse:collapse;width:100%;font-size:.86rem;\
font-variant-numeric:tabular-nums;background:var(--card);\
border:1px solid var(--line);border-radius:10px;overflow:hidden}",
"th{text-align:left;font-weight:600;color:var(--dim);font-size:.76rem;\
text-transform:uppercase;letter-spacing:.04em}",
"th,td{padding:.36rem .7rem;border-bottom:1px solid var(--line)}",
"tbody tr:last-child td{border-bottom:0}",
"td:not(:first-child),th:not(:first-child){text-align:right}",
".more{margin:.6rem 0 0;font-size:.85rem}",
".more a{color:var(--accent)}",
".tablewrap{overflow-x:auto}",
"footer{color:var(--dim);font-size:.82rem;margin-top:3rem;\
border-top:1px solid var(--line);padding-top:1rem}",
"code{background:var(--card);padding:.1rem .3rem;border-radius:4px}",
];
#[allow(clippy::too_many_arguments)]
pub fn render_html(
counters: &BTreeMap<String, Counter>,
sites: &[(String, f64, String)],
cpm_per_usvh: f64,
title: &str,
shots: &BTreeMap<String, String>,
randoms: &BTreeMap<String, String>,
merge: Option<&Merged>,
) -> String {
let random_link = randoms.values().next().map(|s| s.as_str());
let when = |t: f64| clock::format(t, "%Y-%m-%d %H:%M");
let mut out = page_head(title, &[]);
macro_rules! a {
($($arg:tt)*) => { out.push(format!($($arg)*)) };
}
a!("<h1>{}</h1>", esc(title));
a!(
"<p class=\"sub\">{} · generated {} by radbeeper {} · tube factor {} CPM per µSv/h</p>",
esc(TAGLINE),
esc(&when(now())),
VERSION,
f(1, cpm_per_usvh)
);
a!(
"<p class=\"lede\">A <strong>GQ GMC-320 Plus</strong> Geiger–Müller \
counter, plugged into a machine running <strong>Alpine Linux</strong> \
— or <strong><a href=\"https://github.com/vonglurt/copal\">Copal\
</a></strong>, its distillation, which carries this as a stage and \
installs the <code>linux-lts</code> kernel package the counter needs to \
be seen at all — as a USB serial device, here shared into a \
virtual machine over USB pass-through. RadBeeper reads the counter, logs it to tab-separated \
files, and <strong>this page is regenerated from those files by a \
GitHub Action</strong> on every push. The whole of it is forkable: copy \
your own logs into <code>logs/</code> and you get a page like this \
one. <a href=\"{}\">Source and instructions</a>.{}</p>",
HOMEPAGE,
match random_link {
Some(l) => format!(" <a href=\"{}\">Where the random comes from</a>.", esc(l)),
None => String::new(),
}
);
if counters.is_empty() {
a!("<p>No logs found. Put <code>cpm-<serial>-YYYY-MM.tsv</code> \
files beside this page and run <code>radbeeper export</code>.</p>");
}
if let Some(t) = together(counters, cpm_per_usvh) {
a!("<h2>Both counters</h2>");
a!("<div class=\"cards\">");
let card = |k: &str, v: &str, n: &str| {
format!(
"<div class=\"card\"><div class=\"k\">{}</div><div class=\"v\">{}</div>{}</div>",
esc(k),
esc(v),
if n.is_empty() { String::new() } else { format!("<div class=\"n\">{}</div>", esc(n)) }
)
};
out.push(card(
"Mean, together",
&format!("{} CPM", f(1, t.cpm)),
&format!("{} uSv/h", f(3, t.usvh)),
));
out.push(card(
"Precision",
&format!("\u{b1}{} CPM", f(1, t.sigma)),
&format!("{}% of the mean", f(2, 100.0 * t.sigma / pymax(t.cpm, 1e-9))),
));
out.push(card(
"Arrivals behind it",
&commas(t.counts),
&format!("over {} tube-hours", f(1, t.seconds / 3600.0)),
));
out.push(match &t.worst {
Some((z, _, _)) => card(
"Do they agree?",
agreement(*z),
&format!("widest gap {} sigma", f(1, *z)),
),
None => card("Do they agree?", "--", "not enough counts yet"),
});
a!("</div>");
a!(
"<p class=\"note\">Two tubes watching one room are two measurements of \
one number: they do <strong>not</strong> double the dose — what \
doubles is the evidence. The mean above is counts-weighted across \
{} tubes, and the precision is all a second counter buys: arrivals \
are Poisson, so N of them are known to 1/√N and twice the \
counts is a factor of √2 better. The agreement is the one \
question a second instrument exists to answer — identical \
tubes in one room should sit within about two sigma of each other, \
and a gap that keeps growing is the tubes differing, not the room \
being interesting.</p>",
t.tubes
);
let series: Vec<(String, Vec<(f64, f64, Option<f64>)>)> = counters
.iter()
.map(|(serial, c)| (serial.clone(), hour_series(c)))
.collect();
let plot = svg_overlay(&series);
if !plot.is_empty() {
a!("<div class=\"plotwrap\">{}</div>", plot);
a!("<p class=\"note\">Every counter's hourly mean, one colour each. \
Two tubes in one room draw the same shape; where they stop being \
parallel is where something is wrong with a tube, a cable or a \
pass-through, and no table of averages shows that as quickly.</p>");
}
}
if let Some(m) = merge {
a!("<h2>The merged record</h2>");
a!("<div class=\"cards\">");
let card = |k: &str, v: &str, n: &str| {
format!(
"<div class=\"card\"><div class=\"k\">{}</div><div class=\"v\">{}</div>{}</div>",
esc(k),
esc(v),
if n.is_empty() { String::new() } else { format!("<div class=\"n\">{}</div>", esc(n)) }
)
};
out.push(card(
"The room",
&format!("{} CPM", f(3, m.cpm)),
&format!("\u{b1}{} CPM \u{b7} {} uSv/h", f(3, m.sigma), f(4, m.usvh)),
));
out.push(card(
"Raw arrivals",
&commas(m.counts),
&format!(
"{} tube-hours over {} hours of room",
f(2, m.tube_seconds / 3600.0),
f(2, m.seconds / 3600.0)
),
));
out.push(match m.interleave {
Some(g) => card(
"Interleave",
&format!("{} s", f(3, g)),
&format!(
"{}% of what {} tubes could manage",
f(0, 100.0 * analysis::interleave_quality(g, m.tubes)),
m.tubes
),
),
None => card("Interleave", "--", "one tube has nothing to interleave with"),
});
out.push(card(
"Merged rows",
&commas(m.rows as i64),
&match (m.first, m.last) {
(Some(a), Some(b)) => format!("{} to {}", when(a), when(b)),
_ => String::new(),
},
));
a!("</div>");
a!(
"<p class=\"note\">Every counter keeps its own file and nothing is \
ever merged into it — a row that blended two instruments \
could not be taken apart again, and whether the two agree is the \
one question a second tube exists to answer. So the merge is a \
file of its own, <code>cpm-merged-YYYY-MM.tsv</code>, written \
beside them as the counters are read. It carries both halves of \
every interval: the <strong>raw</strong> arrivals as integers, \
with the tube-seconds behind them and a per-tube breakdown, and \
the <strong>merged</strong> rate of the room — counts over \
tube-seconds, which is the mean the tubes agree on and emphatically \
not their sum. Its numbers are written so that reading them back \
gives the same number: the per-counter files round to a tenth of a \
CPM, and this one does not.</p>"
);
a!(
"<p class=\"note\">The <strong>interleave</strong> is the fact no \
per-counter file can hold. Each tube has its own clock and its own \
phase and none can be steered, so the gap between one tube\u{2019}s \
sample and the next tube\u{2019}s is whatever it is — and the \
ideal is 1/n of a second, not half of one. Near it, the tubes are \
taking turns and the pair resolves time n times as finely as one \
of them could. Near zero they are firing together, which still \
multiplies the counts and still buys the precision above, and adds \
no time resolution at all.</p>"
);
if !m.latest.is_empty() {
a!("<h3>The last merged rows</h3>");
a!("<div class=\"tablewrap\"><table><thead><tr>");
for h in ["Time", "Tubes", "Interleave", "Raw counts", "Room s",
"Tube s", "Room CPM", "Arrivals/s", "CPM 30s"] {
a!("<th>{}</th>", esc(h));
}
a!("</tr></thead><tbody>");
for (_, cells) in m.latest.iter().rev() {
a!("<tr>");
for (i, places) in [
(0usize, usize::MAX), (1, 0), (2, 3), (3, 0), (4, 0),
(5, 0), (6, 3), (7, 3), (8, 3),
] {
let raw = cells.get(i).map(String::as_str).unwrap_or("");
let text = if places == usize::MAX {
raw.replace('T', " ")
} else if raw.is_empty() {
"\u{2014}".to_string()
} else {
match float_cell(raw) {
Some(v) if i == 6 => f(places, v * 60.0),
Some(v) => f(places, v),
None => raw.to_string(),
}
};
a!("<td>{}</td>", esc(&text));
}
a!("</tr>");
}
a!("</tbody></table></div>");
}
}
for (serial, c) in counters {
let at = match c.last {
Some(l) if l != 0.0 => l,
_ => now(),
};
let here = log::site_at(serial, at, sites);
a!("<h2>Counter {}</h2>", esc(serial));
a!("<div class=\"cards\">");
let card = |k: &str, v: &str, n: &str| {
format!(
"<div class=\"card\"><div class=\"k\">{}</div><div class=\"v\">{}</div>{}</div>",
esc(k),
esc(v),
if n.is_empty() { String::new() } else { format!("<div class=\"n\">{}</div>", esc(n)) }
)
};
out.push(card("Mean", &format!("{} CPM", f(1, c.cpm)), &format!("{} uSv/h", f(3, c.usvh))));
out.push(match c.peak {
None => card("Highest 3s peak", "--", ""),
Some(p) => card(
"Highest 3s peak",
&format!("{} CPM", f(0, p)),
&format!("{} uSv/h", f(3, p / cpm_per_usvh)),
),
});
out.push(card(
"Rows",
&commas(c.rows as i64),
&format!("{} hours counted", f(1, c.seconds / 3600.0)),
));
let stamp = |t: Option<f64>| match t {
Some(t) if t != 0.0 => when(t),
_ => "--".to_string(),
};
out.push(card("Covering", &stamp(c.first), &format!("to {}", stamp(c.last))));
if let Some(name) = here {
out.push(card("Site", &name, ""));
}
a!("</div>");
let chart = svg_plot(&hour_series(c));
if !chart.is_empty() {
a!("<h2>Counts per minute, by the hour</h2>");
a!("<div class=\"plotwrap\">{}", chart);
a!("<div class=\"legend\">\
<span><i style=\"border-top-color:var(--accent)\"></i>\
hourly mean</span>\
<span><i style=\"border-top-color:var(--warn)\"></i>\
highest 3-second peak in the hour</span>\
<span>a break in the line is an hour with no recording</span>\
</div></div>");
}
a!("<h2>By day</h2>");
a!("<div class=\"tablewrap\"><table><thead><tr><th>Day</th>\
<th>Mean CPM</th>\
<th>µSv/h</th><th>Peak 3s CPM</th><th>Rows</th>\
<th>Hours</th></tr></thead><tbody>");
for (day, d) in c.days.iter().rev() {
let cpm = if d.seconds != 0.0 { d.counts as f64 * 60.0 / d.seconds } else { 0.0 };
a!(
"<tr><td>{}</td><td>{}</td><td>{}</td><td>{}</td><td>{}</td><td>{}</td></tr>",
esc(day),
f(1, cpm),
f(3, cpm / cpm_per_usvh),
d.peak.map(|p| f(0, p)).unwrap_or_else(|| "--".to_string()),
d.rows,
f(1, d.seconds / 3600.0)
);
}
a!("</tbody></table></div>");
a!("<h2>Latest rows</h2>");
a!("<div class=\"tablewrap\"><table><thead><tr><th>Time</th>\
<th>CPS</th><th>3s</th><th>30s</th><th>300s</th><th>Peak 3s</th>\
<th>Source</th><th>Site</th></tr></thead><tbody>");
for (_t, cells) in c.latest.iter().rev() {
let cell = |i: usize| match cells.get(i) {
Some(s) if !s.is_empty() => esc(s),
_ => "--".to_string(),
};
a!(
"<tr><td>{}</td><td>{}</td><td>{}</td><td>{}</td><td>{}</td><td>{}</td><td>{}</td><td>{}</td></tr>",
esc(&cells[0]),
cell(1),
cell(4),
cell(5),
cell(6),
cell(7),
cell(10),
cell(11)
);
}
a!("</tbody></table></div>");
if !c.links.is_empty() {
let links: Vec<String> = c
.links
.iter()
.map(|(name, href)| format!("<a href=\"{}\">{}</a>", href, esc(name)))
.collect();
a!(
"<p class=\"more\">The last {} rows of {}. Read the full chart: {} — tab-separated, one row every 30 seconds.</p>",
c.latest.len(),
commas(c.rows as i64),
links.join(" · ")
);
}
if let Some(href) = randoms.get(serial) {
a!(
"<p class=\"more\"><a href=\"{}\">Where this counter's random \
comes from</a> — every line it has emitted, with the \
counts behind it.</p>",
esc(href)
);
}
}
a!("<section class=\"how\">");
a!("<h2>How to use it</h2>");
let shot = |out: &mut Vec<String>, name: &str, caption: &str| {
if let Some(src) = shots.get(name) {
out.push(format!(
"<figure><img src=\"{}\" alt=\"{}\" loading=\"lazy\"><figcaption>{}</figcaption></figure>",
esc(src),
esc(caption),
esc(caption)
));
}
};
a!("<h3>What you need</h3>");
a!("<p><b>A GQ GMC-320 Plus, plugged into a USB port, switched on.</b> \
That is the hardware, and no amount of software substitutes for it: \
every number on this page came off a real tube over a real serial \
port. A <b>GMC-300</b> works too — RadBeeper tries its 57600 \
baud as well as the 320's 115200 — and a 500 or 600 is found \
and read, but its tube is not an M4011, so it needs its own \
<code>--cpm-per-usvh</code>.</p>");
a!("<ul>");
a!("<li><b>The USB cable that came with it.</b> A charge-only cable \
carries no data, and is indistinguishable from an empty port until \
you try another one.</li>");
a!("<li><b>The counter switched on.</b> Its USB-serial chip is powered \
by the counter, not by the bus — a flat 320 enumerates as \
nothing.</li>");
a!("<li><b>A kernel with <code>ch341</code>.</b> The 320 Plus presents \
as a CH340. <code>linux-lts</code> and <code>linux-rpi</code> carry \
the driver; Alpine's <code>linux-virt</code> does not, which is the \
commonest reason a counter that is plugged in cannot be found. \
<a href=\"https://github.com/vonglurt/copal\">Copal</a> installs the \
<code>linux-lts</code> Alpine package, so the case does not arise \
there.</li>");
a!("<li><b>Membership of <code>dialout</code>.</b> The serial node is \
<code>root:dialout</code> and RadBeeper does not want root.</li>");
a!("</ul>");
a!("<p>Plugged in and working, Linux says so: <code>dmesg</code> ends \
with <code>ch341-uart converter now attached to ttyUSB0</code> and \
<code>/dev/ttyUSB0</code> exists. USB pass-through into a VM counts \
— these logs came from one — provided the guest kernel \
is one of the two that has the driver.</p>");
a!("<p>No counter yet? <code>radbeeper --source sim watch</code> draws \
the whole monitor against a synthetic Poisson background.</p>");
a!("<h3>Install</h3>");
a!("<p>One stdlib Python file. No packages, no build, nothing to compile \
— the install is a copy.</p>");
a!("<pre>git clone {}.git\n\
cd radbeeper && make install\n\n\
doas adduser $USER dialout # then log in again</pre>", HOMEPAGE);
a!("<p>The read side is also a Rust crate, if a native binary suits the \
machine better: <code>cargo install radbeeper</code>, or a static \
musl build from the <a href=\"{}/releases\">releases \
page</a> for x86_64, aarch64, armv7 or the Pi Zero's armv6. It does \
<code>probe</code>, <code>cpm</code> and <code>watch</code>; \
everything that writes these logs stays in the Python.</p>", HOMEPAGE);
a!("<h3>Find the counter</h3>");
a!("<pre>radbeeper probe</pre>");
shot(&mut out, "probe", "radbeeper probe, against the counter these logs came from");
a!("<p>If it finds nothing it says which of four things went wrong, because \
they have four different fixes: no serial node at all (often a kernel \
with no <code>ch341</code> — Alpine's <code>linux-virt</code> has \
none, <code>linux-lts</code> does), permission on the node, something \
that is not a GMC, or a port another reader already holds.</p>");
a!("<h3>Watch it</h3>");
a!("<pre>radbeeper watch</pre>");
shot(&mut out, "watch", "the monitor: five time constants, the counts, the \
spectrum and a line of decay-derived random");
shot(&mut out, "watch-20s", "twenty seconds of a real session, at ten times speed");
a!("<p>The counter's own reading is a rolling 60-second count — one \
number with one time constant. RadBeeper counts the blips itself and \
keeps five windows at once, each a factor of ten apart.</p>");
a!("<ul class=\"windows\">");
a!("<li><b>3 s</b><span>Three seconds is too short to be a measurement. \
On a 40 CPM background it swings between 0 and 80, because at this \
rate three seconds is two counts. Watch it to see a source come and \
go as you move it, and do not write it down.</span></li>");
a!("<li><b>30 s</b><span>Half a minute, and the shortest window that is a \
count rather than a flicker. Settled enough to compare two places, \
quick enough to follow your hands — which is why it is the \
number in the big digits, and what <code>radbeeper cpm</code> \
reports.</span></li>");
a!("<li><b>300 s</b><span>Five minutes. A number worth writing \
down.</span></li>");
a!("<li><b>3000 s</b><span>Fifty minutes. What the background here \
actually is, once the day's traffic through the room has averaged \
out.</span></li>");
a!("<li><b>30000 s</b><span>Eight hours twenty — a working day. It \
is not a faster answer to the same question, it is the only window \
that spans one; a shift's worth of background, against which a day \
that was different is visible as a difference.</span></li>");
a!("</ul>");
a!("<p><strong>A window shows nothing until it is full</strong>, and says \
how long it still needs. A three-second CPM built from one sample is \
twenty times noisier than it looks, and drawing it as though it were \
settled is how a 25 CPM background reads as 60 and somebody goes \
hunting for a leak.</p>");
shot(&mut out, "watch-filling", "the long window still filling, and saying so");
a!("<h3>Is anything periodic?</h3>");
a!("<p>The monitor also accumulates a power spectrum of the per-second \
counts. <strong>Decay is a Poisson process and the spectrum of a \
Poisson process is flat</strong> — so a featureless strip is the \
good answer, and says that nothing is arriving on a schedule.</p>");
shot(&mut out, "watch-spectrum", "the accumulating spectrum: flat is healthy");
a!("<p>A peak is the interesting case: mains hum on the tube's supply, a \
fan carrying a source past, a loose connector, firmware that batches \
its reporting. In the time domain all of those look exactly like more \
counts. Averaging successive windows is what makes a real line climb \
out of the noise — one periodogram of a Poisson process is flat \
in expectation and violently noisy in fact.</p>");
a!("<p>No counter on the desk? Every command runs against a built-in \
source, and it is a real one — radioactive decay is a Poisson \
process, so the simulator draws Poisson samples.</p>");
a!("<pre>radbeeper --source sim --sim-cpm 400 watch</pre>");
a!("<h3>Random numbers out of decay</h3>");
a!("<p>The monitor also keeps an entropy pool and prints a line of hex \
whenever the samples have <strong>earned</strong> it. Not modelled \
— measured: the counts coming back over the serial link are \
measurably burstier than Poisson, so the bits per second are \
estimated from the samples themselves and pushed to the far end of a \
99% confidence interval before anything is emitted.</p>");
a!("<pre>radbeeper random</pre>");
if let Some(l) = random_link {
a!("<p><a href=\"{}\"><strong>Where the random \
comes from</strong></a> — the counts against the model, the \
bits accumulating second by second, what the serial link's \
one-second resolution costs, and every line emitted with the \
counts behind it.</p>", esc(l));
}
a!("<h3>Log it</h3>");
a!("<pre>radbeeper service</pre>");
a!("<p>A row every 30 seconds into a dated file per counter, \
<code>cpm-<serial>-YYYY-MM.tsv</code> — which is rotation \
by construction, with no cron entry and nothing renaming a file while \
a service appends to it. Each row carries the <strong>peak</strong> \
every window reached since the last one, so a source that came and \
went between two rows still leaves a trace.</p>");
shot(&mut out, "log-output", "the log on disk, and what a row holds");
a!("<p>Tabs are invisible, and that matters here: an <strong>empty field is \
not a zero</strong>, it is a window that was not full yet.</p>");
shot(&mut out, "log-tabs", "the same rows with every tab made visible");
a!("<p>The counter also records to its own flash whether or not anything \
is listening. <code>radbeeper backfill</code> reads that back and \
fills the gaps — one row per slot, never over a live \
measurement, and an hour nobody recorded stays an hour nobody \
recorded.</p>");
a!("<pre>radbeeper backfill</pre>");
a!("<h3>Publish it</h3>");
a!("<pre>radbeeper export --logs logs -o index.html</pre>");
a!("<p>This page. Fork the repository, copy your <code>cpm-*.tsv</code> \
into <code>logs/</code>, push, and the workflow rebuilds and commits \
it — served by GitHub Pages with no build step. There is nothing \
to install in the workflow: the generator is the same one file, which \
is also why the page cannot drift from the log format.</p>");
a!(
"<p>MIT License — Copyright (c) 2026 Paul Richeson · <a href=\"{}\">{}</a></p>",
HOMEPAGE,
HOMEPAGE.split_once("//").map(|(_, rest)| rest).unwrap_or(HOMEPAGE)
);
a!("</section>");
a!("<footer>MIT License — Copyright (c) 2026 Paul Richeson. \
Rows marked <code>live</code> were measured by a monitor on \
this machine; rows marked <code>flash</code> were reconstructed from \
the counter's own recorded history. Gaps are gaps: nothing is \
interpolated. Built by \
<code>radbeeper export</code>.</footer>");
a!("</main>");
a!("</body></html>");
out.join("\n") + "\n"
}
pub fn random_files(directory: &Path) -> Vec<(String, PathBuf)> {
let mut names: Vec<String> = match fs::read_dir(directory) {
Ok(entries) => entries
.filter_map(|e| e.ok())
.filter_map(|e| e.file_name().into_string().ok())
.collect(),
Err(_) => return Vec::new(),
};
names.sort();
names
.into_iter()
.filter(|n| n.starts_with("random-") && n.ends_with(".tsv") && n.len() >= 11)
.map(|n| (n[7..n.len() - 4].to_string(), directory.join(&n)))
.collect()
}
pub struct Freq {
order: Vec<u32>,
counts: BTreeMap<u32, usize>,
}
impl Freq {
fn of(samples: &[u32]) -> Freq {
let mut f = Freq { order: Vec::new(), counts: BTreeMap::new() };
for s in samples {
let n = f.counts.entry(*s).or_insert(0);
if *n == 0 {
f.order.push(*s);
}
*n += 1;
}
f
}
fn get(&self, k: u32) -> usize {
self.counts.get(&k).copied().unwrap_or(0)
}
fn mode(&self) -> u32 {
let mut best = self.order[0];
for k in &self.order {
if self.get(*k) > self.get(best) {
best = *k;
}
}
best
}
}
pub struct Budget {
pub n: usize,
pub mean: f64,
pub var: f64,
pub dispersion: f64,
pub pmax: f64,
pub measured: f64,
pub modelled: f64,
pub ratio: f64,
pub freq: Freq,
pub seconds_for: Option<f64>,
pub seconds_modelled: Option<f64>,
}
pub fn entropy_budget(samples: &[u32]) -> Option<Budget> {
let n = samples.len();
if n < 2 {
return None;
}
let freq = Freq::of(samples);
let total: u64 = samples.iter().map(|x| *x as u64).sum();
let mean = total as f64 / n as f64;
let var = py_sum(samples.iter().map(|x| pow(*x as f64 - mean, 2.0))) / (n - 1) as f64;
let most = freq.get(freq.mode());
let measured = entropy::mcv_min_entropy(samples);
let modelled = entropy::poisson_min_entropy(mean);
let bits = entropy::ENTROPY_BITS;
Some(Budget {
n,
mean,
var,
dispersion: if mean != 0.0 { var / mean } else { 0.0 },
pmax: most as f64 / n as f64,
measured,
modelled,
ratio: if measured != 0.0 { modelled / measured } else { 0.0 },
freq,
seconds_for: (measured != 0.0).then(|| bits / measured),
seconds_modelled: (modelled != 0.0).then(|| bits / modelled),
})
}
pub fn svg_hist(freq: &Freq, lam: f64) -> String {
let (width, height, pad_l, pad_b, pad_t, pad_r) = (1120i64, 340i64, 54i64, 34i64, 14i64, 12i64);
let n: usize = freq.counts.values().sum();
if n == 0 {
return String::new();
}
let top = freq.counts.keys().next_back().copied().unwrap_or(0);
let kmax = top.max(8).min(12);
let lo = 1e-5f64;
let hi = 1.0f64;
let span = hi.log10() - lo.log10();
let iw = width - pad_l - pad_r;
let ih = height - pad_t - pad_b;
let slot = iw as f64 / (kmax + 1) as f64;
let bw = slot * 0.36;
let y_of = |p: f64| pad_t as f64 + ih as f64 * (1.0 - (pymax(p, lo).log10() - lo.log10()) / span);
let mut out = vec![format!(
"<svg class=\"plot hist\" viewBox=\"0 0 {} {}\" width=\"100%\" \
preserveAspectRatio=\"xMidYMid meet\" role=\"img\" aria-label=\"\
observed counts per second against the Poisson model\">",
width, height
)];
for decade in [1.0, 0.1, 0.01, 0.001, 0.0001, 0.00001] {
let y = y_of(decade);
out.push(format!(
"<line class=\"grid\" x1=\"{}\" y1=\"{}\" x2=\"{}\" y2=\"{}\"/>",
pad_l, f(1, y), width - pad_r, f(1, y)
));
out.push(format!(
"<text class=\"ylab\" x=\"{}\" y=\"{}\">{}</text>",
pad_l - 8,
f(1, y + 4.0),
if decade >= 0.001 { log::g(decade) } else { e0(decade) }
));
}
let base = y_of(lo);
for k in 0..=kmax {
let x = pad_l as f64 + slot * k as f64 + slot / 2.0;
let bars = [
(poisson_pmf(lam, k), "modelled"),
(freq.get(k) as f64 / n as f64, "seen"),
];
for (i, (p, cls)) in bars.iter().enumerate() {
if *p <= 0.0 {
continue;
}
let y = y_of(*p);
out.push(format!(
"<rect class=\"{}\" x=\"{}\" y=\"{}\" width=\"{}\" height=\"{}\"/>",
cls,
f(1, x + (i as i64 - 1) as f64 * bw),
f(1, y),
f(1, bw),
f(1, pymax(0.0, base - y))
));
}
out.push(format!(
"<text class=\"xlab\" x=\"{}\" y=\"{}\">{}</text>",
f(1, x),
height - 12,
k
));
}
out.push(format!(
"<text class=\"xcap\" x=\"{}\" y=\"{}\">counts in one second</text>",
pad_l,
height - 1
));
out.push(format!(
"<text class=\"ycap\" x=\"{}\" y=\"{}\">share of seconds</text>",
pad_l - 46,
pad_t - 2
));
out.push("</svg>".to_string());
out.concat()
}
pub fn svg_bits(samples: &[u32]) -> String {
let want = ENTROPY_BITS;
let (width, height, pad_l, pad_b, pad_t, pad_r) = (1120i64, 320i64, 54i64, 34i64, 14i64, 12i64);
let n = samples.len();
if n < 30 {
return String::new();
}
let step = (n / 240).max(1);
let mut xs: Vec<usize> = Vec::new();
let mut meas: Vec<f64> = Vec::new();
let mut model: Vec<f64> = Vec::new();
let mut pool = entropy::Entropy::new(want as f64);
for (i, x) in samples.iter().enumerate() {
let i = i + 1;
pool.add(*x);
if i % step != 0 && i != n {
continue;
}
xs.push(i);
meas.push(pool.bits());
model.push(entropy::poisson_min_entropy(pool.rate()) * i as f64);
}
let top = model.iter().copied().fold(model[0], |a, b| if b > a { b } else { a });
let hi = pymax(top, want as f64) * 1.05;
let iw = width - pad_l - pad_r;
let ih = height - pad_t - pad_b;
let x_of = |t: usize| pad_l as f64 + (iw * t as i64) as f64 / n as f64;
let y_of = |v: f64| pad_t as f64 + ih as f64 * (1.0 - v / hi);
let path = |ys: &[f64]| -> String {
xs.iter()
.zip(ys)
.enumerate()
.map(|(i, (x, y))| {
format!("{}{} {}", if i == 0 { "M" } else { "L" }, f(1, x_of(*x)), f(1, y_of(*y)))
})
.collect::<Vec<_>>()
.join(" ")
};
let mut out = vec![format!(
"<svg class=\"plot bits\" viewBox=\"0 0 {} {}\" width=\"100%\" \
preserveAspectRatio=\"xMidYMid meet\" role=\"img\" aria-label=\"\
bits of min-entropy accumulating against seconds\">",
width, height
)];
let tick = [64i64, 128, 256, 512, 1024]
.iter()
.copied()
.find(|t| hi / *t as f64 <= 8.0)
.unwrap_or(1024);
let mut v = 0i64;
while v as f64 <= hi {
let y = y_of(v as f64);
out.push(format!(
"<line class=\"grid\" x1=\"{}\" y1=\"{}\" x2=\"{}\" y2=\"{}\"/>",
pad_l, f(1, y), width - pad_r, f(1, y)
));
out.push(format!(
"<text class=\"ylab\" x=\"{}\" y=\"{}\">{}</text>",
pad_l - 8,
f(1, y + 4.0),
v
));
v += tick;
}
out.push(format!(
"<line class=\"target\" x1=\"{}\" y1=\"{}\" x2=\"{}\" y2=\"{}\"/>",
pad_l,
f(1, y_of(want as f64)),
width - pad_r,
f(1, y_of(want as f64))
));
let every = ((n / 8 / 60).max(1) * 60).max(60);
for t in (every..=n).step_by(every) {
out.push(format!(
"<text class=\"xlab\" x=\"{}\" y=\"{}\">{}s</text>",
f(1, x_of(t)),
height - 12,
t
));
}
out.push(format!("<path class=\"peak\" d=\"{}\"/>", path(&model)));
out.push(format!("<path class=\"mean\" d=\"{}\"/>", path(&meas)));
out.push(format!(
"<text class=\"ycap\" x=\"{}\" y=\"{}\">bits</text>",
pad_l - 46,
pad_t - 2
));
out.push("</svg>".to_string());
out.concat()
}
const VIEWER_JS: &str = include_str!("frames.js");
fn esc_payload(text: &str) -> String {
text.replace("</", "<\\/")
}
fn json_meta(serial: &str, audit: &Audit) -> String {
format!(
"{{\"version\":{},\"serial\":{},\"place\":{},\"fix\":{},\"summary\":{}}}",
json_str(VERSION),
json_str(serial),
json_str(&audit.place),
json_str(&audit.fix),
json_str(&audit.summary())
)
}
fn json_str(s: &str) -> String {
let mut out = String::with_capacity(s.len() + 2);
out.push('"');
for c in s.chars() {
match c {
'"' => out.push_str("\\\""),
'\\' => out.push_str("\\\\"),
'\n' => out.push_str("\\n"),
'\r' => out.push_str("\\r"),
'\t' => out.push_str("\\t"),
'<' => out.push_str("\\u003c"),
c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)),
c => out.push(c),
}
}
out.push('"');
out
}
const RANDOM_CSS: &[&str] = &[
".hist .seen{fill:var(--accent)}",
".hist .modelled{fill:var(--dim);opacity:.45}",
".bits .target{stroke:var(--warn);stroke-width:1;stroke-dasharray:4 3}",
".plot .xcap{text-anchor:start;font-size:10px;letter-spacing:.05em;\
text-transform:uppercase}",
".ledger{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;\
font-size:.78rem;word-break:break-all}",
".budget td:first-child{width:52%}",
".note{color:var(--dim);font-size:.85rem;max-width:68ch}",
];
pub struct Audit {
pub place: String,
pub fix: String,
pub joined: String,
pub frames: String,
pub embedded: Vec<String>,
pub files: Vec<(String, u64)>,
pub siblings: Vec<String>,
}
impl Audit {
pub fn summary(&self) -> String {
let embedded = self.embedded.len();
let files = self.files.len();
format!(
"{} emission file{} on record; {} month{} of raw seconds carried in \
this page.",
files,
if files == 1 { "" } else { "s" },
embedded,
if embedded == 1 { "" } else { "s" }
)
}
pub fn bare() -> Audit {
Audit {
place: String::new(), fix: String::new(), joined: String::new(),
frames: String::new(), embedded: Vec::new(), files: Vec::new(),
siblings: Vec::new(),
}
}
}
fn bytes_text(n: u64) -> String {
if n >= 1024 * 1024 {
format!("{} MiB", f(1, n as f64 / (1024.0 * 1024.0)))
} else if n >= 1024 {
format!("{} KiB", f(1, n as f64 / 1024.0))
} else {
format!("{} B", n)
}
}
pub fn render_random_html(serial: &str, pools: &[entropy::Emission], title: &str, index: &str,
audit: &Audit) -> String {
let samples: Vec<u32> = pools.iter().flat_map(|p| p.counts.iter().copied()).collect();
let budget = entropy_budget(&samples);
let mut out = page_head(title, RANDOM_CSS);
macro_rules! a {
($($arg:tt)*) => { out.push(format!($($arg)*)) };
}
a!("<h1>{}</h1>", esc(title));
a!(
"<p class=\"sub\">radbeeper {} · counter {} · {}{} · generated {}</p>",
VERSION,
esc(serial),
pools.len(),
if pools.len() == 1 { " emission" } else { " emissions" },
esc(&clock::format(now(), "%Y-%m-%d %H:%M"))
);
if !audit.place.is_empty() || !audit.fix.is_empty() {
a!("<p class=\"sub\">{}{}{}</p>",
if audit.place.is_empty() { String::new() } else { format!("at {}", esc(&audit.place)) },
if !audit.place.is_empty() && !audit.fix.is_empty() { " · " } else { "" },
if audit.fix.is_empty() { String::new() } else { format!("<span title=\"rounded when it was recorded, not when it was shown\">{}</span>", esc(&audit.fix)) });
}
a!("<p class=\"lede\">The moment a nucleus decays is not determined by \
anything, which makes a Geiger–Müller counter the textbook \
hardware entropy source. What is <em>not</em> textbook is how much \
randomness survives the journey down a serial cable, and that is what \
this page is for. \
<a href=\"{}\">Back to the monitor</a>.</p>", esc(index));
if !audit.siblings.is_empty() {
let n = audit.siblings.len() + 1;
a!("<h2>The braid: {} tubes, one record</h2>", n);
a!("<p class=\"lede\"><b>Braided decay.</b> This machine is watching \
{} independent tubes, and their seconds are brokered into one \
interleaved record — the braid — rather than being \
averaged into one number. Each strand stays whole and stays \
attributable, which is what makes the arrangement worth more than \
a second opinion.</p>", n);
a!("<div class=\"tablewrap\"><table class=\"budget\"><tbody>");
let rows: Vec<(String, String)> = vec![
("Tubes braided".into(),
format!("<b>{}</b> — this page is {}; the others are {}",
n, esc(serial),
audit.siblings.iter().map(|s| esc(s)).collect::<Vec<_>>().join(", "))),
("Lines per hour".into(),
format!("<b>{}×</b> a single tube. Each tube fills its own pool at its own rate, so {} pools reach {} bits {} times as often as one does", n, n, ENTROPY_BITS, n)),
("What the braid is".into(),
"the <a href=\"docs/cascade.html\">cascade</a>: whole seconds, interleaved in arrival order, one tier per tube. Nothing is summed, so a second can always be traced back to the tube that counted it".into()),
("What it is <em>not</em>".into(),
"<b>one key out of two tubes.</b> The digest of an emission is taken over the counts of a single tube, and deliberately: a key mixed from two sources cannot be recomputed from either one, so nobody downstream could ever check it. Independence is spent on <em>confidence</em> here, not on the bits".into()),
("What it buys instead".into(),
"<b>a witness.</b> Two tubes in one room should agree, to within counting statistics. When they stop agreeing, one of them is wrong — drifting, dying, shielded, or being pointed at something — and a single tube cannot tell you that about itself at any price. The monitor prints the agreement as a z-score".into()),
];
for (k, v) in &rows {
a!("<tr><th>{}</th><td>{}</td></tr>", k, v);
}
a!("</tbody></table></div>");
a!("<p class=\"note\">The catchphrase is doing real work, so it is \
worth unpacking once: <b>a braid, not a blend.</b> A blend would \
average the tubes and throw away which was which; the braid keeps \
every strand separate and legible along its whole length, and \
gets its strength from the fact that the strands were spun \
independently.</p>");
}
let b = match budget {
Some(b) => b,
None => {
a!("<p>No emissions recorded yet.</p>");
a!("</main></body></html>");
return out.join("\n");
}
};
a!("<h2>What the serial link gives you</h2>");
a!("<p class=\"note\">Everything below follows from one line of the \
protocol. <code><HEARTBEAT1>></code> makes the counter send \
<b>two bytes once per second</b>, and those two bytes are a count: \
how many arrivals landed in that second. The device drives the clock, \
so there is no drift between its second and ours — but there is \
also nothing finer. <b>One integer per second is the entire raw \
material.</b></p>");
a!("<div class=\"tablewrap\"><table class=\"budget\"><tbody>");
let secs = |v: Option<f64>| v.map(|s| f(0, s)).unwrap_or_else(|| "--".to_string());
let rows: Vec<(String, String)> = vec![
("Link".into(), "115200 baud — not the limit, and never has been".into()),
("What arrives".into(), "2 bytes per second, masked to 14 bits of count".into()),
("Sampling resolution".into(), "<b>1 second</b>, the finest the protocol offers".into()),
("Samples measured here".into(), commas(b.n as i64)),
("Mean".into(), format!("{} counts per second", f(3, b.mean))),
("Variance".into(), format!("{} — Poisson requires this to equal the mean", f(3, b.var))),
("Variance / mean".into(), format!("<b>{}</b>, so the arrivals are over-dispersed", f(2, b.dispersion))),
(
"Most common value".into(),
format!("{} counts, in {}% of seconds", b.freq.mode(), f(1, 100.0 * b.pmax)),
),
(
"Min-entropy, measured".into(),
format!("<b>{} bits per second</b> (SP 800-90B, 99% bound)", f(3, b.measured)),
),
(
"Min-entropy, Poisson model".into(),
format!("{} bits per second — {}× too generous", f(3, b.modelled), f(1, b.ratio)),
),
(
format!("Seconds for {} bits", ENTROPY_BITS),
format!(
"<b>{} s</b> measured, against {} s the model would have claimed",
secs(b.seconds_for),
secs(b.seconds_modelled)
),
),
];
for (k, v) in rows {
a!("<tr><td>{}</td><td>{}</td></tr>", k, v);
}
a!("</tbody></table></div>");
a!("<h2>Why the spectrum contributes nothing</h2>");
a!("<p class=\"note\">The monitor accumulates a power spectrum of the same \
per-second counts, and it would be easy to think the bits come partly \
from there. They do not, and cannot. The FFT is a <b>deterministic \
function</b> of the samples, and for any deterministic \
<i>f</i>, H<sub>∞</sub>(<i>f</i>(X)) ≤ H<sub>∞</sub>(X): \
a transform moves information about, it does not make any. Worse, \
these coefficients come from a mean-subtracted, Hann-tapered window, \
so neighbouring bins are correlated by construction — bits \
pulled from them would look beautiful and carry less than they \
appear to. <b>The entropy is in the counts. The spectrum is a \
view of them</b>, used as a health check: a peak means something \
periodic is contaminating the arrivals, and the emission is marked \
suspect.</p>");
a!("<h2>The counts, against the model that was assumed</h2>");
a!("<div class=\"plotwrap\">");
out.push(svg_hist(&b.freq, b.mean));
a!("</div>");
a!("<div class=\"legend\"><span><i style=\"border-color:var(--accent)\"></i>\
observed</span><span><i style=\"border-color:var(--dim)\"></i>\
Poisson at the same mean</span></div>");
let mut worst: Option<(u32, f64)> = None;
for (k, count) in b.freq.counts.iter() {
if *k < 3 {
continue;
}
let o = *count as f64 / b.n as f64;
let e = poisson_pmf(b.mean, *k);
if e * b.n as f64 >= 1.0 {
let r = o / e;
if worst.map(|w| r > w.1).unwrap_or(true) {
worst = Some((*k, r));
}
}
}
let empty = 100.0
* (b.freq.get(0) as f64 / b.n as f64 / pymax(poisson_pmf(b.mean, 0), 1e-12) - 1.0);
a!(
"<p class=\"note\">Empty seconds are <b>{}% more common</b> than \
Poisson allows, and the tail runs far past it{}. Both push in the \
same direction: an over-dispersed distribution is piled onto its \
mode, and the mode is exactly what min-entropy is about. That is why \
the measured figure is smaller than the modelled one, not larger.",
f(0, empty),
match worst {
Some((k, r)) => format!(
" — {} counts in a second happens {}× more often \
than the model says it should",
k,
f(0, r)
),
None => String::new(),
}
);
let chart = svg_bits(&samples);
if !chart.is_empty() {
a!("<h2>How the bits accumulate</h2>");
a!("<div class=\"plotwrap\">{}</div>", chart);
a!("<div class=\"legend\"><span><i style=\"border-color:var(--accent)\">\
</i>measured</span><span><i style=\"border-color:var(--warn)\">\
</i>Poisson model</span></div>");
a!("<p class=\"note\">Every second recorded here, run as one pool. The \
measured line is flat at first because the confidence bound has \
nothing to say until there are about a dozen samples; it then \
straightens as the estimate settles, and where it crosses the \
dashed target a line is emitted. The modelled line reaches that \
height in roughly half the time, which is precisely the error \
this replaced — and why the pools listed below, collected \
while the model was believed, all stop short of it.</p>");
}
let lam = b.mean;
let per_ms = if lam > 0.0 { -log_2(1.0 - (-lam * 0.001).exp()) } else { 0.0 };
a!("<h2>What the resolution costs</h2>");
a!(
"<p class=\"note\">Bucketing arrivals into whole seconds throws most of \
the randomness away, and it is worth knowing how much. If the link \
reported the <em>time</em> of each arrival rather than a count per \
second, the gap between two arrivals would be exponential, and \
quantised to a millisecond it would carry about \
<b>{} bits per arrival</b> — roughly {} bits a second at \
this background rate, against the {} actually available. The \
counter's protocol has no such message: <code><GETCPS>></code> \
and the heartbeat both answer with a count, never a timestamp. So \
this is not a limit of the physics or of the tube. <b>It is the \
cost of the interface</b>, and the honest thing is to measure what \
gets through it rather than to claim the ceiling.</p>",
f(1, per_ms),
f(0, per_ms * lam),
f(2, b.measured)
);
a!("<h2>Every line, and the counts behind it</h2>");
a!("<p class=\"note\">Reproducible is not the same as predictable. Each \
emission is SHA-256 over a label, its sequence number, the second the \
pool opened, and the counts — all of which are here, so anyone \
can recompute a past line and see it was not invented. That says \
nothing whatever about the next one, which comes from decays that \
have not happened.</p>");
a!("<pre>radbeeper random --check {}</pre>", esc(&format!("random-{}.tsv", serial)));
a!("<div class=\"tablewrap\"><table><thead><tr>\
<th>seq</th><th>opened</th><th>s</th><th>counts/s</th>\
<th>bits, measured</th><th>Poisson</th><th>flat</th>\
</tr></thead><tbody>");
let mut stale = false;
for p in pools.iter().rev() {
let mut when = p.time.as_str();
if when < "2000" {
when = "not kept";
stale = true;
}
let measured = entropy::mcv_min_entropy(&p.counts) * p.counts.len() as f64;
let modelled = entropy::poisson_min_entropy(p.rate) * p.counts.len() as f64;
a!(
"<tr><td>{}</td><td>{}</td><td>{}</td><td>{}</td><td><b>{}</b></td><td>{}</td><td>{}</td></tr>",
p.seq,
esc(when),
p.seconds,
f(3, p.rate),
f(0, measured),
f(0, modelled),
if p.flat { "yes" } else { "<b>no</b>" }
);
a!("<tr><td colspan=\"7\" class=\"ledger\">{}</td></tr>", esc(&entropy::group_hex(&p.hex)));
}
a!("</tbody></table></div>");
if stale {
a!("<p class=\"note\">Rows marked <b>not kept</b> were written by a \
build that recorded <code>time.monotonic()</code> — seconds \
since this machine booted — where the wall clock belonged, \
so they dated themselves to 1969. The digest used the same \
number, so those lines still recompute; it was the label that \
was wrong, and it is fixed. Those rows also stopped collecting on \
the Poisson figure, which is why their measured column falls \
short of {} — they are the evidence, not a warning.</p>", ENTROPY_BITS);
}
a!("<p class=\"note\"><b>Treat this as a good physical entropy source, not \
a certified one.</b> It has not been through a statistical test \
battery, and {} bits of measured min-entropy is a claim about the \
samples that were seen, not a proof about the output.</p>", ENTROPY_BITS);
a!("<h2>Where these photons were</h2>");
a!("<p class=\"note\">A tube counts what arrives, and what arrives \
depends on where it is standing. Granite gives more than chalk, \
altitude gives more than sea level, and a cellar gives less than \
either — so a count rate without a place is a number nobody \
else can use. The place is recorded against the counter's serial \
number <em>over time</em>, because these things get carried about: \
a reading from last month resolves to where the counter was last \
month, not to where it is now.</p>");
if audit.fix.is_empty() {
a!("<p class=\"note\">No fix has been recorded for this counter. \
<code>radbeeper site --name \"the north window\" --at \
51.317,0.891</code> writes one.</p>");
}
a!("<p class=\"note\"><b>The precision is the privacy control, and it is \
applied on the way in.</b> A fix is rounded when it is written down, \
not when it is displayed, so the file cannot be made to give up a \
precision it was never told. Three decimal places — about 110 \
m — is the default and is as fine as a fixed monitoring station \
needs: enough to put it on a map and compare it with somebody else's, \
not enough to knock on. One place is a town, two a district, four a \
building, six a doorstep.</p>");
a!("<h2>Every second, as it was counted</h2>");
a!("<p class=\"note\">The table below is one row per emission, joined to \
the count log that was running at the time. Click a row to open the \
raw seconds behind it. Drag across the chart to narrow the range, \
drag its edges to resize, scroll to zoom.</p>");
a!("<p class=\"note\"><b>The chain column is the point of it.</b> Every \
emission carries <code>link = H(previous link || this key)</code>, so \
the emissions form a hash chain: any one of them can still be \
recomputed from its own counts, and the chain additionally says that \
they were emitted <em>in this order</em> and that none has been taken \
out. Per-emission integrity cannot see a deletion. The chain can. It \
is tamper-<em>evidence</em> and not tamper-proofing — anybody \
who can rewrite the file can recompute the whole chain — but \
the realistic accident is a truncated copy or a log stitched back \
together wrongly, and it catches those.</p>");
a!("<p class=\"note\">The link is hashed <em>alongside</em> the key and \
never into it. Folding it in would change every hex line this program \
has ever produced and would make each one uncheckable by the \
reference implementation, which knows nothing about chains.</p>");
a!("<div id=\"rb-viewer\"></div>");
a!("<script id=\"rb-meta\" type=\"application/json\">{}</script>",
json_meta(serial, audit));
a!("<script id=\"rb-joined\" type=\"text/tab-separated-values\">{}</script>",
esc_payload(&audit.joined));
a!("<script id=\"rb-frames\" type=\"text/plain\">{}</script>",
audit.frames.trim_end());
a!("<script>{}</script>", VIEWER_JS);
if !audit.files.is_empty() {
a!("<h2>Take the evidence with you</h2>");
a!("<p class=\"note\">Nothing on this page is a summary you have to \
take on trust. These are the files it was built from.</p>");
a!("<div class=\"tablewrap\"><table class=\"budget\"><tbody>");
for (name, size) in &audit.files {
let what = if name.ends_with(".bin") {
"the raw seconds, one byte each — open it in the viewer above, or <code>radbeeper random --frames</code>"
} else if name.ends_with(".hex") {
"the digits alone, one line per emission"
} else {
"the audit trail: every emission with the counts it came from — <code>radbeeper random --check</code> recomputes them"
};
a!("<tr><th><a href=\"logs/{}\">{}</a></th><td>{} — {}</td></tr>",
esc(name), esc(name), bytes_text(*size), what);
}
a!("</tbody></table></div>");
if audit.embedded.is_empty() {
a!("<p class=\"note\">No frames are embedded in this page: the \
viewer above is showing the summary rows only. The raw \
seconds are in the <code>.bin</code> files.</p>");
} else {
a!("<p class=\"note\">{} of those are carried <em>inside</em> this \
page, so a copy saved to a disk still audits with nothing to \
fetch and no server to fetch it from: {}. Older months stay in \
the files.</p>",
audit.embedded.len(),
audit.embedded.iter().map(|n| format!("<code>{}</code>", esc(n)))
.collect::<Vec<_>>().join(", "));
}
}
a!("<footer>Generated by <code>radbeeper export</code> \
{}. <a href=\"{}\">Back to the monitor</a>. \
· MIT License — Copyright (c) 2026 Paul Richeson\
</footer>", VERSION, esc(index));
a!("</main></body></html>");
out.join("\n")
}
pub struct Report {
pub index: PathBuf,
pub counters: usize,
pub rows: u64,
pub randoms: Vec<(PathBuf, usize)>,
}
pub fn export(
logs: &Path,
output: &Path,
random_page: bool,
cpm_per_usvh: f64,
title: &str,
random_output: Option<&Path>,
frame_budget: u64,
) -> io::Result<Report> {
let mut counters = summarise(logs, cpm_per_usvh);
let out = path_str(output);
let out_dir = dirname(&abspath(&out));
for (serial, path) in log::files(logs) {
if let Some(c) = counters.get_mut(&serial) {
let p = path_str(&path);
c.links.push((basename(&p).to_string(), relpath(&p, &out_dir)));
}
}
let sites = log::read_sites(logs);
let mut shots = BTreeMap::new();
for name in SHOTS {
let ext = if name == "watch-20s" { ".gif" } else { ".png" };
let rel = format!("docs/screenshots/{}{}", name, ext);
if Path::new(&join(&out_dir, &rel)).exists() {
shots.insert(name.to_string(), rel);
}
}
let randoms: Vec<(String, Vec<entropy::Emission>)> = random_files(logs)
.into_iter()
.map(|(serial, path)| (serial, entropy::read_emissions(&path)))
.filter(|(_, pools)| !pools.is_empty())
.collect();
let mut random_pages: Vec<(String, String, usize)> = Vec::new();
if random_page {
let site_rows = log::read_site_rows(logs);
let every: Vec<String> = randoms.iter().map(|(s, _)| s.clone()).collect();
for (i, (serial, pools)) in randoms.iter().enumerate() {
let target = if i == 0 {
match random_output.filter(|p| !p.as_os_str().is_empty()) {
Some(p) => path_str(p),
None => join(&out_dir, "random.html"),
}
} else {
join(&out_dir, &format!("random-{}.html", serial))
};
let last = pools.last().and_then(|p| clock::parse_stamp(&p.time))
.unwrap_or_else(now);
let here = log::site_row_at(serial, last, &site_rows);
let joined = audit::join(logs, serial, pools, cpm_per_usvh);
let mut head = vec![
format!("radbeeper {} -- counter {}", VERSION, serial),
format!("emissions {}", pools.len()),
];
if let Some(h) = here.as_ref() {
head.push(format!("place {}", h.name));
let fix = h.fix(log::FIX_PRECISION);
if !fix.is_empty() {
head.push(format!("fix {}", fix));
}
}
head.push(
"counts is clamped at fifteen a second, as the emission log \
records it; the .bin frames hold it unclamped".into(),
);
let tsv = audit::joined_tsv(&joined, &head);
let table = join(&out_dir, &format!("frames-{}.tsv", serial));
fs::write(&table, &tsv)?;
let embed = audit::frames_to_embed(logs, serial, frame_budget);
let audit_data = Audit {
place: here.as_ref().map(|h| h.name.clone()).unwrap_or_default(),
fix: here.as_ref().map(|h| h.fix(log::FIX_PRECISION))
.unwrap_or_default(),
joined: tsv,
frames: audit::base64(&audit::frames_bytes(&embed)),
embedded: embed.iter()
.map(|p| basename(&path_str(p)).to_string()).collect(),
files: audit::downloads(logs, serial),
siblings: every.iter().filter(|s| *s != serial).cloned().collect(),
};
fs::write(&target, render_random_html(serial, pools, RANDOM_TITLE,
basename(&out), &audit_data))?;
random_pages.push((serial.clone(), target, pools.len()));
}
}
let links: BTreeMap<String, String> = random_pages
.iter()
.map(|(serial, p, _)| (serial.clone(), relpath(p, &out_dir)))
.collect();
let merge = merged(logs, cpm_per_usvh);
let html = render_html(&counters, &sites, cpm_per_usvh, title, &shots, &links,
merge.as_ref());
fs::write(output, html)?;
Ok(Report {
index: output.to_path_buf(),
counters: counters.len(),
rows: counters.values().map(|c| c.rows).sum(),
randoms: random_pages
.into_iter()
.map(|(_, p, n)| (PathBuf::from(p), n))
.collect(),
})
}
pub fn run(
logs: &Path,
output: &Path,
random_page: bool,
cpm_per_usvh: f64,
title: &str,
random_output: Option<&Path>,
frame_budget: u64,
) -> i32 {
match export(logs, output, random_page, cpm_per_usvh, title, random_output,
frame_budget) {
Ok(r) => {
println!(
"radbeeper: {} -- {} counter{}, {} rows",
r.index.display(),
r.counters,
if r.counters == 1 { "" } else { "s" },
r.rows
);
for (p, n) in &r.randoms {
println!(
"radbeeper: {} -- {} emission{}",
p.display(),
n,
if *n == 1 { "" } else { "s" }
);
}
0
}
Err(e) => {
eprintln!("radbeeper: export: {}", e);
1
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_merged_record_is_written_and_read_back_whole() {
let spans = [3.0, 30.0, 300.0];
let dir = std::env::temp_dir()
.join(format!("radbeeper-export-merged-{}", std::process::id()));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
let mut text = log::merged_header(&spans);
for (i, counts) in [30u64, 60, 90].iter().enumerate() {
text.push('\n');
text.push_str(&log::merged_row(
1_700_000_000.0 + 30.0 * i as f64,
2,
Some(0.5),
*counts,
30.0,
60.0,
&[Some(*counts as f64), Some(*counts as f64), None],
Some(1.0),
&[None, None, None],
&[("AAA".into(), counts / 2), ("BBB".into(), counts / 2)],
log::SRC_LIVE,
"",
));
}
fs::write(dir.join("cpm-merged-2023-11.tsv"), text).unwrap();
let m = merged(&dir, 100.0).expect("a merged log was written");
assert_eq!(m.rows, 3);
assert_eq!(m.tubes, 2);
assert_eq!(m.counts, 180);
assert_eq!(m.seconds, 90.0);
assert_eq!(m.tube_seconds, 180.0);
assert!((m.cpm - 60.0).abs() < 1e-9, "{}", m.cpm);
assert!((m.usvh - 0.6).abs() < 1e-9);
assert!((m.sigma - 60.0 / 180.0f64.sqrt()).abs() < 1e-9, "{}", m.sigma);
assert_eq!(m.interleave, Some(0.5));
assert!((analysis::interleave_quality(m.interleave.unwrap(), m.tubes) - 1.0).abs() < 1e-9);
assert!(summarise(&dir, 100.0).is_empty());
assert!(merged(&dir.join("nowhere"), 100.0).is_none());
let _ = fs::remove_dir_all(&dir);
}
#[test]
fn two_tubes_report_the_mean_rate_and_not_the_sum() {
let mut counters = BTreeMap::new();
for serial in ["A", "B"] {
counters.insert(
serial.to_string(),
Counter {
serial: serial.to_string(),
counts: 1000,
seconds: 1000.0,
..Counter::default()
},
);
}
let t = together(&counters, 100.0).expect("two tubes with counts");
assert_eq!(t.tubes, 2);
assert!((t.cpm - 60.0).abs() < 1e-9, "the mean rate, not the sum: {}", t.cpm);
assert_eq!(t.counts, 2000, "both tubes' arrivals are behind it");
assert!((t.sigma - 60.0 / 2000f64.sqrt()).abs() < 1e-9);
let one = 60.0 / 1000f64.sqrt();
assert!(t.sigma < one, "the pair is the more precise");
assert!(((one / t.sigma) - 2f64.sqrt()).abs() < 1e-9, "by exactly root two");
}
#[test]
fn the_pair_is_asked_whether_it_agrees_with_itself() {
let tube = |counts: i64| Counter { counts, seconds: 1000.0, ..Counter::default() };
let mut same = BTreeMap::new();
same.insert("A".to_string(), tube(1000));
same.insert("B".to_string(), tube(1000));
let (z, _, _) = together(&same, 100.0).unwrap().worst.unwrap();
assert!(z < 2.0, "identical tubes agree, got {} sigma", z);
assert_eq!(agreement(z), "they agree");
let mut apart = BTreeMap::new();
apart.insert("A".to_string(), tube(1000));
apart.insert("B".to_string(), tube(4000));
let (z, _, _) = together(&apart, 100.0).unwrap().worst.unwrap();
assert!(z > 4.0, "four times the rate is not the same measurement");
assert_eq!(agreement(z), "they disagree -- not the same measurement");
}
#[test]
fn one_tube_is_not_asked_to_agree_with_anybody() {
let mut one = BTreeMap::new();
one.insert(
"A".to_string(),
Counter { counts: 1000, seconds: 1000.0, ..Counter::default() },
);
assert!(together(&one, 100.0).is_none());
one.insert("B".to_string(), Counter::default());
assert!(together(&one, 100.0).is_none());
}
#[test]
fn the_overlay_draws_a_line_per_tube_and_nothing_for_one() {
let hours = |base: f64| -> Vec<(f64, f64, Option<f64>)> {
(0..6).map(|i| (i as f64 * 3600.0, base + i as f64, None)).collect()
};
let pair = vec![("A".to_string(), hours(40.0)), ("B".to_string(), hours(44.0))];
let svg = svg_overlay(&pair);
assert!(svg.contains("<svg"), "a pair is a picture");
assert_eq!(svg.matches("class=\"tube t").count(), 2, "one line each");
assert!(svg.contains(">A<") && svg.contains(">B<"), "each line is named");
assert!(svg_overlay(&pair[..1]).is_empty(), "one tube overlays nothing");
let stub = vec![
("A".to_string(), hours(40.0)),
("B".to_string(), vec![(0.0, 40.0, None)]),
];
assert!(svg_overlay(&stub).is_empty(), "a single point is not a line");
}
#[test]
fn numbers_are_written_the_way_python_writes_them() {
assert_eq!(commas(0), "0");
assert_eq!(commas(999), "999");
assert_eq!(commas(1000), "1,000");
assert_eq!(commas(28544), "28,544");
assert_eq!(commas(1234567), "1,234,567");
assert_eq!(e0(0.0001), "1e-04");
assert_eq!(e0(0.00001), "1e-05");
assert_eq!(f(0, 2.5), "2", "half to even, as printf does");
assert_eq!(f(1, 0.25), "0.2");
}
#[test]
fn paths_are_worked_out_the_way_os_path_does() {
assert_eq!(relpath("/a/b/c.tsv", "/a"), "b/c.tsv");
assert_eq!(relpath("/a/logs/x.tsv", "/a/site"), "../logs/x.tsv");
assert_eq!(relpath("/a", "/a"), ".");
assert_eq!(abspath("/a/./b/../c"), "/a/c");
assert_eq!(abspath("/"), "/");
assert_eq!(dirname("/a/b/index.html"), "/a/b");
assert_eq!(dirname("/index.html"), "/");
assert_eq!(join("/", "random.html"), "/random.html");
assert_eq!(basename("out/index.html"), "index.html");
}
#[test]
fn a_tie_for_the_most_common_value_goes_to_the_first_seen() {
assert_eq!(Freq::of(&[2, 1, 1, 2, 0]).mode(), 2);
assert_eq!(Freq::of(&[1, 2, 2, 1]).mode(), 1);
}
#[test]
fn the_compensated_sum_is_not_a_running_total() {
let xs = [1e16, 1.0, -1e16];
assert_eq!(py_sum(xs.iter().copied()), 1.0);
assert_eq!(xs.iter().sum::<f64>(), 0.0);
}
#[test]
fn an_axis_ceiling_is_a_round_number() {
assert_eq!(nice_ceiling(0.0), 1.0);
assert_eq!(nice_ceiling(37.0), 40.0);
assert_eq!(nice_ceiling(100.0), 100.0);
assert_eq!(nice_ceiling(101.0), 150.0);
}
#[test]
fn a_gap_breaks_the_line() {
let series = vec![
(0.0, 40.0, Some(80.0)),
(3600.0, 41.0, None),
(7200.0 * 4.0, 39.0, Some(90.0)),
];
let svg = svg_plot(&series);
let mean = svg.split("class=\"mean\" d=\"").nth(1).unwrap();
assert_eq!(mean.split('"').next().unwrap().matches('M').count(), 2);
}
}