✨ feat: tangent representations

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

Author: nstarman

README.md

@@ -34,8 +34,8 @@ pip install coordinax
 
 - Specialized quantities: scalar coordinate quantities with units, including `Angle` (directional values on $S^1$ with explicit wrapping) and `Distance` (length-valued quantity), plus astronomy-facing forms like `Parallax` and `DistanceModulus`.
 - Charts: a coordinate chart / component schema (names + physical dimensions). A chart does not store numerical values.
-- Representation: geometric meaning of components, encoded as (geometry, basis, semantics), e.g. `point`.
 - Point: data + chart + representation, with conversion and arithmetic behavior defined by chart transition maps and tangent pushforwards.
+- Representation: geometric meaning of components, encoded as (geometry, basis, semantics), e.g. `point`, `coord_vel`, `phys_acc`.
 
 ## Modules
 
@@ -104,6 +104,8 @@ Common representation constants are available from the high-level module:
 import coordinax.main as cx
 
 cx.point  # point location data
+cx.coord_vel  # coordinate-basis velocity components
+cx.phys_vel  # physical-basis velocity components
 ```
 
 ### Manifolds

docs/api/charts.md

@@ -41,10 +41,9 @@ cart_of_sph = cxc.cartesian_chart(sph)
 - `guess_chart`: infer a chart from keys or array/quantity trailing shape
 - `cdict`: normalize inputs to component dictionaries
 - `pt_map`: transform points between charts on the same manifold
-- `pt_map`: general point map, including realization-style maps
-- `realize_cartesian`: realize point coordinates in `chart.cartesian`
+- `jacobian_pt_map`: general point map, including realization-style maps
 
-`pt_map` is the same-manifold specialization. `pt_map` is the more general interface.
+`pt_map` is the same-manifold specialization. `jacobian_pt_map` is the more general interface.
 
 ## Available Objects
 

docs/api/representations.md

@@ -10,34 +10,42 @@ A representation is the triple $R = (K, B, S)$:
 - $B$: basis kind (how components are interpreted as basis components)
 - $S$: semantic kind (what the object means physically/mathematically)
 
-This is separate from charts:
+This is separate from charts and manifolds:
 
 - Charts define coordinate systems.
+- Manifolds define the underlying space.
 - Representations define geometric meaning and transformation law category.
 
-In the current design, the primary built-in representation is point data.
-
 ## Quick Start
 
-```python
-import coordinax.charts as cxc
-import coordinax.representations as cxr
+```pycon
+>>> import coordinax.charts as cxc
+>>> import coordinax.representations as cxr
+>>> import unxt as u
 
 # Canonical point representation.
-rep = cxr.point
+>>> rep = cxr.point
 
 # Convert point data between charts while preserving representation.
-p = {"x": 1.0, "y": 2.0, "z": 3.0}
-q = cxr.cconvert(p, cxc.cart3d, rep, cxc.sph3d, rep)
+>>> p = {"x": 1.0, "y": 2.0, "z": 3.0}
+>>> q = cxr.cconvert(p, cxc.cart3d, rep, cxc.sph3d, rep)
+
+# 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')}
 
 # Build a reusable conversion map.
-to_sph = cxr.cmap(cxc.cart3d, cxr.point, cxc.sph3d)
-q2 = to_sph(p)
+>>> to_sph = cxr.cmap(cxc.cart3d, cxr.point, cxc.sph3d)
+>>> q2 = to_sph(p)
 ```
 
 ## 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
@@ -51,6 +59,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
@@ -73,6 +82,8 @@ For point data, `cconvert` dispatches through chart-level point conversion laws.
 
 - `AbstractBasis`: base class for basis descriptors
 - `NoBasis` / `no_basis`: basis kind used for affine point data
+- `CoordinateBasis` / `coord_basis`: coordinate-basis tangent components
+- `PhysicalBasis` / `phys_basis`: physical-basis tangent components
 
 ## Semantic Kind
 
@@ -83,6 +94,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`