From e91bb324dc474ee9d44203bc8ffb3591b9d964fc Mon Sep 17 00:00:00 2001 From: Joe DiPrima Date: Fri, 7 Nov 2025 14:00:52 -0600 Subject: [PATCH] Initial commit: Add user documentation --- README.md | 721 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 721 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1b34963 --- /dev/null +++ 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 ` - AC frequency sweep +- `.tran ` - Transient analysis +- `.step param ` - Parametric sweep +- `.meas AC ` - 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* \ No newline at end of file