sdf-xarray 0.2.2__tar.gz → 0.2.4__tar.gz

{sdf_xarray-0.2.2 → sdf_xarray-0.2.4}/CITATION.cff

@@ -16,4 +16,5 @@ authors:
     given-names: Shaun
     orcid: 'https://orcid.org/0009-0005-0693-030X'
     affiliation: University of York
+doi: 10.5281/zenodo.15351323
 date-released: '2024-07-25'

{sdf_xarray-0.2.2 → sdf_xarray-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: sdf-xarray
-Version: 0.2.2
+Version: 0.2.4
 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, epochpic team
@@ -32,11 +32,19 @@ License: Copyright 2024, Peter Hill, Joel Adams, epochpic team
          (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
          OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
          
+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: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Operating System :: OS Independent
 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
 Provides-Extra: docs
 Requires-Dist: sphinx>=5.3; extra == "docs"
 Requires-Dist: sphinx_autodoc_typehints>=1.19; extra == "docs"
@@ -67,9 +75,14 @@ Description-Content-Type: text/markdown
 
 # sdf-xarray
 
-![PyPI](https://img.shields.io/pypi/v/sdf-xarray?color=blue)
+![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.

{sdf_xarray-0.2.2 → sdf_xarray-0.2.4}/README.md

@@ -1,8 +1,13 @@
 # sdf-xarray
 
-![PyPI](https://img.shields.io/pypi/v/sdf-xarray?color=blue)
+![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.

{sdf_xarray-0.2.2 → sdf_xarray-0.2.4}/docs/getting_started.rst

@@ -25,7 +25,14 @@ Usage
 -----
 
 ``sdf-xarray`` is a backend for xarray, and so is usable directly from
-`xarray`.
+`xarray`. There are several ways to load SDF files:
+
+- To load a single file, use :func:`xarray.open_dataset`.
+- To load multiple files, use :func:`xarray.open_mfdataset` or :func:`sdf_xarray.open_mfdataset`.
+- To access the raw contents of a single SDF file, use :func:`sdf_xarray.sdf_interface.SDFFile`.
+
+.. note::
+   When loading ``*.sdf`` files, variables related to ``boundaries``, ``cpu`` and ``output file`` are excluded as they are problematic.
 
 Single file loading
 ~~~~~~~~~~~~~~~~~~~

{sdf_xarray-0.2.2 → sdf_xarray-0.2.4}/docs/key_functionality.rst

@@ -13,11 +13,14 @@ Key Functionality
 
 Loading SDF Files
 -----------------
-There are several ways to load in SDF files using ``sdf-xarray``.
-You can load in a single file using :func:`xarray.open_dataset`,
-load in multiple files using :func:`xarray.open_mfdataset` or
-:func:`sdf_xarray.open_mfdataset`, or load in a single raw SDF file
-using :func:`sdf_xarray.sdf_interface.SDFFile`.
+There are several ways to load SDF files:
+
+- To load a single file, use :func:`xarray.open_dataset`.
+- To load multiple files, use :func:`xarray.open_mfdataset` or :func:`sdf_xarray.open_mfdataset`.
+- To access the raw contents of a single SDF file, use :func:`sdf_xarray.sdf_interface.SDFFile`.
+
+.. note::
+   When loading ``*.sdf`` files, variables related to ``boundaries``, ``cpu`` and ``output file`` are excluded as they are problematic.
 
 Loading a Single SDF File
 ~~~~~~~~~~~~~~~~~~~~~~~~~

{sdf_xarray-0.2.2 → sdf_xarray-0.2.4}/pyproject.toml

@@ -3,7 +3,7 @@ requires = [
   "scikit-build-core>=0.3",
   "setuptools_scm",
   "numpy>=2.0.0",
-  "cython>=3.0",
+  "cython~=3.0",
 ]
 build-backend = "scikit_build_core.build"
 
@@ -22,9 +22,19 @@ dependencies = [
   "numpy>=2.0.0",
   "xarray>=2024.1.0",
   "dask>=2024.7.1",
-  "cython>=3.0",
 ]
 description = "Provides a backend for xarray to read SDF files as created by the EPOCH plasma PIC code."
+classifiers = [
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering",
+  "Operating System :: OS Independent",
+]
 
 [project.optional-dependencies]
 docs = [
@@ -94,4 +104,5 @@ extend-select = [
 ignore = [
   "PLR2004", # magic-comparison
   "B9",      # flake8-bugbear opinionated warnings
+  "PLR0913", # remove maximum number of arguments in a function
 ]

{sdf_xarray-0.2.2 → sdf_xarray-0.2.4}/src/sdf_xarray/__init__.py

@@ -310,6 +310,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
 

{sdf_xarray-0.2.2 → sdf_xarray-0.2.4}/src/sdf_xarray/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.2.2'
-__version_tuple__ = version_tuple = (0, 2, 2)
+__version__ = version = '0.2.4'
+__version_tuple__ = version_tuple = (0, 2, 4)

sdf_xarray-0.2.4/src/sdf_xarray/plotting.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import xarray as xr
+
+if TYPE_CHECKING:
+    import matplotlib.pyplot as plt
+    from matplotlib.animation import FuncAnimation
+
+
+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"""
+    # 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()
+
+    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}"
+
+    # 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}"
+
+
+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
+
+    # 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 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)]
+
+    # 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 animate(
+    data: xr.DataArray,
+    fps: float = 10,
+    min_percentile: float = 0,
+    max_percentile: float = 100,
+    title: str | None = None,
+    display_sdf_name: bool = False,
+    ax: plt.Axes | None = None,
+    **kwargs,
+) -> FuncAnimation:
+    """Generate an animation
+
+    Parameters
+    ---------
+    data
+        The dataarray containing the target data
+    fps
+        Frames per second for the animation (default: 10)
+    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
+        Keyword arguments to be passed to matplotlib.
+
+    Examples
+    --------
+    >>> dataset["Derived_Number_Density_Electron"].epoch.animate()
+    """
+    import matplotlib.pyplot as plt
+    from matplotlib.animation import FuncAnimation
+
+    kwargs_original = kwargs.copy()
+
+    if ax is None:
+        _, ax = plt.subplots()
+
+    N_frames = data["time"].size
+    global_min, global_max = compute_global_limits(data, min_percentile, max_percentile)
+
+    # 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
+        kwargs.setdefault("x", "X_Grid_mid")
+        kwargs.setdefault("y", "Y_Grid_mid")
+
+        # 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, title))
+
+        # Add colorbar
+        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_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_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, title))
+
+        # Update y-limits for 1D data
+        if data.ndim == 2:
+            ax.set_ylim(global_min, global_max)
+
+    return FuncAnimation(
+        ax.get_figure(),
+        update,
+        frames=range(N_frames),
+        interval=1000 / fps,
+        repeat=True,
+    )
+
+
+@xr.register_dataarray_accessor("epoch")
+class EpochAccessor:
+    def __init__(self, xarray_obj):
+        self._obj = xarray_obj
+
+    def animate(self, *args, **kwargs) -> FuncAnimation:
+        """Generate animations of Epoch data.
+
+        Parameters
+        ----------
+        args
+            Positional arguments passed to :func:`generate_animation`.
+        kwargs
+            Keyword arguments passed to :func:`generate_animation`.
+
+        Examples
+        --------
+        >>> import xarray as xr
+        >>> from sdf_xarray import SDFPreprocess
+        >>> ds = xr.open_mfdataset("*.sdf", preprocess=SDFPreprocess())
+        >>> ani = ds["Electric_Field_Ey"].epoch.animate()
+        >>> ani.save("myfile.mp4")
+        """
+        return animate(self._obj, *args, **kwargs)

{sdf_xarray-0.2.2 → sdf_xarray-0.2.4}/src/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.2.4/tests/example_dist_fn/input.deck

@@ -0,0 +1,154 @@
+begin:control
+
+  # global number of gridpoints
+  # Divide nx and ny by 2 from 40 to 20  
+  nx = 16 # in x
+  ny = 8
+  nparticles = nx * ny * 4
+
+  # maximum number of iterations
+  # set to -1 to run until finished
+  nsteps = -1
+
+  # final time of simulation
+  t_end = 200e-15
+
+  # size of domain
+  x_min = 0e-6
+  x_max =  40e-6
+  y_min = -10e-6
+  y_max = -y_min
+
+  dt_multiplier = 0.8
+  dlb_threshold = 0.8
+
+end:control
+
+begin:laser
+
+  boundary = x_min
+  intensity_w_cm2 = 1.0e23
+  lambda = 1e-6
+  phase = 0.0
+  t_profile = gauss(time, 40.0e-15, 30.0e-15)  # This profile means your laser pulse has a maximum intensity at t=40 fs, and the intensity will smoothly decrease as time moves away from this point, with a width parameter of 30 fs.
+  t_start = 0.0
+  t_end = end
+end:laser
+
+begin:collisions
+
+  use_collisions = T
+  coulomb_log = auto
+  collide = all
+
+end:collisions
+
+
+begin:boundaries
+
+  bc_x_min = simple_laser
+  bc_x_max = open
+  bc_y_min = periodic
+  bc_y_max = periodic
+
+end:boundaries
+
+
+begin:species
+
+  # electrons
+  name = Electron
+  fraction = 0.5
+  dump = T
+
+  temperature = 0
+  number_density = if ((x gt 10e-6) and (x lt 30e-6), 1e22, 0)
+  number_density_min = 1
+
+  identify:electron
+
+end:species
+
+
+begin:output_global
+
+  force_final_to_be_restartable = F
+
+end:output_global
+
+
+begin:output
+
+  name = normal
+
+  # If use_offset_grid is true then the code dumps a grid which displays
+  # positions relative to the left hand edge of the window
+  use_offset_grid = F
+
+  # number of timesteps between output dumps
+  dt_snapshot = 100.0e-15 # 100.0e-15 / 100.0
+
+  # Properties at particle positions
+  particles = never
+  px = never
+  py = never
+  pz = never
+  vx = never
+  vy = never
+  vz = never
+  charge = never
+  mass = never
+  particle_weight = never
+  species_id = never
+
+  # Properties on grid
+  grid = always
+  ex = never
+  ey = always
+  ez = never
+  bx = never
+  by = never
+  bz = never
+  jx = never
+  jy = never
+  jz = never
+  poynt_flux = always
+  average_particle_energy = never
+  mass_density = never
+  charge_density = never
+  number_density = never
+  temperature = never
+
+  # extended io
+  distribution_functions = always
+  particle_probes = never
+  absorption = never
+  total_energy_sum = never
+
+end:output
+
+
+begin:dist_fn
+
+  name = x_px_py
+  ndims = 3
+  dumpmask = always
+
+  direction1 = dir_x
+  direction2 = dir_px
+  direction3 = dir_py
+
+  # range is ignored for spatial coordinates
+  range1 = (1, 1)
+  range2 = (1.6e-20, 1.6e-19)
+  range3 = (1.6e-20, 1.6e-19)
+
+  # resolution is ignored for spatial coordinates
+  resolution1 = 1
+  resolution2 = 20
+  resolution3 = 20
+
+  #include_species:Photon
+  include_species:Electron
+
+end:dist_fn

sdf_xarray-0.2.4/tests/example_files_2D_moving_window/input.deck

@@ -0,0 +1,63 @@
+begin:control
+  nx = 100
+  ny = 100
+
+  # final time of simulation
+  t_end = 10e-9
+
+  # size of domain
+  x_min = 0
+  x_end = 1
+
+  y_min = 0
+  y_max = 1
+
+  stdout_frequency = 10
+end:control
+
+
+begin:boundaries
+  bc_x_min = simple_outflow
+  bc_x_max = simple_outflow
+  bc_y_min = periodic
+  bc_y_max = periodic
+end:boundaries
+
+
+begin:window
+  move_window = T
+  window_start_time = 0
+  bc_x_min_after_move = simple_outflow
+  bc_x_max_after_move = simple_outflow
+  window_v_x = 2e8
+end:window
+
+begin:constant
+  x0 = 1.31
+  y0 = 0.5
+  r0 = 0.4^2
+  r2 = (x - x0)^2 + (y - y0)^2
+end:constant
+
+begin:species
+  # electron
+  name = electron
+  charge = -1.0
+  mass = 1.0
+  nparticles_per_cell = 5
+
+  number_density = if(abs(x-x0) lt 0.3, 2, 1)
+  number_density = if(abs(y-y0) lt 0.2, number_density(electron), 1)
+
+  temperature_ev = 0
+end:species
+
+
+begin:output
+  name = normal
+  dt_snapshot = 10e-9/4
+
+  # Properties on grid
+  grid = always
+  number_density = always + species + no_sum
+end:output

{sdf_xarray-0.2.2 → sdf_xarray-0.2.4}/tests/test_basic.py

@@ -5,11 +5,12 @@ import xarray as xr
 
 from sdf_xarray import SDFPreprocess, _process_latex_name, open_mfdataset
 
-EXAMPLE_FILES_DIR = pathlib.Path(__file__).parent / "example_files"
+EXAMPLE_FILES_DIR = pathlib.Path(__file__).parent / "example_files_1D"
 EXAMPLE_MISMATCHED_FILES_DIR = (
     pathlib.Path(__file__).parent / "example_mismatched_files"
 )
 EXAMPLE_ARRAYS_DIR = pathlib.Path(__file__).parent / "example_array_no_grids"
+EXAMPLE_3D_DIST_FN = pathlib.Path(__file__).parent / "example_dist_fn"
 
 
 def test_basic():
@@ -178,3 +179,9 @@ def test_arrays_with_no_grids_multifile():
         random_states = "Random_States"
         assert random_states in df
         assert df[random_states].shape == (2, 8)
+
+
+def test_3d_distribution_function():
+    with xr.open_dataset(EXAMPLE_3D_DIST_FN / "0000.sdf") as df:
+        distribution_function = "dist_fn_x_px_py_Electron"
+        assert df[distribution_function].shape == (16, 20, 20)

{sdf_xarray-0.2.2 → sdf_xarray-0.2.4}/tests/test_cython.py

@@ -6,7 +6,7 @@ import pytest
 
 from sdf_xarray import SDFFile
 
-EXAMPLE_FILES_DIR = pathlib.Path(__file__).parent / "example_files"
+EXAMPLE_FILES_DIR = pathlib.Path(__file__).parent / "example_files_1D"
 
 
 def test_sdffile():