Merge branch 'iterorganization:develop' into feature/allow-slices-for-IDSStructArray

Author: prasad-sawantdesai

.github/workflows/test_with_pytest.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]  # Test on multiple Python versions
+        python-version: ["3.10", "3.11", "3.12", "3.13"]  # Test on multiple Python versions
 
     steps:
       - name: Checkout repository

conftest.py

@@ -70,6 +70,13 @@ def pytest_addoption(parser):
     "hdf5": HDF5_BACKEND,
     "mdsplus": MDSPLUS_BACKEND,
 }
+try:
+    from imas.db_entry import DBEntry
+    from imas_core.exception import ImasCoreBackendException
+    DBEntry("imas:mdsplus?path=dummy","r")
+except ImasCoreBackendException as iex:
+    if "not available" in str(iex.message):
+        _BACKENDS.pop("mdsplus")
 
 
 try:

docs/source/changelog.rst

@@ -3,6 +3,44 @@
 Changelog
 =========
 
+What's new in IMAS-Python 2.1.0
+-------------------------------
+
+Build
+'''''
+
+- update Python version support (remove 3.8, add 3.13)
+- add dependency on `imas_core <https://pypi.org/project/imas-core/>`__
+
+
+Improvements
+''''''''''''
+
+- :issue:`84`: improve `imas process-db-analysis` 
+- :issue:`71`: take into account identifier aliases (introduced in DD 4.1)
+- :issue:`78`: disable *implicit* conversion when crossing a major version update
+- improve integration of UDA backend
+- cleaning old AL4 deprecated code
+- :issue:`59`: convert name+identifier (DD3) into description+name (DD4) 
+- improve type hints (following PEP-585 and PEP-604)
+- improve performance of IDS deepcopy 
+- :issue:`60`: improve `equilibrium` DD3->4 by converting `boundary_separatrix` into `contour_tree`
+- :issue:`22`: add custom conversion example in the doc for `em_coupling` IDS
+
+
+Bug fixes
+'''''''''
+
+- fix testcases with coordinate validation issues
+- :issue:`80`: fix `imas print` when using netcdf and imas_core is not present
+- :issue:`61`: special DD3->4 rule to flip sign quantities missing the `cocos_label_transform attribute` in DD
+- :merge:`58`: fix unclear provenance capture
+- :merge:`57`: fix 0D arrays from lazy loading with netcdf
+- :issue:`55`: handle missing case when converting 3.42->4 (_tor->_phi)
+  
+
+
+
 What's new in IMAS-Python 2.0.1
 -------------------------------
 
@@ -74,9 +112,9 @@ Bug fixes
     Dictionary 4.0.0 and 3.42.0. In other cases, the Data Dictionary version is
     now explicitly indicated.
 
-- :issue:`IMAS-5560`: Fix a bug where IMASPy would not correctly recognize that
+- IMAS-5560: Fix a bug where IMASPy would not correctly recognize that
   the UDA backend is used.
-- :issue:`IMAS-5541`: Fix a bug when converting a closed contour to Data
+- IMAS-5541: Fix a bug when converting a closed contour to Data
   Dictionary version 4.0.0.
 - Work around incorrect Data Dictionary 3.x metadata when converting
   ``flux_loop/flux`` in the ``magnetics`` IDS to Data Dictionary version 4.0.0.

docs/source/conf.py

@@ -39,21 +39,21 @@
 iter_projects = "https://github.com/iterorganization/"
 dd_url = urljoin(iter_projects, "imas-data-dictionary/")
 al_url = urljoin(iter_projects, "imas-core/")
-issue_url = jira_url = "https://github.com/iterorganization/IMAS-Python/issues"
 
 # IMAS-Python
 repository_url = f"{iter_projects}/{src_project}/"
 blob_url = repository_url
-mr_url = urljoin(repository_url, "/pulls")
+issue_url = urljoin(repository_url, "issues/")
+mr_url = urljoin(repository_url, "pull/")
 
 
 # Configuration of sphinx.ext.extlinks
 # See https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 # unique name: (base URL, label prefix)
 extlinks = {
     "src": (blob_url + "%s", "%s"),
-    "issue": (issue_url + "%s", "%s"),
-    "merge": (mr_url + "%s", "!%s"),
+    "issue": (issue_url + "%s", "#%s"),
+    "merge": (mr_url + "%s", "#%s"),
     "dd": (dd_url + "%s", "%s"),
     "al": (al_url + "%s", "%s"),
     "pypa": ("https://packaging.python.org/%s", None),

docs/source/identifiers.rst

@@ -11,13 +11,16 @@ enumerated list of options for defining, for example:
   a neutron, or a photon.
 - Plasma heating may come from neutral beam injection, electron cyclotron heating,
   ion cyclotron heating, lower hybrid heating, alpha particles.
+- These may have alternative naming conventions supported through aliases 
+  (e.g., "235U" and "U_235" for Uranium 235).
 
-Identifiers are a list of possible valid labels. Each label has three
+Identifiers are a list of possible valid labels. Each label has up to four
 representations:
 
 1. An index (integer)
 2. A name (short string)
 3. A description (long string)
+4. List of aliases (list of short strings)
 
 
 Identifiers in IMAS-Python
@@ -44,6 +47,15 @@ the available identifiers is stored as ``imas.identifiers.identifiers``.
     print(csid.total.index)
     print(csid.total.description)
 
+    # Access identifiers with aliases (when available)
+    mid = imas.identifiers.materials_identifier
+    print(mid["235U"].name)        # Access by canonical name
+    print(mid["U_235"].name)       # Access by alias
+    
+    # Both return the same object
+    assert mid["235U"].name is mid["U_235"].name
+    assert mid["235U"].name is mid.U_235.name
+
     # Item access is also possible
     print(identifiers["edge_source_identifier"])
 
@@ -64,8 +76,8 @@ Assigning identifiers in IMAS-Python
 
 IMAS-Python implements smart assignment of identifiers. You may assign an identifier
 enum value (for example ``imas.identifiers.core_source_identifier.total``), a
-string (for example ``"total"``) or an integer (for example ``"1"``) to an
-identifier structure (for example ``core_profiles.source[0].identifier``) to set
+string (for example ``"total"`` or its alias), or an integer (for example ``"1"``) 
+to an identifier structure (for example ``core_profiles.source[0].identifier``) to set
 all three child nodes ``name``, ``index`` and ``description`` in one go. See
 below example:
 
@@ -86,6 +98,20 @@ below example:
     # 3. Assign an integer. This looks up the index in the identifier enum:
     core_sources.source[0].identifier = 1
 
+    # Identifiers can still be assigned with the old alias name for backward compatibility:
+    wallids = imas.IDSFactory().wall()
+    wallids.description_ggd.resize(1)
+    wallids.description_ggd[0].material.resize(1)
+    wallids.description_ggd[0].material[0].grid_subset.resize(1)
+    mat = wallids.description_ggd[0].material[0].grid_subset[0].identifiers
+    mat.names.extend([""] * 1)
+    mid = imas.identifiers.materials_identifier
+    # Assign using canonical name
+    mat.names[0] = "235U"
+    # Or assign using alias (equivalent to above)
+    mat.names[0] = mid["U_235"].name
+    mat.names[0] = mid.U_235.name
+
     # Inspect the contents of the structure
     imas.util.inspect(core_sources.source[0].identifier)
 
@@ -101,18 +127,78 @@ below example:
     imas.util.inspect(core_sources.source[1].identifier)
 
 
+Identifier aliases
+------------------
+
+Some identifiers may have multiple aliases defined in the Data Dictionary. Aliases are
+former names kept as an option to ensure better backward compatibility after a change
+and support multiple naming conventions. An identifier can have any number of
+comma-separated aliases.
+
+Aliases can be accessed in the same ways as canonical names, and all aliases for an
+identifier point to the same object.
+
+Aliases that begin with a number (e.g., 235U) cannot be accessed using dot notation 
+(e.g., material_identifier.235U) due to Python's syntax restrictions. Instead, such
+aliases must be accessed using dictionary-style indexing, for example:
+material_identifier["235U"].
+
+.. code-block:: python
+    :caption: Working with identifier aliases
+
+    import imas
+
+    # Get materials identifier which has some aliases defined
+    mid = imas.identifiers.materials_identifier
+    
+    # Access by canonical name
+    uranium235_by_name = mid["235U"]
+    print(f"Name: {uranium235_by_name.name}")
+    print(f"Aliases: {uranium235_by_name.aliases}")  # List of all aliases
+    print(f"First alias: {uranium235_by_name.alias}")  # First alias for compatibility
+    print(f"Index: {uranium235_by_name.index}")
+    print(f"Description: {uranium235_by_name.description}")
+    
+    # Access by any alias - all return the same object
+    uranium235_by_alias1 = mid["U_235"].name
+    uranium235_by_alias2 = mid["Uranium_235"].name
+    print(f"Same objects: {uranium235_by_name is uranium235_by_alias1 is uranium235_by_alias2}")
+    
+    # You can also use attribute access for aliases (when valid Python identifiers)
+    uranium235_by_attr = mid.U_235.name
+    print(f"Same object: {uranium235_by_name is uranium235_by_attr}")
+    
+    # When assigning to IDS structures, alias works the following way
+    wallids = imas.IDSFactory().wall()
+    wallids.description_ggd.resize(1)
+    wallids.description_ggd[0].material.resize(1)
+    wallids.description_ggd[0].material[0].grid_subset.resize(1)
+    mat = wallids.description_ggd[0].material[0].grid_subset[0].identifiers
+    mat.names.extend([""] * 1)
+    mat.indices.resize(1)
+    mat.descriptions.extend([""] * 1)
+    mat.indices[0] = 20
+    mat.descriptions[0] = "Uranium 235 isotope"
+    
+    # These assignments are all equivalent:
+    mat.names[0] = "235U"          # canonical name
+    mat.names[0] = mid["235U"].name  # enum value
+    mat.names[0] = mid.U_235.name  # enum value via alias
+    mat.names[0] = mid["U_235"].name  # enum value via alias
+
 Compare identifiers
 -------------------
 
 Identifier structures can be compared against the identifier enum as well. They
 compare equal when:
 
 1.  ``index`` is an exact match
-2.  ``name`` is an exact match, or ``name`` is not filled in the IDS node
+2.  ``name`` is an exact match, or ``name`` matches an alias, or ``name`` is not filled in the IDS node
 
 The ``description`` does not have to match with the Data Dictionary definition,
 but a warning is logged if the description in the IDS node does not match with
-the Data Dictionary description:
+the Data Dictionary description. The comparison also takes aliases into account,
+so an identifier will match both its canonical name and any defined alias:
 
 .. code-block:: python
     :caption: Comparing identifiers
@@ -139,6 +225,15 @@ the Data Dictionary description:
     >>> core_sources.source[0].identifier.name = "totalX"
     >>> core_sources.source[0].identifier == csid.total
     False
+    >>> # Alias comparison example with materials identifier
+    >>> mid = imas.identifiers.materials_identifier
+    >>> cxr = imas.IDSFactory().camera_x_rays()
+    >>> mat = cxr.filter_window.material
+    >>> mat.index = 20
+    >>> mat.name = "U_235"  # Using alias
+    >>> # Compares equal to the canonical identifier even though name is alias
+    >>> mat == mid["235U"].name
+    True
 
 
 .. seealso::

imas/backends/netcdf/nc2ids.py

@@ -157,6 +157,8 @@ def run(self, lazy: bool) -> None:
                     for index, node in indexed_tree_iter(self.ids, target_metadata):
                         value = data[index]
                         if value != getattr(var, "_FillValue", None):
+                            if isinstance(value, np.generic):
+                                value = value.item()
                             # NOTE: bypassing IDSPrimitive.value.setter logic
                             node._IDSPrimitive__value = value
 
@@ -166,10 +168,16 @@ def run(self, lazy: bool) -> None:
                 # here, we'll let IDSPrimitive.value.setter take care of it:
                 self.ids[target_metadata.path].value = data
 
-            else:
+            # We need to unpack 0D ints, floats and complex numbers. For better
+            # performance this check is done outside the for-loop:
+            elif metadata.ndim or metadata.data_type is IDSDataType.STR:
                 for index, node in indexed_tree_iter(self.ids, target_metadata):
                     # NOTE: bypassing IDSPrimitive.value.setter logic
                     node._IDSPrimitive__value = data[index]
+            else:
+                for index, node in indexed_tree_iter(self.ids, target_metadata):
+                    # NOTE: bypassing IDSPrimitive.value.setter logic
+                    node._IDSPrimitive__value = data[index].item()  # Unpack 0D value
 
     def validate_variables(self) -> None:
         """Validate that all variables in the netCDF Group exist and match the DD."""
@@ -365,7 +373,7 @@ def get_child(self, child):
                 value = var[self.index]
 
             if value is not None:
-                if isinstance(value, np.ndarray):
+                if isinstance(value, (np.ndarray, np.generic)):
                     if value.ndim == 0:  # Unpack 0D numpy arrays:
                         value = value.item()
                     else: