PyOpenMagnetics 1.6.6__tar.gz → 1.7.0__tar.gz

{pyopenmagnetics-1.6.6 → pyopenmagnetics-1.7.0}/AGENTS.md

@@ -112,20 +112,9 @@ The package has **no `__init__.py`**. A bare `import PyOpenMagnetics` gives an
 **empty namespace with 0 functions**. You MUST use `importlib`:
 
 ```python
-import importlib.util, os, glob
+import PyOpenMagnetics as PyOM
 
-pkg_dir = os.path.join(
-    os.path.dirname(__import__('PyOpenMagnetics').__path__[0]),
-    'PyOpenMagnetics'
-)
-so_files = glob.glob(os.path.join(pkg_dir, 'PyOpenMagnetics.cpython-*'))
-assert so_files, f"No .so/.pyd found in {pkg_dir}"
-
-spec = importlib.util.spec_from_file_location('PyOpenMagnetics', so_files[0])
-PyOM = importlib.util.module_from_spec(spec)
-spec.loader.exec_module(PyOM)
-
-# MANDATORY — must call before any other function
+# MANDATORY - must call before any other function
 PyOM.load_databases({})
 ```
 
@@ -404,17 +393,7 @@ Lm ≈ 800 µH                → for desiredInductance (Method B onl
 ### Method A: `design_magnetics_from_converter()` (single call)
 
 ```python
-import importlib.util, os, glob, json
-
-# Load module
-pkg_dir = os.path.join(
-    os.path.dirname(__import__('PyOpenMagnetics').__path__[0]),
-    'PyOpenMagnetics'
-)
-so_files = glob.glob(os.path.join(pkg_dir, 'PyOpenMagnetics.cpython-*'))
-spec = importlib.util.spec_from_file_location('PyOpenMagnetics', so_files[0])
-PyOM = importlib.util.module_from_spec(spec)
-spec.loader.exec_module(PyOM)
+import PyOpenMagnetics as PyOM
 PyOM.load_databases({})
 
 # Define converter (BASE Flyback schema — NO desiredInductance!)
@@ -433,23 +412,16 @@ flyback = {
     }]
 }
 
-# Design (takes 60-120s with "available cores")
-result = PyOM.design_magnetics_from_converter(
-    "flyback", flyback, 1, "available cores", True, None
-)
-
-if isinstance(result, dict) and "error" in result:
-    print(f"Method A failed: {result['error']}")
-    # → Use Method B
+# 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:
-    d = result[0]
-    mas_obj, score = (d[0], d[1]) if isinstance(d, (list, tuple)) else (d, "N/A")
-    core = mas_obj["magnetic"]["core"]["functionalDescription"]
-    coil = mas_obj["magnetic"]["coil"]["functionalDescription"]
-    print(f"Core:  {core['shape'].get('name','?') if isinstance(core['shape'], dict) else core['shape']}")
-    print(f"Material: {core['material'].get('name','?') if isinstance(core['material'], dict) else core['material']}")
-    for w in coil:
-        print(f"  {w.get('name','?')}: {w.get('numberTurns','?')} turns")
+    print(f"Turns ratios: {inputs['designRequirements']['turnsRatios']}")
+    print(f"Operating points: {len(inputs['operatingPoints'])}")
 ```
 
 ### Method B: `process_converter()` → `calculate_advised_magnetics()` (no ngspice needed)
@@ -473,21 +445,21 @@ flyback_adv = {
     }]
 }
 processed = PyOM.process_converter("flyback", flyback_adv, use_ngspice=False)
-assert "error" not in processed
+# 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"]
 }
-designs = PyOM.calculate_advised_magnetics(
-    mas_inputs, 1, "available cores",
-    {"efficiency": 2.0, "cost": 1.0, "dimensions": 0.5}  # optional weights
-)
-
-# Step 3: Parse
-d = designs[0]
-mas_obj, score = (d[0], d[1]) if isinstance(d, (list, tuple)) else (d, "N/A")
+# 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','?')}")
@@ -570,7 +542,7 @@ wire       = PyOM.find_wire_by_name("Round 0.5 - Grade 1")  # ✅ verified (
 
 ### Bobbins
 ```python
-bobbin = PyOM.find_bobbin_by_name("E 25/13/7")    # ✅ verified (.pyi confirmed)
+bobbin = PyOM.find_bobbin_by_name("Bobbin E25/7")    # ✅ verified (.pyi confirmed)
 ```
 
 ### ❌ Wrong names — do NOT use these
@@ -588,7 +560,8 @@ PyOM.get_core_shape_families(True)    # TypeError — takes no arguments
 
 ### Inductance Calculation
 ```python
-inductance = PyOM.calculate_inductance(magnetic)
+inductance = PyOM.calculate_inductance_from_number_turns_and_gapping(
+    core, coil, operating_point, models)
 # Returns dict with:
 #   magnetizingInductance → {magnetizingInductance, coreReluctance, gappingReluctance, ...}
 ```
@@ -611,11 +584,18 @@ sim_result = PyOM.simulate(mas)
 
 ### Wire Utilities
 ```python
-# Skin depth at frequency
-delta = PyOM.calculate_effective_skin_depth("copper", 100000, 25)
+# 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
-rdc = PyOM.calculate_dc_resistance_per_meter("copper", 0.5e-3, 25)
+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

{pyopenmagnetics-1.6.6 → pyopenmagnetics-1.7.0}/CMakeLists.txt

@@ -142,7 +142,7 @@ if(NOT LOCAL_MKF_MAS)
     set(MKF_GIT_TAG "main"
         CACHE STRING "MKF git ref for the vendored PyOM build")
     # Force fresh clone by using a unique timestamp - update this when the pin changes
-    set(MKF_FORCE_REFRESH "2026-08-05-v1.6.4-mkf-dragback-adviser-thermal")
+    set(MKF_FORCE_REFRESH "2026-08-10-v1.7.0-mkf-d9293885")
     # Tell MKF to disable matplotplusplus and use SVG-based Painter instead
     set(INCLUDE_PYMKF ON CACHE BOOL "Build Python interface" FORCE)
     # GIT_SUBMODULES_RECURSE pulls in CAS/PEAS (added 2026-04 alongside the
@@ -166,7 +166,7 @@ if(NOT LOCAL_MKF_MAS)
     # Skip Git LFS to avoid bandwidth quota issues - data files are optional for build
     set(ENV{GIT_LFS_SKIP_SMUDGE} "1")
     # Force fresh clone by using a unique timestamp - update this when MAS changes
-    set(MAS_FORCE_REFRESH "2025-02-26-01")
+    set(MAS_FORCE_REFRESH "2026-08-10-v1.7.0-mas-f736d41")
     FetchContent_Declare(
            mas
            GIT_REPOSITORY https://github.com/OpenMagnetics/MAS.git
@@ -180,10 +180,14 @@ if(NOT LOCAL_MKF_MAS)
     message(STATUS "MAS_POPULATED: ${MAS_POPULATED}")
     message(STATUS "MKF_POPULATED: ${MKF_POPULATED}")
 
-    # Always delete and repopulate MAS to ensure we get the latest
+    # Always delete and repopulate MAS to ensure we get the latest. The subbuild
+    # dir must go too: its stamp files survive the source deletion and make the
+    # next populate run a git "update" step inside the freshly-emptied mas-src,
+    # which fails with "fatal: not a git repository".
     if(EXISTS ${CMAKE_BINARY_DIR}/_deps/mas-src)
         message(STATUS "Removing old MAS source to force fresh clone")
         file(REMOVE_RECURSE ${CMAKE_BINARY_DIR}/_deps/mas-src)
+        file(REMOVE_RECURSE ${CMAKE_BINARY_DIR}/_deps/mas-subbuild)
     endif()
     message(STATUS "Populating MAS")
     FetchContent_Populate(mas)
@@ -198,6 +202,12 @@ if(NOT LOCAL_MKF_MAS)
     if(MAS_GIT_ERROR)
         message(STATUS "MAS git error: ${MAS_GIT_ERROR}")
     endif()
+    # Resolve the MAS commit for the wheel's _build_info.py (ABT #601).
+    execute_process(
+        COMMAND git -C ${mas_SOURCE_DIR} rev-parse HEAD
+        OUTPUT_VARIABLE MAS_GIT_HEAD
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
 
     # Always delete and repopulate MKF so the checkout matches ${MKF_GIT_TAG}
     # exactly, mirroring the MAS refresh above. FetchContent will NOT re-checkout
@@ -208,6 +218,8 @@ if(NOT LOCAL_MKF_MAS)
     if(EXISTS ${CMAKE_BINARY_DIR}/_deps/mkf-src)
         message(STATUS "Removing old MKF source to force fresh checkout at ${MKF_GIT_TAG}")
         file(REMOVE_RECURSE ${CMAKE_BINARY_DIR}/_deps/mkf-src)
+        # Same stamp-staleness hazard as the MAS subbuild above.
+        file(REMOVE_RECURSE ${CMAKE_BINARY_DIR}/_deps/mkf-subbuild)
     endif()
     message(STATUS "Populating MKF")
     FetchContent_Populate(MKF)
@@ -238,7 +250,31 @@ if(NOT LOCAL_MKF_MAS)
 else()
     message(STATUS "Using local MKF at ${MKF_DIR}")
     message(STATUS "Using local MAS at ${MAS_DIR}")
+    # Local-checkout builds still record their engine commits (ABT #601).
+    execute_process(
+        COMMAND git -C ${MKF_DIR} rev-parse HEAD
+        OUTPUT_VARIABLE MKF_GIT_HEAD
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
+    execute_process(
+        COMMAND git -C ${MAS_DIR} rev-parse HEAD
+        OUTPUT_VARIABLE MAS_GIT_HEAD
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+    )
+endif()
+
+# ABT #601: bake the resolved MKF/MAS commits into the package so a wheel is
+# self-describing (PyOpenMagnetics.__mkf_commit__ / __mas_commit__). Before this,
+# MKF_GIT_HEAD was only message(STATUS)-ed to the CMake log and provenance could
+# not be recovered from an install. Fail loudly rather than shipping a wheel with
+# unknown provenance.
+if(NOT MKF_GIT_HEAD OR NOT MAS_GIT_HEAD)
+    message(FATAL_ERROR
+        "Could not resolve MKF/MAS commits for _build_info.py "
+        "(MKF_GIT_HEAD='${MKF_GIT_HEAD}', MAS_GIT_HEAD='${MAS_GIT_HEAD}'). "
+        "The MKF/MAS source dirs must be git checkouts (ABT #601).")
 endif()
+configure_file(_packaging/_build_info.py.in "${CMAKE_BINARY_DIR}/_build_info.py" @ONLY)
 
 message(STATUS "Compiling MAS")
 
@@ -570,8 +606,15 @@ install(TARGETS PyOpenMagnetics LIBRARY DESTINATION .)
 
 # Install the package __init__.py so `import PyOpenMagnetics` exposes the
 # compiled extension's API. Without it the wheel installs as an empty PEP-420
-# namespace package and `PyOpenMagnetics.<fn>` resolves to nothing.
-install(FILES __init__.py DESTINATION .)
+# namespace package and `PyOpenMagnetics.<fn>` resolves to nothing. It lives in
+# _packaging/ (not the repo root) so the repo checkout cannot shadow the installed
+# package when pytest runs from the repo root (ABT #597). The leading underscore
+# matters: a directory literally named "packaging" shadows the REAL `packaging`
+# PyPI library that build backends and pytest import, breaking `python -m build`
+# and pytest with "No module named packaging.PyOpenMagnetics".
+install(FILES _packaging/__init__.py DESTINATION .)
+# Engine-commit provenance, configured above from the resolved MKF/MAS heads.
+install(FILES "${CMAKE_BINARY_DIR}/_build_info.py" DESTINATION .)
 
 # Install documentation files for AI assistants
 install(FILES AGENTS.md llms.txt PyOpenMagnetics.pyi DESTINATION .)

{pyopenmagnetics-1.6.6 → pyopenmagnetics-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: PyOpenMagnetics
-Version: 1.6.6
+Version: 1.7.0
 Summary: Python wrapper for OpenMagnetics
 Author-Email: Alfonso Martinez <Alfonso_VII@hotmail.com>
 Classifier: Development Status :: 4 - Beta
@@ -57,51 +57,48 @@ cd PyOpenMagnetics
 pip install .
 ```
 
-#### MKF is pinned to a SHA (build reproducibility — ABT #73)
+#### Build provenance
 
-This build compiles MKF by **globbing its `.cpp` files directly** into the
-extension (it does not drive MKF's own CMake). MKF `main` has since moved to
-"delete `converter_models` + link the Kirchhoff converter-model library
-(`libKirchhoffApi.so`)"; because Kirchhoff and its AAS sibling are **not yet
-published**, a from-scratch build of newer `main` cannot obtain that library
-and **fails to link**.
+The build compiles MKF by **globbing its `.cpp` files directly** into the
+extension, tracking MKF/MAS `main`, and builds the Kirchhoff converter-model
+library (`libKirchhoffApi.so`) as an ExternalProject. The exact engine commits a
+wheel was compiled from are baked into the package:
 
-`CMakeLists.txt` therefore pins the MKF FetchContent to the last self-contained
-commit — `MKF_GIT_TAG=2ae859dcae6c3b2e5a128893247b7714360e863f`, the exact SHA
-the shipping `.so` was built from — and a configure-time guard fails loudly if
-the checkout drifts. A clean rebuild is reproducible as-is:
+```python
+import PyOpenMagnetics
+print(PyOpenMagnetics.__mkf_commit__)  # MKF SHA this wheel was built from
+print(PyOpenMagnetics.__mas_commit__)  # MAS SHA this wheel was built from
+```
+
+A clean rebuild:
 
 ```bash
-rm -rf build && pip install . --no-deps -v        # or: cmake -S . -B build && ninja -C build
+rm -rf build && pip install . --no-deps -v
 ```
 
-To **advance** the pin you must first wire the Kirchhoff library build into
-`CMakeLists.txt` (publish AAS/Kirchhoff, then `add_subdirectory` +
-`target_link_libraries(... libKirchhoffApi.so)`). Overriding
-`-DMKF_GIT_TAG=main` before that lands will break the link.
-
-### ⚠️ Import Instructions
+### Importing and error handling
 
-**Important:** The compiled extension module may require special import handling:
+`import PyOpenMagnetics` works like any other package. Since v1.7.0 every engine
+failure raises **`PyOpenMagnetics.EngineError`** (a `RuntimeError` subclass) —
+functions never return error strings or `{"data": "<error>"}` objects:
 
 ```python
-import importlib.util
-
-# Option 1: Direct loading (recommended)
-so_path = '/path/to/PyOpenMagnetics.cpython-311-x86_64-linux-gnu.so'
-spec = importlib.util.spec_from_file_location('PyOpenMagnetics', so_path)
-PyOpenMagnetics = importlib.util.module_from_spec(spec)
-spec.loader.exec_module(PyOpenMagnetics)
-
-# Option 2: Create __init__.py (see AGENTS.md for details)
+import PyOpenMagnetics
 
-# Verify installation
 PyOpenMagnetics.load_databases({})
 print(f"✓ Loaded {len(PyOpenMagnetics.get_core_materials())} materials")
 print(f"✓ Loaded {len(PyOpenMagnetics.get_core_shapes())} shapes")
+
+try:
+    PyOpenMagnetics.find_core_shape_by_name("No Such Shape")
+except PyOpenMagnetics.EngineError as e:
+    print(f"Engine error: {e}")
 ```
 
-See [AGENTS.md](AGENTS.md) for complete import instructions and troubleshooting.
+The only exception is the plotting family, which returns a discriminated union
+`{"success": bool, "error": str, ...}` that callers branch on.
+
+See [AGENTS.md](AGENTS.md) for more usage guidance.
 
 ## Quick Start
 
@@ -116,9 +113,11 @@ shape = PyOpenMagnetics.find_core_shape_by_name("E 42/21/15")
 # Find a core material by name
 material = PyOpenMagnetics.find_core_material_by_name("3C95")
 
-# Create a core with gapping
+# Create a core with gapping. "type" is mandatory; shape/material accept
+# either the objects fetched above or plain name strings.
 core_data = {
     "functionalDescription": {
+        "type": "two-piece set",
         "shape": shape,
         "material": material,
         "gapping": [{"type": "subtractive", "length": 0.001}],  # 1mm gap
@@ -190,25 +189,50 @@ for i, item in enumerate(result["data"]):
 ```python
 import PyOpenMagnetics
 
-# Define core and operating point
-core_data = {...}  # Your core definition
-operating_point = {
-    "name": "Nominal",
-    "conditions": {"ambientTemperature": 25},
-    "excitationsPerWinding": [
-        {
-            "frequency": 100000,
-            "magneticFluxDensity": {
-                "processed": {
-                    "peakToPeak": 0.2,  # 200 mT peak-to-peak
-                    "offset": 0
-                }
-            }
-        }
-    ]
-}
+# A complete core (see "Creating a Core" above)
+core = PyOpenMagnetics.calculate_core_data({
+    "functionalDescription": {
+        "type": "two-piece set",
+        "shape": "E 42/21/15",
+        "material": "3C95",
+        "gapping": [{"type": "subtractive", "length": 0.0005}],
+        "numberStacks": 1
+    }
+}, True)
 
-losses = PyOpenMagnetics.calculate_core_losses(core_data, operating_point, "IGSE")
+# A wound coil on that core
+bobbin = PyOpenMagnetics.create_basic_bobbin(core, True)
+coil = PyOpenMagnetics.wind({
+    "bobbin": bobbin,
+    "functionalDescription": [{
+        "name": "Primary",
+        "numberTurns": 20,
+        "numberParallels": 1,
+        "isolationSide": "primary",
+        "wire": "Round 0.5 - Grade 1"
+    }]
+}, 1, [1.0], [0], [])
+
+# Inputs with the excitation waveforms (see the Design Adviser example)
+inputs = PyOpenMagnetics.process_inputs({
+    "designRequirements": {
+        "magnetizingInductance": {"nominal": 100e-6},
+        "turnsRatios": []
+    },
+    "operatingPoints": [{
+        "name": "Nominal",
+        "conditions": {"ambientTemperature": 25},
+        "excitationsPerWinding": [{
+            "name": "Primary",
+            "frequency": 100000,
+            "current": {"waveform": {"data": [-1, 1, -1], "time": [0, 5e-6, 10e-6]}},
+            "voltage": {"waveform": {"data": [50, 50, -50, -50], "time": [0, 5e-6, 5e-6, 10e-6]}}
+        }]
+    }]
+})
+
+models = {"coreLosses": "IGSE", "reluctance": "ZHANG"}
+losses = PyOpenMagnetics.calculate_core_losses(core, coil, inputs, models)
 print(f"Core losses: {losses['coreLosses']} W")
 ```
 
@@ -217,61 +241,66 @@ print(f"Core losses: {losses['coreLosses']} W")
 ```python
 import PyOpenMagnetics
 
-# Define coil requirements
-coil_functional_description = [
-    {
-        "name": "Primary",
-        "numberTurns": 50,
-        "numberParallels": 1,
-        "wire": "Round 0.5 - Grade 1"
-    },
-    {
-        "name": "Secondary",
-        "numberTurns": 10,
-        "numberParallels": 3,
-        "wire": "Round 1.0 - Grade 1"
-    }
-]
+# core from calculate_core_data(...) as above
+bobbin = PyOpenMagnetics.create_basic_bobbin(core, True)
 
-# Wind the coil on the core
-result = PyOpenMagnetics.wind(core_data, coil_functional_description, bobbin_data, [1, 1], [])
-print(f"Winding successful: {result.get('windingResult', 'unknown')}")
+coil_spec = {
+    "bobbin": bobbin,
+    "functionalDescription": [
+        {
+            "name": "Primary",
+            "numberTurns": 50,
+            "numberParallels": 1,
+            "isolationSide": "primary",
+            "wire": "Round 0.5 - Grade 1"
+        },
+        {
+            "name": "Secondary",
+            "numberTurns": 10,
+            "numberParallels": 3,
+            "isolationSide": "secondary",
+            "wire": "Round 1.00 - Grade 1"
+        }
+    ]
+}
+
+# wind(coil, repetitions, proportion_per_winding, pattern, margin_pairs)
+coil = PyOpenMagnetics.wind(coil_spec, 1, [0.5, 0.5], [0, 1], [])
+print(f"Wound {len(coil['turnsDescription'])} turns")
 ```
 
-## Flyback Converter Wizard
+## Converter-Based Design
 
-PyOpenMagnetics includes a complete flyback converter design wizard. See `flyback.py` for a full example:
+The converter surface builds complete MAS Inputs straight from converter
+specifications (the Kirchhoff topology designer sizes inductance, turns ratios
+and waveforms). See `examples/converter_design_example.py` for the full flow:
 
 ```python
-from flyback import design_flyback, create_mas_inputs, get_advised_magnetics
-
-# Define flyback specifications
-specs = {
-    "input_voltage_min": 90,
-    "input_voltage_max": 375,
-    "outputs": [{"voltage": 12, "current": 2, "diode_drop": 0.5}],
-    "switching_frequency": 100000,
-    "max_duty_cycle": 0.45,
-    "efficiency": 0.85,
-    "current_ripple_ratio": 0.4,
-    "force_dcm": False,
-    "safety_margin": 0.85,
-    "ambient_temperature": 40,
-    "max_drain_source_voltage": None,
-}
-
-# Calculate magnetic requirements
-design = design_flyback(specs)
-print(f"Required inductance: {design['min_inductance']*1e6:.1f} µH")
-print(f"Turns ratio: {design['turns_ratios'][0]:.2f}")
+import PyOpenMagnetics
 
-# Create inputs for PyOpenMagnetics
-inputs = create_mas_inputs(specs, design)
+flyback_specs = {
+    "inputVoltage": {"minimum": 185, "maximum": 265},
+    "desiredInductance": 800e-6,      # optional pin; omit to let Kirchhoff size it
+    "desiredTurnsRatios": [13.5],     # optional pin
+    "efficiency": 0.88,
+    "operatingPoints": [{
+        "outputVoltages": [12.0],
+        "outputCurrents": [2.0],
+        "switchingFrequency": 100000,
+        "ambientTemperature": 40
+    }]
+}
 
-# Get recommended magnetics
-magnetics = get_advised_magnetics(inputs, max_results=5)
+inputs = PyOpenMagnetics.process_converter("flyback", flyback_specs)
+processed = PyOpenMagnetics.process_inputs(inputs)
+result = PyOpenMagnetics.calculate_advised_magnetics(processed, 5, "standard cores")
+for item in result["data"]:
+    print(item["mas"]["magnetic"]["manufacturerInfo"]["reference"], item["scoring"])
 ```
 
+A TAS-shaped spec (an object with `designRequirements` / `operatingPoints[].outputs`)
+is also accepted and passed to Kirchhoff untouched.
+
 ## API Reference
 
 ### Database Access
@@ -293,13 +322,13 @@ magnetics = get_advised_magnetics(inputs, max_results=5)
 | `calculate_core_data(core, process)` | Calculate complete core data |
 | `calculate_core_gapping(core, gapping)` | Calculate gapping configuration |
 | `calculate_inductance_from_number_turns_and_gapping(...)` | Calculate inductance |
-| `calculate_core_losses(core, operating_point, model)` | Calculate core losses |
+| `calculate_core_losses(core, coil, inputs, models)` | Calculate core losses |
 
 ### Winding Functions
 
 | Function | Description |
 |----------|-------------|
-| `wind(core, coil, bobbin, pattern, layers)` | Wind coils on a core |
+| `wind(coil, repetitions, proportions, pattern, margins)` | Wind coils on a core |
 | `calculate_winding_losses(...)` | Calculate total winding losses |
 | `calculate_ohmic_losses(...)` | Calculate DC losses |
 | `calculate_skin_effect_losses(...)` | Calculate skin effect losses |
@@ -341,7 +370,13 @@ magnetics = get_advised_magnetics(inputs, max_results=5)
 
 All 24 power topologies are exposed with a uniform API. Use the generic
 `process_converter("<topology>", converter, use_ngspice)` (also accepts
-`"advanced_<topology>"`), or the per-topology functions below.
+`"advanced_<topology>"`), or the per-topology functions below. The converter
+spec is either the legacy flat shape shown in "Converter-Based Design" above
+(`inputVoltage`, optional `desiredInductance`/`desiredTurnsRatios`/`efficiency`/
+`currentRippleRatio`, and `operatingPoints[]` with `outputVoltages[]`/
+`outputCurrents[]`/`switchingFrequency`/`ambientTemperature`) or a TAS-shaped
+spec, which is passed through untouched. Failures raise
+`PyOpenMagnetics.EngineError`.
 
 | Function family | Description |
 |----------|-------------|

{pyopenmagnetics-1.6.6 → pyopenmagnetics-1.7.0}/PyOpenMagnetics.pyi

@@ -84,6 +84,14 @@ by reading AGENTS.md before starting.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 """
 
+class EngineError(RuntimeError):
+    """Raised by every engine failure (v1.7.0+): C++ exceptions surface as this."""
+    ...
+
+__mkf_commit__: str
+__mas_commit__: str
+
+
 from typing import Dict, List, Any, Optional, Union, Literal, overload
 
 # Type aliases for JSON-like structures