Add import data tutorials to the main tutorials section

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

@@ -0,0 +1,166 @@
+.. _ref_tutorials_extract_and_explore_results_data:
+
+================================
+Extract and explore results data
+================================
+
+:bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX`
+
+.. include:: ../../../links_and_refs.rst
+.. |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|.
+Thus, this |Field| contains the data of the result associated with it.
+
+.. note::
+
+    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
+    that all the data of the field is stored within the DPF service. This is important
+    because when building your workflows, the most efficient way of interacting with result data
+    is to minimize the exchange of data between Python and DPF, either by using operators
+    or by accessing exclusively the data that is needed.
+
+:jupyter-download-script:`Download tutorial as Python script<extract_and_explore_results_data>`
+:jupyter-download-notebook:`Download tutorial as Jupyter notebook<extract_and_explore_results_data>`
+
+Get the result file
+-------------------
+
+First, import a result file. For this tutorial, you can use one available in the |Examples| module.
+For more information about how to import your own result file in DPF, see 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 get a |Field| from this |FieldsContainer|.
+
+.. jupyter-execute::
+
+    # Import the ``ansys.dpf.core`` module
+    from ansys.dpf import core as dpf
+    # Import the examples module
+    from ansys.dpf.core import examples
+    # Import the operators module
+    from ansys.dpf.core import operators as ops
+
+    # Define the result file path
+    result_file_path_1 = examples.download_transient_result()
+
+    # Create the model
+    model_1 = dpf.Model(data_sources=result_file_path_1)
+
+    # Extract the displacement results for the last time step
+    disp_results = model_1.results.displacement.on_last_time_freq.eval()
+
+    # Get the displacement field for the last time step
+    disp_field = disp_results[0]
+
+    # Print the displacement Field
+    print(disp_field)
+
+Extract all the data from a |Field|
+-----------------------------------
+
+You can extract the entire data in a |Field| as:
+
+- An array (numpy array);
+- A list.
+
+Data as an array
+^^^^^^^^^^^^^^^^
+
+.. jupyter-execute::
+
+    # Get the displacement data as an array
+    data_array = disp_field.data
+
+    # Print the data as an array
+    print("Displacement data as an array: ", '\n', data_array)
+
+Note that this array is a genuine, local, numpy array (overloaded by the DPFArray):
+
+.. jupyter-execute::
+
+    # Print the array type
+    print("Array type: ", type(data_array))
+
+Data as a list
+^^^^^^^^^^^^^^
+
+.. jupyter-execute::
+
+    # Get the displacement data as a list
+    data_list = disp_field.data_as_list
+    # Print the data as a list
+    print("Displacement data as a list: ", '\n', data_list)
+
+Extract specific data from a field
+----------------------------------
+
+If you need to access data for specific entities (node, element ...), you can extract it with two approaches:
+
+- :ref:`Based on its index <ref_extract_specific_data_by_index>` (data position on the |Field|) by using the |get_entity_data| method;
+- :ref:`Based on the entities id <ref_extract_specific_data_by_id>` by using the |get_entity_data_by_id| method.
+
+The |Field| data is organized with respect to its scoping ids. 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 = disp_field.scoping.index(id=533)
+    # Print the index
+    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 = disp_field.scoping.id(index=533)
+    print("Id entity index=533: ",id_533_entity)
+
+.. _ref_extract_specific_data_by_index:
+
+Get the data by the entity index
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. jupyter-execute::
+
+    # Get the data from the third entity in the field
+    data_3_entity = disp_field.get_entity_data(index=3)
+    # Print the data
+    print("Data entity index=3: ", data_3_entity)
+
+.. _ref_extract_specific_data_by_id:
+
+Get the data by the entity id
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. jupyter-execute::
+
+    # Get the data from the entity with id=533
+    data_533_entity = disp_field.get_entity_data_by_id(id=533)
+    # Print the data
+    print("Data entity id=533: ", data_533_entity)
+
+Extract specific data from a field using a loop over the array
+--------------------------------------------------------------
+
+While the methods above 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| 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 disp_field.as_local_field() as f:
+        for i in disp_field.scoping.ids[2:50]:
+            f.get_entity_data_by_id(i)
+
+    # Print the field
+    print(f)

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

@@ -0,0 +1,159 @@
+.. _ref_tutorials_extract_and_explore_results_metadata:
+
+====================================
+Extract and explore results metadata
+====================================
+
+:bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX`
+
+.. include:: ../../../links_and_refs.rst
+.. |ResultInfo| replace:: :class:`ResultInfo<ansys.dpf.core.result_info.ResultInfo>`
+
+This tutorial shows how to extract and explore results metadata from a result file.
+
+:jupyter-download-script:`Download tutorial as Python script<extract_and_explore_results_metadata>`
+:jupyter-download-notebook:`Download tutorial as Jupyter notebook<extract_and_explore_results_metadata>`
+
+Get the result file
+-------------------
+
+First, import a result file. For this tutorial, you can use one available in the |Examples| module.
+For more information about how to import your own result file in DPF, see the :ref:`ref_tutorials_import_result_file`
+tutorial.
+
+.. jupyter-execute::
+
+    # Import the ``ansys.dpf.core`` module
+    from ansys.dpf import core as dpf
+    # Import the examples module
+    from ansys.dpf.core import examples
+    # Import the operators module
+    from ansys.dpf.core import operators as ops
+
+    # Define the result file path
+    result_file_path_1 = examples.download_transient_result()
+    # Create the model
+    model_1 = dpf.Model(data_sources=result_file_path_1)
+
+Explore the results general metadata
+------------------------------------
+
+You can explore the general results metadata, before extracting the results, by using
+the |ResultInfo| object and its methods. This metadata includes:
+
+- Analysis type;
+- Physics type;
+- Number of results;
+- Unit system;
+- Solver version, date and time;
+- Job name;
+
+.. jupyter-execute::
+
+    # Define the ResultInfo object
+    result_info_1 = model_1.metadata.result_info
+
+    # Get the analysis type
+    analysis_type = result_info_1.analysis_type
+    # Print the analysis type
+    print("Analysis type: ",analysis_type, "\n")
+
+    # Get the physics type
+    physics_type = result_info_1.physics_type
+    # Print the physics type
+    print("Physics type: ",physics_type, "\n")
+
+    # Get the number of available results
+    number_of_results = result_info_1.n_results
+    # Print the number of available results
+    print("Number of available results: ",number_of_results, "\n")
+
+    # Get the unit system
+    unit_system = result_info_1.unit_system
+    # Print the unit system
+    print("Unit system: ",unit_system, "\n")
+
+    # Get the solver version, data and time
+    solver_version = result_info_1.solver_version
+    solver_date = result_info_1.solver_date
+    solver_time = result_info_1.solver_time
+
+    # Print the solver version, data and time
+    print("Solver version: ",solver_version, "\n")
+    print("Solver date: ", solver_date, "\n")
+    print("Solver time: ",solver_time, "\n")
+
+    # Get the job name
+    job_name = result_info_1.job_name
+    # Print the job name
+    print("Job name: ",job_name, "\n")
+
+Explore a result metadata
+-------------------------
+When you extract a result from a result file DPF stores it in a |Field|.
+Thus, this |Field| contains the metadata for the result associated with it.
+This metadata includes:
+
+- Location;
+- Scoping (type and quantity of entities);
+- Elementary data count (number of entities, how many data vectors we have);
+- Components count (vectors dimension, here we have a displacement so we expect to have 3 components (X, Y and Z));
+- Shape of the data stored (tuple with the elementary data count and the components count);
+- Fields size (length of the data entire vector (equal to the number of elementary data times the number of components));
+- Units of the data.
+
+Here we will explore the metadata of the displacement results.
+
+Start by extracting the displacement results.
+
+.. jupyter-execute::
+
+    # Extract the displacement results
+    disp_results = model_1.results.displacement.eval()
+
+    # Get the displacement field
+    disp_field = disp_results[0]
+
+Explore the displacement results metadata:
+
+.. jupyter-execute::
+
+    # Get the location of the displacement data
+    location = disp_field.location
+    # Print the location
+    print("Location: ", location,'\n')
+
+    # Get the displacement Field scoping
+    scoping = disp_field.scoping
+    # Print the Field scoping
+    print("Scoping: ", '\n',scoping, '\n')
+
+    # Get the displacement Field scoping ids
+    scoping_ids = disp_field.scoping.ids  # Available entities ids
+    # Print the Field scoping ids
+    print("Scoping ids: ", scoping_ids, '\n')
+
+    # Get the displacement Field elementary data count
+    elementary_data_count = disp_field.elementary_data_count
+    # Print the elementary data count
+    print("Elementary data count: ", elementary_data_count, '\n')
+
+    # Get the displacement Field components count
+    components_count = disp_field.component_count
+    # Print the components count
+    print("Components count: ", components_count, '\n')
+
+    # Get the displacement Field size
+    field_size = disp_field.size
+    # Print the Field size
+    print("Size: ", field_size, '\n')
+
+    # Get the displacement Field shape
+    shape = disp_field.shape
+    # Print the Field shape
+    print("Shape: ", shape, '\n')
+
+    # Get the displacement Field unit
+    unit = disp_field.unit
+    # Print the displacement Field unit
+    print("Unit: ", unit, '\n')