⚛️ MajoranaLab

"The world is made of reality, not appearances."
— Ettore Majorana

MajoranaLab is an ambitious, long-term project to map the entire landscape of physics—from classical kinematics to the counter-intuitive world of Quantum Mechanics—into a unified C++ framework. It is a bridge between rigorous mathematical theory and real-time computation.

It combines three things in one repository:

• A C++ physics library — header-only, built from scratch, no external dependencies
• Interactive 2D simulations — visual demos built with SFML
• A terminal physics manual — navigate topics, formulas and derivations from the command line

The project grows alongside the study of physics — every concept studied becomes code in the library, a page in the handbook, and a visual demo.

---

📦 What's inside

majorana-handbook — Terminal manual

An interactive TUI (terminal user interface) built with FTXUI.
Browse physics topics organized by chapter, read formulas with derivations, and launch demos directly from the topic page.

 MajoranaLab  --  Physics Handbook
──────────────────────────────────────
Chapter I — Kinematics: The Geometry of Motion
  Projectile Motion                    [demo]
  Uniformly Accelerated Motion         [demo]
  Uniform Circular Motion              [demo]
  Uniformly Accelerated Circular Motion[demo]
  Velocity and Acceleration in 2D

Chapter II — Dynamics: Forces and Newton's Laws
  Newton's First Law — Inertia
  Newton's Second Law — F = m·a
  ...
  Work & Kinetic Energy                [demo]
  Simple Harmonic Motion               [demo]

Direct demo integration — from any topic marked [demo], press d to launch the simulation without leaving the handbook.

demos/ — Interactive simulations

Visual simulations where you can tune parameters in real time and observe how the physics changes. Each demo shows live equations alongside the animation.

Demo	Topic	Key feature
ProjectileMotion	Kinematics	Parabolic trajectories, angle/speed control
UAM	Kinematics	Free-fall on multiple gravity presets
UniformCircularMotion	Kinematics	Centripetal force, radius, angular speed
UACM	Kinematics	Angular acceleration, α/ω plot
InclinedPlane	Dynamics	Force vectors W/N/fk, static vs kinetic regime
NewtonsCradle	Dynamics	Elastic collisions, momentum conservation
SpringOscillator	Dynamics	SHM, phase portrait, damping modes
WorkEnergy	Dynamics	W_net = ΔEk theorem, live verification

core/ — C++ physics library

Header-only library implementing classical mechanics from scratch. No graphics, no external dependencies — just C++20 and the standard library.

Kinematics module (core/kinematics/): Particle, Integrator (Euler/Symplectic/RK4), PlaneMotion (URM, UAM, projectile, UCM, UACM).

Dynamics module (core/dynamics/): Force, Newton's laws, Weight, Friction, InclinedPlane, Spring (SHM), RigidBody2D (with work/energy/power).

---

🛠️ Dependencies

Component	Dependency	How
core/	none	C++20 stdlib only
tests/	Google Test	auto-downloaded by CMake
handbook/	FTXUI	auto-downloaded by CMake
demos/	SFML 2.5	apt install

sudo apt install cmake g++ git libsfml-dev

Google Test and FTXUI are fetched automatically on first build.

---

🚀 Build

git clone https://github.com/DevFoxxx/MajoranaLab.git
cd MajoranaLab
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

All binaries end up in build/.

---

▶️ Running

# Handbook
./build/handbook/majorana-handbook

# Open a specific topic directly
./build/handbook/majorana-handbook show projectile_motion
./build/handbook/majorana-handbook show work_energy

# Demos
./build/demos/ProjectileMotion/projectile_demo
./build/demos/WorkEnergy/work_energy_demo
./build/demos/SpringOscillator/spring_oscillator_demo
# ...

Handbook navigation:

• ↑ ↓ — move between topics
• Enter — open topic
• d — launch associated demo
• q / Esc — back / quit

---

🧪 Tests

cd build && ctest --output-on-failure

# Individual suites
./build/tests/test_PlaneMotion
./build/tests/test_Dynamics

---

⚙️ Build options

Option	Default	Description
MAJORANA_BUILD_TESTS	ON	Google Test suite
MAJORANA_BUILD_HANDBOOK	ON	FTXUI terminal handbook
MAJORANA_BUILD_DEMOS	ON	SFML simulations

cmake -B build -DMAJORANA_BUILD_HANDBOOK=OFF   # skip FTXUI download
cmake -B build -DMAJORANA_BUILD_DEMOS=OFF       # skip SFML
cmake -B build -DMAJORANA_BUILD_TESTS=OFF       # skip GTest download

---

🗺️ Roadmap

Phase I — Classical Mechanics (current)

Component	Handbook	Demo	Status
Kinematics	✅	✅	Done
Newton's Laws & Dynamics	✅	✅	Done
Work, Energy & Power	✅	✅	Done
Oscillators (SHM)	✅	✅	Done
Gravitation & Orbits	⏳	⏳	Next

Phase II — Gravity & Thermodynamics

Component	Status
Orbital Mechanics (Kepler, N-Body)	Planned
Thermodynamics & Entropy	Planned
Fluid Dynamics	Planned

Phase III — Electromagnetism & Light

Component	Status
Electrostatics & Magnetostatics	Future
Maxwell's Equations	Future
Optics & Wave Theory	Future

Phase IV — Modern & Quantum Physics

Component	Status
Special Relativity	Concept
Wave-Particle Duality	Concept
Schrödinger Equation	Concept

---

📁 Project structure

MajoranaLab/
├── core/
│   ├── math/           Vec2.hpp
│   ├── kinematics/     Particle.hpp, Integrator.hpp, PlaneMotion.hpp
│   └── dynamics/       Force.hpp, NewtonLaws.hpp, Weight.hpp,
│                       Friction.hpp, InclinedPlane.hpp, Spring.hpp,
│                       RigidBody2D.hpp
├── demos/
│   ├── ProjectileMotion/
│   ├── UAM/
│   ├── UniformCircularMotion/
│   ├── UACM/
│   ├── InclinedPlane/
│   ├── NewtonsCradle/
│   ├── SpringOscillator/
│   └── WorkEnergy/
├── handbook/
│   ├── chapters/       kinematics.hpp, dynamics.hpp
│   ├── Topic.hpp
│   ├── TopicRegistry.hpp
│   └── main.cpp
├── tests/
│   ├── test_PlaneMotion.cpp
│   └── test_Dynamics.cpp
├── CMakeLists.txt
├── BUILDING.md
└── README.md

---

👤 Author

Personal project — inspired by Ettore Majorana (1906–1938?), Italian theoretical physicist.

---

📄 License

MIT License — free for personal, educational and commercial use.