sxs 2024.0.26__tar.gz → 2024.0.28__tar.gz

{sxs-2024.0.26 → sxs-2024.0.28}/.github/workflows/build.yml

@@ -30,12 +30,12 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ['3.8', '3.12']
+        python-version: ['3.10', '3.12']
 
     steps:
       - name: Skip replicates on main branch
         env:
-          skip_replicates: ${{ github.ref == 'refs/heads/main' && (matrix.os != 'ubuntu-latest' || matrix.python-version != '3.12') }}
+          skip_replicates: ${{ github.ref == 'refs/heads/main' && matrix.os != 'ubuntu-latest' }}
         shell: bash
         run: |
           echo "skipping_build_and_test_replicate=${skip_replicates}" >> $GITHUB_ENV

{sxs-2024.0.26 → sxs-2024.0.28}/CITATION.cff

@@ -10,5 +10,5 @@ authors:
 title: "The sxs package"
 license: MIT
 doi: 10.5281/zenodo.4034006
-version: 2024.0.26
-date-released: 2024-12-18
+version: 2024.0.28
+date-released: 2025-01-31

{sxs-2024.0.26 → sxs-2024.0.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sxs
-Version: 2024.0.26
+Version: 2024.0.28
 Summary: Interface to data produced by the Simulating eXtreme Spacetimes collaboration
 Project-URL: Homepage, https://github.com/sxs-collaboration/sxs
 Project-URL: Documentation, https://sxs.readthedocs.io/
@@ -34,18 +34,18 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Astronomy
 Classifier: Topic :: Scientific/Engineering :: Physics
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Requires-Dist: h5py>=3
 Requires-Dist: inflection>=0.5.1
 Requires-Dist: juliacall>=0.9.20
 Requires-Dist: numba>=0.55; implementation_name == 'cpython'
-Requires-Dist: numpy>=1.20
+Requires-Dist: numpy>=1.25
 Requires-Dist: pandas>=1.1.2
 Requires-Dist: pytz>=2020.1
 Requires-Dist: quaternionic>=1.0
 Requires-Dist: requests>=2.24.0
-Requires-Dist: scipy>=1.7
-Requires-Dist: spherical>=1.0
+Requires-Dist: scipy>=1.13
+Requires-Dist: spherical>=1.0.15
 Requires-Dist: tqdm>=4.63.1
 Requires-Dist: urllib3>=1.25.10
 Provides-Extra: docs

{sxs-2024.0.26 → sxs-2024.0.28}/pyproject.toml

@@ -3,7 +3,7 @@ name = "sxs"
 dynamic = ["version"]
 description = "Interface to data produced by the Simulating eXtreme Spacetimes collaboration"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 license = {file = "LICENSE"}
 authors = [
   { name = "Michael Boyle", email = "michael.oliver.boyle@gmail.com" }
@@ -18,11 +18,11 @@ classifiers = [
   "Topic :: Scientific/Engineering :: Astronomy"
 ]
 dependencies = [
-  "numpy >=1.20",
-  "scipy >=1.7",
+  "numpy >=1.25",
+  "scipy >=1.13",
   "numba >=0.55; implementation_name == 'cpython'",
   "quaternionic >=1.0",
-  "spherical >=1.0",
+  "spherical >=1.0.15",
   "h5py >=3",
   "inflection >=0.5.1",
   "requests >=2.24.0",

sxs-2024.0.28/sxs/__version__.py

@@ -0,0 +1 @@
+__version__ = "2024.0.28"

{sxs-2024.0.26 → sxs-2024.0.28}/sxs/waveforms/alignment.py

@@ -1,12 +1,13 @@
 import numpy as np
 
+import quaternionic
+
 from scipy.integrate import trapezoid
 
 import multiprocessing as mp
 from functools import partial
 
 
-
 def align1d(wa, wb, t1, t2, n_brute_force=None):
     """Align waveforms by shifting in time
 
@@ -77,7 +78,6 @@ def align1d(wa, wb, t1, t2, n_brute_force=None):
 
     """
     from scipy.interpolate import CubicSpline
-    from scipy.integrate import trapezoid
     from scipy.optimize import least_squares
 
     # Check that (t1, t2) makes sense and is actually contained in both waveforms
@@ -89,8 +89,8 @@ def align1d(wa, wb, t1, t2, n_brute_force=None):
         raise ValueError(f"(t1,t2)=({t1}, {t2}) not contained in wb.t, which spans ({wb.t[0]}, {wb.t[-1]})")
 
     # Figure out time offsets to try
-    δt_lower = max(t1 - t2, wb.t[0] - t1)
-    δt_upper = min(t2 - t1, wb.t[-1] - t2)
+    δt_lower = max(t1 - t2, t2 - wb.t[-1])
+    δt_upper = min(t2 - t1, t1 - wb.t[0])
 
     # We'll start by brute forcing, sampling time offsets evenly at as many
     # points as there are time steps in (t1,t2) in the input waveforms
@@ -126,15 +126,13 @@ def _cost2d(δt_δϕ, args):
 
     # Take the sqrt because least_squares squares the inputs...
     diff = trapezoid(
-        np.sum(
-            abs(modes_A(t_reference + δt) * np.exp(1j * m * δϕ) * δΨ_factor - modes_B) ** 2, axis=1
-        ),
+        np.sum(abs(modes_A(t_reference + δt) * np.exp(1j * m * δϕ) * δΨ_factor - modes_B) ** 2, axis=1),
         t_reference,
     )
     return np.sqrt(diff / normalization)
 
 
-def align2d(wa, wb, t1, t2, n_brute_force_δt=None, n_brute_force_δϕ=5, include_modes=None, nprocs=None):
+def align2d(wa, wb, t1, t2, n_brute_force_δt=None, n_brute_force_δϕ=5, max_δt=np.inf, use_δΨ=False, include_modes=None, nprocs=None):
     """Align waveforms by shifting in time and phase
 
     This function determines the optimal time and phase offset to apply to `wa` by
@@ -166,7 +164,7 @@ def align2d(wa, wb, t1, t2, n_brute_force_δt=None, n_brute_force_δϕ=5, includ
         Waveforms to be aligned
     t1 : float
     t2 : float
-        Beginning and end of integration interval
+        Beginning and end of integration interval.
     n_brute_force_δt : int, optional
         Number of evenly spaced δt values between (t1-t2) and (t2-t1) to sample
         for the initial guess.  By default, this is just the maximum number of
@@ -179,6 +177,10 @@ def align2d(wa, wb, t1, t2, n_brute_force_δt=None, n_brute_force_δϕ=5, includ
         is not the default because, even though it is formally the right
         thing to do, it takes much longer to produce the same result
         as just using 5, which is much faster.
+    max_δt : float, optional
+        Max δt to allow for when choosing the initial guess.
+    use_δΨ : float, optional
+        Whether or not to allow for a h -> -h transformation.
     include_modes: list, optional
         A list containing the (ell, m) modes to be included in the L² norm.
     nprocs: int, optional
@@ -218,23 +220,19 @@ def align2d(wa, wb, t1, t2, n_brute_force_δt=None, n_brute_force_δϕ=5, includ
     if t2 <= t1:
         raise ValueError(f"(t1,t2)=({t1}, {t2}) is out of order")
     if wa.t[0] > t1 or wa.t[-1] < t2:
-        raise ValueError(
-            f"(t1,t2)=({t1}, {t2}) not contained in wa.t, which spans ({wa.t[0]}, {wa.t[-1]})"
-        )
+        raise ValueError(f"(t1,t2)=({t1}, {t2}) not contained in wa.t, which spans ({wa.t[0]}, {wa.t[-1]})")
     if wb.t[0] > t1 or wb.t[-1] < t2:
-        raise ValueError(
-            f"(t1,t2)=({t1}, {t2}) not contained in wb.t, which spans ({wb.t[0]}, {wb.t[-1]})"
-        )
+        raise ValueError(f"(t1,t2)=({t1}, {t2}) not contained in wb.t, which spans ({wb.t[0]}, {wb.t[-1]})")
 
     # Figure out time offsets to try
-    δt_lower = max(t1 - t2, wa.t[0] - t1)
-    δt_upper = min(t2 - t1, wa.t[-1] - t2)
-
+    δt_lower = max(-max_δt, max(t1 - t2, t2 - wa.t[-1]))
+    δt_upper = min(max_δt, min(t2 - t1, t1 - wa.t[0]))
+    
     # We'll start by brute forcing, sampling time offsets evenly at as many
     # points as there are time steps in (t1,t2) in the input waveforms
     if n_brute_force_δt is None:
         n_brute_force_δt = max(sum((wa.t >= t1) & (wa.t <= t2)), sum((wb.t >= t1) & (wb.t <= t2)))
-    δt_brute_force = np.linspace(δt_lower, δt_upper, num=n_brute_force_δt)
+    δt_brute_force = np.array(list(np.linspace(δt_lower, δt_upper, num=n_brute_force_δt)) + [0.0])
 
     if n_brute_force_δϕ is None:
         n_brute_force_δϕ = 2 * wa.ell_max + 1
@@ -246,7 +244,7 @@ def align2d(wa, wb, t1, t2, n_brute_force_δt=None, n_brute_force_δϕ=5, includ
 
     # Remove certain modes, if requested
     ell_max = min(wa.ell_max, wb.ell_max)
-    if include_modes != None:
+    if include_modes is not None:
         for L in range(2, ell_max + 1):
             for M in range(-L, L + 1):
                 if not (L, M) in include_modes:
@@ -254,17 +252,11 @@ def align2d(wa, wb, t1, t2, n_brute_force_δt=None, n_brute_force_δϕ=5, includ
                     wb.data[:, wb.index(L, M)] *= 0
 
     # Define the cost function
-    modes_A = CubicSpline(
-        wa.t, wa[:, wa.index(2, -2) : wa.index(ell_max + 1, -(ell_max + 1))].data
-    )
-    modes_B = CubicSpline(
-        wb.t, wb[:, wb.index(2, -2) : wb.index(ell_max + 1, -(ell_max + 1))].data
-    )(t_reference)
+    modes_A = CubicSpline(wa.t, wa[:, wa.index(2, -2) : wa.index(ell_max + 1, -(ell_max + 1))].data)
+    modes_B = CubicSpline(wb.t, wb[:, wb.index(2, -2) : wb.index(ell_max + 1, -(ell_max + 1))].data)(t_reference)
 
     normalization = trapezoid(
-        CubicSpline(
-            wb.t, wb[:, wb.index(2, -2) : wb.index(ell_max + 1, -(ell_max + 1))].norm ** 2
-        )(t_reference),
+        CubicSpline(wb.t, wb[:, wb.index(2, -2) : wb.index(ell_max + 1, -(ell_max + 1))].norm ** 2)(t_reference),
         t_reference,
     )
 
@@ -272,7 +264,10 @@ def align2d(wa, wb, t1, t2, n_brute_force_δt=None, n_brute_force_δϕ=5, includ
 
     optimums = []
     wa_primes = []
-    for δΨ_factor in [-1, +1]:
+    δΨ_factors = [1]
+    if use_δΨ:
+        δΨ_factors = [-1, +1]
+    for δΨ_factor in δΨ_factors:
         # Optimize by brute force with multiprocessing
         cost_wrapper = partial(_cost2d, args=[modes_A, modes_B, t_reference, m, δΨ_factor, normalization])
 
@@ -310,3 +305,241 @@ def align2d(wa, wb, t1, t2, n_brute_force_δt=None, n_brute_force_δϕ=5, includ
     idx = np.argmin(abs(np.array([optimum.cost for optimum in optimums])))
 
     return optimums[idx].cost, wa_primes[idx], optimums[idx]
+
+
+def _cost4d(δt_δso3, args):
+    from .. import WaveformModes
+
+    modes_A, modes_B, t_reference, normalization = args
+    δt = δt_δso3[0]
+    δSO3 = np.exp(quaternionic.array.from_vector_part(δt_δso3[1:]))
+
+    modes_A_at_δt = modes_A(t_reference + δt)
+    ell_max = int(np.sqrt(modes_A_at_δt.shape[1] + 4)) - 1
+
+    wa_prime = WaveformModes(
+        input_array=(modes_A_at_δt),
+        time=t_reference,
+        time_axis=0,
+        modes_axis=1,
+        ell_min=2,
+        ell_max=ell_max,
+        spin_weight=-2,
+    )
+
+    wa_prime = wa_prime.rotate(δSO3)
+
+    # Take the sqrt because least_squares squares the inputs...
+    diff = trapezoid(
+        np.sum(abs(wa_prime.data - modes_B) ** 2, axis=1),
+        t_reference,
+    )
+    return np.sqrt(diff / normalization)
+
+
+def align4d(
+    wa,
+    wb,
+    t1,
+    t2,
+    n_brute_force_δt=1_000,
+    n_brute_force_δϕ=None,
+    max_δt=np.inf,
+    include_modes=None,
+    align2d_first=False,
+    nprocs=None,
+):
+    """Align waveforms by optimizing over a time translation and an SO(3) rotation.
+
+    This function determines the optimal transformation to apply to `wa` by 
+    minimizing the averaged (over time) L² norm (over the sphere) of the 
+    difference of the waveforms.
+
+    The integral is taken from time `t1` to `t2`.
+
+    Note that the input waveforms are assumed to be initially aligned at least 
+    well enough that:
+
+      1) the time span from `t1` to `t2` in the two waveforms will overlap at 
+         least slightly after the second waveform is shifted in time; and
+      2) waveform `wb` contains all the times corresponding to `t1` to `t2` in 
+         waveform `wa`.
+
+    The first of these can usually be assured by simply aligning the peaks prior 
+    to calling this function:
+
+        wa.t -= wa.max_norm_time() - wb.max_norm_time()
+
+    The second assumption will be satisfied as long as `t1` is not too close to 
+    the beginning of `wb` and `t2` is not too close to the end.
+
+    Parameters
+    ----------
+    wa : WaveformModes
+    wb : WaveformModes
+        Waveforms to be aligned
+    t1 : float
+    t2 : float
+        Beginning and end of integration interval
+    n_brute_force_δt : int, optional
+        Number of evenly spaced δt values between (t1-t2) and (t2-t1) to sample 
+        for the initial guess.  By default, this is 1,000.  If this is too small, 
+        an incorrect local minimum may be found.
+    n_brute_force_δϕ : int, optional
+        Number of evenly spaced angles about the angular-velocity axis to sample 
+        for the initial guess.  By default, this is `2 * (2 * ell_max + 1)`.
+    max_δt : float, optional
+        Max δt to allow for when choosing the initial guess.
+    include_modes: list, optional
+        A list containing the (ell, m) modes to be included in the L² norm.
+    align2d_first : bool, optional
+        Do a 2d align first for an initial guess, with no SO(3) initial guess 
+        (besides the phase returned by the 2d solve)
+    nprocs: int, optional
+        Number of cpus to use.  Default is maximum number.  If -1 is provided, 
+        then no multiprocessing is performed.
+
+    Returns
+    -------
+    error: float
+        Cost of scipy.optimize.least_squares.  This is 0.5 ||wa - wb||² / ||wb||²
+    wa_prime: WaveformModes
+        Resulting waveform after transforming `wa` using `optimum`
+    optimum: OptimizeResult
+        Result of scipy.optimize.least_squares
+
+    Notes
+    -----
+    Choosing the time interval is usually the most difficult choice to make when 
+    aligning waveforms.  Assuming you want to align during inspiral, the times 
+    must span sufficiently long that the waveforms' norm (equivalently, orbital 
+    frequency changes) significantly from `t1` to `t2`.  This means that you 
+    cannot always rely on a specific number of orbits, for example.  Also note 
+    that neither number should be too close to the beginning or end of either 
+    waveform, to provide some "wiggle room".
+
+    """
+    from scipy.interpolate import CubicSpline
+    from scipy.optimize import least_squares
+    from .. import WaveformModes
+
+    if wa.spin_weight != wb.spin_weight:
+        raise ValueError(f"Waveform spin weights do not match: {wa.spin_weight=} != {wb.spin_weight=}")
+    spin_weight = wa.spin_weight
+    ell_min = max(wa.ell_min, wb.ell_min)
+    ell_max = min(wa.ell_max, wb.ell_max)
+
+    wa_orig = wa
+    wa = wa.copy()
+    wb = wb.copy()
+
+    # Check that (t1, t2) makes sense and is actually contained in both waveforms
+    if t2 <= t1:
+        raise ValueError(f"(t1,t2)=({t1}, {t2}) is out of order")
+    if wa.t[0] > t1 or wa.t[-1] < t2:
+        raise ValueError(f"(t1,t2)=({t1}, {t2}) not contained in wa.t, which spans ({wa.t[0]}, {wa.t[-1]})")
+    if wb.t[0] > t1 or wb.t[-1] < t2:
+        raise ValueError(f"(t1,t2)=({t1}, {t2}) not contained in wb.t, which spans ({wb.t[0]}, {wb.t[-1]})")
+
+    # Figure out time offsets to try
+    δt_lower = max(-max_δt, max(t1 - t2, t2 - wa.t[-1]))
+    δt_upper = min(max_δt, min(t2 - t1, t1 - wa.t[0]))
+
+    t_reference = wb.t[np.argmin(abs(wb.t - t1)) : np.argmin(abs(wb.t - t2)) + 1]
+    
+    if not align2d_first:
+        # Get time initial guess
+        # Negative sign because align1d aligns wb to wa
+        δt_IG = -align1d(wa, wb, t1, t2)
+        
+        wa_interp = wa.interpolate(t_reference + δt_IG)
+        wb_interp = wb.interpolate(t_reference)
+        
+        # Get rotor initial guess
+        omegaa = wa_interp.angular_velocity
+        omegab = wb_interp.angular_velocity
+        R_IG = quaternionic.align(omegaa, omegab)
+    else:
+        _, _, res = align2d(
+            wa, wb, t1, t2, max_δt=50,
+            n_brute_force_δt=n_brute_force_δt, nprocs=nprocs
+        )
+        δt_IG = res.x[0]
+
+        wa_interp = wa.interpolate(t_reference + δt_IG)
+        wb_interp = wb.interpolate(t_reference)
+
+        # Get rotor initial guess
+        omegaa = wa_interp.angular_velocity
+        omegab = wb_interp.angular_velocity
+        R_IG = quaternionic.align(omegaa, omegab)
+        
+        R_IG = quaternionic.array([0, 0, 0, res.x[1] / 2]) * R_IG
+
+    # Brute force over R_IG * exp(theta * z / 2) with δt_IG
+    n_brute_force_δϕ = n_brute_force_δϕ or 2 * (2 * ell_max + 1)
+    δt_δso3_brute_force = [
+        [δt_IG, *np.log(R_IG * np.exp(quaternionic.array([0, 0, 0, angle / 2]))).vector]
+        for angle in np.linspace(0, 2 * np.pi, num=n_brute_force_δϕ, endpoint=False)
+    ]
+
+    # Remove certain modes, if requested
+    if include_modes is not None:
+        for L in range(ell_min, ell_max + 1):
+            for M in range(-L, L + 1):
+                if not (L, M) in include_modes:
+                    wa.data[:, wa.index(L, M)] *= 0
+                    wb.data[:, wb.index(L, M)] *= 0
+
+    # Define the cost function
+    modes_A = CubicSpline(wa.t, wa[:, wa.index(ell_min, -ell_min) : wa.index(ell_max, ell_max)+1].data)
+    modes_B = CubicSpline(wb.t, wb[:, wb.index(ell_min, -ell_min) : wb.index(ell_max, ell_max)+1].data)(t_reference)
+
+    normalization = trapezoid(
+        CubicSpline(
+            wb.t,
+            wb[:, wb.index(ell_min, -ell_min) : wb.index(ell_max, ell_max)+1].norm ** 2
+        )(t_reference),
+        t_reference,
+    )
+
+    # Optimize by brute force with multiprocessing
+    cost_wrapper = partial(_cost4d, args=[modes_A, modes_B, t_reference, normalization])
+
+    if nprocs != -1:
+        if nprocs is None:
+            nprocs = mp.cpu_count()
+        pool = mp.Pool(processes=nprocs)
+        cost_brute_force = pool.map(cost_wrapper, δt_δso3_brute_force)
+        pool.close()
+        pool.join()
+    else:
+        cost_brute_force = [
+            cost_wrapper(δt_δso3_brute_force_item)
+            for δt_δso3_brute_force_item in δt_δso3_brute_force
+        ]
+
+    δt_δso3 = δt_δso3_brute_force[np.argmin(cost_brute_force)]
+    
+    # Optimize explicitly
+    optimum = least_squares(
+        cost_wrapper,
+        δt_δso3,
+        bounds=[(δt_lower, -np.pi/2, -np.pi/2, -np.pi/2), (δt_upper, np.pi/2, np.pi/2, np.pi/2)],
+        max_nfev=50000,
+    )
+    δt = optimum.x[0]
+    δSO3 = np.exp(quaternionic.array.from_vector_part(optimum.x[1:]))
+    
+    wa_prime = WaveformModes(
+        input_array=(wa_orig[:, wa_orig.index(ell_min, -ell_min) : wa_orig.index(ell_max, ell_max)+1].data),
+        time=wa_orig.t - δt,
+        time_axis=0,
+        modes_axis=1,
+        ell_min=ell_min,
+        ell_max=ell_max,
+        spin_weight=spin_weight,
+    )
+    wa_prime = wa_prime.rotate(δSO3)
+
+    return optimum.cost, wa_prime, optimum

sxs-2024.0.26/sxs/__version__.py

@@ -1 +0,0 @@
-__version__ = "2024.0.26"