Simulating eXtreme Spacetimes package
The sxs python package provides a high-level interface for using data
produced by the SXS collaboration. In particular, the function sxs.load can
automatically find, download, and load data, returning objects that provide
common interfaces to the various types of data, without forcing the user to
worry about details like data formats or where to find the data. It can also
automatically select the newest or highest-resolution dataset for a given
simulation, or return a range of versions or resolutions. Currently, the
high-level objects encapsulate
- Dataframe — a catalog of all simulations produced by the SXS collaboration
- Simulation — an object encapsulating all data for a single simulation
- Metadata — data describing the simulation parameters
- Horizons — time-series data describing the apparent horizons
- Waveform — time-series data describing the extrapolated gravitational-wave modes
Installation
Because this package is pure python code, installation is very simple. In particular, with a reasonably modern installation, you can just run a command like
python -m pip install sxs
or
mamba install -c conda-forge sxs
Here, the first command assumes that you have an appropriate python
environment set up in some other way;
mamba is the
newer replacement for conda, and is a convenient way to install
python and manage environments. Either of these commands will
download and install the sxs package and its most vital
requirements.
You may also want to set some convenient defaults to automatically download and cache data:
python -c "import sxs; sxs.write_config(download=True, cache=True)"
This will write a configuration file in the directory returned by
sxs.sxs_directory("config"), and downloaded data will be cached in the
directory returned by sxs.sxs_directory("cache"). See that function's
documentation
for details.
Citing this package and/or data
If you use this package and/or the data it provides in your research,
please cite them, including the specific version of the data that
you use (see below). To help with this, we provide the function
sxs.cite. Use print(sxs.cite()) to see BibTeX citations for the
version of this package you are using, the most recent paper
describing the catalog, and the catalog data itself. Use, e.g.,
print(sxs.cite("SXS:BBH:0001", "SXS:BBH:4001")) to include citations
for those specific simulations and the papers that introduced them.
Usage
An extensive demonstration of this package's capabilities is available
here, in the form of
interactive jupyter notebooks that are actually running this code and some
pre-downloaded data. The following is just a very brief overview of the sxs
package's main components.
Loading a specific version of the catalog
For the purposes of reproducibility — both reproducing your own
results and allowing others to reproduce them — it is important to be
aware of which version of the catalog you are using, and to cite it
when you publish results using SXS data. Whenever sxs tries to load
data, it most first load some version of the catalog. If you do not
specify a version, it will automatically find and load the most recent
version available via github, and print out a message telling you
which version it is using, like
Loading SXS simulations using latest tag 'v3.0.0', published at 2025-05-12T10:00:00Z.
For the rest of that Python session, all data loaded will be from that version of the catalog. If you want to use a different version, you can specify it explicitly while loading the catalog — preferably as
sxs.load("dataframe", tag="3.0.0")
Even if you do not use the returned object from this command, it will
ensure that all data will be loaded from the specified version of the
catalog. Thus, it is best practice to make this call as soon as you
import the sxs package.
Interacting with the data
There are four important objects to understand in this package:
import sxs
# Load a specific version of the catalog for reproducibility
df = sxs.load("dataframe", tag="3.0.0")
# Load a specific simulation
sim = sxs.load("SXS:BBH:4001")
# Obtain data about the horizons
horizons = sim.horizons
# Obtain data about the gravitational-wave strain
h = sim.h
Note that tag is optional, but is good to include because it sets
the version of the catalog from which data is loaded, which ensures
reproducibility. Leave it out to see the most recent version
available, and then use that version consistently in any analysis. Be
sure to cite the specific version of the catalog you used in any
publications.
The "dataframe"
df contains information about every simulation in the catalog,
including all available data files, and information about how to get
them. You probably don't need to actually know about details like
where to get the data, but df can help you find the simulations you
care about. It is a
pandas.DataFrame object, where
the rows are names of simulations (like "SXS:BBH:0123") and the
columns include the
metadata
for the simulations — things like mass ratio, spins, eccentricity,
etc. — in addition to extra refinements like spin magnitudes, etc.
Once you have found a simulation you want to work with, you can load
it with, e.g., sxs.load("SXS:BBH:4001"), which will return a
Simulation
object, which contains metadata about the simulation, and allows you
to load data from the simulation. By default, it uses the
highest-resolution run of the simulation, though this lower
resolutions can be specified.
The actual data itself is primarily contained in the next two objects. The
horizons
object
has three attributes — horizons.A, horizons.B, and horizons.C — typically
representing the original two horizons of the black-hole binary and the common
horizon that forms at merger. In matter simulations, one or more of these may
be None. Otherwise, each of these three is a
HorizonQuantities
object, containing several timeseries relating to mass, spin, and position.
Finally, the h
waveform
encapsulates the modes of the strain waveform and the corresponding
time information, along with relevant metadata like data type, spin
weight, etc., with useful features like numpy-array-style slicing.
There is also psi4 data available, which is computed with entirely
different methods; h and psi4 are not just computed one from the
other by a double integral or differentiation. As a result, we
generally recommend using h instead of psi4 unless you have very
specific requirements.
Contributing
Contributions are welcome! There are at least two ways to contribute to this codebase:
- If you find a bug or want to suggest an enhancement, use the issue tracker on GitHub. It's a good idea to look through past issues, too, to see if anybody has run into the same problem or made the same suggestion before.
- If you will write or edit the python code, we use the fork and pull request model.
You are also allowed to make use of this code for other purposes, as detailed in the MIT license. For any type of contribution, please follow the code of conduct.
Reporting catalog data issues
If you find an issue with our data or metadata, please let us know! Fill out an issue with the catalog data template and we will take a look as soon as possible.
1 maintainer
Release files for sxs 2026.0.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sxs-2026.0.6.tar.gz | 9.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sxs-2026.0.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 10.2 MB
Release files / sxs-2026.0.6.tar.gz
| Download URL | sxs-2026.0.6.tar.gz |
|---|---|
| Size | 9.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
34942a8b5df12484c4b84179d39449aeda9d6910e1fa825ba41fcd4a37f6be47
|
|
BLAKE2b-256 checksum How to use checksums |
fcbcbce226650028c6679140f8d3ebae74f49b06fa72e3e4ab1dd337431bac6f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
Hatch/1.18.1 {"ci":true,"cpu":"x86_64","distro":{"id":"noble","libc":{"lib":"glibc","version":"2.39"},"name":"Ubuntu","version":"24.04"},"implementation":{"name":"CPython","version":"3.13.15"},"installer":{"name":"hatch","version":"1.18.1"},"openssl_version":"OpenSSL 3.0.13 30 Jan 2024","python":"3.13.15","system":{"name":"Linux","release":"6.17.0-1022-azure"}} HTTPX2/2.13.1
|
Release files / sxs-2026.0.6-py3-none-any.whl
| Download URL | sxs-2026.0.6-py3-none-any.whl |
|---|---|
| Size | 244.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2febf49e3a6c27e43a3a3fc4680f56fecec1c705504a07ba7d03114d3e337e10
|
|
BLAKE2b-256 checksum How to use checksums |
7c1ecf75771635d632335e28d663568d7fc0dd9504d97234330a2fbbad73d697
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
Hatch/1.18.1 {"ci":true,"cpu":"x86_64","distro":{"id":"noble","libc":{"lib":"glibc","version":"2.39"},"name":"Ubuntu","version":"24.04"},"implementation":{"name":"CPython","version":"3.13.15"},"installer":{"name":"hatch","version":"1.18.1"},"openssl_version":"OpenSSL 3.0.13 30 Jan 2024","python":"3.13.15","system":{"name":"Linux","release":"6.17.0-1022-azure"}} HTTPX2/2.13.1
|
