Merge pull request #4323 from forrestglines/parthenon-frontend

Add `Parthenon` frontend

Author: neutrinoceros

doc/source/analyzing/fields.rst

@@ -439,9 +439,9 @@ which results in:
     p_B = \frac{B^2}{2} \\
     v_A = \frac{B}{\sqrt{\rho}}
 
-Using this convention is currently only available for :ref:`Athena<loading-athena-data>`
-and :ref:`Athena++<loading-athena-pp-data>` datasets, though it will likely be available
-for more datasets in the future.
+Using this convention is currently only available for :ref:`Athena<loading-athena-data>`,
+:ref:`Athena++<loading-athena-pp-data>`, and :ref:`AthenaPK<loading-parthenon-data>` datasets,
+though it will likely be available for more datasets in the future.
 
 yt automatically detects on a per-frontend basis what units the magnetic should be in, and allows conversion between
 different magnetic field units in the different unit systems as well. To determine how to set up special magnetic field handling when designing a new frontend, check out

doc/source/examining/loading_data.rst

@@ -553,6 +553,123 @@ using a ``parameters`` dict, accepting the following keys:
   release.
 * Domains may be visualized assuming periodicity.
 
+.. _loading-parthenon-data:
+
+Parthenon Data
+--------------
+
+Parthenon HDF5 data is supported and cared for by Forrest Glines and Philipp Grete.
+The Parthenon framework is the basis for various downstream codes, e.g.,
+`AthenaPK <https://github.com/parthenon-hpc-lab/athenapk>`_,
+`Phoebus <https://github.com/lanl/phoebus>`_,
+`KHARMA <https://github.com/AFD-Illinois/kharma>`_,
+RIOT, and the
+`parthenon-hydro <https://github.com/parthenon-hpc-lab/parthenon-hydro>`_ miniapp.
+Support for these codes is handled through the common Parthenon frontend with
+specifics described in the following.
+Note that only AthenaPK data is currently automatically converted to the
+standard fields known by yt.
+For other codes, the raw data of the fields stored in the output file is accessible
+and a conversion between those fields and yt standard fields needs to be done manually.
+
+   .. rubric:: Caveats
+
+* Reading particle data from Parthenon output is currently not supported.
+* Spherical and cylindrical coordinates only work for AthenaPK data.
+* Only periodic boundary conditions are properly handled. Calculating quantities requiring
+larger stencils (like derivatives) will be incorrect at mesh boundaries that are not periodic.
+
+AthenaPK
+^^^^^^^^
+
+Fluid data on uniform-grid, SMR, and AMR datasets in Cartesian coordinates are fully supported.
+
+AthenaPK data may contain information on units in the output (when specified
+via the ``<units>`` block in the input file when the simulation was originally run).
+If that information is present, it will be used by yt.
+Otherwise the default unit system will be the code unit
+system with conversion of 1 ``code_length`` equalling 1 cm, and so on (given yt's default
+cgs/"Gaussian" unit system).  If you would like to provided different
+conversions, you may supply conversions for length, time, and mass to ``load``
+using the ``units_override`` functionality:
+
+.. code-block:: python
+
+   import yt
+
+   units_override = {
+       "length_unit": (1.0, "Mpc"),
+       "time_unit": (1.0, "Myr"),
+       "mass_unit": (1.0e14, "Msun"),
+   }
+
+   ds = yt.load("parthenon.restart.final.rhdf", units_override=units_override)
+
+This means that the yt fields, e.g. ``("gas","density")``,
+``("gas","velocity_x")``, ``("gas","magnetic_field_x")``, will be in cgs units
+(or whatever unit system was specified), but the AthenaPK fields, e.g.,
+``("parthenon","prim_density")``, ``("parthenon","prim_velocity_1")``,
+``("parthenon","prim_magnetic_field_1")``, will be in code units.
+
+The default normalization for various magnetic-related quantities such as
+magnetic pressure, Alfven speed, etc., as well as the conversion between
+magnetic code units and other units, is Gaussian/CGS, meaning that factors
+of :math:`4\pi` or :math:`\sqrt{4\pi}` will appear in these quantities, e.g.
+:math:`p_B = B^2/8\pi`. To use the Lorentz-Heaviside normalization instead,
+in which the factors of :math:`4\pi` are dropped (:math:`p_B = B^2/2), for
+example), set ``magnetic_normalization="lorentz_heaviside"`` in the call to
+``yt.load``:
+
+.. code-block:: python
+
+    ds = yt.load(
+        "parthenon.restart.final.rhdf",
+        units_override=units_override,
+        magnetic_normalization="lorentz_heaviside",
+    )
+
+Alternative values (i.e., overriding the default ones stored in the simulation
+output) for the following simulation parameters may be specified
+using a ``parameters`` dict, accepting the following keys:
+
+* ``gamma``: ratio of specific heats, Type: Float. If not specified,
+  :math:`\gamma = 5/3` is assumed.
+* ``mu``: mean molecular weight, Type: Float. If not specified, :math:`\mu = 0.6`
+  (for a fully ionized primordial plasma) is assumed.
+
+Other Parthenon based codes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As mentioned above, a default conversion from code fields to yt fields (e.g.,
+from a density field to ``("gas","density")``) is currently not available --
+though more specialized frontends may be added in the future.
+
+All raw data of a Parthenon-based simulation output is available through
+the ``("parthenon","NAME")`` fields where ``NAME`` varies between codes
+and the respective code documentation should be consulted.
+
+One option to manually convert those raw fields to the standard yt fields
+is by adding derived fields, e.g., for the field named "``mass.density``"
+that is stored in cgs units on disk:
+
+.. code-block:: python
+
+    from yt import derived_field
+
+
+    @derived_field(name="density", units="g*cm**-3", sampling_type="cell")
+    def _density(field, data):
+        return data[("parthenon", "mass.density")] * yt.units.g / yt.units.cm**3
+
+Moreover, an ideal equation of state is assumed with the following parameters,
+which may be specified using a ``parameters`` dict, accepting the following keys:
+
+* ``gamma``: ratio of specific heats, Type: Float. If not specified,
+  :math:`\gamma = 5/3` is assumed.
+* ``mu``: mean molecular weight, Type: Float. If not specified, :math:`\mu = 0.6`
+  (for a fully ionized primordial plasma) is assumed.
+
+
 .. _loading-orion-data:
 
 AMReX / BoxLib Data

doc/source/reference/code_support.rst

@@ -70,6 +70,8 @@ each supported output format using yt.
 +-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
 | OWLS/EAGLE            |     Y      |     Y     |      Y     |   Y   |    Y     |    Y     |     Y      |   Full      |
 +-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
+| Parthenon             |     Y      |     N     |      Y     |   Y   |    Y     |    Y     |     Y      | Partial     |
++-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
 | Piernik               |     Y      |    N/A    |      Y     |   Y   |    Y     |    Y     |     Y      |   Full      |
 +-----------------------+------------+-----------+------------+-------+----------+----------+------------+-------------+
 | Pluto                 |     Y      |     N     |      Y     |   Y   |    Y     |    Y     |     Y      | Partial     |

pyproject.toml

@@ -124,6 +124,7 @@ nc4-cm1 = ["yt[netCDF4]"]
 open-pmd = ["yt[HDF5]"]
 owls = ["yt[HDF5]"]
 owls-subfind = ["yt[HDF5]"]
+parthenon = ["yt[HDF5]"]
 ramses = ["yt[Fortran]"]
 rockstar = []
 sdf = ["requests>=2.20.0"]
@@ -183,6 +184,7 @@ full = [
     "yt[open_pmd]",
     "yt[owls]",
     "yt[owls_subfind]",
+    "yt[parthenon]",
     "yt[ramses]",
     "yt[rockstar]",
     "yt[sdf]",
@@ -353,6 +355,7 @@ addopts = '''
     --ignore-glob='/*/yt/frontends/open_pmd/tests/test_outputs.py'
     --ignore-glob='/*/yt/frontends/owls/tests/test_outputs.py'
     --ignore-glob='/*/yt/frontends/owls_subfind/tests/test_outputs.py'
+    --ignore-glob='/*/yt/frontends/parthenon/tests/test_outputs.py'
     --ignore-glob='/*/yt/frontends/ramses/tests/test_outputs.py'
     --ignore-glob='/*/yt/frontends/rockstar/tests/test_outputs.py'
     --ignore-glob='/*/yt/frontends/tipsy/tests/test_outputs.py'

tests/tests.yaml

@@ -171,6 +171,11 @@ answer_tests:
   local_nc4_cm1_002: # PR  2176, 2998
     - yt/frontends/nc4_cm1/tests/test_outputs.py:test_cm1_mesh_fields
 
+  local_parthenon_001: # PR 4323
+    - yt/frontends/parthenon/tests/test_outputs.py:test_loading_data
+    - yt/frontends/parthenon/tests/test_outputs.py:test_cluster
+    - yt/frontends/parthenon/tests/test_outputs.py:test_derived_fields
+
 other_tests:
   unittests:
      # keep in sync with nose_ignores.txt

yt/frontends/__init__.py

@@ -35,6 +35,7 @@
     "open_pmd",
     "owls",
     "owls_subfind",
+    "parthenon",
     "ramses",
     "rockstar",
     "sdf",

yt/frontends/parthenon/__init__.py

@@ -0,0 +1,4 @@
+from . import tests
+from .data_structures import ParthenonDataset, ParthenonGrid, ParthenonHierarchy
+from .fields import ParthenonFieldInfo
+from .io import IOHandlerParthenon