pyTesla - User Documentation

Table of Contents

• Overview
• Installation
• Getting Started
• Configuration
• User Interface
• Parameter Reference
• Simulation Types
• Viewing Results
• Profile Management
• Troubleshooting
• 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