✨ feat: tangent representations

[nstarman]

No description provided.

[Copilot]

Pull request overview

Adds first-class tangent (vector) representations to Coordinax, including new geometry/basis/semantic kinds and a Jacobian-based tangent_map, then wires these into cconvert, docs/specs, and the Hypothesis strategy layer.

Changes:

• Introduces TangentGeometry, linear bases (CoordinateBasis, PhysicalBasis), tangent semantic kinds (Displacement, Velocity, Acceleration), and canonical tangent Representation singletons.
• Adds tangent_map (Jacobian pushforward) and a v1 change_basis API; integrates tangent conversions into cconvert.
• Expands tests and documentation/specs to cover the new tangent surface area.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
tests/unit/representations/init.py	Adds unit-test package marker for representations tests.
tests/unit/representations/test_basis_linear.py	Tests new linear basis kinds and exports.
tests/unit/representations/test_cconvert_tangent.py	Tests cconvert routing for TangentGeometry.
tests/unit/representations/test_change_basis.py	Tests new change_basis API and dispatch behavior.
tests/unit/representations/test_geom_tangent.py	Tests TangentGeometry kind + singleton export behavior.
tests/unit/representations/test_semantics_tangent.py	Tests tangent semantic kinds + time-order ladder behavior.
tests/unit/representations/test_tangent_map.py	Adds core unit tests for tangent_map behavior + JAX compat.
tests/unit/representations/test_tangent_map_properties.py	Adds property-based tests for tangent_map invariants and cconvert integration.
tests/unit/representations/test_tangent_singletons.py	Tests canonical tangent Representation singletons.
src/coordinax/charts/_src/jacobian_pt_map.py	Relaxes usys typing to OptUSys for curried form.
src/coordinax/main/init.py	Re-exports new tangent types/functions from coordinax.main.
src/coordinax/representations/init.py	Public API exports for tangent kinds, singletons, and new functions.
src/coordinax/representations/_src/init.py	Imports tangent_map into internal package surface.
src/coordinax/representations/_src/basis.py	Adds AbstractLinearBasis, CoordinateBasis, PhysicalBasis + singletons.
src/coordinax/representations/_src/constants.py	Adds speed/acceleration/time dimension constants.
src/coordinax/representations/_src/core.py	Adds change_basis; adds tangent cconvert dispatch and threads at.
src/coordinax/representations/_src/geom.py	Adds TangentGeometry + tangent_geom singleton.
src/coordinax/representations/_src/guess.py	Extends guessing logic for tangent dims/semantics + tangent guess_rep dispatch.
src/coordinax/representations/_src/rep.py	Adds canonical tangent representation singletons + canonical name map entries.
src/coordinax/representations/_src/semantics.py	Adds tangent semantic kinds, d_dt_dim, and ladder/derivative helpers.
src/coordinax/representations/_src/tangent_map.py	Implements tangent_map (4-arg + 7-arg dispatch) with unit-aware Jacobian application.
src/coordinax/transforms/_src/actions/rotate.py	Adds Rotate action dispatch for TangentGeometry.
src/coordinax/transforms/_src/actions/translate.py	Changes Translate semantic_kind field default/type.
packages/coordinax.api/src/coordinax/api/representations.py	Adds abstract API declarations for change_basis and tangent_map.
packages/coordinax.hypothesis/src/coordinax/hypothesis/representations/_src/cdict.py	Adds TangentGeometry handling/validation in cdict strategies.
packages/coordinax.hypothesis/src/coordinax/hypothesis/representations/_src/reps.py	Adds TangentGeometry restrictions for basis/semantic strategy generation.
packages/coordinax.hypothesis/tests/unit/representations/test_cdicts.py	Adds strategy tests for tangent representations.
packages/coordinax.hypothesis/tests/unit/representations/test_representations.py	Adds tests for valid basis/semantic classes for TangentGeometry and strategy restrictions.
docs/api/representations.md	Documents change_basis, tangent bases, and tangent notes.
docs/guides/representations.md	Adds guide section for tangent basis changes.
docs/spec.md	Extends spec with tangent-map and tangent representation semantics and exported objects list.
docs/tutorials/cdict_objects.md	Adds tutorial section for change_basis.
README.md	Updates README to mention tangent representations.

Comments suppressed due to low confidence (1)

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

• tangent_map is defined as an abstract API in this file, but it’s not included in __all__. That makes it inconsistent with the other public abstract functions and can break from coordinax.api.representations import * / docs tooling. Consider adding "tangent_map" to __all__ alongside cconvert and change_basis.

__all__ = (
    "add",
    "cconvert",
    "change_basis",
    "guess_basis_kind",
    "guess_geometry_kind",
    "guess_rep",
    "guess_semantic_kind",
    "subtract",
)

[codecov]

Codecov Report

❌ Patch coverage is 95.38462% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.31%. Comparing base (58e18ad) to head (cb44f2f).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/coordinax/representations/_src/tangent_map.py	93.18%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #495      +/-   ##
==========================================
+ Coverage   92.29%   92.31%   +0.02%     
==========================================
  Files         217      218       +1     
  Lines        6576     6633      +57     
==========================================
+ Hits         6069     6123      +54     
- Misses        507      510       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.