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

{sdf_xarray-0.4.0 → sdf_xarray-0.5.0}/.github/workflows/build_publish.yml

@@ -19,6 +19,13 @@ jobs:
         fetch-depth: 0
         submodules: "recursive"
 
+    - name: Cache Zenodo datasets
+      uses: actions/cache@v4
+      with:
+        enableCrossOsArchive: true
+        path: ~/.cache/sdf_datasets
+        key: sdf-datasets-17991042
+
     - name: Setup uv
       id: setup-uv
       uses: astral-sh/setup-uv@v3

sdf_xarray-0.5.0/.github/workflows/lint.yml

@@ -0,0 +1,30 @@
+name: lint
+
+on:
+  push:
+    paths:
+      - '**.py'
+  pull_request:
+    paths:
+      - '**.py'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # Providing 'args' prevents the action from running 'ruff check .'
+      # immediately after installing ruff.
+      - name: Install Ruff
+        uses: astral-sh/ruff-action@v3
+        with:
+          args: "--version"
+
+      - name: Check
+        run: ruff check --output-format=github src tests
+
+      - name: Format
+        run: ruff format --check --diff src tests

{sdf_xarray-0.4.0 → sdf_xarray-0.5.0}/.github/workflows/tests.yml

@@ -8,7 +8,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v4
@@ -30,5 +30,11 @@ jobs:
         uv python install ${{ matrix.python-version }}
         uv sync --python ${{ matrix.python-version }} --frozen
 
+    - name: Cache Zenodo datasets
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/sdf_datasets
+        key: sdf-datasets-17991042
+
     - name: Test with pytest
       run: uv run pytest

{sdf_xarray-0.4.0 → sdf_xarray-0.5.0}/.gitignore

@@ -1,4 +1,6 @@
 # -*- mode: gitignore; -*-
+# https://github.com/github/gitignore/blob/main/Global/Emacs.gitignore
+# --------------------------------------------------------------------
 *~
 \#*\#
 /.emacs.desktop
@@ -47,6 +49,9 @@ flycheck_*.el
 # network security
 /network-security.data
 
+# https://github.com/github/gitignore/blob/main/Global/Linux.gitignore
+# --------------------------------------------------------------------
+
 *~
 
 # temporary files which can be created if a process still has a handle open of a deleted file
@@ -60,6 +65,10 @@ flycheck_*.el
 
 # .nfs files are created when an open file is removed but is still being accessed
 .nfs*
+
+# https://github.com/github/gitignore/blob/main/Python.gitignore
+# --------------------------------------------------------------
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -222,6 +231,37 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+.vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# https://github.com/github/gitignore/blob/main/CMake.gitignore
+# ------------------------------------------------------------
+
 CMakeLists.txt.user
 CMakeCache.txt
 CMakeFiles
@@ -233,6 +273,11 @@ install_manifest.txt
 compile_commands.json
 CTestTestfile.cmake
 _deps
+CMakeUserPresets.json
+
+# https://github.com/github/gitignore/blob/main/C.gitignore
+# ---------------------------------------------------------
+
 # Prerequisites
 *.d
 
@@ -286,6 +331,9 @@ Module.symvers
 Mkfile.old
 dkms.conf
 
+# sdf-xarray specific ignores
+# ---------------------------
+
 # Generated version file
 src/sdf_xarray/_version.py
 

{sdf_xarray-0.4.0 → sdf_xarray-0.5.0}/CONTRIBUTING.md

@@ -28,14 +28,8 @@ pip install .
 
 ### Style
 
-We follow [PEP 8](https://peps.python.org/pep-0008/) and use the
-following tools:
-
-- [ruff](https://github.com/astral-sh/ruff) for linting
-- [black](https://black.readthedocs.io/en/stable/) for formatting
-- [isort](https://pycqa.github.io/isort/) for sorting imports
-
-To run these tools locally, install the `lint` dependency group:
+We use [Ruff](https://docs.astral.sh/ruff/) to maintain code quality and
+formatting. This can be installed locally via the `lint` dependency group:
 
 ```bash
 pip install --group lint
@@ -53,6 +47,20 @@ Alternatively, `uv` users can do this in one step with `uv run`:
 uv run ruff check src tests
 ```
 
+Many of the issues raised by Ruff can be fixed automatically:
+
+```bash
+ruff check --fix src tests
+```
+
+Ruff may also be used to format the code to a style similar to that enforced by
+[Black](https://black.readthedocs.io/en/stable/), which (almost) matches the
+[PEP-8 standard](https://peps.python.org/pep-0008/):
+
+```bash
+ruff format src tests
+```
+
 ### Running and adding tests
 
 We use [pytest](https://docs.pytest.org/en/stable/) to run tests.
@@ -130,8 +138,8 @@ Then open http://localhost:8000 in your browser to view the documentation.
 
 All pull requests are automatically checked using GitHub Actions for:
 
-- Linting (`ruff`)
-- Formatting (`black` and `isort`)
+- Linting and formatting (`ruff`)
 - Testing (`pytest`)
+- Cross-platform building (`cibuildwheel`)
 
 These checks must pass before a pull request can be merged.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdf-xarray
-Version: 0.4.0
+Version: 0.5.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>
 License-Expression: BSD-3-Clause
@@ -10,12 +10,11 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Python: <3.15,>=3.10
+Requires-Python: <3.15,>=3.11
 Requires-Dist: numpy>=2.0.0
 Requires-Dist: xarray>=2024.1.0
 Requires-Dist: dask>=2024.7.1
@@ -35,7 +34,7 @@ Description-Content-Type: text/markdown
 ![Build/Publish](https://github.com/epochpic/sdf-xarray/actions/workflows/build_publish.yml/badge.svg)
 ![Tests](https://github.com/epochpic/sdf-xarray/actions/workflows/tests.yml/badge.svg)
 [![Read the Docs](https://img.shields.io/readthedocs/sdf-xarray?logo=readthedocs&link=https%3A%2F%2Fsdf-xarray.readthedocs.io%2F)](https://sdf-xarray.readthedocs.io)
-[![Formatted with black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
 
 sdf-xarray provides a backend for [xarray](https://xarray.dev) to read SDF files as created by
@@ -148,4 +147,4 @@ To run checks locally before opening a pull request, see [CONTRIBUTING.md](CONTR
 
 ![PlasmaFAIR logo](PlasmaFAIR.svg)
 
-Originally developed by [PlasmaFAIR](https://plasmafair.github.io), EPSRC Grant EP/V051822/1
+Originally developed by [PlasmaFAIR](https://plasmafair.github.io), EPSRC Grant EP/V051822/1

{sdf_xarray-0.4.0 → sdf_xarray-0.5.0}/README.md

@@ -6,7 +6,7 @@
 ![Build/Publish](https://github.com/epochpic/sdf-xarray/actions/workflows/build_publish.yml/badge.svg)
 ![Tests](https://github.com/epochpic/sdf-xarray/actions/workflows/tests.yml/badge.svg)
 [![Read the Docs](https://img.shields.io/readthedocs/sdf-xarray?logo=readthedocs&link=https%3A%2F%2Fsdf-xarray.readthedocs.io%2F)](https://sdf-xarray.readthedocs.io)
-[![Formatted with black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
 
 sdf-xarray provides a backend for [xarray](https://xarray.dev) to read SDF files as created by
@@ -119,4 +119,4 @@ To run checks locally before opening a pull request, see [CONTRIBUTING.md](CONTR
 
 ![PlasmaFAIR logo](PlasmaFAIR.svg)
 
-Originally developed by [PlasmaFAIR](https://plasmafair.github.io), EPSRC Grant EP/V051822/1
+Originally developed by [PlasmaFAIR](https://plasmafair.github.io), EPSRC Grant EP/V051822/1

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

@@ -3,6 +3,9 @@
 .. |animate_accessor| replace:: `xarray.DataArray.epoch.animate
    <sdf_xarray.plotting.animate>`
 
+.. |animate_multiple_accessor| replace:: `xarray.Dataset.epoch.animate_multiple
+   <sdf_xarray.plotting.animate_multiple>`
+
 ==========
 Animations
 ==========
@@ -131,10 +134,8 @@ Moving window
 -------------
 
 EPOCH allows for simulations that have a moving simulation window
-(changing x-axis over time). |animate_accessor| will
-automatically detect when a simulation has a moving window by searching 
-for NaNs in the `xarray.DataArray` and change the x-axis limits
-accordingly.
+(changing x-axis over time). |animate_accessor| can accept the boolean parameter
+``move_window`` and change the x-axis limits accordingly.
 
 .. warning::
    `sdf_xarray.open_mfdataset` does not currently function with moving window data.
@@ -152,7 +153,7 @@ accordingly.
       )
 
    da = ds["Derived_Number_Density_Beam_Electrons"]
-   anim = da.epoch.animate(fps = 5)
+   anim = da.epoch.animate(move_window=True, fps = 5)
    anim.show()
 
 .. warning::
@@ -191,73 +192,70 @@ before plotting as in :ref:`sec-unit-conversion`. Some functionality such as
       )
    anim.show()
 
-Advanced usage
---------------
+Combining multiple animations
+-----------------------------
 
-Multiple plots on the same axes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+|animate_multiple_accessor| creates a `matplotlib.animation.FuncAnimation`
+that contains multiple plots layered on top of each other.
+
+1D simulation
+~~~~~~~~~~~~~
 
 What follows is an example of how to combine multiple animations on the
-same axis. This may be implemented in a more user-friendly function in
-a future update.
+same axis.
 
 .. jupyter-execute::
 
-   # Open the SDF files
    ds = sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
 
-   # Create figure and axes
-   fig, ax = plt.subplots()
-   plt.close(fig)
-
-   # Generate the animations independently
-   anim_1 = ds["Derived_Number_Density_Electron"].epoch.animate()
-   anim_2 = ds["Derived_Number_Density_Ion"].epoch.animate()
-
-   # Extract the update functions from the animations
-   update_1 = anim_1._func
-   update_2 = anim_2._func
-
-   # Create axes details for new animation
-   x_min, x_max = update_1(0)[0].axes.get_xlim()
-   y_min_1, y_max_1 = update_1(0)[0].axes.get_ylim()
-   y_min_2, y_max_2 = update_2(0)[0].axes.get_ylim()
-   y_min = min(y_min_1, y_min_2)
-   y_max = max(y_max_1, y_max_2)
-   x_label = update_1(0)[0].axes.get_xlabel()
-   y_label = "Number Density [m$^{-3}$]"
-   label_1 = "Electron"
-   label_2 = "Ion"
-
-   # Create new update function
-   def update_combined(frame):
-      anim_1_fig = update_1(frame)[0]
-      anim_2_fig = update_2(frame)[0]
-
-      title = anim_1_fig.axes.title._text
-
-      ax.clear()
-      plot = ax.plot(anim_1_fig._x, anim_1_fig._y, label = label_1)
-      ax.plot(anim_2_fig._x, anim_2_fig._y, label = label_2)
-      ax.set_title(title)
-      ax.set_xlim(x_min, x_max)
-      ax.set_ylim(y_min, y_max)
-      ax.set_xlabel(x_label)
-      ax.set_ylabel(y_label)
-      ax.legend(loc = "upper left")
-      return plot
-
-   N_frames = anim_1._save_count
-   interval = anim_1._interval
-
-   # Create combined animation
-   anim_combined = FuncAnimation(
-      fig,
-      update_combined,
-      frames=range(N_frames),
-      interval = interval,
-      repeat=True,
-      )
+   anim = ds.epoch.animate_multiple(
+      ds["Derived_Number_Density_Electron"],
+      ds["Derived_Number_Density_Ion"],
+      datasets_kwargs=[{"label": "Electron"}, {"label": "Ion"}],
+      ylim=(0e27,4e27),
+      ylabel="Derived Number Density [1/m$^3$]"
+   )
 
-   # Display animation as jshtml
-   HTML(anim_combined.to_jshtml())
+   anim.show()
+
+2D simulation
+~~~~~~~~~~~~~
+
+.. tip::
+   To correctly display 2D data on top of one another you need to specify
+   the ``alpha`` value which sets the opacity of the plot.
+
+This also works with 2 dimensional data.
+
+.. jupyter-execute::
+   
+   import numpy as np
+   from matplotlib.colors import LogNorm
+
+   ds = sdfxr.open_mfdataset("tutorial_dataset_2d/*.sdf")
+
+   flux_magnitude = np.sqrt(
+      ds["Derived_Poynting_Flux_x"]**2 +
+      ds["Derived_Poynting_Flux_y"]**2 +
+      ds["Derived_Poynting_Flux_z"]**2
+   )
+   flux_magnitude.attrs["long_name"] = "Poynting Flux Magnitude"
+   flux_magnitude.attrs["units"] = "W/m$^2$"
+
+   # Cut-off low energy values so that they will be rendered as transparent
+   # in the plot as they've been set to NaN
+   flux_masked = flux_magnitude.where(flux_magnitude > 0.2e23)
+   flux_norm = LogNorm(
+      vmin=float(flux_masked.min()),
+      vmax=float(flux_masked.max())
+   )
+
+   anim = ds.epoch.animate_multiple(
+      ds["Derived_Number_Density_Electron"],
+      flux_masked,
+      datasets_kwargs=[
+         {"alpha": 1.0},
+         {"cmap": "hot", "norm": flux_norm, "alpha": 0.9},
+      ],
+   )
+   anim.show()

{sdf_xarray-0.4.0 → sdf_xarray-0.5.0}/docs/getting_started.rst

@@ -64,6 +64,16 @@ Loading single files
 
     xr.open_dataset("tutorial_dataset_1d/0010.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::
+
+    import sdf_xarray as sdfxr
+
+    sdfxr.open_datatree("tutorial_dataset_1d/0010.sdf")
+
 Loading multiple files
 ----------------------
 
@@ -73,6 +83,16 @@ Loading multiple files
 
     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::
+
+    import sdf_xarray as sdfxr
+
+    sdfxr.open_mfdatatree("tutorial_dataset_1d/*.sdf")
+
 .. _loading-raw-files-getting-started:
 
 Loading raw files

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

@@ -15,8 +15,8 @@ Loading SDF files
 -----------------
 There are several ways to load SDF files:
 
-- To load a single file, use `xarray.open_dataset`.
-- To load multiple files, use `sdf_xarray.open_mfdataset` or `xarray.open_mfdataset`.
+- 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::
@@ -41,6 +41,13 @@ Loading single files
 
    xr.open_dataset("tutorial_dataset_1d/0010.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_datatree("tutorial_dataset_1d/0010.sdf")
 
 .. _loading-raw-files:
 
@@ -72,6 +79,14 @@ is by using the `sdf_xarray.open_mfdataset`.
 
    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
 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
@@ -219,6 +234,44 @@ value intead of an index.
 
    ds["Electric_Field_Ex"].sel(time=sim_time)
 
+Visualisation on HPCs
+---------------------
+
+In many cases you will be running EPOCH simulations via a HPC cluster and your
+subsequent SDF files will probably be rather large and cumbersome to interact with
+via traditional Jupyter notebooks. In some cases your HPC may outright block the
+use of Jupyter notebooks entirely. To circumvent this issue you can use a Terminal
+User Interface (TUI) which renders the contents of SDF files directly in a Terminal
+and allows for you to do some simple data analysis and visualisation. To do this we
+shall leverage the `xr-tui <https://github.com/samueljackson92/xr-tui>`_ package
+which can be installed to either a venv or globally using:
+
+.. code-block:: bash
+
+   pip install xr-tui sdf-xarray
+
+or if you are using ``uv``
+
+.. code-block:: bash
+
+   uv tool install xr-tui --with sdf-xarray
+
+Once installed you can visualise SDF files by simply writing in the command line
+
+.. code-block:: bash
+
+   xr path/to/simulation/0000.sdf
+   # OR
+   xr path/to/simulation/*.sdf
+
+
+Below is an example gif of how this interfacing looks as seen on
+`xr-tui <https://github.com/samueljackson92/xr-tui>`_ ``README.md``:
+
+.. image:: https://raw.githubusercontent.com/samueljackson92/xr-tui/main/demo.gif
+   :alt: xr-tui interfacing gif
+   :align: center
+
 Manipulating data
 -----------------
 

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

@@ -19,7 +19,7 @@ authors = [
   { name = "Chris Herdman", email = "chris.herdman@york.ac.uk" },
   { name = "Liam Pattinson", email = "liam.pattinson@york.ac.uk" },
 ]
-requires-python = ">=3.10,<3.15"
+requires-python = ">=3.11,<3.15"
 dependencies = ["numpy>=2.0.0", "xarray>=2024.1.0", "dask>=2024.7.1"]
 description = "Provides a backend for xarray to read SDF files as created by the EPOCH plasma PIC code."
 classifiers = [
@@ -29,7 +29,6 @@ classifiers = [
   "Operating System :: OS Independent",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
@@ -42,10 +41,10 @@ pint = ["pint", "pint-xarray"]
 
 [dependency-groups]
 dev = [
-    {include-group = "build"},
-    {include-group = "docs"},
-    {include-group = "lint"},
-    {include-group = "test"},
+  { include-group = "build" },
+  { include-group = "docs" },
+  { include-group = "lint" },
+  { include-group = "test" },
 ]
 docs = [
   "sphinx>=5.3",
@@ -76,6 +75,9 @@ test = [
 [project.entry-points."xarray.backends"]
 sdf_engine = "sdf_xarray:SDFEntrypoint"
 
+[project.entry-points."xr_tui.backends"]
+"*.sdf" = "sdf_xarray:XrTUIEntrpoint"
+
 [tool.scikit-build]
 metadata.version.provider = "scikit_build_core.metadata.setuptools_scm"
 sdist.include = ["src/sdf_xarray/_version.py"]
@@ -94,7 +96,6 @@ cache-keys = [{ file = "pyproject.toml" }, { git = true }]
 
 [tool.ruff]
 line-length = 88
-target-version = "py310"
 
 [tool.ruff.lint]
 extend-select = [
@@ -123,6 +124,5 @@ ignore = [
   "B9",      # flake8-bugbear opinionated warnings
   "PLR0913", # remove maximum number of arguments in a function
 ]
-exclude = [
-  "**/_version.py", # Auto-generated file
-]
+exclude = ["**/_version.py"]
+# Auto-generated file