chore: (migrated PR #4009) docs: static rom training data generation example #4011

germa89 · 2025-06-16T10:31:41Z

This PR is a mirror pull request created from docs: static rom training data generation example to allow the code to access PyMAPDL CICD secrets.

Check the original PR made by @${originalPR.user.login} for more details.

Closes #4009

docs: static rom training data generation example

Description

Add an example showing how PyMAPDL and PyDPF can be use to export training data to be used to create a Static Reduced Order model in Ansys Twin Builder.

Issue linked

None.

Checklist

Summary by Sourcery

Add a new documentation example demonstrating how to generate static reduced-order model (ROM) training data with PyMAPDL, DPF, and PyTwin for use in Ansys Twin Builder

Documentation:

Introduce a Python script and RST guide for Static ROM data generation example under extended examples
Update examples index and links to include the new Static ROM example
Add intersphinx mapping for the pytwin package in conf.py to enable cross-references to PyTwin documentation

Summary by Sourcery

Add a new documentation example demonstrating how to export static ROM training data using PyMAPDL, DPF, and PyTwin for Ansys Twin Builder and update relevant docs configuration and indexes.

Documentation:

Add a static ROM training data generation example with Python script and RST guide under extended examples
Update examples index and cross-reference links to include the new static ROM example
Add intersphinx mapping for the PyTwin package in Sphinx configuration
Include a changelog entry for the migrated documentation PR

sourcery-ai · 2025-06-16T10:31:46Z

Reviewer's Guide

This PR integrates a new extended-doc example that demonstrates how to generate static ROM training data with PyMAPDL, DPF, and PyTwin by adding a Python export script and its corresponding RST guide, and updating documentation configuration and indices accordingly.

File-Level Changes

Change	Details	Files
Introduce static ROM training data generation example script and guide	Add Python script with utility functions (data compression, settings writer, DPF export functions, MAPDL variation runner) Create RST documentation for the static ROM example under extended examples	`doc/source/examples/extended_examples/static_rom/static_rom_data_generation.py` `doc/source/examples/extended_examples/static_rom/static_rom_data_generation.rst`
Update Sphinx configuration for PyTwin cross-references	Add intersphinx mapping for the pytwin package	`doc/source/conf.py`
Register the new example in documentation indices and link references	Include the static ROM example in the extended examples index Update links registry to reference the new example	`doc/source/examples/extended_examples/index.rst` `doc/source/links.rst`
Add changelog entry for the migrated PR	Introduce a miscellaneous changelog file for this chore	`doc/changelog.d/4011.miscellaneous.md`

Assessment against linked issues

Issue	Objective	Addressed
#4009	Add an example showing how PyMAPDL and PyDPF can be used to export training data for creating a Static Reduced Order Model in Ansys Twin Builder.	✅
#4009	Introduce a Python script and RST guide for the Static ROM data generation example under extended examples.	✅
#4009	Update examples index and links to include the new Static ROM example and add intersphinx mapping for the pytwin package in conf.py to enable cross-references to PyTwin documentation.	✅

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

ansys-reviewer-bot · 2025-06-16T10:31:47Z

Thanks for opening a Pull Request. If you want to perform a review write a comment saying:

@ansys-reviewer-bot review

sourcery-ai

Hey @germa89 - I've reviewed your changes - here's some feedback:

In get_scoping(), you call op.outputs.mesh_scoping() twice—capture the first output in a variable and reuse it to avoid rerunning the operator and ensure consistency.
The conditional block in export_static_ROM_variation for handling 'displacement' vs 'stress' is hardcoded; consider refactoring this into a mapping or helper function so it’s easier to add new result types in the future.
Wrap the launch_mapdl() and download_example_data() calls in try/except to provide clearer error messages and clean up resources if the MAPDL session fails to start or the download fails.

Prompt for AI Agents

Please address the comments from this code review:
## Overall Comments
- In get_scoping(), you call op.outputs.mesh_scoping() twice—capture the first output in a variable and reuse it to avoid rerunning the operator and ensure consistency.
- The conditional block in export_static_ROM_variation for handling 'displacement' vs 'stress' is hardcoded; consider refactoring this into a mapping or helper function so it’s easier to add new result types in the future.
- Wrap the launch_mapdl() and download_example_data() calls in try/except to provide clearer error messages and clean up resources if the MAPDL session fails to start or the download fails.

## Individual Comments

### Comment 1
<location> `doc/source/examples/extended_examples/static_rom/static_rom_data_generation.py:117` </location>
<code_context>
+        take_mid_nodes=True,
+    )
+    # Get output data
+    connected_nodes_scoping = op.outputs.mesh_scoping()
+    # Compress the list to only keep unique IDs
+    connected_nodes_scoping.ids = sorted(list(set(op.outputs.mesh_scoping().ids)))
+    return connected_nodes_scoping
+
</code_context>

<issue_to_address>
Reuse the mesh_scoping output instead of calling it twice

Reuse the previously assigned `connected_nodes_scoping.ids` instead of calling `op.outputs.mesh_scoping()` again to avoid redundancy and improve code clarity.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
    # Get output data
    connected_nodes_scoping = op.outputs.mesh_scoping()
    # Compress the list to only keep unique IDs
    connected_nodes_scoping.ids = sorted(list(set(op.outputs.mesh_scoping().ids)))
    return connected_nodes_scoping
=======
    # Get output data
    connected_nodes_scoping = op.outputs.mesh_scoping()
    # Compress the list to only keep unique IDs
    connected_nodes_scoping.ids = sorted(list(set(connected_nodes_scoping.ids)))
    return connected_nodes_scoping
>>>>>>> REPLACE

</suggested_fix>

### Comment 2
<location> `doc/source/examples/extended_examples/static_rom/static_rom_data_generation.rst:205` </location>
<code_context>
+
+Modifying result scoping
+------------------------
+The script exports results on all nodes that are connected to elements. This does not account for
+nodes that are connected to elements, but do not have results associated with them. For example
+MPC184 pilot nodes would not usually have a stress result. The script also does not allow scoping 
+component.
</code_context>

<issue_to_address>
Awkward phrasing: 'does not allow scoping component' should be 'does not allow component scoping'.

Rephrase as 'does not allow component scoping' for clarity.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
MPC184 pilot nodes would not usually have a stress result. The script also does not allow scoping 
component.
=======
MPC184 pilot nodes would not usually have a stress result. The script also does not allow component scoping.
>>>>>>> REPLACE

</suggested_fix>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

doc/source/examples/extended_examples/static_rom/static_rom_data_generation.py

doc/source/examples/extended_examples/static_rom/static_rom_data_generation.rst

sourcery-ai

Hey @germa89 - I've reviewed your changes - here's some feedback:

In conf.py, rename the intersphinx key from “pytwin” to something like “ansys-pytwin” to keep it consistent with your other ansys-* mapping names.
The static_rom_data_generation.py script is quite large—consider extracting common utility functions into a separate module or splitting into smaller sections to make the example easier to navigate.
Add a brief prerequisites section in the RST example (e.g. required package installs and versions) so users know they must have PyTwin and DPF set up before running the script.

Prompt for AI Agents

Please address the comments from this code review:
## Overall Comments
- In conf.py, rename the intersphinx key from “pytwin” to something like “ansys-pytwin” to keep it consistent with your other `ansys-*` mapping names.
- The `static_rom_data_generation.py` script is quite large—consider extracting common utility functions into a separate module or splitting into smaller sections to make the example easier to navigate.
- Add a brief prerequisites section in the RST example (e.g. required package installs and versions) so users know they must have PyTwin and DPF set up before running the script.

## Individual Comments

### Comment 1
<location> `doc/source/examples/extended_examples/static_rom/static_rom_data_generation.py:295` </location>
<code_context>
+
+def run():
+    # Define a folder for output.
+    rom_folder = Path(tempfile.gettempdir()).joinpath("ansys_pymadl_Static_ROM")
+    mapdl_results = run_mapdl_variations()
+    export_static_ROM_data(mapdl_results, rom_folder)
</code_context>

<issue_to_address>
Typo in output folder name

Please rename the folder to `ansys_pymapdl_Static_ROM` for consistency.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
def run():
    # Define a folder for output.
    rom_folder = Path(tempfile.gettempdir()).joinpath("ansys_pymadl_Static_ROM")
    mapdl_results = run_mapdl_variations()
    export_static_ROM_data(mapdl_results, rom_folder)
    print(f"ROM data exported to: {rom_folder}")
=======
def run():
    # Define a folder for output.
    rom_folder = Path(tempfile.gettempdir()).joinpath("ansys_pymapdl_Static_ROM")
    mapdl_results = run_mapdl_variations()
    export_static_ROM_data(mapdl_results, rom_folder)
    print(f"ROM data exported to: {rom_folder}")
>>>>>>> REPLACE

</suggested_fix>

### Comment 2
<location> `doc/source/examples/extended_examples/static_rom/static_rom_data_generation.py:228` </location>
<code_context>
+    """
+    for idx, (rst_path, parameters) in enumerate(mapdl_results):
+        # Load the results to DPF and create scoping.
+        model = dpf.Model(rst_path)
+        scoping = get_scoping(model)
+
</code_context>

<issue_to_address>
Release or close DPF model resources

To prevent increased memory usage, ensure each DPF model is released or closed after use, either via a context manager or by explicitly calling the appropriate method.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
    for idx, (rst_path, parameters) in enumerate(mapdl_results):
        # Load the results to DPF and create scoping.
        model = dpf.Model(rst_path)
        scoping = get_scoping(model)
=======
    for idx, (rst_path, parameters) in enumerate(mapdl_results):
        # Load the results to DPF and create scoping.
        with dpf.Model(rst_path) as model:
            scoping = get_scoping(model)
>>>>>>> REPLACE

</suggested_fix>

### Comment 3
<location> `doc/source/examples/extended_examples/static_rom/static_rom_data_generation.rst:205` </location>
<code_context>
+
+Modifying result scoping
+------------------------
+The script exports results on all nodes that are connected to elements. This does not account for
+nodes that are connected to elements, but do not have results associated with them. For example
+MPC184 pilot nodes would not usually have a stress result. The script also does not allow scoping 
+component.
</code_context>

<issue_to_address>
Grammar: 'does not allow scoping component' should be 'does not allow component scoping'.

Rephrase as 'does not allow component scoping' for improved clarity.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
MPC184 pilot nodes would not usually have a stress result. The script also does not allow scoping 
component.
=======
MPC184 pilot nodes would not usually have a stress result. The script also does not allow component scoping.
>>>>>>> REPLACE

</suggested_fix>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

doc/source/examples/extended_examples/static_rom/static_rom_data_generation.py

doc/source/examples/extended_examples/static_rom/static_rom_data_generation.rst

PipKat

Minor edits based mostly on writing to the Google developer documentation style guide.

Co-authored-by: Kathy Pippert <[email protected]>

EDCarman · 2025-06-17T08:02:42Z

Thanks @PipKat for the review. @germa89 is there anything else the needs to be done before merging? Do you do that or do I?

germa89 · 2025-06-17T09:59:51Z

@PipKat thank you a lot for your prompt and comprehensive review!! It is much appreciated as always! :)

@EDCarman. Nothing else to do. We are good to go!! Thank you again for your PR! :)

EDCarman and others added 15 commits June 5, 2025 14:34

build: Add PyTwin to doc dependencies

d310f06

docs: Initial static ROM example

be4e277

Merge branch 'ansys:main' into docs/rom_data_generation_example

33fd387

docs: refactor example

a256d7b

docs: remove local .db file, refactor script

8ed05f3

docs: separate MAPDL DoE and export runs in example

5b7fa76

docs: add Pytwin to links and intersphinx mapping

91897f7

docs: add Static ROM example description

708e520

docs: undo commenting out filename_pattern

f6a149b

Merge branch 'ansys:main' into docs/rom_data_generation_example

75570b9

build: Undo addition of PyTwin to doc dependencies

e2b75a4

docs: fixed code-block vailing Vale.Spelling

28d3d99

docs: add corrections suggested by sourcery-ai

253e3f3

docs: sort scoping IDs

133efa6

Merge branch 'main' into docs/rom_data_generation_example

684bcc4

germa89 requested a review from a team as a code owner June 16, 2025 10:31

germa89 requested review from clatapie and pyansys-ci-bot June 16, 2025 10:31

germa89 assigned EDCarman Jun 16, 2025

github-actions bot added documentation Documentation related (improving, adding, etc) enhancement Improve any current implemented feature labels Jun 16, 2025

chore: adding changelog file 4011.miscellaneous.md [dependabot-skip]

c7fd971

germa89 mentioned this pull request Jun 16, 2025

docs: static rom training data generation example #4009

Closed

10 tasks

sourcery-ai bot reviewed Jun 16, 2025

View reviewed changes

doc/source/examples/extended_examples/static_rom/static_rom_data_generation.py Show resolved Hide resolved

doc/source/examples/extended_examples/static_rom/static_rom_data_generation.rst Outdated Show resolved Hide resolved

sourcery-ai bot reviewed Jun 16, 2025

View reviewed changes

germa89 changed the title ~~chore: [migrated PR #4009] docs: static rom training data generation example~~ migrated (PR #4009): docs: static rom training data generation example Jun 16, 2025

pyansys-ci-bot and others added 2 commits June 16, 2025 10:47

chore: adding changelog file 4011.miscellaneous.md [dependabot-skip]

e7afbd0

docs: address sourcery-ai corrections

84c6432