sxs 2025.0.12__py3-none-any.whl → 2025.0.13__py3-none-any.whl

sxs/__init__.py

@@ -20,6 +20,7 @@ from .utilities import (
     sxs_id, lev_number, sxs_id_to_url,
     jit, vectorize, guvectorize, version_info
 )
+from .citation import cite
 from .time_series import TimeSeries
 from .metadata import Metadata
 from .catalog import Catalog

sxs/__version__.py

@@ -1 +1 @@
-__version__ = "2025.0.12"
+__version__ = "2025.0.13"

sxs/citation.py

@@ -0,0 +1,205 @@
+def cite(*sxs_ids, bibtex=True):
+    """Cite this package and/or data
+
+    Prints out a citation for the package, the most recent paper
+    describing the catalog, the catalog data itself, and optionally
+    individual simulations.
+
+    Note that this function makes web requests to obtain the DOIs and
+    corresponding BibTeX entries.
+
+    If you want to cite a specific version of the SXS catalog data, be
+    sure to load it with `sxs.load("dataframe", tag="v3.0.0")` or
+    similar *before* calling this function.  Otherwise, the most recent
+    version will be used.
+    
+    Parameters
+    ----------
+    sxs_ids : str
+        Any number of SXS IDs to include in the citation.
+    bibtex : bool, optional
+        If True — the default — returns full BibTeX entries.
+        Otherwise, just returns a list of DOIs to cite.
+    
+    Returns
+    -------
+    str or list[str]
+        A string containing BibTeX entries, or a list of DOI strings.
+    
+    """
+    from . import doi_prefix, load, __version__
+    from . import sxs_id as sxs_identifier
+
+    simulations = load("simulations")
+
+    # Get the DOI for this version of this package
+    package_version = f"v{__version__}"
+    package_doi = get_zenodo_doi("The sxs package", package_version)
+
+    # Get the DOI for the paper
+    paper_doi = f"{doi_prefix}/SXSCatalog3"
+
+    # Get the DOI for this version of the catalog
+    catalog_tag = getattr(simulations, "tag", "v3.0.0")
+    catalog_doi = get_zenodo_doi(
+        "The SXS catalog of simulations",
+        catalog_tag
+    )
+
+    sxs_id_references = {
+        doi
+        for sxs_id in sxs_ids
+        for doi in simulations[sxs_identifier(sxs_id)].get("citation_dois", [])
+        if doi.startswith("10.")
+    } - {package_doi, paper_doi, catalog_doi}
+
+    if bibtex:
+        package_bibtex = doi2bibtex(package_doi, key=f"SXSPackage_{package_version}")
+        paper_bibtex = doi2bibtex(paper_doi, key="SXSCatalogPaper_3")
+        catalog_bibtex = doi2bibtex(
+            catalog_doi,
+            key=f"SXSCatalogData_{catalog_tag[1:]}",
+            title_suffix=f" {catalog_tag}"
+        )
+        sxs_id_references_bibtex = [
+            doi2bibtex(doi) for doi in sxs_id_references
+        ]
+        sxs_id_bibtex = [
+            doi2bibtex(f"{doi_prefix}/{sxs_id}", key=sxs_id)
+            for sxs_id in sxs_ids
+        ]
+        return "\n".join(
+            [package_bibtex, paper_bibtex, catalog_bibtex]
+            + sxs_id_references_bibtex
+            + sxs_id_bibtex
+        )
+    else:
+        sxs_id_references_dois = list(sxs_id_references)
+        sxs_id_dois = [f"{doi_prefix}/{sxs_id}" for sxs_id in sxs_ids]
+        return [package_doi, paper_doi, catalog_doi] + sxs_id_references_dois + sxs_id_dois
+
+
+def doi2bibtex(doi, key="", title_suffix=""):
+    """Convert a DOI to a BibTeX entry
+
+    This function queries doi.org — and possibly the service it
+    redirects to — for the BibTeX entry corresponding to the DOI.
+
+    Note that there are some services that do not provide good BibTeX.
+    In particular, MNRAS does not support this service very well.
+
+    Parameters
+    ----------
+    doi : str
+        The DOI to convert.
+    key : str, optional
+        The BibTeX key to use.  If not provided, the key will be
+        generated from the DOI.  If multiple entries are found, this
+        function will raise an exception.
+    
+    Returns
+    -------
+    str
+        The BibTeX entry as a string.
+    
+    """
+    import requests
+    import bibtexparser
+    from .utilities import sxs_identifier_re
+
+    url = f"https://doi.org/{doi}"
+    headers = {"Accept": "application/x-bibtex"}
+    response = requests.get(url, headers=headers)
+    response.raise_for_status()
+    bibtex = response.text
+
+    bibtex_format = bibtexparser.BibtexFormat()
+    bibtex_format.indent = "  "
+    bibtex_format.block_separator = "\n"
+
+    try:
+        library = bibtexparser.parse_string(bibtex)
+
+        for i,entry in enumerate(library.entries):
+            # Replace the key, if requested
+            if key:
+                if i>1:
+                    raise Exception("Multiple entries found in BibTeX, but one key was given.")
+                entry.key = key
+
+            # Ensure that the "author" field does not end in ","
+            if (author := entry.fields_dict.get("author", "")):
+                if author.value.rstrip().endswith(","):
+                    author.value = author.value.rstrip()[:-1]
+                if author.value == "SXS Collaboration":
+                    author.value = "{SXS Collaboration}"
+                entry.set_field(author)
+
+            # Now, look for an SXS ID in the `title` field; if present
+            # surround it with curly braces to prevent BibTeX from
+            # downcasing it.
+            title = entry.fields_dict.get("title", "")
+            if (m:=sxs_identifier_re.search(title.value)):
+                # Surround the SXS ID with curly braces
+                replacement = f"{{{m.group('sxs_identifier')}}}"
+
+                # The title will not (currently) include the version,
+                # but if the requested DOI contains a *versioned* SXS
+                # ID, we add the version (e.g., "v3.0") to the
+                # replacement string
+                if (
+                    (match:=sxs_identifier_re.search(doi))
+                    and match.group("sxs_identifier") == m.group("sxs_identifier")
+                    and match.group("version")
+                ):
+                    replacement += "v" + match.group("version")
+
+                title.value = title.value.replace(m.group("sxs_identifier"), replacement)
+                entry.set_field(title)
+            elif title_suffix:
+                title.value += title_suffix
+                entry.set_field(title)
+
+        bibtex = bibtexparser.write_string(library, bibtex_format=bibtex_format)
+
+    except Exception as e:
+        print("Failed to replace key and/or escape titles in BibTeX entry:\n")
+        for line in bibtex.split("\n"):
+            print("    " + line)
+        print("")
+        raise
+
+    return bibtex
+
+
+def get_zenodo_doi(title, version):
+    import requests
+
+    params = {
+        "q": f'metadata.title:"{title}" AND metadata.version:"{version}"',
+        "size": 1,
+        "page": 1,
+        "sort": "mostrecent",
+        "all_versions": "",  # Need to include this to get older versions
+    }
+    url = "https://zenodo.org/api/records"
+    r = requests.get(url, params=params)
+
+    if r.status_code != 200:
+        print(f"An unknown error occurred when trying to access '{url}'.")
+        print(f"The search parameters were '{params}'")
+        try:
+            print(r.json())
+        except:
+            pass
+        r.raise_for_status()
+        raise RuntimeError()  # Will only happen if the response was not strictly an error
+
+    json = r.json()
+
+    if json.get("hits", {}).get("total", 0) == 0:
+        print(f"No results found for '{title}' version '{version}'.")
+        return None
+    else:
+        hit = json["hits"]["hits"][0]
+        return hit["doi"]

sxs/simulations/simulation.py

@@ -45,10 +45,10 @@ def Simulation(location, *args, **kwargs):
     the version number must be in the form "v2.0", not "2.0", and it
     must exist, or no files will be found to load the data from.
 
-    The returned object will be either a `Simulation_v1` or
-    `Simulation_v2` object, depending on the version number.
-    Hopefully, most details of the two versions will be hidden from
-    the user, so that the interface is identical.
+    The returned object will be either a `Simulation_v1`,
+    `Simulation_v2`, or `Simulation_v3` object, depending on the
+    version number.  Hopefully, most details of the two versions will
+    be hidden from the user, so that the interface is identical.
 
     Note that some simulations are deprecated and/or superseded by
     other simulations.  By default, this function will raise an error
@@ -119,13 +119,13 @@ def Simulation(location, *args, **kwargs):
     Returns
     -------
     simulation : SimulationBase
-        A `Simulation_v1` or `Simulation_v2` object, depending on the
-        version of the simulation data.
+        A `Simulation_v1`, `Simulation_v2`, or `Simulation_v3` object,
+        depending on the version of the simulation data.
 
     Note that all remaining arguments (including keyword arguments)
-    are passed on to the `SimulationBase`, `Simulation_v1`, and/or
-    `Simulation_v2` constructors, though none currently recognize any
-    arguments other than those listed above.
+    are passed on to the `SimulationBase`, `Simulation_v1`,
+    `Simulation_v2`, and/or `Simulation_v3` constructors, though none
+    currently recognize any arguments other than those listed above.
     
     """
     import numpy as np
@@ -938,6 +938,13 @@ class Simulation_v2(SimulationBase):
 
 
 class Simulation_v3(Simulation_v2):
+    """Simulation object for version 3 of the data format
+        
+    Note that users almost certainly never need to call this function;
+    see the `Simulation` function or `sxs.load` function instead.  See
+    also `SimulationBase` for the base class that this class inherits
+    from.
+    """
     # Default extrapolation order for this simulation version
     default_extrapolation = "N2"
 

sxs/zenodo/api/login.py

@@ -237,7 +237,7 @@ class Login(object):
         -------------------
         q: string [optional]
             Search query, using Elasticsearch query string syntax.  See
-            https://help.zenodo.org/guides/search/ for details.
+            https://help.zenodo.org/help/search/ for details.
         status: string, either 'draft' or 'published' [optional]
             Filter result based on deposit status.
         sort: string [optional]

{sxs-2025.0.12.dist-info → sxs-2025.0.13.dist-info}/METADATA

@@ -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.12.dist-info → sxs-2025.0.13.dist-info}/RECORD

@@ -1,5 +1,6 @@
-sxs/__init__.py,sha256=8PntABL6yx7Ad70hP7WedNAVDTZiwm_2At5xIQGo4k8,2610
-sxs/__version__.py,sha256=Tem3fdqMzEHLi16ZN24N3JI_RtXclnvUn9fGXGVo-uc,26
+sxs/__init__.py,sha256=C8VhmrUPAa70Y-C2KfZv9BhS6ef-eB7uaNtwm18IRhk,2637
+sxs/__version__.py,sha256=qT5_mCWSL-clhzUVFYLfMLmGxxmlJqEydwiwpos4nFw,26
+sxs/citation.py,sha256=hPns9t996GeKJe2HviUs00hM3fJb7JQu_f54XOPV3BE,7061
 sxs/handlers.py,sha256=jVV-HK-omzoBx5N2wcpLHvyoWq86hUfWCjnGbPpD91I,18343
 sxs/juliapkg.json,sha256=-baaa3Za_KBmmiGjlh2YYLWmvUvZl6GaKKXwNI4S7qU,178
 sxs/time_series.py,sha256=OKaLg8tFyrtKcef7900ri-a0C6A8wKxA68KovZXvH6I,41081
@@ -18,7 +19,7 @@ sxs/metadata/metric.py,sha256=Tsig1Jm50OO8r89zfjCuQ4i3JAoiazSb4J9qYtPWKgM,41
 sxs/simulations/__init__.py,sha256=eXkheYhRaYyKjul5J1IXpoJ7Wq4nr3Tgwr-HSS3BTek,156
 sxs/simulations/analyze.py,sha256=YwX0i_GRATRpvp7T8VheShkclvqYsraGDDKEkJQxJnw,11530
 sxs/simulations/local.py,sha256=e77SeaWMl2PWX_EndQtShOXZxcFKhQsUDQ55R2Njcuc,43
-sxs/simulations/simulation.py,sha256=STrVSpxR0m6lntjt2jNGOVltBYXiJzrKL7OGWDL7RRY,43322
+sxs/simulations/simulation.py,sha256=vTqroGL4QVOl0wFcOve69ScSNRJn4bWAuJtA_hg1PAw,43673
 sxs/simulations/simulations.py,sha256=sMle89VoD1CQni1N23Vjo3h2yj9LHHAtuaB_qfD3Wgg,109
 sxs/utilities/__init__.py,sha256=WSStlqljfgQheMxHGfuofSc5LdmASGvO3FNO3f_zaT0,4806
 sxs/utilities/bitwise.py,sha256=G9ZNYgwDQRhq5wbDf-p2HcUqkEP_IRDiQoXW4KyU17k,13205
@@ -80,9 +81,9 @@ sxs/zenodo/simannex.py,sha256=t-j_xChmND7vXnGu4rWyW6pa-5aZ31iokZOUaobzgak,4491
 sxs/zenodo/surrogatemodeling.py,sha256=NTJXrnyXdrbX4KsoYP2obxVy-lakXtD7LqOEB4jQ_MI,8381
 sxs/zenodo/api/__init__.py,sha256=EM_eh4Q8R5E0vIfMhyIR1IYFfOBu6vA0UTasgX9gHys,217
 sxs/zenodo/api/deposit.py,sha256=J4RGvGjh0cEOrN4bBZWEDcPAhNscqB2fzLlvRZ5HTHM,36948
-sxs/zenodo/api/login.py,sha256=Yz0ytgi81_5BpDzhrS0WPMXlvU2qUaCK8yn8zxfEbko,18007
+sxs/zenodo/api/login.py,sha256=hXyxLrx1PALaEEH76XrBvlO5Wwz-qa-MCjkI8UyB3t0,18005
 sxs/zenodo/api/records.py,sha256=nKkhoHZ95CTztHF9Zzaug5p7IiUCJG4Em1i-l-WqH6U,3689
-sxs-2025.0.12.dist-info/METADATA,sha256=vujhXdWS293esEV1g4q4_YeQsD2uI4_bsxe4c92uZkY,9312
-sxs-2025.0.12.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sxs-2025.0.12.dist-info/licenses/LICENSE,sha256=ptVOd5m7LDM5ZF0x32cxb8c2Nd5NDmAhy6DX7xt_7VA,1080
-sxs-2025.0.12.dist-info/RECORD,,
+sxs-2025.0.13.dist-info/METADATA,sha256=kiyO3KLqzK_lqQe3cIMsMunkIUv6dqeuTHUgWJzbwck,11644
+sxs-2025.0.13.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sxs-2025.0.13.dist-info/licenses/LICENSE,sha256=ptVOd5m7LDM5ZF0x32cxb8c2Nd5NDmAhy6DX7xt_7VA,1080
+sxs-2025.0.13.dist-info/RECORD,,