Add FreqRange utility class and unit tests

George-Guryev · George-Guryev · commit d354c666967f · 2025-06-05T00:04:29.000-04:00
Includes methods for frequency/wavelength conversion, interval updates, and sampling. Adds test coverage for main methods.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Implemented `FreqRange` utility class for frequency/wavelength handling; the default constructor and `from_interval()` class method assume, that the central frequency `freq0` is defined to be `freq0 = (fmin + fmax) / 2`; class methods `from_wavelength()` and `from_wavelegth_interval()` assume that the central wavelength `lda0` is defined to be `lda0 = (lda_min + lda_max) / 2`. 
+- Added methods to initialize frequency data from intervals and sample values.
+- Included unit tests for constructor and edge-case input handling.
+
+## [0.1.0] - 2025-06-03
+
 ### Added
 
 - Fields `convex_resolution`, `concave_resolution`, and `mixed_resolution` in `CornerFinderSpec` can be used to take into account the dimensions of autodetected convex, concave, or mixed geometric features when `dl_min` is automatically inferred during automatic grid generation.
diff --git a/tests/test_FreqRange.py b/tests/test_FreqRange.py
@@ -0,0 +1,134 @@
+import numpy as np 
+
+from tidy3d.freq_range import FreqRange, um_to_m
+from tidy3d.components.source.time import GaussianPulse
+import tidy3d.constants as td_const
+
+
+def test_constructor():
+    
+    # set initial params
+    freq0  = 1e9     # set central frequency 
+    fwidth = 1e8     # set one-side bandwidth
+
+    # construct instance of FreqRange class
+    freq_range = FreqRange(freq0, fwidth)
+    
+    # validated if class atributes were initialized correctly
+    assert freq_range.fmin == freq0 - fwidth
+    assert freq_range.fmax == freq0 + fwidth
+    assert freq_range.lda0 == um_to_m(td_const.C_0  / freq0)
+    assert freq_range.freq0 == freq0
+    assert freq_range.fwidth == fwidth
+
+def test_from_interval():
+
+    fmin = 1e10      # new min frequency      
+    fmax = 1e11      # new max frequency
+    
+    # update object given new frequencies
+    freq_range = FreqRange.from_interval(fmin=fmin, fmax=fmax)
+
+    # validate if frequencies were updated correctly
+    assert freq_range.fmin == fmin
+    assert freq_range.fmax == fmax
+    assert freq_range.freq0 == (fmin + fmax) / 2
+    assert freq_range.fwidth == (fmax - fmin) / 2
+    assert freq_range.lda0 == um_to_m(2 * td_const.C_0 / (fmin + fmax))
+
+def test_from_wavelength():
+
+    # set initial params
+    wvl0 = 1e-6
+    wvl_width = 1e-7
+
+    # get the shortest and the longest wavelengths
+    wvl_min = wvl0 - wvl_width
+    wvl_max = wvl0 + wvl_width
+
+    # define frequency range 
+    freq_range = FreqRange.from_wavelength(wvl0, wvl_width)
+
+    # 
+    assert freq_range.lda0  == wvl0
+    assert freq_range.freq0 == um_to_m(td_const.C_0) / wvl0
+
+
+    print(um_to_m(td_const.C_0) / wvl_max)
+    print(um_to_m(td_const.C_0) / wvl_min)
+
+    assert freq_range.fmin  == um_to_m(td_const.C_0 / (wvl_max))
+    assert freq_range.fmax  == um_to_m(td_const.C_0 / (wvl_min))
+    assert freq_range.fwidth == 0.5 * (um_to_m(td_const.C_0 / wvl_min) - um_to_m(td_const.C_0 / wvl_max))
+
+
+def test_from_wavelegth_interval():
+
+    # set initial params
+    freq0  = 1e9     # set central frequency 
+    fwidth = 1e8     # set one-side bandwidth
+    wvl_min = 1e-7
+    wvl_max = 1e-6
+
+    # freq_range = FreqRange(freq0, fwidth)
+
+    # update frequencies based on wavelength
+    freq_range = FreqRange.from_wavelegth_interval(wvl_min, wvl_max)
+
+    # ensure that parameters are updated correctly
+    assert freq_range.lda0  == (wvl_min + wvl_max) / 2
+    assert freq_range.freq0 == um_to_m(2 * td_const.C_0 / (wvl_max + wvl_min))
+    assert freq_range.fmax  == um_to_m(td_const.C_0 / wvl_min)
+    assert freq_range.fmin  == um_to_m(td_const.C_0 / wvl_max)
+    assert freq_range.fwidth == 0.5 * (um_to_m(td_const.C_0 / wvl_min) - um_to_m(td_const.C_0 / wvl_max))
+
+def test_samples():
+
+    # set initial params
+    freq0  = 1e9     # set central frequency 
+    fwidth = 1e8     # set one-side bandwidth
+    num_points = 11
+
+    # construct instance of FreqRange class
+    freq_range = FreqRange(freq0, fwidth)
+
+    # form sampling frequency points
+    freqs = freq_range.samples(num_points)
+
+    # make sure 
+    assert np.array_equal(freqs,np.linspace(freq0 - fwidth, freq0 + fwidth, num_points))
+
+    # reset number of sampling points to 1
+    num_points = 1
+    freqs = freq_range.samples(num_points)
+
+    # check if freqs == freq0
+    assert np.array_equal(freqs, np.array([freq0]))
+
+    # reset number of sampling points to 111
+    num_points = 111
+    freqs = freq_range.samples(num_points)
+
+    # check if sampling frequencies are updated correctly
+    assert np.array_equal(freqs, np.linspace(freq0 - fwidth, freq0 + fwidth, num_points))
+
+
+
+
+def test_gaussian_pulse():
+    
+    # set initial params
+    freq0  = 1e9     # set central frequency 
+    fwidth = 1e8     # set one-side bandwidth
+
+    # construct instance of FreqRange class
+    freq_range = FreqRange(freq0, fwidth)
+
+    pulse_exp = GaussianPulse(freq0 = freq0, fwidth = fwidth) # instantiate GaussianPulse explicitly 
+    pulse_imp = freq_range.gaussian_pulse()                   # get instance by calling a method gaussian_pulse()
+
+    assert pulse_exp == pulse_imp                             # compare two pulses 
+
+
+
+
diff --git a/tidy3d/freq_range.py b/tidy3d/freq_range.py
@@ -0,0 +1,237 @@
+import numpy as np
+
+from tidy3d import constants as td_const  
+from tidy3d.components.source.time import GaussianPulse
+
+
+
+def um_to_m(val):
+    """um_to_m() is a simple function for convertion from [um] to [m]"""
+    return val * 1e-6
+
+
+class FreqRange:
+    """
+        Convenience class for handling frequency/wavelength conversion and assignment
+
+        Example
+        -------
+        >>> freq0  = 1e12
+        >>> fwidth = 1e11
+        >>> freq_range = FreqRange(freq0, fwidth)
+    """
+
+    # constructor 
+    def __init__(self, freq0, fwidth):
+        """
+            FreqRange constructor accepts central frequency "freq0" and one-sided bandwidth "fwidth"
+            as input arguments; this constructor makes an assumption that freq0 is a central frequency,
+            i.e. freq0 = (fmin + fmax) / 2; this implies that lda0 != (lda_min + lda_max) / 2
+              
+            when class methods with wavelength parameters are called, 
+            "fmin" and "fmax" have to be reassigned inside those methods, as there the assumption is: 
+            lda0 = (lda_min + lda_max) / 2; this implies that freq0 != (fmin + fmax) / 2
+
+            Parameters
+            ----------
+            freq0 - central frequency [Hz]
+            fwidth - one-sided bandwidth [Hz]
+        """
+
+        if not isinstance(freq0, (int, float)):
+            raise TypeError("Central frequency freq0 must be a number (int or float)")
+        if not isinstance(fwidth, (int, float)):
+            raise TypeError("Frequency bandwidth fwidth must be a number (int or float)")
+
+
+        # assign input args 
+        self.freq0  = freq0
+        self.fwidth = fwidth
+
+        # infer frequency range from central frequency and one-side bandwidth
+        self.fmin = self.freq0 - self.fwidth
+        self.fmax = self.freq0 + self.fwidth
+
+        self.num_points = 1        # set default number of wavelengths/frequencies to 1
+        self.freqs = np.array([self.freq0])    # until num_points is updated set freqs to carrier frequency/central frequency  
+        self.lda0  = um_to_m(td_const.C_0  / self.freq0)  # set central wavelength 
+        self.ldas  = np.array([self.lda0])                   # set wavelength range to central wavelength
+
+    #-----------------------------------
+    #       class methods 
+    #-----------------------------------
+    @classmethod
+    def from_interval(clf, fmin, fmax):
+        """
+            method from_interval() updated instance of class FreqRange by reassigning new 
+            frequency- and wavelength-related parameters; this method assumes, that the following 
+            definition is true:
+
+            freq0 = (fmin + fmax) / 2; it implies that lda0 != (lda_min + lda_max) / 2
+
+            Input Parameters
+            ----------------
+            fmin - the lowest frequency  [Hz]
+            fmax - the highest frequency [Hz]
+
+            Returns
+            -------
+            updated instance of class FreqRange
+
+            Example
+            -------
+            >>> fmin = 1e12
+            >>> fmax = 1e13
+            >>> freq_range = FreqRange.from_interval(fmin, fmax)
+        """
+
+        if fmax < fmin:
+            raise ValueError("fmax has to be higher than (or equal to) fmin")
+        if fmin < 0:
+            raise ValueError("fmin has to be a non-negative value")
+        
+        # extract frequency-related info
+        freq0  = 0.5 * (fmax + fmin)   # extract central freq
+        fwidth = 0.5 * (fmax - fmin)   # extract bandwidth
+        return clf(freq0, fwidth)
+
+    @classmethod
+    def from_wavelength(clf, wvl0, wvl_width):
+        """
+            method from_wavelength() updated instance of class FreqRange by reassigning new 
+            frequency- and wavelength-related parameters; this method assumes, that the following 
+            definition is true:
+
+            lda0 = (lda_min + lda_max) / 2; it implies that freq0 != (fmin + fmax) / 2
+
+            Input Parameters
+            ----------------
+            wvl0      - central wavelength  [m]
+            wvl_width - wavelength range [m]
+
+            Returns
+            -------
+            updated instance of class FreqRange
+
+            Example
+            -------
+            >>> wvl0 = 1e-6
+            >>> wvl_width = 1e-7
+            >>> freq_range = FreqRange.from_wavelength(wvl0, wvl_width)
+        """
+        if wvl0 < wvl_width:
+            raise ValueError("negative wavelengths are not allowed")
+        if wvl_width <= 0:
+            raise ValueError("wavelength range has to be a positive value")
+
+
+        freq0 = um_to_m(td_const.C_0) / wvl0   
+
+        fmin = um_to_m(td_const.C_0) / (wvl0 + wvl_width)
+        fmax = um_to_m(td_const.C_0) / (wvl0 - wvl_width)
+
+        fwidth = 0.5 * (fmax - fmin)
+
+        freq_range = clf(freq0, fwidth)
+
+        freq_range.fmin = fmin
+        freq_range.fmax = fmax
+
+        return freq_range
+
+    @classmethod
+    def from_wavelegth_interval(clf, wvl_min, wvl_max):
+        """
+            method from_wavelegth_interval() updated instance of class FreqRange by reassigning new 
+            frequency- and wavelength-related parameters; this method assumes, that the following 
+            definition is true:
+
+            lda0 = (lda_min + lda_max) / 2; it implies that freq0 != (fmin + fmax) / 2
+
+            Input Parameters
+            ----------------
+            wvl_min - the shortest wavelength [m]
+            wvl_max - the longest wavelength [m]
+
+            Returns
+            -------
+            updated instance of class FreqRange
+
+            Example
+            -------
+            >>> wvl_min = 1e-7
+            >>> wvl_max = 1e-6
+            >>> freq_range = FreqRange.from_wavelength(wvl_min, wvl_max)
+        """
+
+        if wvl_max <= wvl_min:
+            raise ValueError("longest wavelength must be greater than the shortest wavelength")
+        if wvl_min <= 0:
+            raise ValueError("wavelength has to be a positive value")
+
+        # convert wavelength intervals to freq. range
+        lda0  = 0.5 * (wvl_min + wvl_max)     # get central wavelength
+        freq0 = um_to_m(td_const.C_0 / lda0)  # get central frequency
+        fmax = um_to_m(td_const.C_0 / wvl_min)
+        fmin = um_to_m(td_const.C_0 / wvl_max)
+        fwidth = 0.5 * (fmax - fmin)     # define width of source frequency range
+
+        
+        freq_range = clf(freq0, fwidth)
+
+        freq_range.fmin = fmin
+        freq_range.fmax = fmax
+        return freq_range
+    
+
+    def samples(self, num_points):
+        """
+            method samples() performes discretization of the frequency range by a
+            given number of points "num_points"; frequency samples are uniformly 
+            distributed in ascending order (e.g. freqs = [3,4,...,100]Hz)
+
+            Parameters
+            ----------
+            num_points - number of frequency points 
+
+            Returns
+            -------
+            freqs - a numpy array of uniformly distributed frequency samples in ascending order
+        """
+
+        # update number of freq points 
+        self.num_points = num_points
+
+        if num_points == 1:     # if one sample frequency point is selected
+
+            self.freqs = np.array([self.freq0])
+            self.ldas  = np.array([self.lda0])
+
+        else:                   # otherwise 
+
+            if self.fmax <= self.fmin:
+                raise ValueError("fmin has to be larger than fmin")
+            if self.fmin <=0:
+                raise ValueError("frequencies have to be positive values")
+
+            # calculate frequency points and corresponding wavelengths
+            self.freqs = np.linspace(self.fmin, self.fmax, self.num_points)
+
+            # define shortest and longest wavelengths
+            lmin = um_to_m(td_const.C_0 / self.fmax)
+            lmax = um_to_m(td_const.C_0 / self.fmin) 
+
+            # update array of wavelengths (wavelengths would be in descending order) 
+            self.ldas  = um_to_m(td_const.C_0 / self.freqs)
+
+        return self.freqs
+    
+    def gaussian_pulse(self):
+        """
+            method gaussian_pulse() returns instance of class GaussianPulse
+            with central frequency freq0 and width of the source frequency fwidth
+        """
+
+        # create an instance of GaussianPulse class with defined frequency params
+        return GaussianPulse(freq0 = self.freq0, fwidth = self.fwidth)
+
