# interaction magnetic.force

Describes the entry `magnetic.force` at version `0.1.0`, registered by `mime.interactions.magnetic.MagneticForce`.

## At a glance

- interaction `magnetic.force`, 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), [`MagneticForceNode`](../../nodes/MagneticForceNode.md)
- The equations are on the node page: [equations](../../nodes/SourceReactionNode.md#governing-equations), [equations](../../nodes/MagneticForceNode.md#governing-equations)
- Derivative: `exact`
- Validity: 1 declared line

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

### The force of a field's gradient on a magnet

**What it models.** The force on a body's permanent magnetic moment from the gradient of the field it sits in,
`exp.attach(Magnetic.Force(), body=umr, field=rpm.magnetic)`: the force on a point dipole in a current-free field, the
moment turned into the world by the body's orientation, the gradient read at the body's centre of mass. The force acts
where the body's magnet sits, its `magnet_centre`, from its parts or declared, so where that is off the centre of mass
it delivers a torque about it too. A uniform field's gradient is zero, so beside a uniform field it delivers nothing.
The field's torque on the moment is another law, `Magnetic.Torque`; attach both for the whole of a magnet's response.

Its reaction, the equal and opposite force on the magnet that makes the field, along the same line, is delivered to
the frame that magnet is mounted on wherever that frame's segment takes loads: a segment on its dynamic rung, an arm or
a motor's rotor. With `Magnetic.Torque`'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, the equal and opposite force between two point dipoles by a test of its own, and its reaction on the source,
with the torque's, against the force and torque of the body's dipole on the source's.

**When not to use it.**
- Where the gradient varies across the body: it is read at one point, the body's centre of mass.
- Inside a point dipole'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.

**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.force` 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 |
|---|---|
| `gradient` | field [`field.magnetic.gradient`](../../vocabulary.md#namespace-mime) at the points of body [`body.pose`](../../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 |
|---|---|---|
| `magnet_centre` | body | `magnet_centre` |
| `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

- [`MagneticForceNode`](../../nodes/MagneticForceNode.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: publishes [`field.magnetic.gradient`](../../vocabulary.md#namespace-mime) | a permanent moment, a point dipole, in a field's gradient read at the body's centre of mass: valid while the gradient 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 point dipole in a field read at the body's centre of mass: valid while the gradient varies little across the body, and outside a point dipole's near field (MIME-ANO-100); a validity line that checks the distance is a1's

## 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

[@Jackson1998]

## Other declarations

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