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 uses FEMM and LTspice to simulate Tesla coils. It handles the electromagnetic field analysis (FEMM) and circuit simulation (LTspice) so you can tune your coil design without doing all the math by hand.

What it does

• Calculates inductance, capacitance, and coupling using FEMM
• Runs circuit simulations in LTspice to find resonant frequencies
• Shows you the coil geometry as you adjust parameters
• Saves your designs as profiles you can load later

---

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 results display in the right panel for calculated values
   • View field plots in the bottom image 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: Default theme for low-light environments
• Light Theme: Alternative for 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 uses a split layout:

1. Left Panel: Interactive Tesla coil visualization (matplotlib canvas)
2. Right Panel: Scrollable area containing:
   • Parameter input groups (Secondary, Topload, Primary, etc.)
   • Simulation control buttons
   • Model selection radio buttons (Lumped/Distributed)
   • Results display text area
3. Bottom Panel: Image gallery showing simulation plots (5 per row)

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 right 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
• Solver Precision: 1e-8, 1e-10, or 1e-12 (1e-6 removed due to FEMM bug)
• Magnetic Boundary Mode: Controls open boundary approximation
  • A=0 (Fast): Simple Dirichlet boundary, doubled radius - fastest solve
  • 3 Shells (Balanced): IABC with 3 shells - good balance of speed/accuracy (default)
  • 7 Shells (Accurate): IABC with 7 shells - FEMM's recommended accuracy

---

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

• Full 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
• Adaptive frequency sweep: Automatically scales to 10× your operating frequency to capture high-frequency parasitic modes
• Mode limit: Analyzes up to 5 parasitic modes per run to balance detail with processing time
• Uses logarithmic (decade) sweep for consistent resolution across frequency range
• Useful for optimizing coil geometry and understanding multi-mode behavior
• Requires Distributed simulation and LTspice results

---

Viewing Results

Results Panel

The right panel displays key simulation results based on the selected model (below the parameter inputs):

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 bottom 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 lets you run custom LTspice analyses and plot the results. It has presets so you don't have to set everything up from scratch each time.

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 (transient decay behavior)
• 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 (transient decay), 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

Save groups of measurements you use often:

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

These bundle together circuit setup, SPICE directives, and measurements into one-click configurations:

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 (transient decay) 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

Configurations save everything - circuit settings, directives, measurements, and display options - so you can reproduce the same test later or share it.

Hover Info

Move your mouse over the plot to see values at that point. The tooltip shows all plotted measurements at once, with crosshairs on both magnitude and phase plots.

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 (ringdown)
5. Analyze decay 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 (Ctrl+S): Quick save to current profile
• File → Save As... (Ctrl+Shift+S): Save to new location with file dialog
• All parameters, results, and images are saved
• Profiles are stored in the profiles/ directory

Loading Profiles

• File → Load Coil Profile (Ctrl+O): 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

Themes

pyTesla includes dark and light themes:

• Dark Theme: Default theme for low-light environments
• Light Theme: Alternative 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

You can add SPICE netlist templates for controllers and interrupters:

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 Colors

The simulation buttons change color to show what needs to be re-run:

• Blue: Ready to run
• Yellow: Parameters changed since last run - you should re-run this
• Red: Currently running
• Green: Done, results are current

When you change coil geometry, all simulations turn yellow. When you only change circuit values (like MMC), only the LTspice-related buttons turn yellow. This way you don't have to re-run expensive FEMM simulations when you're just tweaking circuit parameters.

---

Tips for Effective Use

Typical Workflow

1. Quick check: Run "Lumped" first to get a rough frequency estimate. It's fast.

2. Full analysis: Click "Distributed" for accurate results. It runs lumped automatically first, then does the full multi-section analysis.

3. Iterate if needed: If the distributed button is already green and you want to refine the frequency, click it again. It'll skip the electrostatic calculation and just re-run the magnetic + LTspice parts.

4. When to use each model:

   • Lumped: Quick checks, basic coupling analysis
   • Distributed: Voltage distribution, parasitic modes, spark optimization, final validation

5. Speed tips:

   • Change all your parameters before running simulations (avoids multiple re-runs)
   • 10 sections is usually enough; only go higher if you need extra precision