toroid/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Python/Flask web application for designing and simulating toroidal transformers. It provides a browser-based UI backed by several physics modules:

1. Designer (designer.py) - Computes winding feasibility, layer counts, wire lengths, DC resistance, and weight for each winding segment given core geometry and wire specs
2. Simulator (sim_toroid.py) - Evaluates operating points (flux density, currents, losses, efficiency) and sweeps across frequency/load combinations
3. Drawing (draw_toroid.py) - Renders a top-down axial cross-section of the toroid (wire dots in bore, core annulus) as a PNG via matplotlib
4. Web App (app.py) - Flask server exposing REST API routes consumed by the browser UI
5. Legacy simple model (model.py) - Earlier physics-based model (taps, flux density, losses); still present but not used by the web app
6. Legacy optimizer (optimizer.py) - Brute-force tap/voltage optimizer for the legacy model
7. Impedance-Based Model (old/transformer_model.py) - Uses measured open-circuit and short-circuit parameters for AC analysis

Commands

Running the Web App

# Activate venv first (Unix/Mac):
source .venv/bin/activate

# Start the Flask dev server (port 5010):
python app.py
# Then open http://localhost:5010 in a browser

Running Legacy Simulations

# Run the simple transformer model with optimizer example
python sim.py

# Run the per-segment resistance example
python example_per_segment_resistance.py

# Run the impedance-based model example
python old/run_model_example.py

Development Environment

# Virtual environment exists at .venv
# Activate it (Windows):
.venv\Scripts\activate

# Activate it (Unix/Mac):
source .venv/bin/activate

# Install dependencies:
pip install -r requirements.txt

Code Architecture

Web App (app.py)

Flask server with these routes:

Route	Method	Description
GET /	GET	Serves the main HTML page (templates/index.html)
/api/design	POST	Runs design_transformer(), returns winding info + PNG drawing (base64)
/api/simulate	POST	Computes a single operating point via ToroidSimulator.simulate()
/api/sweep	POST	Runs sweep_operating_points() over a grid of frequencies × loads
/api/presets/<type>	GET	Lists saved presets for a category
/api/presets/<type>/<name>	GET/POST/DELETE	Load, save, or delete a named preset

Preset categories: core, windings, constraints, sim. Presets are persisted as JSON files in the presets/ directory.

Designer (designer.py)

• ToroidCore dataclass: core geometry (ID_mm, OD_mm, height_mm, Ae_mm2, Ve_mm3, optional Pv_func)
• WindingSpec dataclass: awg (list of AWG per segment), taps (incremental turns list), name
• WireSpec dataclass: wire diameter (with insulation), resistance/m, weight/m; look up via WireSpec.from_awg(awg)
• WindingResult dataclass: per-segment results (SegmentResult) including layers, wire length, resistance, weight, fits flag
• design_transformer(core, specs, fill_factor): returns list of WindingResult

Tap format: taps is a list of incremental turns. [0, 25, 50] means segment 1 = 25 turns, segment 2 = 50 turns; total turns = 75. Tap numbers are 1-indexed.

Simulator (sim_toroid.py)

• SimConstraints dataclass: B_max_T, Vp_max, Vs_max, Ip_max, Is_max, P_out_max_W
• ToroidSimulator: takes ToroidCore, primary WindingResult, secondary WindingResult
  • simulate(Vp_rms, freq_hz, primary_tap, secondary_tap, Z_load, constraints) → SimResult
  • SimResult fields: Np_eff, Ns_eff, turns_ratio, B_peak_T, Vp_rms_applied, Vs_rms, Ip_rms, Is_rms, P_out_W, P_cu_W, P_cu_primary_W, P_cu_secondary_W, P_core_W, P_in_W, efficiency, violations
• SweepEntry / sweep_operating_points(): sweeps all tap combinations over a frequency × load grid, finding the best tap pair for each condition at the target power
  • SweepEntry.as_dict() serialises to a flat dict for JSON responses

Drawing (draw_toroid.py)

• draw_toroid(core, results, output_path, dpi, fig_size_mm, actual_fill): renders top-down cross-section PNG using matplotlib
• View: looking down the toroid axis. Grey annulus = core; white disc = bore; coloured dots = wire cross-sections per winding/layer

Legacy Simple Model (model.py)

• TransformerModel dataclass: core area (Ae_mm2), turn counts, tap lists, per-turn resistance (uniform or per-segment)
• simulate(tap, Vp, freq, R_load) → flux density, currents, powers, efficiency

Legacy Optimizer (optimizer.py)

• TransformerOptimizer: brute-force search over all tap combinations + voltage sweep
• Returns OptimizationResult with optimal tap/voltage configuration

Impedance Model (old/transformer_model.py)

• TransformerModel: interpolates measured OC/SC test data; frequency-dependent Rc/Lm; per-tap Req/L_leak
• input_impedance(), transfer() for AC analysis

Important Implementation Details

• Loads are specified as complex impedance (R, X) pairs in ohms
• Flux density uses sinusoidal formula: B_peak = Vp / (4.44 * f * N * Ae)
• Core loss uses Pv_func(f_hz, B_T) if provided, else a simple Steinmetz fallback
• Tap numbering is 1-indexed throughout
• The old/ directory contains the earlier impedance-based approach
• presets/ directory is auto-created; stores JSON files (core.json, windings.json, constraints.json, sim.json)