docs: add FreqRange, FrequencyUtils, frequencies and wavelengths to utilities.rst

Author: George-Guryev-flxcmp

docs/api/utils.rst renamed to docs/api/utilities.rst

@@ -9,6 +9,6 @@ Utilities
 
    tidy3d.RunTimeSpec
    tidy3d.FreqRange
-   tidy3d.FreqUtils
+   tidy3d.FrequencyUtils
    tidy3d.frequencies
    tidy3d.wavelengths

tidy3d/__init__.py

@@ -208,7 +208,7 @@
 from .components.field_projection import FieldProjector
 
 # frequency conversion utilities
-from .components.frequencies import FreqRange, frequencies, wavelengths
+from .components.frequencies import FreqRange, FrequencyUtils, frequencies, wavelengths
 
 # geometry
 from .components.geometry.base import Box, ClipOperation, Geometry, GeometryGroup, Transformed
@@ -544,6 +544,7 @@ def set_logging_level(level: str) -> None:
     "FluxTimeMonitor",
     "FossumCarrierLifetime",
     "FreqRange",
+    "FrequencyUtils",
     "FullyAnisotropicMedium",
     "GaussianBeam",
     "GaussianBeamProfile",

tidy3d/components/frequencies.py

@@ -20,7 +20,7 @@
 
 
 class FrequencyUtils(Tidy3dBaseModel):
-    """Class for general frequency/wavelength utilities."""
+    """Utilities for classifying frequencies/wavelengths and generating samples for standard optical bands."""
 
     use_wavelength: bool = pd.Field(
         False,
@@ -235,6 +235,16 @@ def u_band(self, n: int = 11) -> list[float]:
 frequencies = FrequencyUtils(use_wavelength=False)
 wavelengths = FrequencyUtils(use_wavelength=True)
 
+frequencies.__doc__ = (
+    "Frequency utilities configured to interpret and return values in hertz (Hz). "
+    "Use for RF, microwave, optical, and other band classifications in frequency units."
+)
+
+wavelengths.__doc__ = (
+    "Frequency utilities configured to interpret and return values in micrometers (μm). "
+    "Use for optical and photonic calculations where wavelength units are preferred."
+)
+
 
 class FreqRange(Tidy3dBaseModel):
     """