Commit b72d6dd0 authored by Vacaliuc, Bogdan's avatar Vacaliuc, Bogdan
Browse files

slides: pre-hack-a-thon slides 1 (current vs ideal) and 2 (API mapping) 

Adds hand-authored SVG slides for the 2026-04-21 pre-hack-a-thon
meeting, plus rendered PNGs at 1920x1080 for drop-in use in
PowerPoint / Google Slides, plus a small render.sh for
regeneration via cairosvg.

Slide 1 — Current vs Ideal Coupling:
  Left panel (warm tones) shows quicknxsv2 ↔️

 mr_reduction tangle,
  Mantid 6.14/6.15 pin conflict, and scientist-visible consequences
  (GUI/autoreduce R(Q) disagreement, ErrorWeighted vs uniform
  background, synchronous reduction on Qt thread, etc.). Right
  panel (cool tones) shows the modular target: thin UI calling a
  unified mr_core back-end exposing one reduce(), stitch(),
  inspect() API, with pinned Mantid and lr_reduction as a peer
  sharing primitives. Arrow in the middle labelled "Hack-a-thon
  outcome".

Slide 2 — Functional API Mapping:
  Three-column table (phase / mr_reduction ideal / lr_reduction
  new_workflow) covering 10 reduction phases: top-level reduce,
  cross-section filter, peak/ROI, dead-time, per-run reduction,
  resolution, stitch/merge, ASCII output, HTML report, repro
  template. Highlights the "function over form" insight: mr_reduction
  wraps a Mantid PyAlgorithm (MRR, 53 properties); lr_reduction
  implements EventReflectivity in numpy/scipy with optional h5py
  I/O; but the public-API shape is the same. Key-insight footer
  ties to hack-a-thon Day 3 stretch goal: a reduce / inspect /
  stitch / write / report contract.

Both slides are scientist-audience and self-contained — every
claim in the body has source citations in the footer.

Co-Authored-By: default avatarClaude Opus 4.7 (1M context) <noreply@anthropic.com>
parent 4447ffe9

plan/quicknxsv2-modularization/slides/README.md

0 → 100644
+46 −0
Original line number Diff line number Diff line 
# Pre-hack-a-thon slides — Day PRE-2 (2026-04-21)



Scientist-facing slides for the pre-hack-a-thon meeting on

2026-04-21.  Authored in SVG (hand-written; no template dependency)

and rendered to PNG for drop-in use in PowerPoint / Google Slides.



## Files



| Slide | SVG | PNG | Notes |

|---|---|---|---|

| 1 — Current vs. ideal coupling | [slide-1-current-vs-ideal.svg](slide-1-current-vs-ideal.svg) | [slide-1-current-vs-ideal.png](slide-1-current-vs-ideal.png) | Left = today, right = ideal, arrow in middle |

| 2 — API mapping, mr_reduction ↔ lr_reduction | [slide-2-api-mapping.svg](slide-2-api-mapping.svg) | [slide-2-api-mapping.png](slide-2-api-mapping.png) | Three-column table: phase, mr_reduction ideal, lr_reduction:new_workflow |



## Regenerating the PNGs



Requires `cairosvg` (install once with `uv tool install cairosvg`).



```bash

./render.sh

```



`render.sh` simply loops over every `.svg` in this directory and

rewrites the corresponding `.png` at native 1920×1080.  The SVGs are

the source of truth; the PNGs are artifacts.



## Design choices (for future slide authors)



- **Dimensions:** 1920×1080 (16:9 HD).  Fits modern projectors and

  meeting-room displays without scaling.

- **Font:** `Helvetica, Arial, sans-serif` — renders acceptably on

  every platform without needing to embed a font file.

- **Colors:** ORNL-ish navy (`#002E5D`), amber (`#F5C13A`), warm

  warning orange (`#E87722`), calm green (`#53A548`).  Current state

  uses warm tones; ideal/target state uses cool tones.

- **No emoji, no Mermaid:** every graphic is hand-authored SVG so the

  output is deterministic and the XML is editable in any text editor.

- **Footer:** each slide carries source citations (file paths, SHAs)

  so scientists can trace every claim back to code.



## Cross-references



- `../README.md` — knowledge-base reading map

- `../00-executive-summary.md` — the 10-minute orient

- `../10-mantid-algorithms-deep-dive.md` — the physics behind slide 1's "5 silent default disagreements"

- `../11-technical-debt.md` — the item list on the left panel of slide 1

- `../12-parameter-propagation-and-qt-leakage.md` — the Qt-signal timing and class-attr globals that make up the "tangle"

plan/quicknxsv2-modularization/slides/render.sh

0 → 100755
+19 −0
Original line number Diff line number Diff line 
#!/usr/bin/env bash

# Re-render every SVG in this directory to a matching PNG at 1920x1080.

# Requires cairosvg (install with: uv tool install cairosvg).

set -euo pipefail



cd "$(dirname "$0")"



if ! command -v cairosvg >/dev/null 2>&1; then

    echo "cairosvg not found on PATH.  Install with: uv tool install cairosvg" >&2

    exit 1

fi



for svg in *.svg; do

    png="${svg%.svg}.png"

    echo "  render: ${svg} -> ${png}"

    cairosvg "${svg}" -f png -o "${png}" --output-width 1920

done



echo "done."

plan/quicknxsv2-modularization/slides/slide-1-current-vs-ideal.png

0 → 100644
+226 KiB
Loading image diff...

plan/quicknxsv2-modularization/slides/slide-1-current-vs-ideal.svg

0 → 100644
+164 −0
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8"?>

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" width="1920" height="1080" font-family="Helvetica, Arial, sans-serif">

  <!-- Definitions: gradients, markers, filters -->

  <defs>

    <linearGradient id="headerGrad" x1="0" x2="0" y1="0" y2="1">

      <stop offset="0%" stop-color="#002E5D"/>

      <stop offset="100%" stop-color="#004B8D"/>

    </linearGradient>

    <linearGradient id="leftPanel" x1="0" x2="0" y1="0" y2="1">

      <stop offset="0%" stop-color="#FFF6F0"/>

      <stop offset="100%" stop-color="#FDE8D5"/>

    </linearGradient>

    <linearGradient id="rightPanel" x1="0" x2="0" y1="0" y2="1">

      <stop offset="0%" stop-color="#EEF7FB"/>

      <stop offset="100%" stop-color="#D6ECF6"/>

    </linearGradient>

    <linearGradient id="arrowGrad" x1="0" x2="1" y1="0" y2="0">

      <stop offset="0%" stop-color="#E87722"/>

      <stop offset="100%" stop-color="#53A548"/>

    </linearGradient>

    <marker id="arrowHead" viewBox="0 0 16 12" refX="14" refY="6" markerWidth="12" markerHeight="10" orient="auto">

      <path d="M 0 0 L 16 6 L 0 12 z" fill="#53A548"/>

    </marker>

    <marker id="tangleHead" viewBox="0 0 12 9" refX="11" refY="4.5" markerWidth="8" markerHeight="6" orient="auto">

      <path d="M 0 0 L 12 4.5 L 0 9 z" fill="#C8102E"/>

    </marker>

    <marker id="cleanHead" viewBox="0 0 12 9" refX="11" refY="4.5" markerWidth="8" markerHeight="6" orient="auto">

      <path d="M 0 0 L 12 4.5 L 0 9 z" fill="#002E5D"/>

    </marker>

    <filter id="softShadow" x="-10%" y="-10%" width="120%" height="120%">

      <feGaussianBlur in="SourceAlpha" stdDeviation="3"/>

      <feOffset dx="2" dy="3" result="offset"/>

      <feComponentTransfer><feFuncA type="linear" slope="0.25"/></feComponentTransfer>

      <feMerge><feMergeNode/><feMergeNode in="SourceGraphic"/></feMerge>

    </filter>

  </defs>



  <!-- Background -->

  <rect width="1920" height="1080" fill="#FAFAFA"/>



  <!-- Header -->

  <rect x="0" y="0" width="1920" height="110" fill="url(#headerGrad)"/>

  <text x="960" y="62" font-size="40" font-weight="700" fill="white" text-anchor="middle">From Today's Coupling to a Modular Back-End</text>

  <text x="960" y="94" font-size="20" fill="#B8D4E8" text-anchor="middle">quicknxsv2 + mr_reduction — the modularization target of the 2026 hack-a-thon</text>



  <!-- ─── LEFT PANEL: TODAY ─── -->

  <rect x="40" y="140" width="860" height="860" rx="18" fill="url(#leftPanel)" stroke="#E87722" stroke-width="3"/>

  <text x="470" y="192" font-size="36" font-weight="700" fill="#8C3A00" text-anchor="middle">TODAY — tangled</text>

  <text x="470" y="222" font-size="18" fill="#8C3A00" text-anchor="middle" font-style="italic">UI, reduction and Mantid calls weave across repos</text>



  <!-- quicknxsv2 (Qt UI + backend mixed) -->

  <rect x="80" y="260" width="760" height="150" rx="10" fill="#FFFFFF" stroke="#C8102E" stroke-width="2" filter="url(#softShadow)"/>

  <text x="460" y="295" font-size="22" font-weight="700" fill="#002E5D" text-anchor="middle">quicknxsv2 (Qt GUI)</text>

  <text x="460" y="320" font-size="15" fill="#444">src/quicknxs/interfaces/…</text>

  <text x="460" y="345" font-size="14" fill="#8C3A00">• calls Mantid directly (15 sites)  • re-implements DataInfo, peak_finding</text>

  <text x="460" y="365" font-size="14" fill="#8C3A00">• two MRR call sites with different defaults  • two local _as_ints</text>

  <text x="460" y="385" font-size="14" fill="#8C3A00">• class-attr Configuration globals  • QuickNXS post-scaling with ±1.0 drift</text>



  <!-- mr_reduction -->

  <rect x="80" y="440" width="370" height="130" rx="10" fill="#FFFFFF" stroke="#C8102E" stroke-width="2" filter="url(#softShadow)"/>

  <text x="265" y="475" font-size="22" font-weight="700" fill="#002E5D" text-anchor="middle">mr_reduction</text>

  <text x="265" y="498" font-size="15" fill="#444" text-anchor="middle">autoreduce · livereduce · library</text>

  <text x="265" y="523" font-size="13" fill="#8C3A00" text-anchor="middle">ReductionProcess → MRR</text>

  <text x="265" y="543" font-size="13" fill="#8C3A00" text-anchor="middle">different default-value set than the UI path</text>



  <!-- lr_reduction -->

  <rect x="470" y="440" width="370" height="130" rx="10" fill="#FFFFFF" stroke="#C8102E" stroke-width="2" filter="url(#softShadow)"/>

  <text x="655" y="475" font-size="22" font-weight="700" fill="#002E5D" text-anchor="middle">lr_reduction (sibling)</text>

  <text x="655" y="498" font-size="15" fill="#444" text-anchor="middle">REF_L, h5py-centric</text>

  <text x="655" y="523" font-size="13" fill="#8C3A00" text-anchor="middle">registers 3rd copy of</text>

  <text x="655" y="543" font-size="13" fill="#8C3A00" text-anchor="middle">SingleReadoutDeadTimeCorrection</text>



  <!-- Mantid 6.14 / 6.15 pin conflict -->

  <rect x="80" y="600" width="760" height="120" rx="10" fill="#FFFFFF" stroke="#C8102E" stroke-width="2" filter="url(#softShadow)"/>

  <text x="460" y="635" font-size="22" font-weight="700" fill="#002E5D" text-anchor="middle">Mantid — version-pin conflict</text>

  <text x="460" y="665" font-size="16" fill="#444" text-anchor="middle">

    <tspan fill="#8C3A00" font-weight="600">quicknxsv2 → Mantid 6.14</tspan>

    <tspan dx="20" fill="#606060">vs.</tspan>

    <tspan dx="20" fill="#8C3A00" font-weight="600">mr_reduction → Mantid 6.15</tspan>

  </text>

  <text x="460" y="693" font-size="14" fill="#444" text-anchor="middle" font-style="italic">(MR Python algorithms are byte-identical across versions — this is packaging, not science)</text>



  <!-- Tangle lines between the three boxes -->

  <path d="M 300 410 Q 280 425 265 440" stroke="#C8102E" stroke-width="2" fill="none" marker-end="url(#tangleHead)"/>

  <path d="M 500 410 Q 580 425 640 440" stroke="#C8102E" stroke-width="2" fill="none" marker-end="url(#tangleHead)"/>

  <path d="M 265 570 Q 260 585 300 600" stroke="#C8102E" stroke-width="2" fill="none" marker-end="url(#tangleHead)"/>

  <path d="M 655 570 Q 650 585 620 600" stroke="#C8102E" stroke-width="2" fill="none" marker-end="url(#tangleHead)"/>

  <path d="M 300 410 C 500 475 280 495 265 440" stroke="#C8102E" stroke-width="2" stroke-dasharray="4 4" fill="none"/>



  <!-- Consequences box -->

  <rect x="80" y="750" width="760" height="225" rx="10" fill="#FEF4EE" stroke="#E87722" stroke-width="2" stroke-dasharray="6 4"/>

  <text x="100" y="784" font-size="20" font-weight="700" fill="#8C3A00">What scientists see today:</text>

  <text x="100" y="816" font-size="16" fill="#3E2C00">● GUI and autoreduce produce <tspan font-weight="700">numerically different R(Q)</tspan> for the same run</text>

  <text x="100" y="842" font-size="16" fill="#3E2C00">● Background estimates disagree at low S/N (ErrorWeighted vs uniform mean)</text>

  <text x="100" y="868" font-size="16" fill="#3E2C00">● Empty polarization cross-sections — one path shows, the other crashes</text>

  <text x="100" y="894" font-size="16" fill="#3E2C00">● Peak-drag freezes the UI while reduction runs on the Qt thread</text>

  <text x="100" y="920" font-size="16" fill="#3E2C00">● Bug fixes in one codebase don't benefit the other</text>

  <text x="100" y="946" font-size="16" fill="#3E2C00">● New instrument-staff members face a 2-week learning wall to trace any reduction parameter</text>



  <!-- ─── ARROW ─── -->

  <g>

    <path d="M 920 540 L 1000 540 L 1000 500 L 1065 570 L 1000 640 L 1000 600 L 920 600 Z"

          fill="url(#arrowGrad)" stroke="#53A548" stroke-width="2"/>

    <text x="992" y="480" font-size="20" font-weight="700" fill="#002E5D" text-anchor="middle">Hack-a-thon</text>

    <text x="992" y="668" font-size="20" font-weight="700" fill="#002E5D" text-anchor="middle">outcome</text>

  </g>



  <!-- ─── RIGHT PANEL: IDEAL ─── -->

  <rect x="1085" y="140" width="795" height="860" rx="18" fill="url(#rightPanel)" stroke="#53A548" stroke-width="3"/>

  <text x="1482" y="192" font-size="36" font-weight="700" fill="#1F5B1F" text-anchor="middle">IDEAL — modular</text>

  <text x="1482" y="222" font-size="18" fill="#1F5B1F" text-anchor="middle" font-style="italic">one back-end library, UI and autoreduce agree by construction</text>



  <!-- quicknxsv2 UI (thin) -->

  <rect x="1115" y="260" width="735" height="110" rx="10" fill="#FFFFFF" stroke="#53A548" stroke-width="2" filter="url(#softShadow)"/>

  <text x="1482" y="295" font-size="22" font-weight="700" fill="#002E5D" text-anchor="middle">quicknxsv2 — pure UI</text>

  <text x="1482" y="322" font-size="15" fill="#444" text-anchor="middle">Qt widgets, plotting, session state — no Mantid imports</text>

  <text x="1482" y="348" font-size="14" fill="#1F5B1F" text-anchor="middle">calls a single <tspan font-family="monospace" font-weight="700">reduce(configuration)</tspan> function on the back-end</text>



  <!-- Clean arrow down -->

  <path d="M 1482 380 L 1482 410" stroke="#002E5D" stroke-width="3" marker-end="url(#cleanHead)"/>



  <!-- mr_core (shared back-end) -->

  <rect x="1115" y="420" width="735" height="220" rx="10" fill="#FFFFFF" stroke="#002E5D" stroke-width="2.5" filter="url(#softShadow)"/>

  <text x="1482" y="458" font-size="24" font-weight="700" fill="#002E5D" text-anchor="middle">mr_core — shared reduction back-end</text>

  <text x="1482" y="486" font-size="15" fill="#444" text-anchor="middle" font-style="italic">(name TBD: mr_core, mr_backend, reflectometry_core …)</text>

  <rect x="1145" y="505" width="330" height="110" rx="8" fill="#EEF7FB" stroke="#002E5D" stroke-width="1"/>

  <text x="1310" y="535" font-size="17" font-weight="700" fill="#002E5D" text-anchor="middle">Public API</text>

  <text x="1310" y="562" font-size="14" fill="#1F3A5F" text-anchor="middle" font-family="monospace">reduce(ws, config) → ReducedRun</text>

  <text x="1310" y="582" font-size="14" fill="#1F3A5F" text-anchor="middle" font-family="monospace">inspect(ws) → DataInfo</text>

  <text x="1310" y="602" font-size="14" fill="#1F3A5F" text-anchor="middle" font-family="monospace">stitch([runs]) → R(Q)</text>



  <rect x="1490" y="505" width="335" height="110" rx="8" fill="#EEF7FB" stroke="#002E5D" stroke-width="1"/>

  <text x="1657" y="535" font-size="17" font-weight="700" fill="#002E5D" text-anchor="middle">Shared primitives (one copy)</text>

  <text x="1657" y="562" font-size="14" fill="#1F3A5F" text-anchor="middle">dead-time correction · peak finder</text>

  <text x="1657" y="582" font-size="14" fill="#1F3A5F" text-anchor="middle">DataInfo · ORSO · QuickNXS scale</text>

  <text x="1657" y="602" font-size="14" fill="#1F3A5F" text-anchor="middle">one parameter-builder for MRR</text>



  <!-- arrows down to Mantid and peer -->

  <path d="M 1310 650 L 1310 690" stroke="#002E5D" stroke-width="3" marker-end="url(#cleanHead)"/>

  <path d="M 1657 650 L 1657 690" stroke="#002E5D" stroke-width="3" marker-end="url(#cleanHead)"/>



  <!-- Mantid + autoreduce row -->

  <rect x="1115" y="700" width="355" height="110" rx="10" fill="#FFFFFF" stroke="#53A548" stroke-width="2" filter="url(#softShadow)"/>

  <text x="1292" y="735" font-size="22" font-weight="700" fill="#002E5D" text-anchor="middle">Mantid (pinned)</text>

  <text x="1292" y="762" font-size="14" fill="#444" text-anchor="middle">one version range for the whole suite</text>

  <text x="1292" y="786" font-size="13" fill="#1F5B1F" text-anchor="middle">MagnetismReflectometryReduction · RefRoi · Rebin …</text>



  <rect x="1495" y="700" width="355" height="110" rx="10" fill="#FFFFFF" stroke="#53A548" stroke-width="2" filter="url(#softShadow)"/>

  <text x="1672" y="735" font-size="22" font-weight="700" fill="#002E5D" text-anchor="middle">autoreduce · livereduce</text>

  <text x="1672" y="762" font-size="14" fill="#444" text-anchor="middle">import mr_core, call reduce(…)</text>

  <text x="1672" y="786" font-size="13" fill="#1F5B1F" text-anchor="middle">same code path as the GUI, same numbers</text>



  <!-- peer: lr_reduction uses same primitives -->

  <rect x="1115" y="835" width="735" height="150" rx="10" fill="#FDFEFD" stroke="#53A548" stroke-width="2" stroke-dasharray="6 4"/>

  <text x="1482" y="870" font-size="20" font-weight="700" fill="#1F5B1F" text-anchor="middle">Peer: lr_reduction (REF_L)</text>

  <text x="1482" y="898" font-size="15" fill="#444" text-anchor="middle">shares dead-time, peak-finder, DataInfo primitives with mr_core</text>

  <text x="1482" y="922" font-size="15" fill="#444" text-anchor="middle">keeps its own event_reduction algorithm (h5py-centric) — same functional shape</text>

  <text x="1482" y="952" font-size="14" fill="#1F5B1F" text-anchor="middle" font-style="italic">no 3-way AlgorithmFactory registration race; one canonical implementation</text>



  <!-- Footer -->

  <rect x="0" y="1020" width="1920" height="60" fill="#002E5D"/>

  <text x="40" y="1058" font-size="14" fill="#B8D4E8">Sources: plan/quicknxsv2-modularization/ — 10 (MRR internals), 11 (technical debt), 12 (parameter propagation)</text>

  <text x="1880" y="1058" font-size="14" fill="#B8D4E8" text-anchor="end">Reflectometry Hack-a-thon 2026 · pre-meeting slide 1 of 2</text>

</svg>

plan/quicknxsv2-modularization/slides/slide-2-api-mapping.png

0 → 100644
+291 KiB
Loading image diff...