Introduction

Note: As of Spring 2026, the stem framework and its documentation are under active development. Hence, this book will be expanded substantially over time.

stem is a Simulation Toolbox for Electric Motors written in Rust, consisting of multiple crates (packages / libraries) for defining electric motors, calculation of their properties and simulation of their operating behaviour. This framework offers a huge variety of features, such as:

• calculate winding factors, resistance, inductance, wire length etc. of arbitrary windings,
• get the leakage inductances for a wide variety of slot geometries,
• draw the components for visual inspection (see above),
• define custom magnetic simulation models or use predefined ones to determine the torque of a motor,
• simulate the S1 torque characteristic of a motor using coupled magnetic / thermal models,
• predict the start-up behaviour (maximum currents and torque) of an asynchronous motor starting at the power grid with different loads,
• serialize and deserialize motor components, simulation models or even complex workflows like S1 torque characteristc calculation using serde,
• create interactive GUIs for winding analysis,
• … and many more!

The individual crates of the ecosystem are designed to be modular and extensible. This makes it easy to define your own custom motor components (e.g. custom magnets), magnetic / thermal models or even optimization routines.

This book is a tutorial / manual for stem, showcasing how to use it, its general design philosophy, its components and how to extend it. The API documentation of the individual crates can be found on https://docs.rs/. Where appropriate, this book provides links to them. The book assumes knowledge of Rust and yaml.

As of now, all the features hinted at above exist, but most of the ecosystem is not yet uploaded to crates.io due to a lack of documentation (and in practice, software without good documentation is hardly usable). Over the following months, I strive to fix this one crate at a time and to upload them individually to Github and crates.io.

TODO: stem only for radial flux machines

License

Every crate in the framework as well as this book itself is licensed under the MIT license.

Ecosystem overview

Crates belonging to the ecosystem are prefixed with “stem_” and can be sorted into three different layers:

• The “description layer” offers the fundamental building blocks for defining a motor: Its components, its geometry, its materials, its winding design and so on.
• The “model layer” is centered around the stem_physical_model crate which defines interfaces (traits) for magnetic and thermal models. All other crates within this layer are based on it and describe a particular magnetic or thermal model.
• Crates within the “application layer” either provide complex routines for e.g. the calculation of operational behaviour combining magnetic and thermal models or form fully self-contained applications such as the stem_winding_gui for interactive evaluation of winding properties.

Crates belonging to stem

TODO: List the crates here over time

Description layer

• stem_material: This is the most foundational crate of stem, because it enables the definition of physical material properties specifically for electromagnetic (and thermal) calculations.
• stem_magnet: Provides an interface for defining (surface) permanent magnets which can be mounted in the air gap.
• stem_magnetic_core: TODO
• stem_motor: TODO
• stem_slot: TODO
• stem_winding: TODO
• stem_wire: Provides an interface for defining electrical wires for the coils of windings.

Model layer

Application layer

Crates related to stem

The following list of crates has been created as enablers for stem, but are not part of the ecosystem and can be meaningfully used outside of it. Types of these crates are often used in the API of “stem_” crates:

• akima_spline: Akima spline interpolation with smooth polynomial extrapolation, used for fitting ferromagnetic permeability curves.
• deserialize_untagged_verbose_error: Deserialization of untagged enums with detailed error messages. Oftentimes, motor components can be equivalently represented in different ways (for example, an arc magnet can be defined by its inner and outer radius or by its inner radius and thickness). Since the default untagged deserialization mechanism in serde does not create helpful error messages, this crate is used throughout stem instead.
• dyn_quantity: Whenever possible, stem uses the uom crate for zero-cost dimensional analysis. Sometimes however, the units are not known until runtime. The dyn_quantity crate fills that gap and provides seamless transformation from and to uom types.
• planar_geo: 2D geometry and drawing library. It is used to calculate geometric properties of motor components, perform intersection checks during the assembly of a motor and for drawing.
• serde_mosaic: Provides a mechanism to define “links” between serialized components. This is useful to e.g. reuse the contents of a file containing the definition of a copper material across multiple serialized motors.
• var_quantity: Defines quantites whose value depends on that of other quantities - an example would be the specific electric resistivity of a material which depends on the material temperature. This crate serves as the base of stem_material.