sdf-xarray 0.7.0__tar.gz → 0.7.1__tar.gz

{sdf_xarray-0.7.0 → sdf_xarray-0.7.1}/.readthedocs.yaml

@@ -7,7 +7,7 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-24.04
   tools:
     python: "3.12"
 

{sdf_xarray-0.7.0 → sdf_xarray-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdf-xarray
-Version: 0.7.0
+Version: 0.7.1
 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.7.0 → sdf_xarray-0.7.1}/docs/api.md

@@ -1,5 +1,3 @@
-# API Reference
-
 ```{eval-rst}
 .. autosummary::
    :toctree: generated

{sdf_xarray-0.7.0 → sdf_xarray-0.7.1}/docs/conf.py

@@ -33,7 +33,7 @@ main_release = ".".join(release.split(".")[:3])
 dev_release = release.split(".")[-1]
 
 # Set html title manually for nicer formatting
-html_title = f"{project} {main_release} [{dev_release}] documentation"
+html_title = f"{project} {main_release} documentation"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -50,6 +50,7 @@ extensions = [
     "myst_nb",
     "sphinx_copybutton",
     "sphinx_togglebutton",
+    "sphinx_design",
 ]
 
 source_suffix = {".rst": "restructuredtext", ".md": "myst-nb"}

{sdf_xarray-0.7.0 → sdf_xarray-0.7.1}/docs/index.md

@@ -7,13 +7,27 @@ plasma PIC code.
 `sdf-xarray` uses the [SDF-C](https://github.com/epochpic/SDF_C) library.
 
 ```{toctree}
-:caption: 'Contents'
+:caption: 'Getting Started'
 :maxdepth: 1
 
-getting_started.md
-key_functionality.md
-animation.md
+installation.md
+why_sdf_xarray.md
+```
+
+```{toctree}
+:caption: 'User Guide'
+:maxdepth: 1
+
+loading_data.md
+understanding_datasets.md
 unit_conversion.md
+animation.md
+```
+
+```{toctree}
+:caption: 'Development'
+:maxdepth: 1
+
 known_issues.md
 contributing.md
 ```

sdf_xarray-0.7.1/docs/installation.md

@@ -0,0 +1,135 @@
+# Installation
+
+```{important}
+To install this package, ensure that you are using one of the supported Python
+versions [![Supported Python versions](https://img.shields.io/pypi/pyversions/sdf-xarray.svg)](https://github.com/epochpic/sdf-xarray)
+```
+
+There are several ways in which you can install <project:#sdf_xarray>. If you are unfamiliar with Python, [follow the guide below](#new-to-python). If you are already familiar with Python and `pip` then you can install this using the following.
+
+Install sdf-xarray from PyPI with:
+
+```bash
+pip install sdf-xarray
+```
+
+or download this code locally:
+
+```bash
+git clone --recursive https://github.com/epochpic/sdf-xarray.git
+cd sdf-xarray
+pip install .
+```
+
+## New to Python?
+
+### Installing uv
+
+We recommend [installing uv](https://docs.astral.sh/uv/getting-started/installation/) which is a command line tool that can install both Python versions and packages. This tool is widely used in the Python community and is significantly faster than other tools that do the same. 
+
+`````{tab-set}
+````{tab-item} Linux/MacOS
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+````
+
+````{tab-item} Windows
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+You might need to change the [execution policy](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4#powershell-execution-policies) to allow running a script from the internet.
+````
+`````
+
+You can then check `uv` is correctly installed by running:
+
+```bash
+uv --version
+```
+
+### Installing Python
+
+If Python is already installed on your system then `uv` will detect and use it. If you don't have python already installed on your machine you can use `uv` to install it:
+
+```console
+uv python install 3.14
+```
+Once installed, it should be possible to run Python using 
+
+```bash
+python3.14 --version
+```
+
+### Setting up a virtual environment
+
+Now that you've installed `uv` and have a supported Python version you need to create a [virtual environment](https://docs.astral.sh/uv/reference/cli/#uv-venv). You need to do this because Python doesn't allow you to install libraries globally on your system. From a folder of your choosing run the following command to create a subfolder called `.venv` containing all the Python libraries you install.
+
+```bash
+uv venv
+```
+
+Depending on your operating system you'll need to follow the activation command that appears after running `uv venv`. This will tell Python to use the libraries installed in this package.
+
+### Installing sdf-xarray
+
+Finally we can install <project:#sdf_xarray> to the `venv` using the following command. Any additional packages that can be installed using `pip` can also be installed using this method.
+
+```bash
+uv pip install sdf-xarray
+```
+
+### Getting an error about a missing `CMAKE_C_COMPILER`?
+
+Are you getting an error that looks like this?
+
+```bash
+$ uv pip install sdf-xarray
+Resolved 16 packages in 293ms
+  x Failed to build `sdf-xarray==0.7.0`
+  |-> The build backend returned an error
+  `-> Call to `scikit_build_core.build.build_wheel` failed (exit status: 1)
+
+      [stdout]
+      *** scikit-build-core 0.12.2 using CMake 4.3.1 (wheel)
+      *** Configuring CMake...
+      loading initial cache file /tmp/tmp8ch254_2/build/CMakeInit.txt
+      -- Configuring incomplete, errors occurred!
+
+      [stderr]
+      CMake Error at
+      /nix/tmp/debug-tools/.cache/uv/builds-v0/.tmpa3v1oF/lib/python3.14/site-packages/cmake/data/share/cmake-4.3/Modules/CMakeDetermineCCompiler.cmake:48
+      (message):
+        Could not find the compiler specified in the environment variable CC:
+
+        cc -pthread.
+      Call Stack (most recent call first):
+        CMakeLists.txt:3 (project)
+
+
+      CMake Error: CMAKE_C_COMPILER not set, after EnableLanguage
+
+      *** CMake configuration failed
+
+      hint: This usually indicates a problem with the package or the build environment.
+```
+
+Don't panic, this error means you've not installed a `C` compiler onto your computer. 
+
+````{tab-set}
+```{tab-item} Linux
+If you're on a fresh or recent Linux install then there's a good chance you might be missing a it, you can remedy this by running `sudo apt install build-essential` on Debian-based Linux systems such as Ubuntu.
+```
+
+```{tab-item} MacOS
+Make sure you've installed the [Command Line Tools package](https://developer.apple.com/documentation/xcode/installing-the-command-line-tools/#Install-the-Command-Line-Tools-package-in-Terminal).
+```
+
+```{tab-item} Windows
+If you've encountered this error then I have no idea... But I strongly recommending installing [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) and running a mini Ubuntu install on your machine instead of fighting windows.
+```
+````
+
+### How do I run my Python scripts?
+
+As long as you've "activated" your `venv` you can run a Python script from anywhere on your computer.

{sdf_xarray-0.7.0 → sdf_xarray-0.7.1}/docs/known_issues.md

@@ -9,3 +9,7 @@ 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.
+- [Issue #112](https://github.com/epochpic/sdf-xarray/issues/112) Due to the 
+way [cylindrical EPOCH](https://github.com/epochpic/cylindrical_epoch) sets up 
+grids we can't currently load it's SDF files. If there is enough interest in this
+we will attempt to find a solution otherwise it shall remain low priority.

sdf_xarray-0.7.0/docs/key_functionality.md → sdf_xarray-0.7.1/docs/loading_data.md

@@ -4,19 +4,48 @@ kernelspec:
   name: python3
 ---
 
-# Key Functionality
+# Loading SDF Files
 
-```{code-cell} ipython3
-import xarray as xr
-import sdf_xarray as sdfxr
-import matplotlib.pyplot as plt
+There are two main ways to load [EPOCH SDF files](https://epochpic.github.io/documentation/visualising_output.html)
+into <inv:#xarray> objects; using the dedicated <project:#sdf_xarray> functions or
+using the standard <inv:#xarray> interface with our custom engine. 
+
+The <project:#sdf_xarray> functions are wrappers designed specifically for SDF data, providing the most
+straightforward experience:
+
+- **Single files**: Use <project:#sdf_xarray.open_dataset> or <project:#sdf_xarray.open_datatree>
+- **Multiple files**: Use <project:#sdf_xarray.open_mfdataset> or <project:#sdf_xarray.open_mfdatatree>
+- **Raw files**: use <project:#sdf_xarray.sdf_interface.SDFFile>
+
+If you prefer using the native <inv:#xarray> functions, you can use the <inv:#xarray.open_dataset>,
+<inv:#xarray.open_datatree> and <inv:#xarray.open_mfdataset>. Strangely there is no function in
+<inv:#xarray> for `xarray.open_mfdatatree`.
+
+These functions should all work out of the box as long as <project:#sdf_xarray> is installed on your
+system. If you are having issues reading files, you might need to pass the parameter
+`engine=sdf_engine` when calling any of the above xarray functions.
+
+```{important}
+When loading SDF files, variables related to `boundaries`, `cpu` and `output file`
+are excluded as they are problematic. If you wish to load these variables in see
+<project:#loading-raw-files>.
 ```
 
-## Loading SDF files
+````{note}
+All code examples shown here are visualised using [Jupyter notebooks](https://jupyter.org/)
+so that you can interactively explore the datasets. To do this on your machine
+make sure that you have the necessary dependencies installed:
+
+```bash
+uv pip install "sdf-xarray[jupyter]"
+```
+````
 
-### Loading single files
+## Loading single files
 
 ```{code-cell} ipython3
+import sdf_xarray as sdfxr
+
 sdfxr.open_dataset("tutorial_dataset_1d/0010.sdf")
 ```
 
@@ -25,22 +54,26 @@ hierarchically into `groups` (for example grouping related quantities such as th
 components of the electric and magnetic fields) while keeping each item as a <inv:#xarray.Dataset>.
 
 ```{code-cell} ipython3
+import sdf_xarray as sdfxr
+
 sdfxr.open_datatree("tutorial_dataset_1d/0010.sdf")
 ```
 
 (loading-raw-files)=
 
-### Loading raw files
+## Loading raw files
 
 If you wish to load data directly from the `SDF.C` library and ignore
 the <inv:#xarray> interface layer.
 
 ```{code-cell} ipython3
+import sdf_xarray as sdfxr
+
 raw_ds = sdfxr.SDFFile("tutorial_dataset_1d/0010.sdf")
 raw_ds.variables.keys()
 ```
 
-### Loading multiple files
+## Loading multiple files
 
 Multiple files can be loaded using one of two methods. The first of which
 is by using the <project:#sdf_xarray.open_mfdataset>.
@@ -53,15 +86,19 @@ function or following our implmentation in [](#loading-sparse-data).
 ```
 
 ```{code-cell} ipython3
+import sdf_xarray as sdfxr
+
 sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
 ```
 
-Alternatively, files can be loaded using <inv:#xarray.open_mfdataset> however when loading in
+Alternatively, files can be loaded using <inv:#xarray.open_mfdataset>. However, when loading in
 all the files we have do some processing of the data so that we can correctly align it along
 the time dimension; This is done via the `preprocess` parameter utilising the
 <project:#sdf_xarray.SDFPreprocess> function.
 
 ```{code-cell} ipython3
+import xarray as xr
+
 xr.open_mfdataset(
    "tutorial_dataset_1d/*.sdf",
    join="outer",
@@ -75,10 +112,12 @@ hierarchically into `groups` (for example grouping related quantities such as th
 components of the electric and magnetic fields) while keeping each item as a <inv:#xarray.Dataset>.
 
 ```{code-cell} ipython3
+import sdf_xarray as sdfxr
+
 sdfxr.open_mfdatatree("tutorial_dataset_1d/*.sdf")
 ```
 
-### Loading sparse data
+## Loading sparse data
 
 When dealing with sparse data (where different variables are saved at different,
 non-overlapping time steps) you can optimize memory usage by loading the data with
@@ -89,10 +128,12 @@ significantly reduces memory consumption, though it requires more deliberate han
 if you need to compare variables that exist on these different time coordinates.
 
 ```{code-cell} ipython3
+import sdf_xarray as sdfxr
+
 sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf", separate_times=True)
 ```
 
-### Loading particle data
+## Loading particle data
 
 ```{warning}
 It is **not recommended** to use <inv:#xarray.open_mfdataset> or
@@ -116,10 +157,12 @@ Pass `keep_particles=True` as a keyword argument to
 multiple files).
 
 ```{code-cell} ipython3
+import sdf_xarray as sdfxr
+
 sdfxr.open_dataset("tutorial_dataset_1d/0010.sdf", keep_particles=True)
 ```
 
-### Loading specific variables
+## Loading specific variables
 
 When loading datasets containing several (`>10`) coordinates/dimensions
 using <project:#sdf_xarray.open_mfdataset>, <inv:#xarray> may struggle to locate
@@ -132,12 +175,14 @@ and the relevant coordinates/dimensions, significantly reducing memory
 consumption.
 
 ```{code-cell} ipython3
+import sdf_xarray as sdfxr
+
 sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf", data_vars=["Electric_Field_Ex"])
 ```
 
 (loading-input-deck)=
 
-### Loading the input.deck
+## Loading the input.deck
 
 When loading SDF files, <project:#sdf_xarray> will attempt to automatically load
 the `input.deck` file used to initialise the simulation from the same
@@ -165,157 +210,13 @@ An example of loading a deck can be seen below
 
 import json
 from IPython.display import Code
+import sdf_xarray as sdfxr
 
-ds = xr.open_dataset("tutorial_dataset_1d/0010.sdf")
+ds = sdfxr.open_dataset("tutorial_dataset_1d/0010.sdf")
 # The results are accessible by calling
 deck = ds.attrs["deck"]
 
 # Some prettification to make it looks nice in jupyter notebooks
 json_str = json.dumps(deck, indent=4)
 Code(json_str, language='json')
-```
-
-## Data interaction examples
-
-When loading in either a single dataset or a group of datasets you
-can access the following methods to explore the dataset:
-
-- `ds.variables` to list variables. (e.g. Electric Field, Magnetic
-  Field, Particle Count)
-- `ds.coords` for accessing coordinates/dimensions. (e.g. x-axis,
-  y-axis, time)
-- `ds.attrs` for metadata attached to the dataset. (e.g. filename,
-  step, time)
-
-It is important to note here that <inv:#xarray> lazily loads the data
-meaning that it only explicitly loads the results your currently
-looking at when you call `.values`
-
-```{code-cell} ipython3
-ds = sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
-
-ds["Electric_Field_Ex"]
-```
-
-On top of accessing variables, you can plot these 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()
-```
-
-When loading a multi-file dataset using <project:#sdf_xarray.open_mfdataset>, a
-time dimension is automatically added to the resulting <inv:#xarray.Dataset>.
-This dimension represents all the recorded simulation steps and allows
-for easy indexing. To quickly determine the number of time steps available,
-you can check the size of the time dimension.
-
-```{code-cell} ipython3
-# This corresponds to the number of individual SDF files loaded
-print(f"There are a total of {ds['time'].size} time steps")
-
-# You can look up the actual simulation time for any given index
-sim_time = ds['time'].values[20]
-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
-the first snapshot).
-
-```{code-cell} ipython3
-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.
-
-```{tip}
-If you know roughly what time you wish to select but not the exact value
-you can use the parameter `method="nearest"`.
-```
-
-```{code-cell} ipython3
-ds["Electric_Field_Ex"].sel(time=sim_time)
-```
-
-## Visualisation on HPCs
-
-In many cases you will be running EPOCH simulations via a HPC cluster and your
-subsequent SDF files will probably be rather large and cumbersome to interact with
-via traditional Jupyter notebooks. In some cases your HPC may outright block the
-use of Jupyter notebooks entirely. To circumvent this issue you can use a Terminal
-User Interface (TUI) which renders the contents of SDF files directly in a Terminal
-and allows for you to do some simple data analysis and visualisation. To do this we
-shall leverage the [xr-tui](https://github.com/samueljackson92/xr-tui) package
-which can be installed to either a venv or globally using:
-
-```bash
-pipx install xr-tui sdf-xarray
-```
-
-or if you are using `uv`
-
-```bash
-uv tool install xr-tui --with sdf-xarray
-```
-
-Once installed you can visualise SDF files by simply writing in the command line
-
-```bash
-xr path/to/simulation/0000.sdf
-# OR
-xr path/to/simulation/*.sdf
-```
-
-Below is an example gif of how this interfacing looks as seen on
-[xr-tui](https://github.com/samueljackson92/xr-tui) `README.md`:
-
-![xr-tui interfacing gif](https://raw.githubusercontent.com/samueljackson92/xr-tui/main/demo.gif)
-
-## Manipulating data
-
-These datasets can also be easily manipulated the same way as you
-would with `numpy` arrays.
-
-```{code-cell} ipython3
-ds["Laser_Absorption_Fraction_in_Simulation"] = (
-   (ds["Total_Particle_Energy_in_Simulation"] - ds["Total_Particle_Energy_in_Simulation"][0])
-   / ds["Absorption_Total_Laser_Energy_Injected"]
-) * 100
-
-# We can also manipulate the units and other attributes
-ds["Laser_Absorption_Fraction_in_Simulation"].attrs["units"] = "%"
-ds["Laser_Absorption_Fraction_in_Simulation"].attrs["long_name"] = "Laser Absorption Fraction"
-
-ds["Laser_Absorption_Fraction_in_Simulation"].epoch.plot()
-plt.title("Laser absorption fraction in simulation")
-plt.show()
-```
-
-You can also call the [`xarray.DataArray.epoch.plot`](project:#sdf_xarray.dataarray_accessor.EpochAccessor.plot) function on several variables with
-labels by delaying the call to `plt.show()`.
-
-```{code-cell} ipython3
-ds["Total_Particle_Energy_Electron"].epoch.plot(label="Electron")
-ds["Total_Particle_Energy_Ion"].epoch.plot(label="Ion")
-plt.title("Particle Energy in Simulation per Species")
-plt.legend()
-plt.show()
-```
-
-```{code-cell} ipython3
-print(f"Total laser energy injected: {ds["Absorption_Total_Laser_Energy_Injected"][-1].values:.1e} J")
-print(f"Total particle energy absorbed: {ds["Total_Particle_Energy_in_Simulation"][-1].values:.1e} J")
-print(f"The laser absorption fraction: {ds["Laser_Absorption_Fraction_in_Simulation"][-1].values:.1f} %")
-```
+```