Repository navigation
Anchors should be named after the machine, not numbered (Geometry2) #26
Description
Short summary
Geometry2 / Computation2 in motors/motor2.py are named for being the second machine defined, not for the machine they describe. Nothing in the name says 5-phase, 40-slot, 113-turn.
Long description
CONTRIBUTING.md on main tells you to "pick an anchor", "derive it from an existing anchor" and use a method "on any anchor" (lines 61, 63, 65) — but never defines what an anchor is. The defining section still exists on the contributing branch:
## Anchor designs — named, frozen, derived not forked
An anchor is a named, version-controlled machine definition — everything needed to instantiate and solve one physical machine:
class, slots, phases, winding (turns, Rs), end-winding Lew, rotor radii, geometry generator + parameter bounds, FEA template
…named<class>_<phases>f_<slots>s_<turns>t, e.g.synrm_5f_60s_113t
It was dropped in the #23 rewrite. The substitution was left unfinished — line 63 currently reads "add an motors (PR to main)", i.e. the string "anchor" was replaced by "motors" in the layout language but the word stayed in the checklists. So the convention that machines are named was lost by accident, not decided against.
What the anonymous naming costs in practice:
Geometry2cannot be told apart from the other 5-phase variants in flight. A 5-phase 60-slot/113-turn SynRM is being run on a research branch; under the documented scheme those aresynrm_5f_40s_113tandsynrm_5f_60s_113t, but asGeometry2vsGeometry2they are indistinguishable — which is exactly the divergence CONTRIBUTING exists to prevent.- The dropped definition requires an anchor to declare its rotor radii.
Geometry2.set_derived_params()ispass(motors/motor2.py:23-24), sorotor_r_min/rotor_r_maxare never set and noBarrierGeneratorcan be constructed against it — the 5-phase machine cannot have a rotor built for it at all. That went unnoticed for four months partly because no stated contract said the class owed anyone those values. Filed separately; this issue is the naming and the contract.
Proposal
One module per anchor in motors/, named <class>_<phases>f_<slots>s_<turns>t, each exporting plain Geometry/Computation so the module name carries the identity and class names stay uniform. Old paths kept as deprecation shims so branches migrate on their own schedule. Restore the anchor definition to CONTRIBUTING and fix the "add an motors" sentence.
Open question worth settling in review: the scheme puts turns in the name (113t), but turns are sometimes a free design variable. Naming by slots/phases only would be more stable.
Estimated time investment
1 hour (branch ready)
Activity