Skip to content

doc(tuto): DPF collections tutorial #2742

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 18 commits into
base: main
Choose a base branch
from
Open

doc(tuto): DPF collections tutorial #2742

wants to merge 18 commits into from
+313 −6

Conversation

@PProfizi
Copy link
Contributor

@PProfizi PProfizi commented Nov 13, 2025 •
edited
Loading

This tutorial shows how to create and work with some DPF collections.

@PProfizi PProfizi self-assigned this Nov 13, 2025
@PProfizi PProfizi added the tutorials Related to PyDPF-Core tutorials label Nov 13, 2025
PProfizi
PProfizi commented Nov 13, 2025
View reviewed changes
@codecov
Copy link

codecov bot commented Nov 13, 2025 •
edited
Loading

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.43%. Comparing base (ba4a598) to head (61d2565).
⚠️ Report is 3 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files 
@@           Coverage Diff           @@
##             main    #2742   +/-   ##
=======================================
  Coverage   84.42%   84.43%           
=======================================
  Files          92       92           
  Lines       10931    10944   +13     
=======================================
+ Hits         9229     9241   +12     
- Misses       1702     1703    +1

PProfizi
PProfizi commented Nov 13, 2025
View reviewed changes
PProfizi
PProfizi commented Nov 18, 2025
View reviewed changes
PProfizi
PProfizi commented Nov 18, 2025
View reviewed changes
PProfizi
PProfizi commented Nov 18, 2025
View reviewed changes
PProfizi
PProfizi commented Nov 18, 2025
View reviewed changes
PProfizi
PProfizi commented Nov 18, 2025
View reviewed changes
PProfizi
PProfizi commented Nov 18, 2025
View reviewed changes
PProfizi
PProfizi commented Nov 18, 2025
View reviewed changes
PProfizi
PProfizi commented Nov 18, 2025
View reviewed changes
PProfizi
PProfizi commented Nov 19, 2025
View reviewed changes
PProfizi
PProfizi commented Nov 19, 2025
View reviewed changes
PProfizi
PProfizi commented Nov 19, 2025
View reviewed changes
@PProfizi
Copy link
Contributor Author

PProfizi commented Nov 20, 2025

Hello @JennaPaikowsky I think I have finished iterating over this tutorial. Let me know what you think!

JennaPaikowsky
JennaPaikowsky reviewed Nov 20, 2025
View reviewed changes
Copy link
Contributor

@JennaPaikowsky JennaPaikowsky left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, just a few minor suggestions.

@PProfizi @JennaPaikowsky
Apply suggestions from code review
61d2565 
Co-authored-by: JennaPaikowsky <98607744+JennaPaikowsky@users.noreply.github.com>
luisaFelixSalles
luisaFelixSalles reviewed Nov 21, 2025
View reviewed changes
Copy link
Contributor

@luisaFelixSalles luisaFelixSalles left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its ok. For me what is lacking in the tutorial are explanations. We have too long code blocks (that don't have comment lines themselves) but we don't say why/when we are doing something, or why/when should we should do something.

doc/source/user_guide/tutorials/data_structures/collections.rst

.. include:: ../../links_and_refs.rst

This tutorial demonstrates how to create and work with some DPF collections: FieldsContainer, MeshesContainer and ScopingsContainer.
Copy link
Contributor

@luisaFelixSalles luisaFelixSalles Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This tutorial demonstrates how to create and work with some DPF collections: FieldsContainer, MeshesContainer and ScopingsContainer.
This tutorial demonstrates how to create and work with some DPF collections: |FieldsContainer|, |MeshesContainer| and |ScopingsContainer|.

doc/source/user_guide/tutorials/data_structures/collections.rst

This tutorial demonstrates how to create and work with some DPF collections: FieldsContainer, MeshesContainer and ScopingsContainer.

DPF collections are homogeneous groups of labeled raw data storage structures that allow you to organize and manipulate related data efficiently. Collections are essential for handling multiple time steps, frequency sets, or other labeled datasets in your analysis workflows.
Copy link
Contributor

@luisaFelixSalles luisaFelixSalles Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you mean by "homogeneous groups"?
I personally don't like to use the term "Labeled " here because the concept of label in DFP has not been explained yet. "Collections gather raw data storage structures grouped by a category. In dpf these categories are labels ..." Something like this.

doc/source/user_guide/tutorials/data_structures/collections.rst
Introduction to Collections
---------------------------

Collections in DPF serve as containers that group related objects with labels. The main collection types are:
Copy link
Contributor

@luisaFelixSalles luisaFelixSalles Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We did this same intro with other words just before this. I prefer this formulation because it is more straightforward. (but again I would just avoid using the term "label" as a generic word here because "Label" is a DPF concept )

doc/source/user_guide/tutorials/data_structures/collections.rst
Collections in DPF serve as containers that group related objects with labels. The main collection types are:

- |FieldsContainer|: A collection of |Field| objects, typically representing results over multiple time steps or frequency sets
- |MeshesContainer|: A collection of |MeshedRegion| objects for different configurations or time steps
Copy link
Contributor

@luisaFelixSalles luisaFelixSalles Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The term "configurations" her can be misunderstood as it is also a term in the DPF vocabulary.

doc/source/user_guide/tutorials/data_structures/collections.rst
Comment on lines +31 to +32
Collections are widely used in DPF workflows to provide vectorized data to operators,
allowing you to process the data in bulk or to process it in parallel whenever possible.
Copy link
Contributor

@luisaFelixSalles luisaFelixSalles Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would avoid terms that do not express certainty when defining something. Here the "Collections are widely used in DPF..." : this is the only use? this is the main use ? what are the other use cases?

doc/source/user_guide/tutorials/data_structures/collections.rst
first_nodes = dpf.Scoping(location=dpf.locations.nodal)
first_nodes.ids = list(range(1, 11))
scopings_container.add_scoping(label_space={"selection_type": 0}, scoping=first_nodes)
# Selection 2: Every 10th node (sample)
Copy link
Contributor

@luisaFelixSalles luisaFelixSalles Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would put more space between the blocks so it can be more visual.

doc/source/user_guide/tutorials/data_structures/collections.rst
Comment on lines +149 to +152
all_node_ids = mesh.nodes.scoping.ids
every_tenth = dpf.Scoping(location=dpf.locations.nodal)
every_tenth.ids = all_node_ids[::10] # Every 10th node
scopings_container.add_scoping(label_space={"selection_type": 1}, scoping=every_tenth)
Copy link
Contributor

@luisaFelixSalles luisaFelixSalles Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
all_node_ids = mesh.nodes.scoping.ids
every_tenth = dpf.Scoping(location=dpf.locations.nodal)
every_tenth.ids = all_node_ids[::10] # Every 10th node
scopings_container.add_scoping(label_space={"selection_type": 1}, scoping=every_tenth)
#Get the ids for every node on the mesh
all_node_ids = mesh.nodes.scoping.ids
#Define the location
every_tenth = dpf.Scoping(location=dpf.locations.nodal)
# Get every 10th node
every_tenth.ids = all_node_ids[::10]
# Add the Scoping object to the ScopingContainer
scopings_container.add_scoping(label_space={"selection_type": 1}, scoping=every_tenth)

Copy link
Contributor

@luisaFelixSalles luisaFelixSalles Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

example on the comment lines

doc/source/user_guide/tutorials/data_structures/collections.rst
Create a MeshesContainer
^^^^^^^^^^^^^^^^^^^^^^^^

Create a |MeshesContainer| with mesh data for different analysis configurations.
Copy link
Contributor

@luisaFelixSalles luisaFelixSalles Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

analysis configuration

doc/source/user_guide/tutorials/data_structures/collections.rst
Comment on lines +238 to +242
for i in range(min(3, len(displacement_fc))): # Show first 3 fields
field = displacement_fc[i]
label_space = displacement_fc.get_label_space(i)
max_value = field.data.max()
print(f" Field {i}: {label_space}, max value: {max_value:.6f}")
Copy link
Contributor

@luisaFelixSalles luisaFelixSalles Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same thing here for the loop.

doc/source/user_guide/tutorials/data_structures/collections.rst
Filter and Select from Collections
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can filter collections based on labels or criteria.
Copy link
Contributor

@luisaFelixSalles luisaFelixSalles Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which criteria?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@luisaFelixSalles luisaFelixSalles luisaFelixSalles left review comments

@JennaPaikowsky JennaPaikowsky Awaiting requested review from JennaPaikowsky

At least 1 approving review is required to merge this pull request.

Assignees

@PProfizi PProfizi

Labels

tutorials Related to PyDPF-Core tutorials

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@PProfizi @JennaPaikowsky @luisaFelixSalles