Support Differentials (#8)

* feat: AbstractVectorDifferential
* feat: Abstract1DVectorDifferential
* feat: CartesianDifferential1D, RadialDifferential
* feat: Abstract2DVectorDifferential
* feat: CartesianDifferential2D, PolarDifferential
* feat: Abstract3DVectorDifferential
* feat: CartesianDifferential3D, SphericalDifferential, CylindricalDifferential
* feat: support some differential transformations
* tests: add for all the differential classes
* ci: coverage ignores

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

pyproject.toml

@@ -81,9 +81,21 @@
 
 
 [tool.coverage]
-  report.exclude_also = ['\.\.\.', 'if typing.TYPE_CHECKING:']
   run.source = ["vector"]
 
+  [tool.coverage.report]
+    exclude_also = [
+      # Have to re-enable the standard pragma
+      'pragma: no cover',
+      # Ignore type-checking stuff
+      'if typing.TYPE_CHECKING:',
+      'if TYPE_CHECKING:',
+      '\.\.\.',
+      # Ignore contents of abstract methods
+      '@abc.abstractmethod',
+      '@abstractmethod',
+    ]
+
 [tool.mypy]
   disable_error_code = ["no-redef"]
   disallow_incomplete_defs = false

src/vector/_base.py

@@ -1,19 +1,34 @@
 """Representation of coordinates in different systems."""
 
-__all__ = ["AbstractVector"]
+__all__ = ["AbstractVector", "AbstractVectorDifferential"]
 
 from typing import Any, TypeVar
 
 import equinox as eqx
 
 T = TypeVar("T", bound="AbstractVector")
+DT = TypeVar("DT", bound="AbstractVectorDifferential")
 
 
 class AbstractVector(eqx.Module):  # type: ignore[misc]
     """Abstract representation of coordinates in different systems."""
 
-    def represent_as(self, target: type[T], **kwargs: Any) -> T:
+    def represent_as(self, target: type[T], /, **kwargs: Any) -> T:
         """Represent the vector as another type."""
         from ._transform import represent_as  # pylint: disable=import-outside-toplevel
 
         return represent_as(self, target, **kwargs)
+
+
+class AbstractVectorDifferential(eqx.Module):  # type: ignore[misc]
+    """Abstract representation of vector differentials in different systems."""
+
+    vector_cls: eqx.AbstractClassVar[type[AbstractVector]]
+
+    def represent_as(
+        self, target: type[DT], position: AbstractVector, /, **kwargs: Any
+    ) -> DT:
+        """Represent the vector as another type."""
+        from ._transform import represent_as  # pylint: disable=import-outside-toplevel
+
+        return represent_as(self, target, position, **kwargs)

src/vector/_d1/base.py

@@ -1,13 +1,18 @@
 """Representation of coordinates in different systems."""
 
-__all__ = ["Abstract1DVector"]
+__all__ = ["Abstract1DVector", "Abstract1DVectorDifferential"]
 
-from typing import TypeVar
 
-from vector._base import AbstractVector
+import equinox as eqx
 
-T = TypeVar("T", bound="AbstractVector")
+from vector._base import AbstractVector, AbstractVectorDifferential
 
 
 class Abstract1DVector(AbstractVector):
     """Abstract representation of 1D coordinates in different systems."""
+
+
+class Abstract1DVectorDifferential(AbstractVectorDifferential):
+    """Abstract representation of 1D differentials in different systems."""
+
+    vector_cls: eqx.AbstractClassVar[type[Abstract1DVector]]

src/vector/_d1/builtin.py

@@ -4,16 +4,19 @@
     # Position
     "Cartesian1DVector",
     "RadialVector",
+    # Differential
+    "CartesianDifferential1D",
+    "RadialDifferential",
 ]
 
-from typing import final
+from typing import ClassVar, final
 
 import equinox as eqx
 
 from vector._typing import BatchFloatScalarQ
 from vector._utils import converter_quantity_array
 
-from .base import Abstract1DVector
+from .base import Abstract1DVector, Abstract1DVectorDifferential
 
 ##############################################################################
 # Position
@@ -33,3 +36,27 @@ class RadialVector(Abstract1DVector):
 
     r: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
     """Radial coordinate."""
+
+
+##############################################################################
+# Velocity
+
+
+@final
+class CartesianDifferential1D(Abstract1DVectorDifferential):
+    """Cartesian differential representation."""
+
+    d_x: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+    """Differential d_x/d_<>."""
+
+    vector_cls: ClassVar[type[Cartesian1DVector]] = Cartesian1DVector  # type: ignore[misc]
+
+
+@final
+class RadialDifferential(Abstract1DVectorDifferential):
+    """Radial differential representation."""
+
+    d_r: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+    """Differential d_r/d_<>."""
+
+    vector_cls: ClassVar[type[RadialVector]] = RadialVector  # type: ignore[misc]

src/vector/_d2/base.py

@@ -1,13 +1,18 @@
 """Representation of coordinates in different systems."""
 
-__all__ = ["Abstract2DVector"]
+__all__ = ["Abstract2DVector", "Abstract2DVectorDifferential"]
 
-from typing import TypeVar
 
-from vector._base import AbstractVector
+import equinox as eqx
 
-T = TypeVar("T", bound="AbstractVector")
+from vector._base import AbstractVector, AbstractVectorDifferential
 
 
 class Abstract2DVector(AbstractVector):
     """Abstract representation of 2D coordinates in different systems."""
+
+
+class Abstract2DVectorDifferential(AbstractVectorDifferential):
+    """Abstract representation of 2D vector differentials."""
+
+    vector_cls: eqx.AbstractClassVar[type[Abstract2DVector]]

src/vector/_d2/builtin.py

@@ -1,20 +1,24 @@
 """Built-in vector classes."""
 
 __all__ = [
+    # Position
     "Cartesian2DVector",
     "PolarVector",
     # "LnPolarVector",
     # "Log10PolarVector",
+    # Differential
+    "CartesianDifferential2D",
+    "PolarDifferential",
 ]
 
-from typing import final
+from typing import ClassVar, final
 
 import equinox as eqx
 
 from vector._typing import BatchFloatScalarQ
 from vector._utils import converter_quantity_array
 
-from .base import Abstract2DVector
+from .base import Abstract2DVector, Abstract2DVectorDifferential
 
 # =============================================================================
 # 2D
@@ -51,3 +55,26 @@ class PolarVector(Abstract2DVector):
 
 #     log10r: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
 #     theta: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+
+
+##############################################################################
+
+
+@final
+class CartesianDifferential2D(Abstract2DVectorDifferential):
+    """Cartesian differential representation."""
+
+    d_x: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+    d_y: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+
+    vector_cls: ClassVar[type[Cartesian2DVector]] = Cartesian2DVector  # type: ignore[misc]
+
+
+@final
+class PolarDifferential(Abstract2DVectorDifferential):
+    """Polar differential representation."""
+
+    d_r: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+    d_phi: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+
+    vector_cls: ClassVar[type[PolarVector]] = PolarVector  # type: ignore[misc]

src/vector/_d3/base.py

@@ -1,13 +1,18 @@
 """Representation of coordinates in different systems."""
 
-__all__ = ["Abstract3DVector"]
+__all__ = ["Abstract3DVector", "Abstract3DVectorDifferential"]
 
-from typing import TypeVar
 
-from vector._base import AbstractVector
+import equinox as eqx
 
-T = TypeVar("T", bound="AbstractVector")
+from vector._base import AbstractVector, AbstractVectorDifferential
 
 
 class Abstract3DVector(AbstractVector):
     """Abstract representation of 3D coordinates in different systems."""
+
+
+class Abstract3DVectorDifferential(AbstractVectorDifferential):
+    """Abstract representation of 3D vector differentials."""
+
+    vector_cls: eqx.AbstractClassVar[type[Abstract3DVector]]

src/vector/_d3/builtin.py

@@ -1,19 +1,24 @@
 """Built-in vector classes."""
 
 __all__ = [
+    # Position
     "Cartesian3DVector",
     "SphericalVector",
     "CylindricalVector",
+    # Differential
+    "CartesianDifferential3D",
+    "SphericalDifferential",
+    "CylindricalDifferential",
 ]
 
-from typing import final
+from typing import ClassVar, final
 
 import equinox as eqx
 
 from vector._typing import BatchFloatScalarQ
 from vector._utils import converter_quantity_array
 
-from .base import Abstract3DVector
+from .base import Abstract3DVector, Abstract3DVectorDifferential
 
 ##############################################################################
 # Position
@@ -44,3 +49,40 @@ class CylindricalVector(Abstract3DVector):
     rho: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
     phi: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
     z: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+
+
+##############################################################################
+# Differential
+
+
+@final
+class CartesianDifferential3D(Abstract3DVectorDifferential):
+    """Cartesian differential representation."""
+
+    d_x: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+    d_y: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+    d_z: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+
+    vector_cls: ClassVar[type[Cartesian3DVector]] = Cartesian3DVector  # type: ignore[misc]
+
+
+@final
+class SphericalDifferential(Abstract3DVectorDifferential):
+    """Spherical differential representation."""
+
+    d_r: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+    d_theta: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+    d_phi: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+
+    vector_cls: ClassVar[type[SphericalVector]] = SphericalVector  # type: ignore[misc]
+
+
+@final
+class CylindricalDifferential(Abstract3DVectorDifferential):
+    """Cylindrical differential representation."""
+
+    d_rho: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+    d_phi: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+    d_z: BatchFloatScalarQ = eqx.field(converter=converter_quantity_array)
+
+    vector_cls: ClassVar[type[CylindricalVector]] = CylindricalVector  # type: ignore[misc]