# geometry box

Describes the entry `box` at version `0.1.0`, registered by `mime.scene._solids.Box`.

## At a glance

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

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

### `box`

A solid rectangular box, given by the three lengths of its edges (`size`), along the part frame's axes and centred on its
centroid: a block, a slab, the body of a rectangular magnet. As a body's part it gives the body its volume and inertia
(both closed forms), its extent (half its diagonal about any axis), its reach along a direction and its surface samples
by patch, for a solver that integrates over the surface. At run time a node evaluates it through its regions, three slabs
between the pairs of opposite faces (`span_x`, `span_y`, `span_z`), the body being their intersection; its patches are the
three pairs of faces.

**When not to use it.**
- For a body that is not a box: its extent and anything read from its samples would be a box's.
- Where a consumer needs the body's deepest point in a direction (`support`): the kind answers a reach, not a support, and
  a consumer that needs one is refused when it plans, naming both.
- Where the stage must show it as a USD primitive: it has no native form, so the stage writer draws it (the
  capabilities table says so).

**Its derivative** is its slabs', as their switch declares: at a slab's mid-plane the distance has a kink. Its volume
and inertia are exact.

**Its sampling.** At a spacing, for a solver whose unknowns sit at the samples (the MRS rung), it samples its surface
quasi-uniformly, chosen from its quadrature (`mime.scene.quasi_uniform`); the quadrature is Gauss-Legendre along both
edges of each face, so that its divergence integrals are exact. The choice of samples is discrete, so it is not
continuous in `size`: rebuilt at a slightly moved edge, the sampling can choose again and the MRS resistance step with it
(the numbers are MIME-ANO-127's).

**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 |
|---|---|---|---|---|---|
| `size` | `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.

## 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 | yes |
| `area` | the area of each patch | the samples' weights | yes |
| `mass_properties` | volume and inertia at a density | the part resolver | yes |
| `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 | no |
| `reach` | reach | not stated | yes |
| `sampling` | sampling | not stated | yes |
| `support` | support | not stated | no |

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

`placement`: none: its own frame is the frame its settings are written in.

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

[@WeissteinCuboid], [@WeissteinMomentOfInertia]

## Other declarations

| Class variable | Type | Value |
|---|---|---|
| `directions` | `ClassVar[tuple[str, ...]]` | `[]` |
| `moving` | `ClassVar[bool]` | `false` |
| `patches` | `ClassVar[Mapping[str, str]]` | `{"faces_x": "span_x", "faces_y": "span_y", "faces_z": "span_z"}` |
| `reach_envelope` | `ClassVar[float]` | `0.0` |
| `region_shapes` | `ClassVar[Mapping[str, str]]` | `{"span_x": "slab", "span_y": "slab", "span_z": "slab"}` |
| `regions` | `ClassVar[tuple[str, ...]]` | `["span_x", "span_y", "span_z"]` |
| `support_basis` | `ClassVar[str]` | `` |
| `support_error` | `ClassVar[float]` | `0.0` |
| `surfaces` | `ClassVar[Mapping[str, str]]` | `{}` |