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

[germa89]

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

• I have visited and read Develop PyMAPDL.
• I have tested my changes locally
• I have added necessary documentation or updated existing documentation.
• I have followed the PyMAPDL coding style guidelines.
• I have added appropriate unit tests that also ensure the minimal coverage criteria.
• I have reviewed my changes before submitting this pull request.
• I have linked the issue or issues that are solved to the PR if any.
• I have assigned this PR to myself.
• I have marked this PR as draft if it is not ready to be reviewed yet.
• I have made sure that the title of my PR follows Commit naming conventions (e.g. feat: adding new MAPDL command)

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]

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	Explanation
#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]

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 ✨

• X
• Mastodon
• LinkedIn
• Facebook

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

[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 ✨

• X
• Mastodon
• LinkedIn
• Facebook

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

[PipKat]

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

[EDCarman]

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]

@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! :)