A hardware-accelerated finite element analysis (FEA) ray-tracing simulator for modeling flashlight beam profiles.
The simulator performs physics-based optical simulations of flashlight systems, including LED emission, silicone dome refraction, parabolic reflector reflections, gasket shadowing, and beam projection onto a virtual target. It can use NVIDIA CUDA for hardware acceleration or automatically fall back to a CPU ray tracer.
- Physics-based ray tracing
- Finite element LED emitter modeling
- Silicone dome refraction
- Smooth and Orange Peel reflector simulation
- CUDA GPU acceleration
- Automatic CPU fallback
- Wall-shot visualization
- Beam intensity profile plots
- Persistent simulation settings
There are two ways to use the simulator.
Most users should download the latest compiled release from the project's GitHub Releases page.
- Download the latest release ZIP
- Extract
- Run:
flashlight-sim.exe
No installation is required.
If a compatible NVIDIA GPU is available, the simulator automatically enables CUDA acceleration. Otherwise, it automatically uses the CPU ray tracer.
Building from source is only required if you want to:
- Modify the simulator
- Contribute code
- Add new features
- Edit the ray-tracing engine
- Build your own executable
See the Developer Setup section below.
Launch the application.
Select:
- Reflector
- LED Emitter
- Gasket
- Reflector Finish
Click Run FEA Simulation.
Simulation progress is displayed in the progress bar while detailed status messages and final results appear in the log window.
The generated beam image is displayed directly inside the application.
Hardware definitions are stored in:
hardware_library.json
The simulator supports three hardware categories:
- Emitters
- Reflectors
- Gaskets
The hardware library can be edited directly within the application or manually by editing the JSON file.
Changes made in the editor only affect the current simulation unless they are explicitly saved.
Simulation settings are stored in:
simulation_settings.json
Default values are stored in:
default_settings.json
The settings dialog allows every parameter to be modified without editing JSON files manually.
Generates every available output plot instead of only the primary wall-shot image.
Not very useful right now. To be done in future.
Generates the simulated beam projected onto the target wall.
Generates beam intensity cross-sections along:
- Horizontal axis
- Vertical axis
- 45° diagonal
These plots are useful for analyzing hotspot shape, corona, and spill. They will be saved to the output directory when "Explort Plots" is enabled.
Displays a human silhouette on the wall-shot image to provide a sense of beam size and throw.
Exports calculated simulation results to CSV files.
Automatically saves generated plots as image files.
Specifies where exported CSV files and images are saved.
Enables CUDA ray tracing.
If CUDA is unavailable or initialization fails, the simulator automatically falls back to the CPU implementation.
Maximum number of additional reflections permitted after the initial reflector bounce.
Increasing this value improves realism for complex reflector geometries but increases computation time.
Uses the reflector opening diameter exactly as specified in the reflector library.
When disabled, the simulator automatically enlarges the opening if necessary to prevent clipping by the LED package.
Distance between the flashlight and the simulated wall.
Controls the total simulated wall area.
Used to determine the wall grid resolution. Should not need to be changed.
Controls how much of the simulated wall is displayed in output figures.
These settings affect only the rendered wall-shot appearance.
They do not affect the underlying optical calculations.
Automatically selects camera exposure.
Applies an exposure offset in EV.
Virtual camera sensitivity.
Virtual camera aperture.
Virtual camera exposure time.
These settings control simulation accuracy and runtime.
Resolution of the wall illumination grid.
Higher values produce smoother output images but require additional processing.
Default 512 x 512 pixels. Increase to 1024 or 2048 if you increase Emitter Subidivision Elements
The LED die is divided into many finite elements.
Each element acts as an independent light source.
Higher subdivision counts improve accuracy but increase simulation time.
Default 16 by 16. This works on most CPUs.
If you have an nVidia GPU, you can increase this. Should not need to go higher than 128.
Angular spacing between emitted rays in elevation.
Smaller values increase angular sampling density.
Default 0.1.
Can decrease to 0.05 with GPU.
Angular spacing around the LED.
Smaller values produce smoother beam profiles.
Default 0.1.
Can decrease to 0.05 with GPU.
Restrict the angular emission range.
These settings are useful for specialized optical analysis.
Controls the angular integration resolution used during lumen calculations.
These values provide defaults whenever individual hardware entries do not specify them.
They include:
- Smooth reflector reflectivity
- Orange Peel reflector reflectivity
- Reflector opening reflectivity
- Gasket reflectivity
- Orange Peel blur strength
- Spill visibility threshold
- Corona visibility threshold
- Hotspot threshold
- Default gasket dimensions
- Default reflector dimensions
- Default focus offset
Each emitter definition contains electrical and optical parameters describing LED performance.
Forward voltage is estimated using a logarithmic approximation:
Forward Voltage =
Vf Turn-On +
(Vf Scale × ln(Current + 1))
This approximates the nonlinear increase in LED forward voltage as drive current rises.
Electrical power is calculated as:
Power =
Current × Forward Voltage
LED efficiency decreases as current increases due to efficiency droop.
The simulator models this behavior using an exponential decay:
Efficiency =
Base Efficacy × exp(-Droop Factor × Current)
where:
- Base Efficacy is the LED efficiency at low current (lm/W)
- Droop Factor determines how rapidly efficiency decreases with increasing current
Total light output is calculated as:
Lumens =
Electrical Power × Efficiency
This model provides a computationally efficient approximation of real LED performance over a wide operating range.
The simulator uses:
- Numba
- CUDA
- NVIDIA NVVM
When a compatible CUDA environment is available, ray tracing executes on the GPU.
If CUDA cannot be initialized, the simulator automatically switches to the CPU implementation without requiring any configuration changes.
This section is only required if you intend to modify the source code.
- Python 3.11
- Anaconda
- Visual Studio Code (recommended)
CUDA Toolkit 11.8 is optional but recommended for GPU development.
git clone ylinmtl/flashlight-sim.git
cd flashlight-simconda create -n flashlight-sim python=3.11Activate the environment:
conda activate flashlight-simconda install -c conda-forge numpy scipy matplotlib pyqt numba pyinstallerTo enable GPU acceleration:
conda install -c conda-forge cudatoolkit=11.8If required:
conda install -c conda-forge zlib-wapiOpen the project folder.
Select the Conda interpreter:
Ctrl + Shift + P
Python: Select Interpreter
Choose the flashlight Conda environment.
python flashlight-sim.pyor press F5 to start the debugger.
To create a standalone Windows release:
python build.pyThe build script automatically:
- Detects the active Conda environment
- Locates the required CUDA runtime
- Bundles CUDA components
- Packages the application using PyInstaller
- Produces a portable release in:
dist/
flashlight-sim/
The generated folder can be distributed directly to end users.
No Python installation is required on the target machine.
flashlight-sim.py PyQt6 application
fea_engine.py Ray-tracing engine
build.py Release builder
mainwindow.ui User interface
hardware_library.json Hardware database
default_settings.json Default settings
simulation_settings.json User settings
This project is licensed under the GNU General Public License v3.0 (GPL-3.0).
You are free to use, modify, and redistribute this software under the terms of the GNU GPL v3.
See the LICENSE file for the complete license text.
This project makes use of the following open-source libraries:
- PyQt6
- NumPy
- SciPy
- Matplotlib
- Numba
- CUDA Toolkit
- PyInstaller
These libraries provide the scientific computing, visualization, GPU acceleration, and application packaging capabilities used throughout the simulator.