added support of slicing for IDSStructArray

.gitignore

@@ -5,7 +5,7 @@ __pycache__/
 
 # C extensions
 *.so
-
+myenv
 # Distribution / packaging
 .Python
 env/

docs/source/api.rst

@@ -19,4 +19,5 @@ IMAS-Python IDS manipulation
    ids_toplevel.IDSToplevel
    ids_primitive.IDSPrimitive
    ids_structure.IDSStructure
+   ids_slice.IDSSlice
    ids_struct_array.IDSStructArray

docs/source/array_slicing.rst

@@ -0,0 +1,131 @@
+.. _array-slicing:
+
+Array Slicing
+=============
+
+The ``IDSStructArray`` class supports Python's standard slicing syntax.
+
+Key Difference
+---------------
+
+- ``array[0]`` returns ``IDSStructure`` (single element)
+- ``array[:]`` or ``array[1:5]`` returns ``IDSSlice`` (collection with ``values()`` method)
+
+Basic Usage
+-----------
+
+.. code-block:: python
+
+    import imas
+
+    entry = imas.DBEntry("imas:hdf5?path=my-testdb")
+    cp = entry.get("core_profiles")
+
+    # Integer indexing
+    first = cp.profiles_1d[0]           # IDSStructure
+    last = cp.profiles_1d[-1]           # IDSStructure
+
+    # Slice operations
+    subset = cp.profiles_1d[1:5]        # IDSSlice
+    every_other = cp.profiles_1d[::2]   # IDSSlice
+
+    # Access nested arrays
+    all_ions = cp.profiles_1d[:].ion[:]  # IDSSlice of individual ions
+
+    # Extract values
+    labels = all_ions.label.values()
+
+Multi-Dimensional Slicing
+---------------------------
+
+The ``IDSSlice`` class supports multi-dimensional shape tracking and array conversion.
+
+**Check shape of sliced data:**
+
+.. code-block:: python
+
+    # Get shape information for multi-dimensional data
+    print(cp.profiles_1d[:].grid.shape)              # (106,)
+    print(cp.profiles_1d[:].ion.shape)               # (106, ~3)
+    print(cp.profiles_1d[1:3].ion[0].element.shape)  # (2, ~3)
+
+**Extract values with shape preservation:**
+
+.. code-block:: python
+
+    # Extract as list
+    grid_values = cp.profiles_1d[:].grid.values()
+
+    # Extract as numpy array
+    grid_array = cp.profiles_1d[:].grid.to_array()
+
+    # Extract as numpy array
+    ion_array = cp.profiles_1d[:].ion.to_array() 
+
+**Nested structure access:**
+
+.. code-block:: python
+
+    # Access through nested arrays
+    grid_data = cp.profiles_1d[1:3].grid.rho_tor.to_array()
+
+    # Ion properties across multiple profiles
+    ion_labels = cp.profiles_1d[:].ion[:].label.to_array()
+    ion_charges = cp.profiles_1d[:].ion[:].z_ion.to_array()
+
+Common Patterns
+---------------
+
+**Process a range:**
+
+.. code-block:: python
+
+    for element in cp.profiles_1d[5:10]:
+        print(element.time)
+
+**Iterate over nested arrays:**
+
+.. code-block:: python
+
+    for ion in cp.profiles_1d[:].ion[:]:
+        print(ion.label.value)
+
+**Get all values:**
+
+.. code-block:: python
+
+    times = cp.profiles_1d[:].time.values()
+
+    # Or as numpy array
+    times_array = cp.profiles_1d[:].time.to_array()
+
+Important: Array-wise Indexing
+-------------------------------
+
+When accessing attributes through a slice of ``IDSStructArray`` elements,
+the slice operation automatically applies to each array (array-wise indexing):
+
+.. code-block:: python
+
+    # Array-wise indexing: [:] applies to each ion array
+    all_ions = cp.profiles_1d[:].ion[:]
+    labels = all_ions.label.values()
+
+    # Equivalent to manually iterating:
+    labels = []
+    for profile in cp.profiles_1d[:]:
+        for ion in profile.ion:
+            labels.append(ion.label.value)
+
+Lazy-Loaded Arrays
+-------------------
+
+Both individual indexing and slicing work with lazy loading:
+
+.. code-block:: python
+
+    element = lazy_array[0]      # OK - loads on demand
+    subset = lazy_array[1:5]     # OK - loads only requested elements on demand
+
+When slicing lazy-loaded arrays, only the elements in the slice range are loaded,
+making it memory-efficient for large datasets.

docs/source/courses/advanced/explore.rst

@@ -72,6 +72,32 @@ structures (modeled by :py:class:`~imas.ids_struct_array.IDSStructArray`) are (a
 name applies) arrays containing :py:class:`~imas.ids_structure.IDSStructure`\ s. Data
 nodes can contain scalar or array data of various types.
 
+**Slicing Arrays of Structures**
+
+Arrays of structures support Python slice notation, which returns an
+:py:class:`~imas.ids_slice.IDSSlice` object containing matched elements:
+
+.. code-block:: python
+
+    import imas
+
+    core_profiles = imas.IDSFactory().core_profiles()
+    core_profiles.profiles_1d.resize(10)  # Create 10 profiles
+
+    # Integer indexing returns a single structure
+    first = core_profiles.profiles_1d[0]
+
+    # Slice notation returns an IDSSlice
+    subset = core_profiles.profiles_1d[2:5]      # Elements 2, 3, 4
+    every_other = core_profiles.profiles_1d[::2] # Every second element
+
+    # IDSSlice supports array-wise indexing and values() for data access
+    all_ions = core_profiles.profiles_1d[:].ion[:]
+    for ion in all_ions:
+        print(ion.label.value)
+
+For detailed information on slicing operations, see :doc:`../../array_slicing`.
+
 Some methods and properties are defined for all data nodes and arrays of structures:
 
 ``len(<node>)``

docs/source/imas_architecture.rst

@@ -168,6 +168,12 @@ The following submodules and classes represent IDS nodes.
     :py:class:`~imas.ids_struct_array.IDSStructArray` class, which models Arrays of
     Structures. It also contains some :ref:`dev lazy loading` logic.
 
+-   :py:mod:`imas.ids_slice` contains the
+    :py:class:`~imas.ids_slice.IDSSlice` class, which represents a collection of IDS
+    nodes matching a slice expression. It provides slicing operations on
+    :py:class:`~imas.ids_struct_array.IDSStructArray` elements with array-wise
+    indexing and supports the ``values()`` method for extracting raw data.
+
 -   :py:mod:`imas.ids_structure` contains the
     :py:class:`~imas.ids_structure.IDSStructure` class, which models Structures. It
     contains the :ref:`lazy instantiation` logic and some of the :ref:`dev lazy loading`

docs/source/index.rst

@@ -50,6 +50,7 @@ Manual
    configuring
    cli
    netcdf
+   array_slicing
    changelog
    examples
 

docs/source/intro.rst

@@ -154,3 +154,38 @@ can use ``<IDS>.get()`` to load IDS data from disk:
     >>> dbentry2 = imas.DBEntry("mypulsefile.nc","r")
     >>> core_profiles2 = dbentry2.get("core_profiles")
     >>> print(core_profiles2.ids_properties.comment.value)
+
+
+.. _`Multi-Dimensional Slicing`:
+
+Multi-Dimensional Slicing
+''''''''''''''''''''''''''
+
+IMAS-Python supports advanced slicing of hierarchical data structures with automatic
+shape tracking and array conversion to numpy. This enables intuitive access to
+multi-dimensional scientific data:
+
+.. code-block:: python
+
+    >>> # Load data
+    >>> entry = imas.DBEntry("mypulsefile.nc","r")
+    >>> cp = entry.get("core_profiles", autoconvert=False, lazy=True)
+
+    >>> # Check shape of sliced data
+    >>> cp.profiles_1d[:].grid.shape
+    (106,)
+    >>> cp.profiles_1d[:].ion.shape
+    (106, ~3)  # ~3 ions per profile
+
+    >>> # Extract values
+    >>> grid_values = cp.profiles_1d[:].grid.to_array()
+    >>> ion_labels = cp.profiles_1d[:].ion[:].label.to_array()
+
+    >>> # Work with subsets
+    >>> subset_grid = cp.profiles_1d[1:3].grid.to_array()
+    >>> subset_ions = cp.profiles_1d[1:3].ion.to_array()
+
+The ``IDSSlice`` class tracks multi-dimensional shapes and provides both
+``.values()`` and ``.to_array()`` (numpy array)
+methods for data extraction. For more details, see :ref:`array-slicing`.
+