# dynamics motor

Describes the entry `motor` at version `0.2.0`, registered by `mime.dynamics.apparatus._motor.Motor`.

## At a glance

- dynamics `motor`, version `0.2.0`, namespace `mime`
- Rungs built: [`kinematic`](#rung-kinematic), [`dynamic`](#rung-dynamic)
- Nodes: [`KinematicMotorNode`](../../nodes/KinematicMotorNode.md), [`DynamicMotorNode`](../../nodes/DynamicMotorNode.md)
- The equations are on the node page: [equations](../../nodes/KinematicMotorNode.md#governing-equations), [equations](../../nodes/DynamicMotorNode.md#governing-equations)
- Derivative: `exact`
- Validity: none declared

## What it models, and when not to use it

### A motor, as a chain segment

**What it models.** A rotor turning about an axis relative to its stator, as one segment of an apparatus's chain,
usually mounted on the flange of an arm: `chain={..., "motor": Motor.Kinematic(axis=Z, prescribed="velocity",
initial_angle=rad(start), mount="link_6")}`. Its frames are `base`, the stator, and `rotor`; a magnet on the rotor mounts
on `motor.rotor`. The axis is stated in the motor's own base frame, the frame it mounts on, never in the world, so it
turns with whatever carries it.

The `kinematic` rung prescribes its motion: an angle, or a speed integrated over each step, from its initial angle. It
is an ideal source of that motion.

The `dynamic` rung turns its rotor by a torque, `Motor.Dynamic(axis=Z, inertia=..., damping=..., initial_angle=...)`,
the command `<segment>.torque`, against the rotor's inertia about its axis, its bearing's viscous damping on its speed
relative to its stator, and what the loads on the rotor exert about the axis: an ideal torque source. It is a spinner:
it carries the rotor's absolute spin about its axis, whose rate is the torques about the axis over the inertia, with no
term from how its stator turns, and it reads the pose and angular velocity of the frame it is mounted on, this step's
(the arm steps first), for the rotor's turn on its stator and the bearing's damping. The parts mounted on
`<segment>.rotor` with a mass are its rotor: their moments about the axis add to `inertia`; on a dynamic arm their mass
and mean inertia across the axis are welded on the link the motor is mounted on, and the half difference of their two
moments across the axis turns with the rotor, carried in the arm's mass matrix at each step and felt by the spin as a
torque. It takes loads on its frames, the reaction on a magnet on its rotor among them. Its stator holds the rotor: it
takes the drive's reaction and the bearing's and the loads on the rotor across its axis, and passes them, with the
loads on the stator, to the frame it is mounted on; that segment takes them a step late, what the stator passed over
the step before, where it takes loads: an arm on its dynamic rung. The rotor's gyroscopic torque as the arm turns its
axis is the arm's to apply: the motor hands it the rotor's momentum about its axis, and the arm applies the torque at
its own velocity in a way that does no work at any step size. A rotor whose parts lie off its axis or turn out of it,
beyond rounding, on a dynamic arm needs `top_speed`, the most its spin reaches, to judge whether that is a residue,
which the build report gives.

**When not to use it.**
- The kinematic rung when the motor's own behaviour matters: it has no rotor inertia, no cogging, imbalance or
  thermal term (see MIME-ANO-102, as it applies to a prescribed motion), and the torque that turns its rotor is not
  returned to the link it is mounted on (see MIME-ANO-103). Use the dynamic rung.
- The dynamic rung where the drive's electrical side matters: the torque commanded is the torque on the rotor, with no
  armature, saturation, cogging, imbalance or thermal terms (see MIME-ANO-102).
- The dynamic rung on a dynamic arm for a rotor turned off its axis, or with its centre of mass off it, beyond a
  residue: each is refused, since a spinner holds the rotor's centre of mass on its axis and its inertia along it, and
  their rotating load at the top speed is not carried. A residue (a CAD placement's, its rotating load at most a
  thousandth of the rotor's weight) is accepted and reported. On a kinematic arm each is accepted, and its own spin
  carries none of those terms. A rotor unequal across its axis (A0's magnet, spun about a diameter) is carried, on
  every arm: see MIME-ANO-122.
- The kinematic rung for mass on its rotor on a dynamic arm: its prescribed turn moves that mass by a joint the arm
  does not hold, an articulated payload, and it is refused. The dynamic rung carries it.
- Where its reaction must reach the arm in the same step: it arrives a step late, and its bearing's damping closes a
  loop through the lag, stable while the step times the damping is well below the arm's inertia about the motor's axis
  (see MIME-ANO-103).
- When a prescribed speed must hold its phase over a long run in single precision: the angle is a sum over steps, and
  its rounding grows with it.

**Chains, mounts and armature.** How a segment is placed, what mounts on a frame and where a joint's armature comes from: [the multibody note](../../multibody.md).

**Versions.** `motor` 0.1.0 was its first: the kinematic rung, and then the dynamic rung. `motor`
0.2.0, before any release, carries the dynamic rotor's absolute spin, its parts' inertia,
its inequality across its axis and its gyroscopic torque, and publishes both rungs' frames' angular velocities (the
kinematic rung where something reads them); what the kinematic rung computes is unchanged to the last bit on A0.

## Settings

| Setting | Type | Default | Dimension | Role | Default's kind |
|---|---|---|---|---|---|
| `at` | `Annotated[Quantity \| None, Length]` | `null` | length (m) | physical | convention |
| `axis` | `tuple[float, float, float]` | `{"required": true}` | none | physical | none |
| `damping` | `Annotated[Quantity \| None, ROTATIONAL_DAMPING]` | `null` | rotational damping (N m s) | physical | none |
| `inertia` | `Annotated[Quantity \| None, MOMENT_OF_INERTIA]` | `null` | moment of inertia (kg m²) | physical | none |
| `initial_angle` | `Annotated[Quantity, DIMENSIONLESS]` | `{"required": true}` | dimensionless | design | none |
| `initial_velocity` | `Annotated[Quantity \| None, ANGULAR_VELOCITY]` | `null` | angular velocity (rad/s) | design | convention |
| `mount` | `str \| None` | `null` | none | physical | none |
| `orientation` | `tuple[float, float, float, float] \| None` | `null` | none | physical | convention |
| `prescribed` | `str \| None` | `null` | none | design | none |
| `rate` | `Quantity \| None` | `null` | none | numerical | convention |
| `rung` | `str \| None` | `null` | none | design | none |
| `top_speed` | `Annotated[Quantity \| None, ANGULAR_VELOCITY]` | `null` | angular velocity (rad/s) | design | none |

Each role and default's kind is the entry's `setting_roles` (`mime.registry.SettingRole`); a setting that declares none is required.

Each default is a claim (`mime.registry.DefaultKind`): a determined default is resolved in every profile, a convention taken in every profile, a numerical default taken in exploratory only and stamped pending. Their rules and bases:

- `at` (convention): the setting's written default; a segment sits at the origin of the frame it is placed in unless offset
- `initial_velocity` (convention): the setting's written default; a dynamic motor's rotor starts at rest unless given its rates
- `orientation` (convention): the setting's written default; a segment is not turned from the frame it is placed in unless turned
- `rate` (convention): the setting's written default; a node steps every base step unless the experiment chooses a slower rate

## Roles, reads and deliveries

Publishes:

| Interface | Output |
|---|---|
| [`apparatus.frame_angular_velocities`](../../vocabulary.md#namespace-mime) | `frame_angular_velocities` |
| [`apparatus.frame_poses`](../../vocabulary.md#namespace-mime) | `frame_poses` |

## Rungs

A rung is a section of this page, and the entry's `rung` setting names it; there is no default.

### Rung kinematic

- [`KinematicMotorNode`](../../nodes/KinematicMotorNode.md)

Declared in `builds`; the node walk compares it with what a round-trip case builds.

### Rung dynamic

- [`DynamicMotorNode`](../../nodes/DynamicMotorNode.md)

Declared in `builds`; the node walk compares it with what a round-trip case builds.

## Gradient status

The derivative through this entry is `exact`, the derivative of what it computes.

## Validity

none declared

## References

[@Sola2017]

## Other declarations

| Class variable | Type | Value |
|---|---|---|
| `accepts` | `ClassVar[Mapping[str, Port]]` | `{}` |
| `applies_to` | `ClassVar[frozenset[ThingKind]]` | `["apparatus"]` |
| `flags` | `ClassVar[frozenset[Capability]]` | `["rigid"]` |
| `initial_state` | `ClassVar[Mapping[str, Dimension]]` | `{}` |
| `limits` | `ClassVar[tuple[str, ...]]` | `` too long to show; see `mime registry --json` `` |
| `moving` | `ClassVar[bool]` | `false` |
| `nodes` | `ClassVar[tuple[str, ...]]` | `[""]` |
| `registration_kinds` | `ClassVar[frozenset[str]]` | `[]` |