diff --git a/doc/source/_static/custom.css b/doc/source/_static/custom.css index c621c7b647..a778107dd9 100644 --- a/doc/source/_static/custom.css +++ b/doc/source/_static/custom.css @@ -2,3 +2,15 @@ .wy-table-responsive table td, .wy-table-responsive table th { white-space: normal; } +/* Check https://www.w3schools.com/cssref/css_colors.php for colors */ +/* Ansys gold for MAPDL with black text*/ +.sd-bg-mapdl{background-color: #FFB71B} +.sd-bg-text-mapdl{color: Black} +/* Ansys orange accent color for Fluent with black text*/ +.sd-bg-lsdyna{background-color: #FB471F} +.sd-bg-text-lsdyna{color: Black} +/* Ansys blue accent color #00629F for Fluent with black text*/ +.sd-bg-fluent{background-color: #0081D0} +.sd-bg-text-fluent{color: Black} +.sd-bg-cfx{background-color: LightSeaGreen} +.sd-bg-text-cfx{color: Black} diff --git a/doc/source/conf.py b/doc/source/conf.py index 7390890e9c..2663e12c97 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -87,6 +87,7 @@ "sphinx_design", "sphinx_gallery.gen_gallery", 'sphinx_reredirects', + "jupyter_sphinx", ] redirects = { @@ -323,3 +324,17 @@ def reset_servers(gallery_conf, fname, when): # A list of files that should not be packed into the epub file. epub_exclude_files = ["search.html"] + +# Define custom docutils roles for solver badges +from sphinx_design.badges_buttons import BadgeRole + +def setup(app): + badge_roles = { + "bdg-mapdl": "mapdl", + "bdg-cfx": "cfx", + "bdg-fluent": "fluent", + "bdg-lsdyna": "lsdyna" + } + + for role_name, color in badge_roles.items(): + app.add_role(name=role_name, role=BadgeRole(color=color)) diff --git a/doc/source/links_and_refs.rst b/doc/source/links_and_refs.rst new file mode 100644 index 0000000000..d86dce2847 --- /dev/null +++ b/doc/source/links_and_refs.rst @@ -0,0 +1,46 @@ +.. _ref_links_and_refs: + +.. LINKS + +.. Pyansys +.. _pyansys: https://docs.pyansys.com/version/dev/ + +.. PyAnsys Developer Guide +.. _dev_guide_pyansys: https://dev.docs.pyansys.com +.. _dev_guide_contributing: https://dev.docs.pyansys.com/how-to/contributing.html +.. _dev_guide_coding_style: https://dev.docs.pyansys.com/coding-style/index.html +.. _dev_guide_setup_your_environment: https://dev.docs.pyansys.com/how-to/setting-up.html +.. _dev_guide_branch_names: https://dev.docs.pyansys.com/how-to/contributing.html#branch-naming-conventions +.. _dev_guide_commit_names: https://dev.docs.pyansys.com/how-to/contributing.html#commit-naming-conventions + +.. Other libraries +.. _pyvista_docs: https://docs.pyvista.org/version/stable/ +.. _jupyter: https://jupyter.org/ +.. _numpy_org: https://numpy.org/ +.. _numpy_docs: https://numpy.org/doc/stable/ + +.. External links +.. _sphinx: https://www.sphinx-doc.org/en/master/ +.. _sphinx_directives: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html +.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/ +.. _vale: https://www.vale.sh +.. _docutils_directives: https://docutils.sourceforge.io/docs/ref/rst/directives.html + +.. REFERENCES + +.. Main DPF objects +.. |Examples| replace:: :mod:`Examples` +.. |Field| replace:: :class:`Field` +.. |FieldsContainer| replace:: :class:`FieldsContainer` +.. |Model| replace:: :class:`Model ` +.. |DataSources| replace:: :class:`DataSources ` +.. |Scoping| replace:: :class:`Scoping ` +.. |MeshedRegion| replace:: :class:`MeshedRegion ` +.. |MeshInfo| replace:: :class:`MeshInfo ` +.. |Nodes| replace:: :class:`Nodes ` +.. |Elements| replace:: :class:`Elements ` +.. |Faces| replace:: :class:`Faces ` +.. |DpfPlotter| replace:: :class:`DpfPlotter` +.. |Result| replace:: :class:`Result ` +.. |Operator| replace:: :class:`Operator` +.. |TimeFreqSupport| replace:: :class:`TimeFreqSupport ` \ No newline at end of file diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst index 7d1dfab4ae..c6a71c3a91 100644 --- a/doc/source/user_guide/index.rst +++ b/doc/source/user_guide/index.rst @@ -4,24 +4,24 @@ User guide ========== -PyDPF-Core is a Python client API for accessing DPF postprocessing -capabilities. The ``ansys.dpf.core`` package makes highly efficient -computation, customization, and remote postprocessing accessible in Python. +**DPF** provides numerical simulation users and engineers with a toolbox for accessing and +transforming data. -The goals of this section are to: +**PyDPF-Core** is a Python client API for accessing DPF +capabilities. The ``ansys.dpf.core`` package makes highly efficient +computation, customization, and remote data processing accessible in Python. - - Describe the most-used DPF entities and how they can help you to access and modify solver data. - - Provide simple how-tos for tackling the most common use cases. +The goals of this section are to: -.. include:: - concepts/index.rst + - Describe some DPF entities and how they can help you to access and modify solver data. + - Provide detailed tutorials to demonstrate PyDPF-Core functionalities. + - Explain how to resolve the most common issues encountered when using PyDPF-Core .. include:: - main_entities.rst + tutorials/index.rst .. include:: - how_to.rst - + concepts/index.rst Troubleshooting --------------- @@ -52,6 +52,25 @@ Troubleshooting :text-align: center +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Tutorials + + tutorials/data_structures/index.rst + tutorials/language_and_usage/index.rst + tutorials/post_processing_basics/index.rst + tutorials/import_data/index.rst + tutorials/mesh/index.rst + tutorials/transform_data/index.rst + tutorials/export_data/index.rst + tutorials/plot/index.rst + tutorials/animate/index.rst + tutorials/enriching_dpf_capabilities/index.rst + tutorials/distributed_files/index.rst + tutorials/dpf_server/index.rst + tutorials/licensing/index.rst + .. toctree:: :maxdepth: 2 :hidden: @@ -61,30 +80,6 @@ Troubleshooting concepts/waysofusing.rst concepts/stepbystep.rst - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: DPF most-used entities - - model - operators - fields_container - - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: How-tos - - plotting.rst - custom_operators.rst - dpf_server.rst - server_types.rst - server_context.rst - xmlfiles.rst - - .. toctree:: :maxdepth: 3 :hidden: diff --git a/doc/source/user_guide/tutorials/animate/animate_time.rst b/doc/source/user_guide/tutorials/animate/animate_time.rst new file mode 100644 index 0000000000..39feabeb53 --- /dev/null +++ b/doc/source/user_guide/tutorials/animate/animate_time.rst @@ -0,0 +1,361 @@ +.. _ref_tutorials_animate_time: + +====================== +Animate data over time +====================== + +.. |Examples| replace:: :mod:`ansys.dpf.core.examples` +.. |Animator| replace:: :class:`Animator` +.. |Field| replace:: :class:`Field` +.. |FieldsContainer| replace:: :class:`FieldsContainer` +.. |MeshedRegion| replace:: :class:`MeshedRegion ` +.. |TimeFreqSupport| replace:: :class:`TimeFreqSupport ` +.. |animate| replace:: :func:`FieldsContainer.animate() ` +.. |Result| replace:: :class:`Result ` +.. |Operator| replace:: :class:`Operator` +.. |Workflow| replace:: :class:`Workflow` +.. |Elemental| replace:: :class:`elemental` +.. |ElementalNodal| replace:: :class:`elemental_nodal` +.. |Nodal| replace:: :class:`nodal` +.. |Faces| replace:: :class:`faces` +.. |Overall| replace:: :class:`overall` +.. |open_movie| replace:: :class:`pyvista.Plotter.open_movie` + +This tutorial demonstrates how to create 3D animations of data in time. + +:jupyter-download-script:`Download tutorial as Python script` :jupyter-download-notebook:`Download tutorial as Jupyter notebook` + +To animate data across time, you must store the data in a |FieldsContainer| with a ``time`` label. + + +Get the result files +-------------------- + +First, import a results file. For this tutorial, you can use the 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_data` tutorial section. + +.. 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) + +Define a time scoping +--------------------- + +To animate across time, you must define the time steps you are interested in. +This tutorial retrieves all the time steps available in |TimeFreqSupport|, but you can also filter them. +For more information on how to define a scoping, see the ``Narrow down data`` tutorial in the +:ref:`ref_tutorials_import_data` tutorials section. + +.. jupyter-execute:: + + # Get a scoping of all time steps available + time_steps = model.metadata.time_freq_support.time_frequencies + +Extract the results +------------------- + +Extract the results to animate. In this tutorial, you extract the displacement and stress results. + +.. note:: + + Only the |Elemental|, |Nodal|, or |Faces| locations are supported for animations. + |Overall| and |ElementalNodal| locations are not currently supported. + + +.. jupyter-execute:: + + # Get the displacement fields (already on nodes) at all time steps + disp_fc = model.results.displacement(time_scoping=time_steps).eval() + print(disp_fc) + +.. jupyter-execute:: + + # Get the stress fields on nodes at all time steps + # Request the stress on |Nodal| location as the default |ElementalNodal| location is not supported. + stress_fc = model.results.stress.on_location(location=dpf.locations.nodal).on_time_scoping(time_scoping=time_steps).eval() + print(stress_fc) + +Animate the results +------------------- + +Animate the results with the |animate| method. +You can animate them on a deformed mesh (animate the color map and the mesh) +or on a static mesh (animate the color map only). + +The default behavior of the |animate| method is to: + +- Display the norm of the data components; +- Display data at the top layer for shells; +- Display the deformed mesh when animating displacements; +- Display the static mesh for other types of results; +- Use a constant and uniform scale factor of 1.0 when deforming the mesh. + +You can animate any result on a deformed geometry by providing displacement results in the `deform_by` parameter. + +The geometry can be deformed by a |Result| object, an |Operator| (It must evaluate to a |FieldsContainer| +of same length as the one being animated), or a |FieldsContainer| (also of same length as the one being animated). + +.. note:: + + The behavior of the |animate| method is defined by a |Workflow| it creates and feeds to an |Animator|. + This |Workflow| loops over a |Field| of frame indices and for each frame generates a field of norm contours + to render, as well as a displacement field to deform the mesh if `deform_by` is provided. + For more information on plots on deformed meshes see: :ref:`ref_plotting_data_on_deformed_mesh`. + + +Animate the displacement results +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use |animate| with the displacement results. + +.. tab-set:: + + .. tab-item:: Deformed mesh + + .. jupyter-execute:: + :hide-output: + + # Animate the displacement results in a deformed geometry + disp_fc.animate() + + .. jupyter-execute:: + :hide-code: + :hide-output: + + disp_fc.animate(off_screen=True,save_as="source/user_guide/tutorials/animate/animate_disp_1.gif") + + .. image:: animate_disp_1.gif + :scale: 50 % + :align: center + + .. tab-item:: Static mesh + + .. jupyter-execute:: + :hide-output: + + # Animate the displacement results on a static mesh using ``deform_by=False`` + disp_fc.animate(deform_by=False) + + .. jupyter-execute:: + :hide-code: + :hide-output: + + disp_fc.animate(off_screen=True,save_as="source/user_guide/tutorials/animate/animate_disp_2.gif", + deform_by=False) + + .. image:: animate_disp_2.gif + :scale: 50 % + :align: center + +Animate the stress +^^^^^^^^^^^^^^^^^^ + +Use |animate| with the stress results. + +.. tab-set:: + + .. tab-item:: Deformed mesh + + .. jupyter-execute:: + :hide-output: + + # Animate the stress results on a deformed mesh + # Use the ``deform_by`` argument and give the displacement results. + stress_fc.animate(deform_by=disp_fc) + + .. jupyter-execute:: + :hide-code: + :hide-output: + + stress_fc.animate(off_screen=True,save_as="source/user_guide/tutorials/animate/animate_stress_1.gif", + deform_by=disp_fc) + + .. image:: animate_stress_1.gif + :scale: 50 % + :align: center + + .. tab-item:: Static mesh + + .. jupyter-execute:: + :hide-output: + + # Animate the stress results in a static geometry + stress_fc.animate() + + .. jupyter-execute:: + :hide-code: + :hide-output: + + stress_fc.animate(off_screen=True,save_as="source/user_guide/tutorials/animate/animate_stress_2.gif") + + .. image:: animate_stress_2.gif + :scale: 50 % + :align: center + +Change the scale factor +----------------------- + +You can change the scale factor using: + +- A single number for a uniform constant scaling; +- A list of numbers for a varying scaling (same length as the number of frames). + +Uniform constant scaling +^^^^^^^^^^^^^^^^^^^^^^^^ +.. jupyter-execute:: + :hide-output: + + # Define a uniform scale factor + uniform_scale_factor=10. + # Animate the displacements + disp_fc.animate(scale_factor=uniform_scale_factor) + +.. jupyter-execute:: + :hide-code: + :hide-output: + + disp_fc.animate(off_screen=True,save_as="source/user_guide/tutorials/animate/animate_disp_3.gif", + scale_factor=uniform_scale_factor, text="Uniform scale factor") + +.. image:: animate_disp_3.gif + :scale: 45 % + :align: center + +Varying scaling +^^^^^^^^^^^^^^^ + +.. jupyter-execute:: + :hide-output: + + # Define a varying scale factor + varying_scale_factor = [i for i in range(len(disp_fc))] + # Animate the displacements + disp_fc.animate(scale_factor=varying_scale_factor) + +.. jupyter-execute:: + :hide-code: + :hide-output: + + disp_fc.animate(off_screen=True,save_as="source/user_guide/tutorials/animate/animate_disp_4.gif", + scale_factor=varying_scale_factor, text="Varying scale factor") + +.. image:: animate_disp_4.gif + :scale: 45 % + :align: center + +Save the animation +------------------ + +You can save the animation using the ``save_as`` argument with a target file path with the desired format as the extension key. +Accepted extensions are: +- ``.gif``; +- ``.avi``; +- ``.mp4`` + +For more information see |open_movie|. + +.. jupyter-execute:: + :hide-output: + + # Animate the stress results and save it + stress_fc.animate(deform_by=disp_fc, save_as="animate_stress.gif") + + +Control the camera +------------------ + +Control the camera with the ``cpos`` argument. + +A camera position is a combination of: +- A position; +- A focal point (the target); +- A upwards vector. + +It results in a list of format: + +.. code-block:: python + + camera_position= [[pos_x, pos_y, pos_z], # position + [fp_x, fp_y, fp_z], # focal point + [up_x, up_y, up_z]] # upwards vector + +The |animate| method accepts a single camera position or a list of camera positions for each frame. + +.. note:: + A tip for defining a camera position is to do a first interactive plot of the data + with argument ``return_cpos=True``, position the camera as desired in the view, and retrieve + the output of the plotting command. + +Fixed camera +^^^^^^^^^^^^ + +.. jupyter-execute:: + :hide-output: + + # Define the camera position + cam_pos = [[0., 2.0, 0.6], [0.05, 0.005, 0.5], [0.0, 0.0, 1.0]] + # Animate the stress with a custom fixed camera position + stress_fc.animate(cpos=cam_pos) + +.. jupyter-execute:: + :hide-code: + :hide-output: + + stress_fc.animate(save_as="source/user_guide/tutorials/animate/animate_disp_5.gif", + cpos=cam_pos, + off_screen=True) + +.. image:: animate_disp_5.gif + :scale: 50 % + :align: center + +Moving camera +^^^^^^^^^^^^^ + +.. jupyter-execute:: + :hide-output: + + import copy + # Define the list of camera positions + cpos_list = [cam_pos] + # Incrementally increase the x coordinate of the camera by 0.1 for each frame + for i in range(1, len(disp_fc)): + new_pos = copy.deepcopy(cpos_list[i-1]) + new_pos[0][0] += 0.1 + cpos_list.append(new_pos) + + # Animate the stress with a moving camera + stress_fc.animate(cpos=cpos_list) + +.. jupyter-execute:: + :hide-code: + :hide-output: + + stress_fc.animate(save_as="source/user_guide/tutorials/animate/animate_disp_6.gif", + cpos=cpos_list, + off_screen=True) + +.. image:: animate_disp_6.gif + :scale: 50 % + :align: center + +Additional options +------------------ + +You can use additional PyVista arguments of |open_movie|), such as: + +- Show or hide the coordinate system axis with ``show_axes=True`` or ``show_axes=False``; +- Render off-screen for batch animation creation with ``off_screen=True``; +- Change the frame-rate with ``framerate``; +- Change the image quality with ``quality``. diff --git a/doc/source/user_guide/tutorials/animate/index.rst b/doc/source/user_guide/tutorials/animate/index.rst new file mode 100644 index 0000000000..6f360c4216 --- /dev/null +++ b/doc/source/user_guide/tutorials/animate/index.rst @@ -0,0 +1,27 @@ +.. _ref_tutorials_animate: + +======= +Animate +======= + +These tutorials demonstrate how to visualize the data as an animation. + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Animate data over time + :link: ref_tutorials_animate_time + :link-type: ref + :text-align: center + + This tutorial shows how to animate your results data over time. + +++ + :bdg-mapdl:`MAPDL` :bdg-lsdyna:`LS-DYNA` :bdg-fluent:`FLUENT` :bdg-cfx:`CFX` + +.. toctree:: + :maxdepth: 2 + :hidden: + + animate_time.rst diff --git a/doc/source/user_guide/tutorials/data_structures/index.rst b/doc/source/user_guide/tutorials/data_structures/index.rst new file mode 100644 index 0000000000..602efc732d --- /dev/null +++ b/doc/source/user_guide/tutorials/data_structures/index.rst @@ -0,0 +1,42 @@ +.. _ref_tutorials_data_structures: + +=================== +DPF data structures +=================== + +DPF uses two main data structures to handle data: Fields and Collections. +Therefore, it is important to be aware of how the data is +structured in those containers. + +The data containers can be: + + - **Raw data storage structures**: Data arrays (a ``Field`` for example) or Data Maps (a ``DataTree`` for example) + - **Collections**: a group of same labeled objects from one DPF raw data storage structure (a ``FieldsContainer`` for example, that is a group of ``Fields`` with the same label) + +These tutorials explains how these structures work and how you can manipulate data within. + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: DPF raw data storage structures + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial shows how to create and work with some DPF data arrays: + Field, StringField and PropertyField + + + .. grid-item-card:: DPF collections + :link: ref_tutorials_language_and_usage + :link-type: ref + :text-align: center + + This tutorial shows how to create and work with some DPF collections: + FieldsContainer, MeshesContainer and ScopingContainer + +.. toctree:: + :maxdepth: 2 + :hidden: diff --git a/doc/source/user_guide/tutorials/distributed_files/index.rst b/doc/source/user_guide/tutorials/distributed_files/index.rst new file mode 100644 index 0000000000..70240e016d --- /dev/null +++ b/doc/source/user_guide/tutorials/distributed_files/index.rst @@ -0,0 +1,31 @@ +.. _ref_tutorials_distributed_files: + +============================== +Post-process distributed files +============================== + +These tutorials show how to create workflows on different processes (possibly on different machines) and connect them. + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Post process data on distributed processes + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Create a custom workflow on distributed processes + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + +.. toctree:: + :maxdepth: 2 + :hidden: + diff --git a/doc/source/user_guide/tutorials/dpf_server/index.rst b/doc/source/user_guide/tutorials/dpf_server/index.rst new file mode 100644 index 0000000000..efc4e1bfdb --- /dev/null +++ b/doc/source/user_guide/tutorials/dpf_server/index.rst @@ -0,0 +1,24 @@ +.. _ref_tutorials_dpf_server: + +========== +DPF server +========== + +This tutorial explains how to manipulate DPF client-server architecture + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Switch between local and remote server + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + +.. toctree:: + :maxdepth: 2 + :hidden: + diff --git a/doc/source/user_guide/tutorials/enriching_dpf_capabilities/index.rst b/doc/source/user_guide/tutorials/enriching_dpf_capabilities/index.rst new file mode 100644 index 0000000000..232c57c2a4 --- /dev/null +++ b/doc/source/user_guide/tutorials/enriching_dpf_capabilities/index.rst @@ -0,0 +1,42 @@ +.. _ref_tutorials_enriching: + +========================== +Enriching DPF capabilities +========================== + +The available DPF capabilities loaded in a DPF application can be enhanced +by creating new operator’s libraries. DPF offers multiple development APIs +depending on your environment. + +These tutorials demonstrate how to develop those plugins for PyDPF-Core (CPython based) + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Create custom operators and plugins + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Create a plug-in package with multiple operators + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Create a plug-in package that has third-party dependencies + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + +.. toctree:: + :maxdepth: 2 + :hidden: + diff --git a/doc/source/user_guide/tutorials/export_data/index.rst b/doc/source/user_guide/tutorials/export_data/index.rst new file mode 100644 index 0000000000..c9be8ecd6c --- /dev/null +++ b/doc/source/user_guide/tutorials/export_data/index.rst @@ -0,0 +1,28 @@ +.. _ref_tutorials_export_data: + +=========== +Export data +=========== + +Data in DPF can be exported to universal file formats, such as VTK, HDF5, and TXT files. +You can use it to generate TH-plots, screenshots, and animations or to create custom result +plots using the `numpy `_ and `matplotlib `_ packages. + +These tutorials explains how to export data from your manipulations with PyDPF-Core. + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: HDF5 export + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + +.. toctree:: + :maxdepth: 2 + :hidden: + diff --git a/doc/source/user_guide/tutorials/import_data/index.rst b/doc/source/user_guide/tutorials/import_data/index.rst new file mode 100644 index 0000000000..112339d5a5 --- /dev/null +++ b/doc/source/user_guide/tutorials/import_data/index.rst @@ -0,0 +1,65 @@ +.. _ref_tutorials_import_data: + +=========== +Import Data +=========== + +These tutorials demonstrate how to represent data in DPF: either from manual input either +form simulation result files. + +From user input +*************** + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Import data from csv file + :link: ref_tutorials + :link-type: ref + :text-align: center + + Learn how to import data in DPF from csv file + + .. grid-item-card:: Represent your data in DPF + :link: ref_tutorials + :link-type: ref + :text-align: center + + Learn how to represent your manual input data in a DPF data storage structure + +From result files +***************** + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Extract and explore results metadata + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Extract and explore results + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Narrow down data (scoping tutorial) + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + +.. toctree:: + :maxdepth: 2 + :hidden: + diff --git a/doc/source/user_guide/tutorials/index.rst b/doc/source/user_guide/tutorials/index.rst new file mode 100644 index 0000000000..f982528585 --- /dev/null +++ b/doc/source/user_guide/tutorials/index.rst @@ -0,0 +1,144 @@ +.. _ref_tutorials: + +Tutorials +--------- + +The tutorials cover specifics features with detailed demonstrations to help +understanding the fundamental PyDPF-Core functionalities and clarify some concepts. +They are designed to teach how to perform a task, providing explanations at each stage. + +It helps to have a Python interpreter for hands-on experience, but all code examples are +executed, so the tutorial can be read off-line as well. + +For a complete description of all the objects and modules, see the :ref:`API reference ` +section. + +:fa:`person-running` Beginner's guide +************************************* + +New to PyDPF-Core? Check our beginner's tutorials. They offer an overview +of our package background so you can understand how to work with it. + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: PyDPF-Core data structures + :link: ref_tutorials_data_structures + :link-type: ref + :text-align: center + + Learn the different data structures used by DPF when handling data + + .. grid-item-card:: PyDPF-Core language + :link: ref_tutorials_language_and_usage + :link-type: ref + :text-align: center + + Check an overview on how to use PyDPF-Core API. + Learn the different ways to interact with data by using PyDPF-Core + objects and methods. + + .. grid-item-card:: Post-processing data basics + :link: ref_tutorials_processing_basics + :link-type: ref + :text-align: center + + Learn the basics on a post-processing procedure + using PyDPf-Core based on its usual main steps. The goal is to + transform simulation data into output data that can be used to + visualize and analyze simulation results. + +:fa:`book-open-reader` Features usage +************************************* + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Import Data on DPF + :link: ref_tutorials_import_data + :link-type: ref + :text-align: center + + Understand how to represent data in DPF: either from manual input either form result files. + + .. grid-item-card:: Mesh analysis + :link: ref_tutorials_mesh + :link-type: ref + :text-align: center + + Learn how to explore a mesh in DPF. + + .. grid-item-card:: Transform data with PyDPF-Core + :link: ref_tutorials_transform_data + :link-type: ref + :text-align: center + + Learn how to transform and operate on data to obtain the desired input. + + .. grid-item-card:: Export data from DPF + :link: ref_tutorials_export_data + :link-type: ref + :text-align: center + + Discover the best ways to export data from your manipulations with PyDPF-Core. + + .. grid-item-card:: Plot + :link: ref_tutorials_plot + :link-type: ref + :text-align: center + + Explore the different approaches to visualise the data in plots. + + .. grid-item-card:: Animate + :link: ref_tutorials_animate + :link-type: ref + :text-align: center + + Explore the different approaches to visualise the data in an animation. + + .. grid-item-card:: Enriching DPF capabilities + :link: ref_tutorials_enriching + :link-type: ref + :text-align: center + + Discover how to enhance DPF capabilities by creating new operator’s libraries. + + .. grid-item-card:: Post-process distributed files + :link: ref_tutorials_distributed_files + :link-type: ref + :text-align: center + + Learn how to use PyDPF-Core with distributed files. + + .. grid-item-card:: DPF server + :link: ref_tutorials_dpf_server + :link-type: ref + :text-align: center + + Understand how to manipulate DPF client-server architecture + + .. grid-item-card:: Licensing + :link: ref_tutorials_licensing + :link-type: ref + :text-align: center + + Understand how to access the Entry and Premium licensing capabilities + + .. grid-item-card:: Mathematical operations + :link: ref_tutorials_mathematics + :link-type: ref + :text-align: center + + Learn how to do mathematical operations using PyDPF-Core API and data structures + + .. grid-item-card:: Manipulating physics data + :link: ref_tutorials_mathematics + :link-type: ref + :text-align: center + + Learn how to manipulate the physics data associate to a + data storage structure. (Unit, homogeneity ...) \ No newline at end of file diff --git a/doc/source/user_guide/tutorials/language_and_usage/index.rst b/doc/source/user_guide/tutorials/language_and_usage/index.rst new file mode 100644 index 0000000000..d56d10a795 --- /dev/null +++ b/doc/source/user_guide/tutorials/language_and_usage/index.rst @@ -0,0 +1,10 @@ +.. _ref_tutorials_language_and_usage: + +============================= +PyDPF-Core language and usage +============================= + +This tutorials gives you an overview on how the PyDPF-Core API can be used +to interact with data. + +For more detailed information on each module and function, see :ref:`ref_api_section`. diff --git a/doc/source/user_guide/tutorials/licensing/index.rst b/doc/source/user_guide/tutorials/licensing/index.rst new file mode 100644 index 0000000000..e7760c435b --- /dev/null +++ b/doc/source/user_guide/tutorials/licensing/index.rst @@ -0,0 +1,25 @@ +.. _ref_tutorials_licensing: + +========= +Licensing +========= + +This tutorial explains the DPF server licensing logic. Here you +learn about the Entry and Premium licensing capabilities + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Access Entry and Premium Capabilities + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + +.. toctree:: + :maxdepth: 2 + :hidden: + diff --git a/doc/source/user_guide/tutorials/manipulate_physics_data/index.rst b/doc/source/user_guide/tutorials/manipulate_physics_data/index.rst new file mode 100644 index 0000000000..31b4fd3665 --- /dev/null +++ b/doc/source/user_guide/tutorials/manipulate_physics_data/index.rst @@ -0,0 +1,24 @@ +.. _ref_tutorials_manipulate_physics_data: + +======================= +Manipulate Physics data +======================= + +This sections demonstrates how to manipulate the physics data associate to a +data storage structure. (Unit, homogeneity ...). + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Unit + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + +.. toctree:: + :maxdepth: 2 + :hidden: diff --git a/doc/source/user_guide/tutorials/mathematics/index.rst b/doc/source/user_guide/tutorials/mathematics/index.rst new file mode 100644 index 0000000000..b4c251b086 --- /dev/null +++ b/doc/source/user_guide/tutorials/mathematics/index.rst @@ -0,0 +1,32 @@ +.. _ref_tutorials_mathematics: + +=========== +Mathematics +=========== + +DPF provides operators for implementing mathematical operations, ranging +from addition and multiplication to FFT and QR solving. + +This section explains how to you can do mathematical operations using +PyDPF-Core API and data structures. + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Basic maths + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial demonstrate how to do some basic + mathematical operations with PyDPF-Core. + +.. toctree:: + :maxdepth: 2 + :hidden: + + + + diff --git a/doc/source/user_guide/tutorials/mesh/index.rst b/doc/source/user_guide/tutorials/mesh/index.rst new file mode 100644 index 0000000000..8464839b40 --- /dev/null +++ b/doc/source/user_guide/tutorials/mesh/index.rst @@ -0,0 +1,61 @@ +.. _ref_tutorials_mesh: + +==== +Mesh +==== + +The mesh in DPF is represented by the :class:`MeshedRegion ` entity. + +These tutorials explains how to explore different attributes of a given mesh with PyDPF-Core. + + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Create a mesh from scratch + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Get the mesh from a result file + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Read the mesh metadata + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Read the mesh + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Read a subpart of the mesh + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Split the mesh + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + +.. toctree:: + :maxdepth: 2 + :hidden: diff --git a/doc/source/user_guide/tutorials/plot/index.rst b/doc/source/user_guide/tutorials/plot/index.rst new file mode 100644 index 0000000000..32f11495e5 --- /dev/null +++ b/doc/source/user_guide/tutorials/plot/index.rst @@ -0,0 +1,44 @@ +.. _ref_tutorials_plot: + +==== +Plot +==== + +These tutorials demonstrate some different approaches to visualise the data in plots. + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Plotting meshes + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Plotting data on the mesh + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Plotting data on specific placements + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Plotting a graph + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + +.. toctree:: + :maxdepth: 2 + :hidden: diff --git a/doc/source/user_guide/tutorials/post_processing_basics/01-main-steps.rst b/doc/source/user_guide/tutorials/post_processing_basics/01-main-steps.rst new file mode 100644 index 0000000000..43ef9b3a36 --- /dev/null +++ b/doc/source/user_guide/tutorials/post_processing_basics/01-main-steps.rst @@ -0,0 +1,199 @@ +.. _tutorials_main_steps: + +Postprocessing main steps +------------------------- + +There are five main steps to transform simulation data into output data that can +be used to visualize and analyze simulation results: + +.. grid:: + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: 1 + :link: tutorials_main_steps_1 + :link-type: ref + :text-align: center + + Importing and opening results files + + .. grid-item-card:: 2 + :link: tutorials_main_steps_2 + :link-type: ref + :text-align: center + + Access and extract results + + .. grid-item-card:: 3 + :link: tutorials_main_steps_3 + :link-type: ref + :text-align: center + + Transform available data + + .. grid-item-card:: 4 + :link: tutorials_main_steps_4 + :link-type: ref + :text-align: center + + Visualize the data + + .. grid-item-card:: 5 + :link: tutorials_main_steps_5 + :link-type: ref + :text-align: center + + Export data + +.. _tutorials_main_steps_1: + +1- Importing and opening results files +************************************** + +First, import the DPF-Core module as ``dpf`` and import the included examples file + +.. code-block:: python + + from ansys.dpf import core as dpf + from ansys.dpf.core import examples + from ansys.dpf.core import operators as ops + +`DataSources' is a class that manages paths to their files. Use this object to declare +data inputs for DPF and define their locations. + +.. code-block:: python + + # Define the DataSources object + my_data_sources = dpf.DataSources(result_path=examples.find_simple_bar()) + + +The model is a helper designed to give shortcuts to access the analysis results +metadata, by opening a DataSources or a Streams, and to instanciate results provider for it. + +Printing the model displays: + + - Analysis type + - Available results + - Size of the mesh + - Number of results + +.. code-block:: python + + # Define the Model object + my_model = dpf.Model(data_sources=my_data_sources) + print(my_model) + +.. rst-class:: sphx-glr-script-out + + .. jupyter-execute:: + :hide-code: + + from ansys.dpf import core as dpf + from ansys.dpf.core import examples + from ansys.dpf.core import operators as ops + my_data_sources = dpf.DataSources(result_path=examples.find_simple_bar()) + my_model = dpf.Model(data_sources=my_data_sources) + print(my_model) + +.. _tutorials_main_steps_2: + +2- Access and extract results +***************************** + +We see in the model that a displacement result is available. You can access this result by: + +.. code-block:: python + + # Define the displacement results through the models property `results` + my_displacements = my_model.results.displacement.eval() + print(my_displacements) + +.. rst-class:: sphx-glr-script-out + + .. jupyter-execute:: + :hide-code: + + my_displacements = my_model.results.displacement.eval() + print(my_displacements) + +The displacement data can be extract by: + +.. code-block:: python + + # Extract the data of the displacement field + my_displacements_0 = my_displacements[0].data + print(my_displacements_0) + +.. rst-class:: sphx-glr-script-out + + .. jupyter-execute:: + :hide-code: + + my_displacements_0 = my_displacements[0].data + print(my_displacements_0) + +.. _tutorials_main_steps_3: + +3- Transform available data +*************************** + +Several transformations can be made with the data. They can be a single operation, +by using only one operator, or they can represent a succession of operations, by defining a +workflow with chained operators. + +Here we star by computing the displacements norm. + +.. code-block:: python + + # Define the norm operator (here for a fields container) for the displacement + my_norm = ops.math.norm_fc(fields_container=my_displacements).eval() + print(my_norm[0].data) + +.. rst-class:: sphx-glr-script-out + + .. jupyter-execute:: + :hide-code: + + my_norm = ops.math.norm_fc(fields_container=my_displacements).eval() + print(my_norm[0].data) + +Then we compute the maximum values of the normalised displacement + +.. code-block:: python + + # Define the maximum operator and chain it to the norm operator + my_max= ops.min_max.min_max_fc(fields_container=my_norm).outputs.field_max() + print(my_max) + +.. rst-class:: sphx-glr-script-out + + .. jupyter-execute:: + :hide-code: + + my_max = ops.min_max.min_max_fc(fields_container=my_norm).outputs.field_max() + print(my_max) + +.. _tutorials_main_steps_4: + +4- Visualize the data +********************* + +Plot the transformed displacement results + +.. code-block:: python + + # Define the support of the plot (here we plot the displacement over the mesh) + my_model.metadata.meshed_region.plot(field_or_fields_container=my_displacements) + +.. rst-class:: sphx-glr-script-out + + .. jupyter-execute:: + :hide-code: + + my_model.metadata.meshed_region.plot(field_or_fields_container=my_displacements) + +.. _tutorials_main_steps_5: + +5- Extract the data +******************* \ No newline at end of file diff --git a/doc/source/user_guide/tutorials/post_processing_basics/index.rst b/doc/source/user_guide/tutorials/post_processing_basics/index.rst new file mode 100644 index 0000000000..b98cf33a34 --- /dev/null +++ b/doc/source/user_guide/tutorials/post_processing_basics/index.rst @@ -0,0 +1,14 @@ +.. _ref_tutorials_processing_basics: + +====================== +Processing data basics +====================== + +Data Processing consists in a series of operations applied to data to achieve a goal. DPF enables +you to access and transform simulation data using customizable workflows. + +There is an extensive catalog of operators with different kinds and complexity that can be used together. + +The tutorials in this section presents a basic application of PyDPF-Core as post-processing tool. + +.. include:: 01-main-steps.rst \ No newline at end of file diff --git a/doc/source/user_guide/tutorials/transform_data/index.rst b/doc/source/user_guide/tutorials/transform_data/index.rst new file mode 100644 index 0000000000..1af0c017fc --- /dev/null +++ b/doc/source/user_guide/tutorials/transform_data/index.rst @@ -0,0 +1,49 @@ +.. _ref_tutorials_transform_data: + +============== +Transform data +============== + +An operator is the main object that is used to create, transform, and stream data in DPF. + +They can perform different modifications with the data: direct mathematical operations, +averaging in the mesh, changes in the model locations .... They can also be chained together +to create more complex operations and customizable results. + +The tutorials in this section aims to explain how to transform and operate on data to obtain +the desired input by using the DPF operators with PyDPF-Core. + +For more information on how to program with PyDPF-Core check the +:ref:`ref_tutorials_language_and_usage` tutorial. + + +.. grid:: 1 1 3 3 + :gutter: 2 + :padding: 2 + :margin: 2 + + .. grid-item-card:: Using operators + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Create a workflow + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + + .. grid-item-card:: Mathematical operations with PyDPF-Core data storage structures + :link: ref_tutorials + :link-type: ref + :text-align: center + + This tutorial + +.. toctree:: + :maxdepth: 2 + :hidden: + diff --git a/requirements/requirements_docs.txt b/requirements/requirements_docs.txt index 9906654e9e..d5a2cb450f 100644 --- a/requirements/requirements_docs.txt +++ b/requirements/requirements_docs.txt @@ -3,6 +3,7 @@ enum-tools[sphinx]==0.12.0 graphviz==0.20.1 imageio==2.36.0 imageio-ffmpeg==0.5.1 +jupyter_sphinx==0.5.3 nbsphinx==0.9.5 pypandoc==1.14 pytest-sphinx==0.6.3