Add mesh tutorials to the main tutorials branch

[luisaFelixSalles]

Add new plot tutorials to the mesh section:

List of tutorials:

• Create a mesh from scratch
• Get a mesh from a result file
• Read a mesh metadata
• Explore a mesh
• Extract a mesh in split parts
• Split a mesh

Preview on how it renders:

Mesh section main page

Create a mesh from scratch

Get a mesh from a result file

Read a mesh metadata

Explore a mesh

Extract a mesh in split parts

Split a mesh

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.43%. Comparing base (627c2de) to head (56e1a9f).
Report is 11 commits behind head on doc/new-tutorials-section.

Additional details and impacted files

@@                      Coverage Diff                      @@
##           doc/new-tutorials-section    #1908      +/-   ##
=============================================================
- Coverage                      88.50%   88.43%   -0.08%     
=============================================================
  Files                             89       89              
  Lines                          10251    10251              
=============================================================
- Hits                            9073     9065       -8     
- Misses                          1178     1186       +8     

[PProfizi]

Could we restrict the mesh from scratch tutorial to just that? I think the add data and plot data sections should appear somewhere else. Also, this is not "adding" data to the mesh but rather creating data from scratch which we then plot on the mesh. I think this is covered in the plotting tutorials, and the data part should probably be in a tutorial on creating Fields and FieldsContainers from scratch which we can add separately.

[PProfizi]

Get a mesh from a result file: problem with rendering for the mesh_provider operator reference in the section title.
Also we should add a section regarding the meshes_provider.

[PProfizi]

Read and get specific information from a mesh:
rename to read mesh metadata.
I see several references not rendering properly.
Also this looks like two examples where put one after the other, could we rather merge them into one, while giving indications on specifics for different solvers?

[PProfizi]

Get a mesh split on different parts: I think we reshape the tutorial to something very small explaining how to get a mesh split by body for each solver (Fluent+CFX or LSDYNA) with the mesh_provider/meshes_provider (explain the region_scoping input pin)

Basically here the idea would be to show how to Extract a mesh as split per body

The next tutorial on Split a mesh can then be focused on splitting on already existing MeshedRegion into a MeshesContainer, based on mesh properties. There is the split_mesh operator, but there is also the two-steps way using scoping.split_on_property_type and then mesh.from_scoping(s)

[luisaFelixSalles]

Get a mesh from a result file: problem with rendering for the mesh_provider operator reference in the section title. Also we should add a section regarding the meshes_provider.

Wouldn't this section be the Extract a mesh as split per body tutorial?

[jorgepiloto]

I would avoid combining comments and imports. Instead, I feel it is more appropriate to have paragraphs and small code cells:

Suggested change

	.. 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 = examples.find_msup_transient()
	# Create the model
	model = dpf.Model(data_sources=result_file_path)
	Start by importing the `dpf`, `examples`, and `operators` modules:
	.. jupyter-execute::
	from ansys.dpf import core as dpf
	from ansys.dpf.core import examples
	from ansys.dpf.core import operators as ops
	Next, define the path to the result file and create the model:
	.. jupyter-execute::
	result_file_path = examples.find_msup_transient()
	model = dpf.Model(data_sources=result_file_path)

[jorgepiloto]

This replacement is very convenient. I really like it.

[jorgepiloto]

Not a big fan of storing output. It forces to manually regenerate it in the future and it is prone to get outdated quickly.

In the future, it would be great to migrate this to Jupytext. I bet that using MyST can provide us with the same tab-features we are using.

[jorgepiloto]

I think this should work too. It avoids using the np.nditer function and handles dimensions before executing any logic:

Suggested change

	def search_sequence_numpy(arr, seq):
	"""Find a sequence in an array and return its index."""
	indexes = np.where(np.isclose(arr, seq[0]))
	for index in np.nditer(indexes[0]):
	if index % 3 == 0:
	if np.allclose(arr[index + 1], seq[1]) and np.allclose(arr[index + 2], seq[2]):
	return index
	return -1
	if len(seq) == 0:
	raise ValueError("The search sequence must not be empty.")
	if len(seq) > len(arr):
	return -1 # Sequence longer than the array cannot be found.
	# Sliding window approach
	for i in range(len(arr) - len(seq) + 1):
	if np.allclose(arr[i:i + len(seq)], seq):
	return i
	return -1

[jorgepiloto]

Short lists should not end in periods or any other symbol:

Suggested change

	- Number of nodes and elements;
	- Unit;
	- Elements type.
	- Number of nodes and elements
	- Unit
	- Elements type

[jorgepiloto]

Suggested change

	- Number of nodes and elements;
	- Unit;
	- Elements type.
	- Number of nodes and elements
	- Unit
	- Elements type

[jorgepiloto]

Suggested change

	- Properties;
	- Parts;
	- Faces;
	- Bodies;
	- Zones;
	- Number of nodes and elements;
	- Elements types.
	- Properties
	- Parts
	- Faces
	- Bodies
	- Zones
	- Number of nodes and elements
	- Elements types

[jorgepiloto]

Suggested change

	- Unit;
	- Nodes, elements and faces;
	- Named selections: .
	- Unit
	- Nodes, elements and faces
	- Named selections

[jorgepiloto]

Just left some additional comments on how to document list items.

[moe-ad]

Great job Luisa! You made heavy use of substitution definitions which very nice.

I observed the following concerning these definitions:

• Some definitions already in links_and_refs.rst are being redefined, for example |MeshesContainer| and |ScopingsContainer|. If definitions in links_and_refs.rst are changed in the future, the changes will not reflect in your examples because local definitions will take precedence.
• You have same substitution definitions in more than one .rst file, for example |meshes_provider| common to get_mesh_from_result_file.rst and extract_mesh_in_split_parts.rst. If there is a restructuring of the dpf.core package in the future affecting the location |meshes_provider| is pointing to, then each of the definitions in your examples have to be located and changed. It is a similar problem to that above.

The solution to this is to move all your substitution definitions to links_and_refs.rst. Then you have only one source of truth. Let me know what you think about the suggested approach.

[moe-ad]

Great implementation and great suggestion by Jorge as well.
Numpy operations are multidimensional, and knowing how to take advantage of this will greatly simplify things. For example, you can directly determine the index of a node within a DPFArray of nodes as suggested below.

Suggested change

	def search_sequence_numpy(arr, seq):
	"""Find a sequence in an array and return its index."""
	indexes = np.where(np.isclose(arr, seq[0]))
	for index in np.nditer(indexes[0]):
	if index % 3 == 0:
	if np.allclose(arr[index + 1], seq[1]) and np.allclose(arr[index + 2], seq[2]):
	return index
	return -1
	def search_sequence_numpy(arr, node):
	"""Find the node location in an array of nodes and return its index."""
	indexes = np.isclose(arr, seq)
	match = np.all(indexes, axis=1).nonzero()
	return int(match[0][0])

[moe-ad]

So this updated function will take my_nodes_coordinates_data directly as input.

[moe-ad]

If you choose to go with the previous suggestion, then you just need to do this:

Suggested change

	data_index = search_sequence_numpy(my_nodes_coordinates_data_list, [xx, yy, zz])
	scoping_index = int(data_index / 3) # 3components
	scoping_index = search_sequence_numpy(my_nodes_coordinates_data, [xx, yy, zz])

[moe-ad]

Of course, you would still need to take care of the suggestions already given by Jorge.

[moe-ad]

Hi Luisa. Great work!
Going through the examples made me learn new things about DPF as working with DPF is also new for me... :)

I left a couple of comments. I will try to conduct more review when I am chanced.

[cbellot000]

Suggested change

	This tutorial demonstrates how to build a |MeshedRegion| from the scratch.
	This tutorial demonstrates how to build a |MeshedRegion| from scratch.

[cbellot000]

I don't think instantiating is the right word. Maybe more "calling the nodes, `elements [...] properties" ?

[cbellot000]

There is a dedicated property to get the element types. I wouldn't use property_field with the string

[cbellot000]

In Fluent and CFX, there is no concept of part? Maybe we should rename this tutorial with "zone"

[cbellot000]

Suggested change

	This tutorial shows how to split a mesh on a give property.
	This tutorial shows how to split a mesh on a given property.

[cbellot000]

I don't think we are restricted to these properties, are we?

[cbellot000]

Their are some formatting errors :)

Suggested change

	meshes_21 = ops.mesh.split_mesh(mesh=meshed_region_2,property="mat").eval()
	meshes_21 = ops.mesh.split_mesh(mesh=meshed_region_2, property="mat").eval()