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*