Skip to content
BranchesTags

Repository files navigation

Physics Notebook 🔬

An interactive collection of physics concepts with beautiful visualizations and real-time simulations

📖 About

Physics Notebook is an open-source interactive learning platform that brings physics concepts to life through beautiful visualizations and real-time simulations. Each concept features:

  • 🎨 Interactive Canvas Animations - Real-time visualizations built with HTML5 Canvas
  • 🧮 Mathematical Equations - Rendered beautifully using MathJax
  • 🤖 AI Integration - Quick access to AI assistants (Perplexity, Gemini, ChatGPT, Claude, Grok)
  • 🎛️ Adjustable Parameters - Sliders and controls to explore different scenarios
  • 🌓 Dark/Light Mode - Seamless theme switching
  • 📱 Responsive Design - Works beautifully on all devices

✨ Features

Current Concepts

Mechanics

  • 🌀 Harmonic Oscillation
  • 🏹 Projectile Motion
  • 🪐 Orbital Mechanics
  • ⏱️ Simple Pendulum
  • 🔄 Rotational Dynamics
  • 🛠️ Lagrangian & Hamiltonian Mechanics

Waves & Optics

  • 🌊 Wave Interference
  • 🔍 Double Slit Experiment

Electromagnetism

  • ⚡ Electric Fields

Technical Highlights

  • Zero Dependencies - Pure vanilla JavaScript (except MathJax)
  • Performance Optimized - IntersectionObserver for canvas rendering
  • HiDPI/Retina Support - Crystal clear on all displays
  • GSAP Animations - Smooth scroll-triggered animations
  • Modular Architecture - Easy to extend with new concepts

🚀 Getting Started

Prerequisites

You only need a modern web browser! No build process or dependencies required.

Installation

  1. Clone the repository
git clone https://github.com/CasberryIndia/Physics-Notebook.git
cd Physics-Notebook
  1. Start a local server from the repo root
# Using Python's built-in server
python -m http.server 8000

# Or using Node's http-server
npx http-server
  1. Navigate to http://localhost:8000

Serving the site locally is the recommended workflow. Some browser APIs used by the AI-assist buttons are restricted on file:// pages.

That's it! 🎉

📂 Project Structure

Physics-Notebook/
├── index.html              # Main library page
├── STYLE_GUIDE.md          # Shared layout and design rules
├── CONCEPT_PATTERN.md      # Guide for creating new concepts
├── assets/
│   └── fonts/              # Local webfont binaries and licenses
├── Concepts/               # Individual concept pages
│   ├── simple-pendulum.html
│   ├── double-slit-experiment.html
│   ├── orbital-mechanics.html
│   └── ...
├── css/
│   ├── common.css          # Shared styles
│   ├── home.css            # Library page styles
│   └── article.css         # Concept page styles
└── js/
    └── common.js           # Theme toggle & utilities

🤝 Contributing

We love contributions! Whether it's a new physics concept, bug fix, or improvement, your help is welcome.

How to Contribute

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-concept)
  3. Make your changes
  4. Test thoroughly - Open your concept in a browser
  5. Commit your changes (git commit -m 'Add amazing new concept')
  6. Push to the branch (git push origin feature/amazing-concept)
  7. Open a Pull Request

Creating a New Concept

Follow our comprehensive CONCEPT_PATTERN.md guide. Here's the quick version:

1. Create Your Concept File

Create a new HTML file in the Concepts/ directory:

touch Concepts/your-concept-name.html

2. Follow the Standard Structure

Every concept should have:

  • HTML Structure

    • <head> with proper metadata, shared styles, MathJax, GSAP, Lucide icons
    • Navigation bar with back button and theme toggle
    • Hero section with concept title and description
    • 3 sections with split-layout (content + visualization)
    • References section

  • Section Components (repeat for 3 sections)

    • Section label (01, 02, 03)
    • Content column with:
      • Title and description
      • Mathematical equations in <div class="math-block">
      • Concept cards (<div class="etu-card">)
      • AI assistance links (all 5 providers)
      • Interactive controls (<div class="sim-controls">)
    • Visualization column with <canvas> element

  • JavaScript Architecture

    • openAI() function for AI integrations
    • APP object managing initialization
    • BaseVisual class for canvas rendering
    • Specific visual classes extending BaseVisual
    • IntersectionObserver for performance
    • GSAP scroll animations

3. Example: Basic Visual Class

class MyConceptVisual extends BaseVisual {
    constructor(id) {
        super(id);
        this.time = 0;
        this.setupControls();
    }

    setupControls() {
        const slider = document.getElementById('my-slider');
        slider.addEventListener('input', (e) => {
            this.parameter = parseFloat(e.target.value);
        });
    }

    draw() {
        this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
        this.time += 0.03;
        
        // Your visualization logic here
        // Use this.color, this.accent, this.scale, etc.
        // from BaseVisual
    }
}

4. Add to Main Index

Update index.html DATA array:

{
    id: 'your-concept',
    title: 'Your Concept Title',
    domain: 'Mechanics', // or 'Waves', 'Electromagnetism', 'Quantum'
    desc: 'Brief description for the card.',
    type: 'your-type',
    href: 'Concepts/your-concept-name.html'
}

5. Test Your Concept

  • ✅ Works in both light and dark themes
  • ✅ All sliders update visual in real-time
  • ✅ All AI links open correctly
  • ✅ Equations render properly (wait for MathJax)
  • ✅ Responsive on mobile devices
  • ✅ Canvas animations are smooth (60fps)

Refer to STYLE_GUIDE.md when changing shared typography, layout, motion, or page structure.

🤖 Automated Concept Generation

If you are using an AI agent (such as Antigravity, Claude, Copilot, etc.) to contribute, you can automate the process of selecting, researching, generating, and registering a new concept page using our automated workflow tools:

  1. AI Agent Runbook (CREATE_CONCEPT.md): Point your AI assistant to this runbook file (e.g. "Please read CREATE_CONCEPT.md and add the next concept"). The agent will autonomously read the checklist, search the web, generate the HTML page conforming to the style guidelines, update index.html, and run verification scripts.
  2. Workflow Automation Script (scripts/add_concept.py): Run this Python script directly from your terminal: 
    python3 scripts/add_concept.py
    • If GEMINI_API_KEY is set: The script calls the Gemini API (with Google Search Grounding enabled) to autonomously research the next unchecked concept, generate all matching assets, write the files, update the main index layout, run accessibility checks, and check the concept off in the checklist.
    • If GEMINI_API_KEY is not set: The script identifies the next unchecked concept and prints a comprehensive, pre-formatted prompt that you can copy and paste to your AI assistant to execute the workflow.

Contribution Guidelines

  • Code Style: Follow existing patterns for consistency
  • Performance: Use IntersectionObserver for canvas rendering
  • Accessibility: Ensure proper semantic HTML
  • Physics Accuracy: Double-check equations and concepts
  • Documentation: Comment complex visualization logic
  • Testing: Test on Chrome, Firefox, and Safari

📚 Resources

🎨 Design Philosophy

Visual Excellence

We prioritize stunning visuals over minimal viable products. Every concept should:

  • Use the shared typography and restrained accent palette consistently
  • Include smooth, purposeful animations
  • Provide immediate visual feedback
  • Feel polished without decorative excess

Educational Value

Each concept must:

  • Start simple, build complexity
  • Include real-world analogies
  • Provide interactive exploration
  • Link to academic references

Performance First

  • Lazy load canvas rendering (IntersectionObserver)
  • HiDPI scaling for sharp visuals
  • Smooth 60fps animations
  • Minimal dependencies

📊 GitHub Star History

Star History Chart

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Physics concepts inspired by classic textbooks (Halliday, Resnick, Walker)
  • Animations powered by GSAP
  • Icons by Lucide
  • Mathematics rendered by MathJax

💬 Community

🚧 Roadmap

  • More Mechanics concepts (Friction, Collisions)
  • Thermodynamics section
  • Special Relativity visualizations
  • 3D visualizations using Three.js
  • Mobile app (React Native)
  • Offline PWA support
  • Multi-language support

Made with ❤️ by the Physics Notebook Community

⬆ Back to Top

About

An interactive collection of physics concepts with beautiful visualizations and real-time simulations

physics-notebook.casberry.in

Topics

mathematicsphysicsphysics-visualization

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

282 stars

Watchers

1 watching

Forks

57 forks
Report repository

Sponsor this project

Contributors

Languages