Add sdr.power()

src/sdr/_measurement/_power.py

@@ -11,6 +11,37 @@
 from .._helper import convert_output, export, verify_arraylike, verify_bool
 
 
+@export
+def power(
+    x: npt.ArrayLike,
+    db: bool = False,
+) -> float:
+    r"""
+    Measures the instantaneous power of a time-domain signal $x[n]$.
+
+    $$P = \left| x[n] \right|^2$$
+
+    Arguments:
+        x: The time-domain signal $x[n]$ to measure.
+        db: Indicates whether to return the result in decibels (dB).
+
+    Returns:
+        The instantaneous power. If `db=False`, $P$ is returned.
+        If `db=True`, $10 \log_{10} P$ is returned.
+
+    Group:
+        measurement-power
+    """
+    x = verify_arraylike(x, complex=True)
+    verify_bool(db)
+
+    P = np.abs(x) ** 2
+    if db:
+        P = to_db(P, type="power")
+
+    return convert_output(P)
+
+
 @export
 def peak_power(
     x: npt.ArrayLike,

tests/measurements/test_power.py

@@ -4,6 +4,14 @@
 import sdr
 
 
+def test_power():
+    rng = np.random.default_rng()
+    A = rng.uniform(2, 10)  # Signal amplitude
+    N = 50
+    x = A * np.exp(1j * np.linspace(0, 2 * np.pi, N, endpoint=False))
+    assert np.allclose(sdr.power(x), A**2)
+
+
 def test_peak_power():
     rng = np.random.default_rng()
     A = rng.uniform(2, 10)  # Signal amplitude