# interaction gravity

Describes the entry `gravity` at version `0.1.0`, registered by `mime.interactions.gravity.Gravity`.

## At a glance

- interaction `gravity`, version `0.1.0`, namespace `mime`
- Family: [`gravity`](../../families/gravity.md), with 1 member, none of them with rungs
- Nodes: [`GravityNode`](../../nodes/GravityNode.md)
- The equations are on the node page: [equations](../../nodes/GravityNode.md#governing-equations)
- Derivative: `exact`
- Validity: none declared

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

### Weight and buoyancy

**What it models.** The weight of a body less the weight of the fluid it displaces, as one wrench about the body's centre of
mass: `exp.attach(Gravity(), body=umr, medium=water)`. The weight acts at the centre of mass and the buoyancy at the body's
centre of buoyancy, so where a body declares that point off its centre of mass the law also delivers the couple the
buoyancy makes about it, and reads the body's pose to turn the offset into the world; it reads the pose only then. The
body's mass and buoyant volume, the medium's density and the experiment's gravity vector are its inputs, and they are
parameters of the graph, so a study can move them.

It is a member of the gravity family.

**When not to use it.**
- With a medium that moves and carries its own hydrostatic load: the medium here is at rest, and with a flow that
  counts the hydrostatic pressure the buoyancy would be counted twice. No such flow is built yet.
- For a body whose displaced volume changes, or that floats at a surface: the buoyant volume is a constant of the body,
  and the fluid's density is uniform.
- For anything but weight and buoyancy: it is not the drag, the contact or any hydrodynamic load on the body.

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

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

## 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), `medium` (medium).

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 |
|---|---|---|
| `buoyant_volume` | body | `buoyant_volume` |
| `centre_of_buoyancy` | body | `centre_of_buoyancy` |
| `fluid_density` | medium | `density` |
| `mass` | body | `mass` |

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

- [`GravityNode`](../../nodes/GravityNode.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) | a rigid body in a medium at rest |

## Gradient status

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

## Validity

none declared

## Family

Declared: [`gravity`](../../families/gravity.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

[@TatumClassicalMechanics]

## Other declarations

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