Skip to main content

Pole-Craft

PyPI version

Open-source design and simulation tool for quasi-direct-drive (QDD) motors.

Status: early development (version 0.0.2). What 0.0.2 can do: load a motor design file and check it, work out the winding layout and the slice of the motor that repeats, build the cross-section of an outer-rotor surface-magnet motor, mesh it, solve its 2D magnetic field at one rotor position with saturating steel and permanent magnets, report the torque and the flux linked by each phase, and draw the field, from the polecraft mesh and polecraft solve commands or from Python. On the reference motor the solver agrees with FEMM within 0.3 % on torque. What it cannot do yet: it has no real material data, so its steel and magnet are stand-ins and its numbers show how the tool behaves, not how a motor performs. It solves one rotor position only, so there is no cogging torque, back-EMF over a cycle, ripple, losses or efficiency; it is 2D, without end effects; and inner-rotor motors are not supported. The roadmap below shows what comes next.

Mesh of the repeating slice of a 36-slot, 42-pole outer-rotor motor

What it will do

Pole-Craft takes a motor described in a simple design file and tells you how it performs:

  • Builds the motor geometry from parameters (slots, poles, diameters, magnet shape)
  • Runs 2D electromagnetic finite-element analysis
  • Reports torque, cogging, back-EMF, torque constant, losses and efficiency
  • Lets you change magnet grade, steel grade, wire size and turns, and compare the results
  • Sweeps many design variants to find the best one for a target

The first focus is surface-magnet outer-rotor and inner-rotor motors of the kind used in QDD robot actuators.

Why

Commercial motor design tools are expensive, and their free student versions cannot be used for commercial work. Existing open-source tools are general-purpose. Pole-Craft aims to make exploring QDD motor designs fast, scriptable and free for anyone to use.

Install

Needs Python 3.11 or newer.

pip install "polecraft[mesh]"

A plain pip install polecraft has no mesher, because the mesher is Gmsh, which is GPL-licensed and so is kept as an optional extra that Pole-Craft calls but does not include. Without it, design files can still be loaded and checked and their geometry built from Python, and any command that needs a mesh stops with one line giving the install command above.

From version 0.0.2, which has the field solver, a faster solver is optional. To install it as well:

pip install "polecraft[mesh,pardiso]"

This adds pypardiso and with it PARDISO from Intel's MKL, which makes a field solve quicker than the solver that is always there (SciPy's SuperLU): by about a tenth on a small model such as the slice of an example motor, and by a quarter or more on larger ones. MKL is free to use but not open source, which is why it is not installed by default. It exists for Intel and AMD processors on Windows and Linux only: on a Mac, or on an ARM processor, the command above installs everything else and leaves the faster solver out. Installing it does not switch it on: SuperLU stays the default, and PARDISO is used when you ask for it by name, solve(problem, solver="pardiso"). The first solve of a run takes about a third of a second longer while MKL loads, so the gain shows over many solves or on large models. Without it nothing is lost but speed: the timing report of a solve made from Python (Solution.timing_report()) gives the command above; polecraft solve does not print it. If you ask for pardiso by name where it is not installed, a warning says so and the work goes on with SuperLU. To add it to an existing install: pip install "polecraft[pardiso]".

On Linux, Gmsh needs a few system libraries that servers, containers and WSL often lack. If polecraft mesh reports libGLU.so.1: cannot open shared object file (or a similar library name), install them. On Debian or Ubuntu:

sudo apt-get install libglu1-mesa libxcursor1 libxft2 libxinerama1 libxrender1 libgomp1

Try it

Save an example design, for instance qdd_outer_36s42p.yaml, into the folder you are working in. The others are in the designs folder, and a clone of the repository contains them all. Then mesh it and save a picture:

polecraft mesh qdd_outer_36s42p.yaml

This writes qdd_outer_36s42p_mesh.png in the current folder and prints the mesh size and how long each stage took. Only the slice of the motor that repeats is meshed; add --full for the whole machine, -o to choose the output file (.png, .svg or .pdf), and --size 0.5 for a finer mesh.

From version 0.0.2 the field can be solved and drawn as well:

polecraft solve qdd_outer_36s42p.yaml --current 10

This solves the magnetic field at one rotor position with 10 A peak in the phases, prints the torque, the flux linked by each phase and how the solve converged, and writes qdd_outer_36s42p_field.png: flux density as colour, with field lines and the outline of every part over it. The options of polecraft mesh work here too (a mesh too coarse to keep the areas of the design is refused, but a coarser mesh that is accepted can change the torque by several per cent; see the known limits in the changelog), and --advance shifts the current, in electrical degrees.

Flux density and field lines in the repeating slice of the 36-slot, 42-pole motor at 10 A

Real material data is not in the package yet. polecraft solve uses a stand-in steel curve made from a formula and a stand-in magnet (1.2 T unless --remanence says otherwise), and says so in what it prints, so its numbers show how the tool behaves, not how a motor performs. It solves a 2D model with no end effects, at rotor angle 0 only.

The design files are plain YAML, with lengths in millimetres. The dimensions in the examples are placeholders typical of each motor size, not measured or optimised designs. The design-file format may change between 0.0.x versions.

Use from Python

The same steps can be run from a script:

from polecraft import load_design, machine_for
from polecraft.core.mesh import build_mesh
from polecraft.plot import plot_mesh

design = load_design("qdd_outer_36s42p.yaml")
machine = machine_for(design)
print(machine.symmetry())                # the slice that repeats

geometry = machine.build_geometry()      # full=True for the whole machine
mesh = build_mesh(geometry, size=1.0)    # needs Gmsh; smaller size, finer mesh
print(len(mesh.nodes), len(mesh.triangles))

plot_mesh(mesh, geometry, "motor.png")

A longer example that also prints the winding layout is in examples/mesh_a_design.py. The Python interface may change between 0.0.x versions.

Examples

Scripts in the examples folder of the repository, each run with python examples/<name>. They need version 0.0.2 or newer, which has the field solver.

Example What it shows Needs Gmsh
mesh_a_design.py Load a design, print its winding, mesh it, save a picture yes
winding_layouts.py Layout, repeating slice and winding factor for several slot and pole counts no
material_models.py Air, a magnet and saturating steel as the solver sees them; the placeholder steel beside its formula no
solve_a_motor.py Solve the field of a motor; torque, flux linkage, convergence and timing reports yes
torque_against_current.py Torque at several currents, showing the steel saturate yes
slice_against_whole_machine.py The repeating slice gives the whole machine's torque and flux linkage for a fraction of the work yes
picture_of_the_field.py Save a picture of flux density, field lines and region outlines yes
choose_a_solver.py List the sparse solvers on your machine and time each yes
core_with_an_air_gap.py A hand-built saturating core, checked against the magnetic circuit formula no
inductance_of_a_coil.py Inductance of a hand-built coil from its flux linkage, checked against a formula no

The motor examples use a placeholder steel curve and a stand-in magnet, not the grades the design names, so their numbers show how the tool behaves, not how the motor performs.

How the solver is checked

The field solver is checked in two ways. Each part is first tested on a case with a known answer (the field round a wire, a magnetic circuit with an air gap, the inductance of a coil). The whole is then compared with FEMM, an independent 2D field program, on the 36-slot, 42-pole example motor. Pole-Craft writes the FEMM model from the same regions, steel table, magnet and currents that its own solver is given (polecraft.femm), and FEMM's results are stored in tests/data/femm with the script that makes them, so the comparison runs with the tests and needs no FEMM.

Results at one rotor position, Pole-Craft on its default mesh of the repeating slice against FEMM on a fine mesh of the whole machine:

Quantity Pole-Craft FEMM Difference
Torque at 10 A 3.187 N m 3.191 N m 0.1 %
Torque at 40 A (steel saturating) 9.527 N m 9.506 N m 0.2 %
Torque with no current 0.000 N m 0.000 N m none, as the symmetry of that position requires
Flux linked by phase A, no current 10.014 mWb 10.005 mWb 0.1 %
Largest phase flux linkage at 40 A 16.553 mWb 16.603 mWb 0.3 %
Main wave of the air-gap flux density, no current 1.029 T 1.028 T 0.1 %
Main wave of the air-gap flux density, 40 A 0.980 T 0.978 T 0.2 %

Over all three currents the two agree within 0.3 % on torque, on the flux linked by each phase within 0.7 % of the largest phase's, and within 0.3 % on the main wave of the flux density in the air gap. A phase whose linkage is near zero at that position differs by about 3 % of its own small value (3.2 % at 40 A). Making Pole-Craft's mesh twice as fine changes its torque by under 0.2 %, and FEMM's own answer moves by 0.1 % between its normal and its fine mesh.

Time for the same job (mesh the motor and solve the three currents), measured once on one laptop:

Run Nodes Time
Pole-Craft, repeating slice, default mesh 2,480 0.5 s
Pole-Craft, whole machine, mesh four times finer 159,043 43 s
FEMM, whole machine, normal mesh 70,246 112 s
FEMM, whole machine, fine mesh 229,310 943 s

Most of the gain comes from solving only the slice that repeats, on a mesh no finer than the answer needs; on the whole machine with a mesh of similar size Pole-Craft is still several times quicker. FEMM's times include starting the program and drawing the model.

This is a check of the 2D solver only. Both programs use the same placeholder steel curve and stand-in magnet and solve the same 2D model, so it says nothing yet about how close either is to a real motor: end effects, which matter in short, wide motors, and real material data come later. FEMM does far more than this comparison uses, and it remains the reference Pole-Craft is checked against.

Roadmap

  • Parametric geometry and meshing for QDD motors (outer rotor; inner rotor to follow)
  • 2D field solver with saturated steel and permanent magnets (one rotor position)
  • Rotation: cogging torque, back-EMF, torque ripple
  • Material and winding library
  • Losses, torque-speed curve and efficiency map
  • Parallel and GPU-accelerated design sweeps
  • Validation against FEMM and measured motors
  • Gear module for actuator-level results
  • 3D verification

Changes in each release are listed in the changelog.

Built with

Python, Gmsh for meshing, and FEMM as an independent reference for validation.

Development setup and running the tests

Clone the repository, then install it in a virtual environment together with the test tools:

git clone https://github.com/pole-craft/pole-craft.git
cd pole-craft
python -m venv .venv
.venv\Scripts\activate          # Linux/macOS: source .venv/bin/activate
pip install -e ".[dev,mesh]"
pytest

Without the mesh extra everything except meshing works, and the meshing tests are skipped.

Contributing

The project is just starting. Ideas, questions, bug reports and motor data for validation are welcome: please open an issue.

How the package fits together, and how to add a machine type, is described in docs/architecture.md.

License

Apache License 2.0. See LICENSE.

Metadata

Release files for polecraft 0.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for polecraft 0.0.2
File Size Uploaded Provenance Actions
polecraft-0.0.2.tar.gz 814.8 kB With provenance Details for polecraft-0.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for polecraft 0.0.2
File Interpreter ABI Platform Actions
polecraft-0.0.2-py3-none-any.whl Python 3 none any Details for polecraft-0.0.2-py3-none-any.whl

Total release size: 900.5 kB

Release files / polecraft-0.0.2.tar.gz

Download URL polecraft-0.0.2.tar.gz
Size 814.8 kB
Tags Source
SHA-256 checksum
How to use checksums
afec6a6126fda99d3853c85d568ff09ab813faf7759795022a30721a4fda1d0a
BLAKE2b-256 checksum
How to use checksums
9a80351ca2ff31b74ea3f27d0cb7a43235cd69e50de2a0e4afdb660588c9e71d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / polecraft-0.0.2-py3-none-any.whl

Download URL polecraft-0.0.2-py3-none-any.whl
Size 85.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
90d15889fedcbbf8b70339baf55b10954555210ed8f8d9fd35b1488e920e01f6
BLAKE2b-256 checksum
How to use checksums
9758dbdeaac7fe988a1cc289eb471b7e112c491cc368657137c7aeb59b6da12c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for polecraft 0.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for polecraft-0.0.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page