PyOpenMagnetics - Python Wrapper for OpenMagnetics

🤖 For AI Assistants: If you're an AI assistant helping with this library, please read AGENTS.md FIRST before continuing with this README. It contains essential information about:

• Correct import procedures (this package requires special handling)
• ⚠️ Using API methods instead of manual calculations (CRITICAL)
• Required field specifications for converter topologies
• Troubleshooting common API errors
• Complete working examples

⚠️ AVOID MANUAL MODE: Always use process_flyback(), calculate_advised_magnetics(), and other API methods rather than doing manual calculations. The MKF engine handles complex magnetic effects that manual calculations cannot.

PyOpenMagnetics is a Python wrapper for MKF (Magnetics Knowledge Foundation), the simulation engine of OpenMagnetics, providing a comprehensive toolkit for designing and analyzing magnetic components such as transformers and inductors.

Features

• 🧲 Core Database: Access to extensive database of core shapes, materials, and manufacturers
• 🔌 Winding Design: Automatic winding calculations with support for various wire types (round, litz, rectangular, planar)
• 📊 Loss Calculations: Core losses (Steinmetz), winding losses (DC, skin effect, proximity effect)
• 🎯 Design Adviser: Automated recommendations for optimal magnetic designs
• 📈 Signal Processing: Harmonic analysis, waveform processing
• 🖼️ Visualization: SVG plotting of cores, windings, magnetic fields
• 🔧 SPICE Export: Export magnetic components as SPICE subcircuits

Installation

From PyPI (recommended)

pip install PyOpenMagnetics

From Source

git clone https://github.com/OpenMagnetics/PyOpenMagnetics.git
cd PyOpenMagnetics
pip install .

Build provenance

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:

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:

rm -rf build && pip install . --no-deps -v

Importing and error 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:

import PyOpenMagnetics

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}")

The only exception is the plotting family, which returns a discriminated union {"success": bool, "error": str, ...} that callers branch on.

See AGENTS.md for more usage guidance.

Quick Start

Basic Example: Creating a Core

import PyOpenMagnetics

# Find a core shape by name
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. "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
        "numberStacks": 1
    }
}

# Calculate complete core data
core = PyOpenMagnetics.calculate_core_data(core_data, False)
print(f"Effective area: {core['processedDescription']['effectiveParameters']['effectiveArea']} m²")

Design Adviser: Get Magnetic Recommendations

import PyOpenMagnetics

# Define design requirements
inputs = {
    "designRequirements": {
        "magnetizingInductance": {
            "minimum": 100e-6,  # 100 µH minimum
            "nominal": 110e-6   # 110 µH nominal
        },
        "turnsRatios": [{"nominal": 5.0}]  # 5:1 turns ratio
    },
    "operatingPoints": [
        {
            "name": "Nominal",
            "conditions": {"ambientTemperature": 25},
            "excitationsPerWinding": [
                {
                    "name": "Primary",
                    "frequency": 100000,  # 100 kHz
                    "current": {
                        "waveform": {
                            "data": [0, 1.0, 0],
                            "time": [0, 5e-6, 10e-6]
                        }
                    },
                    "voltage": {
                        "waveform": {
                            "data": [50, 50, -50, -50],
                            "time": [0, 5e-6, 5e-6, 10e-6]
                        }
                    }
                }
            ]
        }
    ]
}

# Process inputs (adds harmonics and validation)
processed_inputs = PyOpenMagnetics.process_inputs(inputs)

# Get magnetic recommendations
# core_mode: "available cores" (stock cores) or "standard cores" (all standard shapes)
result = PyOpenMagnetics.calculate_advised_magnetics(processed_inputs, 5, "standard cores")

# Result format: {"data": [{"mas": {...}, "scoring": float, "scoringPerFilter": {...}}, ...]}
for i, item in enumerate(result["data"]):
    mag = item["mas"]["magnetic"]
    core = mag["core"]["functionalDescription"]
    print(f"{i+1}. {core['shape']['name']} - {core['material']['name']} (score: {item['scoring']:.3f})")

Calculate Core Losses

import PyOpenMagnetics

# 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)

# 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")

Winding a Coil

import PyOpenMagnetics

# core from calculate_core_data(...) as above
bobbin = PyOpenMagnetics.create_basic_bobbin(core, True)

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")

Converter-Based Design

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:

import PyOpenMagnetics

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
    }]
}

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

Core Calculations

Winding Functions

Design Adviser

Visualization

Settings

SPICE Export

Converter Topologies

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. 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.

<t> ∈ flyback, buck, boost, single_switch_forward, two_switch_forward, active_clamp_forward, push_pull, isolated_buck, isolated_buck_boost, cuk, sepic, zeta, four_switch_buck_boost, weinberg, llc, cllc, clllc, src, dab, psfb, pshb, ahb, vienna. PFC is basic-only (calculate_pfc_inputs, generate_pfc_ngspice_circuit(json, dc_resistance=0.1, simulation_time=0.02, time_step=1e-8)); common-/differential-mode chokes use the cmc / dmc families. See AGENTS.md §11 for the full per-topology parity matrix.

Core Materials

PyOpenMagnetics includes materials from major manufacturers:

• TDK/EPCOS: N27, N49, N87, N95, N97, etc.
• Ferroxcube: 3C90, 3C94, 3C95, 3F3, 3F4, etc.
• Fair-Rite: Various ferrite materials
• Magnetics Inc.: Powder cores (MPP, High Flux, Kool Mu)
• Micrometals: Iron powder cores

Core Shapes

Supported shape families include:

• E cores: E, EI, EFD, EQ, ER
• ETD/EC cores: ETD, EC
• PQ/PM cores: PQ, PM
• RM cores: RM, RM/ILP
• Toroidal: Various sizes
• Pot cores: P, PT
• U/UI cores: U, UI, UR
• Planar: E-LP, EQ-LP, etc.

Wire Types

• Round enamelled wire: Various AWG and IEC sizes
• Litz wire: Multiple strand configurations
• Rectangular wire: For high-current applications
• Foil: For planar magnetics
• Planar PCB: For integrated designs

Configuration

Use set_settings() to configure:

settings = PyOpenMagnetics.get_settings()
settings["coilAllowMarginTape"] = True
settings["coilWindEvenIfNotFit"] = False
settings["painterNumberPointsX"] = 50
PyOpenMagnetics.set_settings(settings)

Contributing

Contributions are welcome! Please see the OpenMagnetics organization for contribution guidelines.

Documentation

Quick Start

• llms.txt - Comprehensive API reference optimized for AI assistants and quick lookup
• examples/ - Practical example scripts for common design workflows
• PyOpenMagnetics.pyi - Type stubs for IDE autocompletion

Tutorials

• notebooks/ - Interactive Jupyter notebook tutorials with visualizations
  • Getting Started - Introduction to PyOpenMagnetics
  • Buck Inductor - Complete inductor design workflow
  • Core Losses - In-depth core loss analysis

Reference

• docs/errors.md - Common errors and solutions
• docs/performance.md - Performance optimization guide
• docs/compatibility.md - Python/platform version compatibility

Validation

• api/validation.py - Runtime JSON schema validation for inputs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• MKF - C++ magnetics library
• MAS - Magnetic Agnostic Structure schema
• OpenMagnetics Web - Online design tool

References

• Maniktala, S. "Switching Power Supplies A-Z", 2nd Edition
• Basso, C. "Switch-Mode Power Supplies", 2nd Edition
• McLyman, C. "Transformer and Inductor Design Handbook"

Support

For questions and support:

• 🐛 GitHub Issues
• 💬 Discussions
• 📧 Contact the maintainers