phase-sweep

Electromagnetic design sweeps: analytical, FEM, and drive models, checked
against measured data. Use them from a Python API, web dashboard, or MCP
server. Covers PMSM and induction machines, and integrates with
motulator and
NGSolve through optional dependencies.

What it does

phase-sweep reads a motor definition from TOML and runs the models that its
inputs support. A motor with geometry can use the analytical and FEM field
solvers; one with only circuit parameters can still produce torque-speed
envelopes, thermal estimates, and motulator drive simulations. The bundled
motors (motors/ plus the validation anchors under data/) cover radial
and axial-flux machines, including SPM, IPM, outrunner, SynRM, Halbach,
and inset-magnet examples. Published and measured data are
included where licensing permits.

Sweeps can run in parallel and store their results in an append-only JSONL
file. A local browser dashboard runs jobs, plots stored results, and compares
them with imported measurements. An AI agent can submit jobs and read results
over MCP, including model caveats about assumptions and
omissions.

Features

Field solvers

• Closed-form air-gap field (Zhu, Howe & Chan 2002), inrunner and outrunner
• NGSolve 2D FEM: slotted or smooth-bore stators, linear or nonlinear iron,
  Maxwell-stress torque
• Cogging torque and demagnetization screening
• Axial flux: quasi-3D layer model and multi-plane 2D FEM
• Harmonic decomposition, with an optional CuPy GPU path

Circuit models

• MTPA, stall torque, torque-speed envelope with field weakening
• S1 thermal-duty screening and Bertotti iron loss
• Induction machines: equivalent circuit, torque-slip with deep-bar and
  saturation tables, IEEE 112 parameter identification, time-harmonic cage FEM

Drive simulation

• motulator current-control transients, single- or two-mass load

Sweeps and validation

• Parallel parameter sweeps into a crash-safe JSONL result store
• Sensitivity analysis and bounded calibration against measurements
• Measured-data import and cross-validation; FEM checked against Zhu, Howe &
  Chan and ElmerFEM
  (validation report)

Dashboard

• Local browser dashboard: queue jobs, watch progress, plot results, edit
  motor configs

Agent access (MCP)

• MCP endpoint on the same server: per-motor model applicability, dry-run
  cost estimates, sweep tables, and results with headline metrics and model
  caveats; the dashboard's Agent tab shows tool calls and jobs

Documentation:
motor TOML format |
agent use (MCP) |
architecture |
validation report |
result-store contract |
glossary |
references

Scope and limitations

The field solvers are two-dimensional. The axial models combine several 2D
planes, while separate offline studies estimate 3D effects.

Saturation enters the PMSM circuit models only through a user-supplied
[flux_map] (consumed by rated_torque, stall_torque, torque_speed,
operating_point, motor_thermal, and drive_sim), and the induction
circuit models only through a user-supplied magnetizing table
([induction] L_m_vs_i); no model predicts a saturated inductance from
geometry. AC winding losses and magnet eddy-current
losses are not implemented.

Install

Requires Python 3.12+.

git clone https://github.com/jonelay/phase-sweep.git
cd phase-sweep

# Full install (all solvers + server + plotting + pytest)
pip install -e ".[all,test]"

# Or core only (circuit-parameter models and result store, no FEM/sim/plots)
pip install -e .

Optional extras:

NGSolve provides Python packages for supported Linux, macOS, and Windows
environments. See the NGSolve installation guide
for current platform details.
The circuit-parameter models and non-FEM CLI paths do not require NGSolve.

Or with uv:

uv venv .venv --python 3.12
uv sync --extra all --extra test

Run the tests:

uv run pytest -m "not fem and not slow"  # core CI lane
uv run pytest                            # all tests available in this environment

Quick start

Compute the torque-speed envelope of the Prius 2004 IPM:

from phasesweep import MODEL_REGISTRY, RunConfig, load_motor

motor = load_motor("motors/prius_2004.toml")
cfg = RunConfig(motor=motor, model="torque_speed")
envelope = MODEL_REGISTRY["torque_speed"].fn(cfg)
print(f"Peak torque: {envelope['tau_curve_peak'][0]:.0f} Nm")
print(f"Peak power:  {envelope['p_max_peak']/1000:.0f} kW")

Both numbers are constant-inductance over-predictions - see the
saturation caveat below.

Compute the air-gap field of a motor with full geometry - analytically,
then with the 2D FEM solver, and compare:

motor = load_motor("motors/belkhadir_outrunner.toml")

cfg = RunConfig(motor=motor, model="analytical", n_theta=720)
metrics = MODEL_REGISTRY["analytical"].fn(cfg)
print(f"Analytical B1: {metrics['fundamental']:.3f} T")
print(f"Back-EMF:      {metrics['backemf_fundamental']:.1f} V")

cfg = RunConfig(motor=motor, model="fem", n_theta=720)
metrics = MODEL_REGISTRY["fem"].fn(cfg)
print(f"FEM B1:        {metrics['fundamental']:.3f} T")

The analytical solver supports surface-mounted magnets with air between the
arcs. Inset rotors, including the bundled CREATOR motor, require the FEM model.

Launch the dashboard (needs the [server] extra):

phasesweep-server         # serves http://127.0.0.1:8000

It reads motors/*.toml and the result store in output/ relative to
the working directory (the shipped motor definitions live in the source
repository, not in the wheel; --motors-dir points elsewhere), queues
solver jobs across worker processes, streams progress over WebSocket,
and plots stored waveforms, harmonics, and envelopes in the browser.
Downstream consumers of the store read rows against
phasesweep.record_schema and the
result-store contract.

The same server exposes an MCP endpoint
at /mcp, so an AI agent can check which models run on a motor, submit
jobs and sweeps, and read results. Each result comes with the model's
headline metrics and units, plus caveats drawn from its own provenance (for
example, a torque envelope computed with constant inductances). Jobs share
the dashboard's worker pool, and the dashboard's Agent tab plots the
designs the agent has explored and shows each tool call live. For Claude
Code:

claude mcp add --transport http phase-sweep http://127.0.0.1:8000/mcp

The server has no authentication; keep it on loopback unless something in
front of it authenticates. Tools, result caveats, cost planning, and limits
are in docs/mcp.md.

CLI tools

Each command supports --help.

Available models

RunConfig(motor=..., model=<key>) dispatches through MODEL_REGISTRY.
Each entry declares what it produces and which motor fields it needs;
a motor missing a required field fails validation before any solve.

Each model's full input and output contract is in MODEL_REGISTRY; the
TOML fields are documented in docs/motor-toml.md.
The fem quick-start call above is a no-load field solve and does not
return loaded torque. See
docs/add-a-radial-pmsm.md for the staged
new-motor workflow.

The registry keys backemf_capture, inductance_test,
resistance_test, torque_test, iron_loss_test, and airgap_flux_test
are imported measurement record types used by phasesweep-import and the
cross-validation comparisons.

Motor definition

Motors are TOML files. Only a pole-pair count is required (name
defaults to the filename stem);
each model declares which further fields it needs, so a circuit-only
motor (no geometry) runs the torque and envelope models, and the field
solvers require geometry. Minimal example:

[motor]
name = "example"
type = "SPMSM"

[circuit]
n_p = 4
R_s = 0.05       # Ohm per phase
L_d = 0.0002     # H
L_q = 0.0002     # H
psi_f = 0.012    # Wb per-phase peak

[drive]
U_DC = 48.0      # V
MAX_I_S = 30.0   # A peak

Sections, fields, units, and defaults are documented in
docs/motor-toml.md. The bundled motors/
files are worked examples with provenance comments. To add a new motor and
evaluate it, follow docs/add-a-radial-pmsm.md
and phasesweep-check-motor.

Verification and validation

Each model builds on a published formulation (references)
and is tested two ways:

• Verification: the solver computes its equations correctly. FEM is
  compared with closed-form solutions and an independent FEM code.
• Validation: the model describes a real machine. Results are compared
  with measured and published data for the reference machines in data/.

Every comparison runs in the test suite. Three examples follow, one of each
kind of result; the validation report covers more
machines, their sources, and what each comparison tests.

Verification: FEM against TEAM 30a, Zhu, Howe & Chan, and ElmerFEM

The time-harmonic FEM solver is verified against
TEAM Problem 30a, the Compumag benchmark
for induction-machine field codes. Torque, phase voltage, and rotor and steel
losses agree with the problem's exact solution within 0.5 %, and the
three-phase results also match the published tables at every tabulated speed.

The magnetostatic FEM solver is verified against the Zhu, Howe & Chan (2002)
closed-form air-gap field across reference inrunner and outrunner
configurations. Acceptance bounds and current results are documented in the
validation report.

Radial and axial FEM results are also cross-checked against
ElmerFEM. Pinned comparison records in
scripts/elmer_radial/ and scripts/elmer_axial/ are exercised by the core
test suite; regenerating them requires a local ElmerSolver.

Validation: back-EMF against the CREATOR benchmark

The CREATOR open-benchmark PMSM
(sintered-ferrite inrunner; Muetze et al., COMPEL 2025) supplies measured
back-EMF data and published circuit parameters. Computed values, references,
tolerances, and errors are reported in the
validation report.

The benchmark supplies ψ_f. The calculated back-EMF fundamental checks the
electrical-speed conversion and E = ω_e·ψ_f, not the field solver's prediction
of ψ_f. The validation report covers the separate MTPA angle, rated torque,
and nonlinear FEM field comparisons.

The measured waveform is trapezoidal, consistent with the nearly rectangular
ferrite magnets and the square-wave magnetization used by both field solvers.
The current comparison covers only the fundamental because the model does not
yet produce a back-EMF waveform.

Known limit: Prius 2004 stall torque

The Prius 2004 case exercises stall torque, MTPA angle, and the
torque-speed envelope for a 50 kW, 8-pole, V-shape NdFeB traction motor.
Circuit parameters come from ORNL teardown and dynamometer reports
(OSTI 885676,
OSTI 890029). It is not a validation
at high current: the constant-inductance model predicts about 905 N·m stall
torque against about 340 N·m measured in ORNL's locked-rotor test at 250 A
(OSTI 921782; +166 %), because L_q
saturates. The test suite pins that prediction as a regression value and
checks the one-sided bound against the measurement;
the MTPA angle is checked against a plausible band, not a measured value.
See docs/validation-report.md for details.

Reference data

The data/prius_2004/ directory contains the
Pyleecan machine-readable IPM
geometry and ORNL dynamometer reference values for the Toyota
Prius 2004 traction motor. See
data/prius_2004/README.md for sources and
declared assumptions.

The data/creator_case_pmsm/ directory documents the reference data from
the CREATOR open-benchmark PMSM (Muetze et al., 2025); the data files
themselves are not redistributed. See
data/creator_case_pmsm/README.md for
attribution and citation information, and License for terms.

Dependencies

Package layout

The package layout and data-flow spine are described in
docs/architecture.md. Alongside the package:
scripts/ (validation and maintenance tools), tests/ (pytest suite with
fem and slow markers), data/ (published, measured, and derived
validation data), and motors/ (motor parameter files).

Contributing

Bug reports, documentation fixes, validation datasets, and motor references
are welcome.
See CONTRIBUTING.md for setup and process.

Questions and discrepancy reports:
GitHub Issues.

Citing

If you use phasesweep in a report or publication:

J. Lay, phasesweep: Electromagnetic design sweeps — analytical, FEM, and
drive models, 2026. https://github.com/jonelay/phase-sweep

License

Code and data are licensed under Apache-2.0, except for the
third-party data files listed below. The data consists of parameter values
transcribed from cited publications or measured by the project authors.
NOTICE credits the sources, and anyone who redistributes
phasesweep must include it (Apache-2.0 §4(d)).

data/creator_case_im/creator_case_im.toml is transcribed and therefore
Apache-2.0.