zwl20085/femm-agent-suite

---

Contents: What you can ask · Why this exists · Install · Tool groups · Skills · Video tour · Architecture · Validation · FEMM 5 facts you will hit · Python API · Development · Licence · Acknowledgement

What you can ask

Build a planar C-core actuator with a 1 mm gap, 200 turns at 2 A and a 20 mm stack, solve it, and tell me the gap flux density and the pull force. Check both against hand calculations.

Here is my 12-slot / 4-pole surface-PM motor. Run cogging torque by rotating the rotor and again with the air-gap element, and tell me whether the two agree.

Open-circuit back-EMF at 1000 rpm, Ld and Lq, and the mean torque at iq = 10 A. Is the torque consistent with 3/2 p psi iq?

Sweep a round copper conductor from 1 Hz to 10 kHz and compare R(f) with the Bessel solution. Does the input power match the losses?

This FEMM 4.2 Lua script uses “M-19 Steel” and “NdFeB 32 MGOe”. Run it on FEMM 5, port it to Python, and tell me which materials changed.

The agent uses the MCP tools and the skill family below. Every tool answers with {"ok", "result" | "error": {"message", "hint"}, "session", "seconds"}, errors carry the next action as a hint, and the skills teach the agent to back each number with a health check and an analytic estimate before calling it a result.

Why this exists

FEMM is the finite element program a generation of engineers learned magnetics with. FEMM 5 (femm-qt, by David Meeker) is the first FEMM with cross-platform scripting: a Qt build for Windows, macOS and Linux, a headless engine, and a plain TCP protocol that any language can speak, with MicroPython inside the engine instead of Lua 4.

An agent still cannot just “call FEMM”. It needs:

• validated building blocks: tools that put arguments in the right order for each physics (the 12-argument mi_addboundprop, the frequency that moves position between mi_probdef and ci_probdef), save before analysing, handle stateful selections, and turn every FEMM error into an actionable hint;
• physics checks: energy and coenergy identities, force and torque by two methods, AC power balance, flux conservation, saturation, boundary distance, magnet operating points, plus 25 closed-form estimates to compare against;
• a catalog: all 677 FEMM 5 scripting commands with arguments, return values and code tables, the four material libraries, and a record of FEMM 5 behaviour verified live.

This suite is meant as the golden-standard library a future finite element workflow can build on: an MCP server with 88 tools, a pure-Python engineering layer (health rules, estimates, experiments, file parser), and eleven Claude skills that teach the agent how a FEMM user works and when not to trust a number.

Install

Requirements: FEMM 5.0 (build 06oct2026 or newer), Python 3.10 or newer, and Claude Code or any MCP client. FEMM itself is not bundled.

Windows

git clone https://github.com/Zwl20085/femm-agent-suite
cd femm-agent-suite
.\scripts\install.ps1                       # venv + package, MCP server "femm", the 11 skills
.\scripts\install.ps1 -FemmDir "D:\femm-qt\bin"   # if FEMM is not in a default location

macOS / Linux

git clone https://github.com/Zwl20085/femm-agent-suite
cd femm-agent-suite
./scripts/install.sh                        # same steps
FEMM_DIR=~/.local/opt/femm-qt/bin ./scripts/install.sh

Restart Claude Code and ask: run the FEMM self-test. It solves an axisymmetric thick solenoid and compares the centre field with the closed form (0.7 % on build 06oct2026), and checks materials, units, bulk getters and circuits.

Tool groups

88 tools in 12 groups. One line per tool: .claude/skills/femm/references/tool-map.md.

Anything without a curated tool is one femm_call away; the call is checked against the 677-command catalog first.

Skills

Eleven skills in .claude/skills/. The router femm is the entry point and states the safety rules; each specialised skill has references/ for depth.

Video tour

A 109-second narrated introduction to the suite: the problem, the architecture, an agent building and proving a 12-slot / 4-pole motor, the validation table, the skills and the install.

Architecture

MCP client (Claude Code, ...)
   |  stdio
   v
femm_agent.server  ---- 12 tool groups, 88 tools, envelope {ok, result | error{message, hint}}
   |-- sessions.py      named FEMM engines: port, pid, physics, open document, solved flag, work dir
   |     `-- ipc.py     FemmLink: TCP 127.0.0.1, one MicroPython line per request, reply parsing,
   |                    timeouts, journal of every line sent (no pyFEMM import needed)
   |-- catalog.py       data/commands.json: 677 commands, arguments, returns, code tables
   |-- materials.py     data/materials/*.json + the installed .dat libraries, 4.2 rename map
   |-- experiments.py   force-position, torque-angle, cogging, back-EMF, inductance, AC sweep, parametric
   |-- health.py        pure physics invariants (unit tested)    diagnostics.py  live health check
   |-- estimate.py      25 closed-form references                units.py        conversions
   |-- benchmarks.py    validated models: ccore, coilgun, spm, round_wire
   `-- femfile.py, plotting.py, reporting.py   file parser, field maps, Markdown reports
                         |
                         v  TCP, one engine per session
              femm_headless(w) --port N   or   femm_gui --port N
              (FEMM 5: MicroPython engine, tangle mesher, fkn / belasolv / hsolv / csolv solvers)

Each session spawns its own headless engine on a free port (launch about 0.5 s), so several models can run side by side. Bulk results (whole-mesh nodes, elements, B) are written to .npz/.csv in the work dir and summarised; they never flood the agent’s context.

Validation

Measured live on FEMM 5.0 build 06oct2026 (Windows, headless) by examples/ and tests/live/.

The C-core inductance (7.47 mH vs 4.81 mH from the no-fringing formula) is the reminder that a formula is a reference, not a target: the skills teach the agent to explain the gap, not to tune it away.

FEMM 5 facts you will hit

• Material names changed. M-19 Steel is M-19 14 mil, Pure Iron is ARMCO Pure Iron, 1010 Steel is 1010 Steel (hot rolled), and NdFeB 32 MGOe has no entry (nearest N33). FEMM raises Couldn't load "..." from the materials library; femm_material_search maps the old names.
• Commands exist only with a document. mi_* appears after newdocument(0), mo_* only after a solution is loaded, and mi_analyze refuses an unsaved model.
• One line per request. Multi-line MicroPython goes through exec(open(path).read()); lines over 64 KiB are split by the engine.
• One client per engine, and the engine dies with it. A second connection gets femm-qt is already connected to another client; a headless engine exits within about 0.5 s of its client disconnecting.
• No screenshots headless. mo_savebitmap succeeds but writes nothing without the GUI; the suite renders field maps from the bulk mesh arrays instead.
• The air-gap element needs a `` annulus, the stress-tensor block integral reads about zero across it (use mo_gapintegral), and an unknown boundary name returns zeros, not an error.
• pyFEMM helpers are not engine commands. mo_getb and 61 other conveniences answer name 'mo_getb' isn't defined; use mo_getpointvalues (14 values). Standalone pyFEMM finds the engine only through FEMM_DIR.
• Units. Magnetic current density is in MA/m^2, magnetic conductivity in MS/m, current-flow conductivity in S/m; the post-processor reports depth in metres, the pre-processor in problem units.

All verified behaviour is collected in docs/femm5-facts.md and served to the agent by femm_facts.

Python API

The engineering layer works without an MCP client. From examples/ccore/run_ccore.py:

from pathlib import Path
from femm_agent import benchmarks, diagnostics, experiments, ipc

out = Path("out").resolve()
out.mkdir(exist_ok=True)
link = ipc.launch(port=ipc.pick_free_port(49700), cwd=str(out))   # headless FEMM 5 engine
try:
    model = (out / "ccore.fem").as_posix()
    meta = benchmarks.build_ccore(link, model)                    # validated C-core benchmark
    link.call("mi_analyze", 1)
    link.call("mi_loadsolution")
    x, y = meta["probe_gap_point"]
    print("gap B", abs(link.call("mo_getpointvalues", x, y)[2]), "T",
          "analytic", meta["estimate"]["gap_B_T"])
    hc = diagnostics.run(link, model, force_groups=[1], reaction_groups=[2, 3])
    print(hc["summary"])
    fr = experiments.force_vs_position(link, [1], dy=0.25, steps=9,
                                       out_dir=out / "experiments", restore_path=model)
    print(fr["summary"], fr["files"]["csv"])
finally:
    link.close()                                                   # the engine exits with it

Full examples with reports: examples/ccore/run_ccore.py and examples/spm_motor/run_spm.py (about 130 solves, about 25 s). See examples/README.md.

Development

python -m venv .venv; .venv\Scripts\pip install -e ".[dev]"
.venv\Scripts\python -m pytest            # offline suite: a fake engine, no FEMM needed (runs in CI)
.venv\Scripts\python -m pytest -m live    # live tests against a local FEMM 5
.venv\Scripts\python -m femm_agent        # run the MCP server on stdio

tests/test_tool_names.py fails if this README or any skill names a femm_* tool that is not registered. Repository layout:

Contributions: see CONTRIBUTING.md. Only document behaviour observed on a real FEMM 5, and mark the rest unverified.

Licence

The suite is MIT licensed (LICENSE). FEMM 5 itself is not part of this repository and is not redistributed: the femm-qt application, engine, mesher, bindings and material libraries are MIT, and the finite element solvers (fkn, belasolv, hsolv, csolv) are GPLv3 or later. The suite talks to FEMM over its TCP interface and does not link the solvers. The JSON summaries in data/ are generated from the installed FEMM 5 libraries and keep their MIT licence.

Acknowledgement

FEMM is the work of David Meeker. Thank you for decades of a free, rigorous 2D field solver, and for FEMM 5’s open scripting interface that made this project possible. Get FEMM 5 from femm.info: download page. This project is independent and not affiliated with or endorsed by the FEMM author.