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

{sdf_xarray-0.4.0 → sdf_xarray-0.6.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.6.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.6.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.6.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.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.4.0 → sdf_xarray-0.6.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.6.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: sdf-xarray
-Version: 0.4.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
@@ -10,15 +10,15 @@ 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
+Requires-Dist: epydeck~=1.0
 Provides-Extra: jupyter
 Requires-Dist: dask[diagnostics]; extra == "jupyter"
 Requires-Dist: ipykernel>=6.29.5; extra == "jupyter"
@@ -35,7 +35,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 +148,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.6.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.6.0/docs/_static/jupyter_padding.css

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

{sdf_xarray-0.4.0 → sdf_xarray-0.6.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
 ==========
@@ -122,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()
@@ -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.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.