Skip to content

Commit 790db91

Browse files
luisaFelixSallesPProfizi
luisaFelixSalles
and
PProfizi
authored
Add import data tutorials to the main tutorials section (#1933)
* add new basic tutorial and jupyter_ sphinx extension * add tutorials files * add narrow_down_data.rst tutorial * updates narrow_down_data.rst tutorial * add extract_and_explore_results_metadata.rst tutorial * updates extract_and_explore_results_metadata.rst tutorial * updates extract_and_explore_results_metadata.rst tutorial * updates narrow_down_data.rst tutorial * updates extract_and_explore_results_metadata.rst tutorial * utilise que juptyter sphinx * use only jupyter sphinx: extract_and_explore_results_metadata.rst * add import_result_file.rst tutorial * updates * add extract_and_explore_results_data.rst tutorial * updates on extract_and_explore_results_metadata.rst * add represent_data_on_dpf.rst tutorial * updates on the index page * updates * update the import_result_file.rst to the tutorials guidelines * update the extract_and_explore_results_metadata.rst to the tutorials guidelines * update the extract_and_explore_results_data.rst to the tutorials guidelines * update the index.rst to the tutorials guidelines * update the narrow_down_data.rst to the tutorials guidelines * update the load_custom_data.rst to the tutorials guidelines * update the index.rst to the tutorials guidelines * add solvers badges to the index.rst cards * add solvers badges to the beginning of each tutorial * updates on the text of the load_custom_data.rst turorial * updates on the text of the import_result_file.rst turorial * updates on the text of the load_custom_data.rst turorial * updates on the text of the narrow_down_data.rst tutorial * delete file basic_tutorial.rst * Update doc/source/user_guide/tutorials/import_data/index.rst --------- Co-authored-by: Paul Profizi <[email protected]>
1 parent bf18b2f commit 790db91

File tree

6 files changed

+1878
-18
lines changed

6 files changed

+1878
-18
lines changed

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

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
.. _ref_tutorials_extract_and_explore_results_data:
2+
3+
================================
4+
Extract and explore results data
5+
================================
6+
7+
:bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX`
8+
9+
.. include:: ../../../links_and_refs.rst
10+
.. |get_entity_data| replace:: :func:`get_entity_data()<ansys.dpf.core.field.Field.get_entity_data>`
11+
.. |get_entity_data_by_id| replace:: :func:`get_entity_data_by_id()<ansys.dpf.core.field.Field.get_entity_data_by_id>`
12+
13+
This tutorial shows how to extract and explore results data from a result file.
14+
15+
When you extract a result from a result file DPF stores it in a |Field|.
16+
Thus, this |Field| contains the data of the result associated with it.
17+
18+
.. note::
19+
20+
When DPF-Core returns the |Field| object, what Python actually has is a client-side
21+
representation of the |Field|, not the entirety of the |Field| itself. This means
22+
that all the data of the field is stored within the DPF service. This is important
23+
because when building your workflows, the most efficient way of interacting with result data
24+
is to minimize the exchange of data between Python and DPF, either by using operators
25+
or by accessing exclusively the data that is needed.
26+
27+
:jupyter-download-script:`Download tutorial as Python script<extract_and_explore_results_data>`
28+
:jupyter-download-notebook:`Download tutorial as Jupyter notebook<extract_and_explore_results_data>`
29+
30+
Get the result file
31+
-------------------
32+
33+
First, import a result file. For this tutorial, you can use one available in the |Examples| module.
34+
For more information about how to import your own result file in DPF, see the :ref:`ref_tutorials_import_result_file`
35+
tutorial.
36+
37+
Here, we extract the displacement results. The displacement |Result| object gives a |FieldsContainer| when evaluated.
38+
Thus, we get a |Field| from this |FieldsContainer|.
39+
40+
.. jupyter-execute::
41+
42+
# Import the ``ansys.dpf.core`` module
43+
from ansys.dpf import core as dpf
44+
# Import the examples module
45+
from ansys.dpf.core import examples
46+
# Import the operators module
47+
from ansys.dpf.core import operators as ops
48+
49+
# Define the result file path
50+
result_file_path_1 = examples.download_transient_result()
51+
52+
# Create the model
53+
model_1 = dpf.Model(data_sources=result_file_path_1)
54+
55+
# Extract the displacement results for the last time step
56+
disp_results = model_1.results.displacement.on_last_time_freq.eval()
57+
58+
# Get the displacement field for the last time step
59+
disp_field = disp_results[0]
60+
61+
# Print the displacement Field
62+
print(disp_field)
63+
64+
Extract all the data from a |Field|
65+
-----------------------------------
66+
67+
You can extract the entire data in a |Field| as:
68+
69+
- An array (numpy array);
70+
- A list.
71+
72+
Data as an array
73+
^^^^^^^^^^^^^^^^
74+
75+
.. jupyter-execute::
76+
77+
# Get the displacement data as an array
78+
data_array = disp_field.data
79+
80+
# Print the data as an array
81+
print("Displacement data as an array: ", '\n', data_array)
82+
83+
Note that this array is a genuine, local, numpy array (overloaded by the DPFArray):
84+
85+
.. jupyter-execute::
86+
87+
# Print the array type
88+
print("Array type: ", type(data_array))
89+
90+
Data as a list
91+
^^^^^^^^^^^^^^
92+
93+
.. jupyter-execute::
94+
95+
# Get the displacement data as a list
96+
data_list = disp_field.data_as_list
97+
# Print the data as a list
98+
print("Displacement data as a list: ", '\n', data_list)
99+
100+
Extract specific data from a field
101+
----------------------------------
102+
103+
If you need to access data for specific entities (node, element ...), you can extract it with two approaches:
104+
105+
- :ref:`Based on its index <ref_extract_specific_data_by_index>` (data position on the |Field|) by using the |get_entity_data| method;
106+
- :ref:`Based on the entities id <ref_extract_specific_data_by_id>` by using the |get_entity_data_by_id| method.
107+
108+
The |Field| data is organized with respect to its scoping ids. Note that the element with id=533
109+
would correspond to an index=2 within the |Field|.
110+
111+
.. jupyter-execute::
112+
113+
# Get the index of the entity with id=533
114+
index_533_entity = disp_field.scoping.index(id=533)
115+
# Print the index
116+
print("Index entity id=533: ",index_533_entity)
117+
118+
Be aware that scoping IDs are not sequential. You would get the id of the element in the 533
119+
position of the |Field| with:
120+
121+
.. jupyter-execute::
122+
123+
# Get the id of the entity with index=533
124+
id_533_entity = disp_field.scoping.id(index=533)
125+
print("Id entity index=533: ",id_533_entity)
126+
127+
.. _ref_extract_specific_data_by_index:
128+
129+
Get the data by the entity index
130+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
131+
132+
.. jupyter-execute::
133+
134+
# Get the data from the third entity in the field
135+
data_3_entity = disp_field.get_entity_data(index=3)
136+
# Print the data
137+
print("Data entity index=3: ", data_3_entity)
138+
139+
.. _ref_extract_specific_data_by_id:
140+
141+
Get the data by the entity id
142+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
143+
144+
.. jupyter-execute::
145+
146+
# Get the data from the entity with id=533
147+
data_533_entity = disp_field.get_entity_data_by_id(id=533)
148+
# Print the data
149+
print("Data entity id=533: ", data_533_entity)
150+
151+
Extract specific data from a field using a loop over the array
152+
--------------------------------------------------------------
153+
154+
While the methods above are acceptable when requesting data for a few elements
155+
or nodes, they should not be used when looping over the entire array. For efficiency,
156+
a |Field| data can be recovered locally before sending a large number of requests:
157+
158+
.. jupyter-execute::
159+
160+
# Create a deep copy of the field that can be accessed and modified locally.
161+
with disp_field.as_local_field() as f:
162+
for i in disp_field.scoping.ids[2:50]:
163+
f.get_entity_data_by_id(i)
164+
165+
# Print the field
166+
print(f)

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

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
.. _ref_tutorials_extract_and_explore_results_metadata:
2+
3+
====================================
4+
Extract and explore results metadata
5+
====================================
6+
7+
:bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX`
8+
9+
.. include:: ../../../links_and_refs.rst
10+
.. |ResultInfo| replace:: :class:`ResultInfo<ansys.dpf.core.result_info.ResultInfo>`
11+
12+
This tutorial shows how to extract and explore results metadata from a result file.
13+
14+
:jupyter-download-script:`Download tutorial as Python script<extract_and_explore_results_metadata>`
15+
:jupyter-download-notebook:`Download tutorial as Jupyter notebook<extract_and_explore_results_metadata>`
16+
17+
Get the result file
18+
-------------------
19+
20+
First, import a result file. For this tutorial, you can use one available in the |Examples| module.
21+
For more information about how to import your own result file in DPF, see the :ref:`ref_tutorials_import_result_file`
22+
tutorial.
23+
24+
.. jupyter-execute::
25+
26+
# Import the ``ansys.dpf.core`` module
27+
from ansys.dpf import core as dpf
28+
# Import the examples module
29+
from ansys.dpf.core import examples
30+
# Import the operators module
31+
from ansys.dpf.core import operators as ops
32+
33+
# Define the result file path
34+
result_file_path_1 = examples.download_transient_result()
35+
# Create the model
36+
model_1 = dpf.Model(data_sources=result_file_path_1)
37+
38+
Explore the results general metadata
39+
------------------------------------
40+
41+
You can explore the general results metadata, before extracting the results, by using
42+
the |ResultInfo| object and its methods. This metadata includes:
43+
44+
- Analysis type;
45+
- Physics type;
46+
- Number of results;
47+
- Unit system;
48+
- Solver version, date and time;
49+
- Job name;
50+
51+
.. jupyter-execute::
52+
53+
# Define the ResultInfo object
54+
result_info_1 = model_1.metadata.result_info
55+
56+
# Get the analysis type
57+
analysis_type = result_info_1.analysis_type
58+
# Print the analysis type
59+
print("Analysis type: ",analysis_type, "\n")
60+
61+
# Get the physics type
62+
physics_type = result_info_1.physics_type
63+
# Print the physics type
64+
print("Physics type: ",physics_type, "\n")
65+
66+
# Get the number of available results
67+
number_of_results = result_info_1.n_results
68+
# Print the number of available results
69+
print("Number of available results: ",number_of_results, "\n")
70+
71+
# Get the unit system
72+
unit_system = result_info_1.unit_system
73+
# Print the unit system
74+
print("Unit system: ",unit_system, "\n")
75+
76+
# Get the solver version, data and time
77+
solver_version = result_info_1.solver_version
78+
solver_date = result_info_1.solver_date
79+
solver_time = result_info_1.solver_time
80+
81+
# Print the solver version, data and time
82+
print("Solver version: ",solver_version, "\n")
83+
print("Solver date: ", solver_date, "\n")
84+
print("Solver time: ",solver_time, "\n")
85+
86+
# Get the job name
87+
job_name = result_info_1.job_name
88+
# Print the job name
89+
print("Job name: ",job_name, "\n")
90+
91+
Explore a result metadata
92+
-------------------------
93+
When you extract a result from a result file DPF stores it in a |Field|.
94+
Thus, this |Field| contains the metadata for the result associated with it.
95+
This metadata includes:
96+
97+
- Location;
98+
- Scoping (type and quantity of entities);
99+
- Elementary data count (number of entities, how many data vectors we have);
100+
- Components count (vectors dimension, here we have a displacement so we expect to have 3 components (X, Y and Z));
101+
- Shape of the data stored (tuple with the elementary data count and the components count);
102+
- Fields size (length of the data entire vector (equal to the number of elementary data times the number of components));
103+
- Units of the data.
104+
105+
Here we will explore the metadata of the displacement results.
106+
107+
Start by extracting the displacement results.
108+
109+
.. jupyter-execute::
110+
111+
# Extract the displacement results
112+
disp_results = model_1.results.displacement.eval()
113+
114+
# Get the displacement field
115+
disp_field = disp_results[0]
116+
117+
Explore the displacement results metadata:
118+
119+
.. jupyter-execute::
120+
121+
# Get the location of the displacement data
122+
location = disp_field.location
123+
# Print the location
124+
print("Location: ", location,'\n')
125+
126+
# Get the displacement Field scoping
127+
scoping = disp_field.scoping
128+
# Print the Field scoping
129+
print("Scoping: ", '\n',scoping, '\n')
130+
131+
# Get the displacement Field scoping ids
132+
scoping_ids = disp_field.scoping.ids # Available entities ids
133+
# Print the Field scoping ids
134+
print("Scoping ids: ", scoping_ids, '\n')
135+
136+
# Get the displacement Field elementary data count
137+
elementary_data_count = disp_field.elementary_data_count
138+
# Print the elementary data count
139+
print("Elementary data count: ", elementary_data_count, '\n')
140+
141+
# Get the displacement Field components count
142+
components_count = disp_field.component_count
143+
# Print the components count
144+
print("Components count: ", components_count, '\n')
145+
146+
# Get the displacement Field size
147+
field_size = disp_field.size
148+
# Print the Field size
149+
print("Size: ", field_size, '\n')
150+
151+
# Get the displacement Field shape
152+
shape = disp_field.shape
153+
# Print the Field shape
154+
print("Shape: ", shape, '\n')
155+
156+
# Get the displacement Field unit
157+
unit = disp_field.unit
158+
# Print the displacement Field unit
159+
print("Unit: ", unit, '\n')

0 commit comments

Comments
 (0)