Vector geometry and rigid transforms

Use this page when a computation needs domain-neutral vector geometry or a rigid three-dimensional transform without selecting an astronomical coordinate frame.

Representation contract¶

Contract field	Current representation
Mathematical object	Euclidean vectors, angular separation, rotation matrices, unit quaternions, and rigid transforms.
Physical convention	Rotations are right-handed; quaternions are stored as scalar-first `[w, x, y, z]`; rigid composition is explicitly `outer(inner(point))`.
Runtime owner	`jaxstro.geometry` owns the domain-neutral geometric maps.
Shape and unit policy	Vectors have a final component axis, rotations are `(3, 3)`, quaternions are `(4,)`, and angles are radians; coordinate units remain caller-owned and must be consistent.
Transform boundary	Regular finite vectors and fixed composition paths support `jit`, `vmap`, and local AD; zero-vector normalization, collinear angular endpoints, and singular axes are excluded boundaries.
Evidence	Unit tests check norm preservation, matrix-quaternion parity, inverse transforms, and composition; validation compares smooth-domain AD with finite differences.
Downstream interpretation boundary	Jaxstro does not assign a sky frame, body frame, handedness conversion, uncertainty model, or domain geometry policy.

Vectors and angles¶

normalize(vectors, axis=..., return_norm=...) returns unit vectors and optionally their original norms. angular_distance(a, b) normalizes both inputs to $\hat{\mathbf{a}}$ and $\hat{\mathbf{b}}$ and evaluates

\alpha = 2\,\operatorname{atan2}\!\left( \lVert\hat{\mathbf{a}}-\hat{\mathbf{b}}\rVert,\; \lVert\hat{\mathbf{a}}+\hat{\mathbf{b}}\rVert \right),

(1)

which equals $\arccos(\hat{\mathbf{a}}\cdot\hat{\mathbf{b}})$ but keeps full relative precision at small angles and near $\pi$ . In float64 the arccos form returns 0 for separations below about 10^-8 rad, because the dot product rounds to 1. The angle is not differentiable at exact coincidence or opposition; there the returned gradient is 0, an element of the subdifferential, rather than NaN.

Inputs may have leading batch dimensions. axis identifies the component dimension. Angles are returned in radians and do not carry a runtime unit object.

Degenerate zero-vector behavior is explicit through the eps argument to normalize. With eps=0, a zero vector produces an undefined division; with a positive eps, the caller has deliberately chosen a numerical floor. Neither choice creates a physical direction for a zero-vector input.

Rotations and quaternions¶

rotation_matrix(axis, angle) uses the right-handed axis-angle convention. quaternion_from_axis_angle, quaternion_multiply, quaternion_conjugate, and quaternion_rotate use quaternions stored as [w, x, y, z]. Quaternion rotation normalizes the quaternion before applying the Hamilton product.

Rigid transforms and order¶

rigid_transform(points, rotation, translation) applies

\mathbf{p}' = \mathbf{R}\mathbf{p}+\mathbf{t}.

(2)

invert_rigid returns the inverse. compose_rigid(outer_R, outer_t, inner_R, inner_t) returns a transform equivalent to outer(inner(point)); reversing the arguments changes the result because rigid-transform composition is not commutative.

The tests establish the algebra and the smooth executed-map derivatives represented by (1) and (2). They do not identify which frame a vector belongs to or whether a downstream rotation convention matches these choices.