sxs 2025.0.13__tar.gz → 2025.0.15__tar.gz

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

@@ -16,5 +16,5 @@ authors:
 title: "The sxs package"
 license: MIT
 doi: 10.5281/zenodo.4034006
-version: 2025.0.13
-date-released: 2025-05-12
+version: 2025.0.15
+date-released: 2025-05-14

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sxs
-Version: 2025.0.13
+Version: 2025.0.15
 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/
@@ -78,7 +78,7 @@ Description-Content-Type: text/markdown
 [![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)
+[![Open with marimo](https://marimo.io/shield.svg)](https://data.black-holes.org/)
 
 
 # Simulating eXtreme Spacetimes package
@@ -142,11 +142,11 @@ for details.
 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.
-
+`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
 
@@ -255,3 +255,30 @@ 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:
+
+1. If you find a bug or want to suggest an enhancement, use the [issue
+   tracker](https://github.com/sxs-collaboration/sxs/issues) 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.
+2. If you will write or edit the python code, we use the [fork and
+   pull
+   request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)
+   model.
+
+You are also allowed to make use of this code for other purposes, as
+detailed in the [MIT license](LICENSE).  For any type of contribution,
+please follow the [code of
+conduct](https://github.com/sxs-collaboration/.github/blob/master/CODE_OF_CONDUCT.md).
+
+## 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](https://github.com/sxs-collaboration/sxs/issues/new?template=catalog-data-issue-template.md)
+and we will take a look as soon as possible.

{sxs-2025.0.13 → sxs-2025.0.15}/README.md

@@ -3,7 +3,7 @@
 [![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)
+[![Open with marimo](https://marimo.io/shield.svg)](https://data.black-holes.org/)
 
 
 # Simulating eXtreme Spacetimes package
@@ -67,11 +67,11 @@ for details.
 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.
-
+`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
 
@@ -180,3 +180,30 @@ 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:
+
+1. If you find a bug or want to suggest an enhancement, use the [issue
+   tracker](https://github.com/sxs-collaboration/sxs/issues) 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.
+2. If you will write or edit the python code, we use the [fork and
+   pull
+   request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)
+   model.
+
+You are also allowed to make use of this code for other purposes, as
+detailed in the [MIT license](LICENSE).  For any type of contribution,
+please follow the [code of
+conduct](https://github.com/sxs-collaboration/.github/blob/master/CODE_OF_CONDUCT.md).
+
+## 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](https://github.com/sxs-collaboration/sxs/issues/new?template=catalog-data-issue-template.md)
+and we will take a look as soon as possible.

sxs-2025.0.15/docs/api/cite.md

@@ -0,0 +1,10 @@
+# `sxs.cite`
+
+For reasons of reproducibility — and for general academic integrity —
+it is important to cite the specific packages and data you use in your
+research.  In particular, it is absolutely vital to cite the specific
+version of the catalog of SXS simulations you use, as well as the
+version of this `sxs` package that you use.  The `sxs.cite` function
+provides those specific citations.
+
+::: sxs.cite

{sxs-2025.0.13 → sxs-2025.0.15}/docs/api/simulation.md

@@ -1,6 +1,6 @@
 # `Simulation` classes
 
-The `Simulation` classes are the primary interface for accessing
+The `Simulation` classes form the primary interface for accessing
 simulation data.  They are the top-level objects that contain all the
 data for a single simulation.  These classes are designed to be
 lightweight and to load data only when needed.
@@ -21,3 +21,6 @@ return the appropriate object.
 
 ## `Simulation_v2` class
 ::: sxs.simulations.simulation.Simulation_v2
+
+## `Simulation_v3` class
+::: sxs.simulations.simulation.Simulation_v3

{sxs-2025.0.13 → sxs-2025.0.15}/mkdocs.yml

@@ -30,6 +30,7 @@ nav:
     - "Time Series": "api/time_series.md"
     - "Horizons": "api/horizons.md"
     - "Waveforms": "api/waveforms.md"
+    - "Cite": "api/cite.md"
   - "Calling from Mathematica": "mathematica.md"
   - "Calling from Julia": "julia.md"
 

sxs-2025.0.15/sxs/__version__.py

@@ -0,0 +1 @@
+__version__ = "2025.0.15"

{sxs-2025.0.13 → sxs-2025.0.15}/sxs/citation.py

@@ -1,7 +1,7 @@
 def cite(*sxs_ids, bibtex=True):
     """Cite this package and/or data
 
-    Prints out a citation for the package, the most recent paper
+    Prints out a citation for this package, the most recent paper
     describing the catalog, the catalog data itself, and optionally
     individual simulations.
 
@@ -30,6 +30,9 @@ def cite(*sxs_ids, bibtex=True):
     from . import doi_prefix, load, __version__
     from . import sxs_id as sxs_identifier
 
+    if len(sxs_ids) == 1 and isinstance(sxs_ids[0], (list, tuple)):
+        sxs_ids = tuple(sxs_ids[0])
+
     simulations = load("simulations")
 
     # Get the DOI for this version of this package

{sxs-2025.0.13 → sxs-2025.0.15}/sxs/handlers.py

@@ -199,29 +199,36 @@ def load(location, download=None, cache=None, progress=None, truepath=None, **kw
     -----
     This function can load data in various ways.
 
-      1) Given an absolute or relative path to a local file, it just
-         loads the data directly.
-
-      2) If `truepath` is set, and points to a file that exists —
+      1) If `truepath` is set, and points to a file that exists —
          whether absolute, relative to the current working directory,
          or relative to the cache directory — that file will be
          loaded.
 
-      3) If `location` is a valid URL including the scheme (https://,
+      2) Given an absolute or relative path to a local file, it just
+         loads the data directly.
+
+      3) If `location` is one of "simulations" or "dataframe" (or the
+         deprecated "catalog"), the corresponding catalog data is
+         loaded.  The "simulations" option returns a dictionary mapping
+         SXS IDs to raw metadata, while "dataframe" returns a pandas
+         DataFrame indexed by SXS ID, but the metadata is processed
+         into more consistent form.
+
+      4) If `location` is a valid URL including the scheme (https://,
          or http://), it will be downloaded regardless of the
          `download` parameter and optionally cached.
 
-      4) Given an SXS simulation specification — like "SXS:BBH:1234",
+      5) Given an SXS simulation specification — like "SXS:BBH:1234",
          "SXS:BBH:1234v2.0", "SXS:BBH:1234/Lev5", or
          "SXS:BBH:1234v2.0/Lev5" — the simulation is loaded as an
          `sxs.Simulation` object.
 
-      5) Given an SXS path — like
+      6) Given an SXS path — like
          "SXS:BBH:1234/Lev5/h_Extrapolated_N2.h5" — the file is
          located in the catalog for details.  This function then looks
          in the local cache directory and loads it if present.
 
-      6) If the SXS path is not found in the cache directory and
+      7) If the SXS path is not found in the cache directory and
          `download` is set to `True` (when this function is called, or
          in the sxs config file) this function attempts to download
          the data.  Note that `download` must be explicitly set in
@@ -263,6 +270,15 @@ def load(location, download=None, cache=None, progress=None, truepath=None, **kw
         elif truepath and (testpath := cache_path / sxs_path_to_system_path(truepath)).exists():
             path = testpath
 
+        elif _safe_resolve_exists(path):
+            pass  # We already have the correct path
+
+        elif location == "catalog":
+            return Catalog.load(download=download)
+
+        elif location in ["simulations", "dataframe"]:
+            return sxscatalog.load(location, download=download, **kwargs)
+
         elif _safe_resolve_exists(h5_path):
             path = h5_path
 
@@ -278,12 +294,6 @@ def load(location, download=None, cache=None, progress=None, truepath=None, **kw
                     raise ValueError(f"File '{truepath}' not found in cache, but downloading turned off")
                 download_file(location, path, progress=progress)
 
-        elif location == "catalog":
-            return Catalog.load(download=download)
-
-        elif location in ["simulations", "dataframe"]:
-            return sxscatalog.load(location, download=download, **kwargs)
-
         elif sxs_id_version_lev_exact_re.match(location):
             return Simulation(location, download=download, cache=cache, progress=progress, **kwargs)
 

{sxs-2025.0.13 → sxs-2025.0.15}/tests/test_simulation.py

@@ -2,7 +2,8 @@ import pytest
 import sxs
 from .conftest import skip_macOS_GH_actions_downloads
 
-@pytest.mark.xfail(reason="Missing files in the catalog should be updated soon")
+
+@skip_macOS_GH_actions_downloads
 def test_catalog_file_sizes():
     simulations = sxs.load("simulations")
     success = True

{sxs-2025.0.13 → sxs-2025.0.15}/tests/test_utilities.py

@@ -98,28 +98,33 @@ def test_sxs_directory_unwritable(directory_type, tmp_path, monkeypatch):
     import os
     import stat
     from pathlib import Path
+    import shutil
 
     d = tmp_path / "unwritable"
-    d.mkdir(mode=0o000)
-    assert d.exists()
-    assert d.is_dir()
-    assert stat.filemode(d.stat().st_mode) == "d---------"
-    assert not os.access(str(d), os.W_OK)
-
-    with monkeypatch.context() as mp:
-        mp.setattr(Path, "home", lambda: d)
-        mp.setenv(f"SXS{directory_type.upper()}DIR", str(d))
-        for dir_type in ["config", "cache"]:
-            mp.delenv(f'XDG_{dir_type.upper()}_HOME', raising=False)
-        sxs.utilities.sxs_directory.cache_clear()
-        with pytest.warns(UserWarning):
-            sxs_dir = sxs.utilities.sxs_directory(directory_type, persistent=True)
-        assert ".sxs" not in str(sxs_dir), (str(sxs_dir), str(d))
-        sxs_config_dir = sxs.utilities.sxs_directory("config", persistent=True)
-        assert str(sxs_config_dir) in str(sxs_dir)
-
-    d.chmod(0o777)
-    time.sleep(0.1)
+    try:
+        d.mkdir(mode=0o000)
+        assert d.exists()
+        assert d.is_dir()
+        assert stat.filemode(d.stat().st_mode) == "d---------"
+        assert not os.access(str(d), os.W_OK)
+
+        with monkeypatch.context() as mp:
+            mp.setattr(Path, "home", lambda: d)
+            mp.setenv(f"SXS{directory_type.upper()}DIR", str(d))
+            for dir_type in ["config", "cache"]:
+                mp.delenv(f'XDG_{dir_type.upper()}_HOME', raising=False)
+            sxs.utilities.sxs_directory.cache_clear()
+            with pytest.warns(UserWarning):
+                sxs_dir = sxs.utilities.sxs_directory(directory_type, persistent=True)
+            assert ".sxs" not in str(sxs_dir), (str(sxs_dir), str(d))
+            sxs_config_dir = sxs.utilities.sxs_directory("config", persistent=True)
+            assert str(sxs_config_dir) in str(sxs_dir)
+
+        d.chmod(0o777)
+        time.sleep(0.1)
+    finally:
+        # Remove the subdirectory manually, because forking scares the file system
+        shutil.rmtree(str(d))
 
 
 def test_read_write_config(tmp_path, monkeypatch):

sxs-2025.0.13/sxs/__version__.py

@@ -1 +0,0 @@
-__version__ = "2025.0.13"