# interaction magnetic.torque

Describes the entry `magnetic.torque` at version `0.1.0`, registered by `mime.interactions.magnetic.MagneticTorque`.

## At a glance

- interaction `magnetic.torque`, version `0.1.0`, namespace `mime`
- Family: [`magnetic`](../../families/magnetic.md), with 2 members, none of them with rungs; not compared, they are not alternatives
- Nodes: [`SourceReactionNode`](../../nodes/SourceReactionNode.md), [`MagneticTorqueNode`](../../nodes/MagneticTorqueNode.md)
- The equations are on the node page: [equations](../../nodes/SourceReactionNode.md#governing-equations), [equations](../../nodes/MagneticTorqueNode.md#governing-equations)
- Derivative: `exact`
- Validity: 1 declared line

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

### The torque of a field on a magnet

**What it models.** The torque of the field bound to `field` on the body's permanent magnetic moment, about the
centre of mass: `exp.attach(Magnetic.Torque(), body=umr, field=rpm.magnetic)`. The moment is the body's
`magnetic_moment`, in the body's frame, turned into the world by the body's orientation; the torque is its cross product
with the flux density. It delivers no force: the pull of a field's gradient on the moment is another law, `Magnetic.Force`,
and the two are attached together for the whole of a magnet's response. A field that varies in space is read at the body's
centre of mass, and a uniform field is read as it always was, with no points.

It reads the body's pose at the start of the step, as every law reads its body's state, so the torque of a step turns
the body as it stood after the step before: a lag of one step in phase at a rotating field's rate. Its reaction, the
opposite torque on the field's source, is delivered to the frame that source is mounted on wherever that frame's
segment takes loads: a segment on its dynamic rung. With `Magnetic.Force`'s reaction beside it, that is the whole of
what the body's moment exerts on a point dipole source. A source fixed in the world, or carried by a kinematic segment,
takes none.

It is a member of the magnetic family: its sign, frame, units, closed form and gradients are checked by the family's
suite, and its reaction against the force and torque of the body's dipole on the source's. It is a complementary
delivery to `Magnetic.Force`, not an alternative to it.

**When not to use it.**
- Where the field varies across the body: it is read at one point, the body's centre of mass.
- Inside a point dipole source's near field, where the source's own model fails before this law does (see MIME-ANO-100).
- When the reaction on a source carried by a kinematic segment matters: a prescribed motion takes no load, so the
  reaction is delivered only where the source's segment is on its dynamic rung (see MIME-ANO-103).
- For an induced moment, which depends on the field: the moment here is permanent.
- When the lag of one step matters: it is a phase lag of the field's rate times the timestep, so it grows with both.

**Where its values come from.** A declaration, a record or the body's parts, and what "declared" means: [the materials note](../../materials.md).

**Versions.** `magnetic.torque` 0.1.0 is its first; it delivers its reaction on a source mounted
on a segment that takes loads, which no earlier experiment had, so what it computes elsewhere is unchanged.

## Settings

none: the entry takes no setting, so its `setting_roles` declares none.

## Roles, reads and deliveries

Roles, bound by keyword when the entry is attached: `body` (body), `field` (field).

Reads:

| Label | Reads |
|---|---|
| `flux_density` | field [`field.magnetic.flux_density`](../../vocabulary.md#namespace-mime) |
| `pose` | body [`body.pose`](../../vocabulary.md#namespace-mime) |

Delivers:

| Label | Role | Into the target |
|---|---|---|
| `wrench` | body | [`body.applied_wrench`](../../mechanisms/load.md) |

Reads values of the things it is bound to:

| Label | Role | Value |
|---|---|---|
| `moment` | body | `magnetic_moment` |

Reads, values and deliveries that its `plan` adds for a particular construction are not in these tables: they list what the class declares, and `plan` is code the build runs when the entry is attached.

## Nodes it builds

- [`MagneticTorqueNode`](../../nodes/MagneticTorqueNode.md)
- [`SourceReactionNode`](../../nodes/SourceReactionNode.md)

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

Supported constructions, by what each bound thing's dynamics or field provider must offer:

| Requires | Note |
|---|---|
| body: flag rigid, accepts [`body.applied_wrench`](../../mechanisms/load.md), publishes [`body.pose`](../../vocabulary.md#namespace-mime); field: flag uniform, publishes [`field.magnetic.flux_density`](../../vocabulary.md#namespace-mime) | a permanent moment in a uniform field |
| body: flag rigid, accepts [`body.applied_wrench`](../../mechanisms/load.md), publishes [`body.pose`](../../vocabulary.md#namespace-mime); field: flag provision=evaluated, publishes [`field.magnetic.flux_density`](../../vocabulary.md#namespace-mime) | a permanent moment in a field that varies in space, read at the body's centre of mass: valid while the field varies little across the body, and outside a point dipole's near field (MIME-ANO-100) |

## Gradient status

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

## Validity

Declared validity lines: free text, not parsed, and not yet checked against the operating point or the region each one describes.

- a permanent moment in a field that varies in space, read at the body's centre of mass: valid while the field varies little across the body, and outside a point dipole's near field (MIME-ANO-100)

## Family

Declared: [`magnetic`](../../families/magnetic.md). The family's conformance suite is run by a test of the lab or of MIME; which test, and in which lane, is resolved when the evidence resolver lands.

## References

[@Ling2016UniversityPhysics2]

## Other declarations

| Class variable | Type | Value |
|---|---|---|
| `holds_off` | `ClassVar[str \| None]` | `null` |
| `id_roles` | `ClassVar[tuple[str, ...] \| None]` | `null` |
| `moving` | `ClassVar[bool]` | `false` |