Chat about this codebase

AI-powered code exploration

Online

Project Overview

The Quantum-Particle-Simulator is a C++/Raylib-based interactive application that visualizes core quantum mechanics principles through animated particles and mini-games. It targets both educational and entertainment use, letting users experiment with abstract phenomena in real time.

Why This Exists

  • Bridge the gap between theory and intuition by animating quantum concepts.
  • Offer hands-on experimentation with superposition, uncertainty, entanglement, wave-particle duality and chaos.
  • Provide bite-sized mini-games that reinforce learning through play.

Main Features

  • Principle Views
    • Switch between five core demonstrations (keys 1–5):
    – Superposition
    – Uncertainty
    – Entanglement
    – Wave-Particle Duality
    – Chaos
  • Real-Time Particle Engine
    • Physics-driven updates and rendering via Raylib
    • Easily extendable particle system and shader support
  • Interactive Controls
    • Keyboard shortcuts for mode switching and parameter tweaks
    • Mouse input for direct particle interaction
  • Settings Menu
    • Tweak simulation parameters (e.g. speed, probabilities) with sliders
    • Live preview of changes
  • Mini-Games
    • Focused challenges (e.g. measure a particle’s position within a time limit)
    • Instant feedback and score tracking
  • HUD Overlay
    • Displays current principle, key bindings and performance stats

Technologies & Setup

  • Language: Modern C++17
  • Graphics/Audio: Raylib (OpenGL backend)
  • Build System: CMake
  • Cross-Platform: Windows, macOS, Linux

Clone the repo and run:

git clone https://github.com/sk-almansoori/Quantum-Particle-Simulator.git
cd Quantum-Particle-Simulator
mkdir build && cd build
cmake ..
cmake --build .
./QuantumParticleSimulator

Repository Layout

  • src/
    • main.cpp
    • Simulation.h/.cpp – Core state, update & draw routines
    • SettingsMenu.cpp – Parameter sliders and UI logic
    • HUD.cpp – On-screen overlay
  • assets/
    • shaders/ – GLSL files for visuals
    • textures/ – Particle sprites
  • CMakeLists.txt – Build configuration

This structure helps you locate and extend simulation modules, UI components and asset pipelines efficiently.

Getting Started

Follow these steps to obtain the Quantum Particle Simulator, install dependencies, build for your platform using the supplied Makefile, and launch the simulation.

Prerequisites

  • A C++17-compatible compiler (g++ or clang++)
  • make
  • Raylib development files
    • Ubuntu/Debian: 
    sudo apt update
sudo apt install build-essential libraylib-dev
    • Raspberry Pi OS: 
    sudo apt install build-essential libraylib-dev
    • macOS (Homebrew): 
    brew install raylib
    • Web (Emscripten): follow https://emscripten.org/docs/getting_started/downloads.html

1. Clone the Repository

git clone https://github.com/sk-almansoori/Quantum-Particle-Simulator.git
cd Quantum-Particle-Simulator

2. Build for Your Platform

The Makefile defaults to PLATFORM_DESKTOP and RELEASE mode. Binaries go to bin/.

Desktop (Linux/macOS)

make
# or explicitly:
make PLATFORM=PLATFORM_DESKTOP BUILD_MODE=RELEASE

Raspberry Pi

make PLATFORM=PLATFORM_RPI BUILD_MODE=RELEASE

Android

Ensure Android NDK is in your PATH, then:

make PLATFORM=PLATFORM_ANDROID BUILD_MODE=RELEASE

Web (HTML5)

With Emscripten activated:

make PLATFORM=PLATFORM_WEB BUILD_MODE=RELEASE

Custom Build Options

Override any Makefile variable on the command line:

# Debug build with address sanitizer
make BUILD_MODE=DEBUG CXXFLAGS="-std=c++17 -g -fsanitize=address"
# Increase default particle count at compile time
make PARTICLE_COUNT=5000

3. Run the Simulator

./bin/quantum_sim

Pass runtime flags:

# Fullscreen with 200 particles
./bin/quantum_sim --fullscreen --particles=200

4. Clean Up

make clean
# Removes bin/ and obj/ directories

Troubleshooting

• “raylib.h: No such file or directory”
– Verify libraylib-dev is installed or add -I/path/to/raylib/include to CXXFLAGS.
• Undefined references to Raylib symbols
– Confirm -lraylib appears in pkg-config --libs raylib or set RAYLIB_INSTALL_PATH/RAYLIB_H_INSTALL_PATH.
• Android build errors
– Check your NDK path and ABI settings in the Makefile’s ANDROID_* variables.

Now you’re ready to explore quantum tunneling, double-slit interference and mini-games via keys 1–5.

User Guide

This guide explains in-game controls, on-screen UI elements, and how to launch mini-games and visualizations once the simulator is running.

1. Running the Simulator

Launch from terminal or double-click the executable:

./QuantumParticleSimulator

The simulation window opens in windowed mode. Press F to toggle fullscreen.

2. Controls

2.1 Simulation Controls

• 1–5 Select quantum principle
1 – SUPERPOSITION
2 – UNCERTAINTY
3 – ENTANGLEMENT
4 – WAVE-PARTICLE DUALITY
5 – CHAOS

• UP/DOWN Increase/Decrease particle count
• SPACE Pause/Resume simulation
• F Toggle fullscreen
• ESC Quit application

2.2 Mini-Game Controls

• D Enter “Quantum Dodge”
• Q Enter “Formula Quiz”

Inside Quantum Dodge
Arrow keys – Move shield
ESC Return to simulation

Inside Formula Quiz
Number keys – Select answer
ENTER Submit answer
ESC Return to simulation

3. On-Screen UI Elements

• Top-left corner
– Current principle name
– Simulation state (Running / Paused)
– Particle count

• Top-right corner
– FPS counter

• Bottom bar (in mini-games)
– Instructions and current score or question

4. Accessing Mini-Games

4.1 Quantum Dodge

Press D during simulation.
The viewport switches to a dodge arena:

// Enter dodge mode
if (IsKeyPressed(KEY_D)) {
    gameState = GAME_QUANTUM_DODGE;
    InitQuantumDodge(particles);
}

// In the main loop
if (gameState == GAME_QUANTUM_DODGE) {
    UpdateQuantumDodge();
    DrawQuantumDodge();
    if (IsKeyPressed(KEY_ESCAPE)) gameState = GAME_SIMULATION;
}

4.2 Formula Quiz

Press Q during simulation.
The screen displays a quantum formula question:

// Enter quiz mode
if (IsKeyPressed(KEY_Q)) {
    gameState = GAME_FORMULA_QUIZ;
    InitFormulaQuiz();
}

if (gameState == GAME_FORMULA_QUIZ) {
    UpdateFormulaQuiz();
    DrawFormulaQuiz();
    if (IsKeyPressed(KEY_ESCAPE)) gameState = GAME_SIMULATION;
}

5. Switching Visualizations

The simulator overlays live visual cues per principle. To toggle additional overlays: • V Cycle particle trajectory trails
• H Toggle probability-density heatmap

Example in input handling:

if (IsKeyPressed(KEY_V)) showTrails = !showTrails;
if (IsKeyPressed(KEY_H)) showHeatmap = !showHeatmap;

Use these controls and UI cues to explore quantum behaviors, engage mini-games, and customize visual feedback in real time.

License

This project is licensed under the MIT License. You may use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, subject to the conditions below.

1. Permissions and Conditions

  • Grant: Free use for commercial or private purposes
  • Condition: Include the full MIT license text and copyright notice in all copies or substantial portions

2. Disclaimer

The Software is provided “as is”, without warranty of any kind. The authors are not liable for any claim, damages, or other liability.

3. Including the License in Distributions

Ensure every distribution (source or binary) contains a copy of LICENSE at the root of the package.

Example: npm package.json

{
  "name": "quantum-particle-simulator",
  "version": "1.0.0",
  "license": "MIT",
  // ...
}

Example: CMakeLists.txt (C++ projects)

project(QuantumParticleSimulator VERSION 1.0 LANGUAGES CXX)
# Embed license file in install
install(FILES ${CMAKE_SOURCE_DIR}/LICENSE DESTINATION share/${PROJECT_NAME})

4. Adding License Headers to Source Files

Include a short header in each source file to improve traceability.

C++ Example (.cpp / .h)

// Quantum-Particle-Simulator
// Copyright (c) 2025 Your Name
// SPDX-License-Identifier: MIT

Python Example (.py)

# Quantum-Particle-Simulator
# Copyright (c) 2025 Your Name
# SPDX-License-Identifier: MIT

5. Attribution for Derivative Works

When modifying or extending this code:

  1. Retain the original MIT license in LICENSE.
  2. Add your own copyright line:
    Copyright (c) 2025 Your Name
  3. Document your changes in CHANGELOG.md or your fork’s README.

6. Third-Party Dependencies

Review each dependency’s license for compatibility. Include their licenses alongside this project’s LICENSE if redistribution requires it.

By following these guidelines, you ensure compliance with the MIT License and maintain clear attribution for all contributors.