Feature: optional loading of an EPOCH input deck #93

Dartrisen · 2026-01-12T11:24:10Z

Now you can get access to the input.deck file by simply doing this:

import sdf_xarray as sdf
import xarray as xr
import epydeck

TEST_FILES_DIR = sdf.download.fetch_dataset("test_files_1D")
ds = xr.open_dataset(TEST_FILES_DIR / "0000.sdf", load_deck=True)
ds.attrs["deck"]

The package epydeck should be installed in your virtual environment to use this. The default value of load_deck is False.

Resolves #91

JoelLucaAdams · 2026-01-12T11:52:12Z

Hi @Dartrisen, thank you very much for implementing the new feature!

This is a great first start although it would be nice to also allow for this parameter would accept bool | str | Path with the default being False. If the user passes in a str | Path then it would first check if the path specified is a full file path using Path.is_absolute(), otherwise if the path is relative then look for it in the same directory as the SDF file being opened.

On top of adding this feature could you also add some additional documentation to highlight how this works? Probably a small section after this https://sdf-xarray.readthedocs.io/en/latest/key_functionality.html#loading-specific-variables or potentially a new page if you prefer.

JoelLucaAdams · 2026-01-12T11:52:58Z

src/sdf_xarray/__init__.py

+        if self.load_deck:
+            import epydeck  # type: ignore  # noqa: PGH003
+            deck_path = Path(attrs["filename"]).parent / "input.deck"
+            with open(deck_path, encoding="utf-8") as f:


Suggested change

with open(deck_path, encoding="utf-8") as f:

with open(deck_path) as f:

utf-8 encoding specification is not required here

JoelLucaAdams · 2026-01-13T12:14:29Z

FYI, you might want to additionally pull in branch #89 so that it works with datatrees as well

JoelLucaAdams

Thank you for the feature implementation! There are a few things that need ironing out that I have listed below.

On top of those changes you also need to add some tests please

JoelLucaAdams · 2026-01-20T13:09:07Z

docs/conf.py

+togglebutton_hint = "Click to show input.deck"
+togglebutton_hint_hide = "Click to hide input.deck"
+


Since this changes the toggle information globally I think it's best if it's removed

JoelLucaAdams · 2026-01-20T13:13:27Z

docs/key_functionality.rst

+When loading SDF files, you can optionally include the `input.deck` file
+used to generate the simulation. This file contains important simulation
+parameters that may not be present in the SDF outputs. By loading this file,
+you can access these parameters as part of your dataset's metadata.
+To do this, use the ``input_deck`` parameter when calling
+`sdf_xarray.open_dataset`.
+
+.. note::
+   You may need to install the `epydeck` extra dependencies
+   to enable this functionality. You can do this via pip:
+
+   .. code-block:: bash
+
+        pip install "epydeck"
+
+By default the ``input_deck`` parameter is set to ``False``. You can set it to
+``True`` to automatically search for an `input.deck` file in the same directory
+as the SDF file being loaded, or you can provide a specific path to the
+`input.deck` file as a path variable or string.


Watch out when using single "`" backticks here as they always need to be double unless you're referencing an internal function or one of the ones linked in the conf.py.

JoelLucaAdams · 2026-01-20T13:19:05Z

docs/key_functionality.rst

+.. note::
+   You may need to install the `epydeck` extra dependencies
+   to enable this functionality. You can do this via pip:
+
+   .. code-block:: bash
+
+        pip install "epydeck"


Suggested change

.. note::

You may need to install the `epydeck` extra dependencies

to enable this functionality. You can do this via pip:

.. code-block:: bash

pip install "epydeck"

In order to parse the deck file you need to install the

`epydeck` package. This can be done via pip:

.. code-block:: bash

pip install epydeck

I don't think this needs to be a note as its required in order to work but feel free to leave it in if you think otherwise. Even so I think the wording needs to change slightly to look more like this

JoelLucaAdams · 2026-01-20T13:39:28Z

docs/key_functionality.rst

+By default the ``input_deck`` parameter is set to ``False``. You can set it to
+``True`` to automatically search for an `input.deck` file in the same directory
+as the SDF file being loaded, or you can provide a specific path to the
+`input.deck` file as a path variable or string.


Suggested change

By default the ``input_deck`` parameter is set to ``False``. You can set it to

``True`` to automatically search for an `input.deck` file in the same directory

as the SDF file being loaded, or you can provide a specific path to the

`input.deck` file as a path variable or string.

By default the ``input_deck`` parameter is set to ``False``. You can set it to

``True`` to automatically search for a file with the name ``"input.deck"`` in the

same directory as the SDF file being loaded. If you wish to load a file that has

a different name and the path is relative then it will search in the same directory

as the SDF file (e.g. ``"template.deck"``), if it is absolute then it will use the

full path to the find the file (e.g. ``"/path/to/decks/input.deck"``).

Slight change to the description here

JoelLucaAdams · 2026-01-20T13:40:48Z

src/sdf_xarray/__init__.py

        keep_particles=False,
        lock=None,
        probe_names=None,
+        load_deck: bool | str | Path = False,


Suggested change

load_deck: bool | str | Path = False,

load_deck: bool | PathLike = False,

Use the PathLike defined on line 43

I doubt that it is more readable than str | Path, especially if it wasn't defined like a default type in Path lib but fixed like you suggested.

JoelLucaAdams · 2026-01-20T14:09:10Z

src/sdf_xarray/__init__.py

+
+            sdf_dir = Path(attrs["filename"]).parent
+
+            if isinstance(self.load_deck, (str, Path)):


Suggested change

if isinstance(self.load_deck, (str, Path)):

if isinstance(self.load_deck, PathLike):

Again, use the PathLike type from above

thanks, fixed

JoelLucaAdams · 2026-01-20T14:11:10Z

src/sdf_xarray/__init__.py

    def open_datatree(
        self,
        filename_or_obj,
        *,
        drop_variables=None,
        keep_particles=False,
        probe_names=None,
    ):
        ds = self.open_dataset(
            filename_or_obj,
            drop_variables=drop_variables,
            keep_particles=keep_particles,
            probe_names=probe_names,
        )


Looks like you're missing a load_deck in here so that it's passed into the dataset

JoelLucaAdams · 2026-01-20T14:14:21Z

src/sdf_xarray/__init__.py

    path: PathLike,
    *,
    keep_particles: bool = False,
    probe_names: list[str] | None = None,


Needs to be updated so that it includes load_deck and simply passes it into xr.open_datatree(...) as its handled in SDFEntryPoint

JoelLucaAdams · 2026-01-20T14:16:52Z

src/sdf_xarray/__init__.py

There should also be an implementation of load_deck in open_mfdataset(...) and open_mfdatatree(...). Since both of these along with the base implementation in SDFDataStore.load(...) will use the same underlying structure I'd probably extract the logic to a separate hidden helper function at the top of the file e.g. _load_deck(...).

JoelLucaAdams · 2026-01-20T14:20:18Z

docs/key_functionality.rst

+parameters that may not be present in the SDF outputs. By loading this file,
+you can access these parameters as part of your dataset's metadata.
+To do this, use the ``input_deck`` parameter when calling
+`sdf_xarray.open_dataset`.


Once you've implemented load_deck into the other classes then please update this to link to them e.g.

Suggested change

`sdf_xarray.open_dataset`.

`xarray.open_dataset`, `sdf_xarray.open_datatree`, `sdf_xarray.open_mfdataset` and `sdf_xarray.open_mfdatatree`.

add support for loading deck

9f0aa27

JoelLucaAdams self-requested a review January 12, 2026 11:36

JoelLucaAdams reviewed Jan 12, 2026

View reviewed changes

Dartrisen and others added 2 commits January 12, 2026 16:16

add parameter handling for Path | str types

52015ae

patch fetch_datasets to work with new datasets. see epochpic#88

5834084

Dartrisen and others added 9 commits January 14, 2026 16:20

Merge branch 'main' into feature/adding-deck-handler

e17baea

add docs for load_deck feature

65ab6ac

add note (epydeck should be installed first to use feature)

c137c41

Merge branch 'epochpic:main' into feature/adding-deck-handler

415e14a

add dependency (togglebutton, epydeck), improve docs

5e00c4d

make linter happy

91ff67b

file reformat

8fb7070

uv lock update

1746e5e

Fix incorrect setting of self._filename in `SDFDataStore

b4a11aa

JoelLucaAdams requested changes Jan 20, 2026

View reviewed changes

Dartrisen added 3 commits January 23, 2026 13:32

add various fixes (types, etc)

7ba425a

extract _load_deck to separate function

d975e5f

small cosmetic changes to make ruff happy

30d1dc5

	with open(deck_path, encoding="utf-8") as f:
	with open(deck_path) as f:

		togglebutton_hint = "Click to show input.deck"
		togglebutton_hint_hide = "Click to hide input.deck"

	load_deck: bool \| str \| Path = False,
	load_deck: bool \| PathLike = False,


		sdf_dir = Path(attrs["filename"]).parent

		if isinstance(self.load_deck, (str, Path)):

	if isinstance(self.load_deck, (str, Path)):
	if isinstance(self.load_deck, PathLike):

	`sdf_xarray.open_dataset`.
	`xarray.open_dataset`, `sdf_xarray.open_datatree`, `sdf_xarray.open_mfdataset` and `sdf_xarray.open_mfdatatree`.

Feature: optional loading of an EPOCH input deck #93

Are you sure you want to change the base?

Feature: optional loading of an EPOCH input deck #93

Uh oh!

Conversation

Dartrisen commented Jan 12, 2026 • edited by JoelLucaAdams Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JoelLucaAdams commented Jan 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JoelLucaAdams commented Jan 13, 2026

Uh oh!

JoelLucaAdams left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JoelLucaAdams Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Dartrisen commented Jan 12, 2026 •

edited by JoelLucaAdams

Loading

JoelLucaAdams Jan 20, 2026 •

edited

Loading