WIP

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

Author: nstarman

.github/copilot-instructions.md

@@ -19,11 +19,11 @@ This is a UV workspace repository containing multiple packages:
 Before making _any_ change to:
 
 - charts / geometries
-- roles (Point / Pos / Vel / Acc)
+- roles (Point / PhysDisp / PhysVel / PhysAcc)
 - metrics
 - embeddings / manifolds
 - operators / reference frames
-- Vector / FiberPoint / Coordinate semantics
+- Vector / PointedVector / Coordinate semantics
 
 You MUST:
 
@@ -409,7 +409,7 @@ def add_p_vec_qty(lhs: Vector, rhs: Quantity, /) -> Vector:
     """Handle Vector + Quantity via desugaring to Vector + Vector."""
     # Desugar: convert Quantity to Vector with appropriate role
     if u.dimension_of(rhs) == u.dimension("length"):
-        rhs_vec = Vector.from_(rhs, r.Pos)
+        rhs_vec = Vector.from_(rhs, r.PhysDisp)
     else:
         rhs_vec = Vector.from_(rhs)
     return add(lhs.role, rhs_vec.role, lhs, rhs_vec, at=None)

README.md

@@ -44,7 +44,7 @@ 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, Acc, etc.). A role is
+- 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).
@@ -134,8 +134,8 @@ v = {
     "y": u.Q(5.0, "km/s"),
     "z": u.Q(6.0, "km/s"),
 }
-qvec = cx.Vector(data=q, chart=cx.charts.cart3d, role=cx.roles.Pos())
-vvec = cx.Vector(data=v, chart=cx.charts.cart3d, role=cx.roles.Vel())
+qvec = cx.Vector(data=q, chart=cx.charts.cart3d, role=cx.roles.PhysDisp())
+vvec = cx.Vector(data=v, chart=cx.charts.cart3d, role=cx.roles.PhysVel())
 v_sph = vvec.vconvert(cx.charts.sph3d, qvec)
 v_back = v_sph.vconvert(cx.charts.cart3d, qvec)
 bool(
@@ -150,19 +150,19 @@ Different vector roles transform via different mechanisms:
 
 | Role           | Transformation                      | Requires Base Point? |
 | -------------- | ----------------------------------- | -------------------- |
-| `Pos`          | Position transform (coordinate map) | No                   |
-| `Displacement` | Tangent transform (physical vector) | Sometimes[^1]        |
-| `Vel`          | Tangent transform (physical vector) | Sometimes[^1]        |
-| `Acc`          | Tangent transform (physical vector) | Sometimes[^1]        |
+| `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 ↔
     Spherical), not required for unit conversions within the same
     representation.
 
-## FiberPoint: Ergonomic Tangent Vector Conversions
+## PointedVector: Ergonomic Tangent Vector Conversions
 
-`FiberPoint` provides a container for vectors anchored at a common base point,
+`PointedVector` provides a container for vectors anchored at a common base point,
 automatically managing the base point dependency required for tangent vector
 transformations:
 
@@ -174,7 +174,7 @@ vel = cx.Vector.from_([10, 20, 30], "km/s")
 acc = cx.Vector.from_([0.1, 0.2, 0.3], "km/s^2")
 
 # Create bundle - base is explicit, fields are tangent vectors
-bundle = cx.FiberPoint(base=base, velocity=vel, acceleration=acc)
+bundle = cx.PointedVector(base=base, velocity=vel, acceleration=acc)
 
 # Convert entire bundle - automatically handles `at=` for tangent vectors
 sph_bundle = bundle.vconvert(cx.charts.sph3d)
@@ -188,13 +188,13 @@ sph_bundle = bundle.vconvert(cx.charts.sph3d)
 
 **Key features:**
 
-- Base must have role `Pos`; fields must not (enforced at construction)
+- Base must have role `PhysDisp`; fields must not (enforced at construction)
 - Automatic `at=` parameter handling for tangent transformations
 - JAX-compatible (works with `jax.jit`, `vmap`)
 - Physical components with uniform units (not coordinate derivatives)
 
 See the
-[FiberPoint guide](https://coordinax.readthedocs.io/en/latest/guides/anchored_vector_bundle.html)
+[PointedVector guide](https://coordinax.readthedocs.io/en/latest/guides/anchored_vector_bundle.html)
 for details.
 
 ## Vector Algebra: Points vs Displacements
@@ -238,33 +238,33 @@ disp_from_origin = cx.as_pos(new_pos)
 
 | Operation                     | Result         | Allowed? |
 | ----------------------------- | -------------- | -------- |
-| `Displacement + Displacement` | `Displacement` | ✅       |
-| `Pos + Displacement`          | `Pos`          | ✅       |
-| `Displacement + Pos`          | —              | ❌       |
-| `Pos + Pos`                   | —              | ❌       |
+| `PhysDisp + PhysDisp`         | `PhysDisp`     | ✅       |
+| `Point + PhysDisp`            | `Point`        | ✅       |
+| `PhysDisp + Point`            | —              | ❌       |
+| `Point + Point`               | —              | ❌       |
 
 > **⚠️ Critical: Physical Components with Uniform Units**
 >
-> `Displacement` stores **physical vector components in an orthonormal frame**,
+> `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**: `Displacement(rho=1m, phi=2m, z=3m)` — physical components,
+> - ✅ **Correct**: `PhysDisp(rho=1m, phi=2m, z=3m)` — physical components,
 >   where `phi=2m` means "2 meters in the tangential direction"
-> - ❌ **Wrong**: `Displacement(rho=1m, phi=0.5rad, z=3m)` — coordinate
+> - ❌ **Wrong**: `PhysDisp(rho=1m, phi=0.5rad, z=3m)` — coordinate
 >   increments with mixed units
 >
-> This applies to all tangent vectors (`Displacement`, `Vel`, `Acc`), which
+> This applies to all tangent vectors (`PhysDisp`, `PhysVel`, `PhysAcc`), which
 > transform via orthonormal frame transformations, not coordinate chart
 > transformations.
 
 ## Metrics and Representations
 
-Representations are coordinate charts; roles (Pos, Vel, Acc, ...) give vectors
-their physical meaning. A chart’s default metric defines how physical components
-are interpreted.
+Representations are coordinate charts; roles (PhysDisp, PhysVel, PhysAcc, ...)
+give vectors their physical meaning. A chart’s default metric defines how
+physical components are interpreted.
 
 - Euclidean charts are exposed in `cx.r` (Cart, Cylindrical, Spherical, etc.).
 - Manifold charts are exposed in `cx.r` (e.g. `TwoSphere`).

docs/api/objs.md

@@ -8,7 +8,7 @@ vectors and coordinates.
 This module contains the main user-facing objects:
 
 - **Vector**: A geometric vector with data, chart, and role
-- **FiberPoint**: A collection of related vectors anchored at a common point
+- **PointedVector**: A collection of related vectors anchored at a common point
 - **Coordinate**: A vector attached to a reference frame
 
 ## Quick Start
@@ -21,22 +21,22 @@ 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.pos,
+    role=cx.roles.phys_disp,
 )
 
 # Create a velocity vector
 v = cx.Vector(
     data={"x": u.Q(4.0, "kpc/Myr"), "y": u.Q(5.0, "kpc/Myr"), "z": u.Q(6.0, "kpc/Myr")},
     chart=cx.charts.cart3d,
-    role=cx.roles.vel,
+    role=cx.roles.phys_vel,
 )
 
 # Convert to spherical coordinates
 q_sph = q.vconvert(cx.charts.sph3d)
 v_sph = v.vconvert(cx.charts.sph3d, q)
 
 # Group related vectors
-space = cx.FiberPoint(base=q, speed=v)
+space = cx.PointedVector(base=q, speed=v)
 
 # Attach to a frame
 import coordinax.frames as cxf
@@ -53,14 +53,14 @@ 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.pos,
+    role=cx.roles.phys_disp,
 )
 
 # From array (auto-detect chart and role)
 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.vel)
+v = cx.Vector.from_([10, 20, 30], "km/s", cx.charts.cart3d, cx.roles.phys_vel)
 
 # Access components
 print(q["x"])  # Quantity
@@ -74,13 +74,13 @@ print(q.role)  # Role instance
 - `vconvert(to_chart, at=None)`: Convert to a different chart
 - `uconvert(units)`: Convert units of components
 
-## FiberPoint
+## PointedVector
 
-The `FiberPoint` class groups related vectors (position, velocity, acceleration)
+The `PointedVector` class groups related vectors (position, velocity, acceleration)
 at a common point:
 
 ```python
-space = cx.FiberPoint(base=q, speed=v, acceleration=a)
+space = cx.PointedVector(base=q, speed=v, acceleration=a)
 
 # Access vectors
 space.base  # position
@@ -117,7 +117,7 @@ v_sph = cx.vconvert(cx.charts.sph3d, v, q)
 
 ## as_pos Function
 
-Convert a Point role to a Pos role (interpret location as displacement from
+Convert a Point role to a PhysDisp role (interpret location as displacement from
 origin):
 
 ```python

docs/api/roles.md

@@ -10,7 +10,7 @@ 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
-- **Acc** (Acceleration): A tangent vector representing rate of change of
+- **PhysAcc** (Acceleration): A tangent vector representing rate of change of
   velocity
 
 Roles determine transformation laws: positions transform as points, while
@@ -24,13 +24,13 @@ import coordinax.roles as cxr
 
 # Use predefined role instances
 point = cxr.point  # Point role
-pos = cxr.pos  # Position role
-vel = cxr.vel  # Velocity role
-acc = cxr.acc  # Acceleration role
+pos = cxr.phys_disp  # Position role
+vel = cxr.phys_vel  # Velocity role
+acc = cxr.phys_acc  # Acceleration role
 
 # Or instantiate classes directly
 point_role = cxr.Point()
-pos_role = cxr.Pos()
+pos_role = cxr.PhysDisp()
 ```
 
 ## Role Hierarchy
@@ -39,9 +39,9 @@ pos_role = cxr.Pos()
 AbstractRole
 ├── Point         # Affine location (transforms via point_transform)
 └── AbstractPhysicalRole
-    ├── Pos       # Position/displacement (transforms via point_transform)
-    ├── Vel       # Velocity (transforms via physical_tangent_transform)
-    └── Acc       # Acceleration (transforms via physical_tangent_transform)
+    ├── PhysDisp       # Position/displacement (transforms via point_transform)
+    ├── PhysVel       # Velocity (transforms via physical_tangent_transform)
+    └── PhysAcc       # Acceleration (transforms via physical_tangent_transform)
 ```
 
 ## Role Semantics
@@ -51,10 +51,10 @@ AbstractRole
 - **Point**: An absolute location; cannot be added to other points
 - **Pos**: A displacement from an origin; forms a vector space
 
-Use `as_pos(point)` to convert a Point to a Pos (interpreting the point as a
+Use `as_pos(point)` to convert a Point to a PhysDisp (interpreting the point as a
 displacement from the origin).
 
-### Physical Roles (Vel, Acc)
+### Physical Roles (Vel, PhysAcc)
 
 Velocity and acceleration are **tangent vectors**. They transform using the
 Jacobian of the coordinate transformation, not by simple coordinate conversion.
@@ -66,12 +66,12 @@ import unxt as u
 q = cx.Vector.from_(
     {"x": u.Q(1, "kpc"), "y": u.Q(2, "kpc"), "z": u.Q(3, "kpc")},
     cx.charts.cart3d,
-    cx.roles.pos,
+    cx.roles.phys_disp,
 )
 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.vel,
+    cx.roles.phys_vel,
 )
 
 # Position converts directly

docs/api/transforms.md

@@ -121,7 +121,7 @@ Velocity transforms use the Jacobian:
 
 $$v'^i = \frac{\partial q'^i}{\partial q^j} v^j$$
 
-### Acceleration (Acc)
+### Acceleration (PhysAcc)
 
 Acceleration transforms include connection terms for correct geometric behavior.
 

docs/conventions.md

@@ -10,9 +10,9 @@ avoid verbosity. Many of these are also found in the [Glossary](glossary.md).
   Concrete (or 'final') classes are not so prefixed. As a further rule, no
   abstract class inherits from a concrete class and no concrete class inherits
   from any other concrete class.
-- `Pos`: a shorthand for "position", used in class names for concision.
-- `Vel`: a shorthand for "velocity", used in class names for concision.
-- `Acc`: a shorthand for "acceleration", used in class names for concision.
+- `PhysDisp`: a shorthand for "position", used in class names for concision.
+- `PhysVel`: a shorthand for "velocity", used in class names for concision.
+- `PhysAcc`: a shorthand for "acceleration", used in class names for concision.
 
 ## Functional vs Object-Oriented APIs