What should we do with the undocumented arguments (--) ?

[germa89]

Given this APDL command:

MPCOPY,--,matf,matt

where:

• -- is an "unused" field or, in pythonic terms, an undocumented argument. This undocumented argument can serve different purposes:
  • Maybe it is a deprecated argument which is kept there to mantain the API (other arguments position)
  • Maybe it is an empty placeholder for future arguments
  • Maybe its usage is not intended for general public.
  • Others reasons...
• matf and matt are well-documented and used comamnds.

What should we do with the undocumented argument (sometimes referred as 'unused'), knowing the following assumptions:

Assuptions

• You can't have empty arguments in PyMAPDL. The following code is not a valid Python code:

 mapdl.mpcopy(,matf,matt)

• The fact that an argument is "unused" or undocumented, does not mean that is not used internally. For instance WB uses some undocumented arguments to interface with MAPDL solver.
• Different versions of MAPDL can add or remove undocumented arguments.

What to do?

Option A. Remove it all together from the PyMAPDL function (Current behaviour).

The function signature will be then:

mapdl.mpcopy(matf="", matt="")

If you want to use the undocumented argument, you can use mapdl.run:

mapdl.run("/MPCOPY,arg,matf,matt")

Please do notice that the user needs to know the full MAPDL command, which sometimes can be tricking because PyMAPDL strip leading *, /, and \ from the command name, since those symbols are not allowed in Python function names.
Some commands requires them to discriminate for instance from *SET, from SET, which are converted to mapdl.starset and mapdl.set.

Option B. Keep the place holder for the unused command.

This makes using the command a bit cumbersome, because in 95% of the times the standard user does not need to use the undocumented argument, but with this option you are forced to do:

mapdl.mpcopy("", matf, matt)

Furthermore, when defining the function you need to define that argument which as no name, that could be probably bypassed with something like:

def mpcopy(self, empty1="", matf="", matt=""):
        """APDL Command: MPCOPY

        Copies linear material model data from one material reference number to
        another.
        ....

It should also be noticed that commands can have multiple undocumented arguments, for instance BCSOPTION or MODOPT.

[germa89]

Pinging @ansys/pymapdl-collaborators @ansys/pymapdl-developers @ansys/pymapdl-maintainers @ansys/pyansys-core for feedback

[germa89]

Finished poll:

Result: Option A. Remove it all together from the PyMAPDL function (Current behaviour).

[mikerife]

Well, looks like I lost this argument in a land slide. Oh well.

[mcMunich]

I don't know if the APIP data records apdl commands (they track element usage) but if a command is undocumented and unused, then of course remove it. If users are still using it, these would be long time apdl users and might be convinced to convert to pymapdl if, for starters, all the same functionality is there. But that is not super likely.
Also note, the example command MPCOPY is used in a verification manual example 242 and maybe that is another reason to keep certain commands.

https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/v242/en/ans_vm/Hlp_V_VM242TXT.html?q=vm242

[mikerife]

Hi @mcMunich the poll was about unused fields of commands and not unused commands. If PyMAPDL is going to support MAPDL going back to version 14.5 then supporting undocumented etc commands is necessary.