Rewrite PyDPF-Post doc to PyAnsys library style guidelines (#785)

* Rewriting PyDPF-Post doc to PyAnsys library style guidelines * Add Sphinx-Design extension for support of cards * Add sphinx_design to conf.py file * Run pre-commit to fix code style issue * Fix error in doc requirements file * Adjust sphinx-design version in doc requirements file * Remove bad formatting * Edits based on HTML artifact and updates to User guide section * Minor edits based on HTML artifact reveiw * Mostly edits to example files * Fix icon and change figure to image directive * Edits to contribute and cleanup based on HTML artifact * Update doc/source/getting_started/demo.rst * Set image alignment to center for now * Fix footnote confusion and add example link * Format fixes to previous commit * Fix typo * Add key differenences between Core and Post to README and doc landing page * Apply suggestions from code review Implement Paul's suggestions Co-authored-by: Paul Profizi <[email protected]> * Add additional Ansys solver result file support info --------- Co-authored-by: Roberto Pastor Muela <[email protected]> Co-authored-by: Paul Profizi <[email protected]>
ansys · Jan 31, 2025 · 7553885 · 7553885
1 parent 14850f7
commit 7553885
Show file tree

Hide file tree

Showing 59 changed files with 1,081 additions and 1,004 deletions.
diff --git a/README.md b/README.md
@@ -1,42 +1,47 @@
-# PyDPF-Post - Ansys Data PostProcessing Framework
+# PyDPF-Post
 [![PyAnsys](https://img.shields.io/badge/Py-Ansys-ffc107.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC)](https://docs.pyansys.com/)
 [![Python](https://img.shields.io/pypi/pyversions/ansys-dpf-post?logo=pypi)](https://pypi.org/project/ansys-dpf-post/)
 [![pypi](https://badge.fury.io/py/ansys-dpf-post.svg?logo=python&logoColor=white)](https://pypi.org/project/ansys-dpf-post)
 [![MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Ansys Data Processing Framework (DPF) provides numerical simulation 
-users and engineers with a toolbox for accessing and transforming simulation 
-data. With DPF, you can perform complex preprocessing or postprocessing of
-large amounts of simulation data within a simulation workflow.
+PyDPF-Post is part of the Ansys Data Processing Framework (DPF), which provides reusable operators
+that let you access and transform simulation data coming from different Ansys and third-party
+result files.
 
-The Python `ansys-dpf-post` package provides a high-level, physics-oriented
-API for postprocessing. Loading a simulation (defined by its results files)
-allows you to extract simulation metadata and results and then apply
-postprocessing operations on them.
+PyDPF-Post leverages [PyDPF-Core](https://github.com/ansys/pydpf-core), a package for building more
+advanced and customized workflows using Ansys DPF. After loading a simulation's result file in PyDPF-Post,
+you can extract simulation metadata and results and then apply postprocessing operations on them.
 
-The latest version of DPF supports Ansys solver results files for:
+PyDPF-Core is physics-agnostic and operator-oriented. It is a direct exposure of the DPF features and
+objects with a few helpers. It is not restricted to postprocessing.
 
-  - Mechanical APDL (`.rst`, `.mode`, `.rfrq`, `.rdsp`)
-  - LS-DYNA (`.d3plot`, `.binout`)
-  - Fluent (`.cas/dat.h5`, `.flprj`)
-  - CFX (`.cas/dat.cff`, `.flprj`, `.res`)
-
-For more information on file support, see the [main page](https://dpf.docs.pyansys.com/version/stable/index.html)
-in the PyDPF-Core documentation.
-
-PyDPF-Post leverages the PyDPF-Core project's ``ansys-dpf-core`` package, which is
-available at [PyDPF-Core GitHub](https://github.com/ansys/pydpf-core).
-Use the ``ansys-dpf-core`` package for building more advanced and customized workflows
-using Ansys DPF.
+PyDPF-Post on the other hand provides a high-level, physics-oriented API for postprocessing. It has a
+more Pythonic and user-friendly API dedicated to postprocessing, with new objects meant to provide a specific
+interface for each type of physics and analysis (such as mechanics static versus transient versus fluids).
+Most importantly, there is no need to manipulate operators or workflows.
 
 ## Documentation and issues
 
 Documentation for the latest stable release of PyPDF-Post is hosted at
 [PyDPF-Post documentation](https://post.docs.pyansys.com/version/stable/).
 
-In the upper right corner of the documentation's title bar, there is an option for switching from
-viewing the documentation for the latest stable release to viewing the documentation for the
-development version or previously released versions.
+The PyDPF-Post documentation has five sections:
+
+- [Getting started](https://post.docs.pyansys.com/version/stable/getting_started/index.html): Learn how to
+  install PyDPF-Post in user mode and quickly begin using it.
+- [User guide](https://post.docs.pyansys.com/version/stable/user_guide/index.html): Understand key concepts
+  for using PyDPF-Post.
+- [API reference](https://post.docs.pyansys.com/version/stable/api/index.html): Understand how to use
+  Python to interact programmatically with PyDPF-Post.
+- [Examples](https://post.docs.pyansys.com/version/stable/examples/index.html): Explore examples
+  that show how to use PyDPF-Post to perform nay different types of operations.
+- [Contribute](https://post.docs.pyansys.com/version/stable/contributing.html): Learn how to
+  contribute to the PyDPF-Post codebase or documentation.
+
+In the upper right corner of the documentation's title bar, there is an option
+for switching from viewing the documentation for the latest stable release
+to viewing the documentation for the development version or previously
+released versions.
 
 You can also [view](https://cheatsheets.docs.pyansys.com/pydpf-post_cheat_sheet.png) or
 [download](https://cheatsheets.docs.pyansys.com/pydpf-post_cheat_sheet.pdf) the
@@ -45,82 +50,8 @@ for using PyDPF-Post.
 
 On the [PyDPF-Post Issues](https://github.com/ansys/pydpf-post/issues) page,
 you can create issues to report bugs and request new features. On the
-[PyDPF-Post Discussions](https://github.com/ansys/pydpf-post/discussions) page or the [Discussions](https://discuss.ansys.com/)
-page on the Ansys Developer portal, you can post questions, share ideas, and get community feedback. 
+[PyDPF-Post Discussions](https://github.com/ansys/pydpf-post/discussions) page or
+the [Discussions](https://discuss.ansys.com/) page on the Ansys Developer portal,
+you can post questions, share ideas, and get community feedback. 
 
 To reach the project support team, email [[email protected]](mailto:[email protected]).
-
-## Installation
-
-To install this package, run this command:
-
-```
-pip install ansys-dpf-post
-```
-
-You can also clone and install this package with these commands:
-
-```
-git clone https://github.com/ansys/pydpf-post
-cd pydpf-post
-pip install . --user
-```
-
-## Brief demo
-
-Provided you have Ansys 2023 R1 or later installed, a DPF server automatically starts
-once you start using PyDPF-Post.
-
-To load a simulation for a MAPDL result file to extract and
-postprocess results, use this code:
-
-```pycon
->>> from ansys.dpf import post
->>> from ansys.dpf.post import examples
->>> simulation = post.load_simulation(examples.download_crankshaft())
->>> displacement = simulation.displacement()
->>> print(displacement)
-```
-```pycon
-             results       U (m)
-             set_ids           3
- node_ids components            
-     4872          X -3.4137e-05
-                   Y  1.5417e-03
-                   Z -2.6398e-06
-     9005          X -5.5625e-05
-                   Y  1.4448e-03
-                   Z  5.3134e-06
-      ...        ...         ...
-```
-```pycon
->>> displacement.plot()
-```
-![Example Displacement plot Crankshaft](https://github.com/ansys/pydpf-post/raw/master/docs/source/images/crankshaft_disp.png)
-```pycon
->>> stress_eqv = simulation.stress_eqv_von_mises_nodal()
->>> stress_eqv.plot()
-```
-![Example Stress plot Crankshaft](https://github.com/ansys/pydpf-post/raw/master/docs/source/images/crankshaft_stress.png)
-
-To run PyDPF-Post with Ansys 2021 R1 through 2022 R2, use this code to
-start the legacy PyDPF-Post tools:
-
-```pycon
->>> from ansys.dpf import post
->>> from ansys.dpf.post import examples
->>> solution = post.load_solution(examples.download_crankshaft())
->>> stress = solution.stress()
->>> stress.eqv.plot_contour(show_edges=False)
-```
-![Example Stress plot Crankshaft](https://github.com/ansys/pydpf-post/raw/master/docs/source/images/crankshaft_stress.png)
-
-## License and acknowledgements
-
-PyDPF-Post is licensed under the MIT license. For more information, see the
-[LICENSE](https://github.com/ansys/pydpf-post/raw/master/LICENSE) file.
-
-PyDPF-Post makes no commercial claim over Ansys whatsoever. This library
-extends the functionality of Ansys DPF by adding a Python interface
-to DPF without changing the core behavior or license of the original
-software.
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -79,6 +79,7 @@
     "sphinx.ext.todo",
     "sphinx_copybutton",
     "sphinx_gallery.gen_gallery",
+    "sphinx_design",
 ]
 
 typehints_defaults = "comma"

diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
@@ -6,20 +6,23 @@ Contribute
 
 Overall guidance on contributing to a PyAnsys repository appears in
 `Contribute <https://dev.docs.pyansys.com/overview/contributing.html>`_
-in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar
-with this guide, paying particular attention to `Guidelines and Best Practices
-<https://dev.docs.pyansys.com/guidelines/index.html>`_, before attempting
-to contribute to PyDPF-Post.
+in the *PyAnsys developer's guide*. Ensure that you are thoroughly familiar
+with this guide before attempting to contribute to PyDPF-Post.
 
 The following contribution information is specific to PyDPF-Post.
 
-Clone the repository
---------------------
+Install in development mode
+---------------------------
 
-To clone and install the latest version of PyDPF-Core in
-development mode, run:
+If you want to edit and potentially contribute to PyDPF-Post,
+clone the repository and install it using ``pip`` with the ``-e``
+development flag:
 
-.. include:: pydpf-post_clone_install.rst
+.. code::
+
+    git clone https://github.com/ansys/pydpf-post
+    cd pydpf-post
+    pip install -e .
 
 
 Post issues
@@ -29,13 +32,3 @@ Use the `PyDPF-Post Issues <https://github.com/ansys/pydpf-post/issues>`_
 page to submit questions, report bugs, and request new features.
 
 To reach the project support team, email `[email protected] <[email protected]>`_.
-
-View documentation
-------------------
-Documentation for the latest stable release of PyDPF-Post is hosted at
-`PyDPF Documentation <https://post.docs.pyansys.com/>`_.
-
-In the upper right corner of the documentation's title bar, there is an option
-for switching from viewing the documentation for the latest stable release
-to viewing the documentation for the development version or previously
-released versions.
diff --git a/doc/source/getting_started/compatibility.rst b/doc/source/getting_started/compatibility.rst
@@ -1,27 +1,32 @@
 .. _compatibility:
 
-=============
-Compatibility
-=============
+=============================
+PyDPF library compatibilities
+=============================
 
-PyDPF-Post supports Windows 10 and CentOS 7 and later. For
-more information, see `Ansys Platform Support <https://www.ansys.com/solutions/solutions-by-role/it-professionals/platform-support>`_.
+Potential crashes can occur when using PyDPF-Post 0.2.2 or earlier with PyDPF-Core 0.5.2
+or later. For a given DPF server version, the following table indicates version compatibilities
+for these two libraries.
 
-Other platforms may be supported by using PyDPF-Post in a
-containerized ecosystem, such as `Docker <https://www.docker.com/>`_ or
-`Kubernetes <https://kubernetes.io/>`_.
-
-Due to potential crashes when using PyDPF-Post 0.2.2 or earlier with PyDPF-Core 0.5.2
-or later, you should refer to the following table for compatibility between these two
-libraries.
-
-.. list-table:: PyDPF compatibility
+.. list-table:: **PyDPF library compatibilities**
    :widths: 20 20 20
    :header-rows: 1
 
    * - DPF server version
-     - ansys.dpf.core python module version
-     - ansys.dpf.post python module version
+     - PyDPF-Core version
+     - PyDPF-Post version
+   * - 10.0 (DPF Server 2025.2.pre0)
+     - 0.13.4 or later
+     - 0.9.0 or later
+   * - 9.1 (Ansys 2025 R1)
+     - 0.13.4 or later
+     - 0.9.0 or later
+   * - 9.0 (DPF Server 2025.1.pre0)
+     - 0.13.0 or later
+     - 0.9.0 or later
+   * - 8.2 (Ansys 2024 R2)
+     - 0.12.1 or later
+     - 0.8.0 or later
    * - 8.1 (DPF Server 2024.2.pre1)
      - 0.12.0 or later
      - 0.8.0 or later
@@ -53,10 +58,10 @@ libraries.
      - 0.4.0 to 0.9.0
      - 0.1.0 to 0.5.0
    * - 2.0 (Ansys 2021 R2)
-     - 0.3.0 to 0.9.0**
+     - 0.3.0 to 0.9.0*
      - 0.1.0 to 0.5.0
    * - 1.0 (Ansys 2021 R1)
-     - 0.2.*
+     - 0.2.0 to 0.2.x
      - 0.1.0
 
-(** Compatibility of DPF 2.0 with ansys-dpf-core 0.5.0 to 0.9.0 is assumed but not certified.)
+*Compatibility of DPF 2.0 with PyDPF-Core 0.5.0 to 0.9.0 is assumed but not certified.
diff --git a/doc/source/getting_started/demo.rst b/doc/source/getting_started/demo.rst
@@ -0,0 +1,78 @@
+==========
+Brief demo
+==========
+
+This brief demo shows how to load an Ansys Mechanical APDL (MAPDL) result file to extract
+and postprocess results. The code to use depends on which Ansys version you have installed.
+For comprehensive examples of how to use PyDPF-Post, see :ref:`gallery`.
+
+2023 R1 and later
+-----------------
+
+If Ansys 2023 R1 or later is installed, a DPF server automatically starts
+once you start using PyDPF-Post. Use this code to load an MAPDL result file
+to extract and postprocess results:
+
+.. code:: python
+
+    >>> from ansys.dpf import post
+    >>> from ansys.dpf.post import examples
+    >>> simulation = post.load_simulation(examples.download_crankshaft())
+    >>> displacement = simulation.displacement()
+    >>> print(displacement)
+
+
+.. rst-class:: sphx-glr-script-out
+
+ .. code-block:: none
+
+             results         U
+              set_id         3
+      node      comp
+      4872         X -3.41e-05
+                   Y  1.54e-03
+                   Z -2.64e-06
+      9005         X -5.56e-05
+                   Y  1.44e-03
+                   Z  5.31e-06
+       ...
+
+.. code:: python
+
+    >>> displacement.plot()
+
+
+.. image:: ./../images/crankshaft_disp.png
+    :align: center
+    :width: 300pt
+
+
+.. code:: python
+
+    >>> stress_eqv = simulation.stress_eqv_von_mises_nodal()
+    >>> stress_eqv.plot()
+
+.. image:: ./../images/crankshaft_stress.png
+    :align: center
+    :figwidth: 300pt
+
+
+2021 R1 through 2022 R2
+-----------------------
+
+If an Ansys release of 2021 R1 through 2022 R2 is installed, use this code to
+start the legacy PyDPF-Post tools and then load an MAPDL result file
+to extract and postprocess results:
+
+.. code:: python
+
+    >>> from ansys.dpf import post
+    >>> from ansys.dpf.post import examples
+    >>> solution = post.load_solution(examples.download_crankshaft())
+    >>> stress = solution.stress()
+    >>> stress.eqv.plot_contour(show_edges=False)
+
+.. image:: ./../images/crankshaft_stress.png
+    :align: center
+    :width: 300pt
+