docs: adding reporting example

[germa89]

Description

• Introduced a new example script beam_with_report.py that performs a structural analysis of a simply supported I-beam.
• Implemented parameterized modeling for beam geometry, material properties, and loading conditions.
• Added functionality for generating detailed reports in both Markdown and Word formats, including plots and tables.
• Updated documentation to include a reference to the new example in the extended examples index.

Issue linked

Close #3862

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 extended example script for I-beam structural analysis with automated report generation, update documentation to include it, fix minor formatting issues in existing examples, and extend recognized MAPDL commands.

New Features:

• Introduce a new beam_with_report example script demonstrating parameterized I-beam modeling and automated report generation in Markdown and Word formats

Bug Fixes:

• Correct formatting in existing examples: exponent spacing in bracket_static, backslash escaping in lathe_cutter, and raw string usage for y-axis labels in transient_thermal

Enhancements:

• Enable parameterized geometry, material, and loading setup in the new example
• Add plot generation and table summaries for analysis results in reports
• Include 'SECP' in the list of recognized MAPDL commands

Documentation:

• Update extended examples index to reference the new beam analysis with reporting example

[sourcery-ai]

Reviewer's Guide

This PR introduces a comprehensive parameterized I-beam analysis example with automated Markdown and Word report generation, updates the extended examples index and documentation to reference it, extends the core API to recognize a new section type, and applies minor formatting fixes in existing examples.

Class diagram for the new I-beam analysis and reporting example

classDiagram
    class create_ibeam_analysis_and_report {
        +create_ibeam_analysis_and_report()
    }
    class generate_analysis_plots {
        +generate_analysis_plots(mapdl, output_dir)
    }
    class generate_markdown_report {
        +generate_markdown_report(data, output_dir)
    }
    class generate_word_report {
        +generate_word_report(data, output_dir)
    }
    create_ibeam_analysis_and_report --> generate_analysis_plots
    create_ibeam_analysis_and_report --> generate_markdown_report
    create_ibeam_analysis_and_report --> generate_word_report

Loading

Class diagram for parameterized data structures in the I-beam example

classDiagram
    class BeamParams {
        +length: float
        +flange_width: float
        +web_height: float
        +flange_thickness: float
        +web_thickness: float
        +num_elements: int
    }
    class MaterialProps {
        +elastic_modulus: float
        +poisson_ratio: float
        +density: float
        +yield_strength: float
    }
    class LoadParams {
        +distributed_load: float
        +safety_factor: float
    }
    class AnalysisData {
        +beam_params: BeamParams
        +material_props: MaterialProps
        +load_params: LoadParams
        +results: dict
        +section_props: dict
        +plot_files: dict
    }

Loading

Class diagram for the extension of MAPDL core API section types

classDiagram
    class mapdl_core {
        +SECP
    }

Loading

File-Level Changes

Change	Details	Files
Introduce parameterized I-beam analysis example with report generation	Add beam_with_report.py script that encapsulates model setup, solution, post-processing, and report functions Implement generation of Markdown and Word reports with tables, plots, and metadata Separate plotting routines and report writers into helper functions Wrap workflow in a main block for standalone execution	examples/00-mapdl-examples/beam_with_report.py
Update documentation to include new extended example	Add reference to I-beam reporting example in extended examples index Create RST file for beam analysis report documentation	doc/source/examples/extended_examples/index.rst doc/source/examples/extended_examples/beam_analysis_with_reporting/beam_analysis_report.rst
Extend core API to support new section type	Add 'SECP' to the list of recognized section type keywords	src/ansys/mapdl/core/mapdl_core.py
Apply minor formatting and literal fixes in existing examples	Adjust exponent spacing in bracket_static.py Escape backslash in HTML export path in lathe_cutter.py Use raw string for degree symbol in transient_thermal.py	examples/00-mapdl-examples/bracket_static.py examples/00-mapdl-examples/lathe_cutter.py examples/00-mapdl-examples/transient_thermal.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#3862	Provide an example that demonstrates reporting combining Excel, Word, PDF, and Latex outputs.	❌	The PR adds an example script that generates reports in Markdown and Word formats, but there is no evidence of Excel, PDF, or Latex report generation in the code or documentation. Only Markdown and Word outputs are implemented.

Possibly linked issues

• Reporting example #3862: The PR adds a new example for generating reports from MAPDL results, addressing the issue's feedback on improving Pythonic I/O for output and extracting info.
• Reporting example #3862: The PR includes a fix for a permission error in the 'Lathe Cutter' example, which was reported as a bug in the issue.

---

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.

[sourcery-ai]

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

• The new example script is quite long; consider splitting the modeling workflow and report‐generation logic into smaller, reusable functions or modules to improve readability and maintainability.
• Rather than using raw print statements throughout, leverage Python’s logging module so users can adjust verbosity and better integrate with other applications.
• It would be helpful to parameterize hard-coded values (like element count, load magnitude, and output directory) via command-line arguments (e.g., argparse) for greater flexibility in different use cases.

Prompt for AI Agents

Please address the comments from this code review:
## Overall Comments
- The new example script is quite long; consider splitting the modeling workflow and report‐generation logic into smaller, reusable functions or modules to improve readability and maintainability.
- Rather than using raw print statements throughout, leverage Python’s logging module so users can adjust verbosity and better integrate with other applications.
- It would be helpful to parameterize hard-coded values (like element count, load magnitude, and output directory) via command-line arguments (e.g., argparse) for greater flexibility in different use cases.

## Individual Comments

### Comment 1
<location> `examples/00-mapdl-examples/beam_with_report.py:266` </location>
<code_context>
+    # Get nodal displacements
+    # Extract displacement results - Y direction only
+    displacements = mapdl.post_processing.nodal_displacement("Y")
+    max_displacement = np.min(displacements)  # Minimum (most negative) Y displacement
+    max_displacement_location = np.argmin(displacements) + 1  # Node number
+
</code_context>

<issue_to_address>
Using np.min for maximum displacement may be misleading if upward displacements are possible.

Use np.abs(displacements).max() to find the largest displacement magnitude, regardless of direction.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
    # Get nodal displacements
    # Extract displacement results - Y direction only
    displacements = mapdl.post_processing.nodal_displacement("Y")
    max_displacement = np.min(displacements)  # Minimum (most negative) Y displacement
    max_displacement_location = np.argmin(displacements) + 1  # Node number
=======
    # Get nodal displacements
    # Extract displacement results - Y direction only
    displacements = mapdl.post_processing.nodal_displacement("Y")
    max_displacement = np.abs(displacements).max()  # Maximum displacement magnitude (regardless of direction)
    max_displacement_location = np.argmax(np.abs(displacements)) + 1  # Node number with max magnitude
>>>>>>> REPLACE

</suggested_fix>

### Comment 2
<location> `examples/00-mapdl-examples/beam_with_report.py:298` </location>
<code_context>
+    bending_strain_bottom = mapdl.get_array("ELEM", "", "ETAB", "EPELByB").max()
+    max_strain_fem = max(bending_strain_top, bending_strain_bottom)
+
+    safety_factor = material_props["yield_strength"] / max_stress_fem
+
+    print("\n" + "=" * 50)
</code_context>

<issue_to_address>
Division by zero risk if max_stress_fem is zero.

Add a check to prevent ZeroDivisionError when max_stress_fem is zero.
</issue_to_address>

### Comment 3
<location> `doc/source/examples/extended_examples/beam_analysis_with_reporting/beam_analysis_report.rst:30` </location>
<code_context>
+This example shows how PyMAPDL can be used to create a complete analysis workflow
+that includes automated report generation.
+
+The analysis focuses on a simply supported I-beam subjected to an uniformly distributed
+load, a fundamental structural engineering problem. The results are verified against
+analytical solutions and presented in professional report formats.
</code_context>

<issue_to_address>
Typo: 'an uniformly' should be 'a uniformly'.

It should be 'a uniformly distributed load' to use the correct article.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
The analysis focuses on a simply supported I-beam subjected to an uniformly distributed
load, a fundamental structural engineering problem. The results are verified against
analytical solutions and presented in professional report formats.
=======
The analysis focuses on a simply supported I-beam subjected to a uniformly distributed
load, a fundamental structural engineering problem. The results are verified against
analytical solutions and presented in professional report formats.
>>>>>>> REPLACE

</suggested_fix>

### Comment 4
<location> `doc/source/examples/extended_examples/beam_analysis_with_reporting/beam_analysis_report.rst:42` </location>
<code_context>
+**Geometry:**
+
+- Length: 5.0 meters
+- I-section with typical structural steel proportions
+- Clamped at both ends
+
+**Loading:**
</code_context>

<issue_to_address>
Inconsistency: 'Clamped at both ends' contradicts 'simply supported' elsewhere.

This section should use 'Supported at both ends' or 'Simply supported at both ends' to match the terminology used elsewhere.
</issue_to_address>

---

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.}

[Copilot]

Pull Request Overview

This PR introduces a comprehensive example for I-beam structural analysis with automated report generation in PyMAPDL. The example demonstrates parameterized modeling, finite element analysis, and professional report generation in both Markdown and Word formats.

Key changes include:

• Added a new example script showing I-beam analysis with automated reporting capabilities
• Implemented parameterized beam modeling with material properties and loading conditions
• Fixed a string formatting issue in an existing thermal analysis example
• Updated documentation to include the new example in the extended examples index

Reviewed Changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/ansys/mapdl/core/mapdl_core.py	Adds "SECP" command to the list of commands that require plotting
examples/00-mapdl-examples/transient_thermal.py	Fixes raw string formatting for temperature ylabel to prevent escape sequence warning
examples/00-mapdl-examples/lathe_cutter.py	Corrects backslash escaping in file path string
examples/00-mapdl-examples/beam_with_report.py	Introduces comprehensive new example for I-beam analysis with automated report generation
doc/source/examples/extended_examples/index.rst	Adds reference to the new beam analysis example in documentation index
doc/source/examples/extended_examples/beam_analysis_with_reporting/beam_analysis_report.rst	Provides detailed documentation for the new beam analysis example

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.29%. Comparing base (db31b73) to head (8c49a5f).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4127      +/-   ##
==========================================
- Coverage   91.35%   91.29%   -0.07%     
==========================================
  Files         189      189              
  Lines       15650    15650              
==========================================
- Hits        14297    14287      -10     
- Misses       1353     1363      +10     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[germa89]

I think this example is almost ready.

Pinging @mikerife for APDL feedback.

Pinging @PipKat for documentation review

Pinging @clatapie for general feedback.

[PipKat]

Minor suggestions!

[germa89]

@pyansys-ci-bot LGTM

[pyansys-ci-bot]

✅ Approving this PR because germa89 said so in here 😬