SEO / Portfolio / Public Site
Consequence Briefing, Explainability, and Comparative Product Benchmark
Report summary
The design and implementation of a public-facing, educational planetary simulation dealing with nuclear-event consequences requires an intricate balance between scientific fidelity, user accessibility, and stringent ethical boundaries. When the interaction model restricts users to minimal inputs—spe
Key topics
- SEO / Portfolio / Public Site
- SEO
- Portfolio
- Public Site
- AI
- Physics
- Semantic Systems
- Research Archive
- Strategy
Research provenance
For citation, use the report title and canonical URL. Archival presence does not establish authorship or promote report statements into portfolio evidence.
This page renders the archived Markdown as safe, formatted HTML. It is background research and does not become a portfolio claim without evidence review.
Full report
On this page
The design and implementation of a public-facing, educational planetary simulation dealing with nuclear-event consequences requires an intricate balance between scientific fidelity, user accessibility, and stringent ethical boundaries. When the interaction model restricts users to minimal inputs—specifically, a geographical site and a minimal nuclear-event or weapon classification—the simulation engine and its user interface must assume the entirety of the explanatory burden. The outputs, which range from prompt physical destruction to multidecadal systemic stressors, must be communicated without conveying false scientific authority, without inducing unwarranted panic, and without facilitating operational military targeting. This report details an exhaustive, evidence-based strategy for presenting these generated results. It defines how the system must guide the user to understand causal mechanisms, the temporal evolution of the disaster, and the inherent uncertainties of the underlying models through deterministic boundaries and structured narrative design.
1. Comparative Benchmark
To derive foundational principles for the simulation’s interface, causal explainability, and uncertainty architecture, a comprehensive analysis of twelve distinct product categories, analytical frameworks, and interface patterns was conducted. The analysis extracts critical lessons in spatial navigation, temporal progression, uncertainty communication, and cognitive accessibility. Understanding the successes and failures of these existing paradigms is paramount for designing a simulation that minimizes user inputs while maximizing educational output. The landscape of disaster and strategy simulators reveals a stark dichotomy: tools are either highly accessible but analytically shallow, or analytically exhaustive but completely inaccessible to the layperson. Educational visualizers like Alex Wellerstein’s NUKEMAP1 have achieved massive public reach by overlaying deterministic blast radii on familiar geographic interfaces, relying heavily on the physical equations defined by Glasstone and Dolan4. However, such tools typically present a static snapshot of prompt effects, lacking the temporal cascading of systemic infrastructure collapse. Conversely, professional platforms like FEMA’s Hazus-MH6 and HURREVAC9 provide rigorous, phased temporal tracking and economic loss estimations based on geographic information systems (GIS), but require exhaustive data inputs and domain expertise to operate, making them unsuitable for public educational tools. To bridge this gap, the simulation must incorporate cognitive frameworks from intelligence and scientific communities. The Analysis of Competing Hypotheses (ACH), developed by Richards Heuer for the CIA, provides a structural basis for comparing divergent outcomes based on identical evidence, emphasizing the "diagnosticity" of variables12. In parallel, the Intergovernmental Panel on Climate Change (IPCC) and risk-communication researchers have demonstrated that qualitative uncertainty (e.g., "Likely") is routinely misinterpreted by the public unless explicitly paired with numerical probability bounds15. Finally, spatial rendering engines like Cesium and Mapbox18 and W3C web accessibility guidelines21 dictate how visual and auditory information must be controlled to prevent user disorientation during complex data visualizations.
| Product / Pattern | Intended Audience | User Inputs | Map & Temporal Behavior | Result Format & Uncertainty | Lessons for this Product |
|---|---|---|---|---|---|
| NUKEMAP \[cite: 1, 23, 24\] | General public, educators, journalists | Site, yield, burst height, fission fraction | 2D/3D overlays; static snapshot of immediate prompt effects | Concentric effect radii, casualty estimates; uses qualitative FAQ for uncertainty | Minimize inputs; utilize clear concentric visual hierarchies; avoid relying solely on static snapshots. |
| FEMA Hazus-MH \[cite: 6, 25, 26\] | Emergency managers, urban planners | Deep local infrastructure inventories, hazard extents | ArcGIS integration; pre- and post-disaster temporal phases | Tabular loss estimates, displaced populations; utilizes confidence bounds on damage curves | Abstract complex calculations into plain-language systemic impacts; do not force users to input infrastructure data. |
| HURREVAC \[cite: 9, 11\] | Government emergency managers | Live forecast data, evacuation clearance times | Panning view with locked evacuation zones; forecast hour scrubber | Track cones, wind probability timing; explicit potential track error cones | Tie timeline scrubbers directly to map phase transitions; lock critical spatial bounds during presentation. |
| Analysis of Competing Hypotheses (ACH) \[cite: 12, 13, 27\] | Intelligence analysts | Hypotheses, evidence matrices, diagnosticity weights | N/A; iterative refinement of logical chains | Consistency matrices; emphasizes rejecting hypotheses | Present branch comparisons by showing how identical evidence yields different outcomes under varying contextual assumptions. |
| IPCC AR5/AR6 Uncertainty Framework \[cite: 15, 28, 29\] | Policymakers, scientists, public | N/A | Multidecadal projections | Calibrated likelihood and confidence text | Always pair qualitative uncertainty (e.g., "Likely") with a numerical range; do not rely on text alone16. |
| Cesium / Mapbox Camera APIs \[cite: 18, 19, 30\] | Spatial developers, end-users | Vector coordinates, pitch/yaw limits | 3D locked tracking, smooth easing; viewport states | Rendered visual output | Lock the camera during result briefings using lookAtTransform or viewport states to maintain context without user disorientation. |
| W3C ARIA-Live Dashboards \[cite: 31, 32, 33\] | Screen reader users, accessibility tools | Keyboard navigation | Real-time DOM updates | Asynchronous audio announcements | Use aria-live="polite" for timeline changes; reserve assertive for critical errors to prevent cognitive overload. |
| System Dynamics Dashboards (En-ROADS) | Policymakers, students | Policy sliders, economic levers | Century-scale continuous | Causal loop diagrams, global graphs | Translate complex causal loops into linear, expandable narrative chains; avoid overwhelming node-link graphs34. |
| Outrider Bomb Sight \[cite: 35\] | General public | Location, blast type | Cinematic 3D overlay; static immediate effects | Immersive visual radius; minimal uncertainty communication | Aesthetic polish aids engagement but must be paired with structured, rigorous data to avoid superficiality. |
| Structured LLM Output (Pydantic/Instructor) 36 | AI developers, end-users | Natural language queries | Immediate generation | JSON schema constrained objects; explicit retry mechanisms | Enforce strict schema constraints for AI explanations; maintain deterministic fallbacks to prevent hallucination. |
| MacEachren Cartographic Uncertainty 38 | Cartographers, GIS scientists | GIS layers, statistical variance | Extrinsic/intrinsic visual overlays | Bivariate choropleths, texture mapping, boundary blurring | Use texture or blurring to denote uncertain geographic boundaries rather than hard lines, conveying precision visually. |
| CDC CERC Framework \[cite: 41, 42, 43\] | Public health officials, responders | Emergency data | Pre-event to recovery | Actionable empathetic messaging; explicitly states what is known/unknown | Frame all results respectfully, acknowledge gaps, and maintain strict educational boundaries. |
The synthesis of these twelve benchmarks establishes that input minimization must be counterbalanced by transparent, phased explainability. The simulation must guide the user through a temporal narrative that respects the physical realities of the event while explicitly acknowledging model limitations, utilizing structured spatial control and dual-scale uncertainty mechanics.
2. Recommended Result Hierarchy
To prevent cognitive overload while satisfying the requirement for exhaustive detail, the post-commit result must be presented in a progressive disclosure hierarchy. When the user commits the site and event class, the simulation transitions from an open exploratory state to a highly structured briefing. This layering strategy ensures that the user absorbs the prompt physical reality before grappling with complex secondary systemic cascades. Immediate Confirmation: The system immediately acknowledges the committed coordinates and event class. The map transitions to a locked viewport focused on the site, establishing spatial context without requiring further navigation18. This confirms the user's minimal input before rendering the output. What Happened: A plain-language, high-level summary of the deterministic physical event. This layer translates the raw kiloton or megaton inputs into immediate geographical and physical realities, utilizing the established principles of thermal radiation, air blast phenomena, and initial nuclear radiation5. Why the Model Produced This Outcome: An accessible causal explanation detailing the specific relationships between the selected event class, the geographical characteristics of the chosen site, and the resultant physical destruction. This step demystifies the simulation engine, proving the outcome is a mathematically calculated result rather than a pre-authored narrative. What Changes Now: An analysis of immediate systemic pressures, such as infrastructure collapse, displaced populations, and emergency response degradation. This transitions the focus from raw physics to human and systemic geography, echoing the operational focus of platforms like Hazus-MH7. What Develops Over Time: A phased timeline illustrating the progression of the event from the initial milliseconds of the thermal flash to the weeks and months of secondary cascades and recovery efforts. What Remains Uncertain: A dedicated module identifying the variables that the model cannot predict with absolute certainty, such as exact meteorological conditions, localized structural resilience, or human behavioral responses. This aligns with the IPCC's mandate to make uncertainty a primary feature of the communication, not an afterthought17. What Assumptions Were Used: An explicit disclosure of the baseline data driving the simulation, including ambient population density, generalized infrastructure resilience scores, and idealized terrain models. How to Compare Another Branch: An interface mechanism allowing the user to view how the identical event at the identical site would unfold under altered initiating conditions (e.g., daytime versus nighttime population distributions), utilizing the principles of ACH12. How to Inspect the Globe: Controls that unlock the camera, allowing the user to pan and observe the broader geographical impact, with visual effects scaled to the timeline's current phase. How to Revise the Initiating Facts: A clear pathway to reset the simulation, returning to the initial minimal input state to explore a completely new geographic site or event class.
3. Analytical Briefing Template
The analytical briefing bridges the gap between raw algorithmic output and human comprehension. It is designed to be reusable, modular, and strictly deterministic. This structural rigidity ensures that even if optional artificial intelligence components experience timeouts or fail safety validations, the core educational value remains perfectly intact via template-driven text.
Template Structure
| Section | Content Description | Data Source / Mapping |
|---|---|---|
| Event | The minimal weapon or event classification selected by the user. | User Input |
| Site and Coordinates | The exact latitude and longitude committed by the user. | User Input |
| Simulation Date | The in-simulation temporal anchor for the event. | System Generated |
| Branch | The current contextual state (e.g., standard baseline, high-wind). | System Generated |
| Initiating Facts | The locked contextual parameters at the moment of calculation. | System Generated |
| Model Assumptions | Disclosed baseline constants (e.g., idealized flat terrain). | Deterministic Constants |
| Immediate Consequence Summary | Plain-language overview of the physical impact (blast, thermal, prompt radiation). | Deterministic Calculation |
| Major System Pressures | Identification of cascading failures in infrastructure or society. | Deterministic Calculation |
| Timeline | A sequence of phases from immediate prompt effects to long-term systemic failure. | Deterministic Calculation |
| Confidence and Uncertainty | Specific bounds on the reliability of the calculated estimates, using dual-scales. | Deterministic Constants |
| Visual-Layer Status | Legend explaining the current map overlays and cartographic uncertainty representation. | UI State |
| Secondary Cascades | Downstream effects resulting from system pressures (e.g., economic halts, mass displacement). | Deterministic Calculation |
| Recovery Factors | Variables that will influence the hypothetical stabilization. | Deterministic Calculation |
| Alternative Branch Comparison | Summary of how altered conditions shift the outcome. | Pre-calculated Counterfactual |
| Educational Boundary | Disclaimer restricting the use of the data for real-world planning. | Static Copy |
| Provenance and Model Version | Citation of the underlying physics models and software version. | Static Copy |
Fictional Example Implementation
Event: Class III Atmospheric Detonation (Approx. 100kt yield equivalent) Site and Coordinates: Lat: 45.1234, Lon: \-90.5678 (Simulated Mid-Latitude Urban Proxy) Simulation Date: 14 October 2026 Branch: Baseline Terrestrial Initiating Facts: Mid-autumn ambient temperatures, standard atmospheric pressure, daytime population distribution. Model Assumptions: Idealized uniform terrain elevation, generalized urban infrastructure resilience, static wind velocity (10 knots easterly). Immediate Consequence Summary: The event generated a high-temperature plasma fireball and subsequent overpressure wave consistent with a 100kt airburst5. Within a 3.2-kilometer radius, structural integrity of commercial and residential buildings suffered catastrophic failure due to extreme air blast loading. The thermal radiation extended sufficiently to ignite exposed combustible materials across a 5.5-kilometer radius, initiating secondary fires. Major System Pressures: The immediate destruction of the localized electrical grid and the severing of primary transportation arteries have isolated the primary impact zone. First responder staging areas within the 5-kilometer radius are rendered non-operational, severely degrading local emergency capacity. Timeline: Phase 1 (0-1 Hour): Initial blast and thermal flash; prompt nuclear radiation exposure; primary structural collapse; toroid cloud formation5. Phase 2 (1-24 Hours): Propagation of secondary fires; atmospheric loading of particulate matter; initiation of spontaneous civilian evacuation. Phase 3 (1-7 Days): Systemic failure of regional medical supply chains; stabilization of thermal events; early fallout deposition patterns materialize. Confidence and Uncertainty: The structural failure radii carry a High Confidence (85-95% probability) based on established overpressure equations16. The extent of secondary fires carries Low Confidence (20-40% probability), as the simulation cannot account for localized combustible fuel loads or spontaneous firebreak creation. Visual-Layer Status: The map currently displays the 5 psi overpressure radius (solid orange boundary) and the thermal ignition probability zone (textured yellow gradient)40. Secondary Cascades: The loss of the regional water purification facility at the edge of the impact zone will result in a rapid depletion of potable water for the surrounding 50-kilometer metropolitan periphery within 72 hours. Recovery Factors: Restoration of systemic stability depends heavily on the rapid deployment of external logistics convoys via intact southern highway corridors and the establishment of peripheral triage centers. Alternative Branch Comparison: Under a Nighttime Population branch, immediate residential casualty rates increase by an estimated 22%, while commercial and industrial district impacts fall proportionately, shifting the required focus of peripheral medical recovery efforts from urban centers to suburban rings. Educational Boundary: This simulation utilizes generalized physics models for educational illustration. It does not predict precise real-world casualties and must not be utilized for operational military targeting, device construction, or emergency management resource allocation. Provenance and Model Version: Simulation Engine v2.4, utilizing generalized algorithms adapted from Glasstone and Dolan (1977) and modern systemic risk frameworks44.
4. Causal Explanation Design
Explaining the "why" behind the simulation results requires translating complex, non-linear system dynamics into comprehensible cognitive pathways. While system dynamics dashboards often rely on node-link graphs and causal loop diagrams, empirical research demonstrates that these complex visual webs frequently overwhelm lay users, inducing cognitive fatigue and reducing comprehension34. Therefore, the causal explanation must utilize a strictly linear, expandable narrative structure supported by visual evidence badges, drawing upon the methodological rigor of the Analysis of Competing Hypotheses (ACH)27. The architecture of the causal chain follows a linear progression that the user can expand for deeper technical granularity: Selected event → Immediate local disruption → Infrastructure and service pressure → Population movement → Institutional response → Regional economic effects → Escalation or recovery To implement this, the interface will utilize an accordion-style textual narrative. Each stage of the chain acts as a plain-language summary sentence. When a user interacts with a stage to expand it, the system reveals the specific deterministic logic and quantitative data driving that link. Within the expanded text, specific claims are adorned with interactive Evidence and Assumption Badges. For example, if the narrative states that "Regional medical capacity collapsed within 4 hours," the word "collapsed" is underlined with a badge indicating the model assumption: Assumption: Baseline hospital bed capacity of 2.5 per 1,000 residents was exceeded by 400%. Confidence Indicators are placed adjacent to every causal link. Utilizing the dual-scale approach required by climate communication research, a badge might read "High Confidence (80-100%)" for physical blast damage, but "Low Confidence (0-20%)" for the speed of population evacuation15. Furthermore, "Why this happened" Disclosures are provided as non-obtrusive tooltips for physical phenomena. If the user hovers over the term "thermal radiation," a deterministic disclosure explains the rapid conversion of weapon mass into a high-temperature plasma fireball and the subsequent emission of electromagnetic radiation, referencing established unclassified physics principles without venturing into weapon engineering5. Counterfactual Comparisons are lightly integrated into the causal chain. At critical junctures, a small prompt indicates how the chain might have broken or altered under different circumstances. This lays the cognitive groundwork for the user to explore the dedicated Branch Comparison view, teaching the user that the outcome is highly dependent on initial contextual conditions rather than just the explosive yield.
5. Timeline Design
The temporal evolution of a nuclear event is as critical to educational comprehension as its spatial footprint. The interface must seamlessly harmonize the textual result summary, the visual effects on the globe, and the simulated event-age phase. The timeline is governed by a horizontal date scrubber anchored to the bottom of the viewport. As the user manipulates the scrubber, the globe visual effects and the analytical briefing dynamically and synchronously update to reflect the selected temporal phase. The relationship is strictly synchronized across the following components:
1. Result Summary: Text dynamically updates. If the scrubber is set to "Phase 3: 72 Hours," the summary emphasizes systemic pressures, displacement, and economic halt rather than the immediate thermal flash.
2. Globe Visual Effects: Prompt effects (fireball, initial radiation) fade out of the rendering engine, replaced by representations of atmospheric loading, displaced population heatmaps, or infrastructural darkness.
3. Phase Markers: Distinct visual notches on the scrubber denote critical transition periods (e.g., T+0, T+1 Hour, T+24 Hours, T+1 Week).
4. Historical Replay: The scrubber can be dragged backward to observe the physical expansion of the prompt effects in slow motion.
5. Future Branch Projections: Beyond the deterministic baseline, the timeline fades into a dashed line representing highly uncertain long-term recovery or escalation projections.
To ensure spatial continuity, manipulating the timeline does not unlock or wildly swing the camera. The viewport remains constrained using SDK features (e.g., enableRotate: false, lookAtTransform) to ensure the user can observe the geographic changes from a stable vantage point18.
Desktop Wireframe Structure
| UI Region | Component | Behavior / Interaction |
|---|---|---|
| Top Left (Overlay) | Event Identity & Minimal Inputs | Locked display of Site, Coordinates, and Event Class. |
| Left Sidebar | Analytical Briefing (Scrollable) | Displays the structured template. Text fields update dynamically based on the current phase selected in the timeline scrubber. |
| Center/Right (Background) | 3D Globe / Map Viewport | Camera angle is locked to the impact site18. Displays visual overlays corresponding to the timeline. Features smooth transitions between states20. |
| Bottom (Full Width) | Date Scrubber & Phase Markers | Draggable slider. Snaps to Phase Markers. Updates Sidebar text and Globe overlays simultaneously. |
| Top Right (Overlay) | Branch Comparison & Settings | Toggles the comparison matrix. Accesses accessibility and visual settings. |
Mobile Wireframe Structure
| UI Region | Component | Behavior / Interaction |
|---|---|---|
| Top (Overlay) | Event Identity | Minimized to Site Name and Event Class to preserve vertical screen real estate. |
| Upper Half | 3D Globe / Map Viewport | Touch-to-pan restricted19. Visuals update based on timeline scrubber position. |
| Lower Half | Analytical Briefing (Swipeable Tabs) | Defaults to the 'What Happened' view. Swiping horizontally accesses 'Why', 'Timeline', and 'Uncertainty' layers. |
| Bottom Edge | Date Scrubber | Simplified, thickened slider with snap-to-phase functionality for touch optimization. |
6. Uncertainty and Model Humility
Simulations of this magnitude possess inherent, unavoidable margins of error. Presenting point estimates without contextualizing their uncertainty violates core risk communication principles and risks imparting a false sense of scientific authority38. Furthermore, research into the IPCC's communication strategies reveals that the public consistently misinterprets qualitative probability terms (e.g., assuming "Likely" means exactly 50%) unless they are paired with numerical boundaries16. The simulation will adopt a standardized, dual-scale language for uncertainty, combining qualitative terms with quantitative probability bounds. Crucially, uncertainty must not be hidden in a footer disclaimer; it must be presented immediately adjacent to the relevant claim.
Exact Language Patterns
| Uncertainty Scenario | Standardized Language Pattern |
|---|---|
| High Confidence | "The model indicates this outcome is highly likely (85–100% probability) based on established physical laws and consistent historical test data." |
| Moderate Confidence | "The model indicates this outcome is about as likely as not (40–60% probability) due to highly variable environmental factors at the selected site." |
| Low Confidence | "The model indicates this outcome is highly uncertain (0–20% probability), as it relies heavily on unpredictable human behavioral responses." |
| Missing Data | "Insufficient local data. The simulation utilized generalized global averages to calculate this specific regional metric." |
| Synthetic Assumption | "Calculated using an idealized assumption (e.g., flat terrain) rather than specific local topography, which alters wave propagation." |
| Model Disagreement | "Alternative scientific models suggest divergent outcomes for this specific metric; displayed results represent the median baseline." |
| Illustrative Visual | "Visual boundaries on the map are illustrative generalizations; real-world effects do not stop at precise geographic lines." |
| Nonphysical Visual Radius | "This radius denotes a probabilistic risk zone, not a physical barrier to prompt effects." |
| Provider-Generated Explanation | "This causal explanation was dynamically generated by an AI model utilizing the deterministic simulation data." |
| Deterministic Fallback | "Standard baseline explanation provided; dynamic causal generation is currently unavailable." |
On the map, visual uncertainty is represented extrinsically, adhering to cartographic best practices established by MacEachren38. Rather than drawing hard, distinct circles for blast radii or thermal zones, the edges must utilize gradient blurring or textured hatching. This visual language intuitively communicates that the boundary is a transition zone of probability rather than an absolute line of safety, mitigating the risk of the user misinterpreting the map as a precise operational forecast.
7. AI Explanation Boundary
To enhance the narrative flow of the causal explanation and the analytical briefing, an optional Large Language Model (LLM) may be utilized to synthesize the deterministic outputs into fluid, readable prose. However, the AI must act strictly as a translator of the simulation's data, never as the authoritative source of the data itself. Allowing an LLM to freely generate consequences risks hallucination, thereby destroying the educational integrity of the simulation. Structured Input to the Explainer: The LLM receives a strict, structured JSON payload containing the locked inputs, the deterministic calculation results, and the allowed physical relationships. The prompt strictly instructs the LLM to only synthesize the provided data and forbids the introduction of external factual claims. Schema-Constrained Output: The LLM must output its response in a validated JSON schema (e.g., utilizing frameworks like Pydantic or Outlines) ensuring the response maps exactly to the required sections of the analytical briefing36. If the output breaks the schema, it is rejected. Claim Grounding and Rejection: A secondary validation layer checks the LLM output against the deterministic payload. If the LLM generates a claim unsupported by the payload (e.g., hallucinating a specific casualty figure not provided by the math engine), the output is flagged and rejected before it reaches the user interface. Citation and Provenance Links: The LLM is instructed to append citation tags to its sentences linking back to the specific line of deterministic data or the static assumption that generated it. This allows the user to audit the AI's reasoning. Timeout and Outage Fallback: If the LLM fails to generate a validated response within 4.5 seconds, or if the external API is unreachable, the system must instantly and seamlessly fall back to a purely deterministic, template-driven text rendering. The user experience must never break due to an AI failure. Disclosure of AI-Generated Text: Any prose generated by the LLM must be accompanied by a subtle but distinct visual indicator (e.g., a specific background tint or an icon) and the explicit uncertainty pattern: "This causal explanation was dynamically generated by an AI model utilizing the deterministic simulation data." Versioning and Reproducibility: Because LLMs introduce non-determinism, reproducing exact text across different sessions is challenging. Therefore, the system must log the exact seed, model version, and deterministic payload used for generation. Users sharing a simulation result will share the saved deterministic output, ensuring reproducibility regardless of subsequent LLM updates.
8. Branch Comparison
A core educational objective of the simulation is demonstrating how sensitive consequence models are to initial conditions. To achieve this without allowing the user to actively optimize or target specific outcomes (e.g., manually increasing the yield to achieve a desired casualty count), the simulation utilizes a controlled Branch Comparison view. This methodology draws heavily from RAND wargaming techniques, where the value lies in exploring alternate contextual realities rather than changing the fundamental adversary action47. The user cannot change the site or the weapon class during comparison. Instead, they are presented with the same initiating event under different contextual states pre-calculated by the system, mirroring the mechanics of the Analysis of Competing Hypotheses (ACH) to reveal which variables possess the highest diagnosticity13. The comparison is presented as a side-by-side matrix analyzing:
- Selected Site: Constant.
- Event Class: Constant.
- Current-World Conditions (Baseline): E.g., Daytime population distribution, standard weather, current infrastructure resilience.
- Alternative Assumptions (Branch): E.g., Nighttime population distribution, severe weather patterns, severely degraded infrastructure.
- Calculated Results: Highlighted differences in prompt effects and systemic pressures based on the assumption delta.
- Time to Peak: Variations in the speed at which systemic failure occurs under the alternative branch.
- Recovery Capacity: How the altered context degrades or enhances hypothetical stabilization efforts.
- Uncertainty: Shifts in confidence levels based on the altered assumptions.
By locking the aggressive inputs and only allowing manipulation of the contextual defense or environmental variables, the simulation remains firmly educational and avoids acting as a weapon-employment simulator.
9. Accessibility and Comprehension
The simulation must be entirely navigable and comprehensible for users utilizing assistive technologies, adhering to modern web accessibility standards (WCAG) and prioritizing the correct implementation of WAI-ARIA guidelines. Plain-Language Summary: The primary 'What Happened' section is written at an eighth-grade reading level, avoiding dense physical jargon where possible to ensure immediate comprehension during high-stress information absorption42. Expert Detail: Technical users can access exact overpressure PSI thresholds, thermal fluence (cal/cm²), and REM exposure rates by expanding the narrative accordions, ensuring the product scales to academic users without overwhelming lay audiences. Screen-Reader Ordering: The Document Object Model (DOM) is structured logically, ensuring screen readers announce the critical event parameters and the immediate summary before moving into the timeline controls or complex causal chains. Table Alternatives and Chart Descriptions: All visual data, including the branch comparison matrices and timeline scrubbers, are backed by hidden textual summaries and properly labeled ARIA components to ensure non-visual access to data trends. Color-Independent Legends: Map overlays do not rely solely on color hue to convey meaning. They utilize distinct patterns, hatching, and opacities, ensuring legibility for users with color vision deficiencies or situational glare49. Keyboard Navigation: All interactable elements, including the map camera controls, accordion toggles, and the timeline scrubber, are fully accessible via standard keyboard tabbing and arrow keys. Mobile Reflow: The interface utilizes flexible grids to ensure the analytical briefing stacks logically below the map on narrow viewports without requiring horizontal scrolling or awkward zooming. Cognitive Load: The progressive disclosure hierarchy prevents overwhelming the user. Information is chunked into logical units, and white space is heavily utilized to separate distinct phases of the event. ARIA-Live Regions for Dynamic Updates: When the timeline scrubber is moved, dynamic updates to the analytical briefing must be announced to screen readers. Crucially, the aria-live="polite" attribute is used to ensure the screen reader waits for a pause in the user's interaction before announcing the new timeline phase. The aria-live="assertive" or role="alert" attributes are strictly avoided for timeline updates, as they will disrupt the user's flow and create a chaotic auditory experience22. Assertive alerts are reserved solely for critical system failures (e.g., API timeouts). Numerical Formatting: Large numbers (e.g., populations, distances) use localized grouping separators, and coordinates are formatted consistently with cardinal directions for immediate legibility.
10. Ethical and Educational Boundaries
Simulating catastrophic events carries profound ethical responsibilities. The interface is designed to support serious educational inquiry while strictly preventing misuse or psychological harm. The tone and framing of the simulation rely heavily on the Centers for Disease Control and Prevention (CDC) Crisis and Emergency Risk Communication (CERC) guidelines41. Avoiding Operational Targeting: The simulation accepts only minimal inputs and deliberately obscures the ability to fine-tune height-of-burst, precise fission-fusion fractions, or specific delivery vehicles. It will not calculate target optimization, provide strike planning data, or offer device construction insights. Avoiding False Scientific Authority: By heavily prioritizing uncertainty disclosures and explicitly stating model assumptions, the simulation refuses to act as an infallible crystal ball. It presents a plausible outcome, not a certain one, maintaining humility regarding the limits of simulation46. Real Casualty Prediction: The simulation does not output precise, integer-level casualty figures (e.g., "14,532 dead"). Instead, it reports on "populations at extreme risk" or "severe casualty probabilities," maintaining the focus on systemic vulnerability rather than macabre accounting. Invisible AI Invention: The strict AI explanation boundaries and required visual disclosures ensure the user always knows when they are reading generated prose versus deterministic data, preventing the AI from usurping the authority of the physics model. CERC Principles Integration: Following CERC guidelines, the tone of the interface is respectful, empathetic to the gravity of the subject matter, and objective42. It avoids gamification, scoring systems, or sensationalized aesthetics. The goal is to preserve the chilling educational value of the physical realities—honoring the devastating nature of nuclear weapons—rather than reducing the result to a generic, easily dismissible warning or a detached video game.
11. Final Recommended Product Specification
The unified sequence of the product experience, integrating all previously defined systems, is specified as follows:
1. Creation Screen: A global map view. The user is prompted to select a site. The interface is clean, displaying only the map, a search/selection tool, and the overarching educational boundaries.
2. Locked Site: Upon clicking the globe, the camera centers on the coordinates. A minimal modal appears requesting the selection of a broad event or weapon class (e.g., "Minimal Fission Device," "Strategic Atmospheric Detonation"). No other inputs are permitted.
3. Calculation Transition: Upon commit, the modal disappears. The screen dims slightly. A deterministic loading state indicates that physics models, population data, and systemic risk assessments are being calculated.
4. Result Briefing: The interface resolves into the Desktop or Mobile Wireframe structure. The camera is locked to prevent spatial disorientation19. The Immediate Confirmation and What Happened summaries are visible. The map displays the Phase 1 visual overlays.
5. Globe Effects: The user manipulates the timeline scrubber at the bottom of the screen. The map and the sidebar dynamically update to show the progression from prompt physical effects to systemic fallout.
6. Uncertainty Integration: As the user expands the causal explanations in the sidebar, uncertainty badges and confidence intervals are displayed alongside every causal claim, forcing an acknowledgment of model limitations.
7. Branch Comparison: The user selects the Branch Comparison toggle. A matrix appears overlaying the briefing, showing how altered environmental assumptions would shift the current timeline, facilitating deep comparative analysis.
8. Revision: The user selects a reset function, clearing the current state and returning to the Creation Screen to explore a different geography or event class.
9. Failure States: If the AI explanation engine times out, the text boxes instantly populate with pre-formatted, deterministic string templates. If the map tiles fail to load, a stylized vector fallback maintains the spatial context without breaking the application.
12. Acceptance Criteria
To ensure the product meets these rigorous standards and fulfills its educational mandate, development must satisfy the following 60 measurable acceptance criteria:
| ID | Category | Criterion Description |
|---|---|---|
| 1 | Inputs | The system must only accept geographic coordinates and a single categorical event class as inputs. |
| 2 | Inputs | The system must actively prevent the user from inputting desired casualty counts or infrastructure damage goals. |
| 3 | Inputs | The system must actively prevent the user from fine-tuning the height of burst or specific weapon engineering parameters. |
| 4 | Processing | The simulation must calculate physical effects deterministically using established unclassified models (e.g., Glasstone and Dolan). |
| 5 | Processing | The calculation transition state must display a loading indicator for no longer than 5 seconds to maintain user engagement. |
| 6 | Explainability | The result must explicitly explain consequences that were not selected by the user (e.g., atmospheric loading, systemic stress). |
| 7 | Explainability | Every reported consequence must link to an initiating fact, scenario condition, or explicit assumption via UI badges. |
| 8 | Explainability | The immediate summary must be written at an eighth-grade reading level to ensure broad public comprehension. |
| 9 | Explainability | The causal explanation must strictly follow the sequence: event → disruption → pressure → movement → response → economic → recovery/escalation. |
| 10 | Explainability | Causal chains must be presented in an expandable accordion UI rather than complex node-link graphs. |
| 11 | UI/UX | The displayed coordinates on the briefing screen must identically match the committed event input. |
| 12 | UI/UX | The camera must lock to the selected site during the initial briefing presentation to establish context. |
| 13 | UI/UX | The map must prevent user-initiated tilt and rotation during the locked briefing phase to prevent disorientation. |
| 14 | UI/UX | The left sidebar (or mobile bottom tab) must house the analytical briefing template components. |
| 15 | UI/UX | The interface must strictly prohibit gamification elements, including scores, achievements, or win-states. |
| 16 | Maps | Visual overlays must utilize texture, hatching, or gradients to indicate probability zones, avoiding solid, absolute lines. |
| 17 | Maps | The map legend must dynamically update based on the currently displayed overlays associated with the timeline. |
| 18 | Maps | Overlays must not rely solely on color hue for differentiation, ensuring accessibility for colorblind users. |
| 19 | Maps | If external map tiles fail to load, a vector fallback must render the geographic context to prevent complete application failure. |
| 20 | Timeline | The interface must feature a horizontal date scrubber anchored to the bottom of the viewport. |
| 21 | Timeline | The result summary text and globe visuals must synchronously show the exact same phase and simulated date. |
| 22 | Timeline | The timeline must include visually distinct phase markers representing critical temporal thresholds (e.g., 1 Hour, 24 Hours). |
| 23 | Timeline | Scrubbing the timeline backward must accurately and smoothly reverse the visual and textual states. |
| 24 | Timeline | Long-term projections must be visually distinct (e.g., dashed lines or faded opacities) from immediate deterministic effects. |
| 25 | AI | The deterministic baseline result must remain fully available and populate instantly when AI explanation fails or times out. |
| 26 | AI | The LLM must receive a strictly formatted JSON payload containing only the deterministic results and assumptions. |
| 27 | AI | The LLM response must strictly conform to a predefined, validated JSON schema prior to rendering. |
| 28 | AI | The system must automatically reject LLM outputs that contain claims, figures, or data not present in the deterministic payload. |
| 29 | AI | The LLM must append citation links connecting generated prose directly to the deterministic payload lines. |
| 30 | AI | The LLM request must timeout and immediately trigger the deterministic fallback template after 4.5 seconds. |
| 31 | AI | Any AI-generated text must be accompanied by a persistent, visible disclosure badge indicating its synthetic origin. |
| 32 | AI | The system must log the seed, model version, and payload for every generated explanation to support auditing. |
| 33 | Uncertainty | Uncertainty metrics must appear directly adjacent to their affected conclusions, not relegated to footers. |
| 34 | Uncertainty | Uncertainty language must utilize the dual-scale format, pairing qualitative text with a numerical probability range. |
| 35 | Uncertainty | The system must explicitly state when generalized global averages are used due to missing localized geographic data. |
| 36 | Uncertainty | The system must explicitly disclose idealized assumptions (e.g., flat terrain) that alter wave propagation physics. |
| 37 | Branching | The branch comparison view must present data in a side-by-side or matrix format for immediate visual contrast. |
| 38 | Branching | The user must not be able to manually select the branch consequence; they may only view pre-calculated alternative contexts. |
| 39 | Branching | Branch comparisons must hold the site location and event class constant across all scenarios. |
| 40 | Branching | The comparison matrix must explicitly highlight the delta in systemic pressures and time-to-peak metrics between branches. |
| 41 | Accessibility | All interactive elements, including camera controls and timeline scrubbers, must be fully accessible via keyboard tab navigation. |
| 42 | Accessibility | The DOM structure must order the critical summary before the deep causal chains for screen reader prioritization. |
| 43 | Accessibility | Dynamic timeline updates to the briefing text must utilize the aria-live="polite" attribute to prevent auditory interruption. |
| 44 | Accessibility | The aria-live="assertive" attribute must be restricted exclusively to critical system failures or timeouts. |
| 45 | Accessibility | All charts, matrices, and visual overlays must be backed by hidden, accessible textual summaries. |
| 46 | Accessibility | The UI must fluidly reflow to a single-column layout on viewports narrower than 768px. |
| 47 | Accessibility | Large numerical outputs (e.g., populations, distances) must utilize localized grouping separators. |
| 48 | Accessibility | The interface must meet or exceed WCAG 2.1 AA contrast ratios for all textual elements. |
| 49 | Ethics | The simulation must permanently display an educational boundary disclaimer explicitly forbidding operational use. |
| 50 | Ethics | The system must not output precise, exact integer casualty counts under any circumstances. |
| 51 | Ethics | Casualty estimates must be exclusively framed as "populations at extreme risk" or "probability of severe injury." |
| 52 | Ethics | The UI must not include operational military language (e.g., "Target destroyed," "Kill probability," "Yield optimization"). |
| 53 | Ethics | The language tone must remain objective, respectful, and empathetic, avoiding sensationalism per CERC guidelines. |
| 54 | Ethics | The system must clearly cite the provenance of the underlying physical models within the analytical briefing. |
| 55 | Integration | Expanding a causal narrative accordion must not shift or reset the map viewport camera. |
| 56 | Integration | Tooltips explaining physical phenomena must not obstruct or overlap the primary text summary. |
| 57 | Integration | The branch comparison matrix must be easily dismissible via a single click or keyboard ESC press. |
| 58 | Security | The UI must aggressively sanitize all inputs to prevent injection attacks during coordinate or class selection. |
| 59 | Security | The AI validation and schema-checking layer must run securely on the server side, not the client side. |
| 60 | Overall | The entire post-commit sequence must organically guide the user from visual impact to systemic understanding without requiring external documentation. |
13. Traceability Matrix
To ensure the recommendations provided in this report are grounded in established research, the following matrix connects the major design decisions to their supporting evidence and primary sources.
| Recommendation / Design Decision | Supporting Evidence & Domain Principles | Source Citations |
|---|---|---|
| Input Minimization & Radial Visuals | Public engagement thrives on minimal friction; radial blast effects are universally understood mental models for nuclear events. | 1 |
| Causal Chains over Node-Link Graphs | Node-link diagrams induce cognitive overload; linear, expandable narratives improve comprehension of system dynamics. | 34 |
| Dual-Scale Uncertainty Language | Qualitative terms ("Likely") are misinterpreted by the public; they must be paired with numerical bounds. | 15 |
| Extrinsic Cartographic Uncertainty | Utilizing texture, blur, and gradients prevents users from interpreting probabilistic bounds as absolute geographic lines. | 38 |
| Camera Locking & Viewport Easing | Spatial context is lost if the camera rotates freely during data presentation; lookAtTransform stabilizes the user's view. | 18 |
| Polite ARIA-Live Timeline Updates | Screen readers must not be interrupted (assertive) during routine timeline scrubbing; updates must wait for user pauses (polite). | 22 |
| Empathetic & Objective Framing | Disaster communication must be respectful and explicitly state what is known/unknown to build trust and prevent panic. | 41 |
| Branch Comparison via Assumption Shifts | Educational value in wargaming and intelligence analysis comes from testing alternative contexts against identical events. | 13 |
| Constrained LLM Output Generation | AI explanations must be forced into strict JSON schemas (e.g., Pydantic) to prevent hallucinations of non-deterministic data. | 36 |
| Prompt vs. Delayed Physical Effects | Nuclear physical realism dictates a strict temporal separation between initial flash/blast and subsequent systemic/fallout cascades. | 4 |
Works cited
1. Nukemap \- Wikipedia, https://en.wikipedia.org/wiki/Nukemap
2. NUKEMAP \- Alex Wellerstein, https://alexwellerstein.com/projects/nukemap/
3. Full article: NUKEMAP creator Alex Wellerstein puts nuclear risk on the radar, https://www.tandfonline.com/doi/full/10.1080/00963402.2017.1338001
4. The Effects of Nuclear Weapons \- Glasstone and Dolan | Historical Documents, https://www.atomicarchive.com/resources/documents/effects/glasstone-dolan.html
5. The Effects of Nuclear Weapons \- Glasstone and Dolan | Chapter II \- Atomic Archive, https://atomicarchive.com/resources/documents/effects/glasstone-dolan/chapter2.html
6. Hazus \- FEMA Flood Map Service Center, https://msc.fema.gov/portal/resources/hazus
7. Hazus | FEMA.gov, https://www.fema.gov/flood-maps/products-tools/hazus
8. HAZUS-MH Coastal Flood Model \- Overview \- ArcGIS Online, https://www.arcgis.com/home/item.html?id=79c14c02c87d427d945866b8730c6181
9. Guide to the Workspace | HURREVAC, https://www.hurrevac.com/wp-content/uploads/2026/03/2026-HURREVAC-workspace-guide.pdf
10. Key Features – HURREVAC | Home, https://www.hurrevac.com/program-information/key-features/
11. HURREVAC Quick Reference Guide, https://www.hurrevac.com/wp-content/uploads/2026/03/2026-HURREVAC-Quick-Reference-Guide.pdf
12. Analysis of Competing Hypotheses \- Rodolfo Santos Flaborea \- Medium, https://anticitizenone.medium.com/analysis-of-competing-hypotheses-176bd8147dbc
13. Analysis of competing hypotheses \- Wikipedia, https://en.wikipedia.org/wiki/Analysis\_of\_competing\_hypotheses
14. Analysis of Competing Hypotheses (ACH part 1\) \- SANS ISC, https://isc.sans.edu/diary/22460
15. How are uncertainties communicated? \- Climate-ADAPT, https://climate-adapt.eea.europa.eu/en/knowledge/tools/uncertainty-guidance/topic2/index\_html
16. The interpretation of IPCC probabilistic statements around the world, https://researchportalplus.anu.edu.au/en/publications/the-interpretation-of-ipcc-probabilistic-statements-around-the-wo/
17. Improving communication of uncertainty in the IPCC reports David V. Budescu, https://www.ipcc.ch/site/assets/uploads/2016/02/Budescu\_IPCC\_Communication\_Meeting\_OSLO\_February\_2016.pdf
18. ScreenSpaceCameraController \- Cesium Documentation, https://cesium.com/learn/ion-sdk/ref-doc/ScreenSpaceCameraController.html
19. Control the Camera \- Cesium, https://cesium.com/learn/cesiumjs-learn/cesiumjs-camera/
20. Viewport | Maps SDK | iOS | Mapbox, https://docs.mapbox.com/ios/maps/guides/camera-and-animation/viewport/
21. ARIA Authoring Practices Guide | APG | WAI \- W3C, https://www.w3.org/WAI/ARIA/apg/
22. ARIA live regions \- MDN Web Docs \- Mozilla, https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Live\_regions
23. Map of the Week: NUKEMAP | Mappenstance. \- University of Richmond, https://blog.richmond.edu/livesofmaps/2022/03/29/nukemap-alex-wellersteins-mapping-tool/
24. NUKEMAP FAQ \- The Nuclear Secrecy Blog, https://nuclearsecrecy.com/nukemap/faq/
25. Hazus \- U.S. Climate Resilience Toolkit, https://toolkit.climate.gov/tool/hazus
26. HAZUS: FEMA's Flood Damage Estimation Tool Explained \- Continuuiti, https://continuuiti.com/blog/hazus/
27. Improving Intelligence Analysis with ACH \- Pherson, https://pherson.org/wp-content/uploads/2013/06/Improving-Intelligence-Analysis-with-ACH.pdf
28. Uncertainty (Chapter 17\) \- A Critical Assessment of the Intergovernmental Panel on Climate Change, https://www.cambridge.org/core/books/critical-assessment-of-the-intergovernmental-panel-on-climate-change/uncertainty/3B238E862AB873D1D746F8A594DC6DFD
29. Guidance Note for Lead Authors of the IPCC Fifth Assessment Report on Consistent Treatment of Uncertainties, https://www.ipcc.ch/site/assets/uploads/2017/08/AR5\_Uncertainty\_Guidance\_Note.pdf
30. Camera position | Maps SDK | Android Docs | Mapbox, https://docs.mapbox.com/android/maps/guides/camera-and-animation/camera/
31. Technique ARIA19:Using ARIA role=alert or Live Regions to Identify Errors \- W3C, https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA19
32. What Are ARIA Live Regions? \- Bureau of Internet Accessibility, https://www.boia.org/blog/what-are-aria-live-regions
33. Use ARIA to announce updates and messaging \- Centre for Excellence in Universal Design, https://universaldesign.ie/communications-digital/web-and-mobile-accessibility/web-accessibility-techniques/developers-introduction-and-index/use-aria-appropriately/use-aria-to-announce-updates-and-messaging
34. Causal loop diagrams | OpenLearn \- The Open University, https://www.open.edu/openlearn/science-maths-technology/engineering-technology/causal-loop-diagrams
35. Nuclear Weapons \- Outrider, https://outrider.org/nuclear-weapons
36. LLM Structured Output in 2026: Stop Parsing JSON with Regex and Do It Right, https://dev.to/pockit\_tools/llm-structured-output-in-2026-stop-parsing-json-with-regex-and-do-it-right-34pk
37. Generate structured output from LLMs with Dottxt Outlines in AWS | Artificial Intelligence, https://aws.amazon.com/blogs/machine-learning/generate-structured-output-from-llms-with-dottxt-outlines-in-aws/
38. Visualizing Uncertainty in GIS Data | PDF | Geographic Information System \- Scribd, https://www.scribd.com/document/895369887/11
39. VISUALIZING UNCERTAIN INFORMATION \- Semantic Scholar, https://pdfs.semanticscholar.org/f89c/70913c39be1b56445ccb5e11785eea010ec3.pdf
40. Perspectives on Uncertainty, Geovisualization, and Geographical Reasoning / Decision-making \- NCG, https://ncgeo.nl/wp-content/uploads/2024/05/MacEachren\_Uncertainty\_ITC.pdf
41. Crisis & Emergency Risk Communication (CERC) Manual \- CDC, https://www.cdc.gov/cerc/php/cerc-manual/index.html
42. Crisis and Emergency Risk Communications (CERC): Radiation Emergencies \- CDC, https://www.cdc.gov/radiation-emergencies/php/communication-resources/cerc-rad.html
43. Communicating Radiation Risks: Crisis Communications for Emergency Responders \- National Response Team, https://nrt.org/sites/2/files/Communication%20Radiation%20Risk.pdf
44. The Effects Nuclear Weapons \- UCSB Experimental Cosmology Group, https://www.deepspace.ucsb.edu/wp-content/uploads/2013/01/Effects-of-Nuclear-Weapons-1977-3rd-edition-complete.pdf
45. Effects of Nuclear Weapons \- Princeton University, https://www.princeton.edu/\~aglaser/lecture2007\_weaponeffects.pdf
46. glasstone-dolan-1977.pdf \- Stanford, http://large.stanford.edu/courses/2017/ph241/liang2/docs/glasstone-dolan-1977.pdf
47. War Gaming Methodology \- RAND, https://www.rand.org/content/dam/rand/pubs/research\_memoranda/2008/RM2413.pdf
48. Wargaming: The Surprisingly Effective Tool That Can Help Us Prepare for Modern Crises, https://www.rand.org/pubs/commentary/2025/11/wargaming-the-surprisingly-effective-tool-that-can.html
49. The Visualization of Uncertainty | GEOG 486 \- EMS Online Courses, https://courses.ems.psu.edu/geog486/node/906
50. Live regions & status messages — EqualWeb Academy, https://www.equalweb.com/academy/learn/lessons/live-regions.html