epochpic · JoelLucaAdams · Feb 7, 2026 · Feb 3, 2026 · Feb 3, 2026 · Feb 3, 2026
diff --git a/docs/_static/jupyter_padding.css b/docs/_static/jupyter_padding.css
@@ -0,0 +1,3 @@
+.cell_output {
+    margin-bottom: 0.5em;
+}
diff --git a/docs/animation.rst b/docs/animation.rst
@@ -125,7 +125,7 @@ the animation.
 
 .. jupyter-execute::
 
-   ds = xr.open_dataset("tutorial_dataset_3d/0005.sdf")
+   ds = sdfxr.open_dataset("tutorial_dataset_3d/0005.sdf")
    da = ds["Derived_Number_Density"]
    anim = da.epoch.animate(t = "X_Grid_mid")
    anim.show()

diff --git a/docs/conf.py b/docs/conf.py
@@ -103,9 +103,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-html_css_files = [
-    "force_render_dark_xarray_objects.css",
-]
+html_css_files = ["force_render_dark_xarray_objects.css", "jupyter_padding.css"]
 
 html_theme_options = {
     "repository_url": "https://github.com/epochpic/sdf-xarray",

diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -30,77 +30,46 @@ or download this code locally:
     cd sdf-xarray
     pip install .
 
-.. note::
 
-   When loading SDF files, variables related to ``boundaries``, ``cpu`` and ``output file`` are excluded as they are problematic. If you wish to load these in please use the
-   :ref:`loading-raw-files-getting-started` approach.
+Interaction
+-----------
 
-.. tip::
+There are two main ways to load EPOCH SDF files into xarray objects: using the dedicated
+`sdf_xarray` functions or using the standard `xarray` interface with our custom engine.
+For examples of how to use these functions see :ref:`loading-sdf-files`.
 
-    All code examples throughout this documentation are visualised using Jupyter notebooks
-    so that you can interactively explore `xarray.Dataset` objects. To do this on your machine
-    make sure that you have the necessary dependencies installed: 
+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: 
 
-    .. code-block:: bash
-
-        pip install "sdf-xarray[jupyter]"
-
-Usage
------
-
-``sdf-xarray`` is a backend for xarray, and so is usable directly from
-`xarray`. There are several ways to load SDF files:
-
-- To load a single file, use `xarray.open_dataset`.
-- To load multiple files, use `sdf_xarray.open_mfdataset` or `xarray.open_mfdataset`. 
-- To access the raw contents of a single SDF file, use `sdf_xarray.sdf_interface.SDFFile`.
-
-Loading single files
---------------------
-
-.. jupyter-execute::
-
-    import xarray as xr
-
-    xr.open_dataset("tutorial_dataset_1d/0010.sdf")
-
-Alternatively, you can load the data in as a `xarray.DataTree`, which organises the data
-hierarchically into ``groups`` (for example grouping related quantities such as the individual
-components of the electric and magnetic fields) while keeping each item as a `xarray.Dataset`.
-
-.. jupyter-execute::
-
-    import sdf_xarray as sdfxr
-
-    sdfxr.open_datatree("tutorial_dataset_1d/0010.sdf")
-
-Loading multiple files
-----------------------
-
-.. jupyter-execute::
-
-    import sdf_xarray as sdfxr
-
-    sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
+.. code-block:: bash
 
-Alternatively, you can load the data in as a `xarray.DataTree`, which organises the data
-hierarchically into ``groups`` (for example grouping related quantities such as the individual
-components of the electric and magnetic fields) while keeping each item as a `xarray.Dataset`.
+    pip install "sdf-xarray[jupyter]"
 
-.. jupyter-execute::
+.. 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
+   :ref:`loading-raw-files`.
 
-    import sdf_xarray as sdfxr
 
-    sdfxr.open_mfdatatree("tutorial_dataset_1d/*.sdf")
+Using sdf_xarray (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. _loading-raw-files-getting-started:
+These functions are wrappers designed specifically for SDF data, providing the most
+straightforward experience:
 
-Loading raw files
------------------
+- **Single files**: Use `sdf_xarray.open_dataset` or `sdf_xarray.open_datatree`
+- **Multiple files**: Use `sdf_xarray.open_mfdataset` or `sdf_xarray.open_mfdatatree`
+- **Raw files**: use `sdf_xarray.sdf_interface.SDFFile`
 
-.. jupyter-execute::
+Using xarray
+~~~~~~~~~~~~
 
-    import sdf_xarray as sdfxr
+If you prefer using the native `xarray` functions, you can use the `xarray.open_dataset`,
+`xarray.open_datatree` and `xarray.open_mfdataset`. Strangely there is no function in
+`xarray` for ``xarray.open_mfdatatree``.
 
-    raw_ds = sdfxr.SDFFile("tutorial_dataset_1d/0010.sdf")
-    raw_ds.variables.keys()
+These functions should all work out of the box as long as `sdf_xarray` 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.
diff --git a/docs/key_functionality.rst b/docs/key_functionality.rst
@@ -11,37 +11,19 @@ Key Functionality
    import matplotlib.pyplot as plt
    %matplotlib inline
 
+.. _loading-sdf-files:
+
 Loading SDF files
 -----------------
-There are several ways to load SDF files:
-
-- To load a single file, use `xarray.open_dataset`, `sdf_xarray.open_datatree` or `xarray.open_datatree`
-- To load multiple files, use `sdf_xarray.open_mfdataset`, `xarray.open_mfdataset` or `sdf_xarray.open_mfdatatree`.
-- To access the raw contents of a single SDF file, use `sdf_xarray.sdf_interface.SDFFile`.
-
-.. note::
-
-   When loading SDF files, variables related to ``boundaries``, ``cpu`` and ``output file`` are excluded as they are problematic. If you wish to load these in please use the
-   :ref:`loading-raw-files` approach.
-
-.. tip::
-
-    All code examples throughout this documentation are visualised using Jupyter notebooks
-    so that you can interactively explore `xarray.Dataset` objects. To do this on your machine
-    make sure that you have the necessary dependencies installed: 
-
-    .. code-block:: bash
-
-        pip install "sdf-xarray[jupyter]"
 
 Loading single files
 ~~~~~~~~~~~~~~~~~~~~
 
 .. jupyter-execute::
 
-   xr.open_dataset("tutorial_dataset_1d/0010.sdf")
+   sdfxr.open_dataset("tutorial_dataset_1d/0010.sdf")
 
-Alternatively, you can load the data in as a `xarray.DataTree`, which organises the data
+You can also load the data in as a `xarray.DataTree`, which organises the data
 hierarchically into ``groups`` (for example grouping related quantities such as the individual
 components of the electric and magnetic fields) while keeping each item as a `xarray.Dataset`.
 
@@ -72,22 +54,14 @@ is by using the `sdf_xarray.open_mfdataset`.
 
    If your simulation includes multiple ``output`` blocks that specify different variables
    for output at various time steps, variables not present at a specific step will default
-   to a nan value. To clean your dataset by removing these nan values we suggest using the
-   `xarray.DataArray.dropna` function or :ref:`loading-sparse-data`.
+   to a nan value. To remove these nan values we suggest using the `xarray.DataArray.dropna`
+   function or following our implmentation in :ref:`loading-sparse-data`.
 
 .. jupyter-execute::
 
    sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
 
-Alternatively, you can load the data in as a `xarray.DataTree`, which organises the data
-hierarchically into ``groups`` (for example grouping related quantities such as the individual
-components of the electric and magnetic fields) while keeping each item as a `xarray.Dataset`.
-
-.. jupyter-execute::
-
-   sdfxr.open_mfdatatree("tutorial_dataset_1d/*.sdf")
-
-Alternatively files can be loaded using `xarray.open_mfdataset` however when loading in
+Alternatively, files can be loaded using `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
 `sdf_xarray.SDFPreprocess` function.
@@ -101,6 +75,14 @@ the time dimension; This is done via the ``preprocess`` parameter utilising the
       preprocess=sdfxr.SDFPreprocess()
    )
 
+You can also load the data in as a `xarray.DataTree`, which organises the data
+hierarchically into ``groups`` (for example grouping related quantities such as the individual
+components of the electric and magnetic fields) while keeping each item as a `xarray.Dataset`.
+
+.. jupyter-execute::
+
+   sdfxr.open_mfdatatree("tutorial_dataset_1d/*.sdf")
+
 .. _loading-sparse-data:
 
 Loading sparse data
@@ -142,7 +124,7 @@ multiple files).
 
 .. jupyter-execute::
 
-   xr.open_dataset("tutorial_dataset_1d/0010.sdf", keep_particles=True)
+   sdfxr.open_dataset("tutorial_dataset_1d/0010.sdf", keep_particles=True)
 
 Loading specific variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/unit_conversion.rst b/docs/unit_conversion.rst
@@ -15,9 +15,10 @@ to femto-seconds or particle energy from Joules to electron-volts.
 
 .. jupyter-execute::
 
-    from sdf_xarray import open_mfdataset
+    import sdf_xarray as sdfxr
     import matplotlib.pyplot as plt
     %matplotlib inline
+
     plt.rcParams.update({
         "axes.labelsize": 16,
         "xtick.labelsize": 14,
@@ -45,7 +46,7 @@ We can use the |rescale_coords_accessor| method to convert X, Y, and Z coordinat
 
     fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(16, 6))
 
-    ds = open_mfdataset("tutorial_dataset_2d/*.sdf")
+    ds = sdfxr.open_mfdataset("tutorial_dataset_2d/*.sdf")
     ds_in_microns = ds.epoch.rescale_coords(1e6, "µm", ["X_Grid_mid", "Y_Grid_mid"])
 
     ds["Derived_Number_Density_Electron"].isel(time=0).plot(ax=ax1, x="X_Grid_mid", y="Y_Grid_mid")
@@ -65,7 +66,7 @@ seconds (``s``) to femto-seconds (``fs``) by applying a multiplier of ``1e15``.
 
 .. jupyter-execute::
 
-    ds = open_mfdataset("tutorial_dataset_2d/*.sdf")
+    ds = sdfxr.open_mfdataset("tutorial_dataset_2d/*.sdf")
     ds["time"]
 
 .. jupyter-execute::
@@ -97,15 +98,13 @@ Installation
 
 To install the pint libraries you can simply run the following optional
 dependency pip command which will install both the ``pint`` and ``pint-xarray``
-libraries. You can install these optional dependencies via pip:
+libraries. Once installed the ``xarray.Dataset.pint`` accessor should become
+accessible. You can install these optional dependencies via pip:
 
 .. code:: console
 
     $ pip install "sdf_xarray[pint]"
 
-.. note::
-    Once you install ``pint-xarray`` it is automatically picked up and loaded
-    by the code so you should have access to the ``xarray.Dataset.pint`` accessor.
 
 Quantifying DataArrays
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -117,7 +116,7 @@ Joules and convert it to electron volts.
 
 .. jupyter-execute::
 
-    ds = open_mfdataset("tutorial_dataset_1d/*.sdf")
+    ds = sdfxr.open_mfdataset("tutorial_dataset_1d/*.sdf")
     ds["Total_Particle_Energy_Electron"]
 
 Once you call `xarray.DataArray.pint.quantify` the type is inferred the original