Skip to content

Commit 7553885

Browse files
PipKatRobPasMuePProfizi
authored
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]>
1 parent 14850f7 commit 7553885

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

59 files changed

+1081
-1004
lines changed

‎README.md

+33-102
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,47 @@
1-
# PyDPF-Post - Ansys Data PostProcessing Framework
1+
# PyDPF-Post
22
[![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/)
33
[![Python](https://img.shields.io/pypi/pyversions/ansys-dpf-post?logo=pypi)](https://pypi.org/project/ansys-dpf-post/)
44
[![pypi](https://badge.fury.io/py/ansys-dpf-post.svg?logo=python&logoColor=white)](https://pypi.org/project/ansys-dpf-post)
55
[![MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
66

7-
Ansys Data Processing Framework (DPF) provides numerical simulation
8-
users and engineers with a toolbox for accessing and transforming simulation
9-
data. With DPF, you can perform complex preprocessing or postprocessing of
10-
large amounts of simulation data within a simulation workflow.
7+
PyDPF-Post is part of the Ansys Data Processing Framework (DPF), which provides reusable operators
8+
that let you access and transform simulation data coming from different Ansys and third-party
9+
result files.
1110

12-
The Python `ansys-dpf-post` package provides a high-level, physics-oriented
13-
API for postprocessing. Loading a simulation (defined by its results files)
14-
allows you to extract simulation metadata and results and then apply
15-
postprocessing operations on them.
11+
PyDPF-Post leverages [PyDPF-Core](https://github.com/ansys/pydpf-core), a package for building more
12+
advanced and customized workflows using Ansys DPF. After loading a simulation's result file in PyDPF-Post,
13+
you can extract simulation metadata and results and then apply postprocessing operations on them.
1614

17-
The latest version of DPF supports Ansys solver results files for:
15+
PyDPF-Core is physics-agnostic and operator-oriented. It is a direct exposure of the DPF features and
16+
objects with a few helpers. It is not restricted to postprocessing.
1817

19-
- Mechanical APDL (`.rst`, `.mode`, `.rfrq`, `.rdsp`)
20-
- LS-DYNA (`.d3plot`, `.binout`)
21-
- Fluent (`.cas/dat.h5`, `.flprj`)
22-
- CFX (`.cas/dat.cff`, `.flprj`, `.res`)
23-
24-
For more information on file support, see the [main page](https://dpf.docs.pyansys.com/version/stable/index.html)
25-
in the PyDPF-Core documentation.
26-
27-
PyDPF-Post leverages the PyDPF-Core project's ``ansys-dpf-core`` package, which is
28-
available at [PyDPF-Core GitHub](https://github.com/ansys/pydpf-core).
29-
Use the ``ansys-dpf-core`` package for building more advanced and customized workflows
30-
using Ansys DPF.
18+
PyDPF-Post on the other hand provides a high-level, physics-oriented API for postprocessing. It has a
19+
more Pythonic and user-friendly API dedicated to postprocessing, with new objects meant to provide a specific
20+
interface for each type of physics and analysis (such as mechanics static versus transient versus fluids).
21+
Most importantly, there is no need to manipulate operators or workflows.
3122

3223
## Documentation and issues
3324

3425
Documentation for the latest stable release of PyPDF-Post is hosted at
3526
[PyDPF-Post documentation](https://post.docs.pyansys.com/version/stable/).
3627

37-
In the upper right corner of the documentation's title bar, there is an option for switching from
38-
viewing the documentation for the latest stable release to viewing the documentation for the
39-
development version or previously released versions.
28+
The PyDPF-Post documentation has five sections:
29+
30+
- [Getting started](https://post.docs.pyansys.com/version/stable/getting_started/index.html): Learn how to
31+
install PyDPF-Post in user mode and quickly begin using it.
32+
- [User guide](https://post.docs.pyansys.com/version/stable/user_guide/index.html): Understand key concepts
33+
for using PyDPF-Post.
34+
- [API reference](https://post.docs.pyansys.com/version/stable/api/index.html): Understand how to use
35+
Python to interact programmatically with PyDPF-Post.
36+
- [Examples](https://post.docs.pyansys.com/version/stable/examples/index.html): Explore examples
37+
that show how to use PyDPF-Post to perform nay different types of operations.
38+
- [Contribute](https://post.docs.pyansys.com/version/stable/contributing.html): Learn how to
39+
contribute to the PyDPF-Post codebase or documentation.
40+
41+
In the upper right corner of the documentation's title bar, there is an option
42+
for switching from viewing the documentation for the latest stable release
43+
to viewing the documentation for the development version or previously
44+
released versions.
4045

4146
You can also [view](https://cheatsheets.docs.pyansys.com/pydpf-post_cheat_sheet.png) or
4247
[download](https://cheatsheets.docs.pyansys.com/pydpf-post_cheat_sheet.pdf) the
@@ -45,82 +50,8 @@ for using PyDPF-Post.
4550

4651
On the [PyDPF-Post Issues](https://github.com/ansys/pydpf-post/issues) page,
4752
you can create issues to report bugs and request new features. On the
48-
[PyDPF-Post Discussions](https://github.com/ansys/pydpf-post/discussions) page or the [Discussions](https://discuss.ansys.com/)
49-
page on the Ansys Developer portal, you can post questions, share ideas, and get community feedback.
53+
[PyDPF-Post Discussions](https://github.com/ansys/pydpf-post/discussions) page or
54+
the [Discussions](https://discuss.ansys.com/) page on the Ansys Developer portal,
55+
you can post questions, share ideas, and get community feedback.
5056

5157
To reach the project support team, email [[email protected]](mailto:[email protected]).
52-
53-
## Installation
54-
55-
To install this package, run this command:
56-
57-
```
58-
pip install ansys-dpf-post
59-
```
60-
61-
You can also clone and install this package with these commands:
62-
63-
```
64-
git clone https://github.com/ansys/pydpf-post
65-
cd pydpf-post
66-
pip install . --user
67-
```
68-
69-
## Brief demo
70-
71-
Provided you have Ansys 2023 R1 or later installed, a DPF server automatically starts
72-
once you start using PyDPF-Post.
73-
74-
To load a simulation for a MAPDL result file to extract and
75-
postprocess results, use this code:
76-
77-
```pycon
78-
>>> from ansys.dpf import post
79-
>>> from ansys.dpf.post import examples
80-
>>> simulation = post.load_simulation(examples.download_crankshaft())
81-
>>> displacement = simulation.displacement()
82-
>>> print(displacement)
83-
```
84-
```pycon
85-
results U (m)
86-
set_ids 3
87-
node_ids components
88-
4872 X -3.4137e-05
89-
Y 1.5417e-03
90-
Z -2.6398e-06
91-
9005 X -5.5625e-05
92-
Y 1.4448e-03
93-
Z 5.3134e-06
94-
... ... ...
95-
```
96-
```pycon
97-
>>> displacement.plot()
98-
```
99-
![Example Displacement plot Crankshaft](https://github.com/ansys/pydpf-post/raw/master/docs/source/images/crankshaft_disp.png)
100-
```pycon
101-
>>> stress_eqv = simulation.stress_eqv_von_mises_nodal()
102-
>>> stress_eqv.plot()
103-
```
104-
![Example Stress plot Crankshaft](https://github.com/ansys/pydpf-post/raw/master/docs/source/images/crankshaft_stress.png)
105-
106-
To run PyDPF-Post with Ansys 2021 R1 through 2022 R2, use this code to
107-
start the legacy PyDPF-Post tools:
108-
109-
```pycon
110-
>>> from ansys.dpf import post
111-
>>> from ansys.dpf.post import examples
112-
>>> solution = post.load_solution(examples.download_crankshaft())
113-
>>> stress = solution.stress()
114-
>>> stress.eqv.plot_contour(show_edges=False)
115-
```
116-
![Example Stress plot Crankshaft](https://github.com/ansys/pydpf-post/raw/master/docs/source/images/crankshaft_stress.png)
117-
118-
## License and acknowledgements
119-
120-
PyDPF-Post is licensed under the MIT license. For more information, see the
121-
[LICENSE](https://github.com/ansys/pydpf-post/raw/master/LICENSE) file.
122-
123-
PyDPF-Post makes no commercial claim over Ansys whatsoever. This library
124-
extends the functionality of Ansys DPF by adding a Python interface
125-
to DPF without changing the core behavior or license of the original
126-
software.

‎doc/source/conf.py

+1
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@
7979
"sphinx.ext.todo",
8080
"sphinx_copybutton",
8181
"sphinx_gallery.gen_gallery",
82+
"sphinx_design",
8283
]
8384

8485
typehints_defaults = "comma"

‎doc/source/contributing.rst

+12-19
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,23 @@ Contribute
66

77
Overall guidance on contributing to a PyAnsys repository appears in
88
`Contribute <https://dev.docs.pyansys.com/overview/contributing.html>`_
9-
in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar
10-
with this guide, paying particular attention to `Guidelines and Best Practices
11-
<https://dev.docs.pyansys.com/guidelines/index.html>`_, before attempting
12-
to contribute to PyDPF-Post.
9+
in the *PyAnsys developer's guide*. Ensure that you are thoroughly familiar
10+
with this guide before attempting to contribute to PyDPF-Post.
1311

1412
The following contribution information is specific to PyDPF-Post.
1513

16-
Clone the repository
17-
--------------------
14+
Install in development mode
15+
---------------------------
1816

19-
To clone and install the latest version of PyDPF-Core in
20-
development mode, run:
17+
If you want to edit and potentially contribute to PyDPF-Post,
18+
clone the repository and install it using ``pip`` with the ``-e``
19+
development flag:
2120

22-
.. include:: pydpf-post_clone_install.rst
21+
.. code::
22+
23+
git clone https://github.com/ansys/pydpf-post
24+
cd pydpf-post
25+
pip install -e .
2326
2427
2528
Post issues
@@ -29,13 +32,3 @@ Use the `PyDPF-Post Issues <https://github.com/ansys/pydpf-post/issues>`_
2932
page to submit questions, report bugs, and request new features.
3033

3134
To reach the project support team, email `[email protected] <[email protected]>`_.
32-
33-
View documentation
34-
------------------
35-
Documentation for the latest stable release of PyDPF-Post is hosted at
36-
`PyDPF Documentation <https://post.docs.pyansys.com/>`_.
37-
38-
In the upper right corner of the documentation's title bar, there is an option
39-
for switching from viewing the documentation for the latest stable release
40-
to viewing the documentation for the development version or previously
41-
released versions.

‎doc/source/getting_started/compatibility.rst

+24-19
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,32 @@
11
.. _compatibility:
22

3-
=============
4-
Compatibility
5-
=============
3+
=============================
4+
PyDPF library compatibilities
5+
=============================
66

7-
PyDPF-Post supports Windows 10 and CentOS 7 and later. For
8-
more information, see `Ansys Platform Support <https://www.ansys.com/solutions/solutions-by-role/it-professionals/platform-support>`_.
7+
Potential crashes can occur when using PyDPF-Post 0.2.2 or earlier with PyDPF-Core 0.5.2
8+
or later. For a given DPF server version, the following table indicates version compatibilities
9+
for these two libraries.
910

10-
Other platforms may be supported by using PyDPF-Post in a
11-
containerized ecosystem, such as `Docker <https://www.docker.com/>`_ or
12-
`Kubernetes <https://kubernetes.io/>`_.
13-
14-
Due to potential crashes when using PyDPF-Post 0.2.2 or earlier with PyDPF-Core 0.5.2
15-
or later, you should refer to the following table for compatibility between these two
16-
libraries.
17-
18-
.. list-table:: PyDPF compatibility
11+
.. list-table:: **PyDPF library compatibilities**
1912
:widths: 20 20 20
2013
:header-rows: 1
2114

2215
* - DPF server version
23-
- ansys.dpf.core python module version
24-
- ansys.dpf.post python module version
16+
- PyDPF-Core version
17+
- PyDPF-Post version
18+
* - 10.0 (DPF Server 2025.2.pre0)
19+
- 0.13.4 or later
20+
- 0.9.0 or later
21+
* - 9.1 (Ansys 2025 R1)
22+
- 0.13.4 or later
23+
- 0.9.0 or later
24+
* - 9.0 (DPF Server 2025.1.pre0)
25+
- 0.13.0 or later
26+
- 0.9.0 or later
27+
* - 8.2 (Ansys 2024 R2)
28+
- 0.12.1 or later
29+
- 0.8.0 or later
2530
* - 8.1 (DPF Server 2024.2.pre1)
2631
- 0.12.0 or later
2732
- 0.8.0 or later
@@ -53,10 +58,10 @@ libraries.
5358
- 0.4.0 to 0.9.0
5459
- 0.1.0 to 0.5.0
5560
* - 2.0 (Ansys 2021 R2)
56-
- 0.3.0 to 0.9.0**
61+
- 0.3.0 to 0.9.0*
5762
- 0.1.0 to 0.5.0
5863
* - 1.0 (Ansys 2021 R1)
59-
- 0.2.*
64+
- 0.2.0 to 0.2.x
6065
- 0.1.0
6166

62-
(** Compatibility of DPF 2.0 with ansys-dpf-core 0.5.0 to 0.9.0 is assumed but not certified.)
67+
*Compatibility of DPF 2.0 with PyDPF-Core 0.5.0 to 0.9.0 is assumed but not certified.

‎doc/source/getting_started/demo.rst

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
==========
2+
Brief demo
3+
==========
4+
5+
This brief demo shows how to load an Ansys Mechanical APDL (MAPDL) result file to extract
6+
and postprocess results. The code to use depends on which Ansys version you have installed.
7+
For comprehensive examples of how to use PyDPF-Post, see :ref:`gallery`.
8+
9+
2023 R1 and later
10+
-----------------
11+
12+
If Ansys 2023 R1 or later is installed, a DPF server automatically starts
13+
once you start using PyDPF-Post. Use this code to load an MAPDL result file
14+
to extract and postprocess results:
15+
16+
.. code:: python
17+
18+
>>> from ansys.dpf import post
19+
>>> from ansys.dpf.post import examples
20+
>>> simulation = post.load_simulation(examples.download_crankshaft())
21+
>>> displacement = simulation.displacement()
22+
>>> print(displacement)
23+
24+
25+
.. rst-class:: sphx-glr-script-out
26+
27+
.. code-block:: none
28+
29+
results U
30+
set_id 3
31+
node comp
32+
4872 X -3.41e-05
33+
Y 1.54e-03
34+
Z -2.64e-06
35+
9005 X -5.56e-05
36+
Y 1.44e-03
37+
Z 5.31e-06
38+
...
39+
40+
.. code:: python
41+
42+
>>> displacement.plot()
43+
44+
45+
.. image:: ./../images/crankshaft_disp.png
46+
:align: center
47+
:width: 300pt
48+
49+
50+
.. code:: python
51+
52+
>>> stress_eqv = simulation.stress_eqv_von_mises_nodal()
53+
>>> stress_eqv.plot()
54+
55+
.. image:: ./../images/crankshaft_stress.png
56+
:align: center
57+
:figwidth: 300pt
58+
59+
60+
2021 R1 through 2022 R2
61+
-----------------------
62+
63+
If an Ansys release of 2021 R1 through 2022 R2 is installed, use this code to
64+
start the legacy PyDPF-Post tools and then load an MAPDL result file
65+
to extract and postprocess results:
66+
67+
.. code:: python
68+
69+
>>> from ansys.dpf import post
70+
>>> from ansys.dpf.post import examples
71+
>>> solution = post.load_solution(examples.download_crankshaft())
72+
>>> stress = solution.stress()
73+
>>> stress.eqv.plot_contour(show_edges=False)
74+
75+
.. image:: ./../images/crankshaft_stress.png
76+
:align: center
77+
:width: 300pt
78+

0 commit comments

Comments
 (0)