Initial commit: Add user documentation

2 months ago · e91bb324dc
1 changed files with 721 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,721 @@
 # pyTesla - User Documentation
 ## Table of Contents
 - [Overview](#overview)
 - [Installation](#installation)
 - [Getting Started](#getting-started)
 - [Configuration](#configuration)
 - [User Interface](#user-interface)
 - [Parameter Reference](#parameter-reference)
 - [Simulation Types](#simulation-types)
 - [Viewing Results](#viewing-results)
 - [Profile Management](#profile-management)
 - [Troubleshooting](#troubleshooting)
 - [Advanced Features](#advanced-features)
 ---
 ## Overview
 pyTesla integrates FEMM (Finite Element Method Magnetics) and LTspice to provide electromagnetic and circuit analysis for Tesla coil design. The application features a PyQt5-based GUI with real-time visualization capabilities.
 ### Key Features
 - Electromagnetic field analysis using FEMM
 - Circuit simulation with LTspice
 - Interactive Tesla coil visualization
 - Guided simulation workflow
 - Profile management for saving designs
 ---
 ## Installation
 ### System Requirements
 - Windows operating system
 - FEMM 4.2 or higher
 - LTspice XVII or higher
 - 4GB RAM minimum (8GB+ recommended)
 - 1GB free disk space
 ### Installation Steps
 1. **Install Prerequisites**
   - Install FEMM from http://www.femm.info
   - Install LTspice from https://www.analog.com/ltspice
   - LTspice will be automatically detected on first run
   - Manual configuration available via **Config → Settings** if needed
 2. **Install pyTesla**
   - **Option 1**: Download and run `pyTesla.exe` (recommended)
   - **Option 2**: For development, clone repository and run `win-install.bat`
 3. **Verify Installation**
   - Launch pyTesla
   - pyTesla will automatically detect LTspice installation
   - Confirm FEMM and LTspice integration by running a simple simulation
 ---
 ## Getting Started
 ### Your First Simulation
 1. **Launch pyTesla** - The default profile will load automatically
 2. **Adjust Parameters**
   - Enter secondary coil dimensions
   - Configure topload parameters
   - Set primary coil parameters
   - Set circuit parameters as needed
 3. **Run Basic Simulation**
   - Click the "Lumped" button for a quick simulation
   - Review preliminary results
 4. **Run Full Analysis**
   - Click "Distributed" for detailed electromagnetic analysis
   - Click "LTspice Only" for circuit analysis
 5. **View Results**
   - Check the bottom panel for calculated values
   - View field plots in the right panel gallery
   - Use the plotter for frequency response analysis
 ---
 ## Configuration
 ### Settings Dialog
 Access application settings via **Config → Settings** in the menu bar.
 #### LTspice Configuration
 pyTesla automatically detects LTspice on startup using multiple strategies:
 - Searches AppData\Local\Programs\ADI (LTspice 24+)
 - Searches Program Files\ADI and Program Files\LTC (older versions)
 - Supports LTspice XVII, LTspice IV, and newer versions
 **Manual Configuration:**
 1. Open **Config → Settings**
 2. Use **Find LTspice** to auto-detect all installations
 3. Use **Browse** to manually select LTspice executable
 4. Use **Clear** to reset and use automatic detection
 **Supported LTspice Versions:**
 - LTspice 24+ (newest ADI releases)
 - LTspice XVII (widely used version)
 - LTspice IV (legacy version)
 #### Theme Selection
 Choose between Dark and Light themes:
 1. Open **Config → Settings**
 2. Select theme from **Appearance** section
 3. Click **OK** to apply
 **Available Themes:**
 - **Dark Theme**: Optimized for extended use in low-light environments
 - **Light Theme**: Better visibility in bright environments
 ### Automatic Detection
 pyTesla automatically detects:
 - **LTspice**: Multiple installation locations and versions
 - **FEMM**: Standard installation paths
 - **Display Units**: Restores your preferred units from previous session
 ---
 ## User Interface
 ### Main Window Layout
 The interface is divided into four main areas:
 1. **Left Panel**: Interactive Tesla coil visualization
 2. **Center Panel**: Parameter input groups in a scrollable layout
 3. **Right Panel**: Image gallery for simulation results
 4. **Bottom Panel**: Simulation controls, model selection, and results display
 ### Model Selection
 The application supports two electromagnetic modeling approaches:
 - **Lumped Model**: Treats components as single elements - faster but less detailed
 - **Distributed Model**: Divides secondary into sections - more accurate for advanced analysis
 **Using Model Selection:**
 - Radio buttons in the bottom panel allow switching between Lumped and Distributed models
 - Buttons are only enabled when corresponding FEMM results are available
 - Results display automatically updates to show selected model's data
 - Model selection affects both displayed results and LTspice simulations
 ### Parameter Groups
 1. **Secondary Coil**: Dimensions and wire specifications
 2. **Topload**: Size, shape and position
 3. **Primary Coil**: Type and dimensions
 4. **Ferrite Core**: Optional core parameters
 5. **Ground Plane**: Ground plane specifications
 6. **Strike Rings**: Protective ring configuration
 7. **SPICE Inputs**: Circuit simulation parameters
 8. **FEMM Inputs**: Field simulation controls and units
 ### Simulation Controls
 - **Lumped**: Fast, lumped-parameter analysis
 - **Distributed**: Full electromagnetic analysis
 - **LTspice Only**: Circuit simulation using existing FEMM results
 - **Voltage Stress**: Analysis for insulation design
 - **Parasitic Modes**: Higher-order resonance analysis
 - **Plotter**: Interactive frequency response tool
 ### Button Color System
 - **Blue**: Ready to run (prerequisites satisfied)
 - **Yellow**: Parameters changed, needs re-simulation
 - **Red**: Simulation in progress
 - **Green**: Simulation completed successfully
 ---
 ## Parameter Reference
 ### Secondary Coil Parameters
 - **Outer Diameter**: External diameter of the wound coil
 - **Height**: Vertical height of the winding
 - **Base Height**: Distance from ground plane to coil bottom
 - **Wire Gauge (AWG)**: Wire diameter selection
 - **Wire Insulation**: Additional insulation thickness
 ### Topload Parameters
 - **Major Radius**: Distance from coil center to torus center
 - **Minor Radius**: Torus tube radius
 - **Number of Rings**: Multiple ring configuration
 - **Topload Height**: Position above secondary
 ### Primary Coil Parameters
 - **Primary Type**: Toroidal, Flat Spiral, or Helical
 - Dimensions specific to selected type
 - Positioning relative to secondary
 ### FEMM Parameters
 - **Units**: Length unit selection
 - **Frequency**: Operating frequency for analysis
 - **Secondary Sections**: Division count for accuracy vs. speed
 - **Mesh Sizes**: Controls simulation accuracy and speed
 ---
 ## Simulation Types
 ### Lumped Simulation
 - Quick electromagnetic analysis using lumped-parameter model
 - Treats secondary as single inductor (no sectioning)
 - Provides preliminary inductance, capacitance, and coupling estimates
 - Faster than Distributed simulation, useful for rapid design iteration
 - **Note**: Distributed simulation automatically runs lumped first to obtain accurate frequency estimate
 ### Distributed Simulation
 - Comprehensive electromagnetic field analysis using FEMM
 - Includes both magnetic and electric field simulations
 - Multi-section model for accurate distributed parameter effects
 - Required before running LTspice circuit simulations
 **Workflow:**
 1. **Lumped Pre-Simulation**: Automatically runs lumped simulation first to obtain accurate frequency estimate
 2. **Distributed FEMM**: Runs magnetic and electrostatic field simulations at the estimated frequency
 3. **LTspice Analysis**: Circuit simulation using distributed transmission line model
 **Iteration Mode:**
 - When the Distributed button is already green (previous successful run), clicking it again enters iteration mode
 - Iteration mode skips lumped and electrostatic simulations, only re-running magnetic + LTspice
 - Preserves electrostatic capacitance matrix from previous run for faster convergence refinement
 - Useful for manual frequency convergence without resetting all calculations
 - Reuses FEMM geometry for optimized performance
 ### LTspice Circuit Simulation
 - AC circuit analysis using FEMM-derived parameters
 - Uses the currently selected model (Lumped or Distributed):
  - **Lumped Model**: Simpler circuit with single L and C elements
  - **Distributed Model**: Multi-section transmission line model for accuracy
 - Calculates resonant frequencies and impedances
 - Provides voltage distribution and phase information
 - Model selection affects spark gap simulations and parasitic mode analysis
 ### Voltage Stress Analysis
 **Manual Tool**: Click the **Voltage Stress** button to analyze electric field stress at real operating conditions for insulation design and breakdown prevention.
 **How It Works:**
 1. **Calculate Operating Voltage**: Uses desired primary current (from SPICE Inputs) to calculate required bus voltage via LTspice
 2. **Generate Voltage Profile**: Simulates distributed model at calculated bus voltage and selected pole frequency
 3. **Extract Voltage Distribution**: Gets voltage at each secondary section from LTspice (e.g., 4.8kV → 133kV gradient)
 4. **FEMM Field Analysis**: Applies voltage profile to FEMM electric field model and solves for E field
 5. **Stress Visualization**: Displays electric field magnitude (V/m) scaled to 3 MV/m (air breakdown threshold)
 **Key Features:**
 - Uses **real operating voltages** based on primary current, not arbitrary 1V reference
 - Includes effects of **spark loading** and **parasitic modes** on voltage distribution
 - Shows **E field magnitude** in V/m, not absolute voltage
 - Red areas indicate high stress approaching **3 MV/m breakdown field**
 - Helps identify insulation weak points and optimize strike ring placement
 **Requirements:**
 - Distributed FEMM simulation must be completed first
 - Pole frequency must be selected
 - Primary current value in SPICE Inputs
 **Practical Use:**
 - Design strike ring placement to protect high-stress regions
 - Verify insulation safety margins at operating conditions
 - Understand how spark loading shifts stress patterns via parasitic modes
 **Note**: This analysis runs only when manually requested via the Voltage Stress button, not automatically during distributed simulation.
 ### Parasitic Modes Analysis
 - Identifies higher-order resonances beyond primary/secondary poles
 - Shows mode shapes and frequencies for each resonance
 - Efficient implementation: draws FEMM geometry once, updates voltages for each mode
 - Useful for optimizing coil geometry and understanding multi-mode behavior
 - Requires Distributed simulation and LTspice results
 ---
 ## Viewing Results
 ### Results Panel
 The bottom panel displays key simulation results based on the selected model:
 **Model Selection Controls:**
 - Radio buttons to switch between Lumped and Distributed models
 - Only enabled when corresponding FEMM results are available
 - Results automatically update when switching models
 **Displayed Results (vary by selected model):**
 - **Inductance Values**: Primary, secondary, and mutual inductance
 - **Capacitance**: Topload and distributed capacitance
 - **Coupling**: Coupling coefficient (k-factor)
 - **Resonant Frequencies**: Primary and secondary resonances
 - **Wire Data**: Length, turns, and resistance
 - **Model Label**: Shows "LUMPED MODEL" or "DISTRIBUTED MODEL" for clarity
 ### Image Gallery
 The right panel contains simulation visualizations:
 - **Magnetic Field Plots**: Field lines and flux density
 - **Electric Field Plots**: Equipotential lines and field intensity
 - **Frequency Response Plots**: Frequency response charts
 - **Mode Shapes**: Parasitic mode visualizations
 ### Interactive Plotter
 The plotter provides advanced frequency response analysis with a comprehensive preset system for repeatable test scenarios.
 #### Opening the Plotter
 Click the **Plotter** button in the simulation controls after running FEMM simulations. The plotter window is independent and can be resized or moved to a second monitor.
 **Important**: The plotter does not automatically run simulations on startup. You must manually click **Compose & Analyze** to run your first simulation. This prevents startup hangs from problematic simulation parameters and gives you control over when simulations execute.
 #### Circuit Configuration
 Configure the circuit being analyzed:
 - **Input Voltage**: Choose between 1V reference or calculated input voltage
 - **MMC Capacitors**: Set primary and secondary MMC values (µF and pF)
 - **Resonator Model**: Select between models:
  - **Lumped**: Single-element model (formerly called Simple)
  - **Distributed**: Multi-section model (formerly called Complex)
  - Automatically uses the main window's selected model when syncing
 - **Spark Load**: Choose from saved sparks, current GUI values, parametric R load, or none
 - **Sync with Main**: Pull current values and model selection from the main window
 #### Analysis Presets
 Reusable SPICE directives for different analysis types:
 **Built-in Presets:**
 - **Standard sweep**: Linear frequency sweep (1kHz-500kHz, 1000 points) for AC analysis
 - **Trans**: Transient analysis with sinusoidal excitation for ringdown waveforms
 - **fft**: Pulse excitation with parametric frequency for FFT spectrum analysis
 **Managing Presets:**
 1. Edit the **SPICE Directives** text area (supports multi-line)
 2. Click **Add to Presets** to save
 3. Click **Update Preset** to modify existing
 4. Click **Delete Preset** to remove
 **Supported Directives:**
 - `.ac lin/dec/oct <points> <start> <end>` - AC frequency sweep
 - `.tran <tstop> <tstart> <tstep>` - Transient analysis
 - `.step param <name> <start> <end> <step>` - Parametric sweep
 - `.meas AC <name> <measurement>` - AC measurements
 - Voltage/current sources (V1, I1, etc.) for transient excitation
 - Multiple directives per preset (newline-separated)
 #### Transient Analysis Modes
 The plotter supports both frequency-domain (AC) and time-domain (transient) analysis:
 **Time Domain Analysis:**
 - Uses `.tran` directives to simulate waveforms over time
 - Supports various excitation types: SINE, PULSE, PWL (piecewise linear), user-defined
 - Useful for analyzing ringdown behavior, spark breakout, and transient response
 - Example: `V1 vin 0 SINE(0 250 386k)\n.tran 0 1000us 0 100n`
 **FFT (Frequency Spectrum) Analysis:**
 - Applies Python-based FFT (Fast Fourier Transform) to transient simulation results
 - Shows complete frequency spectrum, not just harmonics
 - Uses Hanning window to reduce spectral leakage
 - Ideal for analyzing harmonic content, resonant peaks, and frequency distribution
 - Example: Use PULSE excitation with parametric frequency for broadband analysis
 **Selecting Analysis Mode:**
 - **AC Analysis**: Select "ac" in analysis_mode, use `.ac` directives
 - **Transient (Time Domain)**: Select "transient" in analysis_mode with "time_domain" display mode
 - **Transient (FFT)**: Select "transient" in analysis_mode with "fft" display mode
 - Plot configurations automatically set the correct modes
 #### Measurements
 Add voltage, current, or calculated measurements to plot:
 **Quick Add:**
 - Select signal from **Available Signals** dropdown
 - Click **→ Add** to insert into custom measurement field
 **Custom Formulas:**
 - Simple traces: `V(top)`, `I(L1)`, `V(n001)`
 - Multiplication: `V(top)*I(R_load)` (power)
 - Division: `V(n001)/I(L1)` (impedance)
 - Numeric constants: `V(top)*1000`, `I(L1)/0.001`
 **Managing Measurements:**
 - **Add Measurement**: Add custom formula to plot
 - **Remove Selected**: Delete selected measurement
 - **Clear All**: Remove all measurements at once
 #### Measurement Presets
 Predefined sets of measurements for common analysis tasks:
 **Built-in Presets:**
 - **Power Analysis**: Topload voltage, load current, and power
 - **Voltage Distribution**: Voltage at coil sections (s0, s5, top)
 - **Input Analysis**: Primary voltage, current, and impedance
 **Managing Measurement Presets:**
 1. Add desired measurements to the list
 2. Click **Save as Preset**
 3. Select preset from dropdown to instantly load all measurements
 #### Plot Configurations
 Complete analysis workflows that combine circuit setup, analysis directives, and measurements:
 **Built-in Configurations:**
 *Spice Analysis Configurations:*
 - **Power Sweep (Rval)**: Parametric load resistance sweep to find optimal power transfer
 - **Frequency Response**: Standard frequency sweep (100kHz-1500kHz) with input current measurement
 - **Voltage Distribution**: Voltage at all 10 coil sections across extended frequency range (100kHz-3500kHz)
 *Transient Analysis Configurations:*
 - **Transient - Time Domain**: Ringdown analysis with sinusoidal excitation and realistic spark load (24" spark)
 - **Transient - FFT Example**: Pulse excitation for harmonic analysis with parametric frequency (36" spark)
 **Using Plot Configurations:**
 1. Select configuration from **Saved Configuration** dropdown
 2. Plot automatically updates with the complete preset scenario
 3. All circuit settings, directives, measurements, and display modes are applied
 **Creating Configurations:**
 1. Configure circuit settings (voltage, MMC, resonator model, spark load)
 2. Set analysis directive (`.ac` for AC, `.tran` for transient)
 3. Add measurements to plot
 4. Set analysis_mode ("ac" or "transient") and display_mode ("time_domain" or "fft")
 5. Click **Save Current Setup** to save as reusable configuration
 **Benefits:**
 - **Repeatability**: Exact same test every time
 - **Documentation**: Named scenarios for reports
 - **Comparison**: Quickly switch between AC and transient analysis types
 - **Realistic Defaults**: Transient configurations include appropriate spark loads and excitation
 #### Enhanced Hover System
 Interactive data inspection with comprehensive value display:
 **Features:**
 - **Crosshairs**: Vertical and horizontal reference lines on both magnitude and phase plots
 - **Multi-Line Display**: Shows values from ALL plotted measurements at once
 - **Frequency/Parameter Detection**: Automatically detects sweep type (frequency vs. parametric)
 - **Phase Integration**: Displays both magnitude and phase values in single tooltip
 - **Smart Positioning**: Tooltip avoids plot edges for visibility
 **Using Hover:**
 - Move mouse over plot area to see values at that X-axis position
 - Tooltip shows frequency/parameter value and all measurement values
 - Values snap to actual data points for accuracy
 #### Plot Controls
 Customize plot appearance:
 - **Show Phase**: Toggle phase plot visibility
 - **Logarithmic Frequency**: Log scale for frequency axis (auto-set for DEC/OCT sweeps)
 - **Logarithmic Magnitude**: Log scale for magnitude axis
 - **Use dB for Magnitude**: Convert magnitude values to decibels
 #### Workflow Examples
 **Example 1: Resonant Frequency Analysis (AC)**
 1. Load **Frequency Response** plot configuration
 2. Click **Compose & Analyze**
 3. Hover over peak to find exact resonant frequency
 4. Export plot using toolbar save button
 **Example 2: Load Power Optimization (Parametric)**
 1. Load **Power Sweep (Rval)** configuration
 2. Ensures parametric R load is selected
 3. Plots power (V×I) vs. resistance
 4. Find peak for optimal load matching
 **Example 3: Ringdown Analysis (Transient - Time Domain)**
 1. Load **Transient - Time Domain** plot configuration
 2. Verify circuit parameters and spark load selection
 3. Click **Compose & Analyze** to run transient simulation
 4. View time-domain waveform showing exponential decay and oscillation
 5. Analyze ringdown time and damping behavior
 **Example 4: Harmonic Analysis (Transient - FFT)**
 1. Load **Transient - FFT Example** plot configuration
 2. Check parametric frequency matches your operating frequency
 3. Click **Compose & Analyze** to run transient simulation
 4. FFT automatically computed and displayed as frequency spectrum
 5. Identify resonant peaks and harmonic content
 6. Hover over peaks to read exact frequencies and amplitudes
 **Example 5: Custom Analysis**
 1. Set circuit parameters (voltage, MMC values, spark load)
 2. Create custom directive:
   - AC: `.ac lin 1000 200k 400k`
   - Transient: `V1 vin 0 SINE(0 250 386k)\n.tran 0 500us 0 50n`
 3. Add measurements: `V(top)`, `V(n001)/I(L1)`, `V(top)*I(R_load)`
 4. Set analysis_mode and display_mode as appropriate
 5. Save as plot configuration for reuse
 #### Tips for Effective Use
 - **Sync Before First Plot**: Click **Sync with Main** to pull current circuit values and model selection
 - **Manual Workflow**: Plotter does not auto-run - verify parameters before clicking "Compose & Analyze"
 - **Use Presets for Repeatability**: Save commonly-used configurations as plot presets
 - **AC vs Transient**: Use AC analysis for frequency response, transient for time-domain behavior
 - **FFT for Spectrum**: Use transient simulation with FFT display mode to see complete frequency content
 - **Parametric Sweeps**: Use `.step param` for sweeping component values (R, L, C, frequency)
 - **Multi-Line Formulas**: Hover shows ALL measurements - no need to hover individual lines
 - **Save Plots**: Use toolbar save button - defaults to profile's images directory
 - **Realistic Spark Loads**: Transient configurations use appropriate spark models for accurate results
 ---
 ## Profile Management
 ### Saving Profiles
 - **File → Save Coil Profile**: Save current design
 - All parameters, results, and images are saved
 - Profiles are stored in the `profiles/` directory
 ### Loading Profiles
 - **File → Load Coil Profile**: Load saved design
 - Previous simulation results are restored
 - Button states reflect the profile's simulation status
 ### Profile Structure
 ```
 profiles/
 ├── [profile_name]/
 │   ├── [profile_name].json    # Configuration file
 │   ├── [profile_name].log     # Session log
 │   ├── images/                # Simulation plots
 │   ├── femm/                  # FEMM files (.fem, .fee)
 │   └── ltspice/               # LTspice netlists and results
 │       └── sparks/            # Saved spark configurations
 ```
 ---
 ## Troubleshooting
 ### Common Installation Issues
 - **FEMM Not Found**: Ensure FEMM is installed and in system PATH
 - **LTspice Not Detected**:
  - Go to **Config → Settings**
  - Click **Find LTspice** to auto-detect installations
  - If not found, use **Browse** to manually select LTspice.exe
  - Check common locations:
    - `C:\Users\[YourName]\AppData\Local\Programs\ADI\LTspice\`
    - `C:\Program Files\ADI\LTspice\`
    - `C:\Program Files\LTC\LTspiceXVII\`
 - **Startup Error**: Check file permissions and ensure profiles directory is writable
 ### Simulation Problems
 - **FEMM Convergence Error**: Adjust mesh size or geometry
 - **LTspice Errors**: Check for invalid parameter values
 - **Memory Issues**: Reduce section count or mesh density
 ### Results Issues
 - **Missing Results**: Verify simulation completed successfully
 - **Image Display Problems**: Check profile directory permissions
 - **Unexpected Values**: Confirm parameters are in valid ranges
 ---
 ## Advanced Features
 ### Spark Modeling
 - Dual-capacitance spark model (C_mutual and C_shunt)
 - Phase optimization for streamer analysis
 - "Calculate Spark Values" tool with frequency convergence algorithm:
  - Iteratively optimizes spark resistance for actual operating frequency
  - Maximum 5 iterations with 1000 Hz tolerance
  - FEMM calculates capacitance matrix with spark geometry
  - LTspice determines actual pole frequency with spark load
  - Convergence guarantees R matches resonant frequency
 - Auto-save calculated sparks to library with generated names
 - Load/save spark configurations for repeatable testing
 ### Matrix-Based Analysis
 - Multi-section secondary modeling
 - Accurate capacitance matrix calculations
 - Captures distributed parameter effects
 ### Unit System
 - Change display units via FEMM Inputs panel
 - All measurements automatically convert
 - Supported units: inches, mm, cm, m, mils, ft
 ### Themes
 pyTesla includes professional themes designed for optimal readability:
 - **Dark Theme**: Default theme optimized for extended use in low-light environments
 - **Light Theme**: High-contrast theme for bright environments
 **Changing Themes:**
 1. Go to **Config → Settings**
 2. Select desired theme in the **Appearance** section
 3. Click **OK** to apply immediately
 Theme preference is saved automatically and restored on next launch.
 ### Controller Library
 pyTesla includes a controller template system for DRSSTC and interrupter simulations:
 **Library Location:**
 - `library/controllers/` directory (next to executable)
 - Auto-created on first run if missing
 - Located at project root in development mode
 **Template Format:**
 - SPICE netlist files with `.net` extension
 - First comment line becomes dropdown description in Circuit Analyzer
 - Complete netlists with parameter documentation in comments
 - Users can add custom templates by placing `.net` files in directory
 **Using Templates:**
 1. Open the Plotter (Circuit Analyzer)
 2. Select template from controller dropdown
 3. Click insert button to add to SPICE directives
 4. Modify parameters as needed for your design
 **Note:** The library directory is created automatically but not pre-populated. Users can create custom controller netlists or obtain templates from the Tesla coil community.
 ### Button State Intelligence
 pyTesla uses an intelligent button state tracking system to minimize unnecessary re-simulations:
 **Color-Coded States:**
 - **Blue** (Normal): Ready to run, prerequisites satisfied
 - **Yellow** (Warning): Parameters changed since last run, needs re-simulation
 - **Red** (Running): Simulation currently in progress
 - **Green** (Success): Simulation completed successfully
 **Parameter Snapshots:**
 - Stores "known good" parameters when simulation succeeds
 - Automatically compares current parameters against snapshot
 - Debounced checking (100ms delay) prevents excessive validation
 - Only triggers re-simulation warnings when parameters actually change
 **Sequential Invalidation:**
 - **Geometric changes** (coil dimensions, topload, etc.): Invalidate all simulations
 - **Circuit changes** (MMC, primary current, etc.): Only invalidate LTspice, stress, and modes
 - **Frequency changes**: Only invalidate distributed magnetic simulation
 - Preserves valid downstream results when possible, saving computation time
 This intelligent system ensures you always know which simulations are current and helps optimize your workflow by avoiding redundant calculations.
 ---
 ## Tips for Effective Use
 ### Workflow Optimization
 1. **Initial Design Exploration**:
   - Use standalone "Lumped" simulation for rapid parameter exploration
   - Provides quick frequency and coupling estimates for initial design iterations
 2. **Full Distributed Analysis**:
   - Click "Distributed" button (automatically runs lumped first for accurate frequency estimate)
   - Generates distributed transmission line model with capacitance matrix
   - Both Lumped and Distributed results become available for comparison
 3. **Manual Convergence Refinement**:
   - After successful distributed simulation (green button), adjust frequency manually if needed
   - Click "Distributed" again to enter iteration mode
   - Iteration mode skips lumped and electrostatic, only refining magnetic + LTspice
   - Repeat as needed for convergence without resetting expensive calculations
 4. **Model Selection**:
   - Use Lumped model for:
     - Quick frequency checks
     - Basic coupling analysis
     - Simple circuit analysis
   - Use Distributed model for:
     - Accurate voltage distribution
     - Parasitic mode analysis
     - Spark gap optimization
     - Final design validation
 5. **Performance Tips**:
   - Group parameter changes before running time-consuming simulations
   - Use iteration mode for frequency refinement without full re-simulation
   - Save known-good designs as profiles for reference
   - Choose appropriate section count for Distributed model:
     - 10 sections: Standard analysis (default)
     - 20+ sections: High precision needs
 *© pyTesla Documentation - For Tesla coil design and simulation*