Skip to content

Anchors should be named after the machine, not numbered (Geometry2) #26

Closed

Description

@smidl

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:

  • Geometry2 cannot 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 are synrm_5f_40s_113t and synrm_5f_60s_113t, but as Geometry2 vs Geometry2 they 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() is pass (motors/motor2.py:23-24), so rotor_r_min/rotor_r_max are never set and no BarrierGenerator can 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions