Release 2.3.0

.github/workflows/ci.yml

@@ -57,7 +57,7 @@ jobs:
 
     - name: Cache Zenodo datasets
       id: cache-datasets
-      uses: actions/cache@v4
+      uses: actions/cache/restore@v4
       with:
         path: data
         key: ${{ steps.datasets.outputs.key }}
@@ -70,7 +70,15 @@ jobs:
           echo "Downloading $(basename $url) ..."
           wget -P data/ "$url"
         done
-
+
+    - name: Always save Zenodo datasets (even if pytest would fail)
+      id: cache-datasets-save
+      if: always() && steps.cache-datasets.outputs.cache-hit != 'true'
+      uses: actions/cache/save@v4
+      with:
+        key: ${{ steps.cache-datasets.outputs.cache-primary-key }}
+        path: data
+
     - name: Cache paraview
       id: cache-paraview
       uses: actions/cache/restore@v4
@@ -111,7 +119,7 @@ jobs:
     - name: Run tests
       run: |
         export PATH="$PWD/paraview/bin:$PATH"
-        pvpython --venv venv -m pytest --cov=imas_paraview --cov-report=term-missing --cov-report=html
+        pvpython --venv venv -m pytest --skip-mdsplus --skip-hdf5 --cov=imas_paraview --cov-report=term-missing --cov-report=html
 
     - name: Upload coverage report
       uses: actions/upload-artifact@v4

docs/source/axisymmetric_geometry_reader.rst

@@ -0,0 +1,52 @@
+.. _`using the Geometry Reader (Axisymmetric)`:
+
+Geometry Reader (Axisymmetric)
+==============================
+
+This page explains how to use the Geometry Reader (Axisymmetric) to visualize the axisymmetric active poloidal 
+field coils, as well as axisymmetric passive conductor structures.
+
+Supported IDSs
+--------------
+
+The following IDS and structures are supported in the Geometry Reader (Axisymmetric):
+
+.. list-table::
+   :widths: auto
+   :header-rows: 1
+
+   * - IDS
+     - Structure
+   * - ``pf_active``
+     - `coil geometries <https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/pf_active.html#pf_active-coil-element-geometry>`__
+   * - ``pf_passive``
+     - `loop geometries <https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/pf_passive.html#pf_passive-loop-element-geometry>`__
+   * - ``ferritic``
+     - `axisymmetric geometries <https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/ferritic.html#ferritic-object-axisymmetric>`__
+   * - ``ic_antennas``
+     - `strap geometries <https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/ic_antennas.html#ic_antennas-antenna-module-strap-geometry>`__
+   * - ``iron_core``
+     - `segment geometries <https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/iron_core.html#iron_core-segment-geometry>`__
+
+Using the Geometry Reader (Axisymmetric)
+----------------------------------------
+
+The Geometry Reader (Axisymmetric) functions similarly to the GGD Reader, 
+with the same interface and data loading workflow. 
+This means that the steps for loading an URI, an IDS, and selecting attributes are identical. 
+Refer to the :ref:`using the GGD Reader` for detailed instructions on:
+
+- :ref:`Loading an URI <loading-an-uri>`: How to provide the file path or select a dataset.
+- :ref:`Loading an IDS <loading-an-ids>`: How to load a dataset and display the grid.
+- :ref:`Selecting attribute arrays <selecting-ggd-arrays>`: How to choose and visualize attributes.
+
+Setting the Geometry Resolution
+-------------------------------
+
+The Geometry Reader (Axisymmetric) allows you to change the resolution parameter that 
+controls how many points are used to render the ``arcs_of_circle`` and ``annulus`` geometries.
+
+
+.. figure:: images/annulus_resolution.png
+
+   ``annulus`` geometry element with a resolution of 5 (left) and a resolution of 50 (right)

docs/source/cli.rst

@@ -107,3 +107,61 @@ To convert all time steps that fall between 2.2s and 6.6s:
 .. note:: If the specified time step is not found in the IDS, the time step before the
    specified time step will be used instead.
 
+
+Convert VTK to GGD grids using the CLI
+--------------------------------------
+
+IMAS-ParaView supports converting VTK files to GGD grids in an IDS using the ``vtk2ggd`` command-line tool.
+
+.. tip:: Detailed usage of the CLI tool can be found by running ``vtk2ggd --help``
+
+Usage
+^^^^^
+
+The ``vtk2ggd`` command requires two arguments: the path to VTK files and the output URI where the IDS will be stored.
+
+**Single file conversion:**
+
+.. code-block:: bash
+
+    vtk2ggd example.vtpc imas:hdf5?path=output_db --ids_name edge_profiles
+
+This converts a single ``.vtpc`` file to an IDS, at the given URI.
+
+**File series conversion:**
+
+.. code-block:: bash
+
+    vtk2ggd output_dir/ imas:hdf5?path=output_db
+
+This converts all ``.vtpc`` files in the specified directory to a single IDS with multiple time steps. The files
+should be named following the pattern ``{ids_name}_0.vtpc``, ``{ids_name}_1.vtpc``, etc. The IDS name will be 
+automatically inferred from the file names.
+
+
+VTK File Format Requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``vtk2ggd`` converter has specific requirements for the VTK input files it can process:
+
+* The converter can convert the following VTK files in the XML format:
+
+  - A single ``.vtu`` file containing a vtkUnstructuredGrid.
+  - A single ``.vtpc`` file containing a vtkPartitionedDataSetCollection with a single time step
+  - A directory containing a file series of ``.vtpc`` files (e.g., ``edge_profiles_0.vtpc``, 
+    ``edge_profiles_1.vtpc``, etc.), one for each time step.
+
+* When providing ``.vtpc`` files, each ``vtkPartitionedDataSet`` should contain **exactly one partition** containing a ``vtkUnstructuredGrid``, otherwise the 
+  partition is skipped. Each ``vtkUnstructuredGrid`` will be converted into a separate grid subset in the GGD.
+
+Limitations of VTK grid conversion
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The converter can only output IDSs with:
+
+* a `linear <https://imas-data-dictionary.readthedocs.io/en/latest/generated/identifier/ggd_identifier.html>`_ GGD grid.
+* a single `space of a GGD grid <https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/edge_profiles.html#edge_profiles-grid_ggd-space>`_.
+* `standard space geometries <https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/edge_profiles.html#edge_profiles-grid_ggd-space-geometry_type>`_, not Fourier spaces.
+* X, Y, Z coordinates (`coordinate_identifier.x/y/z <https://imas-data-dictionary.readthedocs.io/en/latest/generated/identifier/coordinate_identifier.html>`_), or R, Phi, Z coordinates (when the ``--cylindrical_coordinates`` flag is enabled).
+* the GGD grid structure itself, not any physical quantities (temperature, density, etc.) defined on the grids in the `ggd <https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/edge_profiles.html#edge_profiles-ggd>`_ AoS.
+* a homogeneous time mode.

docs/source/coils_non_axi_reader.rst

@@ -0,0 +1,57 @@
+.. _`using the Non-Axisymmetric Coils Reader`:
+
+Non-Axisymmetric Coils Reader
+=============================
+
+This page explains how to use the Non-Axisymmetric Coils Reader to visualize the 
+Non-axisymmetric active coil systems.
+
+Supported IDSs
+--------------
+
+The following IDS and structures are supported in the Non-Axisymmetric Coils Reader:
+
+.. list-table::
+   :widths: auto
+   :header-rows: 1
+
+   * - IDS
+     - Structure
+   * - ``coils_non_axisymmetric``
+     - `conductor <https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/coils_non_axisymmetric.html#coils_non_axisymmetric-coil-conductor>`__
+
+Using the Non-Axisymmetric Coils Reader
+---------------------------------------
+
+The Non-Axisymmetric Coils Reader functions similarly to the GGD Reader, with the same interface and data loading workflow. 
+This means that the steps for loading an URI, an IDS, and selecting attributes are identical. 
+Refer to the :ref:`using the GGD Reader` for detailed instructions on:
+
+- :ref:`Loading an URI <loading-an-uri>`: How to provide the file path or select a dataset.
+- :ref:`Loading an IDS <loading-an-ids>`: How to load a dataset and display the grid.
+- :ref:`Selecting attribute arrays <selecting-ggd-arrays>`: How to choose and visualize attributes.
+
+Setting the Geometry Resolution
+-------------------------------
+
+The Non-Axisymmetric Coils Reader allows you to change two resolution parameters that 
+control how coil geometry is discretized for visualization.
+
+Resolution
+^^^^^^^^^^
+
+Defines the number of interpolation points used to represent curved conductor elements (arc_of_circle and full circle). 
+Increasing this value produces smoother coil elements at the cost of higher geometric complexity.
+
+
+.. figure:: images/coils_non_axi_res.png
+
+   Arc of circle element (top) and a full circle element (bottom) with a resolution of 5 (left) and 50 (right)
+
+Cross-sectional Resolution
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Defines the number of interpolation points used to approximate the conductor cross-section when a 
+circular cross-sectional geometry is present. Increasing this value produces a smoother, 
+more circular cross-section.
+

docs/source/scalar_time_trace.rst

@@ -0,0 +1,74 @@
+.. _`using the Scalar Time Trace Reader`:
+
+Scalar Time Trace Reader
+========================
+
+This page explains how to use the Scalar Time Trace Reader to visualize time-dependent scalar 
+data in IDSs.
+
+
+Supported IDSs
+--------------
+
+All IDSs are supported in the Scalar Time Trace Reader. Upon loading an IDS, 
+the reader will automatically scan the IDS for quantities which are: 
+
+- Time-dependent 
+- Either floating point or integer
+- Either a 0D quantity inside a time dependent Array of Structure, or a 1D quantity with time as its coordinate.
+
+Using the Scalar Time Trace Reader
+----------------------------------
+
+The Scalar Time Trace Reader functions similarly to the GGD Reader, 
+with the same interface and data loading workflow. 
+This means that the steps for loading an URI, an IDS, and selecting attributes are identical. 
+Refer to the :ref:`using the GGD Reader` for detailed instructions on:
+
+- :ref:`Loading an URI <loading-an-uri>`: How to provide the file path or select a dataset.
+- :ref:`Loading an IDS <loading-an-ids>`: How to load a dataset and display the grid.
+- :ref:`Selecting attribute arrays <selecting-ggd-arrays>`: How to choose and visualize attributes.
+
+
+Visualizing a time trace
+------------------------
+
+The Scalar Time Trace Reader outputs vtkTable data, containing the time traces of the
+selected quantities. These quantities can be visualized in a 1D line chart plot, with
+time on the horizontal axis.
+After loading the the selected quantities using the steps above, you can visualize the data using
+the 'Line Chart View' in ParaView. 
+See `Paraview's documentation <https://docs.paraview.org/en/latest/UsersGuide/displayingData.html#line-chart-view>`_ 
+to learn more about how to use this view.
+
+Within the 'Line Chart View' options, disable the ``Use Index For X Axis`` option, 
+and in the drop-down menu, select ``Time [s]`` to display time on the horizontal axis in the line chart.
+
+.. tip:: The Line Chart View can be opened side-by-side with other ParaView views. 
+   This means that this reader allows you to visualize how scalar quantities (e.g., the plasma current) 
+   evolve over time, while simultaneously displaying time-dependent 3D geometries loaded from other readers.
+
+This reader supports two ways of visualizing data:
+
+#. Partial Time Trace Up to Selected Time (Default)
+
+   When the ``Show Full Time Trace`` option is disabled in the plugin properties, 
+   the reader outputs only the time trace up to the currently selected time. 
+   This allows you to inspect the evolution of the selected quantities.
+
+   .. figure:: images/full_time_trace_disabled.png
+
+      Plasma current over time with ``Show Full Time Trace`` disabled (default), where
+      the selected time step is 70s.
+
+#. Full Time Trace with Highlighted Current Time
+
+   When the ``Show Full Time Trace`` option is enabled, the reader outputs the complete 
+   time trace for the selected quantities. In addition, a ``Time Marker`` column is outputted, 
+   which marks the currently selected time step. This allows you to see the entire 
+   time series from start to finish.
+
+   .. figure:: images/full_time_trace_enabled.png
+
+       Plasma current over time with ``Show Full Time Trace`` enabled, where
+       the selected time step is 70s.

docs/source/usage.rst

@@ -19,13 +19,16 @@ non-GGD Readers
 ---------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    1d_profiles_reader
    profiles_2d_reader
    beam_reader
+   axisymmetric_geometry_reader
    los_reader
+   coils_non_axi_reader
    position_reader
+   scalar_time_trace
    wall_limiter_reader
 
 Filters

imas_paraview/__init__.py

@@ -48,6 +48,8 @@
 required_imas_python_version = "2.0.0"
 if version.parse(imas_version) < version.parse(required_imas_python_version):
     logger.warning(
-        f"IMAS-Python version {imas_version} is lower than the recommended version "
-        f"{required_imas_python_version}. Some features might not work as expected."
+        "IMAS-Python version %s is lower than the recommended version %s. "
+        "Some features might not work as expected.",
+        imas_version,
+        required_imas_python_version,
     )