sdf-xarray 0.2.0__cp312-cp312-win_amd64.whl → 0.3.2__cp312-cp312-win_amd64.whl

sdf_xarray/__init__.py

@@ -1,12 +1,17 @@
+import contextlib
 import os
-import pathlib
 import re
 from collections import Counter, defaultdict
+from collections.abc import Callable, Iterable
+from importlib.metadata import version
 from itertools import product
-from typing import Iterable
+from os import PathLike as os_PathLike
+from pathlib import Path
+from typing import ClassVar
 
 import numpy as np
 import xarray as xr
+from packaging.version import Version
 from xarray.backends import AbstractDataStore, BackendArray, BackendEntrypoint
 from xarray.backends.file_manager import CachingFileManager
 from xarray.backends.locks import ensure_lock
@@ -14,9 +19,23 @@ from xarray.core import indexing
 from xarray.core.utils import close_on_error, try_read_magic_number_from_path
 from xarray.core.variable import Variable
 
+# NOTE: Do not delete these lines, otherwise the "epoch" dataset and dataarray
+# accessors will not be imported when the user imports sdf_xarray
+import sdf_xarray.dataset_accessor
 import sdf_xarray.plotting  # noqa: F401
 
-from .sdf_interface import Constant, SDFFile
+# NOTE: This attempts to initialise with the "pint" accessor if the user
+# has installed the package
+with contextlib.suppress(ImportError):
+    import pint_xarray  # noqa: F401
+
+from .sdf_interface import Constant, SDFFile  # type: ignore  # noqa: PGH003
+
+# TODO Remove this once the new kwarg options are fully implemented
+if Version(version("xarray")) >= Version("2025.8.0"):
+    xr.set_options(use_new_combine_kwarg_defaults=True)
+
+PathLike = str | os_PathLike
 
 
 def _rename_with_underscore(name: str) -> str:
@@ -48,24 +67,81 @@ def _process_latex_name(variable_name: str) -> str:
     return variable_name
 
 
-def combine_datasets(path_glob: Iterable | str, **kwargs) -> xr.Dataset:
-    """Combine all datasets using a single time dimension"""
+def _resolve_glob(path_glob: PathLike | Iterable[PathLike]):
+    """
+    Normalise input path_glob into a sorted list of absolute, resolved Path objects.
+    """
+
+    try:
+        p = Path(path_glob)
+        paths = list(p.parent.glob(p.name)) if p.name == "*.sdf" else list(p)
+    except TypeError:
+        paths = list({Path(p) for p in path_glob})
+
+    paths = sorted(p.resolve() for p in paths)
+    if not paths:
+        raise FileNotFoundError(f"No files matched pattern or input: {path_glob!r}")
+    return paths
+
+
+def purge_unselected_data_vars(ds: xr.Dataset, data_vars: list[str]) -> xr.Dataset:
+    """
+    If the user has exclusively requested only certain variables be
+    loaded in then we purge all other variables and dimensions
+    """
+    existing_data_vars = set(ds.data_vars.keys())
+    vars_to_keep = set(data_vars) & existing_data_vars
+    vars_to_drop = existing_data_vars - vars_to_keep
+    ds = ds.drop_vars(vars_to_drop)
+
+    existing_dims = set(ds.sizes)
+    dims_to_keep = set()
+    for var in vars_to_keep:
+        dims_to_keep.update(ds[var].coords._names)
+        dims_to_keep.update(ds[var].dims)
+
+    coords_to_drop = existing_dims - dims_to_keep
+    return ds.drop_dims(coords_to_drop)
+
+
+def combine_datasets(
+    path_glob: Iterable | str, data_vars: list[str], **kwargs
+) -> xr.Dataset:
+    """
+    Combine all datasets using a single time dimension, optionally extract
+    data from only the listed data_vars
+    """
+
+    if data_vars is not None:
+        return xr.open_mfdataset(
+            path_glob,
+            join="outer",
+            coords="different",
+            compat="no_conflicts",
+            combine="nested",
+            concat_dim="time",
+            preprocess=SDFPreprocess(data_vars=data_vars),
+            **kwargs,
+        )
 
     return xr.open_mfdataset(
         path_glob,
-        data_vars="minimal",
-        coords="minimal",
-        compat="override",
+        data_vars="all",
+        coords="different",
+        compat="no_conflicts",
+        join="outer",
         preprocess=SDFPreprocess(),
         **kwargs,
     )
 
 
 def open_mfdataset(
-    path_glob: Iterable | str | pathlib.Path | pathlib.Path.glob,
+    path_glob: Iterable | str | Path | Callable[..., Iterable[Path]],
     *,
     separate_times: bool = False,
     keep_particles: bool = False,
+    probe_names: list[str] | None = None,
+    data_vars: list[str] | None = None,
 ) -> xr.Dataset:
     """Open a set of EPOCH SDF files as one `xarray.Dataset`
 
@@ -95,20 +171,36 @@ def open_mfdataset(
         different output frequencies
     keep_particles :
         If ``True``, also load particle data (this may use a lot of memory!)
+    probe_names :
+        List of EPOCH probe names
+    data_vars :
+        List of data vars to load in (If not specified loads in all variables)
     """
 
-    # TODO: This is not very robust, look at how xarray.open_mfdataset does it
-    if isinstance(path_glob, str):
-        path_glob = pathlib.Path().glob(path_glob)
-
-    # Coerce to list because we might need to use the sequence multiple times
-    path_glob = sorted(list(path_glob))
+    path_glob = _resolve_glob(path_glob)
 
     if not separate_times:
-        return combine_datasets(path_glob, keep_particles=keep_particles)
+        return combine_datasets(
+            path_glob,
+            data_vars=data_vars,
+            keep_particles=keep_particles,
+            probe_names=probe_names,
+        )
 
-    time_dims, var_times_map = make_time_dims(path_glob)
-    all_dfs = [xr.open_dataset(f, keep_particles=keep_particles) for f in path_glob]
+    _, var_times_map = make_time_dims(path_glob)
+
+    all_dfs = []
+    for f in path_glob:
+        ds = xr.open_dataset(f, keep_particles=keep_particles, probe_names=probe_names)
+
+        # If the data_vars are specified then only load them in and disregard the rest.
+        # If there are no remaining data variables then skip adding the dataset to list
+        if data_vars is not None:
+            ds = purge_unselected_data_vars(ds, data_vars)
+            if not ds.data_vars:
+                continue
+
+        all_dfs.append(ds)
 
     for df in all_dfs:
         for da in df:
@@ -125,7 +217,11 @@ def open_mfdataset(
                 )
 
     return xr.combine_by_coords(
-        all_dfs, data_vars="minimal", combine_attrs="drop_conflicts"
+        all_dfs,
+        coords="different",
+        combine_attrs="drop_conflicts",
+        join="outer",
+        compat="no_conflicts",
     )
 
 
@@ -146,14 +242,12 @@ def make_time_dims(path_glob):
                 )
 
     # Count the unique set of lists of times
-    times_count = Counter((tuple(v) for v in vars_count.values()))
+    times_count = Counter(tuple(v) for v in vars_count.values())
 
     # Give each set of times a unique name
     time_dims = {}
-    count = 0
-    for t in times_count:
+    for count, t in enumerate(times_count):
         time_dims[f"time{count}"] = t
-        count += 1
 
     # Map each variable to the name of its time dimension
     var_times_map = {}
@@ -205,19 +299,28 @@ class SDFDataStore(AbstractDataStore):
     """Store for reading and writing data via the SDF library."""
 
     __slots__ = (
-        "lock",
-        "drop_variables",
-        "keep_particles",
         "_filename",
         "_manager",
+        "drop_variables",
+        "keep_particles",
+        "lock",
+        "probe_names",
     )
 
-    def __init__(self, manager, drop_variables=None, keep_particles=False, lock=None):
+    def __init__(
+        self,
+        manager,
+        drop_variables=None,
+        keep_particles=False,
+        lock=None,
+        probe_names=None,
+    ):
         self._manager = manager
         self._filename = self.ds.filename
         self.drop_variables = drop_variables
         self.keep_particles = keep_particles
         self.lock = ensure_lock(lock)
+        self.probe_names = probe_names
 
     @classmethod
     def open(
@@ -226,6 +329,7 @@ class SDFDataStore(AbstractDataStore):
         lock=None,
         drop_variables=None,
         keep_particles=False,
+        probe_names=None,
     ):
         if isinstance(filename, os.PathLike):
             filename = os.fspath(filename)
@@ -236,6 +340,7 @@ class SDFDataStore(AbstractDataStore):
             lock=lock,
             drop_variables=drop_variables,
             keep_particles=keep_particles,
+            probe_names=probe_names,
         )
 
     def _acquire(self, needs_lock=True):
@@ -249,12 +354,21 @@ class SDFDataStore(AbstractDataStore):
     def acquire_context(self, needs_lock=True):
         return self._manager.acquire_context(needs_lock)
 
-    def load(self):
+    def load(self):  # noqa: PLR0912, PLR0915
         # Drop any requested variables
         if self.drop_variables:
+            # Build a mapping from underscored names to real variable names
+            name_map = {_rename_with_underscore(var): var for var in self.ds.variables}
+
             for variable in self.drop_variables:
-                # TODO: nicer error handling
-                self.ds.variables.pop(variable)
+                key = _rename_with_underscore(variable)
+                original_name = name_map.get(key)
+
+                if original_name is None:
+                    raise KeyError(
+                        f"Variable '{variable}' not found (interpreted as '{key}')."
+                    )
+                self.ds.variables.pop(original_name)
 
         # These two dicts are global metadata about the run or file
         attrs = {**self.ds.header, **self.ds.run_info}
@@ -274,8 +388,7 @@ class SDFDataStore(AbstractDataStore):
         def _process_grid_name(grid_name: str, transform_func) -> str:
             """Apply the given transformation function and then rename with underscores."""
             transformed_name = transform_func(grid_name)
-            renamed_name = _rename_with_underscore(transformed_name)
-            return renamed_name
+            return _rename_with_underscore(transformed_name)
 
         for key, value in self.ds.grids.items():
             if "cpu" in key.lower():
@@ -310,6 +423,8 @@ class SDFDataStore(AbstractDataStore):
             # Had some problems with these variables, so just ignore them for now
             if "cpu" in key.lower():
                 continue
+            if "boundary" in key.lower():
+                continue
             if "output file" in key.lower():
                 continue
 
@@ -336,7 +451,28 @@ class SDFDataStore(AbstractDataStore):
 
             if value.is_point_data:
                 # Point (particle) variables are 1D
-                var_coords = (f"ID_{_process_grid_name(key, _grid_species_name)}",)
+
+                # Particle data does not maintain a fixed dimension size
+                # throughout the simulation. An example of a particle name comes
+                # in the form of `Particles/Px/Ion_H` which is then modified
+                # using `_process_grid_name()` into `Ion_H`. This is fine as the
+                # other components of the momentum (`Py`, `Pz`) will have the same
+                # size as they represent the same bunch of particles.
+
+                # Probes however have names in the form of `Electron_Front_Probe/Px`
+                # which are changed to just `Px`; this is fine when there is only one
+                # probe in the system but when there are multiple they will have
+                # conflicting sizes so we can't keep the names as simply `Px` so we
+                # instead set their dimension as the full name `Electron_Front_Probe_Px`.
+                is_probe_name_match = self.probe_names is not None and any(
+                    name in key for name in self.probe_names
+                )
+                name_processor = (
+                    _rename_with_underscore
+                    if is_probe_name_match
+                    else _grid_species_name
+                )
+                var_coords = (f"ID_{_process_grid_name(key, name_processor)}",)
             else:
                 # These are DataArrays
 
@@ -403,8 +539,9 @@ class SDFEntrypoint(BackendEntrypoint):
         *,
         drop_variables=None,
         keep_particles=False,
+        probe_names=None,
     ):
-        if isinstance(filename_or_obj, pathlib.Path):
+        if isinstance(filename_or_obj, Path):
             # sdf library takes a filename only
             # TODO: work out if we need to deal with file handles
             filename_or_obj = str(filename_or_obj)
@@ -413,33 +550,68 @@ class SDFEntrypoint(BackendEntrypoint):
             filename_or_obj,
             drop_variables=drop_variables,
             keep_particles=keep_particles,
+            probe_names=probe_names,
         )
         with close_on_error(store):
             return store.load()
 
-    open_dataset_parameters = ["filename_or_obj", "drop_variables", "keep_particles"]
+    open_dataset_parameters: ClassVar[list[str]] = [
+        "filename_or_obj",
+        "drop_variables",
+        "keep_particles",
+        "probe_names",
+    ]
 
     def guess_can_open(self, filename_or_obj):
         magic_number = try_read_magic_number_from_path(filename_or_obj)
         if magic_number is not None:
             return magic_number.startswith(b"SDF1")
 
-        try:
-            _, ext = os.path.splitext(filename_or_obj)
-        except TypeError:
-            return False
-        return ext in {".sdf", ".SDF"}
+        return Path(filename_or_obj).suffix in {".sdf", ".SDF"}
 
     description = "Use .sdf files in Xarray"
 
-    url = "https://epochpic.github.io/documentation/visualising_output/python.html"
+    url = "https://epochpic.github.io/documentation/visualising_output/python_beam.html"
 
 
 class SDFPreprocess:
-    """Preprocess SDF files for xarray ensuring matching job ids and sets time dimension"""
+    """Preprocess SDF files for xarray ensuring matching job ids and sets
+    time dimension.
+
+    This class is used as a 'preprocess' function within ``xr.open_mfdataset``. It
+    performs three main duties on each individual file's Dataset:
+
+    1. Checks for a **matching job ID** across all files to ensure dataset consistency.
+    2. **Filters** the Dataset to keep only the variables specified in `data_vars`
+       and their required coordinates.
+    3. **Expands dimensions** to include a single 'time' coordinate, preparing the
+       Dataset for concatenation.
+
+    EPOCH can output variables at different intervals, so some SDF files
+    may not contain the requested variable. We combine this data into one
+    dataset by concatenating across the time dimension.
+
+    The combination is performed using ``join="outer"`` (in the calling ``open_mfdataset`` function),
+    meaning that the final combined dataset will contain the variable across the
+    entire time span, with NaNs filling the time steps where the variable was absent in
+    the individual file.
+
+    With large SDF files, this filtering method will save on memory consumption when
+    compared to loading all variables from all files before concatenation.
 
-    def __init__(self):
+    Parameters
+    ----------
+    data_vars :
+        A list of data variables to load in (If not specified loads
+        in all variables)
+    """
+
+    def __init__(
+        self,
+        data_vars: list[str] | None = None,
+    ):
         self.job_id: int | None = None
+        self.data_vars = data_vars
 
     def __call__(self, ds: xr.Dataset) -> xr.Dataset:
         if self.job_id is None:
@@ -450,17 +622,23 @@ class SDFPreprocess:
                 f"Mismatching job ids (got {ds.attrs['jobid1']}, expected {self.job_id})"
             )
 
-        ds = ds.expand_dims(time=[ds.attrs["time"]])
+        # If the user has exclusively requested only certain variables be
+        # loaded in then we purge all other variables and coordinates
+        if self.data_vars:
+            ds = purge_unselected_data_vars(ds, self.data_vars)
+
+        time_val = ds.attrs.get("time", np.nan)
+        ds = ds.expand_dims(time=[time_val])
         ds = ds.assign_coords(
             time=(
                 "time",
-                [ds.attrs["time"]],
+                [time_val],
                 {"units": "s", "long_name": "Time", "full_name": "time"},
             )
         )
         # Particles' spartial coordinates also evolve in time
         for coord, value in ds.coords.items():
             if value.attrs.get("point_data", False):
-                ds.coords[coord] = value.expand_dims(time=[ds.attrs["time"]])
+                ds.coords[coord] = value.expand_dims(time=[time_val])
 
         return ds

sdf_xarray/_version.py

@@ -1,16 +1,34 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
 else:
     VERSION_TUPLE = object
+    COMMIT_ID = object
 
 version: str
 __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.3.2'
+__version_tuple__ = version_tuple = (0, 3, 2)
 
-__version__ = version = '0.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__commit_id__ = commit_id = 'g331520e50'

sdf_xarray/dataset_accessor.py

@@ -0,0 +1,73 @@
+from typing import Union
+
+import xarray as xr
+
+
+@xr.register_dataset_accessor("epoch")
+class EpochAccessor:
+    def __init__(self, xarray_obj: xr.Dataset):
+        # The xarray object is the Dataset, which we store as self._ds
+        self._ds = xarray_obj
+
+    def rescale_coords(
+        self,
+        multiplier: float,
+        unit_label: str,
+        coord_names: Union[str, list[str]],
+    ) -> xr.Dataset:
+        """
+        Rescales specified X and Y coordinates in the Dataset by a given multiplier
+        and updates the unit label attribute.
+
+        Parameters
+        ----------
+        multiplier : float
+            The factor by which to multiply the coordinate values (e.g., 1e6 for meters to microns).
+        unit_label : str
+            The new unit label for the coordinates (e.g., "µm").
+        coord_names : str or list of str
+            The name(s) of the coordinate variable(s) to rescale.
+            If a string, only that coordinate is rescaled.
+            If a list, all listed coordinates are rescaled.
+
+        Returns
+        -------
+        xr.Dataset
+            A new Dataset with the updated and rescaled coordinates.
+
+        Examples
+        --------
+        # Convert X, Y, and Z from meters to microns
+        >>> ds_in_microns = ds.epoch.rescale_coords(1e6, "µm", coord_names=["X_Grid", "Y_Grid", "Z_Grid"])
+
+        # Convert only X to millimeters
+        >>> ds_in_mm = ds.epoch.rescale_coords(1000, "mm", coord_names="X_Grid")
+        """
+
+        ds = self._ds
+        new_coords = {}
+
+        if isinstance(coord_names, str):
+            # Convert single string to a list
+            coords_to_process = [coord_names]
+        elif isinstance(coord_names, list):
+            # Use the provided list
+            coords_to_process = coord_names
+        else:
+            coords_to_process = list(coord_names)
+
+        for coord_name in coords_to_process:
+            if coord_name not in ds.coords:
+                raise ValueError(
+                    f"Coordinate '{coord_name}' not found in the Dataset. Cannot rescale."
+                )
+
+            coord_original = ds[coord_name]
+
+            coord_rescaled = coord_original * multiplier
+            coord_rescaled.attrs = coord_original.attrs.copy()
+            coord_rescaled.attrs["units"] = unit_label
+
+            new_coords[coord_name] = coord_rescaled
+
+        return ds.assign_coords(new_coords)

sdf_xarray/plotting.py

@@ -10,60 +10,82 @@ if TYPE_CHECKING:
     from matplotlib.animation import FuncAnimation
 
 
-def get_frame_title(data: xr.DataArray, frame: int, display_sdf_name: bool) -> str:
+def get_frame_title(
+    data: xr.DataArray,
+    frame: int,
+    display_sdf_name: bool = False,
+    title_custom: str | None = None,
+) -> str:
     """Generate the title for a frame"""
-    sdf_name = f", {frame:04d}.sdf" if display_sdf_name else ""
+    # Adds custom text to the start of the title, if specified
+    title_custom = "" if title_custom is None else f"{title_custom}, "
+    # Adds the time and associated units to the title
     time = data["time"][frame].to_numpy()
-    return f"t = {time:.2e}s{sdf_name}"
 
+    time_units = data["time"].attrs.get("units", False)
+    time_units_formatted = f" [{time_units}]" if time_units else ""
+    title_time = f"time = {time:.2e}{time_units_formatted}"
 
-def calculate_window_velocity_and_edges(
-    data: xr.DataArray, x_axis_coord: str
-) -> tuple[float, tuple[float, float], np.ndarray]:
-    """Calculate the moving window's velocity and initial edges.
+    # Adds sdf name to the title, if specifed
+    title_sdf = f", {frame:04d}.sdf" if display_sdf_name else ""
+    return f"{title_custom}{title_time}{title_sdf}"
 
-    1. Finds a lineout of the target atribute in the x coordinate of the first frame
-    2. Removes the NaN values to isolate the simulation window
-    3. Produces the index size of the window, indexed at zero
-    4. Uses distance moved and final time of the simulation to calculate velocity and initial xlims
-    """
-    time_since_start = data["time"].values - data["time"].values[0]
-    initial_window_edge = (0, 0)
-    target_lineout = data.values[0, :, 0]
-    target_lineout_window = target_lineout[~np.isnan(target_lineout)]
-    x_grid = data[x_axis_coord].values
-    window_size_index = target_lineout_window.size - 1
 
-    velocity_window = (x_grid[-1] - x_grid[window_size_index]) / time_since_start[-1]
-    initial_window_edge = (x_grid[0], x_grid[window_size_index])
-    return velocity_window, initial_window_edge, time_since_start
+def calculate_window_boundaries(
+    data: xr.DataArray, xlim: tuple[float, float] | False = False
+) -> np.ndarray:
+    """Calculate the bounderies a moving window frame. If the user specifies xlim, this will
+    be used as the initial bounderies and the window will move along acordingly.
+    """
+    x_grid = data["X_Grid_mid"].values
+    x_half_cell = (x_grid[1] - x_grid[0]) / 2
+    N_frames = data["time"].size
 
+    # Find the window bounderies by finding the first and last non-NaN values in the 0th lineout
+    # along the x-axis.
+    window_boundaries = np.zeros((N_frames, 2))
+    for i in range(N_frames):
+        # Check if data is 1D
+        if data.ndim == 2:
+            target_lineout = data[i].values
+        # Check if data is 2D
+        if data.ndim == 3:
+            target_lineout = data[i, :, 0].values
+        x_grid_non_nan = x_grid[~np.isnan(target_lineout)]
+        window_boundaries[i, 0] = x_grid_non_nan[0] - x_half_cell
+        window_boundaries[i, 1] = x_grid_non_nan[-1] + x_half_cell
 
-def compute_global_limits(data: xr.DataArray) -> tuple[float, float]:
-    """Remove all NaN values from the target data to calculate the 1st and 99th percentiles,
-    excluding extreme outliers.
-    """
-    values_no_nan = data.values[~np.isnan(data.values)]
-    global_min = np.percentile(values_no_nan, 1)
-    global_max = np.percentile(values_no_nan, 99)
-    return global_min, global_max
+    # User's choice for initial window edge supercides the one calculated
+    if xlim:
+        window_boundaries = window_boundaries + xlim - window_boundaries[0]
+    return window_boundaries
 
 
-def is_1d(data: xr.DataArray) -> bool:
-    """Check if the data is 1D."""
-    return len(data.shape) == 2
+def compute_global_limits(
+    data: xr.DataArray,
+    min_percentile: float = 0,
+    max_percentile: float = 100,
+) -> tuple[float, float]:
+    """Remove all NaN values from the target data to calculate the global minimum and maximum of the data.
+    User defined percentiles can remove extreme outliers.
+    """
 
+    # Removes NaN values, needed for moving windows
+    values_no_nan = data.values[~np.isnan(data.values)]
 
-def is_2d(data: xr.DataArray) -> bool:
-    """Check if the data is 2D or 3D."""
-    return len(data.shape) == 3
+    # Finds the global minimum and maximum of the plot, based on the percentile of the data
+    global_min = np.percentile(values_no_nan, min_percentile)
+    global_max = np.percentile(values_no_nan, max_percentile)
+    return global_min, global_max
 
 
-def generate_animation(
+def animate(
     data: xr.DataArray,
+    fps: float = 10,
+    min_percentile: float = 0,
+    max_percentile: float = 100,
+    title: str | None = None,
     display_sdf_name: bool = False,
-    fps: int = 10,
-    move_window: bool = False,
     ax: plt.Axes | None = None,
     **kwargs,
 ) -> FuncAnimation:
@@ -71,17 +93,18 @@ def generate_animation(
 
     Parameters
     ---------
-    dataset
-        The dataset containing the simulation data
-    target_attribute
-        The attribute to plot for each timestep
-    display_sdf_name
-        Display the sdf file name in the animation title
+    data
+        The dataarray containing the target data
     fps
         Frames per second for the animation (default: 10)
-    move_window
-        If the simulation has a moving window, the animation will move along
-        with it (default: False)
+    min_percentile
+        Minimum percentile of the data (default: 0)
+    max_percentile
+        Maximum percentile of the data (default: 100)
+    title
+        Custom title to add to the plot.
+    display_sdf_name
+        Display the sdf file name in the animation title
     ax
         Matplotlib axes on which to plot.
     kwargs
@@ -89,18 +112,28 @@ def generate_animation(
 
     Examples
     --------
-    >>> generate_animation(dataset["Derived_Number_Density_Electron"])
+    >>> dataset["Derived_Number_Density_Electron"].epoch.animate()
     """
-    import matplotlib.pyplot as plt
-    from matplotlib.animation import FuncAnimation
+    import matplotlib.pyplot as plt  # noqa: PLC0415
+    from matplotlib.animation import FuncAnimation  # noqa: PLC0415
+
+    kwargs_original = kwargs.copy()
 
     if ax is None:
         _, ax = plt.subplots()
 
     N_frames = data["time"].size
-    global_min, global_max = compute_global_limits(data)
+    global_min, global_max = compute_global_limits(data, min_percentile, max_percentile)
 
-    if is_2d(data):
+    # Initialise plot and set y-limits for 1D data
+    if data.ndim == 2:
+        kwargs.setdefault("x", "X_Grid_mid")
+        plot = data.isel(time=0).plot(ax=ax, **kwargs)
+        ax.set_title(get_frame_title(data, 0, display_sdf_name, title))
+        ax.set_ylim(global_min, global_max)
+
+    # Initilise plot and set colour bar for 2D data
+    if data.ndim == 3:
         kwargs["norm"] = plt.Normalize(vmin=global_min, vmax=global_max)
         kwargs["add_colorbar"] = False
         # Set default x and y coordinates for 2D data if not provided
@@ -109,44 +142,32 @@ def generate_animation(
 
         # Initialize the plot with the first timestep
         plot = data.isel(time=0).plot(ax=ax, **kwargs)
-        ax.set_title(get_frame_title(data, 0, display_sdf_name))
+        ax.set_title(get_frame_title(data, 0, display_sdf_name, title))
 
         # Add colorbar
-        long_name = data.attrs.get("long_name")
-        units = data.attrs.get("units")
-        plt.colorbar(plot, ax=ax, label=f"{long_name} [${units}$]")
-
-    # Initialise plo and set y-limits for 1D data
-    if is_1d(data):
-        plot = data.isel(time=0).plot(ax=ax, **kwargs)
-        ax.set_title(get_frame_title(data, 0, display_sdf_name))
-        ax.set_ylim(global_min, global_max)
+        if kwargs_original.get("add_colorbar", True):
+            long_name = data.attrs.get("long_name")
+            units = data.attrs.get("units")
+            plt.colorbar(plot, ax=ax, label=f"{long_name} [${units}$]")
 
+    # check if there is a moving window by finding NaNs in the data
+    move_window = np.isnan(np.sum(data.values))
     if move_window:
-        window_velocity, window_initial_edge, time_since_start = (
-            calculate_window_velocity_and_edges(data, kwargs["x"])
-        )
-
-    # User's choice for initial window edge supercides the one calculated
-    if "xlim" in kwargs:
-        window_initial_edge = kwargs["xlim"]
+        window_boundaries = calculate_window_boundaries(data, kwargs.get("xlim", False))
 
     def update(frame):
         # Set the xlim for each frame in the case of a moving window
         if move_window:
-            kwargs["xlim"] = (
-                window_initial_edge[0] + window_velocity * time_since_start[frame],
-                window_initial_edge[1] * 0.99
-                + window_velocity * time_since_start[frame],
-            )
+            kwargs["xlim"] = window_boundaries[frame]
 
         # Update plot for the new frame
         ax.clear()
+
         data.isel(time=frame).plot(ax=ax, **kwargs)
-        ax.set_title(get_frame_title(data, frame, display_sdf_name))
+        ax.set_title(get_frame_title(data, frame, display_sdf_name, title))
 
-        # # Update y-limits for 1D data
-        if is_1d(data):
+        # Update y-limits for 1D data
+        if data.ndim == 2:
             ax.set_ylim(global_min, global_max)
 
     return FuncAnimation(
@@ -181,4 +202,4 @@ class EpochAccessor:
         >>> ani = ds["Electric_Field_Ey"].epoch.animate()
         >>> ani.save("myfile.mp4")
         """
-        return generate_animation(self._obj, *args, **kwargs)
+        return animate(self._obj, *args, **kwargs)

sdf_xarray/sdf_interface.pyx

@@ -39,7 +39,7 @@ cdef class Block:
 
 @dataclasses.dataclass
 cdef class Variable(Block):
-    units: tuple[str] | None
+    units: str | None
     mult: float | None
     grid: str | None
     grid_mid: str | None

sdf_xarray-0.3.2.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: sdf-xarray
+Version: 0.3.2
+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>
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+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
+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"
+Provides-Extra: pint
+Requires-Dist: pint; extra == "pint"
+Requires-Dist: pint-xarray; extra == "pint"
+Description-Content-Type: text/markdown
+
+# sdf-xarray
+
+![Dynamic TOML Badge](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fepochpic%2Fsdf-xarray%2Frefs%2Fheads%2Fmain%2Fpyproject.toml&query=%24.project.requires-python&label=python&logo=python)
+[![Available on PyPI](https://img.shields.io/pypi/v/sdf-xarray?color=blue&logo=pypi)](https://pypi.org/project/sdf-xarray/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15351323.svg)](https://doi.org/10.5281/zenodo.15351323)
+![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)
+
+
+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).
+
+> [!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:
+
+```bash
+git clone https://github.com/epochpic/sdf-xarray.git
+cd sdf-xarray
+pip install .
+```
+
+We recommend switching to [uv](https://docs.astral.sh/uv/) to manage packages.
+
+## Usage
+
+### Single file loading
+
+```python
+import xarray as xr
+
+df = xr.open_dataset("0010.sdf")
+
+print(df["Electric_Field_Ex"])
+
+# <xarray.DataArray 'Electric_Field_Ex' (X_x_px_deltaf_electron_beam: 16)> Size: 128B
+# [16 values with dtype=float64]
+# Coordinates:
+#   * X_x_px_deltaf_electron_beam  (X_x_px_deltaf_electron_beam) float64 128B 1...
+# Attributes:
+#     units:    V/m
+#     full_name: "Electric Field/Ex"
+```
+
+### Multi-file loading
+
+To open a whole simulation at once, pass `preprocess=sdf_xarray.SDFPreprocess()`
+to `xarray.open_mfdataset`:
+
+```python
+import xarray as xr
+from sdf_xarray import SDFPreprocess
+
+with xr.open_mfdataset("*.sdf", preprocess=SDFPreprocess()) as ds:
+    print(ds)
+
+# Dimensions:
+# time: 301, X_Grid_mid: 128, ...
+# Coordinates: (9) ...
+# Data variables: (18) ...
+# Indexes: (9) ...
+# 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.
+
+## Contributing
+
+We welcome contributions to the BEAM ecosystem! Whether it's reporting issues, suggesting features, or submitting pull requests, your input helps improve these tools for the community.
+
+### How to Contribute
+
+There are many ways to get involved:
+- **Report bugs**: Found something not working as expected? Open an issue with as much detail as possible.
+- **Request a feature**: Got an idea for a new feature or enhancement? Open a feature request on [GitHub Issues](https://github.com/epochpic/sdf-xarray/issues)!
+- **Improve the documentation**: We aim to keep our docs clear and helpful—if something's missing or unclear, feel free to suggest edits.
+- **Submit code changes**: Bug fixes, refactoring, or new features are welcome.
+
+
+All code is automatically linted, formatted, and tested via GitHub Actions.
+
+To run checks locally before opening a pull request, see [CONTRIBUTING.md](CONTRIBUTING.md) or [readthedocs documentation](https://sdf-xarray.readthedocs.io/en/latest/contributing.html)
+
+## Broad EPOCH Analysis Modules (BEAM)
+
+![BEAM logo](./BEAM.png)
+
+**BEAM** is a collection of independent yet complementary open-source tools for analysing EPOCH simulations, designed to be modular so researchers can adopt only the components they require without being constrained by a rigid framework. In line with the **FAIR principles — Findable**, **Accessible**, **Interoperable**, and **Reusable** — each package is openly published with clear documentation and versioning (Findable), distributed via public repositories (Accessible), designed to follow common standards for data structures and interfaces (Interoperable), and includes licensing and metadata to support long-term use and adaptation (Reusable). The packages are as follows:
+
+- [sdf-xarray](https://github.com/epochpic/sdf-xarray): Reading and processing SDF files and converting them to [xarray](https://docs.xarray.dev/en/stable/).
+- [epydeck](https://github.com/epochpic/epydeck): Input deck reader and writer.
+- [epyscan](https://github.com/epochpic/epyscan): Create campaigns over a given parameter space using various sampling methods.
+
+## PlasmaFAIR
+
+![PlasmaFAIR logo](PlasmaFAIR.svg)
+
+Originally developed by [PlasmaFAIR](https://plasmafair.github.io), EPSRC Grant EP/V051822/1

{sdf_xarray-0.2.0.dist-info → sdf_xarray-0.3.2.dist-info}/RECORD

@@ -6,19 +6,20 @@ include/SDFC_14.4.7/sdf_list_type.h,sha256=Quu8v0-SEsQuJpGtEZnm09tAyXqWNitx0sXl5
 include/SDFC_14.4.7/sdf_vector_type.h,sha256=dbKjhzRRsvhzrnTwVjtVlvnuisEnRMKY-vvdm94ok_Q,1595
 include/SDFC_14.4.7/stack_allocator.h,sha256=L7U9vmGiVSw3VQLIv9EzTaVq7JbFxs9aNonKStTkUSg,1335
 include/SDFC_14.4.7/uthash.h,sha256=rIyy_-ylY6S_7WaZCCC3VtvXaC9q37rFyA0f1U9xc4w,63030
-lib/SDFC_14.4.7/sdfc.lib,sha256=gjj_61MNoqCeyyxSisEd89aC23ZU86x-exBgcxWimy8,350320
+lib/SDFC_14.4.7/sdfc.lib,sha256=VyuxkhB3q8QOeICxMhp3a7jpi7GXvHRmIwFKCSHSyrA,350158
 lib/SDFC_14.4.7/SDFCConfig.cmake,sha256=IOA1eusC-KvUK4LNTEiOAmEdaPH1ZvNvbYPgiG1oZio,802
 lib/SDFC_14.4.7/SDFCConfigVersion.cmake,sha256=pN7Qqyf04s3izw7PYQ0XK6imvmhaVegSdR_nEl3Ok_o,2830
 lib/SDFC_14.4.7/SDFCTargets-release.cmake,sha256=G4zdx5PyjePigeD_a6rmZAxbk7L8Nf0klUnV78Lm2fI,828
 lib/SDFC_14.4.7/SDFCTargets.cmake,sha256=OVt1Gm8n7Ew4fiTmA9yHoef3vIIGwsXUZfqeG9p9Bys,4152
-sdf_xarray/__init__.py,sha256=VASjtRYa7gd6oSPgtpMhJhCNMeMI_WUby904ETEyMpM,17435
-sdf_xarray/_version.py,sha256=dwm-k_Z-jVJh3XvUUihA4YH_iqS5EfkubVd6suUFZB0,427
+sdf_xarray/__init__.py,sha256=obgAD4Aecvvpd8GkxLIAiIagSaY0bFVP2Q397N48_5g,24201
+sdf_xarray/_version.py,sha256=bmLiJYnZTISDv_NDGANk6QDMSY0XTk0CwXXKhbOvW3Y,746
 sdf_xarray/csdf.pxd,sha256=ADPjAuHsodAvdOz96Z_XlFF7VL3KmVaXcTifWDP3rK0,4205
-sdf_xarray/plotting.py,sha256=pCKZ01sAT0VLEhnWrX6LN5OSJnzcIkRA3joN7f62giM,6238
-sdf_xarray/sdf_interface.cp312-win_amd64.pyd,sha256=zSdMTuvmOMVx3ao-nxQnsP4PVYGNEqHzHzvo9cQSAsQ,379392
-sdf_xarray/sdf_interface.pyx,sha256=3XRFlrC1e_HkJrU8-i3fMz8DlyUxZgt9wTx_QkGE_TQ,11982
-sdf_xarray-0.2.0.dist-info/METADATA,sha256=G0TiE2vkUccaBSwRMM56Pj82xDCdDm9ngpfbTNNAFhw,6589
-sdf_xarray-0.2.0.dist-info/WHEEL,sha256=GgB_RydHGtp7zP9kXrVRu7kuGtdM7WtO3JhH95Vv87o,106
-sdf_xarray-0.2.0.dist-info/entry_points.txt,sha256=gP7BIQpXNg6vIf7S7p-Rw_EJZTC1X50BsVTkK7dA7g0,57
-sdf_xarray-0.2.0.dist-info/licenses/LICENCE,sha256=dsqtZx65gUc4vyNA4JKHTelIFuzWf-HVNi0h1c-lXNI,1517
-sdf_xarray-0.2.0.dist-info/RECORD,,
+sdf_xarray/dataset_accessor.py,sha256=TvnVMBefnT1d94Bkllhd-__O3ittzpaVjZKfze-3WQ4,2484
+sdf_xarray/plotting.py,sha256=PnbEspR4XkA5SHkpoFKA2G7BYj5J3mVgR1TEeGol6Vw,7041
+sdf_xarray/sdf_interface.cp312-win_amd64.pyd,sha256=08xrwtYkgFqyN5GCr4sV5QP3g0mOozAPMg1DCVAqZm8,360960
+sdf_xarray/sdf_interface.pyx,sha256=PFC6upg14OZBqiGInLgBoxztIIKBk-HOh3WC9Ro4YUw,11975
+sdf_xarray-0.3.2.dist-info/METADATA,sha256=xvADFsOdsd5EzaZbVYGOUgmEMe4RzrTDF9IbyijadqE,7624
+sdf_xarray-0.3.2.dist-info/WHEEL,sha256=chqeLhPBtPdrOoreR34YMcofSk3yWDQhkrsDJ2n48LU,106
+sdf_xarray-0.3.2.dist-info/entry_points.txt,sha256=gP7BIQpXNg6vIf7S7p-Rw_EJZTC1X50BsVTkK7dA7g0,57
+sdf_xarray-0.3.2.dist-info/licenses/LICENCE,sha256=aHWuyELjtzIL1jTXFHTbI3tr9vyVyhnw3I9_QYPdEX8,1515
+sdf_xarray-0.3.2.dist-info/RECORD,,

{sdf_xarray-0.2.0.dist-info → sdf_xarray-0.3.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: scikit-build-core 0.10.7
+Generator: scikit-build-core 0.11.6
 Root-Is-Purelib: false
 Tag: cp312-cp312-win_amd64
 

{sdf_xarray-0.2.0.dist-info → sdf_xarray-0.3.2.dist-info}/licenses/LICENCE

@@ -1,4 +1,4 @@
-Copyright 2024, Peter Hill, Joel Adams, PlasmaFAIR team
+Copyright 2024, Peter Hill, Joel Adams, epochpic team
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are

sdf_xarray-0.2.0.dist-info/METADATA

@@ -1,190 +0,0 @@
-Metadata-Version: 2.1
-Name: sdf-xarray
-Version: 0.2.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>
-License: Copyright 2024, Peter Hill, Joel Adams, PlasmaFAIR team
-        
-        Redistribution and use in source and binary forms, with or without
-        modification, are permitted provided that the following conditions are
-        met:
-        
-        1. Redistributions of source code must retain the above copyright
-        notice, this list of conditions and the following disclaimer.
-        
-        2. Redistributions in binary form must reproduce the above copyright
-        notice, this list of conditions and the following disclaimer in the
-        documentation and/or other materials provided with the distribution.
-        
-        3. Neither the name of the copyright holder nor the names of its
-        contributors may be used to endorse or promote products derived from
-        this software without specific prior written permission.
-        
-        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-        “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-        LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-        A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-        HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-        SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-        LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-        DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-        THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-Requires-Python: >=3.10
-Requires-Dist: numpy>=2.0.0
-Requires-Dist: xarray>=2024.1.0
-Requires-Dist: dask>=2024.7.1
-Requires-Dist: cython>=3.0
-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: pytest>=3.3.0; extra == "test"
-Requires-Dist: dask[complete]; extra == "test"
-Requires-Dist: ruff; extra == "lint"
-Requires-Dist: cibuildwheel[uv]; extra == "build"
-Requires-Dist: dask[diagnostics]; extra == "jupyter"
-Requires-Dist: ipykernel>=6.29.5; extra == "jupyter"
-Provides-Extra: docs
-Provides-Extra: test
-Provides-Extra: lint
-Provides-Extra: build
-Provides-Extra: jupyter
-Description-Content-Type: text/markdown
-
-# sdf-xarray
-
-![PyPI](https://img.shields.io/pypi/v/sdf-xarray?color=blue)
-![Build/Publish](https://github.com/PlasmaFAIR/sdf-xarray/actions/workflows/build_publish.yml/badge.svg)
-![Tests](https://github.com/PlasmaFAIR/sdf-xarray/actions/workflows/tests.yml/badge.svg)
-
-`sdf-xarray` provides a backend for [xarray](https://xarray.dev) to
-read SDF files as created by the [EPOCH](https://epochpic.github.io)
-plasma PIC code using the [SDF-C](https://github.com/Warwick-Plasma/SDF_C) library.
-
-## 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:
-
-```bash
-git clone https://github.com/PlasmaFAIR/sdf-xarray.git
-cd sdf-xarray
-pip install .
-```
-
-We recommend switching to [uv](https://docs.astral.sh/uv/) to manage packages.
-
-## Usage
-
-For more in depth documentation please visit  <https://sdf-xarray.readthedocs.io/>
-
-`sdf-xarray` is a backend for xarray, and so is usable directly from
-xarray:
-
-### Single file loading
-
-```python
-import xarray as xr
-
-df = xr.open_dataset("0010.sdf")
-
-print(df["Electric_Field_Ex"])
-
-# <xarray.DataArray 'Electric_Field_Ex' (X_x_px_deltaf_electron_beam: 16)> Size: 128B
-# [16 values with dtype=float64]
-# Coordinates:
-#   * X_x_px_deltaf_electron_beam  (X_x_px_deltaf_electron_beam) float64 128B 1...
-# Attributes:
-#     units:    V/m
-#     full_name: "Electric Field/Ex"
-```
-
-To open a whole simulation at once, pass `preprocess=sdf_xarray.SDFPreprocess()`
-to `xarray.open_mfdataset`:
-
-```python
-import xarray as xr
-from sdf_xarray import SDFPreprocess
-
-with xr.open_mfdataset("*.sdf", preprocess=SDFPreprocess()) as ds:
-    print(ds)
-
-# Dimensions:
-# time: 301, X_Grid_mid: 128, ...
-# Coordinates: (9) ...
-# Data variables: (18) ...
-# Indexes: (9) ...
-# 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.
-
-Alternatively, we can create a separate time dimensions for each `output` block
-(essentially) using `sdf_xarray.open_mfdataset` with `separate_times=True`:
-
-```python
-from sdf_xarray import open_mfdataset
-
-with open_mfdataset("*.sdf", separate_times=True) as ds:
-    print(ds)
-
-# Dimensions:
-# time0: 301, time1: 31, time2: 61, X_Grid_mid: 128, ...
-# Coordinates: (12) ...
-# Data variables: (18) ...
-# Indexes: (9) ...
-# Attributes: (22) ...
-```
-
-This is better for memory consumption, at the cost of perhaps slightly less
-friendly comparisons between variables on different time coordinates.
-
-### Reading particle data
-
-By default, particle data isn't kept as it takes up a lot of space. Pass
-`keep_particles=True` as a keyword argument to `open_dataset` (for single files)
-or `open_mfdataset` (for multiple files):
-
-```python
-df = xr.open_dataset("0010.sdf", keep_particles=True)
-```
-
-### Loading SDF files directly
-
-For debugging, sometimes it's useful to see the raw SDF files:
-
-```python
-from sdf_xarray import SDFFile
-
-with SDFFile("0010.sdf") as sdf_file:
-    print(sdf_file.variables["Electric Field/Ex"])
-
-    # Variable(_id='ex', name='Electric Field/Ex', dtype=dtype('float64'), ...
-
-    print(sdf_file.variables["Electric Field/Ex"].data)
-
-    # [ 0.00000000e+00  0.00000000e+00  0.00000000e+00 ... -4.44992788e+12  1.91704994e+13  0.00000000e+00]
-```