# geometry tube

Describes the entry `tube` at version `0.1.0`, registered by `mime.scene._geometry.Tube`.

## At a glance

- geometry `tube`, version `0.1.0`, namespace `mime`
- Derivative: `piecewise_jump`
- Validity: none declared

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

### `tube`

A straight tube as a structure: a wall of thickness `wall` around a circular lumen of radius `inner_radius`, `length`
long, along `axis` through `centre`. It is what a body is confined in and what a medium fills; it is not a solid body, and
it gives no samples, volume or inertia. It names two regions, the `lumen` and the `wall`, but only the `lumen` has a shape: a law reads
the `lumen` as a region (an unbounded cylinder), and the `wall` is a name that the stage draws as an annulus: it has no
shape for a law to read (`region_shapes` holds none for it). Its `inner_surface` faces the lumen.

What a consumer reads of it, by what it is for:
- **A contact** bounds a body against the `inner_surface`, which is evaluated as an **unbounded** cylinder: the body is
  bounded radially, and the tube's ends bound nothing. A body past an end is outside the tube, which nothing checks yet.
- **A medium** filling the `lumen` sees a uniform tube along its axis with no ends: the lumen is that cylinder's inside.
- **A reach** along a direction is the finite tube's, from its centre, and across the axis it is the outer radius (the
  `inner_radius` plus the `wall`), not the lumen's.
- **The hydrodynamic wall** is a different entry: the [tube wall kind](../wall_kind/tube.md) is the wall's effect on the
  flow, read from a table of the unit tube's image system, and it reads the tube's centre, axis and radius from this
  structure. This page is the structure, not the wall's flow.

**When not to use it.**
- For a body: a tube has no mass properties and gives no samples.
- For a tube with ends, a bend or a varying radius: it is straight, of one radius, and its ends bound nothing.

**Its derivative** is the cylinder's: a kink in the distance and a jump in the normal on the axis. Within a band about
the axis, `AXIS_ULPS` units in the last place of the inner radius, the normal is zero with the derivative of the
offset from the axis, the projection across it; a standing test holds that Jacobian, and within the band the status
promises nothing.

**Regions, surfaces, directions and frames.** What a kind names and how a law or a stage reads it: [the scene note](../../scene.md).

**Versions.** 0.1.0 is its first.

## Settings

| Setting | Type | Default | Dimension | Role | Default's kind |
|---|---|---|---|---|---|
| `axis` | `Annotated[DirectionLike, Direction]` | `{"required": true}` | marked Direction | physical | none |
| `centre` | `Annotated[Quantity, Length]` | `{"unit": "m", "value": [0.0, 0.0, 0.0]}` | length (m) | physical | convention |
| `inner_radius` | `Annotated[Quantity, Length]` | `{"required": true}` | length (m) | physical | none |
| `length` | `Annotated[Quantity, Length]` | `{"required": true}` | length (m) | physical | none |
| `wall` | `Annotated[Quantity, Length]` | `{"required": true}` | length (m) | physical | none |

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:

- `centre` (convention): the setting's written default; a tube is centred on the world's origin unless placed

## Capabilities

Generated from which of the optional methods of `mime.registry.Geometry` the kind implements; a consumer that needs one it lacks is refused when it plans, naming both.

| Capability | What it gives | Used by | This kind |
|---|---|---|---|
| `samples` | surface samples by named patch, at a resolution the consumer chooses | the MRS; immersed-boundary markers | no |
| `area` | the area of each patch | the samples' weights | no |
| `mass_properties` | volume and inertia at a density | the part resolver | no |
| `radial_reach` | the hull's radial reach about its axis | a body's extent; contact on the hull | no |
| `family_parameters` | the parameters of the family it is | a surrogate trained on one family | no |
| `tangent` | a tangent it declares at a surface point | a law anisotropic along it | no |
| `native` | its native form, one of USD's own primitives | the stage writer | no |
| `drawing` | a drawing, tessellated at the writer's resolution | the stage writer, for a kind with no native form | yes |
| `region_primitive` | its regions as OpenMaterica's primitives: exactly, or (a region with no end along an axis) clipped at the kind's own length, or refused | OpenMaterica's manifest and stage | yes |
| `reach` | reach | not stated | yes |
| `sampling` | sampling | not stated | no |
| `support` | support | not stated | no |

`native`: none, so the stage writes it in MIME's schema with its drawing.

`placement`: `axis` is its prim's z axis, `centre` is its prim's origin; on a stage, the prim's transform, never an attribute.

Run-time capabilities (signed distance, outward normal, nearest point) are its regions' and surfaces' shapes, listed below.

## Nodes it builds

Builds no node of its own.

## Gradient status

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

## Validity

none declared

## References

none declared

## Other declarations

| Class variable | Type | Value |
|---|---|---|
| `directions` | `ClassVar[tuple[str, ...]]` | `["axis"]` |
| `moving` | `ClassVar[bool]` | `false` |
| `patches` | `ClassVar[Mapping[str, str]]` | `{}` |
| `reach_envelope` | `ClassVar[float]` | `0.0` |
| `region_shapes` | `ClassVar[Mapping[str, str]]` | `{"lumen": "cylinder"}` |
| `regions` | `ClassVar[tuple[str, ...]]` | `["lumen", "wall"]` |
| `support_basis` | `ClassVar[str]` | `` |
| `support_error` | `ClassVar[float]` | `0.0` |
| `surfaces` | `ClassVar[Mapping[str, str]]` | `{"inner_surface": "cylinder"}` |