dark-su3

name

dark-su3

description

Constraint-first interactive workflow for the Dark SU(3) dark-Higgs benchmark (arXiv:2506.19062 §IV). SU(3)_D broken to SU(2)_D by a dark Higgs VEV; two DM candidates are the massive dark vector V (tree-level SI) and the dark pseudoscalar Psi (exact parameter-independent SI blind spot). Interviews the user for constraint selection, shows the full prereq chain with [EXISTS]/[PLANNED] annotations, and runs relic density via the analytic backend. Invoke when the user picks Dark SU(3) from /demo or says "run dark-su3".

Dark SU(3)

REGRESSION-ANCHOR ONLY — NOT A PHYSICS TARGET (dsu3-002). Dark-SU(3) relic density runs through the analytic backend (analytic_models.dark_su3) and currently uses <sigma v> approximations (sigmav_approx=True). The emitted Ωh² values are roughly 25000× the Planck target and must be read as regression anchors for the analytic pipeline, not as a physics prediction or a paper-fidelity result. Paper fidelity (Ω_tot h² ≈ 0.12) is out of reach this iteration and requires the upgrade roadmap in analytic_models.dark_su3 (full Boltzmann integration + multi-component weighting in /dark-matter-constraints). Any downstream report that quotes these numbers MUST embed this banner verbatim — do not silently strip it.

Variant note. The canonical dark-su3 model in this marketplace is the Higgsed Arcadi-Profumo dark-Higgs variant (arXiv:2506.19062 §IV), not the older confining-variant template that previously occupied this slot. The confining-variant template — whose DM candidates were a scalar dark pion plus a vector dark meson and whose dynamics relied on dark-color confining hadronization — was archived in commit 2bb56d6 and subsequently deleted in the v3 modelspec rollout, because no production-ready analytic or numerical backend was available for the confining sector. The Higgsed variant is multi-component (V + Psi); the archived confining variant is documented here only so historical references to "scalar dark pion", "vector dark meson", and "confining dark sector" still resolve to a real, intentional design decision.

Per-model constraint workflow for the Dark SU(3) dark-Higgs benchmark from Arcadi & Profumo (arXiv:2506.19062 §IV). The model is SU(3)_D → SU(2)_D Higgsing: a dark Higgs doublet in the fundamental of SU(3)_D acquires a VEV, breaking the gauge group and producing two DM candidates — V, the massive dark gauge boson (spin-1, tree-level SI non-zero), and Psi, the CP-odd component of the dark Higgs doublet (spin-0, exact parameter-independent SI blind spot at tree level).

This is a multi-component dark matter model. Relic density per candidate is available now via analytic_models.dark_su3 (see its header docstring for the current integration method and approximation caveats), driven through the analytic-only branch of /dark-matter-constraints [EXISTS]. Multi-component combination of per-candidate relic densities into a paper-fidelity total Ω_tot h² is on the upgrade roadmap (see the dsu3-002 banner above) — values emitted today are regression anchors only. DD and ID chains remain [COMING SOON] on /feynarts//formcalc (DD) and /gamlike (ID); /dark-matter-constraints itself is EXISTS.

---

When to invoke

• User selects Dark SU(3) from /demo's model picker (Step 3).
• User says "run dark-su3", "compute relic density for dark SU(3)", or similar.
• Do NOT invoke if the preflight check in /demo Step 0 failed (missing config.json keys or unresponsive executables).

---

Model metadata

display:
  title: "Dark SU(3)"
  hook:  "SU(3)_D Higgsed to SU(2)_D; two DM candidates with exact parameter-independent blind spot on Psi."
dm_candidates:
  - {name: V,   spin: "1", notes: "Dark vector DM; tree-level SI via Higgs portal (H_1 + H_2 exchange)."}
  - {name: Psi, spin: "0", notes: "Dark pseudoscalar DM; exact parameter-independent SI blind spot (Eq. 29)."}
plot_axes:
  x: {symbol: "m_V",   range: [1, 1000],  units: "GeV", scale: log}
  y: {symbol: "m_Psi", range: [1, 300],   units: "GeV", scale: log}
multi_component: true
multi_component_prereq: dark-matter-constraints
time_overrides:
  relic: {cold: [1.5, 3.0]}
  dd:    {cold: [3.0, 5.0]}
  id:    {cold: [1.5, 4.0]}

---

Constraints and time estimates

Prereq chains and time ranges are resolved from plugins/hep-ph-toolkit/skills/_shared/constraints.yaml (model dark-su3). The table below is generated by running:

python3 plugins/hep-ph-toolkit/skills/_shared/time_budget.py \
    --model dark-su3 --constraints relic dd id

Constraint	Status	Chain	Cold (hr)	Cached (hr)
Relic density	READY (analytic-only branch)	/sarah-build [EXISTS] → /spheno-build [EXISTS] → /dark-matter-constraints [EXISTS]	1.5–3	0.3–0.7
Direct detection	COMING SOON — loop-DD chain integration pending; multi-component combiner pending	/sarah-build [EXISTS] → /spheno-build [EXISTS] → /madgraph [EXISTS] → /feynarts [EXISTS] → /formcalc [EXISTS] → /ddcalc [EXISTS] → /dark-matter-constraints [EXISTS]	3–5	0.5–1
Indirect detection	COMING SOON — /gamlike [v0 — parser only; pull-computation v1+] (parser shipped; pull-computation v1+)	/sarah-build [EXISTS] → /spheno-build [EXISTS] → /madgraph [EXISTS] → /maddm [EXISTS] → /gamlike [v0 — parser only; pull-computation v1+] → /dark-matter-constraints [EXISTS]	1.5–4	0.3–0.7

All-constraints cold total (overlap-adjusted, hypothetical if all prereqs existed): 3.5–9 hr. Selected + ready (relic only): cold ~1–3 hr, cached ~0.3–0.6 hr.

Relic is unblocked via the analytic-only branch in /dark-matter-constraints (per _shared/constraints.yaml models.dark-su3.chain_overrides.relic and backend_hint: analytic). MadGraph/MadDM is bypassed because dark SU(3)_D is non-SM color and cannot be encoded in a UFO/CalcHEP file. DD and ID remain blocked on /feynarts, /formcalc, /ddcalc, /gamlike.

---

Flow

---

Step 1 — DM-candidate declaration

Print verbatim:

For Dark SU(3), the DM candidates are:

• V — Dark vector boson (spin-1); couples to nucleons via H_1 + H_2 Higgs portal; tree-level SI non-zero.
• Psi — Dark pseudoscalar (spin-0); CP-odd component of the dark Higgs doublet; exact parameter-independent SI blind spot (Eq. 29).

This is a multi-component model. Per-candidate observables must be combined using relic-weighted fractions f_i = Ω_i / Ω_tot. Per-candidate relic density is available now via the analytic-only branch of /dark-matter-constraints [EXISTS] (see the module's header docstring for the current method; paper uses micrOMEGAs). Paper-fidelity multi-component weighting into a total Ω_tot h² is on the upgrade roadmap (per the dsu3-002 banner above) — emitted values are regression anchors only. DD and ID chains remain [COMING SOON] on /feynarts//formcalc (DD) and /gamlike (ID).

Reference Lagrangian — this is the physics the analytic module reproduces (arXiv:2506.19062 §IV, Eqs. 26-29). SU(3)_D is broken to SU(2)_D by a dark Higgs doublet Φ_D in the fundamental of SU(3)_D that acquires a VEV v_D:

L ⊃ -¼ F^D_μν F^{D,μν}                       # SU(3)_D gauge kinetic
   + |D_μ Φ_D|²  - V(Φ_D, H)                  # dark Higgs kinetic + potential
   + λ_P |H|² |Φ_D|²                           # Higgs portal

SU(3)_D → SU(2)_D breaking by the dark Higgs doublet VEV breaks 5 generators → 5 massive dark gauge bosons. Of these, the DM candidate V is a triplet under the residual SU(2)_D with mass m_V = g̃ v_D / 2. The remaining 3 generators of the unbroken SU(2)_D remain massless. The dark Higgs doublet produces scalar mass eigenstates H_1 (SM-like, 125 GeV) and H_2 (dark Higgs mass m_H2), mixed by angle θ (sin θ small). The CP-odd component of Φ_D is the pseudoscalar DM Psi with mass m_Psi = g̃ v_D / (2√2).

Parameters: (g̃, sin θ, m_H2, m_V, m_Psi). Reference ModelSpec YAML: plugins/hep-ph-toolkit/skills/_shared/modelspec_v3/specs/dark_su3.yaml. Analytic module: analytic_models.dark_su3. Practitioner script: plugins/hep-ph-toolkit/skills/dark-su3/practitioner_script.md.

Physics notes on the two DM candidates (for context):

V is the dark vector boson arising from the broken generators of SU(3)_D → SU(2)_D. As a spin-1 particle it couples to the SM Higgs via the portal mixing angle θ, giving a non-zero tree-level SI cross-section. Two diagrams contribute: H_1 exchange (with a relative minus sign from the mixing rotation) and H_2 exchange. The coupling is g_{VV H_1} = -(g̃ m_V / 2) sin θ and g_{VV H_2} = +(g̃ m_V / 2) cos θ (Eq. 26). The paper's Fig. 7 shows a Planck-compatible relic band across a broad (m_V, m_Psi) plane; a resonance region near m_H2 ~ 2 m_V enhances the annihilation cross-section.

Psi is the dark pseudoscalar (CP-odd component of the dark Higgs doublet). Its SI direct-detection amplitude vanishes identically at tree level — this is an exact, parameter-independent blind spot (Eq. 29). The cancellation arises from the relative sign between the H_1 and H_2 exchange diagrams: g_{Psi Psi H_1} / m_H1^2 + g_{Psi Psi H_2} / m_H2^2 = 0 for all parameter values. The relic density is computed via the same Higgs-portal annihilation channel (Psi Psi → H_2* → SM). The analytic module computes the relic density; see its header docstring for the current method. The paper uses micrOMEGAs.

The SARAH/MG5 path is blocked for this model: MG5 lacks dark-color algebra for non-abelian dark gauge groups, and the DM candidates are not present in any UV UFO. All observables are produced by analytic_models.dark_su3 (backend spectrum: analytic).

---

Step 2 — Constraint multi-select

Ask the user which constraints to compute:

{
  "question": "Which constraints do you want computed for this model?",
  "options": [
    {"id": "relic",    "label": "Relic density",            "description": "Ω h² via MadDM"},
    {"id": "dd",       "label": "Direct detection",         "description": "σ_SI (tree + loop) via MadGraph + FeynArts/FormCalc + DDCalc"},
    {"id": "id",       "label": "Indirect detection",       "description": "Annihilation spectra via MadDM → GamLike / NuLike"},
    {"id": "collider", "label": "Collider (coming soon)",   "description": "Placeholder — execution is a no-op"}
  ],
  "allowMultiple": true,
  "required": true
}

Validation: at least one non-collider option must be selected. If the user selects collider only, re-ask with the message: "Collider is a placeholder in this iteration; nothing would run. Please also select relic, DD, or ID."

---

Step 3 — Time estimate + prereq resolve + gate

Run (or reason from) plugins/hep-ph-toolkit/skills/_shared/time_budget.py for the selected constraints and print the chain table. For the selection [relic, dd, id] the output is:

Planned chain for Dark SU(3):

  Relic density         READY
    /sarah-build [EXISTS] → /spheno-build [EXISTS] → /dark-matter-constraints [EXISTS]
    cold: 1.5–3 hr   cached: 0.3–0.7 hr

  Direct detection      [COMING SOON — pending: /feynarts, /formcalc, /ddcalc loop chain]
    /sarah-build [EXISTS] → /spheno-build [EXISTS] → /madgraph [EXISTS]
      → /feynarts [EXISTS] → /formcalc [EXISTS] → /ddcalc [EXISTS]
      → /dark-matter-constraints [EXISTS]
    cold: 3–5 hr   cached: 0.5–1 hr

  Indirect detection    [COMING SOON — /gamlike v0 parser shipped; pull-computation v1+]
    /sarah-build [EXISTS] → /spheno-build [EXISTS] → /madgraph [EXISTS] → /maddm [EXISTS]
      → /gamlike [v0 — parser only; pull-computation v1+] → /dark-matter-constraints [EXISTS]
    cold: 1.5–4 hr   cached: 0.3–0.7 hr

Overlap-adjusted totals (shared prereqs counted once):
  selected + ready : cold ~1–3 hr,  cached ~0.3–0.6 hr
  selected total   : cold ~3.5–9 hr,  cached ~1.1–2.3 hr  (if all prereqs existed)

Adapt the printed block to the user's actual selection (not always all three).

Relic is now READY via the analytic-only branch of /dark-matter-constraints [EXISTS]. When the user selects only relic, the ready-branch gate fires; when DD or ID are selected, those are COMING SOON (waiting on /feynarts//formcalc//ddcalc for DD and /gamlike for ID) — /dark-matter-constraints itself is ready. The coming-soon-branch gate fires:

{
  "question": "Some selected constraints are blocked on missing prereqs (DD on /feynarts, /formcalc, /ddcalc; ID on /gamlike). /dark-matter-constraints is available. How to proceed?",
  "options": [
    {"id": "run_ready", "label": "Run available (drop blocked)", "description": "Run the ready constraints (relic via analytic-only branch); skip blocked ones with a note in the final summary."},
    {"id": "back",      "label": "Back",                          "description": "Re-select constraints."},
    {"id": "cancel",    "label": "Cancel",                        "description": "Exit cleanly."}
  ],
  "allowMultiple": false,
  "required": true
}

If all selected are READY (relic-only selection in this iteration; full READY for DD/ID requires /feynarts, /formcalc, /ddcalc, /gamlike to ship):

{
  "question": "Run it? Total cold-run estimate: {cold_total} hr.",
  "options": [
    {"id": "go",     "label": "Run it", "description": "Execute the chain in order."},
    {"id": "back",   "label": "Back",   "description": "Re-select constraints."},
    {"id": "cancel", "label": "Cancel", "description": "Exit cleanly."}
  ],
  "allowMultiple": false,
  "required": true
}

On cancel: print "Cancelled." and exit. Do NOT write summary.json.

On back: return to Step 2.

On run_ready when zero constraints are ready: print the following message and return to Step 2:

No selected constraints are currently runnable. Re-select constraints or Cancel.

This branch fires only if the user selected DD and/or ID exclusively (without relic). In this iteration, relic is READY via the analytic-only branch of /dark-matter-constraints [EXISTS], so any selection that includes relic produces at least one runnable constraint. DD and ID remain blocked on /feynarts//formcalc//ddcalc and /gamlike respectively — not on /dark-matter-constraints.

---

Step 4 — Execute

Relic is READY via the analytic-only branch; DD and ID are [COMING SOON], waiting on /feynarts//formcalc//ddcalc (DD) and /gamlike (ID). The relic chain runs /sarah-build → /spheno-build (analytic backend) → /dark-matter-constraints (analytic-only branch) and produces per-component Ω_V h² and Ω_Psi h² with the exact-blind-spot flag for Psi. The DD/ID sections below document what those paths will look like once the missing skills ship; relic execution is described in §"Step 4 — Relic density branch" immediately following.

---

Step 4 — Relic density branch (READY via analytic-only branch of /dark-matter-constraints)

Overview: the relic chain runs /sarah-build [EXISTS] → /spheno-build [EXISTS] (analytic dispatch) → /dark-matter-constraints [EXISTS] (analytic-only branch) and computes per-candidate Ω h² for V and Psi across the parameter scan range (m_V, m_Psi) defined in the plot_axes metadata. The MG5+MadDM path remains blocked on MG5's lack of dark-color algebra and is intentionally bypassed for this model — see _shared/constraints.yaml models.dark-su3.chain_overrides.relic and backend_hint: analytic.

Per the dsu3-002 banner: emitted Ω h² values are regression anchors only and are roughly 25000× the Planck target. Paper-fidelity multi-component weighting into a total Ω_tot h² ≈ 0.12 is on the upgrade roadmap, not a target for this iteration.

The per-candidate relic density computation proceeds as follows.

4a. Build the model via /lagrangian-builder (analytic dispatch; no SPheno perturbative run)

Invoke /lagrangian-builder on input path (a) (interactive interview), with the practitioner script at plugins/hep-ph-toolkit/skills/dark-su3/practitioner_script.md playing the role of the user.

This replays the four-question interview from plugins/hep-ph-toolkit/skills/lagrangian-builder/references/interview.md with both sides pre-written. For each question:

1. Print Claude's side (preamble, scope-tier announcement for Q1 — Tier 2 for Dark SU(3) because the practitioner's Q1 answer describes a spontaneously broken dark gauge group with explicit scalar content, enumerated Lagrangian for Q3, detected mixing sectors for Q4 — the H_1/H_2 mixing and the dark Higgs VEV) as formatted blockquote text, prefixed Claude:.
2. Print the corresponding answer from practitioner_script.md as formatted blockquote text, prefixed Practitioner:.
3. Do NOT call AskUserQuestion — this is a rehearsed demo, not a live interview. Both sides are scripted; the formatting lets the audience follow what a real interview looks like.
4. Proceed to Claude's next interview step (extraction for Q1/Q2, reconciliation for Q3/Q4) using the scripted answer as the user turn.

After Q4, present the drafted YAML, validate it with validate_spec.py, and on success proceed through /lagrangian-builder's remaining steps — install SARAH / SPheno if missing, run /sarah-build, run /spheno-build, register the model.

Write the generated YAML to ./demo_output/dark-su3/dark_su3_spec.yaml so it's inspectable after the run. If it differs materially from the reference at plugins/hep-ph-toolkit/skills/_shared/modelspec_v3/specs/dark_su3.yaml, note the diff in the final summary.

Analytic backend note. The dark-SU(3) ModelSpec dispatches to analytic_models.dark_su3 (backend analytic_only: true). When /lagrangian-builder drives the interview and reaches /spheno-build, the analytic dispatch runs analytic_models.dark_su3.compute() directly — SPheno's perturbative RGE machinery does not apply to a Higgsed dark sector. This is the expected path, not a bug. Relic density for V and Psi is returned from the analytic backend and consumed by /dark-matter-constraints [EXISTS]'s analytic-only branch. Execution of the DD/ID chains remains gated on /feynarts//formcalc//ddcalc (DD) and /gamlike (ID); /dark-matter-constraints itself is no longer the blocker.

On diagnostic-checkpoint failure (check_vertices.py, check_mass_matrix.py, check_spectrum.py) prior to the analytic-module step, /lagrangian-builder retries per its own iteration loop (see interview.md §"Iteration expectations"). The demo surfaces the retry — don't hide it — but continues automatically. If the retry budget is exhausted, fail the demo and dump the accumulated blockers.

Pass --force to the underlying /sarah-build only if the user explicitly asks to rebuild from scratch.

4b. SPheno spectrum generation (READY via analytic dispatch)

The analytic dispatch runs analytic_models.dark_su3.compute() per scan point, returning masses, mixing, and diagnostics (including Omega_V_h2, Omega_Psi_h2, relic_approx: True). The physical mass spectrum (m_V, m_Psi, m_H2, mixing angle θ) is encoded directly from the five input parameters — SPheno's perturbative spectrum generation does not apply.

Run at least four benchmark points from the paper's scan ranges (Eq. 30):

• (g_tilde=2.0, sin_theta=0.10, m_H2=500, m_V=150, m_Psi=70) — BP1
• (g_tilde=0.5, sin_theta=0.25, m_H2=650, m_V=415, m_Psi=55) — BP2
• (g_tilde=0.2, sin_theta=0.03, m_H2=1000, m_V=75, m_Psi=57) — BP3
• A point near m_H2 ~ 2 m_V to probe the resonance enhancement

4c. Analytic relic density: per-candidate results

The relic density for each candidate is computed by analytic_models.dark_su3.compute() and surfaced through the analytic-only branch of /dark-matter-constraints [EXISTS]. The analytic backend dispatches directly — no MadDM session is run for this model (MG5 lacks dark-color algebra for SU(3)_D; see POST_MORTEM). Both Omega_V_h2 and Omega_Psi_h2 are returned in the diagnostics dict; the analytic module emits flags describing the current approximation level — see its header docstring and result schema for caveats (the paper uses micrOMEGAs). Paper-fidelity multi-component combination of Omega_V_h2 and Omega_Psi_h2 into a Planck-comparable total Omega_tot_h2 and relic-weighted fractions f_i is on the upgrade roadmap (per the dsu3-002 banner); the values emitted today are regression anchors only.

For V, the annihilation cross-section features a resonance region near m_H2 ~ 2 m_V (paper Fig. 7) where the H_2-mediated s-channel is enhanced. See analytic_models.dark_su3 header docstring for the current resonance treatment. DRAKE is recommended for narrow-resonance cross-checks if (m_H2 / (2 m_V) - 1) < 0.1 (see memory project_dm_tool_roles).

Record per-candidate relic densities to ./demo_output/dark-su3/relic_V_<n>.json and ./demo_output/dark-su3/relic_Psi_<n>.json. Per-candidate results also appear in ./demo_output/dark-su3/diagnostics.json.

---

Step 4 — Direct detection branch (COMING SOON)

Direct detection for the Dark SU(3) model is blocked on the loop-DD prereq chain /feynarts [EXISTS] → /formcalc [EXISTS] → /ddcalc [EXISTS] → /dark-matter-constraints [EXISTS]. The /dark-matter-constraints meta-skill is available; the loop-DD chain integration is not yet integrated end-to-end. Two sub-issues:

1. SI cross-sections per candidate — Psi has an exact parameter-independent SI blind spot (Eq. 29): its tree-level SI cross-section vanishes identically due to a cancellation between H_1 and H_2 exchange diagrams. V has non-zero tree-level SI via the same Higgs portal (Eq. 26). Computing the per-candidate σ_SI requires loop amplitudes from /feynarts [EXISTS] and /formcalc [EXISTS]; once those are integrated end-to-end, /ddcalc [EXISTS] converts amplitudes to nuclear-recoil rates and /dark-matter-constraints [EXISTS] performs the relic-weighted combination.

2. DD rate combination — Combination of per-candidate σ_SI into a multi-component DD rate is handled by /dark-matter-constraints [EXISTS]. This step is no longer the blocker; it waits on FeynArts/FormCalc upstream.

When the FeynArts/FormCalc prereqs ship, the relic density branch results would feed directly into the DD rate combination via /dark-matter-constraints.

---

Step 4 — Indirect detection branch (COMING SOON)

Indirect detection is blocked on /gamlike [v0 — parser only; pull-computation v1+]. The full ID chain is … → /maddm [EXISTS] → /gamlike [v0 — parser only; pull-computation v1+] → /dark-matter-constraints [EXISTS]; /dark-matter-constraints itself is available, the missing piece is /gamlike (gamma-ray flux conversion). When /gamlike ships:

1. The analytic module provides per-candidate sv_V and sv_Psi (s-wave cross-sections at threshold); /gamlike [v0 — parser only; pull-computation v1+] will convert these into predicted gamma-ray and neutrino fluxes per candidate.
2. /dark-matter-constraints [EXISTS] then combines the per-candidate fluxes using f_i-weighted rates and compares against Fermi-LAT and IceCube limits.

For V near the H_2 resonance, the annihilation cross-section <sigma v> is velocity-dependent — verify whether the <sigma v> expansion converges before applying the GamLike comparison (consult DRAKE guidance if the expansion fails).

---

Step 4d. Plotting guidance (READY for relic; DD/ID overlays still blocked)

Once relic density has run via the analytic-only branch of /dark-matter-constraints [EXISTS], consult /hep-plotting (reference skill) to produce ./demo_output/dark-su3/summary.{pdf,png}. DD/ID overlays remain blocked on /feynarts//formcalc (DD) and /gamlike (ID).

The Profumo blind-spot paper is theory-only with no experimental affiliation, so use the analytic context from styles/hep_ph_style.py (see /hep-plot §Style) rather than an experiment-branded style:

from styles.hep_ph_style import set_hep_context, check_overlaps
import matplotlib.pyplot as plt
import numpy as np

palette = set_hep_context("analytic")

# 85mm × 63.75mm (single-column 4:3) per analytic style.
fig, ax = plt.subplots(figsize=(85/25.4, 63.75/25.4))

# Scan points — black per analytic palette and HEP data convention.
ax.scatter(mV_values, mPsi_values,
           c=palette["data"], s=6)

# Planck relic band highlight — theory blue.
planck_mask = (omega_h2_total >= 0.119) & (omega_h2_total <= 0.121)
ax.scatter(mV_values[planck_mask], mPsi_values[planck_mask],
           c=palette["theory"], s=12, marker='*')

# Resonance region: m_H2 ~ 2 m_V (not a diagonal in m_V vs m_Psi plane;
# label it as a horizontal band or separate annotation if m_H2 is fixed).

# Axes: from plot_axes metadata.
ax.set_xlabel(r"$m_V$ [GeV]")
ax.set_ylabel(r"$m_\Psi$ [GeV]")
ax.set_xlim(1, 1000)     # from plot_axes.x.range
ax.set_ylim(1, 300)      # from plot_axes.y.range
ax.set_xscale("log")     # from plot_axes.x.scale
ax.set_yscale("log")     # from plot_axes.y.scale

# Subsidiary annotation (paper reference) instead of an experiment label.
ax.text(0.02, 0.98, "Dark SU(3) dark-Higgs model\narXiv:2506.19062 §IV",
        transform=ax.transAxes, va="top", ha="left",
        fontsize=7, color=palette["deemph"])

# Mandatory overlap check before saving.
issues = check_overlaps(fig)
assert not issues, f"Overlaps detected: {issues}"

fig.tight_layout()
fig.savefig("./demo_output/dark-su3/summary.pdf", bbox_inches="tight")
fig.savefig("./demo_output/dark-su3/summary.png", dpi=200, bbox_inches="tight")

Key requirements per HEP convention:

• Analytic (theory-only) style via set_hep_context("analytic") from styles/hep_ph_style.py.
• Data points in black via palette["data"] (per project memory feedback_data_point_color).
• Axis labels from plot_axes metadata: x = m_V [GeV], y = m_Psi [GeV].
• x-range [1, 1000] GeV (log); y-range [1, 300] GeV (log).
• Figure size 85mm × 63.75mm (single-column 4:3); no legend box; left + bottom axes only.
• Save to ./demo_output/dark-su3/summary.{pdf,png}.

---

Step 4e. Write summary.json

At the end of Step 4 (after all READY constraints have run), write ./demo_output/dark-su3/summary.json conforming to plugins/hep-ph-toolkit/skills/dark-su3/summary.schema.json (which $refs _shared/summary.core.schema.json).

In this iteration, relic runs via the analytic-only branch of /dark-matter-constraints [EXISTS] and DD/ID skip with skip reasons (DD blocked on /feynarts//formcalc//ddcalc; ID blocked on /gamlike). The "no constraints runnable" path only fires if the user selected DD or ID exclusively.

Create the output directory first:

mkdir -p ./demo_output/dark-su3/

When relic ran (the typical path in this iteration), write:

{
  "schema_version": "1",
  "model": "dark-su3",
  "run_at": "<ISO-8601 timestamp>",
  "ran": ["relic"],
  "skipped_constraints": [
    {"id": "dd", "reason": "blocked on /feynarts, /formcalc, /ddcalc"},
    {"id": "id", "reason": "blocked on /gamlike"}
  ],
  "artifacts_dir": "./demo_output/dark-su3/",
  "headline": "Relic computed for V and Psi at <N> benchmark points via analytic approx (relic_approx: True); DD/ID skipped."
}

Adapt ran, skipped_constraints, and headline to the actual constraints that ran. The literal path ./demo_output/dark-su3/summary.json is where this file is written.

On Cancel (user chose Cancel at Step 3 gate): do NOT write summary.json. /demo's closing block will degrade gracefully to "dark-su3 interview was cancelled.".

---

Error paths

Skill step	Error code	Trigger	Action
/sarah-build	WOLFRAM_KERNEL_ABSENT	wolfram_engine_path not set in config	Run /install to configure Wolfram Engine, then retry
/sarah-build	SARAH_ABSENT	sarah_path not set in config	Run /install to configure SARAH, then retry
/sarah-build	MODELSPEC_INVALID	v3 validator rejects dark_su3.yaml	Check dark_su3.yaml against modelspec_v3/schema.json; inspect gauge group or fermion spec
/sarah-build	ANOMALY_CANCELLATION_FAILED	SARAH anomaly check fails	The dark SU(3) model uses a dark Higgs doublet; check that the scalar rep assignments are correct and that the dark gauge group is listed as kind: dark in gauge_groups
/sarah-build	SARAH_OUTPUT_MISSING	UFO output absent after successful SARAH exit	Check sarah.log in $STATE_ROOT/models/dark_su3/; MG5 dark-color algebra is blocked — use the analytic backend path
/spheno-build (analytic dispatch)	ValueError from dark_su3.compute()	Invalid parameter values	Check that g_tilde > 0, 0 < sin_theta < 1, and all masses are positive; verify m_Psi < m_V for kinematic consistency (Eq. 30)
Analytic module	Omega_V_h2 or Omega_Psi_h2 anomalously high	Coupling too weak	Check g_tilde and sin_theta values; very small couplings push freeze-out relic to overabundance
Analytic module	resonance_factor_V very large	Near-resonance at m_H2 ~ 2 m_V	The analytic module's resonance treatment may be unreliable in this regime; see its header docstring for method details and consult DRAKE for cross-check (see memory project_dm_tool_roles)
/dark-matter-constraints	ANALYTIC_BRANCH_FAILED	Analytic-only branch raises (e.g. invalid spec, missing analytic_models.dark_su3, schema mismatch)	Inspect the dispatch error; verify analytic_only: true in the ModelSpec backend block and that analytic_models.dark_su3 is importable. Relic for dsu3 does not require MadDM in this iteration
Plotting	styles.hep_ph_style import error	styles/ not on PYTHONPATH	Ensure the repo root is on PYTHONPATH (the styles/ package ships with hephaestus); /hep-plot §Style covers the analytic interface

---

File map

File	Produced by	Contents
$STATE_ROOT/models/dark_su3/sarah_output/UFO/dark_su3/	/sarah-build	MadGraph UFO model files (blocked — MG5 dark-color wall; present for schema compliance)
$STATE_ROOT/models/dark_su3/SPheno.spc.dark_su3	/spheno-build (analytic dispatch)	Mass spectrum + diagnostics from analytic_models.dark_su3
./demo_output/dark-su3/diagnostics.json	Step 4c (analytic)	Per-scan-point diagnostics: Omega_V_h2, Omega_Psi_h2, relic_approx, blind_spot_Psi_tree, couplings
./demo_output/dark-su3/relic_V_<n>.json	Step 4c	Omega h² for V at scan point n
./demo_output/dark-su3/relic_Psi_<n>.json	Step 4c	Omega h² for Psi at scan point n
./demo_output/dark-su3/summary.png	Step 4d	Relic plane scatter plot (m_V, m_Psi)
./demo_output/dark-su3/summary.json	Step 4e	Per-model summary consumed by /demo closing block