# observation swim_speed

Describes the entry `swim_speed` at version `0.1.0`, registered by `mime.observations._swim_speed.SwimSpeed`.

## At a glance

- observation `swim_speed`, version `0.1.0`, namespace `mime`
- Nodes: [`SwimSpeedNode`](../../nodes/SwimSpeedNode.md)
- The equations are on the node page: [equations](../../nodes/SwimSpeedNode.md#governing-equations)
- Derivative: `piecewise_jump`
- Validity: none declared

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

### The swim speed of a body

**What it measures.** The body's velocity along a direction, each step, and its mean over every step that ends after a
start time: `SwimSpeed(umr, along=tube.axis)`. It reads the body's twist, adds no edge into the physics, and keeps what it
measures in its own node's state, so a run need keep no history to report it. Its outputs, by name, are `speed` (each
step, a series when the run records it) and, at the end of the run, `mean_speed`, `distance` (the speed's integral over
the counted steps) and `observed` (the time they cover). The setting `after` starts the window; by default it starts
with the run.

A step counts whole once its end lies after `after`. The mean is the distance over the time observed, and is zero until
some time is observed.

**When not to use it.**
- For the speed of a body relative to a moving fluid: it reads the body's velocity in the world, along a fixed
  direction, and nothing about the fluid.
- For a speed along a direction that turns with the body (its own axis as it turns): the direction is a fixed vector in
  the world, as `tube.axis` is.
- For a claim: it is a number the run produced, and what it bounds or estimates is for the experiment to state, from the
  comparison it makes.
- Where the start time falls between two steps and the result must be smooth in it: see the derivative below.

**Its derivative** is piecewise: the window's edge is a switch, and as `after` moves the distance and the time
observed move in jumps of a step. The entry's gradient record declares the switch and the route to its derivative (count
the step in which the start time falls by the part of it that lies after the start, with the speed interpolated between
successive steps), and that the mean has none where observing begins.

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

## Settings

| Setting | Type | Default | Dimension | Role | Default's kind |
|---|---|---|---|---|---|
| `after` | `Annotated[Quantity, Time]` | `{"unit": "s", "value": 0.0}` | time (s) | design | convention |
| `along` | `Annotated[DirectionLike, Direction]` | `{"required": true}` | marked Direction | design | none |
| `body` | `Any` | `null` | none | none declared | none: required |
| `rate` | `Quantity \| None` | `null` | none | numerical | convention |

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:

- `after` (convention): the setting's written default; the window starts at the run's start unless a later start is given
- `rate` (convention): the setting's written default; an observation reads every base step unless the experiment chooses a slower rate

## Roles, reads and deliveries

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

Reads:

| Label | Reads |
|---|---|
| `twist` | body [`body.twist`](../../vocabulary.md#namespace-mime) |

## Nodes it builds

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

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

## Gradient status

The derivative through this entry is `piecewise_jump`: not the exact derivative of what it computes everywhere.

Switches the law evaluates, each declared once by its owner:

| Switch | Indicator | Orders, per output group | Route to exact |
|---|---|---|---|
| `swim.window` | the time at the end of the step less the setting after, s: a step is counted whole once its end lies after it. Reads the settings `after` | `distance` -1 (a jump); `mean_speed` -1 (a jump); `observed` -1 (a jump) | count the step in which the setting after falls by the part of it that lies after it, with the speed interpolated linearly between the speeds read at successive steps (the trapezoid rule): the distance and the time observed are then continuously differentiable in after, and so is the mean wherever some time has been observed |
| `swim.mean` | the time observed less half a timestep, s: the mean is taken once some time is observed. Reads the settings `after` | `mean_speed` -1 (a jump) | none: where observing starts the mean goes from none to the speed, which has no derivative to compute |

## Outputs

What a run's result reads by name, with its units (`result[handle].<output>`). A per-step output is a series, with its time axis, when the run records it (`run(..., record=[handle.<output>])`); an output at the end is reduced by the graph and always there, over its window. A window holds the steps whose end lies after its start and not after its end.

| Output | When | Dimension | Unit | Shape | What it is | Reduced from |
|---|---|---|---|---|---|---|
| `speed` | per step | velocity (m/s) | `m/s` | `()` | the body's velocity along the direction, each step |  |
| `mean_speed` | at the end | velocity (m/s) | `m/s` | `()` | the mean of the speed over the steps that end after the setting after | `speed` by the rule `mean`, over the steps that end after its setting `after` |
| `distance` | at the end | length (m) | `m` | `()` | the distance travelled along the direction over the steps that end after the setting after: the speed's integral over them | `speed` by the rule `integral`, over the steps that end after its setting `after` |
| `observed` | at the end | time (s) | `s` | `()` | the time observed: the length of the steps that end after the setting after | over the steps that end after its setting `after` |

## Validity

none declared

## References

none declared

## Other declarations

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