sxs 2025.0.12__tar.gz → 2025.0.13__tar.gz

{sxs-2025.0.12 → sxs-2025.0.13}/CITATION.cff

@@ -4,11 +4,17 @@ authors:
   - family-names: Boyle
     given-names: Michael
     orcid: https://orcid.org/0000-0002-5075-5116
+  - family-names: "Mitman"
+    given-names: "Keefe"
+    orcid: "https://orcid.org/0000-0003-0276-3856"
   - family-names: "Scheel"
     given-names: "Mark"
     orcid: "https://orcid.org/0000-0001-6656-9134"
+  - family-names: "Stein"
+    given-names: "Leo"
+    orcid: "https://orcid.org/0000-0001-7559-9597"
 title: "The sxs package"
 license: MIT
 doi: 10.5281/zenodo.4034006
-version: 2025.0.12
+version: 2025.0.13
 date-released: 2025-05-12

{sxs-2025.0.12 → sxs-2025.0.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sxs
-Version: 2025.0.12
+Version: 2025.0.13
 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/
@@ -35,6 +35,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Astronomy
 Classifier: Topic :: Scientific/Engineering :: Physics
 Requires-Python: >=3.10
+Requires-Dist: bibtexparser>=2.0.0b8
 Requires-Dist: h5py>=3
 Requires-Dist: inflection>=0.5.1
 Requires-Dist: juliacall>=0.9.20
@@ -91,11 +92,11 @@ 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
 
-  * Simulations — a catalog of all simulations produced by the SXS collaboration
+  * 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
-  * Waveforms — time-series data describing the extrapolated gravitational-wave
+  * Waveform — time-series data describing the extrapolated gravitational-wave
     modes
 
 
@@ -105,36 +106,25 @@ 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
 
-```bash
-conda install -c conda-forge sxs
-```
-
-or
-
 ```bash
 python -m pip install sxs
 ```
 
-Here, `conda` requires the [conda](https://docs.anaconda.com/anaconda/install/)
-installation of python, which is the most recommended approach for scientific
-python; the second command assumes that you have an appropriate python
-environment set up in some other way.  Either of these commands will download
-and install the `sxs` package and its most vital requirements.
-
-If you want to install all the goodies that enable things like jupyter
-notebooks with plots and interactive tables, you could run
-
-```bash
-conda install -c conda-forge sxs-ecosystem
-```
-
 or
 
 ```bash
-python -m pip install sxs[ecosystem]
+mamba install -c conda-forge sxs
 ```
 
-You will probably also want to set some sensible defaults to automatically
+Here, the first command assumes that you have an appropriate python
+environment set up in some other way;
+[`mamba`](https://mamba.readthedocs.io/en/latest/index.html) 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:
 
 ```bash
@@ -147,6 +137,16 @@ directory returned by `sxs.sxs_directory("cache")`.  See [that function's
 documentation](https://sxs.readthedocs.io/en/main/api/sxs.utilities.sxs_directories/#sxsutilitiessxs_directoriessxs_directory)
 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`, which will print out a citation — in BibTeX format or just
+the DOIs — for the package, the most recent paper describing the
+catalog, the catalog data itself, and optionally individual
+simulations.
+
 
 ## Usage
 
@@ -156,36 +156,83 @@ 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.
 
-There are five important objects to understand in this package:
+### 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
+
+```python
+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
+
+```python
+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:
 
 ```python
 import sxs
 
-simulations = sxs.load("simulations")
-sxs_bbh_1234 = sxs.load("SXS:BBH:1234")
-metadata = sxs_bbh_1234.metadata
-horizons = sxs_bbh_1234.horizons
-h = sxs_bbh_1234.h
+# 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
 ```
 
-[The `simulations`
-object](https://sxs.readthedocs.io/en/main/api/simulations/) 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 `simulations` can help you find the simulations you care
-about.  It is a `dict` object, where the keys are names of simulations
-(like "SXS:BBH:0123") and the values are the same types as [the
-`metadata`
-object](https://sxs.readthedocs.io/en/main/api/sxs.metadata.metadata/#sxs.metadata.metadata.Metadata),
-which contains metadata about that simulation — things like mass
-ratio, spins, etc.  This `metadata` reflects the actual output of the
-simulations, which leads to some inconsistencies in their formats.  A
-more consistent interface (though it is biased toward returning NaNs
-where a human might glean more information) is provided by
-`simulations.dataframe`, which returns a
-[`pandas`](https://pandas.pydata.org/docs/) `DataFrame` with specific
-data types for each column.
+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"](https://sxs.readthedocs.io/en/main/api/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`](https://pandas.pydata.org/docs/) object, where
+the rows are names of simulations (like "SXS:BBH:0123") and the
+columns include [the
+`metadata`](https://sxs.readthedocs.io/en/main/api/sxs.metadata.metadata/#sxs.metadata.metadata.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`](https://sxs.readthedocs.io/en/main/api/sxs.simulation/#sxs.simulation.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`
@@ -197,8 +244,14 @@ be `None`.  Otherwise, each of these three is a
 [`HorizonQuantities`](https://sxs.readthedocs.io/en/main/api/sxs.horizons/#sxs.horizons.HorizonQuantities)
 object, containing several timeseries relating to mass, spin, and position.
 
-Finally, the
-[`waveform`](https://sxs.readthedocs.io/en/main/api/sxs.waveforms.waveform_modes/#sxs.waveforms.waveform_modes.WaveformModes)
-encapsulates the modes of the waveform and the corresponding time information,
-along with relevant metadata like data type, spin weight, etc., and useful
-features like numpy-array-style slicing.
+Finally, the [`h`
+waveform](https://sxs.readthedocs.io/en/main/api/sxs.waveforms.waveform_modes/#sxs.waveforms.waveform_modes.WaveformModes)
+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.

sxs-2025.0.13/README.md

@@ -0,0 +1,182 @@
+[![Test Status](https://github.com/sxs-collaboration/sxs/workflows/tests/badge.svg)](https://github.com/sxs-collaboration/sxs/actions)
+[![Documentation Status](https://readthedocs.org/projects/sxs/badge/?version=main)](https://sxs.readthedocs.io/en/main/?badge=main)
+[![PyPI Version](https://img.shields.io/pypi/v/sxs?color=)](https://pypi.org/project/sxs/)
+[![Conda Version](https://img.shields.io/conda/vn/conda-forge/sxs.svg?color=)](https://anaconda.org/conda-forge/sxs)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/sxs-collaboration/sxs/blob/main/LICENSE)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/moble/sxs_notebooks/main)
+
+
+# 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
+
+```bash
+python -m pip install sxs
+```
+
+or
+
+```bash
+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`](https://mamba.readthedocs.io/en/latest/index.html) 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:
+
+```bash
+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](https://sxs.readthedocs.io/en/main/api/sxs.utilities.sxs_directories/#sxsutilitiessxs_directoriessxs_directory)
+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`, which will print out a citation — in BibTeX format or just
+the DOIs — for the package, the most recent paper describing the
+catalog, the catalog data itself, and optionally individual
+simulations.
+
+
+## Usage
+
+An extensive demonstration of this package's capabilities is available
+[here](https://mybinder.org/v2/gh/moble/sxs_notebooks/main), 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
+
+```python
+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
+
+```python
+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:
+
+```python
+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"](https://sxs.readthedocs.io/en/main/api/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`](https://pandas.pydata.org/docs/) object, where
+the rows are names of simulations (like "SXS:BBH:0123") and the
+columns include [the
+`metadata`](https://sxs.readthedocs.io/en/main/api/sxs.metadata.metadata/#sxs.metadata.metadata.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`](https://sxs.readthedocs.io/en/main/api/sxs.simulation/#sxs.simulation.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](https://sxs.readthedocs.io/en/main/api/sxs.horizons/#sxs.horizons.Horizons)
+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`](https://sxs.readthedocs.io/en/main/api/sxs.horizons/#sxs.horizons.HorizonQuantities)
+object, containing several timeseries relating to mass, spin, and position.
+
+Finally, the [`h`
+waveform](https://sxs.readthedocs.io/en/main/api/sxs.waveforms.waveform_modes/#sxs.waveforms.waveform_modes.WaveformModes)
+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.

sxs-2025.0.13/docs/api/metadata.md

@@ -0,0 +1,3 @@
+# `Metadata` class
+
+::: sxscatalog.metadata.metadata.Metadata

{sxs-2025.0.12 → sxs-2025.0.13}/docs/mathematica.md

@@ -8,7 +8,7 @@ containing the Python code you want to run.
 ## Getting Mathematica working with Python
 
 As of this writing, Mathematica *claims* that it works with all reasonably
-modern versions of Python — specificaly ["Python 2.6+ and Python
+modern versions of Python — specifically ["Python
 3.4+"](https://reference.wolfram.com/language/ref/externalevaluationsystem/Python.html).
 Assuming this is true, the only extra thing to worry about is that Mathematica
 requires the `pyzmq` package to interface with Python.

{sxs-2025.0.12 → sxs-2025.0.13}/docs/tutorials/00-Introduction.ipynb

@@ -17,41 +17,39 @@
    "source": [
     "# Pythonic Preliminaries\n",
     "\n",
-    "* ***Don't*** use your system python.  Installing packages to it might screw up how your OS works.\n",
+    "* ***Don't*** use your system python.  Installing packages to it might mess up how your OS works.\n",
     "* ***Don't*** use `sudo` when doing anything involving python.\n",
     "* ***Do*** use an environment manager:\n",
-    "  * [Anaconda](https://www.anaconda.com/products/individual) is best for scientific python\n",
-    "  * [Virtualenv](https://virtualenv.pypa.io/en/latest/) is slightly simpler, but much less capable\n",
-    "  * [Pip](https://pip.pypa.io/en/stable/) is a useful tool, but is not an environment manager; don't rely on it alone\n",
-    "  * Pipenv is only suitable for web development, not scientific python; don't use this at all\n",
+    "  * [`pixi`](https://pixi.sh/) is the latest way to use [conda](https://docs.conda.io/projects/conda/en/latest/index.html)/[mamba](https://mamba.readthedocs.io/en/latest/index.html).\n",
+    "  * [`uv`](https://docs.astral.sh/uv/) is the only reasonable way to use [`pip`](https://pip.pypa.io/en/stable/).\n",
     "\n",
-    "The `sxs` package requires python 3.8 or greater, and a bunch of other packages that should be automatically installed along with it.\n",
+    "The `sxs` package requires python 3.10 or greater, and a bunch of other packages that should be automatically installed along with it.\n",
     "\n",
-    "The simplest way to install this package is to install anaconda (from the link above) and then install `sxs` like this:\n",
+    "The old-fashioned ways to install this package work as usual:\n",
     "\n",
     "```python\n",
-    "conda install -c conda-forge sxs\n",
+    "python -m pip install sxs\n",
     "```\n",
     "\n",
-    "But if you have your own environment set up in some other way you could also do\n",
+    "or\n",
     "\n",
     "```python\n",
-    "python -m pip install sxs\n",
+    "mamba install -c conda-forge sxs\n",
     "```\n",
     "\n",
-    "If you want a more complete set of tools, you could also do something like\n",
+    "When using either `pixi` or `uv` — as we recommend — you can add the package to your workspace/environment with\n",
     "\n",
     "```python\n",
-    "conda install -c conda-forge sxs-ecosystem\n",
+    "pixi init sxs  # If you don't have a workspace already\n",
+    "pixi add sxs\n",
     "```\n",
     "\n",
     "or\n",
     "\n",
     "```python\n",
-    "python -m pip install sxs[ecosystem]\n",
-    "```\n",
-    "\n",
-    "This installs nice goodies like [Matplotlib](https://matplotlib.org/) for plotting and [Jupyter](https://jupyter.org/) 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`](https://github.com/moble/scri)."
+    "uv venv  # If you don't have a venv already\n",
+    "uv pip install sxs\n",
+    "```"
    ]
   },
   {
@@ -104,7 +102,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sxs.write_config(download=True, cache=True, auto_supersede=True)"
+    "sxs.write_config(download=True, cache=True, auto_supersede=False)"
    ]
   },
   {
@@ -122,7 +120,7 @@
     {
      "data": {
       "text/plain": [
-       "{'download': True, 'cache': True, 'auto_supersede': True}"
+       "{'download': True, 'cache': True, 'auto_supersede': False}"
       ]
      },
      "execution_count": 3,
@@ -183,7 +181,7 @@
     "\n",
     "The first line will\n",
     "\n",
-    "  1. download the catalog of SXS `Simulations` with relevant metadata, if necessary, and cache it to disk if desired\n",
+    "  1. download the catalog of SXS simulations with relevant metadata, if necessary, and cache it to disk if desired\n",
     "  2. find the metadata for the simulation with the given ID\n",
     "  3. check that the simulation has not been deprecated (if so, it will advise you of what to do)\n",
     "  4. decide on the version and `Lev` to use — defaulting to the most recent of each\n",
@@ -240,6 +238,8 @@
    "source": [
     "(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.)\n",
     "\n",
+    "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.\n",
+    "\n",
     "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."
    ]
   },
@@ -251,7 +251,7 @@
     "\n",
     "It is probably best to go through these notebooks in order:\n",
     "\n",
-    "  1. [The `Simulations` interface and `Metadata`](/tutorials/01-Simulations_and_Metadata)\n",
+    "  1. [The catalog `DataFrame` interface](/tutorials/01-Catalog_Dataframe)\n",
     "  2. [The `Simulation` interface](/tutorials/02-Simulation)\n",
     "  3. [Data describing `Horizons`](/tutorials/03-Horizons)\n",
     "  4. [Introduction to `WaveformModes` objects](/tutorials/04-Waveforms)"
@@ -274,7 +274,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.9"
+   "version": "3.12.3"
   },
   "widgets": {
    "application/vnd.jupyter.widget-state+json": {