pycycloid

Open-source, physics-based simulation of cycloidal gear drives.

pycycloid models a single-disc pin-cycloidal reducer from first principles — analytical tooth geometry, Hertzian contact mechanics, and rigid-body equilibrium — to predict contact and bending stresses, transmission error and power losses. It is built for engineering analysis, not black-box prediction: every result is traceable to a physical model, and the kinematics emerge from contact equilibrium rather than being prescribed.

Von Mises stress in a single-disc cycloidal drive as it accelerates and then decelerates again. Arrows show the disc–pin contact forces, with the bearing kinematics visualised alongside.

---

What it computes

The tool is built to answer three engineering questions, all with physics-based models:

#	Question	Outputs
Q1	Stress & deformation vs. load	Hertz contact pressures, half-widths, elastic deflections
Q2	Transmission error	TE vs. input angle, ripple, sensitivity to clearance & profile mods
Q3	Efficiency	Contact-friction and SKF bearing losses → η(load, speed)

Installation

Requires Python ≥ 3.10 and the standard scientific stack (numpy, scipy, matplotlib, pyyaml).

git clone <repo-url> pycycloid
cd pycycloid
pip install -e .                 # core library + CLI
pip install -e ".[gui]"          # + the desktop GUI (NiceGUI)
pip install -e ".[fem]"          # + the optional 2-D FE disc model (triangle)
pip install -e ".[dev]"          # + the test suite

Quickstart

There are three ways to use pycycloid, from highest level to lowest.

1 — The GUI (most users start here):

pycycloid gui          # or: python run_gui.py

2 — The command line — one subcommand per study, each driven by a YAML config (run pycycloid --help for all options):

pycycloid geometry   --q-deg 45
pycycloid stress     --torque 100
pycycloid te         --torque 100 --law hertz
pycycloid efficiency --torque 100 --rpm 1500

3 — As a library — the CycloidalReducer façade is the public API:

from cycloidal import CycloidalReducer

reducer = CycloidalReducer.from_yaml("configs/default.yaml")
op  = reducer.operating_point(output_torque=100.0)     # loaded equilibrium (QS2)
te  = reducer.transmission_error(output_torque=100.0)  # TE over a mesh cycle (QS3)
cs  = reducer.contact_stresses(output_torque=100.0)    # Hertz contact pressures
eta = reducer.efficiency(output_torque=100.0, input_rpm=1500.0)

print(te.te_peak_to_peak_arcsec, "arcsec ripple;",
      f"{eta.efficiency * 100:.1f}% efficient")

Short, runnable demonstrations live in examples/. Outputs (figures, animations) are written under outputs/. To change the drive, copy a config in configs/studies/ and edit it — no code changes needed.

Note: the contact-force animation solves a full quasi-static operating point per frame with the Hertz law, so it takes a few minutes. Use the linear contact law or fewer frames for a quick look.

Repository layout

src/cycloidal/        the library
  geometry/           profiles & assembled drive geometry
  kinematics/         rigid-body transforms and ideal motion
  contact/            gap scan, Hertz line contact, pluggable contact laws
  solver/             quasi-static equilibrium (QS1), torque solve (QS2), TE sweep (QS3)
  fem/                optional 2-D FE disc (mesh, elements, modes, modal reduction)
  losses/             contact friction, SKF bearing model, system efficiency
  visualization/      2D rendering, kinematic & contact-force animation, plots
  io/                 YAML config loading (with `extends` deep-merge)
  reducer.py          CycloidalReducer — the high-level public API
  cli/                the `pycycloid` command-line interface
src/cycloidal_gui/    the NiceGUI desktop app
configs/              default.yaml + per-study configs
examples/             short, runnable API demonstrations
tests/                acceptance tests, one suite per milestone
docs/                 mission statement and technical documentation

Design principles

Physics first (kinematics emerge from forces, never imposed except at the driver) · SI units throughout · a clean library with thin CLI/GUI front-ends · staged, acceptance-tested milestones · reproducible studies via YAML · self-contained (only the standard scientific Python stack; the FE mesher is an optional extra).

Project status

An open-source engineering tool for the physics-based simulation of cycloidal gear drives, shared openly by Bart Blockmans under the MIT license. You're free to read, clone, use, and fork it. It is provided as-is and is not maintained as a collaborative project — issues and pull requests aren't actively monitored. See CONTRIBUTING.md for local setup and the design philosophy.

License & citation

MIT — see LICENSE. Copyright © 2026 Bart Blockmans (bart@blockmans.net). If you use pycycloid in your research, please cite it using CITATION.cff.