WIP

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

Author: nstarman

.github/copilot-instructions.md

@@ -51,6 +51,9 @@ authoritative specification file:
 When working inside a workspace package:
 
 - You MUST read and follow that package’s own `docs/spec.md`.
+- Before editing any code, read the relevant `docs/spec.md` for the package you
+  are changing.
+- If changing behavior, update docstrings, docs, and tests in the same PR.
 - If behavior in a package conflicts with its local spec, the code/tests are
   wrong and must be updated to match the spec.
 - Cross-package changes (e.g. coordinax → coordinax-hypothesis) MUST keep all
@@ -149,6 +152,11 @@ Instructions:
   - cross-reference them in docstrings and comments where appropriate,
   - update them whenever public semantics change.
 
+- Any new transform or role must include:
+  - spec-compliance checklist items (in PR description or doc),
+  - concise doctest-like examples where appropriate,
+  - property-based tests (prefer `coordinax-hypothesis`).
+
 - Never "patch around" a failing spec-driven test. Fix the implementation or
   revise the spec explicitly.
 

.pre-commit-config.yaml

@@ -74,17 +74,6 @@ repos:
         types_or: [yaml, markdown, html, css, scss, javascript, json]
         args: [--prose-wrap=always]
 
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: "v1.19.1"
-    hooks:
-      - id: mypy
-        files: src
-        additional_dependencies:
-          - optional_dependencies
-          - plum-dispatch
-          - quaxed
-          - quax-blocks
-
   - repo: https://github.com/codespell-project/codespell
     rev: "v2.4.1"
     hooks:

README.md

@@ -44,8 +44,8 @@ pip install coordinax
   dimensions). A rep does not store numerical values.
 - Vector: data + rep + role. Data are the coordinate values or physical
   components.
-- Role: semantic interpretation of vector data (Pos, Vel, PhysAcc, etc.). A role is
-  not a rep.
+- Role: semantic interpretation of vector data (Pos, Vel, PhysAcc, etc.). A role
+  is not a rep.
 - Metric: a bilinear form g on the tangent space defining inner products and
   norms (Euclidean, sphere intrinsic, Minkowski).
 - Physical components: components of a geometric vector expressed in an
@@ -84,7 +84,7 @@ We can also transform physical vector components between reps:
 
 ```
 v = {"x": u.Q(4.0, "km/s"), "y": u.Q(5.0, "km/s"), "z": u.Q(6.0, "km/s")}
-v_sph = cxt.tangent_transform(cxc.sph3d, cxc.cart3d, v, at=q)
+v_sph = cxt.physical_tangent_transform(cxc.sph3d, cxc.cart3d, v, at=q)
 ```
 
 ## Metrics
@@ -148,12 +148,12 @@ bool(
 
 Different vector roles transform via different mechanisms:
 
-| Role           | Transformation                      | Requires Base Point? |
-| -------------- | ----------------------------------- | -------------------- |
-| `Point`        | Position transform (coordinate map) | No                   |
-| `PhysDisp`     | Tangent transform (physical vector) | Sometimes[^1]        |
-| `PhysVel`      | Tangent transform (physical vector) | Sometimes[^1]        |
-| `PhysAcc`      | Tangent transform (physical vector) | Sometimes[^1]        |
+| Role       | Transformation                      | Requires Base Point? |
+| ---------- | ----------------------------------- | -------------------- |
+| `Point`    | Position transform (coordinate map) | No                   |
+| `PhysDisp` | Tangent transform (physical vector) | Sometimes[^1]        |
+| `PhysVel`  | Tangent transform (physical vector) | Sometimes[^1]        |
+| `PhysAcc`  | Tangent transform (physical vector) | Sometimes[^1]        |
 
 [^1]:
     Required when converting between representations (e.g., Cartesian ↔
@@ -162,9 +162,9 @@ Different vector roles transform via different mechanisms:
 
 ## PointedVector: Ergonomic Tangent Vector Conversions
 
-`PointedVector` provides a container for vectors anchored at a common base point,
-automatically managing the base point dependency required for tangent vector
-transformations:
+`PointedVector` provides a container for vectors anchored at a common base
+point, automatically managing the base point dependency required for tangent
+vector transformations:
 
 ```
 import coordinax as cx
@@ -236,25 +236,24 @@ d_sum = d1.add(d2)  # role is Displacement
 disp_from_origin = cx.as_pos(new_pos)
 ```
 
-| Operation                     | Result         | Allowed? |
-| ----------------------------- | -------------- | -------- |
-| `PhysDisp + PhysDisp`         | `PhysDisp`     | ✅       |
-| `Point + PhysDisp`            | `Point`        | ✅       |
-| `PhysDisp + Point`            | —              | ❌       |
-| `Point + Point`               | —              | ❌       |
+| Operation             | Result     | Allowed? |
+| --------------------- | ---------- | -------- |
+| `PhysDisp + PhysDisp` | `PhysDisp` | ✅       |
+| `Point + PhysDisp`    | `Point`    | ✅       |
+| `PhysDisp + Point`    | —          | ❌       |
+| `Point + Point`       | —          | ❌       |
 
 > **⚠️ Critical: Physical Components with Uniform Units**
 >
-> `PhysDisp` stores **physical vector components in an orthonormal frame**,
-> not coordinate increments. All components must have uniform dimension
-> `[length]`.
+> `PhysDisp` stores **physical vector components in an orthonormal frame**, not
+> coordinate increments. All components must have uniform dimension `[length]`.
 >
 > For example, in cylindrical coordinates:
 >
 > - ✅ **Correct**: `PhysDisp(rho=1m, phi=2m, z=3m)` — physical components,
 >   where `phi=2m` means "2 meters in the tangential direction"
-> - ❌ **Wrong**: `PhysDisp(rho=1m, phi=0.5rad, z=3m)` — coordinate
->   increments with mixed units
+> - ❌ **Wrong**: `PhysDisp(rho=1m, phi=0.5rad, z=3m)` — coordinate increments
+>   with mixed units
 >
 > This applies to all tangent vectors (`PhysDisp`, `PhysVel`, `PhysAcc`), which
 > transform via orthonormal frame transformations, not coordinate chart

docs/api/embeddings.md

@@ -45,9 +45,9 @@ The `EmbeddedManifold` class represents a manifold embedded in an ambient space:
 
 ```python
 embed = cxc.EmbeddedManifold(
-    intrinsic_chart=intrinsic,  # Chart on the manifold
-    ambient_chart=ambient,  # Chart in the ambient space
-    params={"R": radius},  # Parameters (e.g., radius)
+    intrinsic_chart=cxc.twosphere,  # Chart on the manifold
+    ambient_chart=cxc.cart3d,  # Chart in the ambient space
+    params={"R": u.Q(1.0, "km")},  # Parameters (e.g., radius)
 )
 ```
 

docs/api/metrics.md

@@ -25,6 +25,10 @@ metric = cxm.metric_of(cxc.cart3d)
 # Compute the metric matrix at a point
 p = {"x": u.Q(1, "km"), "y": u.Q(2, "km"), "z": u.Q(3, "km")}
 g = metric.metric_matrix(cxc.cart3d, p)
+
+# Compute the norm of a vector
+v = {"x": u.Q(3, "m"), "y": u.Q(4, "m"), "z": u.Q(0, "m")}
+magnitude = cxm.norm(metric, cxc.cart3d, v)  # Returns 5 m
 ```
 
 ## Built-in Metrics
@@ -48,21 +52,31 @@ metric = cxm.metric_of(cxc.cart3d)
 sphere_metric = cxm.metric_of(cxc.twosphere)
 ```
 
-### Index Raising and Lowering
+### Computing Norms
+
+The `norm` function computes the magnitude of a vector using the metric tensor:
 
 ```python
-# Raise an index (covariant to contravariant)
-v_up = cxm.raise_index(metric, chart, v_down, at=p)
+import coordinax.charts as cxc
+import coordinax.metrics as cxm
+import unxt as u
 
-# Lower an index (contravariant to covariant)
-v_down = cxm.lower_index(metric, chart, v_up, at=p)
+# Euclidean norm (position-independent)
+metric = cxm.metric_of(cxc.cart3d)
+v = {"x": u.Q(3, "m"), "y": u.Q(4, "m"), "z": u.Q(0, "m")}
+magnitude = cxm.norm(metric, cxc.cart3d, v)  # 5 m
 ```
 
-### Computing Norms
+For curved metrics like the sphere, the norm depends on position:
 
 ```python
-# Compute the norm of a vector using the metric
-norm = cxm.norm(metric, chart, v, at=p)
+import jax.numpy as jnp
+
+# On a sphere, the metric varies with latitude
+sphere_metric = cxm.metric_of(cxc.twosphere)
+p = {"theta": u.Angle(jnp.pi / 2, "rad"), "phi": u.Angle(0, "rad")}
+v = {"theta": u.Q(1, "rad/s"), "phi": u.Q(1, "rad/s")}
+magnitude = cxm.norm(sphere_metric, cxc.twosphere, v, at=p)
 ```
 
 ```{eval-rst}

docs/api/objs.md

@@ -21,7 +21,7 @@ import unxt as u
 q = cx.Vector(
     data={"x": u.Q(1.0, "kpc"), "y": u.Q(2.0, "kpc"), "z": u.Q(3.0, "kpc")},
     chart=cx.charts.cart3d,
-    role=cx.roles.phys_disp,
+    role=cx.roles.point,
 )
 
 # Create a velocity vector
@@ -41,7 +41,7 @@ space = cx.PointedVector(base=q, speed=v)
 # Attach to a frame
 import coordinax.frames as cxf
 
-coord = cxf.Coordinate({"length": q, "speed": v}, frame=cxf.ICRS())
+coord = cx.Coordinate({"base": q, "speed": v}, frame=cxf.ICRS())
 ```
 
 ## Vector
@@ -53,7 +53,7 @@ The `Vector` class is the primary object for representing geometric vectors:
 q = cx.Vector(
     data={"x": u.Q(1.0, "kpc"), "y": u.Q(2.0, "kpc"), "z": u.Q(3.0, "kpc")},
     chart=cx.charts.cart3d,
-    role=cx.roles.phys_disp,
+    role=cx.roles.point,
 )
 
 # From array (auto-detect chart and role)
@@ -62,6 +62,8 @@ q = cx.Vector.from_([1, 2, 3], "kpc")
 # From array with explicit chart and role
 v = cx.Vector.from_([10, 20, 30], "km/s", cx.charts.cart3d, cx.roles.phys_vel)
 
+a = cx.Vector.from_([0.1, 0.2, 0.3], "m/s^2", cx.charts.cart3d, cx.roles.phys_acc)
+
 # Access components
 print(q["x"])  # Quantity
 print(q.data)  # Full data dict
@@ -76,15 +78,15 @@ print(q.role)  # Role instance
 
 ## PointedVector
 
-The `PointedVector` class groups related vectors (position, velocity, acceleration)
-at a common point:
+The `PointedVector` class groups related vectors (position, velocity,
+acceleration) at a common point:
 
 ```python
 space = cx.PointedVector(base=q, speed=v, acceleration=a)
 
 # Access vectors
 space.base  # position
-space.speed  # velocity
+space["speed"]  # velocity
 ```
 
 ## Coordinate
@@ -94,7 +96,7 @@ The `Coordinate` class attaches vectors to a reference frame:
 ```python
 import coordinax.frames as cxf
 
-coord = cxf.Coordinate({"length": q, "speed": v}, frame=cxf.ICRS())
+coord = cx.Coordinate({"base": q, "speed": v}, frame=cxf.ICRS())
 
 # Transform to another frame
 coord_gc = coord.to_frame(cxf.Galactocentric())
@@ -121,7 +123,7 @@ Convert a Point role to a PhysDisp role (interpret location as displacement from
 origin):
 
 ```python
-pos = cx.as_pos(point_vector)
+pos = cx.as_pos(q)  # q is a Point vector defined above
 ```
 
 ```{eval-rst}

docs/api/roles.md

@@ -8,13 +8,15 @@ meaning of vectors.
 A **role** defines what a vector represents mathematically and physically:
 
 - **Point**: A location in space (affine, not a vector space element)
-- **Pos** (Position): A displacement vector from an origin
-- **Vel** (Velocity): A tangent vector representing rate of change of position
-- **PhysAcc** (Acceleration): A tangent vector representing rate of change of
-  velocity
+- **PhysDisp**: A physical displacement (tangent) vector in an orthonormal frame
+- **PhysVel**: A physical velocity (tangent) vector in an orthonormal frame
+- **PhysAcc**: A physical acceleration (tangent) vector in an orthonormal frame
+- **CoordDisp / CoordVel / CoordAcc**: Coordinate-basis tangent components in a
+  chart basis
 
 Roles determine transformation laws: positions transform as points, while
-velocities transform using the Jacobian of the coordinate transformation.
+tangent vectors transform using the Jacobian (and, for physical roles, the local
+orthonormal frame), evaluated at a base point `at=`.
 
 ## Quick Start
 
@@ -24,9 +26,10 @@ import coordinax.roles as cxr
 
 # Use predefined role instances
 point = cxr.point  # Point role
-pos = cxr.phys_disp  # Position role
+pos = cxr.phys_disp  # Physical displacement role
 vel = cxr.phys_vel  # Velocity role
 acc = cxr.phys_acc  # Acceleration role
+coord_vel = cxr.coord_vel  # Coordinate-basis velocity role
 
 # Or instantiate classes directly
 point_role = cxr.Point()
@@ -38,21 +41,26 @@ pos_role = cxr.PhysDisp()
 ```
 AbstractRole
 ├── Point         # Affine location (transforms via point_transform)
-└── AbstractPhysicalRole
-    ├── PhysDisp       # Position/displacement (transforms via point_transform)
-    ├── PhysVel       # Velocity (transforms via physical_tangent_transform)
-    └── PhysAcc       # Acceleration (transforms via physical_tangent_transform)
+├── AbstractPhysRole
+│   ├── PhysDisp       # Physical displacement (physical_tangent_transform; needs at=)
+│   ├── PhysVel        # Physical velocity (physical_tangent_transform; needs at=)
+│   └── PhysAcc        # Physical acceleration (physical_tangent_transform; needs at=)
+└── AbstractCoordRole
+    ├── CoordDisp      # Coordinate-basis displacement (coord_transform; needs at=)
+    ├── CoordVel       # Coordinate-basis velocity (coord_transform; needs at=)
+    └── CoordAcc       # Coordinate-basis acceleration (coord_transform; needs at=)
 ```
 
 ## Role Semantics
 
-### Point vs Pos
+### Point vs PhysDisp
 
 - **Point**: An absolute location; cannot be added to other points
-- **Pos**: A displacement from an origin; forms a vector space
+- **PhysDisp**: A physical displacement vector in a tangent space; can translate
+  a point
 
-Use `as_pos(point)` to convert a Point to a PhysDisp (interpreting the point as a
-displacement from the origin).
+Use `as_pos(point)` to convert a Point to a PhysDisp (interpreting the point as
+a displacement from the origin).
 
 ### Physical Roles (Vel, PhysAcc)
 
@@ -63,22 +71,36 @@ Jacobian of the coordinate transformation, not by simple coordinate conversion.
 import coordinax as cx
 import unxt as u
 
-q = cx.Vector.from_(
+p = cx.Vector.from_(
     {"x": u.Q(1, "kpc"), "y": u.Q(2, "kpc"), "z": u.Q(3, "kpc")},
     cx.charts.cart3d,
-    cx.roles.phys_disp,
+    cx.roles.point,
 )
 v = cx.Vector.from_(
     {"x": u.Q(10, "km/s"), "y": u.Q(20, "km/s"), "z": u.Q(30, "km/s")},
     cx.charts.cart3d,
     cx.roles.phys_vel,
 )
 
-# Position converts directly
-q_sph = q.vconvert(cx.charts.sph3d)
-
 # Velocity requires the base point for correct transformation
-v_sph = v.vconvert(cx.charts.sph3d, q)
+v_sph = v.vconvert(cx.charts.sph3d, p)
+```
+
+### Coordinate-Basis Roles
+
+Coordinate-basis tangent roles (`CoordDisp`, `CoordVel`, `CoordAcc`) transform
+by the Jacobian pushforward and also require a base point `at=`:
+
+```python
+import coordinax as cx
+import coordinax.charts as cxc
+import coordinax.roles as cxr
+import unxt as u
+
+at = {"x": u.Q(1.0, "m"), "y": u.Q(0.0, "m")}
+v = {"x": u.Q(2.0, "m/s"), "y": u.Q(0.0, "m/s")}
+
+v_pol = cx.vconvert(cxr.coord_vel, cxc.polar2d, cxc.cart2d, v, at=at)
 ```
 
 ```{eval-rst}