# field provider point_dipole

Describes the entry `point_dipole` at version `0.1.0`, registered by `mime.fields._point_dipole.PointDipole`.

## At a glance

- field provider `point_dipole`, version `0.1.0`, namespace `mime`
- Nodes: [`PointDipoleNode`](../../nodes/PointDipoleNode.md)
- The equations are on the node page: [equations](../../nodes/PointDipoleNode.md#governing-equations)
- Derivative: `exact`
- Validity: 1 declared line

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

### The field of a permanent magnet, as a point dipole

**What it models.** The magnetic field of a magnet part, and its gradient, at each reader's point, as the field of a
point dipole at the magnet's centroid: `fields={"magnetic": PointDipole(part="rotor_magnet")}`. The part is a
part of the apparatus with the `PermanentMagnet` role; its moment is the apparatus's `magnetic_moment`, declared as a
magnitude along the direction the role gives in the part's frame. The magnet sits where its mount puts it, so it
follows the chain that carries it, with no edge written by hand. The gradient is computed from its closed form, and is
the field's derivative.

**When not to use it.**
- Near the magnet. A point dipole is faithful only far from it, measured against the magnet's radius, the radius of
  the smallest sphere about its centroid that holds it, which the provider's node holds; closer, a finite magnet's
  field differs by more (see MIME-ANO-100). No finite-magnet model is built.
- At the magnet itself, where the field is singular: it is evaluated outside the magnet only, and a body that starts
  inside the smallest sphere that holds the magnet is refused at build. The validity line that checks the distance
  against the magnet's radius is a1's.
- For a magnet whose magnetisation is not rigid and uniform along one direction.

**Versions.** `point_dipole` 0.1.0 is its first.

## Settings

| Setting | Type | Default | Dimension | Role | Default's kind |
|---|---|---|---|---|---|
| `part` | `str` | `{"required": true}` | none | physical | none |

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

## Roles, reads and deliveries

Reads values of the things it is bound to:

| Label | Role | Value |
|---|---|---|
| `moment` | its own thing | `magnetic_moment` |

Publishes:

| Interface | Output |
|---|---|
| [`field.magnetic.flux_density`](../../vocabulary.md#namespace-mime) | `flux_density` |
| [`field.magnetic.gradient`](../../vocabulary.md#namespace-mime) | `gradient` |

## Nodes it builds

- [`PointDipoleNode`](../../nodes/PointDipoleNode.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

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

- evaluated outside the magnet: the field is singular at its centroid, and a point dipole is faithful only far from the magnet, against its radius (MIME-ANO-100); a validity line that checks the distance is a1's

## References

[@Jackson1998]

## Other declarations

| Class variable | Type | Value |
|---|---|---|
| `commands` | `ClassVar[Mapping[str, Command]]` | `{}` |
| `flags` | `ClassVar[frozenset[Capability]]` | `["provision=evaluated"]` |
| `moving` | `ClassVar[bool]` | `false` |
| `outside_parts` | `ClassVar[bool]` | `true` |
| `parts` | `ClassVar[Mapping[str, str \| None]]` | `{"part": "permanent_magnet"}` |
| `turns_at` | `ClassVar[str \| None]` | `null` |