sdf-xarray 0.8.0__tar.gz → 0.9.0__tar.gz

{sdf_xarray-0.8.0 → sdf_xarray-0.9.0}/.github/workflows/build_publish.yml

@@ -20,7 +20,7 @@ jobs:
         submodules: "recursive"
 
     - name: Cache Zenodo datasets
-      uses: actions/cache@v4
+      uses: actions/cache@v6
       with:
         enableCrossOsArchive: true
         path: ~/.cache/sdf_datasets

{sdf_xarray-0.8.0 → sdf_xarray-0.9.0}/.github/workflows/tests.yml

@@ -31,7 +31,7 @@ jobs:
         uv sync --python ${{ matrix.python-version }} --frozen
 
     - name: Cache Zenodo datasets
-      uses: actions/cache@v4
+      uses: actions/cache@v6
       with:
         path: ~/.cache/sdf_datasets
         key: sdf-datasets-17991042

{sdf_xarray-0.8.0 → sdf_xarray-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdf-xarray
-Version: 0.8.0
+Version: 0.9.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>, Sviatoslav Shekhanov <sviatoslav.shekhanov@york.ac.uk>
 License-Expression: BSD-3-Clause

{sdf_xarray-0.8.0 → sdf_xarray-0.9.0}/docs/animation.md

@@ -35,9 +35,10 @@ resolved data has 2 dimensions.
 
 | Dimensions |      Plotting function        |        Notes          |
 | ---------- | ----------------------------- | --------------------- |
-|    `2`     | <inv:#xarray.plot.line>       |                       |
-|    `3`     | <inv:#xarray.plot.pcolormesh> |                       |
-|    `>3`    | <inv:#xarray.plot.hist>       | Not fully implemented |
+|     2      | <inv:#xarray.plot.line>       |                       |
+|     3      | <inv:#xarray.plot.pcolormesh> |                       |
+|     4      | <inv:#mpl_toolkits.mplot3d.axes3d.Axes3D.voxels>| WIP |
+|     >4     | <inv:#xarray.plot.hist>       | Not fully implemented |
 
 
 ### 1D simulation
@@ -103,6 +104,10 @@ anim.show()
 
 ### 3D simulation
 
+```{warning}
+[Voxel](./plotting.md#voxel-plots) animations are not currently implemented. 
+```
+
 Opening a 3D simulation as a multi-file dataset and plotting it will
 return a <inv:#xarray.plot.hist>. However, this may not be
 desirable. We can plot a 3D simulation along a certain plane in the

{sdf_xarray-0.8.0 → sdf_xarray-0.9.0}/docs/index.md

@@ -21,6 +21,7 @@ why_sdf_xarray.md
 loading_data.md
 understanding_datasets.md
 unit_conversion.md
+plotting.md
 animation.md
 ```
 

sdf_xarray-0.9.0/docs/plotting.md

@@ -0,0 +1,95 @@
+---
+file_format: mystnb
+kernelspec:
+  name: python3
+---
+
+# Plotting
+
+You can plot datasets using
+[`xarray.DataArray.epoch.plot`](project:#sdf_xarray.dataarray_accessor.EpochAccessor.plot).
+This is a custom <project:#sdf_xarray> plotting routine that builds on top of
+<inv:#xarray.DataArray.plot>, so you keep the familiar <inv:#xarray> plotting
+behaviour while using <project:#sdf_xarray> conveniences (see 
+[here](project:#sdf_xarray.dataarray_accessor.EpochAccessor.plot) for details).
+Under the hood, plotting is still handled by <inv:#matplotlib>, which means you
+can use the full <inv:#matplotlib> API to customise your figure.
+
+| Dimensions | Base plotting function        |        Notes          |
+| ---------- | ----------------------------- | --------------------- |
+|     1      | <inv:#xarray.plot.line>       |                       |
+|     2      | <inv:#xarray.plot.pcolormesh> |                       |
+|     3      | <inv:#mpl_toolkits.mplot3d.axes3d.Axes3D.voxels>| Custom functionality built for <project:#sdf_xarray> |
+|     >3     | <inv:#xarray.plot.hist>       | Not fully implemented |
+
+## Line plots
+
+One dimensional data will be plotted as a line. Multiple lines can be easily
+plotted at the same time.
+
+```{code-cell} ipython3
+import sdf_xarray as sdfxr
+import matplotlib.pyplot as plt
+ds = sdfxr.open_dataset("tutorial_dataset_1d/0010.sdf")
+da_1 = ds["Derived_Number_Density_Electron"]
+da_2 = ds["Derived_Number_Density_Ion"]
+da_1.epoch.plot(label = "Electron")
+da_2.epoch.plot(label = "Ion")
+plt.legend()
+plt.show()
+```
+
+## Mesh plots
+
+Two dimensional data will be plotted as a mesh.
+
+```{code-cell} ipython3
+ds = sdfxr.open_dataset("tutorial_dataset_2d/0010.sdf")
+da = ds["Derived_Number_Density_Electron"]
+da.epoch.plot()
+plt.show()
+```
+
+## Voxel plots
+
+Three dimensional data will be plotted using voxels. This behaviour is not native
+to <inv:#xarray>, it has been custom built specifically for this package.
+
+```python
+ds = sdfxr.open_dataset("tutorial_dataset_3d/0000.sdf")
+da = ds["Derived_Number_Density"]
+da.epoch.plot(vmin = 1e27)
+plt.show()
+```
+
+![voxel_plot_high_res](./figures/voxel_plot_high_res.png)
+
+```{warning}
+Voxel plots can be extremely computationally expensive and may take longer than
+expected to plot.
+```
+
+Because voxel plots are very expensive, even with relatively small data arrays,
+plotting can be sped up by using [`xarray.DataArray.epoch.resize`](project:#sdf_xarray.dataarray_accessor.EpochAccessor.resize),
+which uses interpolation to reduce the resolution.
+
+```{code-cell} ipython3
+ds = sdfxr.open_dataset("tutorial_dataset_3d/0005.sdf")
+da = ds["Derived_Number_Density"]
+da_resized = da.epoch.resize((20, 20, 20))
+da_resized.epoch.plot(vmin = 1e27)
+plt.show()
+```
+
+## Histograms
+
+When the data array has four or more dimensions (or is specified by the user), it will
+be plotted as a histogram.
+
+```{code-cell} ipython3
+ds = sdfxr.open_dataset("tutorial_dataset_3d/0005.sdf")
+da = ds["Derived_Number_Density"]
+
+da.epoch.plot(hist = True)
+plt.show()
+```

{sdf_xarray-0.8.0 → sdf_xarray-0.9.0}/docs/understanding_datasets.md

@@ -29,23 +29,10 @@ ds = sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
 ds["Electric_Field_Ex"]
 ```
 
-## Plotting
+## Visualisation
 
-You can plot datasets using
-[`xarray.DataArray.epoch.plot`](project:#sdf_xarray.dataarray_accessor.EpochAccessor.plot).
-This is a custom <project:#sdf_xarray> plotting routine that builds on top of
-<inv:#xarray.DataArray.plot>, so you keep the familiar <inv:#xarray> plotting
-behaviour while using <project:#sdf_xarray> conveniences (see 
-[here](project:#sdf_xarray.dataarray_accessor.EpochAccessor.plot) for details).
-Under the hood, plotting is still handled by <inv:#matplotlib>, which means you
-can use the full <inv:#matplotlib> API to customise your figure.
-
-```{code-cell} ipython3
-# This is discretized in both space and time
-ds["Electric_Field_Ex"].epoch.plot()
-plt.title("Electric field along the x-axis")
-plt.show()
-```
+`sdf-xarray` has built-in plotting and animation functionality, more details can
+be found on [](./plotting.md) and [](./animation.md).
 
 ## Dimension slicing
 
@@ -56,6 +43,7 @@ for easy indexing. To quickly determine the number of time steps available,
 you can check the size of the time dimension.
 
 ```{code-cell} ipython3
+ds = sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
 # This corresponds to the number of individual SDF files loaded
 print(f"There are a total of {ds['time'].size} time steps")
 
@@ -66,7 +54,7 @@ print(f"The time at the 20th simulation step is {sim_time:.2e} s")
 
 You can select and extract a single simulation snapshot using the integer
 index of the time step with the <inv:#xarray.Dataset.isel> function. This can be
-done by passsing the index to the `time` parameter (e.g., `time=0` for
+done by passing the index to the `time` parameter (e.g., `time=0` for
 the first snapshot).
 
 ```{code-cell} ipython3
@@ -74,7 +62,7 @@ ds["Electric_Field_Ex"].isel(time=20)
 ```
 
 We can also use the <inv:#xarray.Dataset.sel> function if you wish to pass a
-value intead of an index.
+value instead of an index.
 
 ```{tip}
 If you know roughly what time you wish to select but not the exact value
@@ -122,6 +110,51 @@ print(f"Total particle energy absorbed: {ds["Total_Particle_Energy_in_Simulation
 print(f"The laser absorption fraction: {ds["Laser_Absorption_Fraction_in_Simulation"][-1].values:.1f} %")
 ```
 
+## Limit
+
+The `.epoch` accessor has the ability to "limit" data arrays. This is a helper
+function which applies <inv:#xarray.DataArray.where> to the upper and lower bounds
+of each dimension. You can use `None` to preserve the existing limit.
+
+```{code-cell} ipython3
+ds = sdfxr.open_dataset("tutorial_dataset_2d/0020.sdf")
+da = ds["Derived_Number_Density_Electron"]
+da.epoch.plot()
+print(f"Orignal shape: {da.shape}")
+plt.show()
+```
+
+```{code-cell} ipython3
+da_limit = da.epoch.limit(((-2e-6, 2e-6), (None, 0)))
+da_limit.epoch.plot()
+print(f"New shape: {da_limit.shape}")
+plt.show()
+```
+
+## Resize
+
+The data arrays can be interpolated with <project:#sdf_xarray.dataarray_accessor.EpochAccessor.resize>
+to either increase or decrease the resolution while mantaining the general structure.
+Decreasing the size may be useful to download large data from HPCs to local machines
+or ploting with [](./plotting.md#voxel-plots). Be aware that the original
+data will not be preserved.
+
+```{code-cell} ipython3
+ds = sdfxr.open_dataset("tutorial_dataset_2d/0020.sdf")
+da = ds["Derived_Number_Density_Electron"]
+
+da.epoch.plot()
+print(f"Orignal shape: {da.shape}")
+plt.show()
+```
+
+```{code-cell} ipython3
+da_resized = da.epoch.resize((50, 50))
+da_resized.epoch.plot()
+print(f"New shape: {da_resized.shape}")
+plt.show()
+```
+
 ## Visualisation on HPC Machines
 
 In many cases you will be running EPOCH simulations via a HPC cluster and your

{sdf_xarray-0.8.0 → sdf_xarray-0.9.0}/docs/why_sdf_xarray.md

@@ -7,7 +7,7 @@ There are several benefits to using this package over the [`sdf_helper`](https:/
 - [data to numpy and pandas](https://docs.xarray.dev/en/stable/user-guide/pandas.html) - Data can be easily converted to [numpy](https://www.numpy.org/) or [pandas](https://pandas.pydata.org/) if you prefer to work with raw data.
 - [data labelling](project:understanding_datasets.md) - All SDF files come with a bunch of information about them such as the `dimensions`, `units` and `name` of the variable. In <inv:#xarray> these are added to each variable making it much easier to read.
 - [lazy/partial loading](https://docs.xarray.dev/en/stable/internals/internal-design.html#lazy-loading) - This reduces the RAM requirements when loading large SDF files as we only load the actual array values when they are needed.
-- [plotting](project:understanding_datasets.md#plotting) - You can easily plot variables across several dimensions including time using built in <inv:#matplotlib> support.
+- [plotting](project:plotting.md) - You can easily plot variables across several dimensions including time using built in <inv:#matplotlib> support.
 - [animating](project:animation.md) - Visualise your data across time or slice through another dimension and make beautiful GIFs for your presentations.
 - [deck loading](loading-input-deck) - <project:#sdf_xarray> automatically loads in the associated `input.deck` utilised when creating the simulation so that you can access setup variables.
 - [easier unit conversion](project:unit_conversion.md) - Convert dimensions and variable units to other types with the help of [`pint`](https://pint.readthedocs.io/en/stable).

{sdf_xarray-0.8.0 → sdf_xarray-0.9.0}/pyproject.toml

@@ -69,6 +69,7 @@ docs = [
   "sphinx-design>=0.7.0",
   "pooch>=1.8.2",
   "tqdm",
+  "scipy",
 ]
 build = ["cibuildwheel[uv]"]
 lint = ["ruff"]
@@ -80,6 +81,7 @@ test = [
   "tqdm",
   "pint",
   "pint-xarray",
+  "scipy",
 ]
 
 [project.entry-points."xarray.backends"]
@@ -133,6 +135,10 @@ ignore = [
   "PLR2004", # magic-comparison
   "B9",      # flake8-bugbear opinionated warnings
   "PLR0913", # remove maximum number of arguments in a function
+  "PLR0917", # remove maximum number of positional arguments in a function
+  "BLE001",  # allow capturing of base exception
 ]
-exclude = ["**/_version.py"]
-# Auto-generated file
+exclude = ["**/_version.py"] # Auto-generated file
+
+[tool.pytest.ini_options]
+filterwarnings = ['ignore::UserWarning']

{sdf_xarray-0.8.0 → sdf_xarray-0.9.0}/src/sdf_xarray/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.8.0'
-__version_tuple__ = version_tuple = (0, 8, 0)
+__version__ = version = '0.9.0'
+__version_tuple__ = version_tuple = (0, 9, 0)
 
-__commit_id__ = commit_id = 'gbd2a24a3a'
+__commit_id__ = commit_id = 'g65bb865da'

sdf_xarray-0.9.0/src/sdf_xarray/dataarray_accessor.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+from types import MethodType
+from typing import TYPE_CHECKING
+
+import numpy as np
+import xarray as xr
+from xarray.plot.accessor import DataArrayPlotAccessor
+
+from .plotting import _recover_vertex_coord, animate, show, voxel_plot
+
+if TYPE_CHECKING:
+    from matplotlib.animation import FuncAnimation
+
+
+def _resize_ndarray(
+    arr: np.ndarray,
+    new_shape: tuple | list | np.ndarray,
+) -> np.ndarray:
+    """
+    Resizes a `numpy.ndarray` to another shape. The returned array must have the
+    same dimensionality as the input array.
+    Parameters
+    ----------
+    arr
+        The input array.
+    new_shape
+        The shape of the new `xarray.DataArray`, must be the same length as arr.shape.
+    """
+
+    from scipy.interpolate import RegularGridInterpolator  # noqa: PLC0415
+
+    if arr.ndim != len(new_shape):
+        raise ValueError(
+            f"The number of dimensions must match the input array. (original: {arr.ndim}, new: {len(new_shape)})"
+        )
+
+    old_grids = tuple(np.linspace(0, 1, size) for size in arr.shape)
+    new_grids = tuple(np.linspace(0, 1, size) for size in new_shape)
+    mesh = np.meshgrid(*new_grids, indexing="ij")
+    coords = np.stack(mesh, axis=-1)
+
+    return RegularGridInterpolator(old_grids, arr, bounds_error=False, fill_value=0)(
+        coords
+    )
+
+
+@xr.register_dataarray_accessor("epoch")
+class EpochAccessor:
+    def __init__(self, xarray_obj: xr.DataArray):
+        self._obj = xarray_obj
+
+    def plot(self, hist=False, *args, **kwargs) -> DataArrayPlotAccessor:
+        """
+        Builds upon `xarray.DataArray.plot` while changing some of its default behaviours.
+
+        These changes are:
+
+        - Flips the default axes order for 2D plots so that x and y are on the correct axes.
+          This exists because plotting of 2D data in xarray uses the `xarray.plot.pcolormesh`
+          function which takes assumes that ``x = dim[1]`` and ``y = dim[0]``.
+
+        Parameters
+        ----------
+        hist
+            If ``True``, will plot a histogram regardless of dimensionality (default = ``False``).
+        args
+            Positional arguments passed to `xarray.DataArray.plot`.
+        kwargs
+            Keyword arguments passed to `xarray.DataArray.plot`.
+        """
+        dims = self._obj.dims
+
+        if hist:
+            return self._obj.plot.hist(*args, **kwargs)
+
+        if len(dims) == 1:
+            return self._obj.plot(*args, **kwargs)
+
+        if len(dims) == 2:
+            updated_kwargs = dict(kwargs)
+            updated_kwargs.setdefault("x", dims[0])
+            updated_kwargs.setdefault("y", dims[1])
+            return self._obj.plot(*args, **updated_kwargs)
+
+        if len(dims) == 3:
+            return voxel_plot(self._obj, *args, **kwargs)
+
+        return self._obj.plot(*args, **kwargs)
+
+    def animate(self, *args, **kwargs) -> FuncAnimation:
+        """Generate animations of Epoch data.
+
+        Parameters
+        ----------
+        args
+            Positional arguments passed to :func:`animation`.
+        kwargs
+            Keyword arguments passed to :func:`animation`.
+
+        Examples
+        --------
+        >>> anim = ds["Electric_Field_Ey"].epoch.animate()
+        >>> anim.save("animation.gif")
+        >>> # Or in a jupyter notebook:
+        >>> anim.show()
+        """
+
+        # Add anim.show() functionality
+        # anim.show() will display the animation in a jupyter notebook
+        anim = animate(self._obj, *args, **kwargs)
+        anim.show = MethodType(show, anim)
+
+        return anim
+
+    def resize(
+        self,
+        new_shape,
+    ) -> xr.DataArray:
+        """
+        Resizes a `xarray.DataArray` to another shape. The returned array must have the
+        same dimensionality as the input array.
+
+        Parameters
+        ----------
+        new_shape
+            The shape of the new `xarray.DataArray`, must be the same length as self.shape.
+        """
+
+        da = self._obj
+
+        # Create resized data and Dataset
+        data_resized = _resize_ndarray(da.values, new_shape)
+        da_resized = da.copy()
+        da_resized = xr.DataArray(
+            data=data_resized,
+            dims=da.dims,
+            attrs=da.attrs,
+        )
+
+        original_cell_size_da = []
+
+        # Resize coordinates and add to DataArray
+        for i in range(len(da_resized.dims)):
+            coord = list(da_resized.dims)[i]
+
+            if coord.endswith("_mid"):
+                # If the coordinate is a midpoint coordinate, care must be taken to resize correctly
+                vertex_coord = _recover_vertex_coord(da[coord])
+                vertex_coord_resized = np.linspace(
+                    vertex_coord[0], vertex_coord[-1], new_shape[i] + 1
+                )
+                # Turn the vertex coord back into a midpoint coord
+                da_resized[coord] = (
+                    (np.roll(vertex_coord_resized, 1) + vertex_coord_resized) / 2
+                )[1:]
+            else:
+                # If not, the coordinate can be simply resized
+                coord_min = da[coord][0].values
+                coord_max = da[coord][-1].values
+                da_resized[coord] = np.linspace(coord_min, coord_max, new_shape[i])
+
+            da_resized[coord].attrs = da[coord].attrs
+
+            # Add original information as attributes
+            if "original_shape" not in da.attrs:
+                da_resized[coord].attrs["original_size"] = da.shape[i]
+                original_cell_size = float((da[coord][1] - da[coord][0]).values)
+                original_cell_size_da.append(original_cell_size)
+                da_resized[coord].attrs["original_cell_size"] = original_cell_size
+
+        if "original_shape" not in da.attrs:
+            da_resized.attrs["original_shape"] = da.shape
+            da_resized.attrs["original_cell_size"] = tuple(original_cell_size_da)
+
+        return da_resized
+
+    def limit(
+        self,
+        limits,
+        drop: bool = True,
+    ) -> xr.DataArray:
+        """
+        Drops values outside the specified limits.
+
+        Parameters
+        ----------
+        limits
+            Array-like list of limits.
+        drop
+            Bool specifying whether to drop the co-ordinates outside the limits (default = True).
+        """
+        da = self._obj
+        limits = list(limits)
+
+        # List of dimension names
+        dims = da.dims
+
+        original_lims_da = []
+        for i in range(len(dims)):
+            limits[i] = list(limits[i])
+
+            # Find the original limits of the dataarray
+            original_lims = (
+                float(da[dims[i]].values[0]),
+                float(da[dims[i]].values[-1]),
+            )
+            original_lims_da.append(original_lims)
+            if "original_lims" not in da[dims[i]].attrs:
+                da[dims[i]].attrs["original_lims"] = original_lims
+
+            # If None is passed into limit, will assume the existing limit
+            if limits[i][0] is None:
+                limits[i][0] = original_lims[0]
+            if limits[i][-1] is None:
+                limits[i][-1] = original_lims[1]
+
+            # Limit dataarray
+            da = da.where(da[dims[i]] >= limits[i][0], drop=drop).where(
+                da[dims[i]] <= limits[i][1], drop=drop
+            )
+
+        if "original_lims" not in da.attrs:
+            da.attrs["original_lims"] = tuple(original_lims_da)
+
+        return da