# Equation Visualizer Library - Usage Guide

## Overview

The Equation Visualizer is a **generalized, reusable library** for creating interactive equation demos with automatic slider UI generation. 

Instead of hard-coding each calculator, you simply define equations in JSON and the library generates a beautiful, interactive interface.

## Features

✅ **Automatic UI Generation** - Sliders, labels, units auto-generated from JSON
✅ **Real-time Calculation** - Updates results as you move sliders
✅ **Extensible** - Add new equations by simply adding JSON entries
✅ **100s of Equations** - Easily scales to hundreds of equations
✅ **No Code Changes** - Add equations without touching JavaScript
✅ **Mobile Friendly** - Responsive slider design
✅ **Error Handling** - Shows calculation errors gracefully

## Architecture

```
lib/equations.json (library of all equations)
    ↓
partials/equation-visualizer.html (reusable component)
    ↓
EquationVisualizer class (handles all logic)
    ↓
Auto-generated HTML/CSS (rendered on-demand)
    ↓
Real-time JavaScript calculations
```

## Integration on Your Site

The `equation-visualizer.html` component has been included directly into `partials/sidebar.php`. This means it will appear on all pages of your site as part of the sidebar.

**Old WASM calculators (`partials/wasm.html`) have been removed as they are now replaced by this generalized solution.**

### Step 1: Define Equations in JSON

Edit `lib/equations.json` to add new equations. Each equation has:

```json
{
  "id": "unique_id",
  "name": "Display Name",
  "description": "Short description",
  "formula": "Mathematical formula for display",
  "variables": [
    {
      "id": "variable_name",
      "name": "Display Name",
      "symbol": "Symbol",
      "description": "What this variable does",
      "min": 0,
      "max": 100,
      "step": 1,
      "default": 50,
      "unit": "unit_name"
    }
  ],
  "outputs": [
    {
      "id": "output_name",
      "name": "Display Name",
      "formula": "JavaScript expression using variable ids",
      "unit": "result_unit",
      "description": "What the output means"
    }
  ]
}
```

## Example: Adding a New Equation

### Suppose you want to add: E = mc²

```json
{
  "id": "einsteins_mass_energy",
  "name": "Einstein's Mass-Energy Equivalence",
  "description": "The relationship between mass and energy",
  "formula": "E = mc²",
  "variables": [
    {
      "id": "mass",
      "name": "Mass",
      "symbol": "m",
      "description": "Object mass",
      "min": 0.1,
      "max": 1000,
      "step": 0.1,
      "default": 1,
      "unit": "kg"
    },
    {
      "id": "speed_of_light",
      "name": "Speed of Light",
      "symbol": "c",
      "description": "Speed of light constant",
      "min": 1,
      "max": 300000000,
      "step": 1000000,
      "default": 299792458,
      "unit": "m/s"
    }
  ],
  "outputs": [
    {
      "id": "energy",
      "name": "Energy",
      "formula": "mass * speed_of_light * speed_of_light",
      "unit": "Joules",
      "description": "Equivalent energy in Joules"
    }
  ]
}
```

**That's it!** The visualizer automatically:
- Creates two sliders (mass and speed_of_light)
- Shows current values with units
- Calculates and displays energy in real-time
- Formats numbers nicely

## Currently Included Equations

1. **Kelly Criterion** - Optimal bet sizing
2. **Ohm's Law** - V = I × R
3. **Quadratic Formula** - Solves ax² + bx + c = 0
4. **Compound Interest** - Investment growth
5. **Black-Scholes** - Option pricing
6. **Projectile Motion** - Range of projectile

## How It Works - Under the Hood

### 1. Load Equations
```javascript
fetch('/lib/equations.json') → JSON data
```

### 2. Populate Dropdown
```
Kelly Criterion - Optimal bet sizing
Ohm's Law - V = I × R
Quadratic Formula - Solves ax² + bx + c = 0
...
```

### 3. Generate Form
When user selects an equation, JavaScript dynamically creates:
```html
<input type="range"> for each variable
<div> to display current values
<div> for results
```

### 4. Real-Time Calculation
```javascript
// On slider change:
values = getInputValues()
result = eval(output.formula) using values
display result with formatting
```

## Formulas: How to Write Them

The `formula` field in outputs can use:

### Simple Arithmetic
```json
"formula": "a + b"
"formula": "a * b * c"
"formula": "a / b"
```

### Math Functions
```json
"formula": "Math.sqrt(discriminant)"
"formula": "Math.sin(angle * Math.PI / 180)"
"formula": "Math.pow(base, exponent)"
"formula": "Math.exp(-x)"
"formula": "Math.log(value)"
```

### Variable References
```json
"formula": "principal * Math.pow(1 + rate/(100*compounds), compounds * years)"
```

**The formula uses variable IDs directly!**

## Advanced: Calculated Variables

Sometimes you need a variable that's computed from others:

```json
{
  "id": "loss_probability",
  "name": "Loss Probability",
  "calculated": true,
  "calculatedFrom": "100 - p"
}
```

This creates a hidden variable that's automatically updated.

## Styling & Customization

The component uses inline styles (easy to override). Key elements:

- `#equation-library` - Main container
- `#equation-selector` - Dropdown
- `#equation-form-container` - Form area
- `#equation-results` - Results display

Add CSS to customize colors, spacing, fonts, etc.

## Integration with Your Site

### As Sidebar Widget (DONE!)
The `partials/equation-visualizer.html` file has been integrated into `partials/sidebar.php`. This means it will automatically appear in your site's sidebar.

### On Dedicated Page
If you wanted to create a page just for calculators:
Create `content/calculators/index.md` with some intro text and include the component directly:
```markdown
# Interactive Calculators

Welcome to my interactive equation visualizer!

<!-- You can include the component directly if you want it outside the sidebar -->
<?php include '../../partials/equation-visualizer.html'; ?> 
```
_Note: The `../../` is important for relative path from `content/calculators/`_

### Multiple Instances
Create multiple divs with different container IDs and initialize them:
```html
<div id="calc1"></div>
<div id="calc2"></div>

<script>
// Make sure to include the script for EquationVisualizer once on the page
// <script src="/partials/equation-visualizer.html"></script> will do it if you extract the JS
// Or just duplicate the script block in your HTML if you need multiple instances.

// Then initialize each instance:
new EquationVisualizer('calc1', '/lib/equations.json');
new EquationVisualizer('calc2', '/lib/equations.json');
</script>
```

## Adding 100+ Equations

To scale to 100+ equations:

1. **Keep JSON organized** - Group by category
2. **Use descriptive IDs** - `physics_ohms_law`, `finance_kelly_criterion`
3. **Add search/filter** - Add a search box to filter equations by name/category
4. **Lazy load** - Load equation data only when selector is opened
5. **Categories** - Group equations by physics, finance, math, engineering

Example enhanced selector:
```javascript
// Add categories to JSON
const categories = {
  "physics": [...],
  "finance": [...],
  "mathematics": [...]
};

// Populate selector by category
```

## Testing New Equations

When adding a new equation:

1. **Test the formula** - In browser console
2. **Check variable ranges** - Can min/max be reached?
3. **Verify units** - Do they make sense?
4. **Test edge cases** - Division by zero, negative numbers, etc.
5. **Mobile test** - Do sliders work on phone?

## Performance Notes

- **JSON file size** - 100 equations ≈ 100KB (very small)
- **Load time** - Instant (loaded once on page load)
- **Calculation speed** - Real-time (millisecond-level)
- **Memory** - Minimal (one form in DOM at a time)

## Future Enhancements

Possible additions:

- 📊 **Charts** - Plot equation outputs (e.g., Kelly Criterion vs Probability)
- 💾 **Save/Share** - Save equation states as URL
- 📱 **Mobile optimized** - Better sliders for touch
- 🔍 **Search** - Find equations by name/keywords
- 📚 **Learning mode** - Show derivations and explanations
- 🧮 **Multi-output** - Equations with multiple related results
- 🔗 **Dependencies** - Equations that reference other equations

## Example: Education Use Case

A physics student studying projectile motion could:
1. Open your site
2. Click "Projectile Motion" in equation visualizer
3. Move Launch Angle slider
4. See how range changes in real-time
5. Learn the relationship between variables
6. Experiment and explore interactively

This is powerful for STEM education!

## Summary

**One-file solution** for hundreds of interactive equation demos:
- ✅ Minimal JavaScript
- ✅ Easy to add equations (just JSON)
- ✅ Automatic UI generation
- ✅ Real-time calculations
- ✅ Scalable architecture
- ✅ Self-documenting

Perfect for your "learning visualization tool for science and engineering students"! 🎓