sdf-xarray 0.2.5__tar.gz → 0.2.6__tar.gz

{sdf_xarray-0.2.5 → sdf_xarray-0.2.6}/.github/workflows/build_publish.yml

@@ -32,7 +32,7 @@ jobs:
         uv sync --python 3.12 --extra test --extra build --frozen
 
     - name: Build
-      uses: pypa/cibuildwheel@v2.21.3
+      uses: pypa/cibuildwheel@v3.1.3
       env:
         CIBW_ARCHS_LINUX: auto
         CIBW_ARCHS_MACOS: x86_64 arm64

{sdf_xarray-0.2.5 → sdf_xarray-0.2.6}/CONTRIBUTING.md

@@ -68,6 +68,12 @@ pip install "sdf-xarray[docs]"
 cd docs
 make html
 ```
+
+The documentation can be updated by changing any of the `*.rst` files located
+in the main `docs` directory. The existing documentation hopefully includes most
+of the snippets you'd need to write or update it, however if you are stuck
+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.
 

{sdf_xarray-0.2.5 → sdf_xarray-0.2.6}/PKG-INFO

@@ -1,47 +1,20 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: sdf-xarray
-Version: 0.2.5
+Version: 0.2.6
 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
-         
-         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.
-         
+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
-Classifier: Intended Audience :: Science/Research
-Classifier: Topic :: Scientific/Engineering
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
+Requires-Python: <3.14,>=3.10
 Requires-Dist: numpy>=2.0.0
 Requires-Dist: xarray>=2024.1.0
 Requires-Dist: dask>=2024.7.1

{sdf_xarray-0.2.5 → sdf_xarray-0.2.6}/docs/index.rst

@@ -15,6 +15,7 @@ plasma PIC code.
    Getting Started <getting_started>
    Key Functionality <key_functionality>
    Unit Conversion <unit_conversion>
+   Known Issues <known_issues>
    Contributing <contributing>
 
 .. toctree::

{sdf_xarray-0.2.5 → sdf_xarray-0.2.6}/docs/key_functionality.rst

@@ -51,6 +51,12 @@ done via the ``preprocess`` parameter.
 Reading particle data
 ~~~~~~~~~~~~~~~~~~~~~
 
+.. warning::
+   It is **not recommended** to use :func:`xarray.open_mfdataset` or :func:`open_mfdataset` to load particle data from multiple SDF outputs. The number of particles often varies between outputs, which can lead to inconsistent array shapes that these functions cannot handle. Instead, consider loading each file individually and then concatenating them manually.
+
+.. note::
+   When loading multiple probes from a single SDF file, you **must** use the `probe_names` parameter to assign a unique name to each. For example, use `probe_names=["Front_Electron_Probe", "Back_Electron_Probe"]`. Failing to do so will result in dimension name conflicts.
+
 By default, particle data isn't kept as it takes up a lot of space.
 Pass ``keep_particles=True`` as a keyword argument to
 :func:`xarray.open_dataset` (for single files) or :func:`xarray.open_mfdataset` (for

sdf_xarray-0.2.6/docs/known_issues.rst

@@ -0,0 +1,9 @@
+.. _sec-known-issues:
+
+============
+Known Issues
+============
+
+There are a couple of known 'quirks' in sdf-xarray:
+
+- `Issue #57 <https://github.com/epochpic/sdf-xarray/issues/57>`_ Loading multiple SDF files with `open_mfdataset` can lead to out-of-memory errors. The issue is believed to stem from how the underlying `xarray` library handles coordinates, causing it to infer an excessively large array shape that requests far more memory than is needed. Due to the significant architectural changes required for a fix, the maintainers do not plan to resolve this. The recommended solution is to load the files individually or in smaller batches.

{sdf_xarray-0.2.5 → sdf_xarray-0.2.6}/pyproject.toml

@@ -10,30 +10,27 @@ build-backend = "scikit_build_core.build"
 [project]
 name = "sdf-xarray"
 dynamic = ["version"]
-license = { file = "LICENCE" }
+license = "BSD-3-Clause"
 readme = "README.md"
 authors = [
   { name = "Peter Hill", email = "peter.hill@york.ac.uk" },
   { name = "Joel Adams", email = "joel.adams@york.ac.uk" },
   { name = "Shaun Doherty", email = "shaun.doherty@york.ac.uk" },
 ]
-requires-python = ">=3.10"
-dependencies = [
-  "numpy>=2.0.0",
-  "xarray>=2024.1.0",
-  "dask>=2024.7.1",
-]
+requires-python = ">=3.10,<3.14"
+dependencies = ["numpy>=2.0.0", "xarray>=2024.1.0", "dask>=2024.7.1"]
 description = "Provides a backend for xarray to read SDF files as created by the EPOCH plasma PIC code."
 classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering",
+  "Operating System :: OS Independent",
   "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]

{sdf_xarray-0.2.5 → sdf_xarray-0.2.6}/src/sdf_xarray/__init__.py

@@ -69,6 +69,7 @@ def open_mfdataset(
     *,
     separate_times: bool = False,
     keep_particles: bool = False,
+    probe_names: list[str] | None = None,
 ) -> xr.Dataset:
     """Open a set of EPOCH SDF files as one `xarray.Dataset`
 
@@ -98,6 +99,8 @@ 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
     """
 
     # TODO: This is not very robust, look at how xarray.open_mfdataset does it
@@ -108,10 +111,15 @@ def open_mfdataset(
     path_glob = sorted(list(path_glob))  # noqa: C414
 
     if not separate_times:
-        return combine_datasets(path_glob, keep_particles=keep_particles)
+        return combine_datasets(
+            path_glob, 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]
+    all_dfs = [
+        xr.open_dataset(f, keep_particles=keep_particles, probe_names=probe_names)
+        for f in path_glob
+    ]
 
     for df in all_dfs:
         for da in df:
@@ -211,14 +219,23 @@ class SDFDataStore(AbstractDataStore):
         "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(
@@ -227,6 +244,7 @@ class SDFDataStore(AbstractDataStore):
         lock=None,
         drop_variables=None,
         keep_particles=False,
+        probe_names=None,
     ):
         if isinstance(filename, os.PathLike):
             filename = os.fspath(filename)
@@ -237,6 +255,7 @@ class SDFDataStore(AbstractDataStore):
             lock=lock,
             drop_variables=drop_variables,
             keep_particles=keep_particles,
+            probe_names=probe_names,
         )
 
     def _acquire(self, needs_lock=True):
@@ -347,7 +366,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
 
@@ -414,6 +454,7 @@ class SDFEntrypoint(BackendEntrypoint):
         *,
         drop_variables=None,
         keep_particles=False,
+        probe_names=None,
     ):
         if isinstance(filename_or_obj, Path):
             # sdf library takes a filename only
@@ -424,6 +465,7 @@ 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()
@@ -432,6 +474,7 @@ class SDFEntrypoint(BackendEntrypoint):
         "filename_or_obj",
         "drop_variables",
         "keep_particles",
+        "probe_names",
     ]
 
     def guess_can_open(self, filename_or_obj):

{sdf_xarray-0.2.5 → sdf_xarray-0.2.6}/src/sdf_xarray/_version.py

@@ -1,7 +1,14 @@
 # file generated by setuptools-scm
 # don't change, don't track in version control
 
-__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -9,13 +16,19 @@ if TYPE_CHECKING:
     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.2.5'
-__version_tuple__ = version_tuple = (0, 2, 5)
+__version__ = version = '0.2.6'
+__version_tuple__ = version_tuple = (0, 2, 6)
+
+__commit_id__ = commit_id = 'g67411803b'

{sdf_xarray-0.2.5 → sdf_xarray-0.2.6}/src/sdf_xarray/plotting.py

@@ -114,8 +114,8 @@ def animate(
     --------
     >>> 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()
 

sdf_xarray-0.2.6/tests/example_two_probes_2D/input.deck

@@ -0,0 +1,188 @@
+
+### USER DEFINED CONSTANTS ###
+begin:constant
+  # User input constants
+  n_elec = 6e+29 #average electron number density
+  I_peak = 1e+28 #peak intensity of the laser
+
+  scale_length = 0.5e-6 #scale length of the target
+  L_target_x = 1.5e-6 #length of the target
+  L_target_y = 10e-6 #width of the target
+
+  lambda_L = 800e-9 #wavelength of the laser
+  y_fwhm_L = 2e-6 #intensity fwhm in y
+  tau_fwhm_L = 16e-15 #intensity fwhm in t
+
+  mppc = 100 #macro particles per cell
+end:constant
+
+begin:control
+  nx = 150
+  ny = 200
+  nsteps = -1
+  t_end = 200e-15
+  x_min = -10e-06
+  x_max =  5e-06
+  y_min = -10e-06
+  y_max = -y_min
+  nparticles = nint(((L_target_x * L_target_y) / ((x_max - x_min) * (y_max - y_min))) * nx * ny * mppc)
+  dt_multiplier = 0.8
+  smooth_currents = T
+  dlb_threshold = 0.8
+  stdout_frequency = 100 # Print ETA
+  particle_tstart = 30e-15 # Time before the laser hits the target
+end:control
+
+### CALCULATD CONSTANTS ###
+begin:constant
+  w_t = tau_fwhm_L / (2*sqrt(loge(2)))           # Beam waist in t
+  w_y = y_fwhm_L / (2*sqrt(loge(2)))             # Beam waist in y
+  t_hw01m = 0.5 * tau_fwhm_L * sqrt(loge(10)/loge(2))
+
+  x_foc = -x_min                                 # Boundary to focal point distance
+  k_L = 2.0 * pi / lambda_L                      # Laser wave number
+  x_Rr = pi * w_y^2 / lambda_L                   # Rayleigh range
+  omega_L = 2 * pi * c / lambda_L                # Angular frequency of the laser
+
+  w_boundary = w_y * sqrt(1 + (x_foc/x_Rr)^2)    # Waist on boundary
+  I_boundary = I_peak * (w_y / w_boundary)^2     # Intens. on boundary
+  r_curve = x_foc * (1 + (x_Rr/x_foc)^2)         # Boundary curv. rad.
+  phase_Gouy = atan(-x_foc/r_curve)              # Boundary Gouy shift
+end:constant
+
+begin:laser
+  boundary = x_min
+  intensity = I_boundary
+  omega = omega_L
+  phase = k_L * y^2 / (2 * r_curve) - phase_Gouy
+  profile = gauss(y, 0, w_boundary)
+  t_profile = gauss(time, t_hw01m, w_t) 
+  t_start = 0.0
+  t_end = end
+end:laser
+
+begin:qed
+  use_qed = F
+  qed_start_time = 0
+  produce_photons = T
+  photon_energy_min = 1 * kev
+  produce_pairs = T
+  photon_dynamics = T
+end:qed
+
+begin:collisions
+  use_collisions = T
+  coulomb_log = auto
+  collide = all
+end:collisions
+
+begin:boundaries
+  bc_x_min_particle = simple_outflow
+  bc_x_max_particle = simple_outflow
+  bc_y_min_particle = reflect
+  bc_y_max_particle = reflect
+  bc_x_min_field = simple_laser
+  bc_x_max_field = conduct
+  bc_y_min_field = conduct
+  bc_y_max_field = conduct
+end:boundaries
+
+begin:species
+  name = Electron
+  frac = 0.5
+  dump = T
+  temperature = 300
+  number_density  = if((abs(y) lt L_target_y/2), if((x lt 0) or (x gt L_target_x), 0, if((x gt 0) and (x lt scale_length), n_elec * (1-exp(x/scale_length))/(1-exp(1)), n_elec)), 0)
+  number_density_min = 1
+  identify:electron
+end:species
+
+begin:species
+  name = Ion_C
+  charge = 6
+  atomic_number = 12
+  mass = 1836.2 * 12
+  frac = 0.25
+  dump = T
+  number_density = number_density(Electron) * (6/7)
+  temperature = temperature_x(Electron)
+  number_density_min = 1
+end:species
+
+begin:species
+  name = Ion_H
+  charge = 1
+  atomic_number = 1
+  mass = 1836.2
+  fraction = 0.25
+  dump = T
+  number_density = number_density(Electron) / 7
+  temperature = temperature_x(Electron)
+  number_density_min = 1
+  identify:proton
+end:species
+
+begin:species
+  name = Photon
+  nparticles = 0
+  dump = T
+  identify:photon
+end:species
+
+begin:species
+  name = Positron
+  nparticles = 0
+  dump = T
+  identify:positron
+end:species
+
+### THE MANY PARTICLE PROBES ###
+
+#Electron#
+begin:probe
+  name = Electron_Front_Probe
+  point = (x_min, 0)
+  normal = (-1.0, 0.0)
+  ek_min = 0.0
+  ek_max = -1.0
+  include_species : Electron
+  dumpmask = always
+end:probe
+begin:probe
+  name = Electron_Back_Probe
+  point = (x_max, 0)
+  normal = (1.0, 0.0)
+  ek_min = 0.0
+  ek_max = -1.0
+  include_species : Electron
+  dumpmask = always
+end:probe
+
+################################
+
+begin:output_global
+  force_final_to_be_restartable = F
+end:output_global
+
+begin:output
+  name = normal
+  grid = always
+  particle_probes = always
+  dt_snapshot = 15e-14
+  ex = always + single
+  ey = always + single
+  ez = always + single
+  bx = always + single
+  by = always + single
+  bz = always + single
+  particles = always
+  particle_weight = always
+  px = always + single
+  py = always + single
+  pz = always + single
+  average_particle_energy = always + species + no_sum + single
+  number_density = always + species + no_sum + single
+  absorption = always 
+  total_energy_sum = always + species
+end:output
+

{sdf_xarray-0.2.5 → sdf_xarray-0.2.6}/tests/test_basic.py

@@ -11,6 +11,7 @@ EXAMPLE_MISMATCHED_FILES_DIR = (
 )
 EXAMPLE_ARRAYS_DIR = pathlib.Path(__file__).parent / "example_array_no_grids"
 EXAMPLE_3D_DIST_FN = pathlib.Path(__file__).parent / "example_dist_fn"
+EXAMPLE_2D_PARTICLE_DATA = pathlib.Path(__file__).parent / "example_two_probes_2D"
 
 
 def test_basic():
@@ -226,3 +227,32 @@ def test_erroring_drop_variables():
         xr.open_dataset(
             EXAMPLE_FILES_DIR / "0000.sdf", drop_variables=["Electric_Field/E"]
         )
+
+
+def test_loading_multiple_probes():
+    with xr.open_dataset(
+        EXAMPLE_2D_PARTICLE_DATA / "0002.sdf",
+        keep_particles=True,
+        probe_names=["Electron_Front_Probe", "Electron_Back_Probe"],
+    ) as df:
+        assert "X_Probe_Electron_Front_Probe" in df.coords
+        assert "X_Probe_Electron_Back_Probe" in df.coords
+        assert "ID_Electron_Front_Probe_Px" in df.dims
+        assert "ID_Electron_Back_Probe_Px" in df.dims
+
+
+def test_loading_one_probe_drop_second_probe():
+    with xr.open_dataset(
+        EXAMPLE_2D_PARTICLE_DATA / "0002.sdf",
+        keep_particles=True,
+        drop_variables=[
+            "Electron_Back_Probe_Px",
+            "Electron_Back_Probe_Py",
+            "Electron_Back_Probe_Pz",
+            "Electron_Back_Probe_weight",
+        ],
+        probe_names=["Electron_Front_Probe"],
+    ) as df:
+        assert "X_Probe_Electron_Front_Probe" in df.coords
+        assert "ID_Electron_Front_Probe_Px" in df.dims
+        assert "ID_Electron_Back_Probe_Px" not in df.dims