Introduction¶

This series of notebooks describes the sxs python package, which provides an interface to the data produced by the Simulating eXtreme Spacetimes collaboration. All that data is hosted on Zenodo and CaltechDATA. Each simulation gets its own DOI and its own web page — like DOI 10.26138/SXS:BBH:4001, for example, which redirects to its CaltechDATA page. But you want an easier way to get the data than clicking on links. This package will do that for you.

The documentation is here. The github page is here. Please feel free to open issues to report problems, or pull requests to fix them.

Pythonic Preliminaries¶

• Don't use your system python. Installing packages to it might mess up how your OS works.
• Don't use sudo when doing anything involving python.
• Do use an environment manager:
  • pixi is the latest way to use conda/mamba.
  • uv is the only reasonable way to use pip.

The sxs package requires python 3.10 or greater, and a bunch of other packages that should be automatically installed along with it.

The old-fashioned ways to install this package work as usual:

python -m pip install sxs

or

mamba install -c conda-forge sxs

When using either pixi or uv — as we recommend — you can add the package to your workspace/environment with

pixi init sxs  # If you don't have a workspace already
pixi add sxs

or

uv venv  # If you don't have a venv already
uv pip install sxs

Configuration and caching preliminaries¶

By default, downloading data is turned off, which means you will be responsible for obtaining the data yourself. However, an easier option is to let sxs download the data for you.

Of course, downloading data files every time you load them will use a lot of bandwidth. You'll probably want to set up automatic caching of files to disk.

And finally you may want to automatically get the newest simulation for a given set of physical parameters whenever possible.

The sxs package can be configured to do all of these things for you. To start with, this package will try to store configuration settings somewhere. Find where that is with this:

In [1]:

import sxs

sxs.sxs_directory("config")  # Probably returns some path in your home directory

import sxs sxs.sxs_directory("config") # Probably returns some path in your home directory

Out[1]:

PosixPath('/Users/boyle/.sxs')

Now, let's try to write our defaults to the config file:

In [2]:

sxs.write_config(download=True, cache=True, auto_supersede=False)

sxs.write_config(download=True, cache=True, auto_supersede=False)

You can check that this worked by reading your config file:

In [3]:

sxs.read_config()

sxs.read_config()

Out[3]:

{'download': True, 'cache': True, 'auto_supersede': False}

You can also find the directory used to cache the data:

In [4]:

sxs.sxs_directory("cache")  # Probably returns some path in your home directory

sxs.sxs_directory("cache") # Probably returns some path in your home directory

Out[4]:

PosixPath('/Users/boyle/.sxs/cache')

Now that that's all set up, you should be able to use the sxs package efficiently.

User interface: Proof of concept¶

The goal of this package is to enable users to do something like this:

sxs_bbh_1234 = sxs.load("SXS:BBH:1234")
h = sxs_bbh_1234.h

The first line will

1. download the catalog of SXS simulations with relevant metadata, if necessary, and cache it to disk if desired
2. find the metadata for the simulation with the given ID
3. check that the simulation has not been deprecated (if so, it will advise you of what to do)
4. decide on the version and Lev to use — defaulting to the most recent of each
5. download the list of files for that simulation, if necessary, and cache it to disk if desired
6. return a Simulation object with the metadata for "SXS:BBH:0123"

However, no data will be loaded (or downloaded if necessary) until requested. The second line requests the strain data h for this simulation. This line will

1. download the h data, if necessary, and cache it to disk if desired
2. load the data as a WaveformModes object, providing a uniform interface to the data
3. cache the data in the Simulation object, so that it is not reloaded if requested again

Just to prove that this is possible, here's a simple example taking you from zero to plot in four lines of code:

In [5]:

import matplotlib.pyplot as plt
import sxs

sxs_bbh_1234 = sxs.load("SXS:BBH:1234")
plt.plot(sxs_bbh_1234.h.t, sxs_bbh_1234.h.data.real);

import matplotlib.pyplot as plt import sxs sxs_bbh_1234 = sxs.load("SXS:BBH:1234") plt.plot(sxs_bbh_1234.h.t, sxs_bbh_1234.h.data.real);

(If this failed for you, it's probably because you don't already have the data, and you haven't set up the sensible defaults in the previous section. Review that advice to see how to set up those defaults, or pass download=True to the sxs.load function to download just this once.)

Note that h.data represents the modes of the strain waveform, which do not asymptote to zero after merger because of memory effects — real physical effects that should be present in the waveforms.

This example loads the metadata into the sxs_bbh_1234 object. Then, as soon as sxs_bbh_1234.h is accessed, it downloads and loads the waveform. We extract the time data with sxs_bbh_1234.h.t, and the real part of the complex data with sxs_bbh_1234.h.data.real. We will get into much more detail about this in the following notebooks.

The notebooks¶

It is probably best to go through these notebooks in order:

1. The catalog DataFrame interface
2. The Simulation interface
3. Data describing Horizons
4. Introduction to WaveformModes objects