From 4497bb2a8ce9636f8e07e0f3116d61a0b74ff135 Mon Sep 17 00:00:00 2001 From: Olivier Hoenen Date: Fri, 6 Jun 2025 11:36:24 +0200 Subject: [PATCH 1/3] Add example in doc to list available IDS+occ in a data-entry (#35) --- docs/source/courses/basic/analyze.rst | 17 +++++++++++++++++ docs/source/courses/basic/explore.rst | 4 ++-- .../basic/imas_snippets/explore_data_entry.py | 9 +++++++++ 3 files changed, 28 insertions(+), 2 deletions(-) create mode 100644 docs/source/courses/basic/imas_snippets/explore_data_entry.py diff --git a/docs/source/courses/basic/analyze.rst b/docs/source/courses/basic/analyze.rst index d1ae1434..6317cb04 100644 --- 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 index e3395eda..348d9ab4 100644 --- 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 new file mode 100644 index 00000000..cabaf148 --- /dev/null +++ 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() From 930b43f458af65c6828118ba1e8a7e270e538743 Mon Sep 17 00:00:00 2001 From: Olivier Hoenen Date: Fri, 6 Jun 2025 11:52:16 +0200 Subject: [PATCH 2/3] Minor edit --- docs/source/courses/basic/analyze.rst | 4 ++-- .../source/courses/basic/imas_snippets/explore_data_entry.py | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/courses/basic/analyze.rst b/docs/source/courses/basic/analyze.rst index 6317cb04..00b6dd15 100644 --- a/docs/source/courses/basic/analyze.rst +++ b/docs/source/courses/basic/analyze.rst @@ -248,8 +248,8 @@ Exercise 5 .. seealso:: :ref:`Lazy loading` -Explore the DBEntry -''''''''''''''''''' +Explore the DBEntry and occurrences +''''''''''''''''''''''''''''''''''' 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 diff --git a/docs/source/courses/basic/imas_snippets/explore_data_entry.py b/docs/source/courses/basic/imas_snippets/explore_data_entry.py index cabaf148..f49df8d4 100644 --- a/docs/source/courses/basic/imas_snippets/explore_data_entry.py +++ b/docs/source/courses/basic/imas_snippets/explore_data_entry.py @@ -1,9 +1,10 @@ import imas -# Open input data entry +# 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)]) +print([(idsname,occ) for idsname in imas.IDSFactory().ids_names() + for occ in entry.list_all_occurrences(idsname)]) entry.close() From 0806958f72bb136e5a651f14cd1eab006b077b4a Mon Sep 17 00:00:00 2001 From: Olivier Hoenen Date: Fri, 6 Jun 2025 13:56:44 +0200 Subject: [PATCH 3/3] Apply suggestions on code and text of the documentation Co-authored-by: Maarten Sebregts <110895564+maarten-ic@users.noreply.github.com> --- docs/source/courses/basic/analyze.rst | 2 +- .../courses/basic/imas_snippets/explore_data_entry.py | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/courses/basic/analyze.rst b/docs/source/courses/basic/analyze.rst index 00b6dd15..21a7c68b 100644 --- a/docs/source/courses/basic/analyze.rst +++ b/docs/source/courses/basic/analyze.rst @@ -251,7 +251,7 @@ Exercise 5 Explore the DBEntry and occurrences ''''''''''''''''''''''''''''''''''' -You may not know apriori which types of IDSs are available within an IMAS database entry. +You may not know a priori 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). diff --git a/docs/source/courses/basic/imas_snippets/explore_data_entry.py b/docs/source/courses/basic/imas_snippets/explore_data_entry.py index f49df8d4..2ec02698 100644 --- a/docs/source/courses/basic/imas_snippets/explore_data_entry.py +++ b/docs/source/courses/basic/imas_snippets/explore_data_entry.py @@ -1,10 +1,11 @@ import imas # Open input data entry -entry = imas.DBEntry("imas:hdf5?path=<...>","r") +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)]) +for idsname in imas.IDSFactory().ids_names(): + for occ in entry.list_all_occurrences(idsname): + print(idsname, occ) entry.close()