Skip to content

New proposition for the tutorials section layout #1779

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

Closed
wants to merge 4 commits into from
Closed

New proposition for the tutorials section layout #1779

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
aed7e02
adaptation of the tutorials section layout
luisaFelixSalles Sep 30, 2024
ceba714
text update
luisaFelixSalles Sep 30, 2024
ad34c8e
Apply suggestions from code review
luisaFelixSalles Sep 30, 2024
0c8b7cd
updates in the new tutorials layout
luisaFelixSalles Oct 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 27 additions & 26 deletions doc/source/user_guide/how-to/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,40 @@
.. _ref_how_to:

Enriching DPF capabilities
----------------------------------------
.. topic:: Enriching DPF capabilities

.. grid:: 3
:gutter: 2

.. grid-item-card:: Create custom operators and plugins
:link: user_guide_custom_operators
:link-type: ref
:text-align: center
.. grid:: 3
:gutter: 2

.. image:: ../images/drawings/plugin-logo.png
:width: 50%
.. grid-item-card:: Create custom operators and plugins
:link: user_guide_custom_operators
:link-type: ref
:text-align: center

.. image:: ../images/drawings/plugin-logo.png
:width: 25%

.. grid-item-card:: Switch between local and remote server
:link: user_guide_server_types
:link-type: ref
:text-align: center

.. image:: ../images/drawings/remote_machines.png
.. grid-item-card:: Switch between local and remote server
:link: user_guide_server_types
:link-type: ref
:text-align: center

.. image:: ../images/drawings/remote_machines.png
:width: 25%

.. grid-item-card:: Access Entry and Premium capabilities
:link: user_guide_server_context
:link-type: ref
:text-align: center
.. grid-item-card:: Access Entry and Premium capabilities
:link: user_guide_server_context
:link-type: ref
:text-align: center

.. image:: ../images/drawings/entry_premium.png
.. image:: ../images/drawings/entry_premium.png
:width: 25%

.. grid-item-card:: Configure DPF plugins load
:link: user_guide_xmlfiles
:link-type: ref
:text-align: center
.. grid-item-card:: Configure DPF plugins load
:link: user_guide_xmlfiles
:link-type: ref
:text-align: center

.. image:: ../images/drawings/xml.png
.. image:: ../images/drawings/xml.png
:width: 25%
158 changes: 102 additions & 56 deletions doc/source/user_guide/tutorials/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,94 +3,140 @@
Tutorials
---------

What you need to know
+++++++++++++++++++++

The following tutorials show in details how to use basic features of PyDPF-Core
for each usage main step.
These tutorials go through the steps required to access, analyze,
and transform simulation data using PyDPF-Core.

:bdg-dark-line:`Define simulation data` :octicon:`arrow-right;1em` :bdg-dark-line:`Store input data in DPF` :octicon:`arrow-right;1em` :bdg-dark-line:`Transform available data` :octicon:`arrow-right;1em` :bdg-dark-line:`Extract data`
Tutorials are more substantive and complex than examples. They are designed to teach how to perform a task and understand
the underlying concepts, providing detailed explanations at each stage, whereas examples showcase end-to-end specific processes.

**Define input data**
DPF interacts with data stored in DPF data structures.
These DPF data structures are generated automatically when reading data from results file (`ref_to_section`) but they can also be generated from scratch (`ref_to_section`) when no supported result file is available.

Check failure on line 16 in doc/source/user_guide/tutorials/index.rst

View workflow job for this annotation

GitHub Actions / vale

[vale] doc/source/user_guide/tutorials/index.rst#L16 

[Vale.Spelling] Did you really mean 'ref_to_section'?
Raw output 
{"message": "[Vale.Spelling] Did you really mean 'ref_to_section'?", "location": {"path": "doc/source/user_guide/tutorials/index.rst", "range": {"start": {"line": 16, "column": 93}}}, "severity": "ERROR"}

Check failure on line 16 in doc/source/user_guide/tutorials/index.rst

View workflow job for this annotation

GitHub Actions / vale

[vale] doc/source/user_guide/tutorials/index.rst#L16 

[Vale.Spelling] Did you really mean 'ref_to_section'?
Raw output 
{"message": "[Vale.Spelling] Did you really mean 'ref_to_section'?", "location": {"path": "doc/source/user_guide/tutorials/index.rst", "range": {"start": {"line": 16, "column": 156}}}, "severity": "ERROR"}

Overview
++++++++

.. grid:: 3
There are four main steps to transform simulation data into output data that can
be used to visualize and analyze simulation results:
Comment on lines +21 to +22
Copy link
Contributor

@PProfizi PProfizi Sep 30, 2024

Choose a reason for hiding this comment

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

To be discussed further. I think it would be better to mention different categories of actions you can perform with PyDPF-Core. The end-goal of using PyDPF-Core is not necessarily to visualize and analyze.
Maybe something along the lines of: "There are different kind of actions you can perform: from extracting result from result files, to visualization of extracted data, to filtering, transformation of the data, and much more."

Comment on lines +21 to +22
Copy link
Contributor Author

@luisaFelixSalles luisaFelixSalles Sep 30, 2024

Choose a reason for hiding this comment

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

Suggested change
There are four main steps to transform simulation data into output data that can
be used to visualize and analyze simulation results:
There are different kind of actions you can perform with PyDPF-Core: from extracting result from result files, to visualization of extracted data, to filtering, transformation of the data, and much more.
Nevertheless, we can summarize in four main steps the process of transforming simulation data into post-processed output data :


.. grid-item-card:: Data Sources
:link: ref_tutorials_model
:link-type: ref
:text-align: center
:bdg-dark-line:`Define simulation data` :octicon:`arrow-right;1em` :bdg-dark-line:`Store input data in DPF` :octicon:`arrow-right;1em` :bdg-dark-line:`Transform available data` :octicon:`arrow-right;1em` :bdg-dark-line:`Extract data`

.. grid-item-card:: DPF model
:link: ref_tutorials_model
:link-type: ref
:text-align: center
The following tutorials go through each of these steps. Each tutorial presents code snippets specific to each supported file format.

**Load data**

.. topic:: Importing and opening results files
Copy link
Contributor

@PProfizi PProfizi Sep 30, 2024

Choose a reason for hiding this comment

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

Suggested change
.. topic:: Importing and opening results files
.. topic:: Extract data from result files

Copy link
Contributor Author

@luisaFelixSalles luisaFelixSalles Sep 30, 2024

Choose a reason for hiding this comment

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

I don't know if using "extract " here is a great idea. Because in the other section we talk about extracting (like if I want to have a displacement result). So here is it actually extract a result?


.. grid:: 3

.. grid-item-card:: Data arrays
:link: ref_tutorials_model
:link-type: ref
:text-align: center
.. grid:: 3

Fields
.. grid-item-card:: I have one file
Copy link
Contributor

@PProfizi PProfizi Sep 30, 2024

Choose a reason for hiding this comment

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

Suggested change
.. grid-item-card:: I have one file
.. grid-item-card:: Extract data from a single file

:link: ref_tutorials_model
:link-type: ref
:text-align: center

PropertyField
Import and open a single result file with PyDPF-Core.
Copy link
Contributor

@PProfizi PProfizi Sep 30, 2024

Choose a reason for hiding this comment

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

Suggested change
Import and open a single result file with PyDPF-Core.
Extract data from a single result file with PyDPF-Core.


StringField
.. grid-item-card:: I have more than one file
Copy link
Contributor

@PProfizi PProfizi Sep 30, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Suggested change
.. grid-item-card:: I have more than one file
.. grid-item-card:: Extract data from distributed result files

Copy link
Contributor

@PProfizi PProfizi Sep 30, 2024

Choose a reason for hiding this comment

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

And the idea would be to also add a tutorial for:

  • when you have accessory files
  • when you have upstream result files
  • and so on

Copy link
Contributor Author

@luisaFelixSalles luisaFelixSalles Sep 30, 2024

Choose a reason for hiding this comment

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

Yes. If you have more than one file the tutorial will talk about these cases

:link: ref_tutorials_model
:link-type: ref
:text-align: center

CustomTypeField
Import and open multiple result files to be used in the same
post-processing operation.

.. grid-item-card:: Data maps
:link: ref_tutorials_model
:link-type: ref
:text-align: center
.. grid-item-card:: I don’t know my file(s) type(s)
:link: ref_tutorials_model
:link-type: ref
:text-align: center

GenericDataContainer
The result file extension key is unknown by the user.

DataTree
.. topic:: Declare data from scratch

.. grid-item-card:: Collections
:link: ref_tutorials_model
:link-type: ref
:text-align: center

LabelSpace
.. grid:: 3

FieldsContainer
.. grid-item-card:: Creating your own storage structures
:link: ref_tutorials_model
:link-type: ref
:text-align: center

MeshContainer
Create a field, fields container, mesh ... from scratch.

**Transform data**
.. topic:: Access and extract results


.. grid:: 3
.. grid:: 3

.. grid-item-card:: Process creation
:link: ref_tutorials_model
:link-type: ref
:text-align: center
.. grid-item-card:: Narrow down data
:link: ref_tutorials_model
:link-type: ref
:text-align: center

Operators
Scope the data by subsets of time (time sets, time steps.. )
or space (nodes, elements... ).

Workflow
.. grid-item-card:: Extract and explore results data
:link: ref_tutorials_model
:link-type: ref
:text-align: center

.. grid-item-card:: Results visualization
:link: ref_tutorials_model
:link-type: ref
:text-align: center
Get the available results data, results information ...

Plotter
.. grid-item-card:: Extract and explore results metadata
:link: ref_tutorials_model
:link-type: ref
:text-align: center

Animator
Get the available results metadata (meshed region, mesh info... )
and explore the mesh.

**Export data**
.. topic:: Transform data

.. grid:: 3

.. grid:: 3
.. grid-item-card:: Using operators
:link: ref_tutorials_model
:link-type: ref
:text-align: center

.. grid-item-card:: Serialization
:link: ref_tutorials_model
:link-type: ref
:text-align: center
Read, manipulate, analyse the results data using PyDPF-Core operators.

.. grid-item-card:: Create an workflow
:link: ref_tutorials_model
:link-type: ref
:text-align: center

Create more complex operations and customizable results,
by chaining operators together to create workflows.

.. topic:: Visualize the results


.. grid:: 3

.. grid-item-card:: Plotting
:link: ref_tutorials_model
:link-type: ref
:text-align: center

Plotting methods for generating 3D plots of Ansys models directly from Python

.. grid-item-card:: Animations
:link: ref_tutorials_model
:link-type: ref
:text-align: center

Animate the results over their evolution during the analysis

.. topic:: Export data


.. grid:: 3

.. grid-item-card:: Serialization
:link: ref_tutorials_model
:link-type: ref
:text-align: center
Loading