feat(lib): FSPL and path gain

differt/src/differt/em/__init__.py

@@ -16,6 +16,7 @@
     "diffraction_coefficients",
     "epsilon_0",
     "fresnel_coefficients",
+    "fspl",
     "lengths_to_delays",
     "materials",
     "mu_0",
@@ -51,6 +52,7 @@
 from ._material import Material, materials
 from ._utd import F, L_i, diffraction_coefficients
 from ._utils import (
+    fspl,
     lengths_to_delays,
     path_delays,
     sp_directions,

differt/src/differt/em/_fresnel.py

@@ -244,10 +244,11 @@ def reflection_coefficients(
            ground.
 
            >>> from differt.em import (
-           ...     c,
-           ...     reflection_coefficients,
            ...     Dipole,
+           ...     c,
+           ...     fspl,
            ...     pointing_vector,
+           ...     reflection_coefficients,
            ...     sp_directions,
            ... )
            >>> from differt.geometry import normalize
@@ -291,6 +292,8 @@ def reflection_coefficients(
            :context: close-figs
 
            Next, we compute the EM fields from the direct (line-of-sight) path.
+           We also plot the free-space path loss (see :func:`fspl<differt.em.fspl>` :cite:`fspl`)
+           as a reference.
 
            >>> # [num_positions 3]
            >>> E_los, B_los = ant.fields(rx_positions - tx_position)
@@ -301,6 +304,13 @@ def reflection_coefficients(
            ...     10 * jnp.log10(P_los / ant.average_power),
            ...     label=r"$P_\text{los}$",
            ... )  # doctest: +SKIP
+           >>> _, d = normalize(rx_positions - tx_position, keepdims=True)
+           >>> plt.semilogx(
+           ...     x,
+           ...     -fspl(d, ant.frequency, dB=True),
+           ...     "k-.",
+           ...     label="FSPL",
+           ... )  # doctest: +SKIP
 
            After, the :func:`image_method<differt.rt.image_method>`
            function is used to compute the reflection points.
@@ -397,7 +407,7 @@ def reflection_coefficients(
            ...     label=r"$P_\text{total}$",
            ... )  # doctest: +SKIP
            >>> plt.xlabel("Distance to transmitter on x-axis (m)")  # doctest: +SKIP
-           >>> plt.ylabel("Loss (dB)")  # doctest: +SKIP
+           >>> plt.ylabel("Gain (dB)")  # doctest: +SKIP
            >>> plt.legend()  # doctest: +SKIP
            >>> plt.tight_layout()  # doctest: +SKIP
 

differt/src/differt/em/_utils.py

@@ -1,3 +1,4 @@
+from functools import partial
 from typing import Any
 
 import jax
@@ -15,9 +16,9 @@
 @jax.jit
 @jaxtyped(typechecker=typechecker)
 def lengths_to_delays(
-    lengths: Float[Array, " *#batch"],
+    lengths: Float[ArrayLike, " *#batch"],
     speed: Float[ArrayLike, " *#batch"] = c,
-) -> Float[Array, " *#batch"]:
+) -> Float[Array, " *batch"]:
     """
     Compute the delay, in seconds, corresponding to each length.
 
@@ -45,7 +46,7 @@ def lengths_to_delays(
         >>> lengths_to_delays(lengths, speed=2.0)
         Array([0.5, 1. , 2. ], dtype=float32)
     """
-    return lengths / speed
+    return jnp.asarray(lengths) / jnp.asarray(speed)
 
 
 @jax.jit
@@ -345,3 +346,30 @@ def transition_matrices(
     mat = jnp.where(interaction_types == InteractionType.REFLECTION, mat_r, mat)
 
     return mat
+
+
+@partial(jax.jit, static_argnames=("dB",))
+@jaxtyped(typechecker=typechecker)
+def fspl(
+    d: Float[ArrayLike, " *#batch"],
+    f: Float[ArrayLike, " *#batch"],
+    *,
+    dB: bool = False,  # noqa: N803
+) -> Float[Array, " *batch"]:
+    """
+    Compute the free-space path loss (FSPL), optionally in dB.
+
+    See :cite:`fspl` for more information.
+
+    Args:
+        d: The array of distances (in meters).
+        f: The array frequencies (in Hertz).
+        dB: Whether to return the result in dB.
+
+    Returns:
+        The array of free-space path losses.
+    """
+    if dB:
+        return 20 * jnp.log10(d) + 20 * jnp.log10(f) - 147.55221677811662
+
+    return jax.lax.integer_pow(4 * jnp.pi * d * f / c, 2)

differt/tests/em/test_utils.py

@@ -3,12 +3,14 @@
 from contextlib import nullcontext as does_not_raise
 
 import chex
+import jax
 import jax.numpy as jnp
 import pytest
-from jaxtyping import Array
+from jaxtyping import Array, PRNGKeyArray
 
 from differt.em._constants import c
 from differt.em._utils import (
+    fspl,
     lengths_to_delays,
     path_delays,
     sp_directions,
@@ -132,3 +134,16 @@ def test_sp_rotation_matrix() -> None:
     chex.assert_trees_all_close(jnp.linalg.det(got_R), -1.0)
     chex.assert_trees_all_close(got_R, expected_R[:-1, :-1])
     chex.assert_trees_all_close(got_R @ got_R.mT, jnp.eye(2))
+
+
+def test_fspl(key: PRNGKeyArray) -> None:
+    key_d, key_f = jax.random.split(key, 2)
+    d = jax.random.uniform(key_d, (30, 1), minval=1.0, maxval=100.0)
+    f = jax.random.uniform(key_f, (1, 50), minval=0.1e9, maxval=10e9)
+
+    got = fspl(d, f)
+    got_db = fspl(d, f, dB=True)
+    expected_db = 20 * jnp.log10(d) + 20 * jnp.log10(f) - 147.55
+
+    chex.assert_trees_all_close(10 * jnp.log10(got), got_db)
+    chex.assert_trees_all_close(got_db, expected_db, rtol=2e-4)

docs/source/reference/differt.em.rst

@@ -110,6 +110,7 @@ Utility functions, mostly used internally for computing EM fields.
 .. autosummary::
    :toctree: _autosummary
 
+   fspl
    lengths_to_delays
    path_delays
    pointing_vector

docs/source/references.bib

@@ -91,6 +91,14 @@ @misc{fresnel-integrals
   note   = {[Online; accessed 8-March-2024]},
 }
 
+@misc{fspl,
+  author = {{Wikipedia contributors}},
+  title  = {Free-space path loss --- {Wikipedia}{,} The Free Encyclopedia},
+  year   = {2024},
+  url    = {https://en.wikipedia.org/w/index.php?title=Free-space\_path\_loss&oldid=1260213116},
+  note   = {[Online; accessed 13-January-2025]},
+}
+
 @misc{improper-rotation,
   author = {{Wikipedia contributors}},
   title  = {Improper rotation --- {Wikipedia}{,} The Free Encyclopedia},