Skip to main content

Pole-Craft

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

Status: early development (version 0.0.1). Pole-Craft loads a motor design file and checks it, works out the winding layout and the slice of the motor that repeats, builds the cross-section of an outer-rotor motor as labelled regions (steel, coils, magnets, air), meshes it with triangles and saves a picture with the polecraft mesh command. It does not simulate anything yet: there is no field solver, so it reports no torque, back-EMF or losses. 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]"

The mesh extra installs Gmsh, which does the meshing. Gmsh is licensed under the GPL, so it is kept optional: Pole-Craft does not include any Gmsh code and only calls it if you install it. Plain pip install polecraft gives everything except meshing.

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.

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.

Roadmap

  • Parametric geometry and meshing for QDD motors (outer rotor; inner rotor to follow)
  • 2D field solver with saturated steel and permanent magnets
  • 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.

License

Apache License 2.0. See LICENSE.

Metadata

Release files for polecraft 0.0.1

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.1
File Size Uploaded Provenance Actions
polecraft-0.0.1.tar.gz 78.5 kB With provenance Details for polecraft-0.0.1.tar.gz

Built distribution (wheel)

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

Total release size: 120.9 kB

Release files / polecraft-0.0.1.tar.gz

Download URL polecraft-0.0.1.tar.gz
Size 78.5 kB
Tags Source
SHA-256 checksum
How to use checksums
9953b8bc9731c26d4874374391765b8783a558f57cfaf3f1f58d8efe551f3692
BLAKE2b-256 checksum
How to use checksums
860a19c71b69aa49d183f3ff90a02e241a6a9a0ab71e9e2904907c9c5ca6c1cd
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 16, 2026.

Transparency log

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

Download URL polecraft-0.0.1-py3-none-any.whl
Size 42.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
43d2e33ea141242c3b362aeab5aad5ae5611bde9340f313df44c2c493898042b
BLAKE2b-256 checksum
How to use checksums
0cb0a62710f0cc182d5d557ef9eab866dff26558cd14c1690022182ce16cfbe1
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 16, 2026.

Transparency log

Security for polecraft 0.0.1

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.1.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 16, 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.1 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