# geometry sphere

Describes the entry `sphere` at version `0.2.0`, registered by `mime.scene._solids.Sphere`.

Kept registered beside it: `sphere` at version `0.1.0`, by `mime.scene._previous.SphereGrid`, which a document naming that version loads; its differences are in the hand-written part's versions.

## At a glance

- geometry `sphere`, version `0.2.0`, namespace `mime`
- Derivative: `piecewise_jump`
- Validity: none declared

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

### `sphere`

A solid ball, given by its radius and centred on its centroid: a bead, a particle, or the body of a magnetic sphere
pulled by a field gradient. As a body's part it gives the body its volume and inertia, its extent (its radius, about
any axis) and its surface samples by patch, for a solver that integrates over the surface; at run time a node
evaluates it by the shape `sphere`.

**When not to use it.** For a body that is not round: its extent and anything read from its samples would be a
sphere's.

**Its derivative** is the shape's: at the centre the distance is a cone and the normal has no limit. Within a band
about the centre the distance is minus the radius and the normal zero, each with the derivative zero in the point.

**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 has at that spacing, chosen from its 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, so that no two crowd. Its hull query, its reach in a direction, is its radius times the direction's length.

**What its sampling costs.** On the sphere the MRS rung's drag at a given count is further from Stokes's law on the
quasi-uniform sampling than on the grid of its first version, in translation and in rotation, at every count measured
from about a hundred samples to a few thousand: the grid misses by two thirds to three quarters as much. It is not the
grid's symmetry (the same holds on triaxial ellipsoids, and a uniform set that shares no code with the sampler gives the
sampler's numbers); the numbers are MIME-ANO-126's. The sphere's two-resolution extrapolation still meets Stokes's law
within the oracle's tolerance. The sphere samples quasi-uniformly all the same (a labelled default the
maintainer may overturn): it is the only closed-form drag oracle the default sampler has, and on the screw, the body
without the sphere's smoothness, the same sampling comes far closer to a converged reference. 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.2.0 samples its surface quasi-uniformly; 0.1.0, the first, sampled it by its
quadrature, Gauss-Legendre in the cosine of the polar angle and even in azimuth, which put a quarter of its samples
within half the mean spacing of another at the poles (MIME-ANO-123). 0.1.0 stays registered so that a folder saved with
it loads and reproduces; a script that writes `Sphere(...)` gets 0.2.0. The quadrature, the shape and every closed form
are unchanged.

## Settings

| Setting | Type | Default | Dimension | Role | Default's kind |
|---|---|---|---|---|---|
| `radius` | `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 | yes |
| `family_parameters` | the parameters of the family it is | a surrogate trained on one family | yes |
| `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 | yes |
| `drawing` | a drawing, tessellated at the writer's resolution | the stage writer, for a kind with no native form | no |
| `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 | yes |
| `support` | support | not stated | yes |

`native`: written as USD's `Sphere`, its attributes the kind's settings (`radius` holds `radius`).

`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

[@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]]` | `{"solid": "sphere"}` |
| `regions` | `ClassVar[tuple[str, ...]]` | `["solid"]` |
| `support_basis` | `ClassVar[str]` | `closed form` |
| `support_error` | `ClassVar[float]` | `0.0` |
| `surfaces` | `ClassVar[Mapping[str, str]]` | `{}` |