From ac7788442d4dfa4f36eb577576771213adc63623 Mon Sep 17 00:00:00 2001 From: Joel Adams Date: Wed, 8 Apr 2026 14:41:54 +0100 Subject: [PATCH 1/9] Refactor docs and locations in `toctrees` --- docs/api.md | 2 - docs/index.md | 22 +- docs/{getting_started.md => installation.md} | 45 +--- .../{key_functionality.md => loading_data.md} | 221 +++++------------- docs/understanding_datasets.md | 157 +++++++++++++ docs/why_sdf_xarray.md | 13 ++ 6 files changed, 251 insertions(+), 209 deletions(-) rename docs/{getting_started.md => installation.md} (70%) rename docs/{key_functionality.md => loading_data.md} (51%) create mode 100644 docs/understanding_datasets.md create mode 100644 docs/why_sdf_xarray.md diff --git a/docs/api.md b/docs/api.md index e4c8462..dde8549 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,5 +1,3 @@ -# API Reference - ```{eval-rst} .. autosummary:: :toctree: generated diff --git a/docs/index.md b/docs/index.md index 4e4ac95..89903c5 100644 --- a/docs/index.md +++ b/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 ``` diff --git a/docs/getting_started.md b/docs/installation.md similarity index 70% rename from docs/getting_started.md rename to docs/installation.md index c5de756..2075977 100644 --- a/docs/getting_started.md +++ b/docs/installation.md @@ -1,13 +1,11 @@ -# Getting Started - -## Installation +# 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 . If you are unfamiliar with Python, [follow this guide](#new-to-python). If you are already familiar with Python and `pip` then you can install this using the following. +There are several ways in which you can install . 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: @@ -23,45 +21,6 @@ cd sdf-xarray pip install . ``` -## Interaction - -There are two main ways to load [EPOCH SDF files](https://epochpic.github.io/documentation/visualising_output.html) into xarray objects: using the dedicated - functions or using the standard interface with our custom engine. -For examples of how to use these functions see [](./key_functionality.md#loading-sdf-files). - -All code examples throughout this documentation are visualised using Jupyter notebooks -so that you can interactively explore the datasets. To do this on your machine make -sure that you have the necessary dependencies installed: - -```bash -pip install "sdf-xarray[jupyter]" -``` - -```{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 -[](./key_functionality.md#loading-raw-files). -``` - -### Using sdf_xarray (Recommended) - -These functions are wrappers designed specifically for SDF data, providing the most -straightforward experience: - -- **Single files**: Use or -- **Multiple files**: Use or -- **Raw files**: use - -### Using xarray - -If you prefer using the native functions, you can use the , - and . Strangely there is no function in - for `xarray.open_mfdatatree`. - -These functions should all work out of the box as long as is installed on your -system, if you are having issues with it reading files, you might need to pass the parameter -`engine=sdf_engine` when calling any of the above xarray functions. - ## New to Python? ### Installing uv diff --git a/docs/key_functionality.md b/docs/loading_data.md similarity index 51% rename from docs/key_functionality.md rename to docs/loading_data.md index 286d46a..0a69368 100644 --- a/docs/key_functionality.md +++ b/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 objects; using the dedicated functions or +using the standard interface with our custom engine. + +The functions are wrappers designed specifically for SDF data, providing the most +straightforward experience: + +- **Single files**: Use or +- **Multiple files**: Use or +- **Raw files**: use + +If you prefer using the native functions, you can use the , + and . Strangely there is no function in + for `xarray.open_mfdatatree`. + +These functions should all work out of the box as long as is installed on your +system, if you are having issues with it 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 +. ``` -## 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 . ```{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 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 . @@ -53,6 +86,8 @@ function or following our implmentation in [](#loading-sparse-data). ``` ```{code-cell} ipython3 +import sdf_xarray as sdfxr + sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf") ``` @@ -62,6 +97,8 @@ the time dimension; This is done via the `preprocess` parameter utilising the 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 . ```{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 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 , 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, 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 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 plotting routine that builds on top of -, so you keep the familiar plotting -behaviour while using conveniences (see -[here](project:#sdf_xarray.dataarray_accessor.EpochAccessor.plot) for details). -Under the hood, plotting is still handled by , which means you -can use the full 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 , a -time dimension is automatically added to the resulting . -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 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 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} %") -``` +``` \ No newline at end of file diff --git a/docs/understanding_datasets.md b/docs/understanding_datasets.md new file mode 100644 index 0000000..a9f40fa --- /dev/null +++ b/docs/understanding_datasets.md @@ -0,0 +1,157 @@ +--- +file_format: mystnb +kernelspec: + name: python3 +--- + +# Exploring and Manipulating Data + +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 lazily loads the data +meaning that it only explicitly loads the results your currently +looking at when you call `.values` + +```{code-cell} ipython3 +import sdf_xarray as sdfxr +import matplotlib.pyplot as plt + +ds = sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf") + +ds["Electric_Field_Ex"] +``` + +## Plotting + +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 plotting routine that builds on top of +, so you keep the familiar plotting +behaviour while using conveniences (see +[here](project:#sdf_xarray.dataarray_accessor.EpochAccessor.plot) for details). +Under the hood, plotting is still handled by , which means you +can use the full 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() +``` + +## Dimension slicing + +When loading a multi-file dataset using , a +time dimension is automatically added to the resulting . +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 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 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) +``` + +## Manipulating data + +These datasets can also be easily manipulated the same way as you +would with 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} %") +``` + +## 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) diff --git a/docs/why_sdf_xarray.md b/docs/why_sdf_xarray.md new file mode 100644 index 0000000..0e96574 --- /dev/null +++ b/docs/why_sdf_xarray.md @@ -0,0 +1,13 @@ +# Why use sdf_xarray? + +`sdf_xarray` is a Python package that allows for you to load [EPOCH SDF files](https://epochpic.github.io/documentation/visualising_output.html) into a structured N-D labelled datasets (). We leverage the underlying [`SDF-C`](https://github.com/epochpic/SDF_C) library to convert the binary SDF files to . This package might not work as expected when loading datasets so please check the page first before raising a [GitHub Issue](https://github.com/epochpic/sdf-xarray/issues/new). + +There are several benefits to using this package over the [`sdf_helper`](https://epochpic.github.io/documentation/visualising_output/python_sdf_helper.html) including: + +- [data to numpy and pandas](https://docs.xarray.dev/en/stable/user-guide/pandas.html) - Data can be easily converted to [numpy](https://www.numpy.org/) or [pandas](https://pandas.pydata.org/) if you prefer to work with raw data. +- [data labelling](project:understanding_datasets.md) - All SDF files come with a bunch of information about them such as the `dimensions`, `units` and `name` of the variable. In these are added to each variable making it much easier to read. +- [lazy/partial loading](https://docs.xarray.dev/en/stable/internals/internal-design.html#lazy-loading) - This reduces the RAM requirements when loading large SDF files as we only load the actual array values when they are needed. +- [plotting](project:understanding_datasets.md#plotting) - You can easily plot variables across several dimensions including time using built in support. +- [animating](project:animation.md) - Visualise your data across time or slice through another dimension and make beautiful GIFs for your presentations. +- [deck loading](loading-input-deck) - automatically loads in the associated `input.deck` utilised when creating the simulation so that you can access setup variables. +- [easier unit conversion](project:unit_conversion.md) - Convert dimensions and variable units to other types with the help of [`pint`](https://pint.readthedocs.io/en/stable). From 04942a9c4e6fcad1c6e579f9bc22ec6699d8489e Mon Sep 17 00:00:00 2001 From: Joel Adams Date: Wed, 8 Apr 2026 14:42:20 +0100 Subject: [PATCH 2/9] fix single backtick in `SDFPreprocess` --- src/sdf_xarray/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/sdf_xarray/__init__.py b/src/sdf_xarray/__init__.py index ce870e9..c229f76 100644 --- a/src/sdf_xarray/__init__.py +++ b/src/sdf_xarray/__init__.py @@ -998,7 +998,7 @@ class SDFPreprocess: 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` + 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. @@ -1017,7 +1017,7 @@ class SDFPreprocess: Parameters ---------- - data_vars : + data_vars A list of data variables to load in (If not specified loads in all variables) """ From 8f42333a9a7cd82441bf99028a98259d8a1e8aff Mon Sep 17 00:00:00 2001 From: Joel Adams Date: Wed, 8 Apr 2026 14:42:36 +0100 Subject: [PATCH 3/9] Remove incorrect animate docstring example --- src/sdf_xarray/plotting.py | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/src/sdf_xarray/plotting.py b/src/sdf_xarray/plotting.py index fe312a9..80388c6 100644 --- a/src/sdf_xarray/plotting.py +++ b/src/sdf_xarray/plotting.py @@ -236,11 +236,6 @@ def _generate_animation( Matplotlib axes on which to plot kwargs Keyword arguments to be passed to matplotlib - - Examples - -------- - >>> anim = animate(ds["Derived_Number_Density_Electron"]) - >>> anim.save("animation.gif") """ if kwargs is None: @@ -334,7 +329,7 @@ def animate( ) -> FuncAnimation: """ Generate an animation using an `xarray.DataArray`. The intended use - of this function is via `sdf_xarray.plotting.EpochAccessor.animate`. + of this function is via `sdf_xarray.dataarray_accessor.EpochAccessor.animate`. Parameters --------- @@ -362,7 +357,7 @@ def animate( Examples -------- - >>> anim = animate(ds["Derived_Number_Density_Electron"]) + >>> anim = ds["Derived_Number_Density_Electron"].epoch.animate() >>> anim.save("animation.gif") """ import matplotlib.pyplot as plt # noqa: PLC0415 From 0dff99882067ba528414a3e03140672a4bd97d01 Mon Sep 17 00:00:00 2001 From: Joel Adams Date: Wed, 8 Apr 2026 15:49:22 +0100 Subject: [PATCH 4/9] correct `sdf_xarray` to `sdf-xarray` --- docs/why_sdf_xarray.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/why_sdf_xarray.md b/docs/why_sdf_xarray.md index 0e96574..97e3051 100644 --- a/docs/why_sdf_xarray.md +++ b/docs/why_sdf_xarray.md @@ -1,4 +1,4 @@ -# Why use sdf_xarray? +# Why use sdf-xarray? `sdf_xarray` is a Python package that allows for you to load [EPOCH SDF files](https://epochpic.github.io/documentation/visualising_output.html) into a structured N-D labelled datasets (). We leverage the underlying [`SDF-C`](https://github.com/epochpic/SDF_C) library to convert the binary SDF files to . This package might not work as expected when loading datasets so please check the page first before raising a [GitHub Issue](https://github.com/epochpic/sdf-xarray/issues/new). From 5cc0286b59bcd84797b972861484f96a097e0b24 Mon Sep 17 00:00:00 2001 From: Joel Adams <57064123+JoelLucaAdams@users.noreply.github.com> Date: Wed, 8 Apr 2026 17:01:57 +0100 Subject: [PATCH 5/9] Update docs/why_sdf_xarray.md Co-authored-by: Liam Pattinson --- docs/why_sdf_xarray.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/why_sdf_xarray.md b/docs/why_sdf_xarray.md index 97e3051..76bf3f9 100644 --- a/docs/why_sdf_xarray.md +++ b/docs/why_sdf_xarray.md @@ -1,6 +1,6 @@ # Why use sdf-xarray? -`sdf_xarray` is a Python package that allows for you to load [EPOCH SDF files](https://epochpic.github.io/documentation/visualising_output.html) into a structured N-D labelled datasets (). We leverage the underlying [`SDF-C`](https://github.com/epochpic/SDF_C) library to convert the binary SDF files to . This package might not work as expected when loading datasets so please check the page first before raising a [GitHub Issue](https://github.com/epochpic/sdf-xarray/issues/new). +`sdf_xarray` is a Python package that allows you to load [EPOCH SDF files](https://epochpic.github.io/documentation/visualising_output.html) into structured N-D labelled datasets (). We leverage the underlying [`SDF-C`](https://github.com/epochpic/SDF_C) library to convert the binary SDF files to . This package might not work as expected when loading datasets so please check the page first before raising a [GitHub Issue](https://github.com/epochpic/sdf-xarray/issues/new). There are several benefits to using this package over the [`sdf_helper`](https://epochpic.github.io/documentation/visualising_output/python_sdf_helper.html) including: From 6732588e82785ca146e1a354353b39c32025f560 Mon Sep 17 00:00:00 2001 From: Joel Adams <57064123+JoelLucaAdams@users.noreply.github.com> Date: Wed, 8 Apr 2026 17:02:21 +0100 Subject: [PATCH 6/9] Update docs/loading_data.md Co-authored-by: Liam Pattinson --- docs/loading_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/loading_data.md b/docs/loading_data.md index 0a69368..6f25846 100644 --- a/docs/loading_data.md +++ b/docs/loading_data.md @@ -22,7 +22,7 @@ If you prefer using the native functions, you can use the for `xarray.open_mfdatatree`. These functions should all work out of the box as long as is installed on your -system, if you are having issues with it reading files, you might need to pass the parameter +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} From 4860c291d3b9976e24b255a2c8a3ccccf3cf1a93 Mon Sep 17 00:00:00 2001 From: Joel Adams <57064123+JoelLucaAdams@users.noreply.github.com> Date: Wed, 8 Apr 2026 17:02:33 +0100 Subject: [PATCH 7/9] Update docs/loading_data.md Co-authored-by: Liam Pattinson --- docs/loading_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/loading_data.md b/docs/loading_data.md index 6f25846..358cb7b 100644 --- a/docs/loading_data.md +++ b/docs/loading_data.md @@ -91,7 +91,7 @@ import sdf_xarray as sdfxr sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf") ``` -Alternatively, files can be loaded using however when loading in +Alternatively, files can be loaded using . 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 function. From 6e19aac03cd4c5c9a62ae82ee64ca6072def88c2 Mon Sep 17 00:00:00 2001 From: Joel Adams <57064123+JoelLucaAdams@users.noreply.github.com> Date: Wed, 8 Apr 2026 17:03:10 +0100 Subject: [PATCH 8/9] Update docs/understanding_datasets.md Co-authored-by: Liam Pattinson --- docs/understanding_datasets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/understanding_datasets.md b/docs/understanding_datasets.md index a9f40fa..6446642 100644 --- a/docs/understanding_datasets.md +++ b/docs/understanding_datasets.md @@ -31,7 +31,7 @@ ds["Electric_Field_Ex"] ## Plotting -On top of accessing variables, you can plot these datasets using +You can plot datasets using [`xarray.DataArray.epoch.plot`](project:#sdf_xarray.dataarray_accessor.EpochAccessor.plot). This is a custom plotting routine that builds on top of , so you keep the familiar plotting From 643500a2cb3536b5d95b1187abad07f4af5cb362 Mon Sep 17 00:00:00 2001 From: Joel Adams <57064123+JoelLucaAdams@users.noreply.github.com> Date: Wed, 8 Apr 2026 17:03:18 +0100 Subject: [PATCH 9/9] Update docs/understanding_datasets.md Co-authored-by: Liam Pattinson --- docs/understanding_datasets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/understanding_datasets.md b/docs/understanding_datasets.md index 6446642..d2c1914 100644 --- a/docs/understanding_datasets.md +++ b/docs/understanding_datasets.md @@ -122,7 +122,7 @@ print(f"Total particle energy absorbed: {ds["Total_Particle_Energy_in_Simulation print(f"The laser absorption fraction: {ds["Laser_Absorption_Fraction_in_Simulation"][-1].values:.1f} %") ``` -## Visualisation on HPCs +## Visualisation on HPC Machines 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