feat: `session` submodule #3895

clatapie · 2025-05-06T11:04:57Z

Description

This PR follows the PyConverter-XML2Py integration plan to automate the PyMAPDL_commands documentation.
The changes have been generated using pyconverter-xml2py and more specifically mapdl-cmd-conv.

This PR focus on the session submodule.

You can check the mapdl-cmd-conv documentation to have a look at the output of each submodules.

Pinging @ansys/pymapdl-developers for visibility. Feel free to provide any feedback on the way the docstrings and the source code generation are handled.

Issue linked

This PR is meant to be merged within the feat/main_commands branch. The latter will gather all the submodule changes, one by one, prior to be merged to the main branch.

Checklist

Summary by Sourcery

Implement the post26 submodule for PyMAPDL, following the PyConverter-XML2Py integration plan to automate documentation generation

New Features:

Add post26 submodule with comprehensive command implementations
Implement classes for different aspects of POST26 postprocessing such as SetUp, Controls, Display, Listing, Operations, Special Purpose, and Status

Chores:

Reorganize project structure to accommodate the new submodule
Remove old post26_ directory

Summary by Sourcery

Implement the session submodule for PyMAPDL, following the PyConverter-XML2Py integration plan to automate documentation generation

New Features:

Add comprehensive documentation and implementation for session-related MAPDL commands

Enhancements:

Refactor and update session-related command implementations
Improve type hinting and docstring documentation

Documentation:

Add documentation for session submodule commands
Create index and documentation files for session commands

ansys-reviewer-bot · 2025-05-06T11:05:01Z

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

@ansys-reviewer-bot review

sourcery-ai · 2025-05-06T11:05:02Z

Reviewer's Guide

This pull request implements the session submodule commands by leveraging the pyconverter-xml2py tool for automated code generation. The core of the changes involves replacing manually written Python methods in run_controls.py, files.py, processor_entry.py, and list_controls.py with their auto-generated counterparts. This process standardizes method signatures to match APDL commands, incorporates comprehensive docstrings directly sourced from APDL documentation (complete with hyperlinks), and ensures consistent APDL command string construction. Accompanying these code changes, the documentation structure for the session submodule has been updated, including the removal of old RST files and the addition of a new index file and a changelog entry.

Updated Class Diagram for RunControls

classDiagram
    class RunControls {
        +keyw(**kwargs)
        +slashexit(slab: str, fname: str, ext: str, **kwargs)
        +pause(**kwargs)
        +uis(label: str, value: int | str, **kwargs)
        +ui(func: str, type_: str, format_: str, screen: str, color: str, krev: str, orient: str, compress: str, quality: str, **kwargs)
        +unpause(**kwargs)
        +mstart(label: str, key: str, **kwargs)
        +memm(lab: str, kywrd: str, **kwargs)
        +menu(key: str, **kwargs)
        +nerr(nmerr: str, nmabt: str, ifkey: str, num: int | str, **kwargs)
        +output(fname: str, ext: str, loc: str, **kwargs)
        +input(fname: str, ext: str, dir_: str, line: str, log: int | str, **kwargs)
        +cwd(dirpath: str, **kwargs)
        +config(lab: str, val: str, **kwargs)
        +sys(string: str, **kwargs)
        +syp(string: str, arg1: str, arg2: str, arg3: str, arg4: str, arg5: str, arg6: str, arg7: str, arg8: str, **kwargs)
        +slashstatus(lab: str, **kwargs)
        +filname(fname: str, key: str, **kwargs)
    }
    note for RunControls "Methods updated with auto-generated code from pyconverter-xml2py. Docstrings and signatures standardized."

Updated Class Diagram for ProcessorEntry

classDiagram
    class ProcessorEntry {
        +post26(**kwargs)
        +post1(**kwargs)
        +prep7(**kwargs)
        +quit(**kwargs)
        +slashsolu(**kwargs)
        +finish(**kwargs)
    }
    note for ProcessorEntry "Methods updated with auto-generated code. Methods aux2, aux3, aux12, aux15 are no longer part of this class."

Updated Class Diagram for ListControls

classDiagram
    class ListControls {
        +golist(**kwargs)
        +gopr(**kwargs)
        +slashgo(**kwargs)
        +nopr(**kwargs)
        +nolist(**kwargs)
        +com(comment: str, **kwargs)
    }
    note for ListControls "Methods updated with auto-generated code from pyconverter-xml2py. Method slashgo added. Docstrings and signatures standardized."

File-Level Changes

Change	Details	Files
Replaced manual implementations of APDL commands in the `session` submodule with auto-generated code from `pyconverter-xml2py`.	Updated Python method signatures and parameters to match APDL command syntax. Embedded extensive docstrings generated from official APDL documentation, including direct links. Standardized internal APDL command string assembly and removed previous module-level docstrings.	`src/ansys/mapdl/core/_commands/session/run_controls.py` `src/ansys/mapdl/core/_commands/session/files.py` `src/ansys/mapdl/core/_commands/session/processor_entry.py` `src/ansys/mapdl/core/_commands/session/list_controls.py`
Updated the documentation build process and file structure for the `session` submodule to reflect auto-generated content.	Deleted obsolete RST files previously used for `session` command documentation. Added a new `index.rst` for the `session` submodule documentation. Included a changelog entry for the new feature.	`doc/source/mapdl_commands/session/files.rst` `doc/source/mapdl_commands/session/list_controls.rst` `doc/source/mapdl_commands/session/processor_entry.rst` `doc/source/mapdl_commands/session/run_controls.rst` `doc/changelog.d/3894.documentation.md` `doc/source/mapdl_commands/session/index.rst`

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.

germa89

LGTM. Minor changes.

germa89 · 2025-05-06T11:21:47Z

doc/changelog.d/3894.documentation.md

why are we having two changelog fragments? It happened the same with #3892 ...

germa89 · 2025-05-06T11:32:43Z

src/ansys/mapdl/core/_commands/session/files.py


-    def fclean(self, **kwargs):
-        """Deletes all local files in all processors in a distributed parallel processing run.
+         **Solution Control Options**


extra spaces in the sections

Suggested change

**Solution Control Options**

**Solution Control Options**

germa89 · 2025-05-06T11:33:24Z

src/ansys/mapdl/core/_commands/session/files.py

+        Pressure loads from ``SURF154``elements are converted to equivalent nodal loads for ASAS. For AQWA-
+        WAVE, the ``SURF154``pressures are used to identify the wetted surface of the underlying elements.


Missing space

Suggested change

Pressure loads from ``SURF154``elements are converted to equivalent nodal loads for ASAS. For AQWA-

WAVE, the ``SURF154``pressures are used to identify the wetted surface of the underlying elements.

Pressure loads from ``SURF154`` elements are converted to equivalent nodal loads for ASAS. For AQWA-

WAVE, the ``SURF154`` pressures are used to identify the wetted surface of the underlying elements.

src/ansys/mapdl/core/_commands/session/files.py

germa89 · 2025-05-06T11:40:56Z

src/ansys/mapdl/core/_commands/session/list_controls.py

+        Notes
+        -----
+
+        .. _s-NOPR_notes:
+
+        Suppresses printout of interpreted input data, including information labeled as "Notes." When this
+        printout is not suppressed, the data input to the analysis is echoed to the output file in an
+        expanded format. Printout is suppressed until a :ref:`gopr` or :ref:`slashgo` command is read.
+
+        Use of :ref:`nopr` is not recommended when the graphical user interface (GUI) is active. The GUI
+        sometimes issues "hidden" :ref:`nopr` and :ref:`gopr` command sequences, which will countermand
+        user-issued :ref:`nopr` commands, thus making the use of :ref:`nopr` in the GUI environment
+        unpredictable.
+
+        This command is valid in any processor.
+        """


Can we add here also a warning mentioning that PyMAPDL requirest these printouts?

Sure, I can add a warning (or a note depending of what you prefer) at the top of this function description. Could you specify what you expect in it please?

germa89 · 2025-05-06T11:50:39Z

src/ansys/mapdl/core/_commands/session/run_controls.py

+
+            .. _ui_coll_label:
+
+             Label specifying the behavior of the Mechanical APDL main menu after a :ref:`finish` command is issued. User interaction with the main menu is unaffected. Valid only for ``Func`` = COLL:


Suggested change

Label specifying the behavior of the Mechanical APDL main menu after a :ref:`finish` command is issued. User interaction with the main menu is unaffected. Valid only for ``Func`` = COLL:

Label specifying the behavior of the Mechanical APDL main menu after a :ref:`finish` command is issued. User interaction with the main menu is unaffected. Valid only for ``Func`` = COLL:

germa89 · 2025-05-06T11:56:05Z

src/ansys/mapdl/core/_commands/session/run_controls.py


-            CONFIG - List only configuration parameters.
+            * ``:, label`` - Begins reading from the first line beginning with the matching user-defined label :


Extra ,.

Suggested change

* ``:, label`` - Begins reading from the first line beginning with the matching user-defined label :

* ``:label`` - Begins reading from the first line beginning with the matching user-defined label :

Investigating why this extra comma appears here.

germa89 · 2025-05-06T11:57:17Z

src/ansys/mapdl/core/_commands/session/run_controls.py

+        or another file switching directive is read. An end-of-file occurs after the last record of the file
+        or when a ``/EOF`` command is read. An automatic switch back one level (to the previous file) occurs
+        when an end-of-file is encountered. Twenty levels of nested file switching are allowed. Note that
+        files including ``\*DO``, :ref:`use`, :ref:`ulib`, and the "Unknown Command" Macro have less nesting


??

Suggested change

files including ``\*DO``, :ref:`use`, :ref:`ulib`, and the "Unknown Command" Macro have less nesting

files including :ref:`do`, :ref:`use`, :ref:`ulib`, and the "Unknown Command" Macro have less nesting

Investigating why this command is not correctly handled.

src/ansys/mapdl/core/_commands/session/run_controls.py

clatapie · 2025-05-23T17:20:16Z

Latest attempts are intended to fix the pytest errors.

…feat/session_submodule

… to use `run` since the `abort` argument is not public.

… in instead of the original class.

germa89 · 2025-05-27T13:07:42Z

Latest attempts are intended to fix the pytest errors.

@clatapie I just fixed the CICD pipeline.

The mypy precommit hook can by bypassed using SKIP env var

SKIP=mypy git commit -m "feat: my commit message"

clatapie · 2025-05-27T16:45:17Z

Thank you very much @germa89!

clatapie and others added 2 commits May 6, 2025 13:03

feat: session submodule

d594b81

chore: adding changelog file 3894.documentation.md [dependabot-skip]

b7d185a

clatapie self-assigned this May 6, 2025

clatapie requested a review from a team as a code owner May 6, 2025 11:04

clatapie requested review from germa89 and pyansys-ci-bot and removed request for a team May 6, 2025 11:04

github-actions bot added documentation Documentation related (improving, adding, etc) new feature Request or proposal for a new feature labels May 6, 2025

chore: adding changelog file 3895.documentation.md [dependabot-skip]

d7e2653

germa89 approved these changes May 6, 2025

View reviewed changes

MaxJPRey approved these changes May 7, 2025

View reviewed changes

clatapie added 4 commits May 23, 2025 17:59

feat: commands ordered by name

d270dec

feat: commands ordered by pyname

f46fea4

Merge branch 'feat/main_commands' into feat/session_submodule

7058040

fix: removing slashexit + commenting mypy as it is not working

d3153d7

germa89 added 5 commits May 27, 2025 13:10

chore: merge remote-tracking branch 'origin/feat/main_commands' into …

15d962a

…feat/session_submodule

fix: update no abort logging and command execution in MapdlGrpc class…

16afab3

… to use `run` since the `abort` argument is not public.

fix: uncomment mypy hook configuration in pre-commit settings

dd610d5

delete: remove duplicated fragment

0ec8c46

fix: improve cwd method to validate directory paths and handle quotes…

1f47975

… in instead of the original class.

		Pressure loads from ``SURF154``elements are converted to equivalent nodal loads for ASAS. For AQWA-
		WAVE, the ``SURF154``pressures are used to identify the wetted surface of the underlying elements.


		.. _ui_coll_label:

		Label specifying the behavior of the Mechanical APDL main menu after a :ref:`finish` command is issued. User interaction with the main menu is unaffected. Valid only for ``Func`` = COLL:


		CONFIG - List only configuration parameters.
		* ``:, label`` - Begins reading from the first line beginning with the matching user-defined label :

	* ``:, label`` - Begins reading from the first line beginning with the matching user-defined label :
	* ``:label`` - Begins reading from the first line beginning with the matching user-defined label :

	files including ``\*DO``, :ref:`use`, :ref:`ulib`, and the "Unknown Command" Macro have less nesting
	files including :ref:`do`, :ref:`use`, :ref:`ulib`, and the "Unknown Command" Macro have less nesting

feat: session submodule #3895

Are you sure you want to change the base?

feat: session submodule #3895

Conversation

clatapie commented May 6, 2025 • edited by sourcery-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issue linked

Checklist

Summary by Sourcery

Summary by Sourcery

Uh oh!

ansys-reviewer-bot bot commented May 6, 2025

Uh oh!

sourcery-ai bot commented May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer's Guide

Updated Class Diagram for RunControls

Updated Class Diagram for ProcessorEntry

Updated Class Diagram for ListControls

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

germa89 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

clatapie commented May 23, 2025

Uh oh!

germa89 commented May 27, 2025

Uh oh!

clatapie commented May 27, 2025

Uh oh!

Uh oh!

feat: `session` submodule #3895

feat: `session` submodule #3895

clatapie commented May 6, 2025 •

edited by sourcery-ai bot

Loading

sourcery-ai bot commented May 6, 2025 •

edited

Loading