✨ feat: tangent representations

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

Author: nstarman

docs/api/representations.md

@@ -40,11 +40,19 @@ This is separate from charts and manifolds:
 {'r': Array(3.74165739, dtype=float64, ...),
  'theta': Array(0.64052231, dtype=float64),
  'phi': Array(1.10714872, dtype=float64, ...)}
+
+# Change tangent components between basis conventions in the same chart.
+>>> v = {"r": u.Q(1.0, "km/s"), "theta": u.Q(0.0, "rad/s"), "phi": u.Q(0.0, "rad/s")}
+>>> at = {"r": u.Q(2.0, "km"), "theta": u.Q(3.0, "rad"), "phi": u.Q(4.0, "rad")}
+>>> v2 = cxr.change_basis(v, cxc.cart2d, cxr.coord_basis, cxr.phys_basis, at=at)
+>>> v2
+{'r': Q(1., 'km / s'), 'theta': Q(0., 'rad / s'), 'phi': Q(0., 'rad / s')}
 ```
 
 ## Functional API
 
 - `cconvert`: representation-aware coordinate conversion API
+- `change_basis`: same-chart tangent basis conversion API
 - `cmap`: partial-function builder around `cconvert`
 - `guess_basis_kind`: infer basis kind from dimensions/data
 - `guess_geometry_kind`: infer geometric kind from dimensions/data
@@ -58,6 +66,7 @@ For point data, `cconvert` dispatches through chart-level point conversion laws.
 ### Conversion Functions
 
 - `cconvert`: convert data across charts/representations
+- `change_basis`: change tangent basis without changing chart
 - `cmap`: build reusable conversion callables
 - `guess_basis_kind`: infer a basis kind
 - `guess_geometry_kind`: infer a geometry kind
@@ -92,6 +101,8 @@ For point data, `cconvert` dispatches through chart-level point conversion laws.
 
 - Representations are orthogonal to charts: chart choice and representation choice are independent concerns.
 - The current built-in flow is point-first, centered on `(point_geom, no_basis, loc)`.
+- `change_basis` is currently limited to tangent data in Cartesian charts, with `CoordinateBasis` $
+ightleftarrows$ `PhysicalBasis` conversions.
 
 ```{eval-rst}
 

docs/guides/representations.md

@@ -138,12 +138,40 @@ Current built-in representation conversions are point-first:
 
 The representation design is intentionally extensible. Future geometric kinds (for example tangent and cotangent objects) can use different transformation categories (such as Jacobian pushforward/pullback) while keeping the same chart and manifold interfaces.
 
+## Tangent Basis Changes
+
+`change_basis` handles a narrower problem than `cconvert`: it keeps the chart fixed and only changes how tangent components are interpreted with respect to a basis.
+
+In the current v1 implementation, this is intentionally limited to tangent data in Cartesian charts:
+
+- supported basis changes: `CoordinateBasis` $
+ightleftarrows$ `PhysicalBasis`
+- supported representations: tangent representations such as `coord_disp` and `phys_disp`
+- unsupported: point data (`NoBasis`) and non-Cartesian charts
+
+```{code-block} python
+>>> import coordinax.charts as cxc
+>>> import coordinax.representations as cxr
+
+>>> v = {"x": 1.0, "y": 0.0}
+>>> at = {"x": 2.0, "y": 3.0}
+
+>>> cxr.change_basis(v, cxc.cart2d, cxr.coord_basis, cxr.phys_basis, at=at)
+{'x': 1.0, 'y': 0.0}
+
+>>> cxr.change_basis(v, cxc.cart2d, cxr.coord_disp, cxr.phys_disp, at=at)
+{'x': 1.0, 'y': 0.0}
+```
+
+In Cartesian charts the coordinate basis and physical basis coincide, so the component values are unchanged. The API exists so code can state basis intent explicitly and remain extensible to nontrivial basis changes later.
+
 ## Quick Reference
 
 - Need only a same-manifold coordinate rewrite: `pt_map`
 - Need general point mapping behavior: `pt_map`
 - Need manifold compatibility checks: manifold methods like `M.pt_map`
 - Need representation-aware conversions: `cconvert`
+- Need same-chart tangent basis conversion: `change_basis`
 - Need reusable conversion callables: `cmap`
 - Need to infer basis kind from data: `guess_basis_kind`
 - Need to infer semantic kind from data: `guess_semantic_kind`

docs/spec.md

@@ -946,7 +946,7 @@ A non-exhaustive table of exported objects are:
 | `coordinax.angles` | `AbstractAngle`, `Angle`, `wrap_to` |
 | `coordinax.distances` | `AbstractDistance`, `Distance` |
 | `coordinax.charts` | `CartesianProductChart`, </br> `cartesian_chart`, `guess_chart`, `cdict`, `pt_map`, `jac_pt_map`, </br> `cart0d`, </br> `cart1d`, `radial1d`, `time1d`, </br> `cart2d`, `polar2d`, </br> `cart3d`, `cyl3d`, `sph3d`, `lonlat_sph3d`, `loncoslat_sph3d`, `math_sph3d`, </br> `cartnd`, </br> `spacetimect` |
-| `coordinax.representations` | `cconvert`, </br> `Representation`, `point`, `coord_disp`, `coord_vel`, `coord_acc`, `phys_disp`, `phys_vel`, `phys_acc`, </br> `PointGeometry`, `point_geom`, `TangentGeometry`, `tangent_geom`, </br> `NoBasis`, `no_basis`, `CoordinateBasis`, `coord_basis`, `PhysicalBasis`, `phys_basis`, </br> `Location`, `loc`, `Displacement`, `dpl`, `Velocity`, `vel`, `Acceleration`, `acc`, </br> `guess_geometry_kind`, `guess_semantic_kind`, `guess_rep` |
+| `coordinax.representations` | `cconvert`, `change_basis`, `tangent_map`, </br> `Representation`, `point`, `coord_disp`, `coord_vel`, `coord_acc`, `phys_disp`, `phys_vel`, `phys_acc`, </br> `PointGeometry`, `point_geom`, `TangentGeometry`, `tangent_geom`, </br> `NoBasis`, `no_basis`, `CoordinateBasis`, `coord_basis`, `PhysicalBasis`, `phys_basis`, </br> `Location`, `loc`, `Displacement`, `dpl`, `Velocity`, `vel`, `Acceleration`, `acc`, </br> `guess_geometry_kind`, `guess_semantic_kind`, `guess_rep` |
 | `coordinax.vectors` | `Point`, `ToUnitsOptions` |
 | `coordinax.manifolds` | `guess_manifold`, `scale_factors`, `angle_between`, </br> `EuclideanManifold`, `EuclideanMetric`, `euclidean3d`, </br> `EmbeddedManifold`, `EmbeddedChart` </br> `twosphere`, `embedded_twosphere`, </br> `CustomManifold`,`CustomAtlas`, |
 | `coordinax.transforms` | `act`, `simplify`, `compose`, `materialize_transform`, </br> `AbstractTransform`, `Identity`, `Composed`, `Translate`, `Rotate`, `Reflect`, `Scale`, `Shear`, `identity`, </br> `AbstractTransformGroup`, `IdentityGroup`, `DiffeomorphismGroup`, `AffineGroup`, `EuclideanGroup`, `OrthogonalGroup`, `SpecialOrthogonalGroup`, `PoincareGroup`, `LorentzGroup`, `ProperOrthochronousLorentzGroup` |
@@ -1728,6 +1728,44 @@ A representation is therefore **not** the same thing as a chart: the chart deter
 
     - Inherits all failure semantics from `guess_geometry_kind`.
 
+!!! info `tangent_map`
+
+    Transform a tangent vector from one chart to another.
+
+    **Signature:**
+
+    ```text
+    tangent_map(v, from_chart, from_geom, from_rep, to_chart, to_geom, to_rep, /, *, at) -> CDict
+    ```
+
+    A 4-argument shorthand form is also supported:
+
+    ```text
+    tangent_map(v, from_chart, from_rep, to_chart, /, *, at) -> CDict
+    ```
+
+    **Arguments:**
+
+    - `v`: `CDict` — tangent vector components in `from_chart` with basis `from_rep.basis`.
+    - `from_chart`: source chart.
+    - `from_geom`: source geometry (e.g. `TangentGeometry`).
+    - `from_rep`: source `Representation` (must have `TangentGeometry`).
+    - `to_chart`: target chart.
+    - `to_geom`: target geometry.
+    - `to_rep`: target `Representation`.
+    - `at`: `CDict` — base point in `from_chart` coordinates at which the tangent space is attached. Required for non-Cartesian charts (since the Jacobian depends on the base point).
+
+    **Semantics by basis:**
+
+    - **`CoordinateBasis`**: delegates to `jac_pt_map(at, from_chart, to_chart)` to obtain the Jacobian $J^j{}_i = \partial\tilde{q}^j/\partial q^i$, then applies $\tilde{v}^j = J^j{}_i v^i$.
+    - **`PhysicalBasis`**: fetch the orthonormal frame matrices $B_{\rm from}$ (columns = physical basis vectors in Cartesian) and $B_{\rm to}$ via `frame_cart`, compute $R = B_{\rm to}^T B_{\rm from}$, apply $\hat{v}' = R \hat{v}$.
+
+    **Same-chart optimisation:** when `from_chart is to_chart`, returns `v` unchanged.
+
+    **`cconvert` integration:** `cconvert` dispatches to `tangent_map` when the source representation has `TangentGeometry`, passing `at` through the `at` keyword argument.
+
+    **Same-chart basis conversion:** `change_basis(v, chart, from_basis, to_basis, /, *, at)` changes tangent component conventions without changing charts. In v1 it is defined only for Cartesian charts and `CoordinateBasis` $
+
 </br>
 
 ### Geometric Kind
@@ -2625,6 +2663,90 @@ $$g_{ij}(q) = g_p\!\left(\frac{\partial}{\partial q^i}, \frac{\partial}{\partial
     - [`MinkowskiMetric`](#software-spec-minkowskimetric): Lorentzian metric $\eta = \operatorname{diag}(-1, 1, 1, 1)$ on Minkowski spacetime; diagonal in the canonical Cartesian spacetime chart.
     - [`HyperSphericalMetric`](#software-spec-hypersphericalmetric): round metric on $S^{n-1}$; diagonal entries follow the cumulative-sine rule $g_{kk} = \prod_{j < k}\sin^2\!\theta_j$.
 
+(software-spec-abstractdiagonalmetric)=
+
+!!! info `AbstractDiagonalMetric`
+
+    `AbstractDiagonalMetric` is an abstract subclass of `AbstractMetric` for metrics whose matrix is diagonal at every base point in every compatible chart.
+
+    A metric is **diagonal** (equivalently, the coordinate chart is an **orthogonal coordinate system**) when all off-diagonal entries of the metric matrix vanish:
+
+    $$g_{ij}(p) = 0 \quad \text{for } i \neq j \quad \forall\, p \in U.$$
+
+    The coordinate basis vectors $\partial/\partial q^i$ are mutually orthogonal. The diagonal entries $g_{ii}(p)$ give the squared scale factors
+
+    $$h_i(p)^2 = g_{ii}(p),$$
+
+    and the infinitesimal line element simplifies to
+
+    $$ds^2 = \sum_i g_{ii}(q)\,(dq^i)^2.$$
+
+    **Role: structural marker, not behavioral interface.**
+
+    `AbstractDiagonalMetric` adds no new abstract methods beyond those of `AbstractMetric`.  Its sole purpose is to **declare** that `metric_matrix` will always return a diagonal matrix.  This allows:
+
+    - Dispatch specialisations that compute `scale_factors` more efficiently
+      (e.g., extracting only the diagonal of $g$, or using squared Jacobian
+      column norms instead of the full $J^\top J$).
+    - Type-level distinction between orthogonal and general metrics in
+      multiple-dispatch registrations.
+
+    **Subclassing contract:**
+
+    Subclasses must implement the two abstract members inherited from
+    `AbstractMetric`:
+
+    - `signature` (abstract property): a tuple of $\pm 1$ of length `ndim`
+      encoding the metric signature in coordinate order.  Positive entries
+      are Riemannian (space-like); a ``-1`` entry is pseudo-Riemannian
+      (time-like).
+    - `metric_matrix(chart, /, *, at, usys=None)` (abstract method): must
+      return a diagonal `QuantityMatrix` (or plain `Array`) of shape
+      `(ndim, ndim)` with all off-diagonal entries exactly zero.
+
+    All other behavioral requirements of `AbstractMetric` also apply:
+    immutability (frozen dataclass), static JAX PyTree registration, and
+    `jit`/`vmap` compatibility.
+
+    **Relationship to `AbstractMetric.is_diagonal`:**
+
+    `AbstractMetric.is_diagonal(chart, at=at)` inspects the metric matrix at
+    a **specific base point** and returns a `bool`.
+    `AbstractDiagonalMetric` makes this an unconditional **structural
+    promise** across all base points: instances are always diagonal,
+    regardless of which chart or point is supplied.
+
+    **Concrete subclasses (built-in):**
+
+    | Class | Manifold | Diagonal in |
+    |-------|----------|-------------|
+    | [`EuclideanMetric`](#software-spec-euclideanmetric) | $\mathbb{R}^n$ | Cartesian charts; orthogonal curvilinear charts via $g = J^\top J$ |
+    | [`HyperSphericalMetric`](#software-spec-hypersphericalmetric) | $S^{n-1}$ | Intrinsic hyperspherical chart; cumulative-sine rule $g_{kk} = \prod_{j<k}\sin^2\!\theta_j$ |
+    | [`MinkowskiMetric`](#software-spec-minkowskimetric) | $\mathbb{R}^{1,3}$ | Canonical Cartesian spacetime chart $\eta = \operatorname{diag}(-1,1,1,1)$ |
+
+    **Example**
+
+    ```pycon
+    >>> from coordinax.manifolds._src.diagonal import AbstractDiagonalMetric
+    >>> import coordinax.manifolds as cxm
+
+    >>> isinstance(cxm.EuclideanMetric(3), AbstractDiagonalMetric)
+    True
+
+    >>> isinstance(cxm.MinkowskiMetric(), AbstractDiagonalMetric)
+    True
+
+    >>> import unxt as u
+    >>> isinstance(
+    ...     cxm.InducedMetric(
+    ...         cxm.TwoSphereIn3D(radius=u.Q(1.0, "m")),
+    ...         cxm.EuclideanMetric(3),
+    ...     ),
+    ...     AbstractDiagonalMetric,
+    ... )
+    False
+    ```
+
 (software-spec-abstractmanifold)=
 
 !!! info `AbstractManifold`

docs/tutorials/cdict_objects.md

@@ -184,6 +184,25 @@ Identity transform returns the exact same object:
 True
 ```
 
+## Changing Tangent Basis In-Place
+
+Use `cxr.change_basis()` when a CDict already lives in the correct chart and you only need to reinterpret tangent components with respect to a different basis.
+
+In v1 this supports Cartesian tangent data only. For Cartesian charts, coordinate and physical bases coincide, so the values are preserved.
+
+```{code-block} python
+>>> d = {"x": 1.0, "y": 0.0}
+>>> at = {"x": 2.0, "y": 3.0}
+
+>>> cxr.change_basis(d, cxc.cart2d, cxr.coord_basis, cxr.phys_basis, at=at)
+{'x': 1.0, 'y': 0.0}
+
+>>> cxr.change_basis(d, cxc.cart2d, cxr.coord_disp, cxr.phys_disp, at=at)
+{'x': 1.0, 'y': 0.0}
+```
+
+Use `cconvert()` instead when the chart itself must change.
+
 ## Upgrading To A Point
 
 Promote a CDict to a `Point` by providing chart context:

packages/coordinax.api/src/coordinax/api/representations.py

@@ -3,6 +3,7 @@
 __all__ = (
     "add",
     "cconvert",
+    "change_basis",
     "guess_basis_kind",
     "guess_geometry_kind",
     "guess_rep",
@@ -15,6 +16,42 @@
 import plum
 
 
+@plum.dispatch.abstract
+def change_basis(*args: Any, **kwargs: Any) -> Any:
+    """Change the basis of a tangent vector's components.
+
+    Supports both basis-object and representation-object overloads.
+    Tangent-only in v1: only CoordinateBasis <-> PhysicalBasis conversions are supported.
+
+    Examples
+    --------
+    >>> import coordinax.representations as cxr
+    >>> import coordinax.charts as cxc
+    >>> v = {"x": 1.0, "y": 0.0}
+    >>> at = {"x": 1.0, "y": 0.0}
+    >>> cxr.change_basis(v, cxc.cart2d, cxr.coord_basis, cxr.phys_basis, at=at)
+    {'x': 1.0, 'y': 0.0}
+    """
+    raise NotImplementedError  # pragma: no cover
+
+
+@plum.dispatch.abstract
+def tangent_map(*args: Any, **kwargs: Any) -> Any:
+    """Compute the tangent map (Jacobian) of a chart transition.
+
+    This is an abstract API definition. See the main coordinax package for
+    concrete implementations.
+
+    Examples
+    --------
+    >>> import jax.numpy as jnp
+    >>> import coordinax.charts as cxc
+    >>> import coordinax.representations as cxr
+
+    """
+    raise NotImplementedError  # pragma: no cover
+
+
 @plum.dispatch.abstract
 def cconvert(*args: Any, **kwargs: Any) -> Any:
     """Transform the current vector to the target chart.

src/coordinax/main/__init__.py

@@ -78,6 +78,8 @@
     "phys_disp",
     "phys_vel",
     "phys_acc",
+    "tangent_map",
+    "change_basis",
     # vectors
     "Point",
     "ToUnitsOptions",
@@ -134,6 +136,7 @@
     acc,
     add,
     cconvert,
+    change_basis,
     coord_acc,
     coord_basis,
     coord_disp,
@@ -149,6 +152,7 @@
     point_geom,
     subtract,
     tangent_geom,
+    tangent_map,
     vel,
 )
 from coordinax.transforms import (

src/coordinax/representations/__init__.py

@@ -96,6 +96,8 @@
     "guess_rep",
     "guess_semantic_kind",
     "subtract",
+    "tangent_map",
+    "change_basis",
     # Representations
     "Representation",
     "point",
@@ -154,6 +156,7 @@
         TangentGeometry,
         Velocity,
         acc,
+        change_basis,
         cmap,
         coord_acc,
         coord_basis,
@@ -169,6 +172,7 @@
         point,
         point_geom,
         tangent_geom,
+        tangent_map,
         vel,
     )
     from coordinax.api.representations import (

src/coordinax/representations/_src/__init__.py

@@ -1,9 +1,11 @@
 """Representations."""
 
 from .basis import *
+from .basis_change import *
 from .core import *
 from .geom import *
 from .guess import *
 from .register_cx import *
 from .rep import *
 from .semantics import *
+from .tangent_map import *