81 lines
4.0 KiB
Markdown
81 lines
4.0 KiB
Markdown
# 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-based transformer modeling toolkit for electrical power transformers. It contains two distinct transformer models and an optimizer:
|
|
|
|
1. **Simple Ideal Model** ([model.py](model.py)) - Physics-based model for transformers with taps, calculates flux density, losses, and efficiency
|
|
2. **Optimizer** ([optimizer.py](optimizer.py)) - Finds optimal tap settings and input voltage to maximize efficiency for a given load and target power
|
|
3. **Impedance-Based Model** ([old/transformer_model.py](old/transformer_model.py)) - Uses measured open-circuit and short-circuit parameters for AC analysis
|
|
|
|
## Commands
|
|
|
|
### Running Simulations
|
|
|
|
```bash
|
|
# Run the simple transformer model with optimizer example (requires numpy)
|
|
python sim.py
|
|
|
|
# Run the per-segment resistance example
|
|
python example_per_segment_resistance.py
|
|
|
|
# Run the impedance-based model example (requires numpy)
|
|
python old/run_model_example.py
|
|
```
|
|
|
|
### Development Environment
|
|
|
|
```bash
|
|
# Virtual environment exists at .venv
|
|
# Activate it (Windows):
|
|
.venv\Scripts\activate
|
|
|
|
# Activate it (Unix/Mac):
|
|
source .venv/bin/activate
|
|
```
|
|
|
|
## Code Architecture
|
|
|
|
### Simple Model (model.py)
|
|
|
|
- **TransformerModel** class: Dataclass-based model with:
|
|
- Core geometry parameters (Ae_mm2)
|
|
- Turn counts and tap positions for primary/secondary windings
|
|
- Copper resistance per turn (supports both uniform and per-segment values)
|
|
- `simulate()` method: Calculates one operating point given tap number, voltage, frequency, and load
|
|
- Returns flux density (B_peak_T), currents, powers, and efficiency
|
|
|
|
**Key concept**: Taps are defined as lists of **incremental turns** for each segment. First element is always 0, subsequent elements specify turns to add. Example: `[0, 128, 23]` means segment 1 adds 128 turns, segment 2 adds 23 turns. Tap numbers are 1-indexed: `tap=1` gives 128 turns, `tap=2` gives 128+23=151 turns total.
|
|
|
|
**Per-segment resistance**: For windings with different wire gauges per segment, use `primary_Rp_per_turn` and `secondary_Rs_per_turn` lists. Each element specifies R/turn for that segment (e.g., `[0.001, 0.002]` for a 2-segment winding). Legacy single-value `Rp_per_turn`/`Rs_per_turn` still supported.
|
|
|
|
### Optimizer (optimizer.py)
|
|
|
|
- **TransformerOptimizer** class: Brute-force search optimizer
|
|
- `optimize()` method: Searches all tap combinations and voltage sweep to find maximum efficiency
|
|
- Constraints: Target power delivery (with tolerance), maximum flux density (B_max_T), maximum secondary voltage (Vs_max), input voltage range
|
|
- Returns **OptimizationResult** with optimal configuration and all operating point details
|
|
- **Fallback mode** (default): If target power cannot be achieved, finds max achievable power with best efficiency
|
|
|
|
**Key concept**: For a given load and target power, the optimizer tries all possible tap combinations and input voltages to find the configuration that maximizes efficiency while meeting all constraints (power delivery, flux density, and secondary voltage).
|
|
|
|
### Impedance Model (old/transformer_model.py)
|
|
|
|
- **TransformerModel** class: Interpolates measured OC/SC test data
|
|
- Frequency-dependent Rc and Lm from open-circuit tests
|
|
- Per-tap series impedance (Req, L_leak) from short-circuit tests
|
|
- `input_impedance()`: Calculates Zin at frequency/tap/load
|
|
- `transfer()`: Full AC transfer function with powers and efficiency
|
|
|
|
**Key concept**: Model uses complex impedance networks with reflected loads through turns ratios.
|
|
|
|
## Important Implementation Details
|
|
|
|
- Both models assume **purely resistive loads**
|
|
- Simple model uses **sinusoidal excitation** (4.44*f formula for flux density)
|
|
- Impedance model supports **source resistance** and secondary winding resistance per tap
|
|
- Tap numbering: Both models use 1-indexed taps (tap=1, tap=2, etc.)
|
|
- The `old/` directory contains the earlier impedance-based approach with example sweep functionality
|