GWFrames 2.0.0__tar.gz

gwframes-2.0.0/.gitignore

@@ -0,0 +1,25 @@
+# Build products
+build/
+dist/
+wheelhouse/
+*.o
+*.so
+*.dylib
+*.a
+*.egg-info/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ipynb_checkpoints/
+uv.lock
+
+# Editors and operating systems
+.DS_Store
+.vscode/
+.idea/
+
+# Local review notes
+.diffreview/

gwframes-2.0.0/.gitmodules

@@ -0,0 +1,16 @@
+[submodule "Code/PostNewtonian"]
+	path = extern/PostNewtonian
+    url = https://github.com/moble/PostNewtonian.git
+    branch = master
+[submodule "Code/SphericalFunctions"]
+	path = extern/SphericalFunctions
+    url = https://github.com/moble/SphericalFunctions.git
+    branch = master
+[submodule "Code/SpacetimeAlgebra"]
+	path = extern/SpacetimeAlgebra
+    url = https://github.com/moble/SpacetimeAlgebra.git
+    branch = master
+[submodule "Code/Quaternions"]
+	path = extern/Quaternions
+    url = https://github.com/moble/Quaternions.git
+    branch = master

gwframes-2.0.0/CMakeLists.txt

@@ -0,0 +1,101 @@
+cmake_minimum_required(VERSION 3.20...3.31)
+project(GWFrames LANGUAGES C CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_C_STANDARD 99)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+# Let the installed module find shared GSL and FFTW libraries outside system paths
+set(CMAKE_INSTALL_RPATH_USE_LINK_PATH ON)
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Release)
+endif()
+
+# External libraries.  GSL has a module that ships with CMake; FFTW does
+# not, so it is found through pkg-config when that is available, and by
+# searching the usual paths otherwise.
+find_package(GSL 2.0 REQUIRED)
+find_package(PkgConfig QUIET)
+if(PkgConfig_FOUND)
+  pkg_check_modules(FFTW3 QUIET IMPORTED_TARGET fftw3)
+endif()
+if(TARGET PkgConfig::FFTW3)
+  add_library(FFTW3::fftw3 ALIAS PkgConfig::FFTW3)
+else()
+  find_path(FFTW3_INCLUDE_DIR fftw3.h REQUIRED)
+  find_library(FFTW3_LIBRARY NAMES fftw3 REQUIRED)
+  add_library(FFTW3::fftw3 UNKNOWN IMPORTED)
+  set_target_properties(FFTW3::fftw3 PROPERTIES
+    IMPORTED_LOCATION "${FFTW3_LIBRARY}"
+    INTERFACE_INCLUDE_DIRECTORIES "${FFTW3_INCLUDE_DIR}")
+endif()
+
+# The vendored copy of spinsfast is plain C.
+file(GLOB SPINSFAST_SOURCES CONFIGURE_DEPENDS extern/spinsfast/code/*.c)
+add_library(spinsfast STATIC ${SPINSFAST_SOURCES})
+target_include_directories(spinsfast PUBLIC extern/spinsfast/include)
+target_link_libraries(spinsfast PUBLIC FFTW3::fftw3)
+
+# GWFrames itself, together with the C++ code it uses from the submodules.
+add_library(gwframes STATIC
+  extern/Quaternions/Quaternions.cpp
+  extern/Quaternions/IntegrateAngularVelocity.cpp
+  extern/Quaternions/QuaternionUtilities.cpp
+  extern/PostNewtonian/C++/PNEvolution.cpp
+  extern/PostNewtonian/C++/PNEvolution_Q.cpp
+  extern/PostNewtonian/C++/PNWaveformModes.cpp
+  extern/SphericalFunctions/Combinatorics.cpp
+  extern/SphericalFunctions/WignerDMatrices.cpp
+  extern/SphericalFunctions/SWSHs.cpp
+  extern/SpacetimeAlgebra/CodeGenerators/SpacetimeAlgebra.cpp
+  cpp/Utilities.cpp
+  cpp/Waveforms.cpp
+  cpp/PNWaveforms.cpp
+  cpp/WaveformsAtAPointFT.cpp
+  cpp/fft.cpp
+  cpp/NoiseCurves.cpp
+  cpp/Interpolate.cpp
+  cpp/Scri.cpp
+)
+target_include_directories(gwframes PUBLIC
+  cpp
+  extern
+  extern/Quaternions
+  extern/SphericalFunctions
+  extern/SpacetimeAlgebra/CodeGenerators
+)
+target_compile_definitions(gwframes PUBLIC USE_GSL)
+target_link_libraries(gwframes PUBLIC spinsfast GSL::gsl FFTW3::fftw3)
+
+# Waveform histories record the code revision: the git commit when building
+# from a clone, and the package version otherwise (as when building an sdist).
+set(GWFRAMES_CODE_REVISION "${SKBUILD_PROJECT_VERSION}")
+find_package(Git QUIET)
+if(Git_FOUND AND EXISTS "${PROJECT_SOURCE_DIR}/.git")
+  execute_process(
+    COMMAND "${GIT_EXECUTABLE}" rev-parse HEAD
+    WORKING_DIRECTORY "${PROJECT_SOURCE_DIR}"
+    OUTPUT_VARIABLE GWFRAMES_GIT_REVISION
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    ERROR_QUIET)
+  if(GWFRAMES_GIT_REVISION)
+    set(GWFRAMES_CODE_REVISION "${GWFRAMES_GIT_REVISION}")
+  endif()
+endif()
+if(NOT GWFRAMES_CODE_REVISION)
+  set(GWFRAMES_CODE_REVISION "unknown")
+endif()
+target_compile_definitions(gwframes PRIVATE "CodeRevision=\"${GWFRAMES_CODE_REVISION}\"")
+
+# The Python extension module, installed inside the `GWFrames` package
+find_package(Python 3.11 REQUIRED COMPONENTS Interpreter Development.Module)
+find_package(pybind11 CONFIG REQUIRED)
+pybind11_add_module(_GWFrames
+  cpp/bindings/module.cpp
+  cpp/bindings/quaternions.cpp
+  cpp/bindings/utilities.cpp
+  cpp/bindings/waveforms.cpp
+  cpp/bindings/scri.cpp
+)
+target_link_libraries(_GWFrames PRIVATE gwframes)
+install(TARGETS _GWFrames LIBRARY DESTINATION GWFrames)

gwframes-2.0.0/LICENSE

@@ -0,0 +1,31 @@
+Copyright (c) 2026, Michael Boyle
+
+If this software is used in any academic research, the author would
+very much appreciate if resulting works cite the original paper on
+which this software is based: <http://arxiv.org/abs/1302.2919>.  This
+software is covered under the open source MIT license, shown below,
+with the exception of the 'spinsfast' software package.  The
+'spinsfast' software (rev104) is included with this software without
+modification, and is covered separately under the GNU GPL license, as
+documented in its subdirectory.  See its home page:
+<http://www.physics.miami.edu/~huffenbe/research/spinsfast/>.
+
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

gwframes-2.0.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: GWFrames
+Version: 2.0.0
+Summary: Manipulate gravitational waveforms — changing frames, and so on
+Author-Email: Michael Boyle <mob22@cornell.edu>
+License-Expression: MIT AND GPL-3.0-or-later
+License-File: LICENSE
+License-File: extern/spinsfast/COPYING
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Project-URL: Homepage, https://github.com/moble/GWFrames
+Project-URL: Issues, https://github.com/moble/GWFrames/issues
+Project-URL: Paper, https://arxiv.org/abs/1302.2919
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: h5py>=3.8
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Description-Content-Type: text/markdown
+
+> [!NOTE]
+> **For post-Newtonian waveforms, use [PostNewtonian.jl](https://github.com/moble/PostNewtonian.jl).**
+> It is far more complete, accurate, and flexible than the post-Newtonian code
+> in this package.  Most of the rest of the functionality here has moved to
+> [`scri`](https://github.com/moble/scri) and [`sxs`](https://github.com/sxs-collaboration/sxs).
+> GWFrames is kept working mainly as a reference implementation to compare
+> other codes against.
+
+[![Tests](https://github.com/moble/GWFrames/actions/workflows/tests.yml/badge.svg)](https://github.com/moble/GWFrames/actions/workflows/tests.yml)
+[![Wheels](https://github.com/moble/GWFrames/actions/workflows/wheels.yml/badge.svg)](https://github.com/moble/GWFrames/actions/workflows/wheels.yml)
+
+GWFrames
+========
+
+Manipulate gravitational waveforms — changing frames, and so on.
+
+The code in this project extends code written for the paper "[Angular velocity
+of gravitational radiation from precessing binaries and the corotating
+frame](https://arxiv.org/abs/1302.2919)", giving an explicit implementation of
+the methods discussed in it.  The first commit of this project is the last
+commit of the paper's project.
+
+The license for using this software is basically open (see the LICENSE file in
+this directory), though citations to the original paper are appreciated, where
+relevant.  Also, if your work depends on features found in this module that
+have not been described in a separate publication of mine, I would appreciate
+the opportunity to be a coauthor.
+
+Note that this code is not optimized.  In many cases, obvious optimizations
+were rejected in favor of clearer or simpler code, or code that simply
+reflected the discussion in the paper more directly.  The code is generally
+more than fast enough for interactive use on individual waveforms, but there is
+plenty of room for improvement.  In particular, rotations may be painfully slow
+for large data sets.
+
+
+Installation
+============
+
+GWFrames requires Python 3.11 or newer, on Linux or macOS.
+
+With `uv` or `pip`
+------------------
+
+Binary wheels for Linux and macOS (x86_64 and arm64) are published on PyPI, so
+the simplest installation is
+
+```bash
+uv add GWFrames        # in a uv project
+uv pip install GWFrames  # or in any virtual environment
+pip install GWFrames     # or with pip
+```
+
+To install the latest code from GitHub, or on any platform without a wheel,
+GWFrames is compiled from source.  That needs a C++ compiler,
+[GSL](https://www.gnu.org/software/gsl/), and [FFTW](https://www.fftw.org/),
+which are available from most package managers:
+
+```bash
+sudo apt-get install libgsl-dev libfftw3-dev   # Debian or Ubuntu
+brew install gsl fftw                          # macOS with Homebrew
+```
+
+after which
+
+```bash
+uv pip install "git+https://github.com/moble/GWFrames"
+```
+
+builds and installs it.  (The submodules are fetched automatically.)  If GSL or
+FFTW is installed somewhere unusual, set `CMAKE_PREFIX_PATH` to its prefix.
+
+With `mamba` or `conda`
+-----------------------
+
+All of the build requirements are available from conda-forge:
+
+```bash
+mamba create -n gwframes -c conda-forge python numpy scipy h5py gsl fftw \
+    cxx-compiler cmake ninja pkg-config pybind11 scikit-build-core
+mamba activate gwframes
+python -m pip install --no-deps --no-build-isolation "git+https://github.com/moble/GWFrames"
+```
+
+Checking the installation
+-------------------------
+
+```bash
+python -c 'import GWFrames; W = GWFrames.PNWaveform("TaylorT4", 0.0, [0., 0., 0.9], [0.0, 0.0, 0.9], 0.01); print("That worked!")'
+```
+
+
+Usage
+=====
+
+The primary objects are `Waveform` and `PNWaveform`, with various methods
+defined for each; quaternions and functions of arrays of quaternions are in
+`GWFrames.Quaternions`.  Detailed documentation of most functions may be found
+through Python's `help` function, as in `help(GWFrames.Waveform)`.  A Jupyter
+notebook in the `Docs` directory contains extensive examples, following the
+outline of the paper.
+
+Changes from the SWIG-based versions
+------------------------------------
+
+Version 2 replaces the SWIG bindings with [pybind11](https://pybind11.readthedocs.io/),
+and the old `setup.py` with CMake and
+[scikit-build-core](https://scikit-build-core.readthedocs.io/).  The Python
+interface is almost entirely unchanged, apart from these differences:
+
+* The separate `Quaternions` module is now `GWFrames.Quaternions`, so
+  `import Quaternions` becomes `from GWFrames import Quaternions`, and
+  `GWFrames.Quaternion` is also available.
+* Methods that modify a `Waveform` in place and return it (such as
+  `TransformToCorotatingFrame`) return the very same Python object, including
+  for `PNWaveform`.
+
+Several bugs were fixed along the way, notably that `Quaternion` objects
+compared equal exactly when they were *not* equal, and that `Hybridize` read
+past the end of an array and could not handle waveforms in an inertial frame.
+
+
+Development
+===========
+
+Clone the repository with its submodules, then build and test it with `uv`:
+
+```bash
+git clone --recursive https://github.com/moble/GWFrames.git
+cd GWFrames
+uv sync --no-editable
+uv run --no-sync pytest
+```
+
+The C++ code is in `cpp/`, the pybind11 bindings in `cpp/bindings/`, and the
+Python package in `src/GWFrames/`.  The submodules `Quaternions`,
+`SphericalFunctions`, `SpacetimeAlgebra`, and `PostNewtonian`, along with a
+vendored copy of [spinsfast](https://github.com/moble/spinsfast), are in
+`extern/`.  The tests include a comparison with results recorded from the last
+SWIG-based build; see `tests/reference/generate_swig_reference.py`.
+
+Releases are published to PyPI automatically when a GitHub release is created.
+
+Note on licensing: spinsfast, GSL, and FFTW are licensed under the GNU GPL, and
+the binary wheels link all three statically, so the wheels as a whole are
+covered by the GPL.
+
+
+Contributions
+=============
+
+The code is primarily written by me (Mike Boyle).  Dan Hemberger helped by
+porting some of my older code from [Triton](https://github.com/moble/Triton) to
+perform noise-weighted overlap calculations, and with numerous bug reports and
+helpful suggestions.  Serguei Ossokine also helped substantially by
+cross-checking the post-Newtonian formulas and results.  Dante Iozzo has done
+his best to keep things working as this code enters its dotage.
+
+Other contributions are entirely welcome.  If you have a bug report, just go to
+the [issues](https://github.com/moble/GWFrames/issues) page for this repo,
+check for related issues, and if this is new click "New Issue".  If you want to
+contribute code, please open a pull request.

gwframes-2.0.0/README.md

@@ -0,0 +1,162 @@
+> [!NOTE]
+> **For post-Newtonian waveforms, use [PostNewtonian.jl](https://github.com/moble/PostNewtonian.jl).**
+> It is far more complete, accurate, and flexible than the post-Newtonian code
+> in this package.  Most of the rest of the functionality here has moved to
+> [`scri`](https://github.com/moble/scri) and [`sxs`](https://github.com/sxs-collaboration/sxs).
+> GWFrames is kept working mainly as a reference implementation to compare
+> other codes against.
+
+[![Tests](https://github.com/moble/GWFrames/actions/workflows/tests.yml/badge.svg)](https://github.com/moble/GWFrames/actions/workflows/tests.yml)
+[![Wheels](https://github.com/moble/GWFrames/actions/workflows/wheels.yml/badge.svg)](https://github.com/moble/GWFrames/actions/workflows/wheels.yml)
+
+GWFrames
+========
+
+Manipulate gravitational waveforms — changing frames, and so on.
+
+The code in this project extends code written for the paper "[Angular velocity
+of gravitational radiation from precessing binaries and the corotating
+frame](https://arxiv.org/abs/1302.2919)", giving an explicit implementation of
+the methods discussed in it.  The first commit of this project is the last
+commit of the paper's project.
+
+The license for using this software is basically open (see the LICENSE file in
+this directory), though citations to the original paper are appreciated, where
+relevant.  Also, if your work depends on features found in this module that
+have not been described in a separate publication of mine, I would appreciate
+the opportunity to be a coauthor.
+
+Note that this code is not optimized.  In many cases, obvious optimizations
+were rejected in favor of clearer or simpler code, or code that simply
+reflected the discussion in the paper more directly.  The code is generally
+more than fast enough for interactive use on individual waveforms, but there is
+plenty of room for improvement.  In particular, rotations may be painfully slow
+for large data sets.
+
+
+Installation
+============
+
+GWFrames requires Python 3.11 or newer, on Linux or macOS.
+
+With `uv` or `pip`
+------------------
+
+Binary wheels for Linux and macOS (x86_64 and arm64) are published on PyPI, so
+the simplest installation is
+
+```bash
+uv add GWFrames        # in a uv project
+uv pip install GWFrames  # or in any virtual environment
+pip install GWFrames     # or with pip
+```
+
+To install the latest code from GitHub, or on any platform without a wheel,
+GWFrames is compiled from source.  That needs a C++ compiler,
+[GSL](https://www.gnu.org/software/gsl/), and [FFTW](https://www.fftw.org/),
+which are available from most package managers:
+
+```bash
+sudo apt-get install libgsl-dev libfftw3-dev   # Debian or Ubuntu
+brew install gsl fftw                          # macOS with Homebrew
+```
+
+after which
+
+```bash
+uv pip install "git+https://github.com/moble/GWFrames"
+```
+
+builds and installs it.  (The submodules are fetched automatically.)  If GSL or
+FFTW is installed somewhere unusual, set `CMAKE_PREFIX_PATH` to its prefix.
+
+With `mamba` or `conda`
+-----------------------
+
+All of the build requirements are available from conda-forge:
+
+```bash
+mamba create -n gwframes -c conda-forge python numpy scipy h5py gsl fftw \
+    cxx-compiler cmake ninja pkg-config pybind11 scikit-build-core
+mamba activate gwframes
+python -m pip install --no-deps --no-build-isolation "git+https://github.com/moble/GWFrames"
+```
+
+Checking the installation
+-------------------------
+
+```bash
+python -c 'import GWFrames; W = GWFrames.PNWaveform("TaylorT4", 0.0, [0., 0., 0.9], [0.0, 0.0, 0.9], 0.01); print("That worked!")'
+```
+
+
+Usage
+=====
+
+The primary objects are `Waveform` and `PNWaveform`, with various methods
+defined for each; quaternions and functions of arrays of quaternions are in
+`GWFrames.Quaternions`.  Detailed documentation of most functions may be found
+through Python's `help` function, as in `help(GWFrames.Waveform)`.  A Jupyter
+notebook in the `Docs` directory contains extensive examples, following the
+outline of the paper.
+
+Changes from the SWIG-based versions
+------------------------------------
+
+Version 2 replaces the SWIG bindings with [pybind11](https://pybind11.readthedocs.io/),
+and the old `setup.py` with CMake and
+[scikit-build-core](https://scikit-build-core.readthedocs.io/).  The Python
+interface is almost entirely unchanged, apart from these differences:
+
+* The separate `Quaternions` module is now `GWFrames.Quaternions`, so
+  `import Quaternions` becomes `from GWFrames import Quaternions`, and
+  `GWFrames.Quaternion` is also available.
+* Methods that modify a `Waveform` in place and return it (such as
+  `TransformToCorotatingFrame`) return the very same Python object, including
+  for `PNWaveform`.
+
+Several bugs were fixed along the way, notably that `Quaternion` objects
+compared equal exactly when they were *not* equal, and that `Hybridize` read
+past the end of an array and could not handle waveforms in an inertial frame.
+
+
+Development
+===========
+
+Clone the repository with its submodules, then build and test it with `uv`:
+
+```bash
+git clone --recursive https://github.com/moble/GWFrames.git
+cd GWFrames
+uv sync --no-editable
+uv run --no-sync pytest
+```
+
+The C++ code is in `cpp/`, the pybind11 bindings in `cpp/bindings/`, and the
+Python package in `src/GWFrames/`.  The submodules `Quaternions`,
+`SphericalFunctions`, `SpacetimeAlgebra`, and `PostNewtonian`, along with a
+vendored copy of [spinsfast](https://github.com/moble/spinsfast), are in
+`extern/`.  The tests include a comparison with results recorded from the last
+SWIG-based build; see `tests/reference/generate_swig_reference.py`.
+
+Releases are published to PyPI automatically when a GitHub release is created.
+
+Note on licensing: spinsfast, GSL, and FFTW are licensed under the GNU GPL, and
+the binary wheels link all three statically, so the wheels as a whole are
+covered by the GPL.
+
+
+Contributions
+=============
+
+The code is primarily written by me (Mike Boyle).  Dan Hemberger helped by
+porting some of my older code from [Triton](https://github.com/moble/Triton) to
+perform noise-weighted overlap calculations, and with numerous bug reports and
+helpful suggestions.  Serguei Ossokine also helped substantially by
+cross-checking the post-Newtonian formulas and results.  Dante Iozzo has done
+his best to keep things working as this code enters its dotage.
+
+Other contributions are entirely welcome.  If you have a bug report, just go to
+the [issues](https://github.com/moble/GWFrames/issues) page for this repo,
+check for related issues, and if this is new click "New Issue".  If you want to
+contribute code, please open a pull request.

gwframes-2.0.0/cpp/Errors.hpp

@@ -0,0 +1,35 @@
+// Copyright (c) 2026, Michael Boyle
+// See LICENSE file for details
+
+#ifndef ERRORS_HPP
+#define ERRORS_HPP
+
+// Note: These error codes are used in SWIG/Exceptions.i.
+//       If you change them here, change them there.
+
+#define GWFrames_NotYetImplemented 0
+#define GWFrames_FailedSystemCall 1
+#define GWFrames_BadFileName 2
+#define GWFrames_FailedGSLCall 3
+// #define GWFrames_ 4
+// #define GWFrames_ 5
+// #define GWFrames_ 6
+// #define GWFrames_ 7
+// #define GWFrames_ 8
+// #define GWFrames_ 9
+#define GWFrames_ValueError 10
+#define GWFrames_BadSwitches 11
+#define GWFrames_IndexOutOfBounds 12
+// #define GWFrames_ 13
+// #define GWFrames_ 14
+#define GWFrames_VectorSizeMismatch 15
+#define GWFrames_MatrixSizeMismatch 16
+#define GWFrames_MatrixSizeAssumedToBeThree 17
+#define GWFrames_NotEnoughPointsForDerivative 18
+#define GWFrames_EmptyIntersection 19
+#define GWFrames_WaveformMissingLMIndex 20
+#define GWFrames_WrongFrameType 21
+#define GWFrames_BadWaveformInformation 22
+#define GWFrames_UnknownDetector 23
+
+#endif // ERRORS_HPP