feat: `apdl` submodule #3385

clatapie · 2024-09-05T16:03:53Z

This PR is the first one in order to automate the PyMAPDL _commands documentation.
The changes have been generated using pyconverter-xml2py.

This PR focus on the apdl submodule.

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

Note

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

… hook)

ansys-reviewer-bot · 2024-09-05T16:04:01Z

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

@ansys-reviewer-bot review

germa89 · 2024-09-05T16:06:33Z

I am setting this PR as draft because I think it is still not ready until you fix the line length thing.

Ping us and switch this PR to non-draft when you feel it is ready for it.

clatapie · 2024-09-05T16:23:35Z

I can rework on it if docstring length is a priority. I already fixed some issues related in ansys/pyconverter-xml2py#222 but not all of them as you can see.
Except from this issue, feel free to comment any other change you would like me to work on.

Also, I had to comment the codespell pre-commit hook because it was failing even when I was ignoring the dedicated directory ``./src/ansys/mapdl/core/_commands). The next commit will show it.

wiz-inc-572fc38784 · 2024-10-18T12:07:04Z

Wiz Scan Summary

Scanner	Findings
Vulnerabilities
Sensitive Data
Secrets
IaC Misconfigurations

Total

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try using Wiz Code VS Code Extension.

…y subfolder new feature

RobPasMue

Overall LGTM - couldn't really evaluate whether all the changes make sense or not but the logic seems properly done and the docstrings are really nicely formatted (for being autogenerated).

My concern is only about modules that have been renamed completely (take array_param to array_parameters. Maybe we should "keep" the old file, throw a warning saying that this module is deprecated, and import all the "new module" objects in this module (through a star import). But I'd only do this if users are frequently accessing the _commands subpackage directly... otherwise, let the Mapdl object handle it for them.

clatapie · 2024-11-28T13:39:41Z

Good point, thanks for reminding it @RobPasMue!
I will adjust the outdated files to follow the process you mentioned

clatapie · 2024-11-28T14:09:35Z

Error with *TREAD.

Currently in PyMAPDL:

command = f"*TREAD,{par},{fname},{ext},,{nskip}"

With the auto-generated package:

command = f"*TREAD,{par},{fname},{ext},{nskip}"

Fixing this coma error might solve other failing tests as well.
This will be fixed in ansys/pyconverter-xml2py#356

clatapie · 2024-11-28T14:11:24Z

.github/workflows/ci.yml

@@ -33,7 +33,7 @@ env:
  DPF_PORT: 21004
  MAPDL_PACKAGE: ghcr.io/ansys/mapdl
  ON_CI: True
-  PYTEST_ARGUMENTS: '-vvv -rxXsa --color=yes --durations=10 --random-order --random-order-bucket=class --maxfail=10 --reruns 3 --reruns-delay 4 --cov=ansys.mapdl.core --cov-report=html'
+  PYTEST_ARGUMENTS: '-vvv -rxXsa --color=yes --durations=10 --random-order --random-order-bucket=class --maxfail=100 --reruns 3 --reruns-delay 4 --cov=ansys.mapdl.core --cov-report=html'


This will be reverted once the tests will pass

germa89 · 2024-11-28T16:09:31Z

@clatapie ... CICD is SUPER unstable right now since I merged #3268. I'm working on that.

I would probably revert that commit in the main_commands branch and see if the PR passes. To be safe, I would probably revert any other commit after since I'm working quite a lot on that at the moment.

germa89 · 2024-11-28T16:14:15Z

Overall LGTM - couldn't really evaluate whether all the changes make sense or not but the logic seems properly done and the docstrings are really nicely formatted (for being autogenerated).

My concern is only about modules that have been renamed completely (take array_param to array_parameters. Maybe we should "keep" the old file, throw a warning saying that this module is deprecated, and import all the "new module" objects in this module (through a star import). But I'd only do this if users are frequently accessing the _commands subpackage directly... otherwise, let the Mapdl object handle it for them.

Users are not expected to access _commands by themselves, so any adjustment can be done in any of the Commands subclasses:

For modifying already APDL commands use _MapdlCommandExtended
For implementing new commands common to all interfaces _MapdlExtended

clatapie · 2024-11-28T17:17:54Z

Thanks for your feedback @germa89.

The issue I found here is unrelated to the unit test stability. However, if after fixing it the error persists, I will remove the random argument.

You are right! Then, changes should already be in place as I manually modified src/ansys/mapdl/core/commands.py.

germa89

Very good progress, this is looking great.

I would say there a few pain points we need to fix first before final merging.

Paragraphs in Notes are being merged into one.
Identations are wrong in some arguments (fname mainly)
we should decide what to do when the arguments descriptions are the same.
Many places have strange line lengths... like way too long... sometimes they have links.
the mkdir command is missing the argument
It seems bold format is not respected (it is always ignored)
*SET notes section is bad formatted, I think it is missing stuff.

Another things to consider:

For some reason the left side bar is not in alphabetical order:

(it did take a while this review... damn)

germa89 · 2024-11-28T16:21:38Z

.pre-commit-config.yaml

+# - repo: https://github.com/codespell-project/codespell
+#   rev: v2.3.0
+#   hooks:
+#   - id: codespell
+#     args: ["--toml", "pyproject.toml"]
+#     additional_dependencies: ["tomli"]


Why this was deleted?

I commented it as explained in #3385 (comment)
I have planned to rework on it. For the moment, I don't know why the repository can not be ignored.

germa89 · 2024-11-28T16:22:22Z

doc/source/mapdl_commands/apdl/abbreviations.rst

+   Abbreviations.ucmd
+   Abbreviations.abbres
+   Abbreviations.abbr
+   Abbreviations.abbsav


If we are going to extend this commands on _MapdlCommandExtended class... shouldn't we use Mapdl or _MapdlCommandExtended instead of Abbreviations ??

Same for all the rest.

germa89 · 2024-11-28T16:23:11Z

doc/source/mapdl_commands/apdl/index.rst

+.. _ref_apdl:
+
+<!-- vale off -->
+Apdl


I think APDL should be all capital.

germa89 · 2024-11-28T16:26:38Z

doc/source/mapdl_commands/apdl/index.rst

+<!-- vale on -->
+
+.. list-table::
+
+   * - :ref:`ref_macro_files`
+   * - :ref:`ref_parameter_definition`
+   * - :ref:`ref_matrix_operations`
+   * - :ref:`ref_abbreviations`
+   * - :ref:`ref_process_controls`
+   * - :ref:`ref_array_parameters`
+   * - :ref:`ref_encryption_decryption`
+
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   macro_files
+   parameter_definition
+   matrix_operations
+   abbreviations
+   process_controls
+   array_parameters
+   encryption_decryption


This is amazing.

germa89 · 2024-11-28T16:27:53Z

examples/00-mapdl-examples/transient_thermal.py

@@ -290,7 +290,7 @@
 plt.plot(my_bulk[:, 0], my_bulk[:, 1], ":", label="Input")
 plt.legend()
 plt.xlabel("Time (seconds)")
-plt.ylabel("Temperature ($^\circ$F)")
+plt.ylabel("Temperature (°F)")


I think it is better to keep the old one... since it is rendered with LaTeX... but probably both works.

germa89 · 2024-11-28T17:59:55Z

src/ansys/mapdl/core/_commands/apdl/parameter_definition.py

+           \*TAXIS,longtable(1,4,1,1),2,1.0,2.2,3.5,4.7,5.9
+         ``nAxis`` 2 (column location), starting at location 4.


Missing tex and newline.

Suggested change

\*TAXIS,longtable(1,4,1,1),2,1.0,2.2,3.5,4.7,5.9

``nAxis`` 2 (column location), starting at location 4.

\*TAXIS,longtable(1,4,1,1),2,1.0,2.2,3.5,4.7,5.9

would fill index values 1.0, 2.2, 3.5, 4.7, and 5.9 in ``nAxis`` 2 (column location), starting at location 4.

germa89 · 2024-11-28T18:00:27Z

src/ansys/mapdl/core/_commands/apdl/parameter_definition.py

-        Assigns values to user-named parameters that may be substituted later
-        in the run.  The equivalent (and recommended) format is
+        Reads data from a file and fills in an array parameter vector or matrix. Data are read from a
+        formatted file or, if the menu is off ( :ref:`menu` ,OFF) and ``Fname`` is blank, from the next input lines. The format of the data to be read must be input immediately following the :ref:`vread` command. The format specifies the number of fields to be read per record, the field width, and the placement of the decimal point (if none specified in the value). The read operation follows the available FORTRAN FORMAT conventions of the system (see your system FORTRAN manual). Any standard FORTRAN `real` format (such as (4F6.0), (E10.3,2X,D8.2), etc.) or alphanumeric format (A) may be used. Alphanumeric


I'm puzzled with the line lengths.. they are so random...

germa89 · 2024-11-28T18:02:59Z

src/ansys/mapdl/core/_commands/apdl/parameter_definition.py

+        to (blank). A defined parameter must be deleted ( :ref:`starset` ) before its dimensions can be changed. Scalar (single valued) parameters should not be dimensioned. :ref:`dim` ,A,,3 defines a vector array with elements A(1), A(2), and A(3). :ref:`dim` ,B,,2,3 defines a 2x3 array with elements B(1,1), B(2,1), B(1,2), B(2,2), B(1,3), and B(2,3). Use :ref:`starstatus`, ``Par`` to display elements of array ``Par`` . You can write formatted data files (tabular formatting) from data held in arrays through the :ref:`vwrite` command.
+
+        If you use table parameters to define boundary conditions, then ``Var1``, ``Var2``, and/or ``Var3`` can either specify a primary variable (listed in ) or can be an independent parameter. If specifying an independent parameter, then you must define an additional table for the independent parameter. The additional table must have the same name as the independent parameter and may be a function of one or more primary variables or another independent parameter. All independent parameters must relate to a primary variable.
+
+        Tabular load arrays can be defined in both global Cartesian (default), cylindrical, spherical, or


germa89 · 2024-11-28T18:05:22Z

src/ansys/mapdl/core/_commands/apdl/process_controls.py

+    def endif(self, **kwargs):
+        r"""Ends an if-then-else.
+
+        Mechanical APDL Command: `\*ENDIF <https://ansyshelp.ansys.com/Views/Secured/corp/v232/en//ans_cmd/Hlp_C_ENDIF.html>`_
+
+        Notes


In the future I would like to add bits here.. like how these commands are compared to the python ones.

germa89 · 2024-11-28T18:06:23Z

src/ansys/mapdl/core/_commands/apdl/process_controls.py

+        -----
+        Optional intermediate block separator within an if-then-else construct. All seven characters of the
+        command name (\*ELSEIF) must be input. This command is similar to the :ref:`if` command except that
+        the ``Base`` field is not used. The :ref:`if`, :ref:`elseif`, :ref:`else`, and :ref:`endif`


:ref:else is also taken from the python guide...

You might need to go for :ref:ansys.mapdl.core.mapdl.MapdlBase.if or similar...

(double check the above)

germa89 · 2024-11-28T18:10:49Z

Error with *TREAD.

Currently in PyMAPDL:
command = f"*TREAD,{par},{fname},{ext},,{nskip}"
With the auto-generated package:
command = f"*TREAD,{par},{fname},{ext},{nskip}"
Fixing this coma error might solve other failing tests as well. This will be fixed in ansys/pyconverter-xml2py#356

Just double checking that the version with the empty argument is the correct one. :)

…odule

RobPasMue · 2024-12-11T07:31:45Z

@germa89 - this PR should be "automated". I don't understand the reason to make local changes.

clatapie · 2024-12-11T14:54:30Z

@germa89 's previous changes might be automatic since the branch is connected to feat/main_commands and not to the main one.

…into feat/apdl_submodule

feat: changes obtained using pyconverter-xml2py (after pre-commit…

e9de204

… hook)

clatapie added documentation Documentation related (improving, adding, etc) enhancement Improve any current implemented feature labels Sep 5, 2024

clatapie self-assigned this Sep 5, 2024

clatapie requested a review from a team as a code owner September 5, 2024 16:03

clatapie requested review from germa89 and pyansys-ci-bot and removed request for a team September 5, 2024 16:03

clatapie requested a review from RobPasMue September 5, 2024 16:04

github-actions bot added new feature Request or proposal for a new feature and removed documentation Documentation related (improving, adding, etc) labels Sep 5, 2024

chore: adding changelog file 3385.added.md

04dac45

germa89 marked this pull request as draft September 5, 2024 16:06

github-actions bot added CI/CD Related with CICD, Github Actions, etc examples Publishing PyMAPDL examples documentation Documentation related (improving, adding, etc) dependencies maintenance General maintenance of the repo (libraries, cicd, etc) labels Oct 18, 2024

clatapie force-pushed the feat/apdl_submodule branch from ac7b46a to 04dac45 Compare October 18, 2024 12:15

github-actions bot removed CI/CD Related with CICD, Github Actions, etc examples Publishing PyMAPDL examples documentation Documentation related (improving, adding, etc) dependencies maintenance General maintenance of the repo (libraries, cicd, etc) labels Oct 18, 2024

Merge branch 'main' into feat/apdl_submodule

5d300f1

github-actions bot added the CI/CD Related with CICD, Github Actions, etc label Oct 18, 2024

clatapie added 6 commits November 26, 2024 10:16

feat: removing unauthorized MAPDL methods and using pyconverter-xml2p…

47fb37a

…y subfolder new feature

test: skip retrieving value for endif and enddo

a246c15

fix: tests

ea01683

Merge branch 'feat/main_commands' into feat/apdl_submodule

d745c79

fix: tests - 2

56e1823

maint: modifying max run for testing purpose only - TO BE MODIFIED

ddeab20

RobPasMue approved these changes Nov 28, 2024

View reviewed changes

fix: test_command for *END... commands

19b6461

github-actions bot added the examples Publishing PyMAPDL examples label Nov 28, 2024

clatapie commented Nov 28, 2024

View reviewed changes

germa89 requested changes Nov 28, 2024

View reviewed changes

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

77c5683

…odule

clatapie mentioned this pull request Dec 11, 2024

fix: command issues ansys/pyconverter-xml2py#374

Open

Merge branch 'feat/main_commands' into feat/apdl_submodule

95109a4

clatapie added 8 commits December 12, 2024 11:03

fix: coma issues in commands

510e624

Merge branch 'feat/apdl_submodule' of https://github.com/ansys/pymapdl …

b433ec0

…into feat/apdl_submodule

maint: adding linuxdoc dependency for flat tables

f984e72

docs: removing ref.ref warning temporarily

ca3e9ef

fix: removing xpl and directory methods

15d9084

feat: adding links from pyconverter-xml2py

712a2e3

fix: removing mwrite and vwrite methods

cd7f2f1

fix: readding mwrite and vwrite methods + fixing mkdir

7baebc4

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: `apdl` submodule #3385

feat: `apdl` submodule #3385

clatapie commented Sep 5, 2024 •

edited

Loading

ansys-reviewer-bot bot commented Sep 5, 2024

germa89 commented Sep 5, 2024

clatapie commented Sep 5, 2024

wiz-inc-572fc38784 bot commented Oct 18, 2024 •

edited

Loading

RobPasMue left a comment •

edited

Loading

clatapie commented Nov 28, 2024

clatapie commented Nov 28, 2024

clatapie Nov 28, 2024

germa89 commented Nov 28, 2024

germa89 commented Nov 28, 2024

clatapie commented Nov 28, 2024

germa89 left a comment

germa89 Nov 28, 2024

clatapie Dec 13, 2024

germa89 Nov 28, 2024

germa89 Nov 28, 2024

germa89 Nov 28, 2024

germa89 Nov 28, 2024

germa89 Nov 28, 2024

germa89 Nov 28, 2024

germa89 Nov 28, 2024

germa89 Nov 28, 2024

germa89 Nov 28, 2024

germa89 Nov 28, 2024

germa89 Nov 28, 2024

germa89 Nov 28, 2024

germa89 commented Nov 28, 2024

RobPasMue commented Dec 11, 2024

clatapie commented Dec 11, 2024

		\*TAXIS,longtable(1,4,1,1),2,1.0,2.2,3.5,4.7,5.9
		``nAxis`` 2 (column location), starting at location 4.

feat: apdl submodule #3385

Are you sure you want to change the base?

feat: apdl submodule #3385

Conversation

clatapie commented Sep 5, 2024 • edited Loading

Note

Checklist

ansys-reviewer-bot bot commented Sep 5, 2024

germa89 commented Sep 5, 2024

clatapie commented Sep 5, 2024

wiz-inc-572fc38784 bot commented Oct 18, 2024 • edited Loading

Wiz Scan Summary

RobPasMue left a comment • edited Loading

Choose a reason for hiding this comment

clatapie commented Nov 28, 2024

clatapie commented Nov 28, 2024

Choose a reason for hiding this comment

germa89 commented Nov 28, 2024

germa89 commented Nov 28, 2024

clatapie commented Nov 28, 2024

germa89 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

germa89 commented Nov 28, 2024

RobPasMue commented Dec 11, 2024

clatapie commented Dec 11, 2024

feat: `apdl` submodule #3385

feat: `apdl` submodule #3385

clatapie commented Sep 5, 2024 •

edited

Loading

wiz-inc-572fc38784 bot commented Oct 18, 2024 •

edited

Loading

RobPasMue left a comment •

edited

Loading