feat: DimensionSystem and decomposition

Signed-off-by: Nathaniel Starkman <[email protected]>

Author: nstarman

src/metrology_apis/__init__.py

@@ -17,6 +17,70 @@ def __pow__(self, other: int, /) -> Self: ...
     def __rmul__(self, other: Self, /) -> Self: ...
     def __rtruediv__(self, other: Self, /) -> Self: ...
 
+    def decompose(self, dimension_system: "DimensionSystem", /) -> "dict[Dimension, float | int]":
+        """Decompose the dimension into its base dimensions and exponents.
+
+        Parameters
+        ----------
+        dimension_system
+            The dimension system to use for decomposition. This defines the base
+            dimensions.
+
+        Notes
+        -----
+        By far the most common dimension system is (Length, Mass, Time, Electric
+        Current, Temperature, Amount of Substance, Luminous Intensity).
+        Implementing libraries are free to make this the default dimension
+        system and to set it as the default value in their ``decompose`` method.
+
+        Examples
+        --------
+        As this is an API protocol, no runtime examples are possible. The
+        following is an illustrative example:
+
+        >>> import metrology as u
+
+        >>> dim = u.Length / u.Time
+
+        >>> dim_sys = u.DimensionSystem(u.Length, u.Time)
+        >>> dim.decompose(dim_sys)
+        {Length: 1, Time: -1}
+
+        >>> dim_sys = u.DimensionSystem(u.Velocity)
+        >>> dim.decompose(dim_sys)
+        {Velocity: 1}
+
+        """
+        ...
+
+
+@runtime_checkable
+class DimensionSystem(Protocol):
+    """A system of dimensions.
+
+    This is a collection of base dimensions. Most unit systems, like the
+    International System of Units, have a dimension system involving Length,
+    Mass, Time, Electric Current, Temperature Amount of Substance, and Luminous
+    Intensity. However, other dimension systems are possible, such as 'natural'
+    systems where the speed of light is set to 1. The `DimensionsSystem` class
+    is the API for any choice of dimension system.
+
+    Examples
+    --------
+    As this is an API protocol, no runtime examples are possible. The following
+    is an illustrative example:
+
+    >>> import metrology as u
+
+    >>> dim_sys = u.DimensionSystem(u.Length, u.Time)
+
+    >>> dim_sys = u.DimensionSystem(u.Velocity)
+
+    """
+
+    base_dimensions: tuple[Dimension, ...]
+    """The base dimensions of the system."""
+
 
 @runtime_checkable
 class Unit(Protocol):