fix: command conversion (#4126)

* fix: ``clear``, ``file`` and ``mrep``

* chore: adding changelog file 4126.miscellaneous.md [dependabot-skip]

* chore: adding changelog file 4126.miscellaneous.md [dependabot-skip]

* fix: refactor file and clear methods in _MapdlCommandExtended for improved functionality

---------

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: German <[email protected]>

Author: 3 people

doc/changelog.d/4126.miscellaneous.md

@@ -0,0 +1 @@
+Fix: command conversion

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

@@ -896,7 +896,7 @@ def free(self, name: str = "", val1: str = "", **kwargs):
 
         .. _a-FREE_notes:
 
-        A ``/CLEAR`` command will automatically delete all the current APDL Math objects.
+        A :ref:`clear` command will automatically delete all the current APDL Math objects.
         """
         command = f"*FREE,{name},{val1}"
         return self.run(command, **kwargs)

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

@@ -1080,7 +1080,7 @@ def get(
              - Description
            * - MAT
              - ``Sect1``
-             - ``Item2`` = 0 or blank; ``IT2NUM`` = ``Sect2``. Material ID to be used for general contact between ``Sect1`` and ``Sect2``. Alternative get function: SECTOMAT( ``Sect1``, ``Sect2`` ).
+             - ``Item2`` = 0 or blank; ``IT2NUM`` = ``Sect2``. Material ID to be used for general contact between ``Sect1`` and ``Sect2`` . Alternative get function: SECTOMAT( ``Sect1``, ``Sect2`` ).
            * - REAL
              - ``Sect1``
              - ``Item2`` = 0 or blank; ``IT2NUM`` = ``Sect2``. Real constant ID to be used for general contact between ``Sect1`` and ``Sect2`` . Alternative get function: SECTOREAL( ``Sect1``, ``Sect2`` ).
@@ -3017,11 +3017,11 @@ def inquire(self, strarray: str = "", func: str = "", **kwargs):
 
           * ``JOBNAME`` - Returns the current ``Jobname``.
 
-          * ``RSTDIR`` - Returns rst directory ( ``FILE`` command).
+          * ``RSTDIR`` - Returns rst directory ( :ref:`file` command).
 
-          * ``RSTFILE`` - Returns rst file name ( ``FILE`` command).
+          * ``RSTFILE`` - Returns rst file name ( :ref:`file` command).
 
-          * ``RSTEXT`` - Returns rst file extension ( ``FILE`` command).
+          * ``RSTEXT`` - Returns rst file extension ( :ref:`file` command).
 
           * ``PSEARCH`` - Returns path used for "unknown command" macro ( :ref:`psearch` command).
 

src/ansys/mapdl/core/_commands/aux15/iges.py

@@ -147,7 +147,7 @@ def ioptn(self, lab: str = "", val1: str = "", **kwargs):
         Attempts to read in B-spline curve or surface entities of degree higher than 20 may result in error
         messages.
 
-        If you issue the ``/CLEAR`` command, the :ref:`ioptn` settings return to their defaults.
+        If you issue the :ref:`clear` command, the :ref:`ioptn` settings return to their defaults.
 
         For MERG,YES, merging of coincident geometry items is performed automatically when the :ref:`igesin`
         command is issued (that is, an internal :ref:`nummrg`,KP command is issued). The model is merged
@@ -164,7 +164,7 @@ def ioptn(self, lab: str = "", val1: str = "", **kwargs):
 
         The :ref:`ioptn` command should be issued before the :ref:`igesin` command. You cannot change these
         options after your model has been imported or created. If you must change the options: Clear the
-        database ( ``/CLEAR`` ) or exit and restart the program.
+        database ( :ref:`clear` ) or exit and restart the program.
 
         Set the correct options.
 

src/ansys/mapdl/core/_commands/aux2/binary_file_manipulation.py

@@ -280,10 +280,10 @@ def psmat(
         .. _PSMAT_notes:
 
         This command is used to copy a matrix from the assembled global matrix file ( :file:`.FULL` file) as
-        specified on the ``FILE`` command and write it in a postscript format to a new file named ``Fname``.
-        ``Ext`` (defaults to :file:`Jobname.PS` ). The matrix is symbolized by a grid in which the black or
-        colored squares represent the nonzero coefficients of the matrix. The :file:`.FULL` file must be
-        available for this command to work properly.
+        specified on the :ref:`file` command and write it in a postscript format to a new file named
+        ``Fname``. ``Ext`` (defaults to :file:`Jobname.PS` ). The matrix is symbolized by a grid in which
+        the black or colored squares represent the nonzero coefficients of the matrix. The :file:`.FULL`
+        file must be available for this command to work properly.
 
         If the matrix is large, it may be difficult to display the postscript file. In this case, use
         ``Color`` = BLACK to reduce the postscript file size.

src/ansys/mapdl/core/_commands/database/set_up.py

@@ -23,6 +23,53 @@
 
 class SetUp:
 
+    def clear(self, read: str = "", **kwargs):
+        r"""Clears the database.
+
+        Mechanical APDL Command: `/CLEAR <https://ansyshelp.ansys.com/Views/Secured/corp/v232/en//ans_cmd/Hlp_C_CLEAR.html>`_
+
+        Parameters
+        ----------
+        read : str
+            File read option:
+
+            * ``START`` - Reread :file:`start.ans` file (default).
+
+            * ``NOSTART`` - Do not reread :file:`start.ans` file.
+
+        Notes
+        -----
+
+        .. _s-CLEAR_notes:
+
+        The :ref:`clear` command resets the database to the conditions present at the beginning of the
+        problem.
+
+        The command is typically used between multiple analyses in the same run, or between passes of a
+        multipass analysis (such as between substructure generation, use, and expansion passes).
+
+        The command sets the import and Boolean options back to the default, deletes all items from the
+        database, and sets memory values to zero for items derived from database information. (All files
+        remain intact.) The command also resets the jobname to match the currently open session :file:`.LOG`
+        and :file:`.ERR` files, returning the jobname to its original value or to the most recent value
+        specified via :ref:`filname` with ``KEY`` = 1.
+
+        After the database is cleared, the :file:`start.ans` file is reread (by default) unless ``Read`` =
+        NOSTART.
+
+        Additional commands cannot be stacked (via the $ separator) on the same line as the :ref:`clear`
+        command.
+
+        Use caution when placing the :ref:`clear` command within branching constructs (for example, those
+        using ``*DO`` or ``*IF`` commands), as the command deletes all parameters including the looping
+        parameter for do-loops. (To preserve your iteration parameter, issue a :ref:`parsav` command prior
+        to :ref:`clear`, then follow  :ref:`clear` with a :ref:`parres` command.)
+
+        This command is valid in any processor. Issuing this command at any point clears the database.
+        """
+        command = f"/CLEAR,{read}"
+        return self.run(command, **kwargs)
+
     def resume(
         self,
         fname: str = "",

src/ansys/mapdl/core/_commands/graphics/set_up.py

@@ -1103,7 +1103,7 @@ def mrep(
         of the graphics command macro, following the last graphics command within the macro, to enable the
         replot or zoom feature.
         """
-        command = f"/MREP,{name},{arg1},{arg2},{arg3},,{arg4},{arg5},{arg6},{arg7},{arg8},{arg9},{arg10},{arg11},{arg12},{arg13},{arg14},{arg15},{arg16},{arg17},{arg18}"
+        command = f"/MREP,{name},{arg1},{arg2},{arg3},{arg4},{arg5},{arg6},{arg7},{arg8},{arg9},{arg10},{arg11},{arg12},{arg13},{arg14},{arg15},{arg16},{arg17},{arg18}"
         return self.run(command, **kwargs)
 
     def noerase(self, **kwargs):

src/ansys/mapdl/core/_commands/post1/load_case_calculations.py

@@ -99,7 +99,7 @@ def lcdef(
         ----------
         lcno : str
             Arbitrary pointer number (1-99) to be assigned to the load case specified by ``LSTEP``,
-            ``SBSTEP`` and by the ``FILE`` command. Defaults to 1 + previous value.
+            ``SBSTEP`` and by the :ref:`file` command. Defaults to 1 + previous value.
 
         lstep : str
             Load step number to be defined as the load case. Defaults to one.

src/ansys/mapdl/core/_commands/post1/set_up.py

@@ -572,6 +572,63 @@ def dnsol(
         command = f"DNSOL,{node},{item},{comp},{v1},{v2},{v3},{v4},{v5},{v6},{datakey}"
         return self.run(command, **kwargs)
 
+    def file(self, fname: str = "", ext: str = "", **kwargs):
+        r"""Specifies the data file where results are to be found.
+
+        Mechanical APDL Command: `FILE <https://ansyshelp.ansys.com/Views/Secured/corp/v232/en//ans_cmd/Hlp_C_FILE.html>`_
+
+        Parameters
+        ----------
+        fname : str
+            File name and directory path (248 characters maximum, including the characters needed for the
+            directory path). An unspecified directory path defaults to the working directory; in this case,
+            you can use all 248 characters for the file name. The file name defaults to :file:`Jobname`.
+
+        ext : str
+            Filename extension (eight-character maximum). If ``Fname`` is blank, the extension defaults to
+            RST (for structural, fluid, or coupled-field analyses), to RTH (for thermal or electrical
+            analyses), or to RMG (for magnetic analyses). For postprocessing contact results corresponding
+            to the initial contact state in POST1, use the RCN extension. For postprocessing modal
+            coordinates results in POST1, use the RDSP or RFRQ extension.
+
+        Notes
+        -----
+
+        .. _FILE_notes:
+
+        Specifies the Mechanical APDL data file where the results are to be found for postprocessing.
+
+        Issuing the :ref:`file` command with ``Ext`` = RSDP or RFRQ in POST1 specifies the :file:`.rsdp` or
+        :file:`.rfrq` file used by the :ref:`prmc` and :ref:`plmc` commands. (See :ref:`POST1 example
+        below.) <FILE_POST1example>`
+
+        **Example Usage**
+
+        .. _FILE_examples:
+
+        .. _FILE_POST1example:
+
+        POST1
+        ^^^^^
+
+        .. code:: apdl
+
+           /POST1
+           FILE,,rdsp   !Choose file Jobname.rdsp from a previous MSUP transient solution
+           PRMC,2,1     !Plot Modal coordinates from rdsp file (loadstep and substep specified as arguments)
+           FILE,,rst    !Choose file Jobname.rst
+           SET,1,1      !Load results from chosen.rst file into database
+           PRNSOL,u,x   !Plot Nodal displacements (loadstep and substep specified using the SET command)
+           FINISH       !Exit POST1
+
+        .. _FILE_POST26example:
+
+        POST26
+        ^^^^^^
+        """
+        command = f"FILE,{fname},{ext}"
+        return self.run(command, **kwargs)
+
     def hrcplx(
         self,
         loadstep: str = "",
@@ -811,8 +868,8 @@ def rescombine(
         :ref:`reswrite` to write the data set into a new results file. The new results file will essentially
         contain the current set of results data for the entire (that is, global) model.
 
-        Upon completion of a :ref:`rescombine` operation, the current file for postprocessing ( ``FILE`` )
-        is set to the last local results file specified via :ref:`rescombine`. For example, if reading in
+        Upon completion of a :ref:`rescombine` operation, the current file for postprocessing ( :ref:`file`
+        ) is set to the last local results file specified via :ref:`rescombine`. For example, if reading in
         four local results files, the results file for POST1 is specified as :file:`Jobname3.RST` when
         :ref:`rescombine` is complete. Therefore, be aware that some downstream postprocessing actions (such
         as :ref:`set` ) may be operating on only this one local results file.

src/ansys/mapdl/core/_commands/post1/special_purpose.py

@@ -318,7 +318,7 @@ def cmsfile(
         If ``CmsKey`` = ON (default), output from the command appears as: ``ADD CMS FILE =`` filename.rst
         ``CmsKey`` = OFF, output from the command appears as: ``ADD FILE =`` filename.rst
 
-        If ``Option`` = DELETE or CLEAR, you must clear the database ( ``/CLEAR`` ), then re-enter the
+        If ``Option`` = DELETE or CLEAR, you must clear the database ( :ref:`clear` ), then re-enter the
         postprocessor ( :ref:`post1` ) and issue a :ref:`set` command for the change to take effect on
         subsequent plots.
 
@@ -2020,8 +2020,8 @@ def plmc(
         :ref:`outres` command description.
 
         For a cyclic harmonic mode-superposition analysis, use the :ref:`cycfiles` command to identify the
-        :file:`.rfrq` None and modal :file:`.rst` None file. For other analyses, use the ``FILE`` command to
-        specify the :file:`.rdsp` or :file:`.rfrq` file.
+        :file:`.rfrq` None and modal :file:`.rst` None file. For other analyses, use the :ref:`file` command
+        to specify the :file:`.rdsp` or :file:`.rfrq` file.
 
         You may limit the plot to display only those modes in a certain harmonic index range. The modes
         having the same harmonic index are each plotted in a unique color. If there are less than 10
@@ -3016,8 +3016,8 @@ def prmc(
         :ref:`outres` command description.
 
         For a cyclic harmonic mode-superposition analysis, use the :ref:`cycfiles` command to identify the
-        :file:`.rfrq` None and modal :file:`.rst` None files. For other analyses, use the ``FILE`` command
-        to specify the :file:`.rdsp` or :file:`.rfrq` file.
+        :file:`.rfrq` None and modal :file:`.rst` None files. For other analyses, use the :ref:`file`
+        command to specify the :file:`.rdsp` or :file:`.rfrq` file.
 
         This information can also be obtained from the optional :file:`Jobname.mcf` text file (see the
         :ref:`trnopt` and :ref:`hropt` commands), and it can be plotted using the :ref:`plmc` command. For