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

{sdf_xarray-0.3.2 → 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
@@ -29,7 +36,7 @@ jobs:
     - name: Set up Python 3.12 and install dependencies
       run: |
         uv python install 3.12
-        uv sync --python 3.12 --extra test --extra build --frozen
+        uv sync --python 3.12 --frozen
 
     - name: Build
       uses: pypa/cibuildwheel@v3.1.3

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.3.2 → 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"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v4
@@ -18,7 +18,7 @@ jobs:
 
     - name: Setup uv
       id: setup-uv
-      uses: astral-sh/setup-uv@v3
+      uses: astral-sh/setup-uv@v7
       with:
         enable-cache: true
 
@@ -28,7 +28,13 @@ jobs:
     - name: Set up Python ${{ matrix.python-version }} and install dependencies
       run: |
         uv python install ${{ matrix.python-version }}
-        uv sync --python ${{ matrix.python-version }} --extra test --extra build --frozen
+        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.3.2 → 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,5 +331,11 @@ Module.symvers
 Mkfile.old
 dkms.conf
 
+# sdf-xarray specific ignores
+# ---------------------------
+
 # Generated version file
 src/sdf_xarray/_version.py
+
+# Downloaded doc tutorial datasets
+docs/tutorial_*

{sdf_xarray-0.3.2 → sdf_xarray-0.5.0}/.readthedocs.yaml

@@ -16,6 +16,16 @@ build:
     # rust: "1.55"
     # golang: "1.17"
 
+  jobs:
+    pre_create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    create_environment:
+      - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
    configuration: docs/conf.py
@@ -23,11 +33,3 @@ sphinx:
 # Optionally build your docs in additional formats such as PDF
 # formats:
 #    - pdf
-
-# Optionally declare the Python requirements required to build your docs
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs

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

@@ -20,5 +20,9 @@ authors:
     given-names: Chris
     orcid: 'https://orcid.org/0000-0002-5159-0130'
     affiliation: University of York
+  - family-names: Pattinson
+    given-names: Liam
+    orcid: 'https://orcid.org/0000-0001-8604-6904'
+    affiliation: University of York
 doi: 10.5281/zenodo.15351323
 date-released: '2024-07-25'

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

@@ -4,7 +4,7 @@ We welcome contributions to the BEAM ecosystem! Whether it's reporting issues,
 suggesting features, improving the documentation, or submitting pull requests,
 your input helps improve these tools for the community.
 
-## How to Contribute
+## How to contribute
 
 There are many ways to get involved:
 
@@ -20,35 +20,69 @@ There are many ways to get involved:
 
 ## Code
 
+```bash
+git clone --recursive https://github.com/epochpic/sdf-xarray.git
+cd sdf-xarray
+pip install .
+```
+
 ### Style
 
-We follow [PEP 8](https://peps.python.org/pep-0008/) and use the
-following tools:
+We use [Ruff](https://docs.astral.sh/ruff/) to maintain code quality and
+formatting. This can be installed locally via the `lint` dependency group:
 
-- [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
+```bash
+pip install --group lint
+```
 
-To run these tools locally, install the optional dependencies and run:
+Ruff can then be run with:
 
 ```bash
-pip install "sdf-xarray[lint]"
 ruff check src tests
 ```
 
-### Running and Adding Tests
+Alternatively, `uv` users can do this in one step with `uv run`:
+
+```bash
+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.
 All new functionality should include relevant tests, placed in the `tests/`
 directory and following the existing structure.
 
+When running the tests for the first time you will need an internet connection
+in order to download the datasets.
+
 Before submitting code changes, ensure that all tests pass:
 
 ```bash
-pip install "sdf-xarray[test]"
+pip install --group test
 pytest
 ```
 
+Alternatively, `uv` users can use:
+
+```bash
+uv run pytest
+```
+
 ## Documentation
 
 ### Style
@@ -59,12 +93,15 @@ When contributing to the documentation:
 - Follow the format of existing `.rst` files.
 - Link to external functions or tools when possible.
 
-### Compiling and Adding Documentation
+### Compiling and adding documentation
+
+When compiling the documentation for the first time you will need an internet
+connection in order to download the datasets.
 
 To build the documentation locally, first install the required packages:
 
 ```bash
-pip install "sdf-xarray[docs]"
+pip install --group docs
 cd docs
 make html
 ```
@@ -77,9 +114,9 @@ please don't hesitate to reach out.
 Every time you make changes to the documentation or add a new page, you must
 re-run the `make html` command to regenerate the HTML files.
 
-### Previewing Documentation
+### Previewing documentation
 
-#### Using VS Code Extensions
+#### Using VS Code extensions
 
 Once the html web pages have been made you can review them installing the
 [Live Server](https://marketplace.visualstudio.com/items/?itemName=ritwickdey.LiveServer)
@@ -87,22 +124,22 @@ VS Code extension. Navigate to the `_build/html` folder, right-click the
 `index.html`, and select **"Open with Live Server"**. This
 will open a live preview of the documentation in your web browser.
 
-#### Using a Simple Python Server
+#### Using a simple python server
 
 Alternatively, if you're not using VS Code, you can start a simple local server with Python:
 
 ```bash
-python -m http.server -d _build/htm
+python -m http.server -d _build/html
 ```
 
 Then open http://localhost:8000 in your browser to view the documentation.
 
-## Continuous Integration
+## Continuous integration
 
 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.3.2 → sdf_xarray-0.5.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: sdf-xarray
-Version: 0.3.2
+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>
+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
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
@@ -10,34 +10,14 @@ 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
-Requires-Python: <3.14,>=3.10
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.11
 Requires-Dist: numpy>=2.0.0
 Requires-Dist: xarray>=2024.1.0
 Requires-Dist: dask>=2024.7.1
-Provides-Extra: docs
-Requires-Dist: sphinx>=5.3; extra == "docs"
-Requires-Dist: sphinx_autodoc_typehints>=1.19; extra == "docs"
-Requires-Dist: sphinx-book-theme>=0.4.0rc1; extra == "docs"
-Requires-Dist: sphinx-argparse-cli>=1.10.0; extra == "docs"
-Requires-Dist: sphinx-inline-tabs; extra == "docs"
-Requires-Dist: pickleshare; extra == "docs"
-Requires-Dist: ipython; extra == "docs"
-Requires-Dist: matplotlib; extra == "docs"
-Requires-Dist: pint; extra == "docs"
-Requires-Dist: pint-xarray; extra == "docs"
-Requires-Dist: myst-parser; extra == "docs"
-Provides-Extra: test
-Requires-Dist: pytest>=3.3.0; extra == "test"
-Requires-Dist: dask[complete]; extra == "test"
-Requires-Dist: matplotlib; extra == "test"
-Provides-Extra: lint
-Requires-Dist: ruff; extra == "lint"
-Provides-Extra: build
-Requires-Dist: cibuildwheel[uv]; extra == "build"
 Provides-Extra: jupyter
 Requires-Dist: dask[diagnostics]; extra == "jupyter"
 Requires-Dist: ipykernel>=6.29.5; extra == "jupyter"
@@ -54,35 +34,28 @@ 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
 [EPOCH](https://epochpic.github.io) using the [SDF-C](https://github.com/epochpic/SDF_C) library.
 Part of [BEAM](#broad-epoch-analysis-modules-beam) (Broad EPOCH Analysis Modules).
 
+## Installation
+
 > [!IMPORTANT]
 > To install this package make sure you are using one of the Python versions listed above.
 
-## Installation
-
 Install from PyPI with:
 
 ```bash
 pip install sdf-xarray
 ```
 
-> [!NOTE]
-> For use within jupyter notebooks, run this additional command after installation:
->
-> ```bash
-> pip install "sdf-xarray[jupyter]"
-> ```
-
-or from a local checkout:
+or download this code locally:
 
 ```bash
-git clone https://github.com/epochpic/sdf-xarray.git
+git clone --recursive https://github.com/epochpic/sdf-xarray.git
 cd sdf-xarray
 pip install .
 ```
@@ -91,6 +64,9 @@ We recommend switching to [uv](https://docs.astral.sh/uv/) to manage packages.
 
 ## Usage
 
+Below are some simple examples to get you started. Please read the full
+documentation here <https://sdf-xarray.readthedocs.io>.
+
 ### Single file loading
 
 ```python
@@ -111,15 +87,22 @@ print(df["Electric_Field_Ex"])
 
 ### Multi-file loading
 
-To open a whole simulation at once, pass `preprocess=sdf_xarray.SDFPreprocess()`
-to `xarray.open_mfdataset`:
+You can open all the SDF files for a given simulation by calling the `open_mfdataset`
+function from `sdf_xarray`. This will additionally add a time dimension using the `"time"`
+value stored in each files attributes.
+
+> [!IMPORTANT]
+> If your simulation has multiple `output` blocks so that not all variables are
+> output at every time step, then at the timesteps where those variables are not
+> present they will have have a value of nan. To clean your dataset by removing
+> these nan values we suggest using the `xarray.DataArray.dropna` function or
+> loading sparse data along separate time dimensions using `separate_times=True`.
 
 ```python
-import xarray as xr
-from sdf_xarray import SDFPreprocess
+from sdf_xarray import open_mfdataset
 
-with xr.open_mfdataset("*.sdf", preprocess=SDFPreprocess()) as ds:
-    print(ds)
+ds = open_mfdataset("*.sdf")
+print(ds)
 
 # Dimensions:
 # time: 301, X_Grid_mid: 128, ...
@@ -129,15 +112,6 @@ with xr.open_mfdataset("*.sdf", preprocess=SDFPreprocess()) as ds:
 # Attributes: (22) ...
 ```
 
-`SDFPreprocess` checks that all the files are from the same simulation, as
-ensures there's a `time` dimension so the files are correctly concatenated.
-
-If your simulation has multiple `output` blocks so that not all variables are
-output at every time step, then those variables will have `NaN` values at the
-corresponding time points.
-
-For more in depth documentation please visit: <https://sdf-xarray.readthedocs.io/>
-
 ## Citing
 
 If sdf-xarray contributes to a project that leads to publication, please acknowledge this by citing sdf-xarray. This can be done by clicking the "cite this repository" button located near the top right of this page.
@@ -173,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.3.2 → sdf_xarray-0.5.0}/README.md

@@ -6,35 +6,28 @@
 ![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
 [EPOCH](https://epochpic.github.io) using the [SDF-C](https://github.com/epochpic/SDF_C) library.
 Part of [BEAM](#broad-epoch-analysis-modules-beam) (Broad EPOCH Analysis Modules).
 
+## Installation
+
 > [!IMPORTANT]
 > To install this package make sure you are using one of the Python versions listed above.
 
-## Installation
-
 Install from PyPI with:
 
 ```bash
 pip install sdf-xarray
 ```
 
-> [!NOTE]
-> For use within jupyter notebooks, run this additional command after installation:
->
-> ```bash
-> pip install "sdf-xarray[jupyter]"
-> ```
-
-or from a local checkout:
+or download this code locally:
 
 ```bash
-git clone https://github.com/epochpic/sdf-xarray.git
+git clone --recursive https://github.com/epochpic/sdf-xarray.git
 cd sdf-xarray
 pip install .
 ```
@@ -43,6 +36,9 @@ We recommend switching to [uv](https://docs.astral.sh/uv/) to manage packages.
 
 ## Usage
 
+Below are some simple examples to get you started. Please read the full
+documentation here <https://sdf-xarray.readthedocs.io>.
+
 ### Single file loading
 
 ```python
@@ -63,15 +59,22 @@ print(df["Electric_Field_Ex"])
 
 ### Multi-file loading
 
-To open a whole simulation at once, pass `preprocess=sdf_xarray.SDFPreprocess()`
-to `xarray.open_mfdataset`:
+You can open all the SDF files for a given simulation by calling the `open_mfdataset`
+function from `sdf_xarray`. This will additionally add a time dimension using the `"time"`
+value stored in each files attributes.
+
+> [!IMPORTANT]
+> If your simulation has multiple `output` blocks so that not all variables are
+> output at every time step, then at the timesteps where those variables are not
+> present they will have have a value of nan. To clean your dataset by removing
+> these nan values we suggest using the `xarray.DataArray.dropna` function or
+> loading sparse data along separate time dimensions using `separate_times=True`.
 
 ```python
-import xarray as xr
-from sdf_xarray import SDFPreprocess
+from sdf_xarray import open_mfdataset
 
-with xr.open_mfdataset("*.sdf", preprocess=SDFPreprocess()) as ds:
-    print(ds)
+ds = open_mfdataset("*.sdf")
+print(ds)
 
 # Dimensions:
 # time: 301, X_Grid_mid: 128, ...
@@ -81,15 +84,6 @@ with xr.open_mfdataset("*.sdf", preprocess=SDFPreprocess()) as ds:
 # Attributes: (22) ...
 ```
 
-`SDFPreprocess` checks that all the files are from the same simulation, as
-ensures there's a `time` dimension so the files are correctly concatenated.
-
-If your simulation has multiple `output` blocks so that not all variables are
-output at every time step, then those variables will have `NaN` values at the
-corresponding time points.
-
-For more in depth documentation please visit: <https://sdf-xarray.readthedocs.io/>
-
 ## Citing
 
 If sdf-xarray contributes to a project that leads to publication, please acknowledge this by citing sdf-xarray. This can be done by clicking the "cite this repository" button located near the top right of this page.
@@ -125,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.5.0/docs/_static/force_render_dark_xarray_objects.css

@@ -0,0 +1,7 @@
+/* workaround Pydata Sphinx theme using light colors for widget cell outputs in dark-mode */
+/* works for many widgets but not for Xarray html reprs */
+/* https://github.com/pydata/pydata-sphinx-theme/issues/2189 */
+html[data-theme="dark"] div.cell_output .text_html:has(div.xr-wrap) {
+    background-color: var(--pst-color-on-background) !important;
+    color: var(--pst-color-text-base) !important;
+}