PyOpenMagnetics 1.7.5__cp314-cp314-win_amd64.whl

PyOpenMagnetics/AGENTS.md

@@ -0,0 +1,905 @@
+# AGENTS.md — PyOpenMagnetics AI Assistant Guide
+
+> **MKF is authoritative for all magnetics math.** Before implementing any
+> magnetics calculation or assuming an API exists, consult
+> [`../MKF/CAPABILITIES.md`](../MKF/CAPABILITIES.md). If a needed capability
+> isn't listed there, ask — don't reinvent it here.
+
+> **Two stub files in this repo:**
+> - `PyOpenMagnetics.pyi` — **curated**. Authoritative on arg conventions
+>   and gotchas. Read this first.
+> - `PyOpenMagnetics.generated.pyi` — **auto-generated** from the compiled
+>   `.so` via pybind11-stubgen. Wider coverage (every exported symbol) but
+>   raw — signatures are right, conventions may not be. Use as a discovery
+>   index; when it disagrees with the curated stub, trust the curated one.
+
+> **This file is the SINGLE SOURCE OF TRUTH for any AI agent using PyOpenMagnetics.**
+> Every instruction was derived from reading the C++ source code
+> (`converter.cpp`, `magnetics.cpp`, `cores.cpp`, `wires.cpp`, `settings.cpp`,
+> `database.cpp`, `CoreAdviser.h/.cpp`, `MagneticAdviser.h/.cpp`, `MAS.hpp`,
+> `Flyback.h/.cpp`, all converter model headers, and all adviser files)
+> and **validated by running the library**.
+>
+> When this document contradicts the `.pyi` stubs or bundled examples,
+> **trust this document**.
+
+
+---
+
+## 🚨 STOP! READ THIS FIRST — COMMON AGENT MISTAKES
+
+**Before writing ANY code, check these three things:**
+
+1. **NEVER use `json.dumps()`** — Pass Python dicts directly to all functions.
+   `json.dumps()` converts your dict to a string, causing schema errors.
+
+2. **NEVER invent your own JSON structure** — Copy the EXACT schemas from Section 5.
+   Fields like `"inputs"`, `"outputs"`, `"voltage"` are WRONG. Use `"inputVoltage"`, `"operatingPoints"`, etc.
+
+3. **NEVER abandon Method A after an error** — If you get `"Input JSON does not conform to schema!"`,
+   the fix is to correct your JSON, NOT to fall back to manual calculations.
+
+**See Section 13.1 for wrong vs correct code examples.**
+
+
+## ⛔ THE #1 RULE — DO NOT USE MANUAL CALCULATIONS
+
+When a user asks you to design a magnetic component for a power converter:
+
+1. **ALWAYS** use `design_magnetics_from_converter()` first (Method A — single call)
+2. If Method A fails (e.g., ngspice cannot initialize), fall back to
+   `process_converter()` → `calculate_advised_magnetics()` (Method B)
+3. **NEVER** calculate turns ratios, inductance, core sizes, or wire gauges manually
+4. **NEVER** fall back to textbook formulas — fix the API call instead
+
+The MKF engine handles complex magnetic field distributions, temperature-dependent
+material properties, geometrical fringing effects, and real commercial core database
+constraints that manual formulas cannot replicate.
+
+### â±ï¸ TIMEOUT IS NOT A FAILURE â€" DO NOT ABANDON METHOD A!
+
+**If Method A times out, this is NOT a reason to switch to Method B.**
+
+The design computation is CPU-intensive:
+- `"available cores"` searches 1301+ shapes and can take **60â€"180+ seconds**
+- `"standard cores"` is faster (10â€"30 seconds) but has fewer options
+
+**If your environment has a short timeout (e.g., 2â€"3 minutes):**
+1. **First try:** Use `"standard cores"` instead of `"available cores"` â€" this is much faster
+2. **If still timing out:** Increase your timeout to 5+ minutes, NOT switch to Method B
+3. **Only use Method B** if Method A returns an actual error (schema error, ngspice failure, etc.)
+
+```python
+# ✅ CORRECT â€" use "standard cores" for faster execution
+result = PyOM.design_magnetics_from_converter(
+    "flyback", flyback, 3, "standard cores", True, None  # faster!
+)
+
+# ⌠WRONG â€" abandoning Method A just because "available cores" is slow
+# Don't do this: "it timed out, so I'll use Method B instead"
+```
+
+**Why this matters:** Method A computes the optimal inductance, turns ratio, and
+operating waveforms automatically from the converter specification. Method B requires
+you to pre-calculate these values, which can introduce errors.
+
+---
+
+## 1. Installation
+
+```bash
+pip install PyOpenMagnetics
+```
+
+If the `.whl` is provided as base64-encoded parts:
+```python
+import base64
+with open("pyopenmagnetics-1.3.0.whl.base64.partaa", "rb") as f:
+    part_a = f.read()
+with open("pyopenmagnetics-1.3.0.whl.base64.partab", "rb") as f:
+    part_b = f.read()
+whl_data = base64.b64decode(part_a + part_b)
+with open("pyopenmagnetics.whl", "wb") as f:
+    f.write(whl_data)
+# Then: pip install pyopenmagnetics.whl
+```
+
+---
+
+## 2. Import — CRITICAL (Most Agents Fail Here)
+
+The package has **no `__init__.py`**. A bare `import PyOpenMagnetics` gives an
+**empty namespace with 0 functions**. You MUST use `importlib`:
+
+```python
+import PyOpenMagnetics as PyOM
+
+# MANDATORY - must call before any other function
+PyOM.load_databases({})
+```
+
+**Verify:**
+```python
+assert len(dir(PyOM)) > 100, "Module not loaded properly"
+assert hasattr(PyOM, 'design_magnetics_from_converter')
+print(f"Materials: {len(PyOM.get_core_material_names())}")   # ~409
+print(f"Shapes: {len(PyOM.get_core_shape_names(True))}")     # ~1301
+```
+
+---
+
+## 3. Method A: `design_magnetics_from_converter()` (Preferred — Single Call)
+
+This goes directly from converter specifications to complete, ranked magnetic
+component designs in a single call.
+
+### ngspice Is Bundled
+
+ngspice is shipped inside the wheel at `.ngspice/lib/libngspice.so`. No
+separate install needed. The C++ code **ignores** the `use_ngspice` parameter:
+`(void)useNgspice;` — it always uses ngspice internally.
+
+In sandboxed environments where `dlopen` is restricted, ngspice may fail to
+initialize — use Method B with `use_ngspice=False` in that case.
+
+### Signature (use POSITIONAL args — the .pyi has WRONG keyword names!)
+
+```python
+result = PyOM.design_magnetics_from_converter(
+    topology_name,    # str — REQUIRED
+    converter_json,   # dict — REQUIRED (BASE class schema, see Section 5)
+    max_results,      # int — 1-10
+    core_mode_json,   # str — "available cores" or "standard cores"
+    use_ngspice,      # bool — IGNORED (always True internally)
+    weights_json      # dict or None
+)
+```
+
+### ⚠️ The .pyi Stub Has WRONG Keyword Names
+
+`.pyi` says: `topology=`, `converter=`, `core_mode=`, `weights=`.
+Actual pybind11: `topology_name=`, `converter_json=`, `core_mode_json=`, `weights_json=`.
+**Safest: use positional arguments.**
+
+---
+
+### 🚨 Pass Python Dicts — NEVER json.dumps()!
+
+The C++ pybind11 binding accepts **Python dicts directly**. `json.dumps()` turns
+your dict into a **string** → the C++ parser gets a string instead of an object
+→ `"Input JSON does not conform to schema!"`.
+
+```python
+# ❌ WRONG — json.dumps() causes schema error
+result = PyOM.design_magnetics_from_converter("flyback", json.dumps(converter), ...)
+result = PyOM.design_magnetics_from_converter("flyback", converter, 3, json.dumps("STANDARD_CORES"), ...)
+
+# ✅ CORRECT — pass Python dict and plain string
+result = PyOM.design_magnetics_from_converter("flyback", converter, 3, "available cores", True, None)
+```
+
+### 🚨 NEVER Abandon Method A After a Schema Error!
+
+If `design_magnetics_from_converter` throws `"Input JSON does not conform to schema!"`,
+the fix is to correct the JSON — **NOT** to fall back to `calculate_advised_cores` or
+manual math. Common fixes:
+1. Remove `json.dumps()` from all arguments
+2. Use `"available cores"` (lowercase + space), not `"STANDARD_CORES"`
+3. Use positional arguments, not keyword arguments
+4. For offline flyback: use the Advanced schema with `desiredInductance`
+
+---
+
+## 4. The THREE Things That MUST Be Correct (All Verified)
+
+### 4.1 `core_mode_json` Must Be LOWERCASE WITH SPACE
+
+From `CoreAdviser.h` `from_json`:
+```cpp
+if (j == "available cores") x = CoreAdviserModes::AVAILABLE_CORES;
+else if (j == "standard cores") x = CoreAdviserModes::STANDARD_CORES;
+else if (j == "custom cores") x = CoreAdviserModes::CUSTOM_CORES;
+else throw std::runtime_error("Input JSON does not conform to schema!");
+```
+
+| ❌ WRONG | ✅ CORRECT |
+|---|---|
+| `"AVAILABLE_CORES"` | `"available cores"` |
+| `"STANDARD_CORES"` | `"standard cores"` |
+| `"Available Cores"` | `"available cores"` |
+| `0` (integer) | `"available cores"` |
+
+- `"available cores"` — WE commercial cores (~1301 shapes, 60–120+ sec)
+- `"standard cores"` — generic shapes (faster, fewer options)
+
+### 4.2 Flyback `operatingPoints[].mode` - Optional When currentRippleRatio Is Set
+
+The `mode` field is **optional** if `currentRippleRatio` is provided. The C++ code
+will auto-infer the mode: CCM if ripple < 1.0, DCM if ripple >= 1.0.
+
+If you omit both `mode` AND `currentRippleRatio`, you'll get an error:
+`"Either current ripple ratio or mode is needed for the Flyback OperatingPoint Mode"`
+
+Valid mode values:
+- `"Continuous Conduction Mode"` (CCM — most common for >20W)
+- `"Discontinuous Conduction Mode"` (DCM)
+- `"Boundary Mode Operation"` (BCM)
+- `"Quasi Resonant Mode"` (QR)
+
+Other topologies (Buck, Boost, Forward, LLC) do **NOT** need a mode field.
+
+### 4.3 Use BASE Class Schema (NOT AdvancedFlyback)
+
+`design_magnetics_from_converter()` uses `OpenMagnetics::Flyback` (base).
+`process_converter()` uses `OpenMagnetics::AdvancedFlyback`.
+
+| Field | Method A (Base) | Method B (Advanced) |
+|---|---|---|
+| `desiredInductance` | ❌ Causes schema error | ✅ Required |
+| `desiredTurnsRatios` | ❌ Causes schema error | ✅ Required |
+| `desiredDutyCycle` | ❌ Causes schema error | ✅ Optional |
+| `currentRippleRatio` | ✅ REQUIRED (Flyback/Boost/Forward) | ✅ Optional |
+| `mode` in operatingPoints | Optional (auto-inferred if currentRippleRatio set) | Not needed |
+
+---
+
+## 5. Converter JSON Schemas — All Topologies (Verified from MAS.hpp)
+
+### 5.1 Flyback — Method A (BASE class)
+
+```python
+flyback_base = {
+    "currentRippleRatio": 0.4,          # REQUIRED (j.at)
+    "diodeVoltageDrop": 0.5,            # REQUIRED (j.at)
+    "efficiency": 0.88,                 # REQUIRED (j.at)
+    "inputVoltage": {                   # REQUIRED (j.at)
+        "minimum": 185.0,
+        "nominal": 220.0,              # recommended
+        "maximum": 265.0
+    },
+    "operatingPoints": [{               # REQUIRED (j.at)
+        "ambientTemperature": 25.0,     # REQUIRED (j.at)
+        "outputVoltages": [12.0],       # REQUIRED (j.at) — PLURAL
+        "outputCurrents": [2.0],        # REQUIRED (j.at) — PLURAL
+        "switchingFrequency": 100000.0, # optional (get_stack_optional)
+        "mode": "Continuous Conduction Mode"  # Optional if currentRippleRatio is set (auto-inferred)
+    }],
+    "maximumDutyCycle": 0.45,           # optional
+    "maximumDrainSourceVoltage": 800.0  # optional
+}
+```
+
+### 5.2 Flyback — Method B (AdvancedFlyback)
+
+```python
+flyback_advanced = {
+    "inputVoltage": {"minimum": 185, "maximum": 265},
+    "desiredInductance": 800e-6,         # AdvancedFlyback only
+    "desiredTurnsRatios": [13.5],        # AdvancedFlyback only
+    "desiredDutyCycle": [[0.45, 0.45]],  # AdvancedFlyback only
+    "maximumDutyCycle": 0.45,
+    "efficiency": 0.88,
+    "diodeVoltageDrop": 0.5,
+    "currentRippleRatio": 0.4,
+    "operatingPoints": [{
+        "outputVoltages": [12.0],
+        "outputCurrents": [2.0],
+        "switchingFrequency": 100000,
+        "ambientTemperature": 25
+    }]
+}
+```
+
+### 5.3 Buck — Method A (BASE class)
+
+```python
+buck_base = {
+    "diodeVoltageDrop": 0.5,            # REQUIRED (j.at)
+    "inputVoltage": {"minimum": 10.0, "maximum": 14.0},  # REQUIRED
+    "operatingPoints": [{
+        "ambientTemperature": 25.0,     # REQUIRED
+        "outputVoltage": 3.3,           # REQUIRED — ⚠️ SINGULAR!
+        "outputCurrent": 5.0,           # REQUIRED — ⚠️ SINGULAR!
+        "switchingFrequency": 500000.0  # REQUIRED (j.at)
+    }]
+}
+```
+
+### 5.4 Boost — Method A (BASE class)
+
+```python
+boost_base = {
+    "currentRippleRatio": 0.3,          # REQUIRED (j.at)
+    "diodeVoltageDrop": 0.7,            # REQUIRED (j.at)
+    "efficiency": 0.92,                 # REQUIRED (j.at)
+    "inputVoltage": {"minimum": 5.0, "maximum": 5.0},  # REQUIRED
+    "operatingPoints": [{
+        "ambientTemperature": 25.0,     # REQUIRED
+        "outputVoltage": 12.0,          # REQUIRED — ⚠️ SINGULAR!
+        "outputCurrent": 1.0,           # REQUIRED — ⚠️ SINGULAR!
+        "switchingFrequency": 100000.0  # REQUIRED (j.at)
+    }]
+}
+```
+
+### 5.5 Forward (Single-Switch, Two-Switch, Active-Clamp) — Method A
+
+```python
+forward_base = {
+    "currentRippleRatio": 0.4,          # REQUIRED (j.at)
+    "diodeVoltageDrop": 0.5,            # REQUIRED (j.at)
+    "inputVoltage": {"minimum": 36.0, "maximum": 72.0},
+    "operatingPoints": [{
+        "ambientTemperature": 25.0,     # REQUIRED (j.at)
+        "outputVoltages": [5.0],        # REQUIRED (j.at) — PLURAL
+        "outputCurrents": [10.0],       # REQUIRED (j.at) — PLURAL
+        "switchingFrequency": 200000.0  # REQUIRED (j.at) for Forward!
+    }]
+    # optional: "efficiency", "dutyCycle", "maximumSwitchCurrent"
+}
+```
+Use topology strings: `"single_switch_forward"`, `"two_switch_forward"`, `"active_clamp_forward"`.
+
+### 5.6 LLC — Method A (BASE class)
+
+```python
+llc_base = {
+    "inputVoltage": {"minimum": 380.0, "maximum": 420.0},  # REQUIRED (j.at)
+    "minSwitchingFrequency": 100000.0,  # REQUIRED (j.at)
+    "maxSwitchingFrequency": 300000.0,  # REQUIRED (j.at)
+    "operatingPoints": [{               # REQUIRED (j.at)
+        "ambientTemperature": 25.0,
+        "outputVoltages": [12.0],       # REQUIRED — PLURAL
+        "outputCurrents": [5.0],        # REQUIRED — PLURAL
+        "switchingFrequency": 200000.0  # Operating frequency
+    }],
+    # optional fields:
+    "efficiency": 0.95,                 # optional
+    "qualityFactor": 0.5,               # optional
+    "resonantFrequency": 150000.0       # optional
+}
+```
+
+
+### 5.7 PushPull — Same Schema as Forward
+
+### 5.8 Singular vs Plural Field Names (Critical!)
+
+| Topology | outputVoltage(s) | outputCurrent(s) |
+|---|---|---|
+| Flyback | `outputVoltages` (PLURAL, list) | `outputCurrents` (PLURAL, list) |
+| Forward | `outputVoltages` (PLURAL, list) | `outputCurrents` (PLURAL, list) |
+| PushPull | `outputVoltages` (PLURAL, list) | `outputCurrents` (PLURAL, list) |
+| LLC | `outputVoltages` (PLURAL, list) | `outputCurrents` (PLURAL, list) |
+| Buck | `outputVoltage` (SINGULAR, float) | `outputCurrent` (SINGULAR, float) |
+| Boost | `outputVoltage` (SINGULAR, float) | `outputCurrent` (SINGULAR, float) |
+| DualActiveBridge | `outputVoltage` (SINGULAR) | `outputCurrent` (SINGULAR) |
+
+### 5.9 How to Estimate Flyback Parameters
+
+If user says "220V to 12V, 2A" without detail:
+```
+Vin_dc_min ≈ 185 × √2 × 0.9 ≈ 235V
+Dmax = 0.45, η = 0.88
+n = (12+0.5)×0.55 / (235×0.45×0.88) ≈ 0.074
+turnsRatio = 1/n ≈ 13.5   → for desiredTurnsRatios (Method B only)
+Lm ≈ 800 µH                → for desiredInductance (Method B only)
+```
+
+---
+
+## 6. Complete Working Examples
+
+### Method A: `design_magnetics_from_converter()` (single call)
+
+```python
+import PyOpenMagnetics as PyOM
+PyOM.load_databases({})
+
+# Define converter (BASE Flyback schema — NO desiredInductance!)
+flyback = {
+    "currentRippleRatio": 0.4,
+    "diodeVoltageDrop": 0.5,
+    "efficiency": 0.88,
+    "inputVoltage": {"minimum": 185.0, "nominal": 220.0, "maximum": 265.0},
+    "maximumDutyCycle": 0.45,
+    "operatingPoints": [{
+        "ambientTemperature": 25.0,
+        "outputVoltages": [12.0],
+        "outputCurrents": [2.0],
+        "switchingFrequency": 100000.0,
+        "mode": "Continuous Conduction Mode"   # Optional if currentRippleRatio is set (auto-inferred)
+    }]
+}
+
+# design_magnetics_from_converter() builds MAS Inputs from the spec (the
+# magnetic adviser is a separate step -- see Method B, which continues from
+# here). Failures raise PyOM.EngineError (v1.7.0+).
+try:
+    inputs = PyOM.design_magnetics_from_converter("flyback", flyback)
+except PyOM.EngineError as e:
+    print(f"Method A failed: {e}")
+else:
+    print(f"Turns ratios: {inputs['designRequirements']['turnsRatios']}")
+    print(f"Operating points: {len(inputs['operatingPoints'])}")
+```
+
+### Method B: `process_converter()` → `calculate_advised_magnetics()` (no ngspice needed)
+
+```python
+# Step 1: Process converter (AdvancedFlyback schema)
+flyback_adv = {
+    "inputVoltage": {"minimum": 185, "maximum": 265},
+    "desiredInductance": 800e-6,
+    "desiredTurnsRatios": [13.5],
+    "desiredDutyCycle": [[0.45, 0.45]],
+    "maximumDutyCycle": 0.45,
+    "efficiency": 0.88,
+    "diodeVoltageDrop": 0.5,
+    "currentRippleRatio": 0.4,
+    "operatingPoints": [{
+        "outputVoltages": [12.0],
+        "outputCurrents": [2.0],
+        "switchingFrequency": 100000,
+        "ambientTemperature": 25
+    }]
+}
+processed = PyOM.process_converter("flyback", flyback_adv, use_ngspice=False)
+# failures raise PyOM.EngineError -- no error-shaped return values (v1.7.0+)
+
+# Step 2: Feed into adviser (with optional weights)
+mas_inputs = {
+    "designRequirements": processed["designRequirements"],
+    "operatingPoints":    processed["operatingPoints"]
+}
+# calculate_advised_magnetics takes (inputs, max_results, core_mode) -- no weights
+# argument (that is calculate_advised_cores). Inputs must be processed first.
+mas_inputs = PyOM.process_inputs(mas_inputs)
+designs = PyOM.calculate_advised_magnetics(mas_inputs, 1, "available cores")
+
+# Step 3: Parse -- result is {"data": [{"mas", "scoring", ...}]}
+d = designs["data"][0]
+mas_obj, score = d["mas"], d["scoring"]
+core = mas_obj["magnetic"]["core"]["functionalDescription"]
+coil = mas_obj["magnetic"]["coil"]["functionalDescription"]
+print(f"Core: {core['shape'].get('name','?')}, Material: {core['material'].get('name','?')}")
+for w in coil:
+    print(f"  {w['name']}: {w['numberTurns']} turns, {w.get('numberParallels',1)} parallels")
+```
+
+---
+
+## 7. Weights (Priorities)
+
+Both `design_magnetics_from_converter()` and `calculate_advised_magnetics()` accept
+an optional weights dict. The keys must be **lowercase** MagneticFilters enum values:
+
+```python
+weights = {
+    "efficiency": 2.0,    # prioritize low losses
+    "cost": 1.0,          # consider cost
+    "dimensions": 0.5     # size is less important
+}
+```
+
+Valid weight keys (from `MAS.hpp` `MagneticFilters` `from_json`):
+- `"cost"` — minimize core/wire cost
+- `"dimensions"` — minimize physical size
+- `"efficiency"` — minimize total losses
+
+Pass as the 4th argument to `calculate_advised_magnetics()` or 6th to
+`design_magnetics_from_converter()`. Pass `None` for default equal weights.
+
+---
+
+## 8. Settings
+
+Control global behavior with the settings API:
+
+```python
+# Get current settings
+settings = PyOM.get_settings()
+
+# Modify settings
+PyOM.set_settings({
+    "useOnlyCoresInStock": True,         # only use cores marked in stock
+    "painterNumberPointsX": 100,         # plot X resolution
+    "painterNumberPointsY": 100,         # plot Y resolution
+    "coilAllowMarginTape": True,         # allow margin tape in coil designs
+    "coilAllowInsulatedWire": True,      # allow insulated wire
+    "magneticFieldMirroringDimension": 0 # simulation accuracy (0=fast, higher=more accurate)
+})
+
+# Reset to defaults
+PyOM.reset_settings()
+```
+
+---
+
+## 9. Database Access
+
+> ⚠️ **Naming convention**: single-item lookup functions use the `find_*_by_name()` prefix,
+> NOT `get_*_by_name()`. `get_core_shape_by_name()` does **not exist** and will raise `AttributeError`.
+
+### Core Shapes
+```python
+names    = PyOM.get_core_shape_names(True)        # ✅ verified — True=include toroidal
+families = PyOM.get_core_shape_families()          # ✅ verified — NO argument (bool arg → TypeError)
+shape    = PyOM.find_core_shape_by_name("E 25/13/7")  # ✅ verified
+```
+
+### Core Materials
+```python
+mat_names = PyOM.get_core_material_names()         # ✅ verified
+material  = PyOM.find_core_material_by_name("3C95")  # ✅ verified (.pyi confirmed)
+```
+
+### Wires
+```python
+wire_names = PyOM.get_wire_names()                 # ✅ verified
+wire       = PyOM.find_wire_by_name("Round 0.5 - Grade 1")  # ✅ verified (.pyi confirmed)
+```
+
+### Bobbins
+```python
+bobbin = PyOM.find_bobbin_by_name("Bobbin E25/7")    # ✅ verified (.pyi confirmed)
+```
+
+### ❌ Wrong names — do NOT use these
+```python
+PyOM.get_core_shape_by_name(...)      # AttributeError — does not exist
+PyOM.get_core_material_by_name(...)   # AttributeError — does not exist
+PyOM.get_wire_by_name(...)            # AttributeError — does not exist
+PyOM.get_bobbin_by_name(...)          # AttributeError — does not exist
+PyOM.get_core_shape_families(True)    # TypeError — takes no arguments
+```
+
+---
+
+## 10. Post-Design Analysis (All Verified)
+
+### Inductance Calculation
+```python
+inductance = PyOM.calculate_inductance_from_number_turns_and_gapping(
+    core, coil, operating_point, models)
+# Returns dict with:
+#   magnetizingInductance → {magnetizingInductance, coreReluctance, gappingReluctance, ...}
+```
+
+### Core Losses
+```python
+models = {"coreLosses": "IGSE"}  # or "STEINMETZ", "ROSHEN", etc.
+losses = PyOM.calculate_core_losses(core, coil, operating_point, models)
+```
+
+### Winding Losses
+```python
+winding_losses = PyOM.calculate_winding_losses(magnetic, operating_point, temperature)
+```
+
+### Full Simulation
+```python
+sim_result = PyOM.simulate(mas)
+```
+
+### Wire Utilities
+```python
+# Skin depth: the 2nd arg is a CURRENT SignalDescriptor (needs processed.label +
+# processed.effectiveFrequency), NOT a bare frequency. Passing a number returns garbage.
+current = {
+    "waveform": {"data": [-5, 5, -5], "time": [0, 5e-6, 10e-6]},
+    "processed": {"label": "triangular", "effectiveFrequency": 100000,
+                  "rms": 2.9, "peak": 5, "peakToPeak": 10, "offset": 0, "dutyCycle": 0.5}
+}
+delta = PyOM.calculate_effective_skin_depth("copper", current, 25)   # ~0.21 mm for Cu @100 kHz
+
+# DC resistance per meter for a given wire diameter
+wire = PyOM.find_wire_by_name("Round 0.5 - Grade 1")
+rdc = PyOM.calculate_dc_resistance_per_meter(wire, 25)   # (wire object, temperature)
+```
+
+### SPICE Export
+```python
+subcircuit = PyOM.export_magnetic_as_subcircuit(magnetic)
+# Returns SPICE subcircuit string
+```
+
+---
+
+## 11. Supported Topologies
+
+`process_converter("<topology>", json, use_ngspice)` is the universal entry
+point and accepts every string below, plus its `"advanced_<topology>"` form
+(the internal builds the `Advanced*` MKF class either way — "advanced" is
+selected by the JSON payload shape, e.g. presence of `desiredInductance` /
+`desiredMagnetizingInductance` / `desiredBoostInductance`, not by the name).
+
+### 11.1 Per-topology API parity matrix
+
+Every topology exposes the **same four surfaces** (✓ = present). Columns:
+- **inputs** — `calculate_<t>_inputs(json)` (basic) and
+  `calculate_advanced_<t>_inputs(json)` (advanced)
+- **process** — dedicated `process_<t>(json)` thin wrapper (all are also
+  reachable via the generic `process_converter`)
+- **simulate** — `simulate_<t>_ideal_waveforms(json)` (ngspice)
+- **ngspice** — `generate_<t>_ngspice_circuit(json, input_voltage_index=0, operating_point_index=0)`
+
+| Topology string | inputs (basic / advanced) | process_* | simulate | generate ngspice |
+|---|---|---|---|---|
+| `flyback` | ✓ / ✓ | ✓ | ✓ (+`simulate_flyback_with_magnetic`) | ✓ |
+| `buck` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `boost` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `single_switch_forward` | ✓ / ✓ | ✓ | ✓ (`simulate_forward_*`) | ✓ (`generate_forward_*`) |
+| `two_switch_forward` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `active_clamp_forward` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `push_pull` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `isolated_buck` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `isolated_buck_boost` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `cuk` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `sepic` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `zeta` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `four_switch_buck_boost` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `weinberg` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `llc` | ✓ / ✓ | via `process_converter` | ✓ | ✓ |
+| `cllc` | ✓ / ✓ | via `process_converter` | ✓ | ✓ |
+| `clllc` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `src` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `dab` | ✓ / ✓ | via `process_converter` | ✓ | ✓ |
+| `phase_shifted_full_bridge` (`psfb`) | ✓ / ✓ | via `process_converter` | ✓ | ✓ |
+| `phase_shifted_half_bridge` (`pshb`) | ✓ / ✓ | via `process_converter` | ✓ | ✓ |
+| `asymmetric_half_bridge` (`ahb`) | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `vienna` | ✓ / ✓ | ✓ | ✓ | ✓ |
+| `power_factor_correction` (`pfc`) | ✓ / — ¹ | via `process_converter` | ✓ (`simulate_pfc_waveforms`) | ✓ ² |
+| `current_transformer` | — ³ | ✓ ³ | — | — |
+| `common_mode_choke` (`cmc`) | `calculate_cmc_inputs` / `calculate_advanced_cmc_inputs` | — | `simulate_cmc_ideal_waveforms`, `simulate_cmc_lisn_waveforms` | `generate_cmc_ngspice_circuit` |
+| `differential_mode_choke` (`dmc`) | `calculate_dmc_inputs` | `propose_dmc_design`, `verify_dmc_attenuation` | `simulate_dmc_waveforms` | `generate_dmc_ngspice_circuit` |
+
+¹ PFC has no `AdvancedPowerFactorCorrection` class in MKF — basic-only by design;
+  there is intentionally no `calculate_advanced_pfc_inputs`.
+² `generate_pfc_ngspice_circuit(json, dc_resistance=0.1, simulation_time=0.02,
+  time_step=1e-8)` — PFC is a line-frequency model, so it takes circuit-damping
+  parameters instead of the `input_voltage_index` / `operating_point_index`
+  sweep indices used by the DC-DC family. Inductance comes from an explicit
+  `"inductance"` field or is derived from `"mode"` (CCM/CrCM/DCM).
+³ Current transformer is measurement-only: `process_current_transformer(json,
+  turns_ratio, secondary_resistance=0.0)`.
+
+### 11.2 Dedicated `process_*` thin wrappers
+
+`process_flyback()`, `process_buck()`, `process_boost()`,
+`process_single_switch_forward()`, `process_two_switch_forward()`,
+`process_active_clamp_forward()`, `process_push_pull()`,
+`process_isolated_buck()`, `process_isolated_buck_boost()`,
+`process_cuk()`, `process_sepic()`, `process_zeta()`,
+`process_four_switch_buck_boost()`, `process_asymmetric_half_bridge()`,
+`process_weinberg()`, `process_vienna()`, `process_clllc()`, `process_src()`,
+`process_current_transformer(json, turns_ratio, secondary_resistance=0.0)`.
+Topologies without a dedicated wrapper (`llc`, `cllc`, `dab`, `psfb`, `pshb`,
+`pfc`) are reached through `process_converter("<topology>", json)`.
+
+---
+
+## 12. Result Structure
+
+Both methods return a list of `[mas_dict, score]` tuples:
+
+```python
+d = result[0]                          # First (best) design
+mas_obj = d[0]                         # MAS dict
+score   = d[1]                         # float — higher is better
+
+# Core info
+core_fd = mas_obj["magnetic"]["core"]["functionalDescription"]
+shape    = core_fd["shape"]            # dict with "name", dimensions, etc.
+material = core_fd["material"]         # dict with "name", properties, etc.
+gapping  = core_fd["gapping"]          # list of gap dicts
+
+# Coil info
+coil_fd = mas_obj["magnetic"]["coil"]["functionalDescription"]
+for winding in coil_fd:
+    name     = winding["name"]          # "primary", "secondary", etc.
+    turns    = winding["numberTurns"]   # int
+    parallels = winding.get("numberParallels", 1)
+    wire     = winding.get("wire", {})  # wire specification
+
+# Design requirements used
+dr = mas_obj["inputs"]["designRequirements"]
+mag_ind = dr["magnetizingInductance"]   # {nominal, minimum, maximum}
+turns_ratios = dr["turnsRatios"]        # list of ratios
+
+# Operating points used (with full waveforms)
+ops = mas_obj["inputs"]["operatingPoints"]
+```
+
+---
+
+## 13. Error Handling — DO NOT FALL BACK TO MANUAL MODE
+
+| Error | Cause | Fix |
+|---|---|---|
+| `"Input JSON does not conform to schema!"` (instant) | Used `json.dumps()` on converter or core_mode | Pass Python dict directly — NOT `json.dumps(dict)` |
+| `"Input JSON does not conform to schema!"` (instant) | Wrong `core_mode_json` | Use `"available cores"` (lowercase + space!) |
+| `"Input JSON does not conform to schema!"` (instant) | Missing both `mode` and `currentRippleRatio` | Add either `mode` OR `currentRippleRatio` (mode auto-inferred if ripple set) |
+| `"Input JSON does not conform to schema!"` (instant) | Used `desiredInductance` with Method A | Remove it — base class doesn't accept it |
+| `"ngspice is not available"` | Sandbox restriction | Use Method B with `use_ngspice=False` |
+| `"key 'currentRippleRatio' not found"` | Missing required field | Add to JSON |
+| `"key 'outputVoltage' not found"` | Used plural for Buck/Boost | Use singular: `outputVoltage`, `outputCurrent` |
+| `"key 'outputVoltages' not found"` | Used singular for Flyback/Forward | Use plural: `outputVoltages`, `outputCurrents` |
+| `TypeError: incompatible function arguments` | Wrong keyword names | Use positional args |
+| Empty namespace (0 functions) | Bare `import PyOpenMagnetics` | Use `importlib` (Section 2) |
+| `get_core_shape_names()` TypeError | Missing bool arg | Use `get_core_shape_names(True)` |
+
+### 13.1 Common Wrong Patterns vs Correct Patterns
+
+**❌ WRONG: Using json.dumps()**
+```python
+# This WILL FAIL with "Input JSON does not conform to schema!"
+result = PyOM.design_magnetics_from_converter(
+    "flyback",
+    json.dumps(converter_spec),  # ❌ WRONG - json.dumps() converts dict to string!
+    3
+)
+```
+
+**✅ CORRECT: Pass Python dict directly**
+```python
+# This works - pass the dict directly, no json.dumps()
+result = PyOM.design_magnetics_from_converter(
+    "flyback",
+    converter_spec,  # ✅ CORRECT - Python dict, not string
+    3,
+    "standard cores",
+    True,
+    None
+)
+```
+
+---
+
+**❌ WRONG: Inventing your own JSON structure**
+```python
+# This WILL FAIL - this is NOT the correct schema!
+converter_spec = {
+    "inputs": [{
+        "name": "Primary",
+        "voltage": {"nominal": 310.0}
+    }],
+    "outputs": [{
+        "name": "Secondary",
+        "voltage": 12.0,
+        "current": 2.0
+    }],
+    "switchingFrequency": 100000.0
+}
+```
+
+**✅ CORRECT: Use the exact schema from Section 5.1**
+```python
+# This is the CORRECT Flyback schema for Method A
+flyback = {
+    "currentRippleRatio": 0.4,          # REQUIRED
+    "diodeVoltageDrop": 0.5,            # REQUIRED
+    "efficiency": 0.88,                 # REQUIRED
+    "inputVoltage": {                   # REQUIRED - not "inputs"!
+        "minimum": 185.0,
+        "nominal": 220.0,
+        "maximum": 265.0
+    },
+    "operatingPoints": [{               # REQUIRED - not "outputs"!
+        "ambientTemperature": 25.0,
+        "outputVoltages": [12.0],       # PLURAL - list!
+        "outputCurrents": [2.0],        # PLURAL - list!
+        "switchingFrequency": 100000.0
+    }],
+    "maximumDutyCycle": 0.45
+}
+```
+
+---
+
+**❌ WRONG: Using keyword arguments from .pyi stubs**
+```python
+# This WILL FAIL - .pyi has wrong keyword names!
+result = PyOM.design_magnetics_from_converter(
+    topology="flyback",      # ❌ Wrong keyword
+    converter=flyback,       # ❌ Wrong keyword
+    max_results=3
+)
+```
+
+**✅ CORRECT: Use positional arguments**
+```python
+# Use positional arguments - they always work
+result = PyOM.design_magnetics_from_converter(
+    "flyback",           # topology_name (positional)
+    flyback,             # converter_json (positional)
+    3,                   # max_results (positional)
+    "standard cores",    # core_mode_json (positional)
+    True,                # use_ngspice (positional, ignored internally)
+    None                 # weights_json (positional)
+)
+```
+
+---
+
+**❌ WRONG: Abandoning Method A after schema error**
+```python
+# DON'T DO THIS!
+try:
+    result = PyOM.design_magnetics_from_converter(...)
+except:
+    print("Method A failed, doing manual calculations instead...")
+    # ❌ WRONG - Never fall back to manual calculations!
+    L = V * D / (f * delta_I)  # ❌ NO!
+```
+
+**✅ CORRECT: Fix the JSON and retry**
+```python
+# If you get a schema error, FIX THE JSON, don't abandon Method A
+# Check:
+# 1. Did you use json.dumps()? Remove it.
+# 2. Did you use the correct field names? Check Section 5.
+# 3. Did you use "available cores" (lowercase with space)?
+# 4. Did you include all REQUIRED fields?
+```
+
+---
+
+## 14. Quick-Reference Checklists
+
+### Method A: `design_magnetics_from_converter()`
+
+- [ ] Used `importlib` to load `.so` (NOT bare `import`)
+- [ ] Called `load_databases({})` after loading
+- [ ] Topology is **lowercase** (`"flyback"`, not `"Flyback"`)
+- [ ] `core_mode_json` is `"available cores"` (lowercase + space!)
+- [ ] JSON uses **BASE class** schema (NO `desiredInductance`, NO `desiredTurnsRatios`)
+- [ ] For Flyback: `currentRippleRatio` present (mode is optional, auto-inferred)
+- [ ] For Buck/Boost: `outputVoltage`/`outputCurrent` are **SINGULAR**
+- [ ] For Forward: `switchingFrequency` is **REQUIRED** in operatingPoints
+- [ ] Using **positional arguments** (keyword names in .pyi are wrong)
+- [ ] Passing **Python dicts directly** — NOT `json.dumps()` (causes schema error)
+- [ ] If error → fix JSON and retry, then Method B — NEVER manual calculations
+
+### Method B: `process_converter()` → `calculate_advised_magnetics()`
+
+- [ ] JSON uses **Advanced** schema (WITH `desiredInductance`, `desiredTurnsRatios`)
+- [ ] `use_ngspice=False` if ngspice can't init, `True` otherwise
+- [ ] Pass `processed["designRequirements"]` + `processed["operatingPoints"]` to adviser
+- [ ] Core mode also uses `"available cores"` (same lowercase convention)
+- [ ] Weights use lowercase: `"efficiency"`, `"cost"`, `"dimensions"`
+
+---
+
+## 15. Known Issues & Notes
+
+1. **`use_ngspice` is ignored by `design_magnetics_from_converter`** — `(void)useNgspice;`
+   in source. ngspice is bundled in the wheel. In restricted sandboxes, use Method B.
+
+2. **`.pyi` has wrong keyword names** — use positional args or `topology_name=`,
+   `converter_json=`, `core_mode_json=`, `weights_json=`.
+
+3. **Two different Flyback classes** — `Flyback` (base, Method A) vs
+   `AdvancedFlyback` (Method B). Different JSON schemas. Never mix them.
+
+4. **`get_core_shape_names()`** requires boolean arg: `True`=include toroidal.
+
+5. **Design computation is CPU-intensive** — `"available cores"` searches 1301+
+   shapes (60–180+ sec). Use `"standard cores"` for speed (10–30 sec).
+   **A timeout is NOT a failure — use "standard cores" or increase timeout, do NOT switch to Method B.**
+
+6. **All enum string values are lowercase** — `"available cores"`, `"standard cores"`,
+   `"efficiency"`, `"cost"`, `"dimensions"`, etc. The only exception is
+   `FlybackModes` which uses Title Case: `"Continuous Conduction Mode"`.
+
+7. **`process_converter` returns two keys** — `designRequirements` (with
+   `magnetizingInductance`, `turnsRatios`, `name`, `topology`) and
+   `operatingPoints` (with full excitation waveforms per winding).
+
+8. **Do NOT `json.dumps()` the arguments** — the pybind11 binding accepts Python
+   dicts directly. `json.dumps(converter)` turns the dict into a string, which
+   the C++ JSON parser rejects with a schema error.
+
+9. **NEVER abandon Method A after a schema error** — the error means your JSON
+   is wrong, not that the function is broken. Fix the JSON and retry. Do NOT
+   fall back to `calculate_advised_cores` or manual textbook formulas.