sdf-xarray provides a backend for xarray to read SDF files as created by EPOCH using the SDF-C library. Part of BEAM (Broad EPOCH Analysis Modules).

Installation

[!IMPORTANT] To install this package make sure you are using one of the Python versions listed above.

Install from PyPI with:

pip install sdf-xarray

or download this code locally:

git clone --recursive https://github.com/epochpic/sdf-xarray.git
cd sdf-xarray
pip install .

We recommend switching to uv to manage packages.

Usage

Below are some simple examples to get you started. Please read the full documentation here https://sdf-xarray.readthedocs.io.

Single file loading

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

You can open all the SDF files for a given simulation by calling the open_mfdataset function from sdf_xarray. This will additionally add a time dimension using the "time" value stored in each files attributes.

[!IMPORTANT] If your simulation has multiple output blocks so that not all variables are output at every time step, then at the timesteps where those variables are not present they will have have a value of nan. To clean your dataset by removing these nan values we suggest using the xarray.DataArray.dropna function or loading sparse data along separate time dimensions using separate_times=True.

from sdf_xarray import open_mfdataset

ds = open_mfdataset("*.sdf")
print(ds)

# Dimensions:
# time: 301, X_Grid_mid: 128, ...
# Coordinates: (9) ...
# Data variables: (18) ...
# Indexes: (9) ...
# Attributes: (22) ...

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!
• 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 or readthedocs documentation

Broad EPOCH Analysis Modules (BEAM)

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: Reading and processing SDF files and converting them to xarray.
• epydeck: Input deck reader and writer.
• epyscan: Create campaigns over a given parameter space using various sampling methods.

PlasmaFAIR

Originally developed by PlasmaFAIR, EPSRC Grant EP/V051822/1