Add a frontend for Quokka dataset

doc/source/examining/loading_data.rst

@@ -2133,6 +2133,182 @@ zero.
 * Particles may be difficult to integrate.
 * Data must already reside in memory.
 
+
+.. _loading-quokka-data:
+
+QUOKKA Data
+-----------
+
+`QUOKKA <https://github.com/quokka-astro/quokka>`_ data is supported and cared
+for by ChongChong He and Rongjun Huang. QUOKKA is based on the AMReX framework.
+Uniform-grid and AMR datasets in cartesian coordinates and particle data are
+fully supported.
+
+A standard QUOKKA dataset includes the following components:
+
+.. code-block:: bash
+
+    plt00007/
+    ├── Level_0/         # QUOKKA data
+    ├── Header           # Dataset header information
+    ├── metadata.yaml    # Configuration file
+    ├── XXX_particles/     # Optional, particle data (e.g., Rad or Sink)
+    │   ├── Fields.yaml    # Particle field names and units
+    │   ├── Header
+    │   └── Level_0/
+
+Loading QUOKKA data is straightforward with the ``load`` command:
+
+.. code-block:: python
+
+    import yt
+
+    ds = yt.load("sample/RadBeam/plt00007")
+
+Boxlib Fields and Units
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The QUOKKA frontend is built upon the AMReX framework, which follows the BoxLib
+data format. When a QUOKKA dataset is loaded, yt automatically:
+
+- Detects and loads all available fields in the dataset from the ``Header`` file
+- Maps the native field names to (field_type, field_name) tuples
+- Assigns physical units based on metadata information
+
+QUOKKA datasets include six mandatory gas fields:
+
+.. code-block:: python
+
+    [
+        ("boxlib", "gasDensity"),
+        ("boxlib", "gasEnergy"),
+        ("boxlib", "gasInternalEnergy"),
+        ("boxlib", "x-GasMomentum"),
+        ("boxlib", "y-GasMomentum"),
+        ("boxlib", "z-GasMomentum"),
+    ]
+
+For simulations with radiative transfer, the following fields are also available:
+
+.. code-block:: python
+
+    [
+        ("boxlib", "radEnergy-Group0"),
+        ("boxlib", "x-RadFlux-Group0"),
+        ("boxlib", "y-RadFlux-Group0"),
+        ("boxlib", "z-RadFlux-Group0"),
+        ("boxlib", "radEnergy-Group1"),
+        ("boxlib", "x-RadFlux-Group1"),
+        ("boxlib", "y-RadFlux-Group1"),
+        ("boxlib", "z-RadFlux-Group1"),
+        ...,
+    ]
+
+To see all available native fields in your dataset, do ``print(ds.field_list)``.
+
+Derived Fields
+^^^^^^^^^^^^^
+
+When a QUOKKA dataset is loaded by yt, the native fields are mapped to derived
+fields with appropriate physical units. The frontend handles:
+
+- Converting dimensionless native fields to physically meaningful units
+- Creating convenient derived fields for analysis and visualization
+
+You can view all available derived fields with ``print(ds.derived_field_list)``.
+For example, the native ('boxlib', 'gasDensity') field is mapped to ('gas',
+'density') with proper units:
+
+.. code-block:: python
+
+    # Accessing density with units
+    print(ds.r[("boxlib", "gasDensity")])
+    print(ds.r[("gas", "density")])
+
+.. code-block:: python
+
+    unyt_array([1.0, 1.0, 1.0, ..., 1.0, 1.0, 1.0], "code_mass/code_length**3")
+    unyt_array([1.0, 1.0, 1.0, ..., 1.0, 1.0, 1.0], "g/cm**3")
+
+Particle Data
+^^^^^^^^^^^^
+
+QUOKKA supports various types of particle data. When particles are present,
+they're stored in dedicated directories:
+
+.. code-block:: bash
+
+    dataset_folder/
+    ├── Level_0/
+    ├── Header
+    ├── metadata.yaml
+    ├── XXX_particles/     # Particle fields (e.g., Rad or Sink or CIC)
+    │   ├── Fields.yaml    # Particle field names and units
+    │   ├── Header
+    │   └── Level_0/
+
+The particle types and fields are automatically detected and loaded. The
+``Fields.yaml`` file defines particle field names and their units, which YT will
+read and automatically convert to physical units.
+
+To access particle data in your analysis:
+
+.. code-block:: python
+
+    # Access particle data
+    ad = ds.all_data()
+
+    # print particle info
+    print(ds.parameters["particle_info"])
+
+    # List particle fields available for the selected particle type
+    print(ad["Rad_particles", "particle_position_x"])
+    print(ad["Rad_particles", "luminosity"])
+
+    # Convert to physical units
+    print(ad["Rad_particles", "luminosity"].to("erg/s"))
+
+To annotate particles in a plot, use the ``annotate_particles`` method:
+
+.. code-block:: python
+
+    yt.SlicePlot(ds, "z", ("gas", "density")).annotate_particles(
+        1, p_size=400.0, col="blue", marker="*", ptype="Rad_particles"
+    )
+
+Face-Centered Variables
+^^^^^^^^^^^^^^^^^^^^^^^
+
+QUOKKA datasets can also include face-centered variables. These are stored in
+the ``fc_vars`` directory which is inside the plotfile directory. When loading a
+Quokka dataset, YT automatically detects and loads any face-centered variables
+from the ``fc_vars/x*****``, ``fc_vars/y*****``, and ``fc_vars/z*****``
+subdirectories. These are made available as attributes of the main dataset
+(``ds.ds_fc_x``, ``ds.ds_fc_y``, ``ds.ds_fc_z``). Each face-centered dataset is a full
+YT dataset object with its own fields and mesh structure, and includes a
+reference back to the parent dataset, ``ds.ds_fc_x.parent_ds``. This allows for
+easy access to both cell-centered and face-centered data in the same analysis
+workflow.
+
+Support for Legacy Datasets
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``metadata.yaml`` file is the key to determining if a dataset is a QUOKKA
+data object. For data generated by early versions of QUOKKA that might be
+missing this file, you can bypass metadata parsing:
+
+.. code-block:: python
+
+    from yt.frontends.amrex.data_structures import QuokkaDataset
+
+
+    class OldQuokkaDataset(QuokkaDataset):
+        def _parse_metadata_file(self):
+            pass
+
+
+    ds_old = OldQuokkaDataset("sample/RadBeam/plt007")
+
 .. _loading-semi-structured-mesh-data:
 
 Semi-Structured Grid Data

pyproject.toml

@@ -89,7 +89,7 @@ Fortran = ["f90nml>=1.1"]
 # We also normalize all target names to lower case for consistency.
 adaptahop = []
 ahf = []
-amrex = []
+amrex = ["PyYAML>=6.0.1"]
 amrvac = ["yt[Fortran]"]
 art = []
 arepo = ["yt[HDF5]"]
@@ -121,6 +121,7 @@ open-pmd = ["yt[HDF5]"]
 owls = ["yt[HDF5]"]
 owls-subfind = ["yt[HDF5]"]
 parthenon = ["yt[HDF5]"]
+quokka = ["PyYAML>=6.0.1"]
 ramses = ["yt[Fortran]", "scipy"]
 rockstar = []
 sdf = ["requests>=2.20.0"]
@@ -181,6 +182,7 @@ full = [
     "yt[owls]",
     "yt[owls_subfind]",
     "yt[parthenon]",
+    "yt[quokka]",
     "yt[ramses]",
     "yt[rockstar]",
     "yt[sdf]",

yt/frontends/amrex/api.py

@@ -11,6 +11,8 @@
     NyxHierarchy,
     OrionDataset,
     OrionHierarchy,
+    QuokkaDataset,
+    QuokkaHierarchy,
     WarpXDataset,
     WarpXHierarchy,
 )
@@ -19,6 +21,7 @@
     CastroFieldInfo,
     MaestroFieldInfo,
     NyxFieldInfo,
+    QuokkaFieldInfo,
     WarpXFieldInfo,
 )
 from .io import IOHandlerBoxlib