add extract_and_explore_results_data.rst tutorial

Author: luisaFelixSalles

doc/source/user_guide/tutorials/import_data/extract_and_explore_results_data.rst

@@ -1,16 +1,20 @@
 .. _ref_tutorials_extract_and_explore_results_data:
 
-====================
-Explore results data
-====================
+================================
+Extract and explore results data
+================================
 
 .. |Field| replace:: :class:`Field<ansys.dpf.core.field.Field>`
 .. |Examples| replace:: :mod:`Examples<ansys.dpf.core.examples>`
+.. |Result| replace:: :class:`Result <ansys.dpf.core.results.Result>`
+.. |FieldsContainer| replace:: :class:`FieldsContainer<ansys.dpf.core.fields_container.FieldsContainer>`
+.. |get_entity_data| replace:: :func:`get_entity_data()<ansys.dpf.core.field.Field.get_entity_data>`
+.. |get_entity_data_by_id| replace:: :func:`get_entity_data_by_id()<ansys.dpf.core.field.Field.get_entity_data_by_id>`
 
 This tutorial shows how to extract and explore results data from a result file.
 
 When you extract a result from a result file DPF stores it in a |Field|.
-This |Field| will then contain the data of the result associated with it.
+This |Field| will contain the data of the result associated with it.
 
 When DPF-Core returns the |Field| object, what Python actually has is a client-side
 representation of the |Field|, not the entirety of the |Field| itself. This means
@@ -19,5 +23,121 @@ because when building your workflows, the most efficient way of interacting with
 is to minimize the exchange of data between Python and DPF, either by using operators
 or by accessing exclusively the data that is needed.
 
+The |Field| data is ordered with respect to its scoping ids (check the :ref:`reft_tutorials_narrow_down_data`
+tutorial for more information on scoping manipulations).
 
+Get the results
+---------------
 
+Here we will download a result file available in our |Examples| package.
+For more information about how to import your result file in DPF check
+the :ref:`ref_tutorials_import_result_file` tutorial.
+
+Here we extract the displacement results. The displacement |Result| object gives a |FieldsContainer| when evaluated.
+Thus, we will get a |Field| from this |FieldsContainer|.
+
+.. jupyter-execute::
+
+    # Import the ``ansys.dpf.core`` module, including examples files and the operators subpackage
+    from ansys.dpf import core as dpf
+    from ansys.dpf.core import examples
+    from ansys.dpf.core import operators as ops
+
+    # Define the result file
+    result_file_path_1 = examples.download_transient_result()
+
+    # Create the model
+    my_model_1 = dpf.Model(data_sources=result_file_path_1)
+
+    # Extract the displacement results for the last time step
+    disp_results = my_model_1.results.displacement.on_last_time_freq.eval()
+
+    # Get the displacement field for the last time step
+    my_disp_field = disp_results[0]
+
+    print(my_disp_field)
+
+Extract all data from a field
+-----------------------------
+
+You can extract the the entire data in the |Field| as an array (numpy array) or as a list.
+
+Data as an array
+^^^^^^^^^^^^^^^^
+
+.. jupyter-execute::
+
+    # Get the displacement data as an array
+    my_data_array = my_disp_field.data
+    print("Displacement data as an array: ", '\n', my_data_array)
+
+Note that this array is a genuine, local, numpy array (overloaded by the DPFArray):
+
+.. jupyter-execute::
+
+    print("Array type: ", type(my_data_array))
+
+Data as a list
+^^^^^^^^^^^^^^
+
+.. jupyter-execute::
+
+    # Get the displacement data as a list
+    my_data_list = my_disp_field.data_as_list
+    print("Displacement data as a list: ", '\n', my_data_list)
+
+Extract specific data from a field
+----------------------------------
+
+If you need to access data for specific entities (node, element ...), you can extract it
+based on its index (data position on the |Field| by using the |get_entity_data| method), or based
+on the entities id (by using the |get_entity_data_by_id| method).
+
+Get the data by the entity index
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. jupyter-execute::
+
+    # Get the data from the third entity in the field
+    data_3_entity = my_disp_field.get_entity_data(index=3)
+    print("Data entity index=3: ", data_3_entity)
+
+Get the data by the entity ind
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. jupyter-execute::
+
+    # Get the data from the entity with id=533
+    data_533_entity = my_disp_field.get_entity_data_by_id(id=533)
+    print("Data entity id=533: ", data_533_entity)
+
+Note that the element with id=533 would correspond to an index=2 within the |Field|.
+
+.. jupyter-execute::
+
+    # Get the index of  the entity with id=533
+    index_533_entity = my_disp_field.scoping.index(id=533)
+    print("Index entity id=533: ",index_533_entity)
+
+Be aware that scoping IDs are not sequential. You would get the id of the element in the 533
+position of the |Field| with:
+
+.. jupyter-execute::
+
+    # Get the id of  the entity with index=533
+    id_533_entity = my_disp_field.scoping.id(index=533)
+    print("Id entity index=533: ",id_533_entity)
+
+
+While these methods are acceptable when requesting data for a few elements
+or nodes, they should not be used when looping over the entire array. For efficiency,
+a |Field|s data can be recovered locally before sending a large number of requests:
+
+.. jupyter-execute::
+
+    # Create a deep copy of the field that can be accessed and modified locally.
+    with my_disp_field.as_local_field() as f:
+        for i in my_disp_field.scoping.ids[2:50]:
+            f.get_entity_data_by_id(i)
+
+    print(f)