✨ feat: tangents

Signed-off-by: nstarman <nstarman@users.noreply.github.com>

Author: nstarman

docs/spec.md

@@ -38,7 +38,7 @@ A **distance quantity** has dimensions of length and, in the strict metric sense
 Let $M$ be a **smooth manifold** of dimension $n$.
 
 - A **point** is an element $p \in M$.
-- A **tangent vector** at $p$ is an element $v \in T_pM$, where $T_pM$ is the **tangent space** at $p$: a vector space attached to the point that represents the infinitesimal directions in which one may move away from $p$ on the manifold.
+- A **tangent vector** at $p$ is an element $v \in T_pM$, where $T_pM$ is the [**tangent space**](#math-spec-tangents) at $p$: a vector space attached to the point that represents the infinitesimal directions in which one may move away from $p$ on the manifold.
 
 <!-- Charts -->
 
@@ -88,9 +88,110 @@ $$
 \varphi_S(r, \theta, \phi) \circ \varphi_C^{-1}(x, y, z) = (\sqrt(x^2+y^2+z^2), \arccos(z/r), \arctan(y/x))
 $$
 
+<!-- Frame Transformations -->
+
+**_Frame Transformations_**:
+
+A **frame transformation** is a smooth map
+
+$$
+F : M \to M
+$$
+
+that relates two descriptions of points on the same manifold. The map $F : M \to M$ is smooth if it is infinitely differentiable in any chart, a major boon for auto-differentiation codes.
+
+Such maps may represent either:
+
+- an **active transformation**, moving points of the manifold, or
+- a **passive transformation**, re-expressing the same geometric point in a different reference frame.
+
+_In `coordinax`, frame transformations are passive_: a point described in one reference frame can be mapped to its representation in another frame.
+
+Here we enumerate some transformations:
+
+<u>**identity**</u>:
+
+The trivial transformation that leaves all points unchanged.
+
+<!-- Frame Transformations: translations -->
+
+<u>**translation**</u>:
+
+shifts all points by a constant displacement vector:
+
+$$
+F(p) = p + a .
+$$
+
+In Cartesian coordinates this is $ x’ = x + a .$
+
+<!-- Frame Transformations: rotations -->
+
+<u>**rotations**</u>:
+
+A rotation is a linear transformation preserving orientation and distances in Euclidean space. In $\mathbb{R}^n$, rotations are represented by orthogonal matrices with unit determinant:
+
+$$
+R^T R = I, \quad \det R = 1 .
+$$
+
+Rotations form the special orthogonal group $ SO(n).$
+
+<!-- Frame Transformations: rotations -->
+
+<u>**reflections**</u>:
+
+A reflection is a linear transformation that reverses orientation across a hyperplane. Reflections preserve distances but have determinant -1.
+
+Together with rotations, reflections generate the orthogonal group $ O(n). $
+
+<a id="math-spec-tangents"></a>
+
+## Tangents
+
+<!-- tangents -->
+
+**_Tangent Spaces_**:
+
+For a smooth manifold $M$ and a point $p \in M$, the **tangent space** $T_pM$ is the vector space of infinitesimal directions through $p$.
+
+Elements $v \in T_pM$ may be equivalently defined as
+
+- equivalence classes of curves through $p$,
+- derivations acting on smooth functions,
+- coordinate vectors induced by charts.
+
+In a chart $C=(U,\varphi)$ with coordinates $q^i$, the tangent space has a natural coordinate basis
+
+$$
+\left\{\frac{\partial}{\partial q^1},
+      \dots,
+      \frac{\partial}{\partial q^n}\right\}_p .
+$$
+
+A tangent vector can therefore be written
+
+$$
+v = v^i \frac{\partial}{\partial q^i}\Big|_p .
+$$
+
+Under a change of coordinates \(q^i \rightarrow \tilde q^j\), the components transform by the **Jacobian pushforward law**
+
+$$
+\tilde v^j = \frac{\partial \tilde q^j}{\partial q^i} v^i .
+$$
+
+The collection of all tangent spaces forms the **tangent bundle**
+
+$$
+TM = \bigsqcup_{p \in M} T_pM .
+$$
+
+Unlike points, tangent vectors form a vector space and support addition and scalar multiplication.
+
 <!-- metric -->
 
-**_Metrics \& Reimannian Manifolds_**:
+**_Metrics \& Manifolds_**:
 
 A manifold _without_ a metric is just a smooth manifold $M$. We can add geometric structure to the manifold, specifically the **metric**, to obtain a **Riemannian manifold** $(M, g)$.
 
@@ -111,70 +212,128 @@ varying smoothly with p. This additional structure equips the manifold with noti
 
 Importantly, the metric acts only on tangent spaces; it does not act directly on points. Thus, it equips the manifold with intrinsic geometric meaning beyond smooth structure alone.
 
-In chart coordinates, the metric is represented by the matrix
+**Metric Matrix**
+
+In a coordinate chart with coordinates $q^i$, the metric tensor is represented by a symmetric matrix of components
 
 $$
-g_{ij}(q) = g\!\left(\frac{\partial}{\partial q^i},\frac{\partial}{\partial q^j}\right),
+g_{ij}(q) = g\!\left(\frac{\partial}{\partial q^i},\frac{\partial}{\partial q^j}\right).
 $$
 
-evaluated at the base point $p$ with coordinates $q=\varphi(p)$.
+This matrix varies smoothly with the base point $p$ whose coordinates are $q=\varphi(p)$. In matrix form the metric determines the squared line element
 
-<!-- Frame Transformations -->
+$$
+ds^2 = g_{ij}(q)\, dq^i dq^j.
+$$
 
-**_Frame Transformations_**:
+The matrix $g_{ij}$ is symmetric and non-degenerate:
 
-A **frame transformation** is a smooth map
+$$
+g_{ij} = g_{ji}, \qquad \det(g_{ij}) \neq 0.
+$$
+
+The inverse matrix $g^{ij}$ satisfies
 
 $$
-F : M \to M
+g^{ik} g_{kj} = \delta^i_j,
 $$
 
-that relates two descriptions of points on the same manifold. The map $F : M \to M$ is smooth if it is infinitely differentiable in any chart, a major boon for auto-differentiation codes.
+and is used to raise indices and identify tangent and cotangent spaces.
 
-Such maps may represent either:
+**Signature of a Metric**
 
-- an **active transformation**, moving points of the manifold, or
-- a **passive transformation**, re-expressing the same geometric point in a different reference frame.
+The **signature** of a metric describes the signs of the eigenvalues of the metric matrix. If the metric matrix at a point can be diagonalized to
 
-_In `coordinax`, frame transformations are passive_: a point described in one reference frame can be mapped to its representation in another frame.
+$$
+\mathrm{diag}(\underbrace{+1,\dots,+1}_p,\underbrace{-1,\dots,-1}_q),
+$$
 
-Here we enumerate some transformations:
+then the metric is said to have signature $(p,q)$.
 
-<u>**identity**</u>:
+The signature is invariant under coordinate transformations and characterizes the geometric type of the manifold. Typical examples include:
 
-The trivial transformation that leaves all points unchanged.
+- **Riemannian metrics:** signature $(n,0)$, all positive eigenvalues. These describe ordinary curved spatial geometries.
+- **Lorentzian metrics:** signature $(1,3)$ describe spacetime geometry in relativity.
 
-<!-- Frame Transformations: translations -->
+Thus the signature distinguishes purely spatial geometries from spacetime geometries with one timelike direction.
 
-<u>**translation**</u>:
+<!-- transformations -->
 
-shifts all points by a constant displacement vector:
+**_Frame Transformations_**:
+
+<!-- Induced Action on Tangent Spaces -->
+
+A smooth map $F : M \to M$ induces a linear map on tangent spaces called the pushforward
 
 $$
-F(p) = p + a .
+F_* : T_pM \to T_{F(p)}M .
 $$
 
-In Cartesian coordinates this is $ x’ = x + a .$
+If $v \in T_pM$ is a tangent vector, then under the transformation
 
-<!-- Frame Transformations: rotations -->
+$$
+v \mapsto F_* v .
+$$
 
-<u>**rotations**</u>:
+In coordinates $x^i$, if the transformation is written
 
-A rotation is a linear transformation preserving orientation and distances in Euclidean space. In $\mathbb{R}^n$, rotations are represented by orthogonal matrices with unit determinant:
+$$
+x’^i = F^i(x),
+$$
+
+then the tangent components transform according to the Jacobian
 
 $$
-R^T R = I, \quad \det R = 1 .
+v’^i = \frac{\partial F^i}{\partial x^j} v^j .
 $$
 
-Rotations form the special orthogonal group $ SO(n).$
+Thus frame transformations act naturally on both points and tangent vectors.
 
-<!-- Frame Transformations: rotations -->
+<!-- Isometry -->
 
-<u>**reflections**</u>:
+Transformations that preserve distances between points are called isometries. When a metric structure g exists on the manifold, a map $F : M \to M$ is an isometry if
 
-A reflection is a linear transformation that reverses orientation across a hyperplane. Reflections preserve distances but have determinant -1.
+$$
+g(F_* u, F_* v) = g(u,v)
+$$
 
-Together with rotations, reflections generate the orthogonal group $ O(n). $
+<!-- Frame Transformations: Lorentz boosts -->
+
+<u>**Lorentz boosts**</u>:
+
+A Lorentz boost is a Lorentz transformation corresponding to a change between inertial frames moving at constant relative velocity (see [Tangents](#math-spec-tangents) for the definition and properties of velocity).
+
+For motion in an arbitrary spatial direction with velocity vector $\mathbf{v}$,
+
+$$
+\begin{aligned}
+t' &= \gamma \left(t - \frac{\mathbf{v} \cdot \mathbf{x}}{c^2}\right), \\
+\mathbf{x}' &= \mathbf{x} + \frac{\gamma - 1}{\|\mathbf{v}\|^2} (\mathbf{v} \cdot \mathbf{x}) \, \mathbf{v} - \gamma \, \mathbf{v} \, t,
+\end{aligned}
+$$
+
+where
+
+$$
+\gamma = \frac{1}{\sqrt{1 - \|\mathbf{v}\|^2/c^2}} .
+$$
+
+<!-- Frame Transformations: Lorentz acceleration boosts -->
+
+<u>**Acceleration boosts**</u>:
+
+Uniformly accelerated observers in Minkowski spacetime use Rindler coordinates. The transformation from Minkowski coordinates (t,x) to Rindler coordinates (\tau,\rho) is
+
+$$
+\begin{aligned}
+t &= \rho \sinh(a\tau / c), \
+x &= \rho \cosh(a\tau / c),
+\end{aligned}
+$$
+
+where a is the proper acceleration.
+
+These transformations describe reference frames undergoing constant proper acceleration. Unlike Lorentz transformations, they do not correspond to global spacetime symmetries but are still smooth diffeomorphisms on appropriate regions of spacetime.
 
 ## Transformation Groups
 
@@ -524,6 +683,8 @@ Typical examples include
 - **Points**: a point is an element $$p \in M .$$ The transformation law is $$
 q_f = \Phi(q_i) $$
 
+- **Tangent vectors**: a tangent vector at $p$ is an element $$ v \in T_pM , $$ where $T_pM$ is the tangent space of $M$ at $p$. The transformation law is $$ v_f^a = \frac{\partial q_f^a}{\partial q_i^b} v_i^b $$
+
 Thus the geometry kind determines the class of transformation rule applied to the components.
 
 Importantly, the geometry kind is **independent of the coordinate chart** used to represent the components. The same geometric object may be written in any compatible chart.
@@ -550,11 +711,46 @@ The coefficients $v^a$ are the **components of the vector in the basis** $B$.
 
 **Coordinate bases** determine how components are expressed, when such a choice is meaningful.
 
+Given a chart with coordinates $q^a$, the natural coordinate basis of the tangent space is
+
+$$
+\left\{ \frac{\partial}{\partial q^a} \right\}.
+$$
+
+In this basis,
+
+$$
+v = v^a \frac{\partial}{\partial q^a}.
+$$
+
+The corresponding cotangent basis is
+
+$$
+\{ dq^a \}.
+$$
+
+#### Basis transformations
+
+If two bases ${e_a}$ and ${e’_a}$ are related by
+
+$$
+e’_a = A_a^{\ b} e_b ,
+$$
+
+then vector components transform as
+
+$$
+v’^a = (A^{-1})_b^{\ a} v^b .
+$$
+
+Thus basis transformations act **linearly**, in contrast to chart transitions, which are generally nonlinear.
+
 #### Basis relevance
 
 Not all geometric objects require a basis specification.
 
 - Points are affine objects and do not belong to a vector space. Their coordinates are chart values, not vector components.
+- Vectors and tensors require a basis because their components depend on the basis choice.
 
 Therefore the basis component of a representation may be trivial for some geometry kinds.
 
@@ -567,9 +763,20 @@ While the geometry kind determines the mathematical space of the object, the sem
 Examples include:
 
 - **Location**: a point interpreted as the position of a particle or object.
+- **Displacement**: a tangent vector interpreted as the difference between nearby points.
+- **Velocity**: a tangent vector interpreted as the derivative of a trajectory: $$ v = \frac{d\gamma}{dt}. $$
+- **Acceleration**: a tangent vector interpreted as the second derivative of a trajectory.
 
 Semantic kinds do **not** change coordinate transformation laws.
 
+For example, velocity and acceleration both transform as tangent vectors under coordinate changes:
+
+$$
+v_f^a = \frac{\partial q_f^a}{\partial q_i^b} v_i^b .
+$$
+
+Their difference lies only in interpretation and in the operations that produce them.
+
 Separating semantics from geometry provides two advantages:
 
 1. Correct transformation laws -- transformation behavior depends only on geometry kind and basis, not on semantics.

packages/coordinax.hypothesis/src/coordinax/hypothesis/representations/_src/reps.py

@@ -40,6 +40,15 @@ def valid_basis_classes_for_geometry(
     return (cxr.NoBasis,)
 
 
+@plum.dispatch
+def valid_basis_classes_for_geometry(
+    geom_kind: cxr.TangentGeometry, /
+) -> tuple[type[cxr.AbstractBasis], ...]:
+    """Return valid basis classes for tangent geometry."""
+    del geom_kind
+    return (cxr.CoordinateBasis, cxr.PhysicalBasis)
+
+
 @plum.dispatch
 def valid_semantic_classes_for_geometry(
     geom_kind: cxr.AbstractGeometry, /
@@ -61,6 +70,16 @@ def valid_semantic_classes_for_geometry(
     return (cxr.Location,)
 
 
+@plum.dispatch
+def valid_semantic_classes_for_geometry(
+    geom_kind: cxr.TangentGeometry,
+    /,
+) -> tuple[type[cxr.AbstractSemanticKind], ...]:
+    """Return valid semantic classes for tangent geometry."""
+    del geom_kind
+    return (cxr.Displacement, cxr.Velocity, cxr.Acceleration)
+
+
 @st.composite
 def representations(
     draw: st.DrawFn,