Truncate at flow

gw_eccentricity/__init__.py

@@ -8,3 +8,4 @@
 
 from .gw_eccentricity import measure_eccentricity
 from .gw_eccentricity import get_available_methods
+from .gw_eccentricity import truncate_at_flow

gw_eccentricity/gw_eccentricity.py

@@ -339,3 +339,81 @@ def measure_eccentricity(tref_in=None,
     else:
         raise Exception(f"Invalid method {method}, has to be one of"
                         f" {list(available_methods.keys())}")
+
+
+def truncate_at_flow(flow,
+                     m_max=None,
+                     method="Amplitude",
+                     dataDict=None,
+                     extra_kwargs=None):
+    """Truncate waveform at flow.
+
+    Eccentric waveforms have a non-monotonic instantaneous frequency.
+    Therefore, truncating the waveform by demanding that the truncated
+    waveform should contain all frequencies that are greater than or equal
+    to a given minimum frequency, say flow, must be done carefully since
+    the instantaneous frequency can be equal to the given flow at multiple
+    points in time.
+
+    We need to find the time tlow, such that all the frequencies at t <
+    tlow are < flow and therefore the t >= tlow part of the waveform would
+    retain all the frequencies that are >= flow. Note that the t >= tlow
+    part could contain some frequencies < flow but that is fine, all we
+    need is not to lose any frequencies >= flow.
+
+    This can be done by using the frequency interpolant omega22_p(t)
+    through the pericenters because
+    1. It is a monotonic function of time.
+    2. If at a time tlow, omega22_p(tlow) * (m_max/2) = 2*pi*flow, then all
+    frequencies >= flow will be included in the waveform truncated at
+    t=tlow. The m_max/2 factor ensures that this statement is true for all
+    modes, as the frequency of the h_{l, m} mode scales approximately as
+    m/2 * omega_22/(2*pi).
+
+    Thus, we find tlow such that omega22_p(tlow) * (m_max/2) = 2*pi*flow
+    and truncate the waveform by keeping only the part where t >= tlow.
+
+    Parameters:
+    -----------
+    flow: float
+        Lower cutoff frequency to truncate the given waveform modes.
+        The truncated waveform modes will contain all the frequencies >= flow.
+
+    m_max: int
+        Maximum m (index of h_{l, m}) to account for while setting the tlow
+        for truncation.  If None, then it is set using the highest available
+        m from the modes in the dataDict.
+        Default is None.
+
+    method: str
+        Method to use for finding extrema locations.
+        See under `measure_eccentricity` for more details.
+
+    dataDict: dict
+        Dictionary containing waveform modes.
+        See under `measure_eccentricity` for more details.
+
+    extra_kwargs: dict
+        Dictionary of kwargs used to find the extrema or build the interpolants.
+        See under `measure_eccentricity` for more details.
+
+    Returns:
+    truncatedDataDict: dict
+        Dictionary containing waveform data truncated at flow.
+
+    gwecc_object: obj
+        Object used for truncating data.
+    """
+    available_methods = get_available_methods(return_dict=True)
+
+    if method in available_methods:
+        gwecc_object = available_methods[method](
+            dataDict, num_orbits_to_exclude_before_merger=0,
+            extra_kwargs=extra_kwargs)
+        truncatedDataDict = gwecc_object.truncate_at_flow(flow, m_max)
+        return truncatedDataDict, gwecc_object
+    else:
+        raise Exception(f"Invalid method {method}, has to be one of"
+                        f" {list(available_methods.keys())}")
+
+