PowerFix

Physics-Guided Iterative Repair for Power Converter Designs

AAAI / IAAI 2027 submission

Quick start · How it works · Run a repair

PowerFix repairs existing flyback converter designs through engineering diagnosis, constrained LLM planning, and numerical validation. It preserves the original topology and design targets, changes only authorized fields, and exports a repaired design only after validation accepts it.

How it works

1. Characterize the reported failure with fresh PLECS measurements.
2. Diagnose likely causes using a fixed engineering graph and numerical evidence.
3. Repair through LLM route selection and constrained candidate generation.
4. Validate an isolated candidate; use failure feedback to replan when needed.

Workflow illustration from the paper. In this release, acceptance exports a new design file; the original input stays unchanged. Click either figure to view it at full resolution.

Quick start

Requires Python 3.12+. Clone this repository, or download and unzip its source:

git clone https://github.com/spongelovesorange/PowerFix.git
cd PowerFix
python3 --version  # Must be 3.12 or newer
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[test]"
powerfix inspect

The bundled example intentionally contains a capacitor fault. Expected output includes:

{
  "status": "inspected",
  "check_count": 28,
  "simulation_executed": false,
  "repair_accepted": false
}

The full output also lists two capacitor/ripple violations. This inspection runs offline after installation; no API key or PLECS is needed. Run the tests with python -m pytest -q.

Installation downloads dependencies from PyPI. On Windows, create the environment with py -3.12 -m venv .venv and activate it with .venv\Scripts\Activate.ps1 in PowerShell; the remaining offline commands are the same. Full repair requires macOS/Linux.

Run a repair

Start your licensed PLECS Standalone, enable its XML-RPC service, and leave it running. You also need an OpenAI-compatible chat-completions service that accepts seed and temperature.

cp .env.example .env

Fill in the blank settings in .env:

Setting	What to provide
POWERFIX_LLM_BASE_URL	Your provider's API base address, without /chat/completions
POWERFIX_LLM_MODEL	Your provider's model ID
OPENAI_API_KEY	Your API key
POWERFIX_PLECS_EXECUTABLE	Your PLECS executable
POWERFIX_PLECS_RPC_URL	The XML-RPC address configured in PLECS

Then run the bundled example:

powerfix repair --output runs/example

Missing settings fail before any simulation or API call. The default allows one initial attempt and up to three replans; API calls may incur provider charges. Use a new output directory for every run.

Output	Meaning
result.json	Final outcome and repair attempts
accepted_design_state.yaml	Repaired design, exported only after acceptance
error.json	Runtime failure details after output initialization

Acceptance is not guaranteed. The original input is preserved throughout the run.

Use your own design

cp examples/flyback.yaml my-design.yaml
# Edit my-design.yaml, then:
powerfix inspect my-design.yaml
powerfix repair my-design.yaml --output runs/my-design

Use the example's flyback schema and components from the bundled catalog. Keep issue.task_id equal to design.design_id, and update issue.observed_failures to match the design. See powerfix --help for more options; all commands also work with python -m powerfix.

Why repair an existing design?

An illustrative example from the paper. The MOSFET overvoltage example shown here is different from the capacitor-fault input shipped in examples/flyback.yaml.

Repository guide

src/powerfix/    Core implementation; start with repair.py
configs/        Diagnostic graph, repair policies, frozen component facts
examples/       One input YAML and its PLECS model files
tests/          Core invariants and repair workflow tests
assets/         Two paper illustrations used in this README

Follow the method through repair.py → characterization.py → diagnosis.py → planner.py → candidates.py → validation.py. configs/graph.yaml holds the diagnostic graph; configs/repair.yaml holds operating conditions, candidate ranges, edit contracts, and validation policies.

This repository provides the core method and a runnable example. Experiment suites are maintained separately. Tests substitute external interfaces; the local PLECS example has also been checked across eight operating points. Component facts retain their source references and hashes. Historical identifiers such as .powerpr and benchmark_research remain for compatibility.

Research software: the existing proprietary research-software designation and original PE-MAS model usage terms apply. Validation does not imply production approval.