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 this one, for example. 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 screw up how your OS works.
- Don't use
sudo
when doing anything involving python. - Do use an environment manager:
- Anaconda is best for scientific python
- Virtualenv is slightly simpler, but much less capable
- Pip is a useful tool, but is not an environment manager; don't rely on it alone
- Pipenv is only suitable for web development, not scientific python; don't use this at all
The sxs
package requires python 3.6 or greater, and a bunch of other packages that should be automatically installed along with it.
The simplest way to install this package is to install anaconda (from the link above) and then install sxs
like this:
conda install -c conda-forge sxs
But if you have your own environment set up in some other way you could also do
python -m pip install sxs
If you want a more complete set of tools, you could also do something like
conda install -c conda-forge sxs-ecosystem
or
python -m pip install sxs[ecosystem]
This installs nice goodies like Matplotlib for plotting and Jupyter for running interactive notebooks like this one yourself. On non-Windows systems, this also installs some other useful packages from the SXS collaboration, like scri
.
User interface: Proof of concept¶
The goal of this package is to enable users to do something like this:
waveform = sxs.load("SXS:BBH:0123/Lev/rhOverM", extrapolation_order=2)
This function will
- find the most recent version of the data
- download it if desired
- cache it if desired
- decipher the format for this particular file
- return an object that provides a uniform interface to the data
Just to prove that this is possible, here's a simple example taking you from 0 to plot in 4 lines of code:
import matplotlib.pyplot as plt
import sxs
waveform = sxs.load("SXS:BBH:0123/Lev/rhOverM", extrapolation_order=2)
plt.plot(waveform.t, waveform.data.real);
Skipping download from 'https://data.black-holes.org/catalog.json' because local file is newer Found the following files to load from the SXS catalog: SXS:BBH:0123v4/Lev5/rhOverM_Asymptotic_GeometricUnits_CoM.h5
(If this failed for you, it's probably because you don't already have the data, and you haven't set up any sensible defaults. See below for advice on that.)
This example loads the data into the waveform
object. Then, we extract the time data with waveform.t
, and the real part of the complex data with waveform.data.real
. We will get into much more detail about this in the following notebooks.
Configuration and caching¶
Downloading data files every time you load them will very quickly become boring — especially with the old inefficient monolithic files. You'll probably want to set up caching by default.
To start with, this package will try to store configuration settings somewhere. Find where that is with this:
sxs.sxs_directory("config") # Probably returns some path in your home directory
PosixPath('/Users/boyle/.sxs')
Now, let's try to write our sensible defaults to the config file:
sxs.write_config(download=True, cache=True)
You can check that this worked by reading your config file:
sxs.read_config()
{'download': True, 'cache': True}
You can also find the directory used to cache the data:
sxs.sxs_directory("cache") # Probably returns some path in your home directory
PosixPath('/Users/boyle/.sxs/cache')
Now that that's all set up, you should be able to use the sxs
package efficiently.
The notebooks¶
It is probably best to go through these notebooks in order: