Add example in doc to list available IDS+occ in a data-entry (#35)

olivhoenen · olivhoenen · commit ff0f628e6c35 · 2025-06-10T09:06:06.000+02:00
diff --git a/docs/source/courses/basic/analyze.rst b/docs/source/courses/basic/analyze.rst
@@ -246,3 +246,20 @@ Exercise 5
             A plot of :math:`T_e` vs :math:`t`.
 
 .. seealso:: :ref:`Lazy loading`
+
+
+Explore the DBEntry
+'''''''''''''''''''
+
+You may not know apriori which types of IDSs are available within an IMAS database entry.
+It can also happen that several IDSs objects of the same type are stored within
+this entry, in that case each IDS is stored as a separate `occurrence`
+(occurrences are identified with an integer value, 0 being the default).
+
+In IMAS-Python, the function :meth:`~imas.db_entry.DBEntry.list_all_occurrences()` will
+help you finding which occurrences are available in a given database entry and for a given
+IDS type.
+
+The following snippet shows how to list the available IDSs in a given database entry:
+
+.. literalinclude:: imas_snippets/explore_data_entry.py
diff --git a/docs/source/courses/basic/explore.rst b/docs/source/courses/basic/explore.rst
@@ -7,8 +7,8 @@ In this part of the training, we will learn how to use Python to explore data
 saved in IDSs.
 
 
-Explore which IDSs are available
---------------------------------
+Explore which IDS structures are available
+------------------------------------------
 
 Most codes will touch multiple IDSs inside a single IMAS data entry. For example
 a heating code using a magnetic equilibrium from the ``equilibrium`` IDS with a
diff --git a/docs/source/courses/basic/imas_snippets/explore_data_entry.py b/docs/source/courses/basic/imas_snippets/explore_data_entry.py
@@ -0,0 +1,9 @@
+import imas
+
+# Open input data entry
+entry = imas.DBEntry("imas:hdf5?path=<...>","r")
+
+# Print the list of available IDSs with their occurrence
+print([(idsname,occ) for idsname in imas.IDSFactory().ids_names() for occ in entry.list_all_occurrences(idsname)])
+
+entry.close()
