# geometry ellipsoid

Describes the entry `ellipsoid` at version `0.1.0`, registered by `mime.scene._solids.Ellipsoid`.

## At a glance

- geometry `ellipsoid`, version `0.1.0`, namespace `mime`
- Derivative: `exact`
- Validity: none declared

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

### `ellipsoid`

A solid ellipsoid given by its three semi-axes, along its part frame's x, y and z, and centred on its centroid: an
egg-shaped or flattened particle, a cell, or a smooth body whose three widths differ. As a body's part it gives the
body its volume and inertia and its surface samples, its one patch `surface`, for a solver that integrates over the
surface. Its region `solid` has no registered shape (an ellipsoid's distance has no closed form), so nothing evaluates
it at run time, and a body whose hull it is declares its extent where a law reads one.

**When not to use it.** For a body with a feature the ellipsoid smooths away (a thread, a fin, an edge), or where a
law needs the distance to its surface at run time.

**Its derivative** is exact: its volume, inertia, area, samples and reach are smooth functions of its semi-axes.

**Its sampling.** At a spacing, for a solver whose unknowns sit at the samples (the MRS rung), it samples its surface
quasi-uniformly: as many samples as its quadrature (Gauss-Legendre in the cosine of the polar angle about z, the
trapezoid rule round it) has at that spacing, chosen from that quadrature at a finer spacing by farthest points and
Lloyd's relaxation (`mime.scene.quasi_uniform`), each a quadrature sample with its cell's area as its weight. Its hull
query, its reach along `d`, is the length of `(a d_x, b d_y, c d_z)`.

**What its sampling costs.** As on the sphere, the MRS rung's drag at a given count is further from the closed form
(Oberbeck's and Edwardes's, as Kim and Karrila give it) on the quasi-uniform sampling than on its quadrature's grid,
in translation and in rotation, on the two triaxial ellipsoids measured: the grid misses by three fifths to three
quarters as much (the numbers are MIME-ANO-126's). The ellipsoid samples quasi-uniformly all the same, as every kind
does (a labelled default the maintainer may overturn); the separated quadrature chooses the
defaults again.

**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, its first version, gained its quadrature, its sampling and its regions before any release, at the
same version: before it the MRS rung refused it, so no result of it moved.

## Settings

| Setting | Type | Default | Dimension | Role | Default's kind |
|---|---|---|---|---|---|
| `semi_axes` | `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 | yes |

`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 `exact`, the derivative of what it computes.

## Validity

none declared

## References

[@WeissteinEllipsoid]

## Other declarations

| Class variable | Type | Value |
|---|---|---|
| `directions` | `ClassVar[tuple[str, ...]]` | `[]` |
| `moving` | `ClassVar[bool]` | `false` |
| `patches` | `ClassVar[Mapping[str, str]]` | `{"surface": "solid"}` |
| `reach_envelope` | `ClassVar[float]` | `0.0` |
| `region_shapes` | `ClassVar[Mapping[str, str]]` | `{}` |
| `regions` | `ClassVar[tuple[str, ...]]` | `["solid"]` |
| `support_basis` | `ClassVar[str]` | `closed form` |
| `support_error` | `ClassVar[float]` | `0.0` |
| `surfaces` | `ClassVar[Mapping[str, str]]` | `{}` |