DUNE is an advanced point kinetics nuclear reactor simulator with a graphical user interface (GUI) designed for educational purposes and reactor physics demonstrations. This package provides a comprehensive simulation environment that models nuclear reactor behavior, including neutronics, thermal hydraulics, and control systems.
- Real-time Reactor Simulation: Implements a 6-group delayed neutron precursor model based on point kinetics equations
- Fission Product Poisoning: Complete Xenon-135 and Samarium-149 decay chains with reactivity feedback
- Interactive GUI: Full-screen 8-panel layout with wxPython and matplotlib for comprehensive visualization
- Thermal-Hydraulic Modeling: Temperature-dependent heat transfer with Dittus-Boelter correlation
- Dynamic Coolant Flow Control: Automatic flow rate adjustment based on reactor power (200-1200 kg/s)
- Manual Coolant Control Mode: User-controlled coolant flow rate with independent operation
- Control Systems: Supports both manual control rod operation and automatic PID-based power control
- Safety Systems: Automatic SCRAM functionality based on temperature setpoints
- Burnup & Isotope Depletion: Continuous Burnup with effect on reactivity.
- Arduino Integration: Interfaces with physical 3D printed reactor model for hands-on demonstrations
- CSV Data Logging: Automatic timestamped data logging including poison concentrations
- Educational Tool: Designed for nuclear engineering education
This module contains the fundamental reactor physics equations and parameters:
-
Point Kinetics Model: Implements the time-dependent neutron diffusion equations with 6 delayed neutron groups for U-235
-
External Neutron Source: Constant source term S = 10⁵ n/cm³/s representing spontaneous fission, startup sources, or (α,n) reactions
-
Delayed Neutron Data:
- Beta values (β₁ through β₆): Individual delayed neutron fractions
- Lambda values (λ₁ through λ₆): Decay constants ranging from 0.0124 to 3.01 s⁻¹
- Total delayed neutron fraction: β_total = 0.0065
- Average neutron lifetime: Λ = 10⁻⁵ seconds
-
Thermal-Hydraulic Models:
- Temperature-dependent UO₂ fuel heat capacity
- Flow-dependent heat transfer using Dittus-Boelter correlation
- Coupled fuel and coolant temperature evolution
- Reactivity feedback from temperature coefficients (α_T = -0.007 × 10⁻⁵ per K per beta)
-
Fission Product Poisoning (NEW in v0.2):
- Xenon-135 Dynamics: Complete I-135 → Xe-135 decay chain
- I-135 production from fission (γ_I = 0.061)
- Xe-135 formation from I-135 decay (λ_I = 2.87 × 10⁻⁵ s⁻¹)
- Xe-135 neutron absorption (σ_a = 2.6 × 10⁶ barns)
- Xe-135 radioactive decay (λ_X = 2.09 × 10⁻⁵ s⁻¹)
- Samarium-149 Dynamics: Full Nd-149 → Pm-149 → Sm-149 chain
- Nd-149 production from fission (γ_Nd = 0.0113)
- Pm-149 formation and decay (half-life: 53.08 hours)
- Sm-149 as stable poison (σ_a = 40,800 barns)
- Xenon-135 Dynamics: Complete I-135 → Xe-135 decay chain
-
Burnup and Isotope Depletion (NEW in v0.3):
- U-235 Depletion: Fission consumption with scaled cross-section (σ_f = 585 barns)
- U-238 Capture: Conversion to Pu-239 (σ_c = 2.68 barns)
- Pu-239 Buildup: Production from U-238, consumption by fission (σ_f = 750 barns)
- Fission Products: Accumulation tracking for reactivity penalty
- Burnup Tracking: MWd/kgU with demonstration timescale scaling (BURNUP_SCALE = 1e-3)
- Excess Reactivity: Initial ρ_excess = $0.05 for subcritical startup simulation
- Reactivity contributions: ρ = ρ_excess + ρ_rod + ρ_temp + ρ_Xe + ρ_Sm + ρ_burnup
-
Control Rod Worth: Total reactivity worth of $0.2 (fully inserted to fully withdrawn)
- Sinusoidal differential worth curve (peak at core midplane)
- Realistic importance-weighted reactivity insertion
-
Power Calculation: Converts neutron population to thermal power output using:
- Energy per fission: 3.204 × 10⁻¹¹ J
- Macroscopic fission cross-section: 0.0065 cm⁻¹
- Reactor volume: 3 × 10⁶ cm³
The DUNEReactor class provides the main interface for reactor operations:
- State Vector Management: Tracks 20 variables:
- [neutrons/cc, C₁-C₆ precursors, T_fuel, T_coolant, rod position, I-135, Xe-135, Nd-149, Pm-149, Sm-149, N235, N238, N239Pu, NFP, Burnup]
- Time Integration: Uses scipy's odeint for solving the stiff ODE system
- Control Rod Dynamics: Realistic rod motion with rate limiting and $0.2 total reactivity worth
- PID Power Control: Automatic power level regulation
- Dynamic Coolant Flow Control: Automatic flow rate adjustment based on reactor power output
- Power-based flow mapping: 200 kg/s (low power) to 1200 kg/s (high power)
- Prevents thermal shock with smooth tanh-based ramping
- Manual Coolant Control Mode: Direct user control of flow rate independent of power level
- Safety Systems:
- Fuel temperature SCRAM at 1700 K
- Coolant temperature SCRAM at 700 K
- Automatic control rod insertion on SCRAM
The graphical interface built with wxPython provides:
-
Full-Screen 8-Panel Layout (GridSpec 3 rows × 8 columns):
- Top Row: Real-time power output (MW) vs time (full width)
- Middle Row: Reactivity ($), Fuel Temperature (K), Coolant Temperature (K)
- Bottom Row: Xenon-135, Samarium-149, Burnup (MWd/kgU), Isotope Concentrations
-
Control Interfaces:
- Manual control rod position slider
- Power setpoint control with PID mode toggle
- Coolant flow rate adjustment with manual control toggle
- SCRAM button for emergency shutdown
- Pause/Resume simulation control
- Zoom controls for plot viewing
-
Monitoring Displays:
- Current reactor power (MW)
- Fuel and coolant temperatures (K)
- Control rod position (%)
- Coolant flow rate (kg/s)
- Xenon-135 concentration (atoms/cm³)
- Samarium-149 concentration (atoms/cm³)
-
Data Logging System:
- Automatic CSV file generation with timestamps
- Records all critical parameters every 0.5 seconds
- Saves to SimulationData/ folder automatically
- Includes: time, neutron density, power, reactivity, temperatures, flow rate, rod position, Xe-135, Sm-149
- Burnup tracking: Burnup (MWd/kgU), U-235, U-238, Pu-239, fission products
- Full poison and isotope concentration data for post-analysis
-
Arduino Communication: Serial interface to physical reactor model
The Arduino code provides physical feedback through:
- Servo Control: Moves 3D printed control rods to match simulator position (case 'r')
- LED Indication: RGB LED brightness represents reactor power level
- Blue LED: Normal operation - power level indicator (case 'p')
- Red LED: SCRAM condition (case 's')
- Independent Pump Control: PWM-driven motor for coolant pump simulation (case 'c')
- Decoupled from power level for realistic coolant system control
- Motor speed maps to coolant flow rate: 200-1200 kg/s → PWM 20-180
- Allows demonstration of thermal-hydraulic transients
Serial Command Protocol:
'p' + value (0-250): Power level → Blue LED brightness'c' + value (20-180): Coolant flow → Pump motor speed'r' + value (5-140): Rod position → Servo angle's' + value (0-1): SCRAM state → Red LED on/off
Circuit Diagram:
The circuit diagram shows the complete wiring configuration for the Arduino-based physical reactor model, including:
- Servo motor connections (Pin 9) for control rod actuation
- RGB LED wiring (Pins 6 and 11) for power level indication
- Motor PWM control (Pin 3) for coolant pump visualization
- Power supply and ground connections
- Resistor values for LED current limiting
The simulator solves the coupled point kinetics equations with 6 delayed neutron groups and an external neutron source:
Where:
-
$n$ = neutron population density -
$C_i$ = delayed neutron precursor concentration for group i -
$\rho$ = reactivity (includes temperature feedback) -
$\beta$ = total delayed neutron fraction -
$\beta_i$ = delayed neutron fraction for group i -
$\Lambda$ = prompt neutron lifetime -
$\lambda_i$ = decay constant for group i -
$S$ = external neutron source strength (n/cm³/s), representing spontaneous fission, startup sources, or (α,n) reactions
The total reactivity includes contributions from:
- Excess Reactivity: Initial core excess reactivity ($0.05) for subcritical startup
- Control Rod Position: Primary control mechanism ($0.2 total worth)
- Fuel Temperature: Doppler broadening effect (negative feedback)
- Coolant Temperature: Moderator temperature coefficient (negative feedback)
- Xenon-135 Poisoning: Transient neutron absorption (negative, time-dependent)
- Samarium-149 Poisoning: Equilibrium neutron absorption (negative, builds slowly)
- Fuel Burnup: U-235 depletion and Pu-239 buildup effects (negative over long timescales)
Fuel temperature evolution:
Coolant temperature evolution:
Where:
-
$Q_{fission}$ = fission power generated -
$h$ = heat transfer coefficient (flow-dependent) -
$A_c$ = fuel-coolant contact area (4 × 10⁵ cm²) -
$\dot{m}_c$ = coolant mass flow rate -
$C_p$ = specific heat capacity
The DUNE simulator features a comprehensive full-screen interface with eight synchronized real-time plots and extensive monitoring capabilities.
The main interface shows eight synchronized plots arranged in a 3-row grid layout:
Top Row (2 Panels):
- Power Plot: Real-time thermal power output (MW) vs time
- Shows exponential rise during startup, steady-state operation, and decay during shutdown
- Reactivity Plot: Total reactivity ($) vs time showing all feedback contributions
- Displays contributions from control rods, temperature feedback, poison effects, and burnup
Middle Row (2 Panels):
- Fuel & Coolant Temperature Plot:
- Fuel temperature (K) vs time (red)
- Demonstrates thermal inertia and Doppler feedback effects
- Coolant temperature (K) vs time (blue)
- Shows heat transfer dynamics and flow rate effects
- Xenon-135 & Samarium-149 Plot:
- Xe-135 concentration (atoms/cm³) vs time (purple)
- Tracks transient fission product poison buildup and decay
- Sm-149 concentration (atoms/cm³) vs time (orange)
- Shows slow equilibrium poison accumulation
Bottom Row (4 Panels):
- Burnup Plot: Core average burnup (MWd/kgU) vs time
- Tracks cumulative fuel depletion over operation
- Isotope Plot: Relative concentrations of U-235, U-238, Pu-239, and fission products
- Visualizes fuel composition evolution during burnup
Key GUI Features:
- Live parameter updates every 0.5 seconds
- Adjustable time zoom for detailed transient analysis
- Real-time numerical displays for all critical parameters
- Synchronized x-axis across all plots for correlation analysis
- SCARM Button for manual SCARM
- Pause Button for pause the simulation
- Power Ctrl for manual power control
- Flow Ctrl for manually control the flow rate
- Prompt Jump Mode for analysing the prompt jump scenario
- Rod SetPoint Slider for manual rod position control
- Rod % Withdrawn shows the current rod position
- Plot Zoom for changing the x-axix time scale for better understanding of transient
- And the below boxes are showing the exact value of different parameters in the graphs
Initial Condition before activating the Power Control Mode:
After activating the Power Control Mode for a targeted power:
Autometically adjust the control rod position through PID controller to achieve the targeted power level.
Initial Condition before activating the Flow Control Mode:
After activating the Flow Control Mode and Changing the Flow rate:
Independent coolant flow control enables investigation of thermal-hydraulic effects decoupled from automatic power-based control.
This image demonstrates a typical reactor startup sequence showing exponential power rise as control rods are withdrawn. The behavior follows the reactor period equation demonstrating subcritical to critical transition.
This captures a reactivity insertion accident resulting in a prompt jump. When we activate the Prompt jump Mode, a reactivity of 0.003$ is being inserted instantly, causing an instantaneous power jump followed by temperature feedback stabilization.
Here the SCARM is triggred by the manual SCARM button. Shows rapid power decrease as control rods are fully inserted and negative reactivity is added. An automatic SCRAM (Safety Control Rod Axe Man) event can be also triggered by exceeding temperature safety limits.
Long-term simulation showing fission product poison buildup:
- Xenon-135: Reaches equilibrium in ~40-50 hours with characteristic oscillations
- Samarium-149: Builds slowly over days, approaching stable equilibrium
- Both poisons insert negative reactivity requiring compensating rod withdrawal
Shows the Continuous Burnup of fuel and the continuous change in concentration of the nuclides due to Burnup.
All the Simulation data will be autometically saved in a CSV file inside the SimulationData folder. The name will be saved as reactor_sim_Date_Time.csv
The following video demonstrations showcase the DUNE reactor simulator in action:
Media/Videos/Reactor Start-Up.webm
Demonstrates the complete reactor startup sequence with control rod withdrawal and exponential power rise.
Media/Videos/Power Control Mode.webm
Shows the automatic PID-based power control system maintaining setpoint power levels.
Media/Videos/Coolant Flow Control Mode.webm
Demonstrates manual coolant flow rate control and its effects on reactor temperatures.
Media/Videos/Reactor SCARM.webm
Shows emergency shutdown procedure with automatic safety system activation.
Media/Videos/Xenon-135 Negative Reactivity Effect at Start-Up.webm
Illustrates the transient xenon poisoning effects during reactor startup operations.
Media/Videos/Data Collection in CSV.webm
Demonstrates the automatic data logging system and CSV file generation for post-analysis.
DUNE requires Python 3.6 or higher and the following dependencies:
- numpy (≥1.20): Numerical computing and array operations
- scipy (≥1.6): ODE solver for reactor kinetics equations
- matplotlib (≥3.3): Plotting and data visualization
- wxPython (≥4.1): Cross-platform GUI toolkit
- pyserial (≥3.0): Serial communication with Arduino (optional)
-
Clone the repository:
git clone https://github.com/Hridoy-Kabiraj/DUNE.git cd DUNE -
Install in development mode:
python setup.py develop
Or using pip:
pip install -e . -
Verify installation:
DUNE
For physical reactor model integration:
- Upload
arduino/reactorSketch/reactorSketch.inoto your Arduino board - Connect servo to pin 9, RGB LED to pins 6 and 11, and motor to pin 3
- Connect Arduino via USB before starting the simulator
- The simulator will automatically detect and connect to the Arduino
Launch the reactor GUI with the command:
DUNEOr run directly with Python:
python DUNEReactor.py- Use the vertical slider to set control rod position (0-100%)
- Rods move at a realistic rate (~10%/second)
- Monitor reactivity in dollars displayed in real-time
- Watch power respond to rod movements with reactor period dynamics
- Check the "Power Control" toggle
- Set desired power level in the power setpoint box
- The PID controller automatically adjusts control rods to maintain setpoint
- Observe how the controller responds to temperature feedback
- Check the "Flow Ctrl" toggle next to coolant flow rate
- Enter desired coolant flow rate (200-1200 kg/s)
- System maintains user-specified flow rate independent of power level
- Useful for investigating thermal-hydraulic transients and cooling system effects
- Uncheck to return to automatic power-based flow adjustment
- Rod Position Slider: Manual control rod height (0% = fully inserted, 100% = fully withdrawn)
- Power Setpoint: Target power level in MW for automatic control
- Power Ctrl Checkbox: Enable/disable automatic PID power control
- Coolant Flow: Adjust coolant mass flow rate (200-1200 kg/s)
- Flow Ctrl Checkbox: Enable/disable manual coolant flow control
- Prompt Jump Mode Checkbox: Instantly inserts ~$0.003 reactivity for demonstrating prompt jump phenomenon
⚠️ WARNING: For educational demonstration only!- Instantly withdraws control rod by 6% when activated
- Automatic SCRAM remains enabled for safety
- Demonstrates the rapid power increase characteristic of positive reactivity insertion
- SCRAM Button: Emergency shutdown - inserts all control rods immediately
- Press again to reset SCRAM condition and unlock reactor
- Pause: Freeze simulation to examine current state
- Power Plot (Top Row): Real-time reactor power in MW spanning full width
- Reactivity Plot (Middle Left): Total reactivity in dollars ($) showing all feedback contributions
- Temperature Plots (Middle Center/Right): Separate fuel and coolant temperature displays in Kelvin
- Poison Plots (Bottom Left/Center-Left): Xenon-135 and Samarium-149 concentrations in atoms/cm³
- Burnup Plot (Bottom Center-Right): Core burnup in MWd/kgU
- Isotope Plot (Bottom Right): Relative U-235, U-238, Pu-239, and FP concentrations
- Rod Height Indicator: Vertical bar showing current rod position
Value Panel (Scrollable with Section Headers):
- POWER & REACTIVITY: Power (MW), Reactivity ($), Rod position (%)
- TEMPERATURE: Fuel temperature (K), Coolant temperature (K), Flow rate (kg/s)
- FP POISONS: Xenon-135 (atoms/cm³), Samarium-149 (atoms/cm³)
- BURNUP & ISOTOPES: Burnup (MWd/kgU), U-235, U-238, Pu-239 relative concentrations
- Time Scale: Adjustable zoom for viewing different time windows
- Verify coolant flow is adequate (default 200 kg/s)
- Slowly withdraw control rods (increase position from 0%)
- Watch reactivity approach zero dollars
- Continue rod withdrawal until desired power is reached
- Fine-tune position to stabilize at target power
-
Subcritical (
$ρ < 0$ ): Power decreasing, reactor shutting down -
Critical (
$ρ = 0$ ): Power stable, equilibrium condition -
Supercritical (
$ρ > 0$ ): Power increasing
- Fuel Temperature: Must stay below 1700 K (automatic SCRAM above)
- Coolant Temperature: Must stay below 700 K (automatic SCRAM above)
- Temperature increases lag behind power changes due to thermal inertia
- Higher coolant flow improves heat removal and lowers temperatures
- Automatic Recording: All simulations are logged automatically
- Storage Location: Data saved in
SimulationData/folder - Filename Format:
reactor_sim_YYYY-MM-DD_HH-MM-SS.csv - Logging Interval: Data recorded every 0.5 seconds
- Saved Parameters (15 columns):
- Time, neutron density, power (MW), reactivity ($)
- Fuel temperature, coolant temperature, flow rate, rod position
- Xenon-135 concentration, Samarium-149 concentration
- Burnup (MWd/kgU), U-235, U-238, Pu-239, Fission Products
- File Closure: CSV automatically saved when simulation exits
- Post-Processing: Open CSV files in Excel, MATLAB, Python, or other analysis tools
- Long-Term Studies: Ideal for analyzing poison transients and equilibrium behavior
The simulator includes realistic safety features:
-
Automatic SCRAM Triggers:
- Fuel temperature > 1700 K
- Coolant temperature > 700 K
- Both conditions cause immediate rod insertion
-
SCRAM Recovery:
- Click SCRAM button again to unlock
- Reactor must be manually restarted from subcritical state
- Delayed neutron precursors must rebuild (takes 30-60 seconds)
-
Physical Limits:
- Rods cannot be withdrawn beyond 100%
- Rods cannot be inserted below 0%
- Coolant flow has minimum/maximum bounds
- Start with rods at 0%
- Quickly move to 54% and hold (Write 54 in the Rod SetPoint Box)
- Observe exponential power rise
- Calculate reactor period from plot:
$T = \frac{t}{\ln(P_2/P_1)}$
- Establish steady state at high power (400+ MW)
- Suddenly reduce coolant flow by 50%
- Observe power reduction due to negative temperature feedback
- Demonstrates inherent safety of negative temperature coefficients
- Enable manual coolant control mode
- Start at steady state with normal flow (1000 kg/s)
- Reduce flow to minimum (200 kg/s) and observe temperature rise
- Increase flow to maximum (1200 kg/s) and observe cooling effect
- Note how reactor power self-regulates through temperature feedback
- Export CSV data and plot temperature vs. flow rate relationship
- WARNING: For educational observation only!
- Start reactor at low-to-moderate power level
- Enable Prompt Jump Mode by checking the checkbox in the GUI
- This instantly withdraws control rod by 3%, inserting ~$0.003 reactivity
- Observe the characteristic prompt jump in power
- Note how the power stabilizes due to temperature feedback
- Automatic SCRAM remains active for safety
- Demonstrates the reactor's response to sudden reactivity insertions
- Operate at high power
- Press SCRAM button
- Observe power decay from delayed neutrons
- Note the characteristic decay time (~80 seconds for 6-group model)
- Xenon Buildup: Start reactor at high power (500+ MW)
- Run for 24-48 hours to observe Xe-135 equilibrium
- Note reactivity decrease of ~0.03-0.05$ as xenon builds
- Xenon-Free Window: After SCRAM, xenon peaks then decays
- Restart window appears after ~11 hours when Xe-135 has decayed sufficiently
- CSV data captures full transient for analysis
- Long-term simulation (72+ hours) at steady power
- Observe slow Sm-149 buildup through Nd-149 → Pm-149 → Sm-149 chain
- Samarium reaches equilibrium in 3-5 days
- Compare equilibrium Sm-149 reactivity worth (smaller but permanent vs transient Xe-135)
- Export poison concentration data for decay chain analysis
- K-12 Students: Introduction to nuclear energy and reactor safety
- Undergraduate Engineering: Reactor physics and control systems
- Public Outreach: Demonstrations at science fairs and events
- Training: Basic reactor operation concepts
- Understand neutron population dynamics and delayed neutrons
- Learn about reactivity and reactor control
- Observe temperature feedback effects
- Experience safety system operation
- Appreciate the role of control systems in reactor operation
- Study fission product poison dynamics (Xenon-135 and Samarium-149)
- Analyze long-term reactor behavior and equilibrium conditions
- Understand reactivity management during fuel burnup
- Use with 3D printed physical model for tactile learning experience
- LED brightness provides visual feedback of power level
- Moving servo demonstrates control rod mechanism
- Combine with discussion of real reactor designs (PWR, BWR, etc.)
- ODE Solver: scipy.integrate.odeint with adaptive step sizing
- Time Step: Default 5 ms for stability with stiff equations
- Update Rate: GUI refreshes at 1 Hz, physics calculates at 500 Hz
- Numerical Stability: Implicit solver handles stiff reactor kinetics
- 6-group delayed neutron model (industry standard for training simulators)
- Complete Xenon-135 and Samarium-149 fission product chains
- Lumped parameter thermal hydraulics (0D approximation)
- Point kinetics (spatially averaged neutronics)
- Representative of small research reactor or PWR unit cell
- Control rod worth calibrated to $0.2 for realistic control margin
- Burnup and isotope depletion with scaled coefficients for demonstration timescales
- Real-time capable on modern hardware
- Scales to 1000x faster-than-real-time for rapid scenario testing
- Memory efficient with circular buffer for plot data
- Model-View-Controller design pattern
- Physics engine separated from GUI for testability
- Extensible for additional physics models
- Well-documented with inline comments
Arduino not detected:
- Check USB connection and permissions
- Verify correct COM port in device manager
- Ensure pyserial is installed:
pip install pyserial
GUI not displaying:
- Install wxPython:
pip install wxPython - On Linux, may need system packages:
sudo apt-get install python3-wxgtk4.0
Simulation crashes:
- Reduce time step if numerical instabilities occur
- Check that initial conditions are physical
- Ensure numpy/scipy versions are compatible
Slow performance:
- Increase plot update interval (decrease refresh rate)
- Reduce stored data history length
- Close other applications
Enable verbose output for troubleshooting:
# In DUNEReactor.py, add:
import logging
logging.basicConfig(level=logging.DEBUG)Potential improvements and extensions:
- Xenon-135 poisoning dynamics (Completed v0.2)
- Samarium-149 poisoning dynamics (Completed v0.2)
- Burnup and fuel depletion tracking (Completed v0.3)
- Isotope depletion: U-235, U-238, Pu-239, fission products (Completed v0.3)
- Multi-region core model (radial/axial variations)
- Improved neutron kinetics with spatial effects
- Advanced control algorithms (MPC, fuzzy logic)
- Load-following operation modes
- Grid frequency response simulation
- Multiple control rod banks
- CSV data export for post-processing (Completed v0.1)
- 8-panel full-screen layout with GridSpec (Completed v0.3)
- Poison concentration monitoring (Completed v0.2)
- Burnup and isotope concentration displays (Completed v0.3)
- Scrollable value panel with section headers (Completed v0.3)
- 3D reactor core visualization
- Neutron flux distribution animation
- Export data to HDF5 format
- Support for additional Arduino sensors (temperature, flow)
- Raspberry Pi integration for standalone operation
- Multiple 3D printed reactor units for comparison
- VR/AR visualization support
Contributions are welcome! Areas where help is needed:
- Documentation improvements and tutorials
- Additional example scenarios and lesson plans
- Testing on different platforms
- Bug reports and feature requests
- Translation to other languages
Please submit issues and pull requests on GitHub.
For comprehensive technical documentation, including detailed reactor physics derivations, implementation details, and experimental results, please refer to:
DUNE Project Report - Complete technical documentation covering:
- Theoretical background and nuclear physics equations
- System architecture and software design
- Hardware integration and Arduino implementation
- Validation and testing results
- Educational applications and case studies
- Performance analysis and benchmarking
This simulator has been used in:
- University reactor physics courses
- Science demonstrations
- Nuclear engineering department
- Original pyReactor concept: William Gurecky (https://github.com/wgurecky/pyReactor)
- Current development and enhancements: Hridoy Kabiraj
- Delayed neutron data from ENDF/B-VII.1 nuclear data library
- Fission product yield data from JEFF-3.3 library
- Inspiration from commercial reactor training simulators
- Special thanks to educators who provided feedback
- Nuclear Reactor Physics (Lamarsh & Baratta)
- Fundamentals of Nuclear Science and Engineering (Shultis & Faw)
- MIT OpenCourseWare: Nuclear Engineering
- OpenMC: Monte Carlo particle transport code
- SCALE: Comprehensive nuclear safety analysis suite
- Serpent: Reactor physics burnup calculation code
- American Nuclear Society (ANS)
- International Atomic Energy Agency (IAEA)
- Nuclear Energy Institute (NEI)
Q: Is this simulator accurate for real reactor design?
A: No. DUNE uses simplified point kinetics and 0D thermal hydraulics suitable for education and conceptual understanding. Real reactor design requires detailed 3D neutronics and CFD analysis.
Q: Can I use this for homework/projects?
A: Yes! The software is open source and free to use for educational purposes. Please cite this repository in your work.
Q: How realistic are the physics models?
A: The 6-group delayed neutron model is standard for training simulators. Thermal hydraulics are simplified but capture essential behavior. Good for qualitative understanding, not quantitative design.
Q: Why does the reactor SCRAM when I withdraw rods too quickly?
A: Rapid rod withdrawal causes power to rise exponentially. Power heats the fuel, and if temperature limits are exceeded, automatic SCRAM occurs. This demonstrates the importance of controlled startups.
Q: What's the difference between dollars and absolute reactivity?
A: Reactivity in dollars ($) is normalized by β (delayed neutron fraction). $1.00 is the prompt critical threshold. Absolute reactivity ρ has units of Δk/k.
Q: Can I modify the reactor parameters?
A: Yes! Edit reactorPhysics.py to change core size, fuel type, temperature coefficients, control rod worth, etc. Rerun python setup.py develop after changes.
Q: Why is there a delay after SCRAM before I can restart?
A: Delayed neutron precursors (with half-lives of 0.2 to 55 seconds) must decay. Real reactors also have xenon buildup considerations. In this simulator, Xe-135 concentration affects restart capability.
Q: What's the difference between Xenon-135 and Samarium-149?
A: Xenon-135 is a transient poison (9.2 hour half-life) with very high absorption cross-section (2.6M barns). It builds up and decays relatively quickly. Samarium-149 is effectively stable with lower absorption (40.8K barns) but builds slowly through a longer decay chain and represents permanent reactivity loss.
Q: Does this work on Raspberry Pi?
A: It should work but may be slow. The GUI is computationally intensive. Consider using a more powerful computer for smooth operation.
- NEW: External neutron source term S in point kinetics equation for realistic subcritical neutron population
- NEW: Burnup and fuel depletion tracking with real-time display
- NEW: Isotope concentration tracking: U-235, U-238, Pu-239, fission products
- NEW: 8-panel GridSpec GUI layout (Power, Reactivity, Fuel Temp, Coolant Temp, Xe-135, Sm-149, Burnup, Isotopes)
- NEW: Scrollable value panel with organized section headers
- NEW: Burnup reactivity feedback contribution to total reactivity
- NEW: Excess reactivity ($0.05) for realistic subcritical startup
- NEW: Expanded CSV logging with 15 columns including all isotope data
- UPDATED: Control rod total worth increased to $0.2 (from $0.1)
- UPDATED: State vector expanded to 20 dimensions (added N235, N238, N239Pu, NFP, Burnup)
- IMPROVED: Scaled burnup coefficients for demonstration timescales (BURNUP_SCALE = 1e-3)
- NEW: Xenon-135 fission product poisoning with complete I-135 → Xe-135 decay chain
- NEW: Samarium-149 fission product poisoning with Nd-149 → Pm-149 → Sm-149 decay chain
- NEW: Full-screen 4-panel GUI layout with synchronized plots
- NEW: Real-time poison concentration monitoring (Xe-135 and Sm-149)
- NEW: Reactivity plot showing rod, temperature, and poison contributions
- NEW: Enhanced CSV logging with poison concentration columns
- UPDATED: Control rod total worth set to 0.1$ (from ~0.05$)
- UPDATED: State vector expanded to 15 dimensions (added I, Xe, Nd, Pm, Sm)
- UPDATED: Renamed from pyReactor/legoReactor to DUNE/DUNEReactor
- IMPROVED: Documentation with comprehensive fission product theory
- NEW: Dynamic coolant flow control - automatic adjustment based on reactor power
- NEW: Manual coolant control mode with independent flow rate setting
- NEW: CSV data logging system with automatic timestamped file generation
- NEW: Arduino case 'c' command for independent pump speed control
- NEW: Flow control checkbox in GUI for toggling manual mode
- IMPROVED: Coolant flow rate display updates only in automatic mode
- IMPROVED: Enhanced thermal-hydraulic coupling with flow-based control
- Initial public release
- 6-group delayed neutron model
- Temperature-dependent thermal hydraulics
- PID power control
- Arduino/LEGO integration
- wxPython GUI with matplotlib plots
- Automatic SCRAM systems
- Xenon oscillation studies and load-following scenarios
- Enhanced parameter configuration UI
- Pre-configured scenario library (startup, shutdown, load-follow, etc.)
- Multi-zone burnup with radial/axial distribution
- Enhanced documentation and video tutorials
Hridoy Kabiraj
Email: rudrokabiraj@gmail.com
GitHub: @hridoy
Original Developer: William Gurecky
This project is currently unlicensed. All rights reserved by the author.
For usage permissions or licensing inquiries, please contact the author.
For questions, bug reports, or feature requests:
- Open an issue on GitHub
- Email: rudrokabiraj@gmail.com
For educational partnerships or collaboration inquiries, please reach out via email.
Last Updated: February 2026