xhermes 0.1.0__tar.gz

xhermes-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: xhermes
+Version: 0.1.0
+Summary: Analyse data from Hermes-3 simulations using xarray
+License: Apache
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Topic :: Scientific/Engineering :: Physics
+Description-Content-Type: text/markdown
+Requires-Dist: xarray
+Requires-Dist: xbout
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: summary
+
+# xHermes
+
+xHermes is a post-processing package for Hermes-3 in 1D, 2D and 3D which provides automatic conversion to SI units and many useful plotting routines.
+
+xHermes a wrapper around [xBOUT](https://github.com/boutproject/xBOUT) to provide [Hermes-3](https://github.com/bendudson/hermes-3) specific 
+features. At the moment, xHermes is used for loading in the Hermes-3 results, performing SI unit conversion and calculating some geometry terms.
+You may still want to use xBOUT, in particular if you are running 2D and 3D cases and want plotting routines for those.
+
+There is also a collection of Mike Kryjak's personal post-processing scripts [sdtools](https://github.com/mikekryjak/sdtools/tree/main/hermes3) which have extensive additional functionality for 1D and 2D postprocessing.
+These scripts are not officially supported, but feel free to take a look.
+It is intended for all those additional features to be merged into xHermes over time.
+
+Both xBOUT and xHermes use [Xarray](https://docs.xarray.dev/en/stable/) which provides a scalable and powerful framework
+for dealing with large amounts of data while preserving dimensional 
+consistency. If you have ever used [Pandas](https://pandas.pydata.org/), you will find Xarray very familiar, as it is effectively Pandas in more dimensions.
+
+While Xarray is based on Numpy arrays under the hood and the data 
+can be accessed in this way, Xarray's main benefit comes in its
+powerful abilities to select, filter and operate on data. The 
+syntax is similar to Pandas and the basics are explained in 
+Xarray's excellent documentation.
+If you are new to Xarray, it may be useful to start with reviewing the [selection syntax](https://docs.xarray.dev/en/stable/user-guide/indexing.html).
+
+## Installation 
+
+Hermes-3 is pip installable. In the terminal with your Python environment enabled, run:
+
+    pip install xhermes
+
+However, you may not be able to get the latest version this way. For now, it is highly recommended you do an editable install instead:
+
+    git clone https://github.com/boutproject/xhermes
+    cd xhermes
+    pip install -e .
+
+In this way, pip will install the Python package from the xHermes folder you cloned. If you use git to checkout branches or modify the contents in any way, it will be automatically work.
+
+## Loading simulations
+
+The data from a Hermes-3 run can be loaded with just
+
+    import xhermes
+    ds = xhermes.open(hermes_simulation_path)
+
+where the `hermes_simulation_path` directory is assumed to contain the `BOUT.dmp.*.nc`
+files and a `BOUT.settings` file. `open` returns an instance of an
+`xarray.Dataset` which contains BOUT- and Hermes-specific information
+in the `attrs`, so represents a general structure for storing all of
+the output of a simulation, including data, input options and (soon)
+grid data.
+
+When working with 2D or 3D simulations of tokamaks, it can be useful to 
+load the grid along with the simulation file and pass the "toroidal" flag to xBOUT:
+
+    import xhermes
+    ds = xhermes.open(hermes_simulation_path, gridfilepath = grid_file_path, geometry = "toroidal")
+
+This loads the metric tensor and grid corner coordinates from the grid which
+enables geometrical operations, polygonal plotting routines and additional metadata on topology.
+
+## Working with the data
+
+### Normalisation and geometry extraction
+
+All variables within Hermes-3 are normalised. The normalisation factors, the units and variable names 
+are provided in the Hermes-3 output for most variables. 
+This information can be accessed for each variable DataArray:
+
+    ds["Pe"].attrs
+
+xHermes automatically applies the unnormalisation when the simulation is loaded in.
+
+When working with 1D and 2D tokamak simulations, it can be useful to extract 
+cell lengths, volumes and cross-sectional areas as well as some additional metadata from the model:
+
+    ds = ds.hermes.extract_1D_tokamak_geometry()
+
+or
+
+    ds = ds.hermes.extract_2D_tokamak_geometry()
+
+### The Dataset
+
+The Dataset `ds` contains useful objects:
+- A DataArray for each variable: `ds.data_vars` shows a list. `ds["Pe"]` returns the Pe DataArray.
+- A DataArray for each coordinate: `ds.coords` shows a list. `ds["t"]` or `ds.coords["t"]` returns the t DataArray.
+- A summary of dimensions in the model: `ds.dims`
+- Model metadata: `ds.metadata`
+- Model input settings: `ds.options`
+
+### The DataArray
+
+The DataArray (e.g. `ds["Pe"]`) contains the array with the variable data, its dimensionality and
+attributes as well as metadata and options inherited from the parent dataset.
+
+A visual summary of the DataArray contents and size can be obtained by simply:
+
+    ds["Pe"]
+
+Note that this may be slow due to the Xarray overhead. To access the underlying data as a Numpy array, one can use:
+
+    ds["Pe"].values
+
+or
+
+    ds["Pe"].data
+
+### Plotting
+Xarray contains a lot of built-in plotting routines which can be used to prepare [excellent 1D and 2D plots](https://docs.xarray.dev/en/stable/user-guide/plotting.html).
+Unfortunately, it is unable to deal with 2D plots in tokamak geometry.
+Routines to plot those are available in xBOUT which has some excellent [example notebooks](https://github.com/boutproject/xBOUT-examples).
+
+
+

xhermes-0.1.0/README.md

@@ -0,0 +1,114 @@
+# xHermes
+
+xHermes is a post-processing package for Hermes-3 in 1D, 2D and 3D which provides automatic conversion to SI units and many useful plotting routines.
+
+xHermes a wrapper around [xBOUT](https://github.com/boutproject/xBOUT) to provide [Hermes-3](https://github.com/bendudson/hermes-3) specific 
+features. At the moment, xHermes is used for loading in the Hermes-3 results, performing SI unit conversion and calculating some geometry terms.
+You may still want to use xBOUT, in particular if you are running 2D and 3D cases and want plotting routines for those.
+
+There is also a collection of Mike Kryjak's personal post-processing scripts [sdtools](https://github.com/mikekryjak/sdtools/tree/main/hermes3) which have extensive additional functionality for 1D and 2D postprocessing.
+These scripts are not officially supported, but feel free to take a look.
+It is intended for all those additional features to be merged into xHermes over time.
+
+Both xBOUT and xHermes use [Xarray](https://docs.xarray.dev/en/stable/) which provides a scalable and powerful framework
+for dealing with large amounts of data while preserving dimensional 
+consistency. If you have ever used [Pandas](https://pandas.pydata.org/), you will find Xarray very familiar, as it is effectively Pandas in more dimensions.
+
+While Xarray is based on Numpy arrays under the hood and the data 
+can be accessed in this way, Xarray's main benefit comes in its
+powerful abilities to select, filter and operate on data. The 
+syntax is similar to Pandas and the basics are explained in 
+Xarray's excellent documentation.
+If you are new to Xarray, it may be useful to start with reviewing the [selection syntax](https://docs.xarray.dev/en/stable/user-guide/indexing.html).
+
+## Installation 
+
+Hermes-3 is pip installable. In the terminal with your Python environment enabled, run:
+
+    pip install xhermes
+
+However, you may not be able to get the latest version this way. For now, it is highly recommended you do an editable install instead:
+
+    git clone https://github.com/boutproject/xhermes
+    cd xhermes
+    pip install -e .
+
+In this way, pip will install the Python package from the xHermes folder you cloned. If you use git to checkout branches or modify the contents in any way, it will be automatically work.
+
+## Loading simulations
+
+The data from a Hermes-3 run can be loaded with just
+
+    import xhermes
+    ds = xhermes.open(hermes_simulation_path)
+
+where the `hermes_simulation_path` directory is assumed to contain the `BOUT.dmp.*.nc`
+files and a `BOUT.settings` file. `open` returns an instance of an
+`xarray.Dataset` which contains BOUT- and Hermes-specific information
+in the `attrs`, so represents a general structure for storing all of
+the output of a simulation, including data, input options and (soon)
+grid data.
+
+When working with 2D or 3D simulations of tokamaks, it can be useful to 
+load the grid along with the simulation file and pass the "toroidal" flag to xBOUT:
+
+    import xhermes
+    ds = xhermes.open(hermes_simulation_path, gridfilepath = grid_file_path, geometry = "toroidal")
+
+This loads the metric tensor and grid corner coordinates from the grid which
+enables geometrical operations, polygonal plotting routines and additional metadata on topology.
+
+## Working with the data
+
+### Normalisation and geometry extraction
+
+All variables within Hermes-3 are normalised. The normalisation factors, the units and variable names 
+are provided in the Hermes-3 output for most variables. 
+This information can be accessed for each variable DataArray:
+
+    ds["Pe"].attrs
+
+xHermes automatically applies the unnormalisation when the simulation is loaded in.
+
+When working with 1D and 2D tokamak simulations, it can be useful to extract 
+cell lengths, volumes and cross-sectional areas as well as some additional metadata from the model:
+
+    ds = ds.hermes.extract_1D_tokamak_geometry()
+
+or
+
+    ds = ds.hermes.extract_2D_tokamak_geometry()
+
+### The Dataset
+
+The Dataset `ds` contains useful objects:
+- A DataArray for each variable: `ds.data_vars` shows a list. `ds["Pe"]` returns the Pe DataArray.
+- A DataArray for each coordinate: `ds.coords` shows a list. `ds["t"]` or `ds.coords["t"]` returns the t DataArray.
+- A summary of dimensions in the model: `ds.dims`
+- Model metadata: `ds.metadata`
+- Model input settings: `ds.options`
+
+### The DataArray
+
+The DataArray (e.g. `ds["Pe"]`) contains the array with the variable data, its dimensionality and
+attributes as well as metadata and options inherited from the parent dataset.
+
+A visual summary of the DataArray contents and size can be obtained by simply:
+
+    ds["Pe"]
+
+Note that this may be slow due to the Xarray overhead. To access the underlying data as a Numpy array, one can use:
+
+    ds["Pe"].values
+
+or
+
+    ds["Pe"].data
+
+### Plotting
+Xarray contains a lot of built-in plotting routines which can be used to prepare [excellent 1D and 2D plots](https://docs.xarray.dev/en/stable/user-guide/plotting.html).
+Unfortunately, it is unable to deal with 2D plots in tokamak geometry.
+Routines to plot those are available in xBOUT which has some excellent [example notebooks](https://github.com/boutproject/xBOUT-examples).
+
+
+

xhermes-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xhermes-0.1.0/setup.py

@@ -0,0 +1,32 @@
+import os
+from setuptools import setup, find_packages
+
+
+# Utility function to read the README file.
+# Used for the long_description.
+def read(fname):
+    return open(os.path.join(os.path.dirname(__file__), fname)).read()
+
+
+setup(
+    name="xhermes",
+    version="0.1.0",
+    description="Analyse data from Hermes-3 simulations using xarray",
+    license="Apache",
+    long_description=read("README.md"),
+    long_description_content_type="text/markdown",
+    classifiers=[
+        "Development Status :: 2 - Pre-Alpha",
+        "Intended Audience :: Science/Research",
+        "Intended Audience :: Education",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: Apache Software License",
+        "Natural Language :: English",
+        "Operating System :: POSIX :: Linux",
+        "Programming Language :: Python :: 3.6",
+        "Topic :: Scientific/Engineering :: Physics",
+    ],
+    install_requires=["xarray", "xbout"],
+    packages=find_packages(),
+    include_package_data=True,
+)

xhermes-0.1.0/xhermes/__init__.py

@@ -0,0 +1,2 @@
+from .load import open_hermesdataset, open
+from .accessors import HermesDatasetAccessor, HermesDataArrayAccessor

xhermes-0.1.0/xhermes/accessors.py

@@ -0,0 +1,249 @@
+from xarray import register_dataset_accessor, register_dataarray_accessor
+from xbout import BoutDatasetAccessor, BoutDataArrayAccessor
+import numpy as np
+
+
+@register_dataset_accessor("hermes")
+class HermesDatasetAccessor(BoutDatasetAccessor):
+    """
+    Methods on Hermes-3 datasets
+    """
+
+    def __init__(self, ds):
+        super().__init__(ds)
+
+    def unnormalise(self):
+        """
+        In-place modify data, converting to SI units
+
+        Normalisation values set in load.open_hermesdataset
+        in attrs['conversion']
+        """
+
+        # Un-normalise data arrays
+        for key, da in self.data.items():
+            da.hermes.unnormalise()
+
+        # Un-normalise coordinates
+        for coord in ["dx", "dy", "dz", "t"]:
+            units_type = self.data[coord].attrs.get("units_type", "unknown")
+            if (units_type == "unknown") or (units_type == "SI"):
+                continue
+            elif units_type == "hermes":
+                # Un-normalise coordinate, modifying in place
+                self.data[coord] = (
+                    self.data[coord] * self.data[coord].attrs["conversion"]
+                )
+                self.data[coord].attrs["units_type"] = "SI"
+            else:
+                raise ValueError("Unrecognised units_type: " + units_type)
+            
+    def extract_1d_tokamak_geometry(self, remove_outer = False):
+        """
+        Process the results to generate 1D relevant geometry data:
+        - Reconstruct pos, the cell position in [m] from upstream from dy
+        - Calculate cross-sectional area da and volume dv
+
+        Notes
+        ----------
+        - dy is technically in flux space, but in 1D 
+          this is the same as in regular space and in units of [m]
+          
+        Returns
+        ----------
+        - Dataset with the new geometry 
+        """
+        ds = self.data.squeeze() # Get rid of 1-length dimensions
+
+        # Reconstruct grid position (pos, as in position) from dy
+        dy = ds.coords["dy"].values
+        n = len(dy)
+        pos = np.zeros(n)
+        pos[0] = 0.5*dy[0]
+
+        for i in range(1,n):
+            pos[i] = pos[i-1] + 0.5*dy[i-1] + 0.5*dy[i]
+            
+        # Set 0 to be at first cell boundary in domain
+        if remove_outer is True:
+            pos -= (pos[2] + pos[3]) / 2     
+        else:
+            pos -= (pos[1] + pos[2]) / 2   
+        
+
+        ds["pos"] = (["y"], pos)
+        
+        # Make pos the main coordinate instead of y
+        ds = ds.swap_dims({"y":"pos"})
+        ds.coords["pos"].attrs = ds.coords["y"].attrs
+        
+        ds["pos"].attrs.update({
+            "conversion" : 1,
+            "units" : "m",
+            "standard_name" : "parallel position",
+            "long_name" : "Parallel connection length"})
+    
+
+        # Derive and append metadata for the cross-sectional area
+        # and volume. The conversions are 1 because the derivation
+        # is from already-normalised parameters
+        ds["da"] = ds.dx * ds.dz * ds.J / np.sqrt(ds.g_22)
+        ds["da"].attrs.update({
+            "conversion" : 1,
+            "units" : "m2",
+            "standard_name" : "cross-sectional area",
+            "long_name" : "Cell parallel cross-sectional area"})
+        
+        ds["dv"] = ds.J * ds.dx * ds.dy * ds.dz 
+        ds["dv"].attrs.update({
+            "conversion" : 1,
+            "units" : "m3",
+            "standard_name" : "cell volume",
+            "long_name" : "Cell Volume"})
+        
+        return ds
+    
+    def extract_2d_tokamak_geometry(self):
+        """
+        Process the results to generate 2D relevant geometry data:
+        
+        Calculates
+        ----------
+        - nxg and nyg, versions of ny and nx which always include guard cells 
+          if they exist in the dataset, and do not include them if they don't
+        - j1_1g, j1_2g, ..., versions of jyseps which account for guards in the 
+          same way as nxg and nyg
+        - x_idx, y_idx: arrays of radial and poloidal indices of all cells
+        - dv, dr, dthe, dl: cell volume and real space cell dimensions
+        - Adds target names to the metadata accounting for single or double null
+        
+        Notes
+        ----------
+        - Adds copies of jyseps1_1 that are shortened to j1_1 etc. 
+          This is potentially annoying.
+        - The reason it's useful to have arrays of coordinate indices
+          is because Xarray is surprisingly awkward when it comes to 
+          obtaining this from the coordinates.
+        - This method has a hardcoded requirement for providing the grid file.
+          
+        Returns
+        ----------
+        - Dataset with the new geometry 
+        """
+        
+        ds = self.data.squeeze()
+        m = ds.metadata
+        
+        if "topology" not in m:
+            raise Exception(
+                "2D Tokamak topology missing from metadata. Please load model with the flag geometry = 'toroidal' and provide grid")
+        
+        # Add theta index to coords so that both X and theta can be accessed index-wise
+        # It is surprisingly hard to extract the index of coordinates in Xarray...
+        ds.coords["theta_idx"] = (["theta"], range(len(ds.coords["theta"])))
+        
+        # Extract target names. This is done here and not in load because load is not 
+        # tokamak specific.
+        if "single-null" in m["topology"]:
+            m["targets"] = ["inner_lower", "outer_lower"]
+        elif "double-null" in m["topology"]:
+            m["targets"] = ["inner_lower", "outer_lower", "inner_upper", "outer_upper"]
+            
+        num_targets = len(m["targets"])
+
+        # nyg, nxg: cell counts which are always with guard cells 
+        # if they exist, or not if they don't
+        if m["keep_xboundaries"] == 0:
+            m["nxg"] = m["nx"] - m["MXG"] * 2 
+            m["MXG"] = 0
+        else:
+            m["nxg"] = m["nx"]
+            
+        if m["keep_yboundaries"] == 0:
+            m["nyg"] = m["ny"]    
+            m["MYG"] = 0
+        else:
+            m["nyg"] = m["ny"] + m["MYG"] * num_targets   
+        
+        # Simplified names of the separatrix indices          
+        m["j1_1"] = m["jyseps1_1"]
+        m["j1_2"] = m["jyseps1_2"]
+        m["j2_1"] = m["jyseps2_1"]
+        m["j2_2"] = m["jyseps2_2"]
+        
+        # Separatrix indices which account for guard cells in the same way as nxg, nyg
+        m["j1_1g"] = m["j1_1"] + m["MYG"]
+        m["j1_2g"] = m["j1_2"] + m["MYG"] * (num_targets - 1)
+        m["j2_1g"] = m["j2_1"] + m["MYG"]
+        m["j2_2g"] = m["j2_2"] + m["MYG"] * (num_targets - 1)
+            
+        # Array of radial (x) indices and of poloidal (y) indices for each cell
+        # This is useful because Xarray makes it awkward to extract indices in certain cases
+        ds["x_idx"] = (["x", "theta"], np.array([np.array(range(m["nxg"]))] * int(m["nyg"])).transpose())
+        ds["y_idx"] = (["x", "theta"], np.array([np.array(range(m["nyg"]))] * int(m["nxg"])))
+        
+        # Cell volume calculation
+        ds["dv"] = (["x", "theta"], ds["dx"].data * ds["dy"].data * ds["dz"].data * ds["J"].data)
+        ds["dv"].attrs.update({
+            "conversion" : 1,
+            "units" : "m3",
+            "standard_name" : "cell volume",
+            "long_name" : "Cell volume",
+            "source" : "xHermes"})
+        
+        # Cell areas in real space - comes from Jacobian
+        # Note: can be calculated from flux space or real space coordinates:
+        # dV = (hthe/Bpol) * (R*Bpol*dr) * dy*2pi = hthe * dy * dr * 2pi * R
+        ds["dr"] = (["x", "theta"], ds.dx.data / (ds.R.data * ds.Bpxy.data))
+        ds["dr"].attrs.update({
+            "conversion" : 1,
+            "units" : "m",
+            "standard_name" : "radial length",
+            "long_name" : "Length of cell in the radial direction",
+            "source" : "xHermes"})
+        
+        ds["hthe"] = (["x", "theta"], ds["J"].data * ds["Bpxy"].data)    # h_theta
+        ds["hthe"].attrs.update({
+            "conversion" : 1,
+            "units" : "m/radian",
+            "standard_name" : "h_theta: poloidal arc length per radian",
+            "long_name" : "h_theta: poloidal arc length per radian",
+            "source" : "xHermes"})
+        
+        ds["dl"] = (["x", "theta"], ds["dy"].data * ds["hthe"].data)    # poloidal arc length
+        ds["dl"].attrs.update({
+            "conversion" : 1,
+            "units" : "m",
+            "standard_name" : "poloidal arc length",
+            "long_name" : "Poloidal arc length",
+            "source" : "xHermes"})
+        
+        return ds
+
+
+@register_dataarray_accessor("hermes")
+class HermesDataArrayAccessor(BoutDataArrayAccessor):
+    """
+    Methods on Hermes-3 arrays
+    """
+
+    def __init__(self, da):
+        super().__init__(da)
+
+    def unnormalise(self):
+        """
+        In-place modify data, converting to SI units
+
+        Normalisation values set in load.open_hermesdataset
+        in attrs['conversion']
+        """
+        units_type = self.data.attrs.get("units_type", "unknown")
+
+        if units_type == "SI":
+            # already un-normalised
+            return
+        elif ("units" in self.data.attrs) and ("conversion" in self.data.attrs):
+            # Normalise using values
+            self.data *= self.data.attrs["conversion"]
+            self.data.attrs["units_type"] = "SI"
+        return self

xhermes-0.1.0/xhermes/load.py

@@ -0,0 +1,425 @@
+from xbout import open_boutdataset
+
+import os
+
+
+def open_hermesdataset(
+    datapath="./BOUT.dmp.*.nc",
+    inputfilepath=None,
+    chunks={},
+    run_name=None,
+    info=False,
+    unnormalise=True,
+    debug_variable_names = False,
+    **kwargs,
+):
+    """
+    Load a dataset from a set of Hermes output files
+
+    Example:
+    ```
+    import xhermes
+    ds = xhermes.open_hermesdataset('data/BOUT.dmp.*.nc')
+    ```
+
+    Returns
+    -------
+
+    ds : xarray.Dataset
+    """
+
+    ds = open_boutdataset(
+        datapath=datapath,
+        inputfilepath=inputfilepath,
+        chunks=chunks,
+        run_name=run_name,
+        info=info,
+        **kwargs,
+    )
+    
+    # Record if guard cells read in or not
+    if "keep_xboundaries" in kwargs:
+        ds.metadata["keep_xboundaries"] = kwargs["keep_xboundaries"]
+    else:
+        ds.metadata["keep_xboundaries"] = True   # Default
+        
+    if "keep_yboundaries" in kwargs:
+        ds.metadata["keep_yboundaries"] = kwargs["keep_yboundaries"]
+    else:
+        ds.metadata["keep_yboundaries"] = False   # Default
+
+    # Normalisation
+    meta = ds.attrs["metadata"]
+    Cs0 = meta["Cs0"]
+    Omega_ci = meta["Omega_ci"]
+    rho_s0 = meta["rho_s0"]
+    Nnorm = meta["Nnorm"]
+    Tnorm = meta["Tnorm"]
+    Bnorm = meta["Bnorm"]
+
+    # SI values
+    Mp = 1.67e-27  # Proton mass
+    e = 1.602e-19  # Coulombs
+
+
+
+    for varname in list(ds.data_vars) + list(ds.coords):
+        da = ds[varname]
+        if len(da.dims) == 4:  # Time-evolving field
+            da.attrs["units_type"] = "hermes"
+
+            # Check if data already has units and conversion attributes
+            if ("units" in da.attrs) and ("conversion" in da.attrs):
+                if debug_variable_names is True:
+                    print(varname + " already annotated")
+                continue  # No need to add attributes
+
+            # Mark as Hermes-normalised data
+            da.attrs["units_type"] = "hermes"
+
+            if varname[:2] == "NV":
+                # Momentum
+                da.attrs.update(
+                    {
+                        "units": "kg m / s",
+                        "conversion": Mp * Nnorm * Cs0,
+                        "standard_name": "momentum",
+                        "long_name": varname[2:] + " parallel momentum",
+                    }
+                )
+            elif varname[0] == "N":
+                # Density
+                da.attrs.update(
+                    {
+                        "units": "m^-3",
+                        "conversion": Nnorm,
+                        "standard_name": "density",
+                        "long_name": varname[1:] + " number density",
+                    }
+                )
+
+            elif varname[0] == "T":
+                # Temperature
+                da.attrs.update(
+                    {
+                        "units": "eV",
+                        "conversion": Tnorm,
+                        "standard_name": "temperature",
+                        "long_name": varname[1:] + " temperature",
+                    }
+                )
+
+            elif varname[0] == "V":
+                # Velocity
+                da.attrs.update(
+                    {
+                        "units": "m / s",
+                        "conversion": Cs0,
+                        "standard_name": "velocity",
+                        "long_name": varname[1:] + " parallel velocity",
+                    }
+                )
+
+            elif varname[0] == "P":
+                # Pressure
+                da.attrs.update(
+                    {
+                        "units": "Pa",
+                        "conversion": e * Tnorm * Nnorm,
+                        "standard_name": "pressure",
+                        "long_name": varname[1:] + " pressure",
+                    }
+                )
+            elif varname == "phi":
+                # Potential
+                da.attrs.update(
+                    {
+                        "units": "V",
+                        "conversion": Tnorm,
+                        "standard_name": "potential",
+                        "long_name": "Plasma potential",
+                    }
+                )
+            else:
+                # Don't know what this is
+                da.attrs["units_type"] = "unknown"
+
+                
+                
+        # Coordinates
+        if varname == "dy":
+            # Poloidal cell angular width
+            da.attrs.update(
+                {
+                    "units": "radian",
+                    "conversion": 1,
+                    "standard_name": "poloidal cell angular width",
+                    "long_name": "Poloidal cell angular width",
+                }
+            )
+        elif varname == "dx":
+            # Radial cell width
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "Wb",
+                    "conversion": rho_s0**2 * Bnorm,
+                    "standard_name": "radial cell width",
+                    "long_name": "Radial cell width in flux space",
+                }
+            )
+        elif varname == "dz":
+            # Radial cell width
+            da.attrs.update(
+                {
+                    "units_type": "SI",
+                    "units": "radian",
+                    "conversion": 1,
+                    "standard_name": "toroidal cell angular width",
+                    "long_name": "Poloidal cell angular width",
+                }
+            )
+        elif varname == "J":
+            # Jacobian
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "m/radian T",
+                    "conversion": rho_s0 / Bnorm,
+                    "standard_name": "Jacobian",
+                    "long_name": "Jacobian to translate from flux to cylindrical coordinates in real space",
+                }
+            )
+        elif varname == "g11":
+            # Metric tensor term
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "T2 m2",
+                    "conversion": (Bnorm * rho_s0)**2,
+                    "standard_name": "g11",
+                    "long_name": "g11 term in the metric tensor",
+                }
+            )
+        elif varname == "g22":
+            # Metric tensor term
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "m-2",
+                    "conversion": 1/(rho_s0)**2,
+                    "standard_name": "g22",
+                    "long_name": "g22 term in the metric tensor",
+                }
+            )
+        elif varname == "g33":
+            # Metric tensor term
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "m-2",
+                    "conversion": 1/(rho_s0)**2,
+                    "standard_name": "g33",
+                    "long_name": "g33 term in the metric tensor",
+                }
+            )
+        elif varname == "g12":
+            # Metric tensor term
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "T",
+                    "conversion": Bnorm,
+                    "standard_name": "g12",
+                    "long_name": "g12 term in the metric tensor",
+                }
+            )
+        elif varname == "g13":
+            # Metric tensor term
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "T",
+                    "conversion": Bnorm,
+                    "standard_name": "g13",
+                    "long_name": "g13 term in the metric tensor",
+                }
+            )
+        elif varname == "g23":
+            # Metric tensor term
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "m-2",
+                    "conversion": 1/(rho_s0)**2,
+                    "standard_name": "g23",
+                    "long_name": "g23 term in the metric tensor",
+                }
+            )
+        elif varname == "g_11":
+            # Metric tensor term
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "T-2m-2",
+                    "conversion": 1/(Bnorm * rho_s0)**2,
+                    "standard_name": "g_11",
+                    "long_name": "g_11 term in the metric tensor",
+                }
+            )
+        elif varname == "g_22":
+            # Metric tensor term
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "m2",
+                    "conversion": (rho_s0)**2,
+                    "standard_name": "g_22",
+                    "long_name": "g_22 term in the metric tensor",
+                }
+            )
+        elif varname == "g_33":
+            # Metric tensor term
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "m2",
+                    "conversion": (rho_s0)**2,
+                    "standard_name": "g_33",
+                    "long_name": "g_33 term in the metric tensor",
+                }
+            )
+        elif varname == "g_12":
+            # Metric tensor term
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "T-1",
+                    "conversion": 1/Bnorm,
+                    "standard_name": "g_12",
+                    "long_name": "g_12 term in the metric tensor",
+                }
+            )
+        elif varname == "g_13":
+            # Metric tensor term
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "T-1",
+                    "conversion": 1/Bnorm,
+                    "standard_name": "g_13",
+                    "long_name": "g_13 term in the metric tensor",
+                }
+            )
+        elif varname == "g_23":
+            # Metric tensor term
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "m2",
+                    "conversion": (rho_s0)**2,
+                    "standard_name": "g_23",
+                    "long_name": "g_23 term in the metric tensor",
+                }
+            )
+        elif varname == "t" or varname == "t_array":
+            # Time
+            da.attrs.update(
+                {
+                    "units_type": "hermes",
+                    "units": "s",
+                    "conversion": 1/Omega_ci,
+                    "standard_name": "time",
+                    "long_name": "Time",
+                }
+            )
+
+    if unnormalise:
+        ds.hermes.unnormalise()
+
+    if ds.attrs["options"] is not None:
+        # Process options
+        options = ds.attrs["options"]
+
+        # List of components
+        component_list = [
+            c.strip() for c in options["hermes"]["components"].strip(" ()\t").split(",")
+        ]
+
+        # Turn into a dictionary
+        components = {}
+        for component in component_list:
+            if component in options:
+                c_opts = options[component]
+                if "type" in c_opts:
+                    c_type = c_opts["type"]
+                else:
+                    c_type = component  # Type is the name of the component
+            else:
+                c_opts = None
+                c_type = component
+            components[component] = {"type": c_type, "options": c_opts}
+        ds.attrs["components"] = components
+        
+        # Identify dimensions
+        dims = list(ds.squeeze().dims)
+        if "t" in dims: dims.remove("t")
+        meta["dimensions"] = len(dims)
+        
+        # Identify species
+        meta["species"] = [x.split("P")[1] for x in ds.data_vars if x.startswith("P") and len(x) < 4]
+        meta["charged_species"] = [x for x in meta["species"] if "e" in x or "+" in x]
+        meta["ion_species"] = [x for x in meta["species"] if "+" in x]
+        meta["neutral_species"] = list(set(meta["species"]).difference(set(meta["charged_species"])))
+        
+        # Prepare dictionary mapping recycling species pairs
+        if "recycling" in ds.attrs["components"]:
+            meta["recycling_pairs"] = dict()
+            for ion in meta["ion_species"]:
+                if "recycle_as" in ds.options[ion].keys():
+                    meta["recycling_pairs"][ion] = ds.options[ion]["recycle_as"]
+                else:
+                    print(f"No recycling partner found for {ion}")
+
+    return ds
+
+
+def open(
+    path,
+    **kwargs,
+):
+    """
+    Open a data directory containing Hermes output files.
+
+    Example:
+    ```
+    import xhermes
+    ds = xhermes.open('data')
+    ```
+    where 'data' is a directory.
+
+    Can also load a grid file containing geometry information:
+
+    Example:
+    ```
+    bd = xhermes.open(".", geometry="toroidal", gridfilepath="../tokamak.nc")
+    ```
+
+    Parameters
+    ----------
+
+    path : string
+        A directory containing BOUT.dmp.* files and a BOUT.settings file
+
+    All other parameters are passed through to `open_hermesdataset`
+
+    Returns
+    -------
+
+    ds : xarray.Dataset
+    """
+    return open_hermesdataset(
+        datapath=os.path.join(path, "BOUT.dmp.*.nc"),
+        inputfilepath=os.path.join(path, "BOUT.settings"),
+        **kwargs,
+    )

xhermes-0.1.0/xhermes/utils.py

@@ -0,0 +1,44 @@
+import xarray
+
+def guard_replace_1d(da):
+    """
+    Replace the inner guard cells with the values of their respective
+    cell edges, i.e. the values at the model inlet and at the target.
+    This is done by interpolating the value between the two neighbouring
+    cell centres. Checks for presence of guard cells if passed a DataArray.
+
+    Cell order at target:
+    ... | last | guard | second guard (unused)
+                ^target      
+        |  -3  |  -2   |      -1
+        
+    Parameters
+    ----------
+    - da: Numpy array or Xarray DataArray with guard cells
+        
+    Returns
+    ----------
+    - Numpy array with guard replacement
+
+    """
+
+    da = da.copy()
+    
+    if type(da) == xarray.core.dataarray.DataArray:
+        if da.metadata["keep_yboundaries"] is False:
+            raise ValueError("Cannot guard replace if y-boundaries are not kept")
+        
+        if da.name in da.coords:
+            raise ValueError("Cannot guard replace DataArray if it is a coordinate, try passing da.values() instead")
+        
+        da[{"pos" : -2}] = (da[{"pos" : -2}] + da[{"pos" : -3}])/2
+        da[{"pos" : 1}] = (da[{"pos" : 1}] + da[{"pos" : 2}])/2
+        
+        da = da.isel(pos = slice(1, -1))
+        
+    else:
+        da[-2] = (da[-2] + da[-3])/2
+        da[1] = (da[1] + da[2])/2
+        da = da[1:-1]
+
+    return da

xhermes-0.1.0/xhermes.egg-info/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: xhermes
+Version: 0.1.0
+Summary: Analyse data from Hermes-3 simulations using xarray
+License: Apache
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Topic :: Scientific/Engineering :: Physics
+Description-Content-Type: text/markdown
+Requires-Dist: xarray
+Requires-Dist: xbout
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: summary
+
+# xHermes
+
+xHermes is a post-processing package for Hermes-3 in 1D, 2D and 3D which provides automatic conversion to SI units and many useful plotting routines.
+
+xHermes a wrapper around [xBOUT](https://github.com/boutproject/xBOUT) to provide [Hermes-3](https://github.com/bendudson/hermes-3) specific 
+features. At the moment, xHermes is used for loading in the Hermes-3 results, performing SI unit conversion and calculating some geometry terms.
+You may still want to use xBOUT, in particular if you are running 2D and 3D cases and want plotting routines for those.
+
+There is also a collection of Mike Kryjak's personal post-processing scripts [sdtools](https://github.com/mikekryjak/sdtools/tree/main/hermes3) which have extensive additional functionality for 1D and 2D postprocessing.
+These scripts are not officially supported, but feel free to take a look.
+It is intended for all those additional features to be merged into xHermes over time.
+
+Both xBOUT and xHermes use [Xarray](https://docs.xarray.dev/en/stable/) which provides a scalable and powerful framework
+for dealing with large amounts of data while preserving dimensional 
+consistency. If you have ever used [Pandas](https://pandas.pydata.org/), you will find Xarray very familiar, as it is effectively Pandas in more dimensions.
+
+While Xarray is based on Numpy arrays under the hood and the data 
+can be accessed in this way, Xarray's main benefit comes in its
+powerful abilities to select, filter and operate on data. The 
+syntax is similar to Pandas and the basics are explained in 
+Xarray's excellent documentation.
+If you are new to Xarray, it may be useful to start with reviewing the [selection syntax](https://docs.xarray.dev/en/stable/user-guide/indexing.html).
+
+## Installation 
+
+Hermes-3 is pip installable. In the terminal with your Python environment enabled, run:
+
+    pip install xhermes
+
+However, you may not be able to get the latest version this way. For now, it is highly recommended you do an editable install instead:
+
+    git clone https://github.com/boutproject/xhermes
+    cd xhermes
+    pip install -e .
+
+In this way, pip will install the Python package from the xHermes folder you cloned. If you use git to checkout branches or modify the contents in any way, it will be automatically work.
+
+## Loading simulations
+
+The data from a Hermes-3 run can be loaded with just
+
+    import xhermes
+    ds = xhermes.open(hermes_simulation_path)
+
+where the `hermes_simulation_path` directory is assumed to contain the `BOUT.dmp.*.nc`
+files and a `BOUT.settings` file. `open` returns an instance of an
+`xarray.Dataset` which contains BOUT- and Hermes-specific information
+in the `attrs`, so represents a general structure for storing all of
+the output of a simulation, including data, input options and (soon)
+grid data.
+
+When working with 2D or 3D simulations of tokamaks, it can be useful to 
+load the grid along with the simulation file and pass the "toroidal" flag to xBOUT:
+
+    import xhermes
+    ds = xhermes.open(hermes_simulation_path, gridfilepath = grid_file_path, geometry = "toroidal")
+
+This loads the metric tensor and grid corner coordinates from the grid which
+enables geometrical operations, polygonal plotting routines and additional metadata on topology.
+
+## Working with the data
+
+### Normalisation and geometry extraction
+
+All variables within Hermes-3 are normalised. The normalisation factors, the units and variable names 
+are provided in the Hermes-3 output for most variables. 
+This information can be accessed for each variable DataArray:
+
+    ds["Pe"].attrs
+
+xHermes automatically applies the unnormalisation when the simulation is loaded in.
+
+When working with 1D and 2D tokamak simulations, it can be useful to extract 
+cell lengths, volumes and cross-sectional areas as well as some additional metadata from the model:
+
+    ds = ds.hermes.extract_1D_tokamak_geometry()
+
+or
+
+    ds = ds.hermes.extract_2D_tokamak_geometry()
+
+### The Dataset
+
+The Dataset `ds` contains useful objects:
+- A DataArray for each variable: `ds.data_vars` shows a list. `ds["Pe"]` returns the Pe DataArray.
+- A DataArray for each coordinate: `ds.coords` shows a list. `ds["t"]` or `ds.coords["t"]` returns the t DataArray.
+- A summary of dimensions in the model: `ds.dims`
+- Model metadata: `ds.metadata`
+- Model input settings: `ds.options`
+
+### The DataArray
+
+The DataArray (e.g. `ds["Pe"]`) contains the array with the variable data, its dimensionality and
+attributes as well as metadata and options inherited from the parent dataset.
+
+A visual summary of the DataArray contents and size can be obtained by simply:
+
+    ds["Pe"]
+
+Note that this may be slow due to the Xarray overhead. To access the underlying data as a Numpy array, one can use:
+
+    ds["Pe"].values
+
+or
+
+    ds["Pe"].data
+
+### Plotting
+Xarray contains a lot of built-in plotting routines which can be used to prepare [excellent 1D and 2D plots](https://docs.xarray.dev/en/stable/user-guide/plotting.html).
+Unfortunately, it is unable to deal with 2D plots in tokamak geometry.
+Routines to plot those are available in xBOUT which has some excellent [example notebooks](https://github.com/boutproject/xBOUT-examples).
+
+
+

xhermes-0.1.0/xhermes.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+setup.py
+xhermes/__init__.py
+xhermes/accessors.py
+xhermes/load.py
+xhermes/utils.py
+xhermes.egg-info/PKG-INFO
+xhermes.egg-info/SOURCES.txt
+xhermes.egg-info/dependency_links.txt
+xhermes.egg-info/requires.txt
+xhermes.egg-info/top_level.txt

xhermes-0.1.0/xhermes.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xhermes-0.1.0/xhermes.egg-info/requires.txt

@@ -0,0 +1,2 @@
+xarray
+xbout

xhermes-0.1.0/xhermes.egg-info/top_level.txt

@@ -0,0 +1 @@
+xhermes