sdf-xarray 0.5.0__tar.gz → 0.6.0__tar.gz

{sdf_xarray-0.5.0 → sdf_xarray-0.6.0}/CITATION.cff

@@ -24,5 +24,9 @@ authors:
     given-names: Liam
     orcid: 'https://orcid.org/0000-0001-8604-6904'
     affiliation: University of York
+  - family-names: Shekhanov
+    given-names: Sviatoslav
+    orcid: 'https://orcid.org/0000-0002-2125-8962'
+    affiliation: University of York
 doi: 10.5281/zenodo.15351323
 date-released: '2024-07-25'

{sdf_xarray-0.5.0 → sdf_xarray-0.6.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: sdf-xarray
-Version: 0.5.0
+Version: 0.6.0
 Summary: Provides a backend for xarray to read SDF files as created by the EPOCH plasma PIC code.
-Author-Email: Peter Hill <peter.hill@york.ac.uk>, Joel Adams <joel.adams@york.ac.uk>, Shaun Doherty <shaun.doherty@york.ac.uk>, Chris Herdman <chris.herdman@york.ac.uk>, Liam Pattinson <liam.pattinson@york.ac.uk>
+Author-Email: Peter Hill <peter.hill@york.ac.uk>, Joel Adams <joel.adams@york.ac.uk>, Shaun Doherty <shaun.doherty@york.ac.uk>, Chris Herdman <chris.herdman@york.ac.uk>, Liam Pattinson <liam.pattinson@york.ac.uk>, Sviatoslav Shekhanov <sviatoslav.shekhanov@york.ac.uk>
 License-Expression: BSD-3-Clause
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
@@ -18,6 +18,7 @@ Requires-Python: <3.15,>=3.11
 Requires-Dist: numpy>=2.0.0
 Requires-Dist: xarray>=2024.1.0
 Requires-Dist: dask>=2024.7.1
+Requires-Dist: epydeck~=1.0
 Provides-Extra: jupyter
 Requires-Dist: dask[diagnostics]; extra == "jupyter"
 Requires-Dist: ipykernel>=6.29.5; extra == "jupyter"

sdf_xarray-0.6.0/docs/_static/jupyter_padding.css

@@ -0,0 +1,3 @@
+.cell_output {
+    margin-bottom: 0.5em;
+}

{sdf_xarray-0.5.0 → sdf_xarray-0.6.0}/docs/animation.rst

@@ -125,7 +125,7 @@ the animation.
 
 .. jupyter-execute::
    
-   ds = xr.open_dataset("tutorial_dataset_3d/0005.sdf")
+   ds = sdfxr.open_dataset("tutorial_dataset_3d/0005.sdf")
    da = ds["Derived_Number_Density"]
    anim = da.epoch.animate(t = "X_Grid_mid")
    anim.show()

{sdf_xarray-0.5.0 → sdf_xarray-0.6.0}/docs/conf.py

@@ -50,6 +50,7 @@ extensions = [
     "myst_parser",
     "jupyter_sphinx",
     "sphinx_copybutton",
+    "sphinx_togglebutton",
 ]
 
 autosummary_generate = True
@@ -102,9 +103,7 @@ html_theme = "sphinx_book_theme"
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-html_css_files = [
-    "force_render_dark_xarray_objects.css",
-]
+html_css_files = ["force_render_dark_xarray_objects.css", "jupyter_padding.css"]
 
 html_theme_options = {
     "repository_url": "https://github.com/epochpic/sdf-xarray",

sdf_xarray-0.6.0/docs/getting_started.rst

@@ -0,0 +1,75 @@
+.. _sec-getting-started:
+
+=================
+ Getting Started
+=================
+
+Installation
+------------
+
+.. |python_versions_pypi| image:: https://img.shields.io/pypi/pyversions/sdf-xarray.svg
+   :alt: Supported Python versions
+   :target: https://pypi.org/project/sdf-xarray/
+
+.. important::
+
+   To install this package, ensure that you are using one of the supported Python
+   versions |python_versions_pypi|
+
+Install sdf-xarray from PyPI with:
+
+.. code-block:: bash
+
+    pip install sdf-xarray
+
+or download this code locally:
+
+.. code-block:: bash
+
+    git clone --recursive https://github.com/epochpic/sdf-xarray.git
+    cd sdf-xarray
+    pip install .
+
+
+Interaction
+-----------
+
+There are two main ways to load EPOCH SDF files into xarray objects: using the dedicated
+`sdf_xarray` functions or using the standard `xarray` interface with our custom engine.
+For examples of how to use these functions see :ref:`loading-sdf-files`.
+
+All code examples throughout this documentation are visualised using Jupyter notebooks
+so that you can interactively explore the datasets. To do this on your machine make
+sure that you have the necessary dependencies installed: 
+
+.. code-block:: bash
+
+    pip install "sdf-xarray[jupyter]"
+
+.. important::
+   
+   When loading SDF files, variables related to ``boundaries``, ``cpu`` and ``output file``
+   are excluded as they are problematic. If you wish to load these variables in see
+   :ref:`loading-raw-files`.
+
+
+Using sdf_xarray (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These functions are wrappers designed specifically for SDF data, providing the most
+straightforward experience:
+
+- **Single files**: Use `sdf_xarray.open_dataset` or `sdf_xarray.open_datatree`
+- **Multiple files**: Use `sdf_xarray.open_mfdataset` or `sdf_xarray.open_mfdatatree`
+- **Raw files**: use `sdf_xarray.sdf_interface.SDFFile`
+
+Using xarray
+~~~~~~~~~~~~
+
+If you prefer using the native `xarray` functions, you can use the `xarray.open_dataset`,
+`xarray.open_datatree` and `xarray.open_mfdataset`. Strangely there is no function in
+`xarray` for ``xarray.open_mfdatatree``.
+
+These functions should all work out of the box as long as `sdf_xarray` is installed on your
+system, if you are having issues with it reading files, you might need to pass the parameter
+``engine=sdf_engine`` when calling any of the above xarray functions.

{sdf_xarray-0.5.0 → sdf_xarray-0.6.0}/docs/key_functionality.rst

@@ -11,37 +11,19 @@ Key Functionality
    import matplotlib.pyplot as plt
    %matplotlib inline
 
+.. _loading-sdf-files:
+
 Loading SDF files
 -----------------
-There are several ways to load SDF files:
-
-- To load a single file, use `xarray.open_dataset`, `sdf_xarray.open_datatree` or `xarray.open_datatree`
-- To load multiple files, use `sdf_xarray.open_mfdataset`, `xarray.open_mfdataset` or `sdf_xarray.open_mfdatatree`.
-- To access the raw contents of a single SDF file, use `sdf_xarray.sdf_interface.SDFFile`.
-
-.. note::
-
-   When loading SDF files, variables related to ``boundaries``, ``cpu`` and ``output file`` are excluded as they are problematic. If you wish to load these in please use the
-   :ref:`loading-raw-files` approach.
-
-.. tip::
-
-    All code examples throughout this documentation are visualised using Jupyter notebooks
-    so that you can interactively explore `xarray.Dataset` objects. To do this on your machine
-    make sure that you have the necessary dependencies installed: 
-
-    .. code-block:: bash
-
-        pip install "sdf-xarray[jupyter]"
 
 Loading single files
 ~~~~~~~~~~~~~~~~~~~~
 
 .. jupyter-execute::
 
-   xr.open_dataset("tutorial_dataset_1d/0010.sdf")
+   sdfxr.open_dataset("tutorial_dataset_1d/0010.sdf")
 
-Alternatively, you can load the data in as a `xarray.DataTree`, which organises the data
+You can also load the data in as a `xarray.DataTree`, which organises the data
 hierarchically into ``groups`` (for example grouping related quantities such as the individual
 components of the electric and magnetic fields) while keeping each item as a `xarray.Dataset`.
 
@@ -72,22 +54,14 @@ is by using the `sdf_xarray.open_mfdataset`.
 
    If your simulation includes multiple ``output`` blocks that specify different variables
    for output at various time steps, variables not present at a specific step will default
-   to a nan value. To clean your dataset by removing these nan values we suggest using the
-   `xarray.DataArray.dropna` function or :ref:`loading-sparse-data`.
+   to a nan value. To remove these nan values we suggest using the `xarray.DataArray.dropna`
+   function or following our implmentation in :ref:`loading-sparse-data`.
 
 .. jupyter-execute::
 
    sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
 
-Alternatively, you can load the data in as a `xarray.DataTree`, which organises the data
-hierarchically into ``groups`` (for example grouping related quantities such as the individual
-components of the electric and magnetic fields) while keeping each item as a `xarray.Dataset`.
-
-.. jupyter-execute::
-
-   sdfxr.open_mfdatatree("tutorial_dataset_1d/*.sdf")
-
-Alternatively files can be loaded using `xarray.open_mfdataset` however when loading in
+Alternatively, files can be loaded using `xarray.open_mfdataset` however when loading in
 all the files we have do some processing of the data so that we can correctly align it along
 the time dimension; This is done via the ``preprocess`` parameter utilising the
 `sdf_xarray.SDFPreprocess` function.
@@ -101,6 +75,14 @@ the time dimension; This is done via the ``preprocess`` parameter utilising the
       preprocess=sdfxr.SDFPreprocess()
    )
 
+You can also load the data in as a `xarray.DataTree`, which organises the data
+hierarchically into ``groups`` (for example grouping related quantities such as the individual
+components of the electric and magnetic fields) while keeping each item as a `xarray.Dataset`.
+
+.. jupyter-execute::
+
+   sdfxr.open_mfdatatree("tutorial_dataset_1d/*.sdf")
+
 .. _loading-sparse-data:
 
 Loading sparse data
@@ -142,7 +124,7 @@ multiple files).
 
 .. jupyter-execute::
 
-   xr.open_dataset("tutorial_dataset_1d/0010.sdf", keep_particles=True)
+   sdfxr.open_dataset("tutorial_dataset_1d/0010.sdf", keep_particles=True)
 
 Loading specific variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -161,6 +143,47 @@ consumption.
 
    sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf", data_vars=["Electric_Field_Ex"])
 
+.. _loading-input-deck:
+
+Loading the input.deck
+~~~~~~~~~~~~~~~~~~~~~~
+
+When loading SDF files, `sdf_xarray` will attempt to automatically load
+the ``input.deck`` file used to initialise the simulation from the same
+directory as the SDF file. If the file is not found, it will silently fail
+and continue loading the SDF file as normal. This file contains the initial
+simulation setup information which is not present in SDF outputs. By loading
+this file, you can access these parameters as part of your dataset's metadata.
+To do this, use the ``deck_path`` parameter when loading an SDF file with
+`sdf_xarray.open_dataset`, `xarray.open_dataset`, `sdf_xarray.open_datatree`,
+`xarray.open_datatree`, `sdf_xarray.open_mfdataset` or `sdf_xarray.open_mfdatatree`.
+
+There are a few ways you can load an input deck:
+
+- **Default behaviour**: The input deck is loaded from the same directory
+  as the SDF file if it exists. If it does not exist, it will silently fail.
+- **Relative path**: (e.g. ``"template.deck"``) Searches for that specific filename
+  within the same directory as the SDF file.
+- **Absolute path**: (e.g. ``"/path/to/input.deck"``) Uses the full, specified path
+  to locate the file.
+
+An example of loading a deck can be seen below
+
+.. toggle::
+
+   .. jupyter-execute::
+
+      import json
+      from IPython.display import Code
+
+      ds = xr.open_dataset("tutorial_dataset_1d/0010.sdf")
+      # The results are accessible by calling 
+      deck = ds.attrs["deck"]
+
+      # Some prettification to make it looks nice in jupyter notebooks
+      json_str = json.dumps(deck, indent=4)
+      Code(json_str, language='json')
+
 Data interaction examples
 -------------------------
 

{sdf_xarray-0.5.0 → sdf_xarray-0.6.0}/docs/unit_conversion.rst

@@ -15,9 +15,10 @@ to femto-seconds or particle energy from Joules to electron-volts.
 
 .. jupyter-execute::
 
-    from sdf_xarray import open_mfdataset
+    import sdf_xarray as sdfxr
     import matplotlib.pyplot as plt
     %matplotlib inline
+
     plt.rcParams.update({
         "axes.labelsize": 16,
         "xtick.labelsize": 14,
@@ -45,7 +46,7 @@ We can use the |rescale_coords_accessor| method to convert X, Y, and Z coordinat
 
     fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(16, 6))
 
-    ds = open_mfdataset("tutorial_dataset_2d/*.sdf")
+    ds = sdfxr.open_mfdataset("tutorial_dataset_2d/*.sdf")
     ds_in_microns = ds.epoch.rescale_coords(1e6, "µm", ["X_Grid_mid", "Y_Grid_mid"])
 
     ds["Derived_Number_Density_Electron"].isel(time=0).plot(ax=ax1, x="X_Grid_mid", y="Y_Grid_mid")
@@ -65,7 +66,7 @@ seconds (``s``) to femto-seconds (``fs``) by applying a multiplier of ``1e15``.
 
 .. jupyter-execute::
     
-    ds = open_mfdataset("tutorial_dataset_2d/*.sdf")
+    ds = sdfxr.open_mfdataset("tutorial_dataset_2d/*.sdf")
     ds["time"]
 
 .. jupyter-execute::
@@ -97,15 +98,13 @@ Installation
 
 To install the pint libraries you can simply run the following optional
 dependency pip command which will install both the ``pint`` and ``pint-xarray``
-libraries. You can install these optional dependencies via pip:
+libraries. Once installed the ``xarray.Dataset.pint`` accessor should become
+accessible. You can install these optional dependencies via pip:
 
 .. code:: console
 
     $ pip install "sdf_xarray[pint]"
 
-.. note::
-    Once you install ``pint-xarray`` it is automatically picked up and loaded
-    by the code so you should have access to the ``xarray.Dataset.pint`` accessor.
 
 Quantifying DataArrays
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -117,7 +116,7 @@ Joules and convert it to electron volts.
 
 .. jupyter-execute::
 
-    ds = open_mfdataset("tutorial_dataset_1d/*.sdf")
+    ds = sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
     ds["Total_Particle_Energy_Electron"]
 
 Once you call `xarray.DataArray.pint.quantify` the type is inferred the original

{sdf_xarray-0.5.0 → sdf_xarray-0.6.0}/pyproject.toml

@@ -18,9 +18,15 @@ authors = [
   { name = "Shaun Doherty", email = "shaun.doherty@york.ac.uk" },
   { name = "Chris Herdman", email = "chris.herdman@york.ac.uk" },
   { name = "Liam Pattinson", email = "liam.pattinson@york.ac.uk" },
+  { name = "Sviatoslav Shekhanov", email = "sviatoslav.shekhanov@york.ac.uk" },
 ]
 requires-python = ">=3.11,<3.15"
-dependencies = ["numpy>=2.0.0", "xarray>=2024.1.0", "dask>=2024.7.1"]
+dependencies = [
+  "numpy>=2.0.0",
+  "xarray>=2024.1.0",
+  "dask>=2024.7.1",
+  "epydeck~=1.0"
+]
 description = "Provides a backend for xarray to read SDF files as created by the EPOCH plasma PIC code."
 classifiers = [
   "Development Status :: 5 - Production/Stable",
@@ -49,6 +55,7 @@ dev = [
 docs = [
   "sphinx>=5.3",
   "sphinx_autodoc_typehints>=1.19",
+  "sphinx-togglebutton",
   "sphinx-book-theme>=0.4.0rc1",
   "sphinx-argparse-cli>=1.10.0",
   "sphinx-inline-tabs",