CIRCUIT_LAB_QUICKSTART.md

Circuit Lab - Quick Start Guide

Installation & Setup

Prerequisites

• Node.js 18+
• npm or yarn
• Modern browser with WebGL 2.0 support (Chrome, Firefox, Edge)

Step 1: Install Dependencies

Your package.json has been updated with required packages. Install them:

npm install

New packages added:

• three: 3D graphics library
• @react-three/fiber & @react-three/drei: React 3D framework
• framer-motion: Animation library
• recharts: Chart plotting
• d3: Data manipulation
• zustand: State management
• chart.js & react-chartjs-2: Additional charting

Step 2: Run Development Server

npm run dev

Open browser to: http://localhost:3000/circuit-lab

Step 3: First Run

You should see the Circuit Lab interface with:

• 3D visualization of a simple resistor circuit
• Control panel on the right
• Grid in background with ambient lighting

---

Using Circuit Lab

Navigation

Main Interface Sections

┌─────────────────────────────────────────────────────┐
│ Header (Circuits + Graphs buttons)                  │
├──────────────────────┬──────────────────────────────┤
│                      │                              │
│   3D Visualization   │     Control Panel            │
│   (75% width)        │     (25% width)              │
│                      │     - Simulation Controls    │
│   - Components       │     - Component Info        │
│   - Wires            │     - Visualization Options │
│   - Current Flow     │     - Learning Mode         │
│   - Camera Controls  │     - Quick Reference       │
│                      │                              │
└──────────────────────┴──────────────────────────────┘

Basic Workflow

1. Select a Circuit

Button: "Circuits" (top-left)

• Opens circuit gallery modal
• Browse Analog, Digital, or Control Systems
• Click "Open Circuit" to load
• Circuit automatically initializes

2. Start Simulation

Play Button: Green play icon in Control Panel

• Simulation begins running
• Time advances automatically
• Components update in real-time
• Graphs (if open) update live

3. Interact with Components

Click on Component in 3D view:

• Component highlights in green
• Information panel shows:
  • Voltage (V)
  • Current (A)
  • Power (W)
  • Temperature (°C if applicable)

Hover over Component:

• Component highlights in yellow
• Tooltip appears with basic info

4. Adjust Time Scale

Slider: "Time Scale" in Simulation section

• Range: 0.1x (slow-motion) to 5x (fast-forward)
• 1x = real-time
• Useful for observing fast transients or slow processes

5. View Data Graphs

Button: "Graphs" (top-right)

• Right panel shows three real-time graphs
• Voltage vs Time: Shows how voltages change
• Current vs Time: Current through components
• Power vs Time: Energy dissipation

Camera Controls (3D Interaction)

Mouse Actions:

• Left Click + Drag: Rotate view around circuit
• Right Click + Drag: Pan (not available - use middle button)
• Middle Click + Drag: Pan view
• Scroll Wheel: Zoom in/out

Keyboard (if implemented):

• R: Reset camera to default view
• F: Focus on selected component
• Space: Toggle auto-rotation

Control Panel Sections

Simulation

• Play/Pause: Start or pause simulation
• Reset: Clear simulation and reinitialize
• Time Scale: 0.1x to 5x speed adjustment
• Mode: Continuous (default), Step-by-Step, or Analysis

Component Info

(Only visible when component is selected)

• Type: What kind of component
• Voltage: Potential difference (V)
• Current: Charge flow rate (A)
• Power: Energy transfer rate (W)
• Temperature: Thermal state (°C)

Visualization

• Show Current Flow: Toggle glowing particle animations
• Show Voltage: Display voltage color coding on wires
• Show Power: Show power dissipation intensity
• Show Formulas: Display relevant equations
• Show Fields: Visualize electric/magnetic fields

Learning Mode

• Formula Hints: Show equations when hovering
• Explanations: Display component descriptions
• Highlight Active Paths: Show how current flows
• Step-by-Step Mode: Pause after each time interval

Quick Reference

• Common formulas with descriptions
• Helpful for quick lookup while simulating
• Click to see full learning panel

---

Circuit Gallery

Analog Circuits

1. Simple Resistor Circuit Beginner

Learning Goal: Understand Ohm's Law (V = IR)

What you'll learn:

• How voltage drops across resistor
• Relationship between V, I, and R
• Power dissipation formula

Try this:

1. Open this circuit
2. Play simulation
3. Notice voltage on resistor (5V)
4. Calculate current: I = V/R = 5V / 1000Ω = 0.005A
5. Check Control Panel - should show matching values

2. RC Charging Circuit Intermediate

Learning Goal: Exponential transient response (τ = RC)

What you'll learn:

• How capacitors charge through a resistor
• Exponential curve shape: V(t) = V₀(1 - e^(-t/τ))
• Time constant τ = RC = 1kΩ × 1µF = 1ms

Try this:

1. Open this circuit and press Play
2. Watch capacitor voltage rise in graph
3. Notice it curves upward, not linearly
4. After ~5τ (5ms), voltage nearly reaches 5V
5. Open Graphs → see exponential shape

Time constants to observe:

• τ (1ms): Voltage reaches 63.2%
• 2τ (2ms): Voltage reaches ~86%
• 3τ (3ms): Voltage reaches ~95%
• 5τ (5ms): Voltage ~99% (essentially done)

3. RLC Resonance Circuit Advanced

Learning Goal: Learn resonant frequency, quality factor, and oscillations

Properties:

• At resonance: ω₀ = 1/√(LC)
• Quality factor: Q = ω₀L/R
• Higher Q = more ringing oscillations

4. BJT Amplifier Advanced

Learning Goal: Transistor gain and non-linear behavior

What you'll see:

• Base current controls collector current
• Amplification factor β (typically 50-300)
• Saturation when base current is too high

5. Op-Amp Circuits Advanced

Learning Goal: Feedback-controlled amplifiers

Available configurations:

• Inverting Amplifier: Gain = -R_f / R_in
• Non-Inverting Amplifier: Gain = 1 + R_f / R_in
• Integrator: Output increases over time
• Differentiator: Output proportional to rate of change

Digital Circuits

Basic Logic Gates Beginner

Learning Goal: Boolean logic and truth tables

Gates included:

• AND: Output 1 only if all inputs are 1
• OR: Output 1 if any input is 1
• NOT: Output opposite of input
• NAND: AND followed by NOT
• NOR: OR followed by NOT
• XOR: Output 1 if inputs different

Try this:

1. Open this circuit
2. Play simulation
3. Watch clock signals drive the gates
4. Notice outputs change based on logic
5. Verify against truth tables

Half Adder Intermediate

Learning Goal: Binary addition in digital circuits

Outputs:

• Sum: XOR of inputs A and B
• Carry: AND of inputs A and B

Test cases:

• A=0, B=0: Sum=0, Carry=0 (0+0=00)
• A=0, B=1: Sum=1, Carry=0 (0+1=01)
• A=1, B=0: Sum=1, Carry=0 (1+0=01)
• A=1, B=1: Sum=0, Carry=1 (1+1=10)

Counters Advanced

Learning Goal: Sequential circuits with state

Types:

• Ripple Counter: Simpler, but slower
• Synchronous Counter: All flip-flops update together

Observe:

• Binary counting 0→1→2→3→4...
• Frequency division at each stage
• Output follows pattern: 2^n outputs for n stages

Control Systems

Block Diagram Advanced

Learning Goal: Feedback control visualization

Components:

• Reference: Target value (setpoint)
• Summing Junction: Error calculation (Ref - Feedback)
• Controller: Proportional gain (Kp) amplifies error
• Plant: System being controlled
• Feedback: Measurement back to summing junction

Observe:

• Error reduces as system responds
• System oscillates then settles
• Output approaches reference value

---

Tips & Tricks

Optimization

• Slow performance?

  • Close graphs panel (expensive to update)
  • Reduce time scale to lower update frequency
  • Clear browser cache and restart

• Graphs too crowded?

  • Select fewer components
  • Zoom in on time scales of interest
  • Export data and analyze in Excel

Learning Strategies

1. Start Simple: Begin with resistor circuit

   • Verify your voltage/current calculations
   • Understand breadboard-like layout

2. Progress to Dynamics: Try RC charging

   • Observe exponential curves
   • Calculate time constant τ
   • Predict voltage at any time t

3. Dive into Components: Study BJT, MOSFET

   • See non-linear behavior
   • Understand saturation and cutoff
   • Experiment with different biasing

4. Combine Knowledge: Build custom circuits

   • Use learning formulas as reference
   • Predict behavior before simulating
   • Verify against simulated results

Helpful Settings for Learning

Enable these in Control Panel:

• ✓ Show Current Flow (see how current routes)
• ✓ Show Voltage (color-coded wires)
• ✓ Show Formulas (hover components for equations)
• ✓ Show Fields (advanced EM understanding)
• ✓ Highlight Active Paths (trace and logic)

Experiment Workflows

Experiment 1: Understand Ohm's Law

1. Open Simple Resistor circuit
2. Run simulation at 1x speed
3. Note voltage (5V) and calculated current (5mA)
4. Right-click resistor → "Edit" (if available)
5. Change resistance to 500Ω, observe I = 10mA
6. Change to 5000Ω, observe I = 1mA
7. Verify V = IR holds true

Experiment 2: Observe RC Time Constant

1. Open RC Charging circuit
2. Calculate τ = RC = 1ms for this circuit
3. Play simulation
4. At t=0, voltage starts at 0V
5. At t=1ms (1τ), voltage should be ~3.16V (63.2% of 5V)
6. At t=5ms (5τ), voltage should be ~4.97V (essentially 5V)
7. Compare with formula: V(t) = 5(1-e^(-t/0.001))

Experiment 3: Logic Gates Truth Tables

1. Open Basic Logic Gates circuit
2. Run at 0.5x speed (slow enough to see changes)
3. With each clock pulse, note gate outputs
4. Create truth table:

   A	B	AND	OR	XOR
   0	0	0	0	0
   0	1	0	1	1
   1	0	0	1	1
   1	1	1	1	0

---

Common Issues & Solutions

Issue: Circuit Not Updating

Solution:

1. Ensure Play button shows "Pause" (meaning it's running)
2. Check if Time Scale is at 0 - set to 1
3. Click "Reset" to reinitialize
4. Close and reopen Circuit Lab

Issue: Graphs Not Showing

Solution:

1. Let simulation run for at least 1-2 seconds
2. Click "Graphs" button to enable graph panel
3. Check that circuit is actually running (Play button)
4. Ensure at least one component is producing data

Issue: Browser is Freezing

Solution:

1. Close browser tabs with heavy pages
2. Disable "Show Fields" visualization
3. Enable browser hardware acceleration
4. Use Chrome instead of Safari (better WebGL support)
5. Restart browser completely

Issue: Components Not Selectable

Solution:

1. Zoom in camera closer to components
2. Click directly on component center
3. Try different components
4. Reload page if interface becomes unresponsive

---

Keyboard Shortcuts

Currently implemented:

• None (coming in future version)

Planned:

• Space: Pause/play
• R: Reset
• G: Toggle graphs
• L: Toggle learning mode
• W: Toggle wires visibility
• C: Clear simulation

---

Educational Resources

Theory References

• Ohm's Law: V = IR
• Power: P = VI = I²R = V²/R
• Kirchhoff's Voltage Law: ΣV = 0 (in any loop)
• Kirchhoff's Current Law: ΣI_in = ΣI_out (at any node)

Formulas by Component

Check Learning Mode panel (bottom-right when component selected) for:

• Resistors: Voltage drop, power dissipation
• Capacitors: Charging curve, time constant
• Inductors: Current ramp, energy storage
• Diodes: Forward/reverse biasing
• Transistors: Gain, saturation
• Op-Amps: Gain equations, frequency response

Books & Websites

• "Electronics Fundamentals" by Paynter
• "The Art of Electronics" by Horowitz & Hill
• CircuitLab.com - Online circuit simulation
• MIT OpenCourseWare - Electronics courses

---

Next Steps

Explore More

1. Try different circuits in each category
2. Adjust parameters and observe effects
3. Compare simulated results with manual calculations
4. Create your own circuits (coming soon)

Deepen Knowledge

1. Study physics of each component
2. Understand energy transfer and conservation
3. Learn circuit analysis techniques (mesh, nodal)
4. Practice circuit design challenges

Share & Collaborate

1. Save interesting circuits (coming soon)
2. Share circuit designs with classmates
3. Analyze provided homework circuits
4. Participate in design challenges

---

Support

Having issues?

1. Check this guide first
2. Search troubleshooting section above
3. Check browser console for error messages (F12)
4. Restart application
5. Create issue in repository

Want to contribute?

• Report bugs or suggest features
• Help improve documentation
• Add new circuits
• Optimize performance

---

Happy learning! Feel free to experiment and make mistakes - that's how real learning happens!

Last updated: April 2026