diff --git a/doc/changelog.d/3895.miscellaneous.md b/doc/changelog.d/3895.miscellaneous.md new file mode 100644 index 0000000000..791edffbfe --- /dev/null +++ b/doc/changelog.d/3895.miscellaneous.md @@ -0,0 +1 @@ +Feat: ``session`` submodule \ No newline at end of file diff --git a/doc/source/mapdl_commands/session/files.rst b/doc/source/mapdl_commands/session/files.rst index 9e65c19d57..bc00c7e9c9 100644 --- a/doc/source/mapdl_commands/session/files.rst +++ b/doc/source/mapdl_commands/session/files.rst @@ -1,25 +1,29 @@ -.. _ref_files_commands_api: -***** +.. _ref_files: + + Files -***** +===== + -.. currentmodule:: ansys.mapdl.core +.. currentmodule:: ansys.mapdl.core._commands.session.files -These SESSION commands are for file operations, such as deleting, -copying, and listing. +.. autoclass:: ansys.mapdl.core._commands.session.files.Files .. autosummary:: - :toctree: _autosummary/ - - Mapdl.anstoaqwa - Mapdl.anstoasas - Mapdl.assign - Mapdl.copy - Mapdl.slashdelete - Mapdl.fcomp - Mapdl.lgwrite - Mapdl.starlist - Mapdl.slashclog - Mapdl.slashfdele - Mapdl.rename + :template: base.rst + :toctree: _autosummary + + + Files.anstoaqwa + Files.anstoasas + Files.assign + Files.copy + Files.fclean + Files.fcomp + Files.lgwrite + Files.slashclog + Files.slashdelete + Files.slashfdele + Files.slashrename + Files.starlist diff --git a/doc/source/mapdl_commands/session/index.rst b/doc/source/mapdl_commands/session/index.rst new file mode 100644 index 0000000000..9218113b63 --- /dev/null +++ b/doc/source/mapdl_commands/session/index.rst @@ -0,0 +1,22 @@ + +.. _ref_session: + +Session +======= + +.. list-table:: + + * - :ref:`ref_files` + * - :ref:`ref_list_controls` + * - :ref:`ref_run_controls` + * - :ref:`ref_processor_entry` + + +.. toctree:: + :maxdepth: 1 + :hidden: + + files + list_controls + run_controls + processor_entry diff --git a/doc/source/mapdl_commands/session/list_controls.rst b/doc/source/mapdl_commands/session/list_controls.rst index d555443cd9..56805db46f 100644 --- a/doc/source/mapdl_commands/session/list_controls.rst +++ b/doc/source/mapdl_commands/session/list_controls.rst @@ -1,18 +1,23 @@ -.. _ref_list_controls_commands_api: -************* -List controls -************* +.. _ref_list_controls: -.. currentmodule:: ansys.mapdl.core -These SESSION commands are used to control listings and printed program output. +ListControls +============ + + +.. currentmodule:: ansys.mapdl.core._commands.session.list_controls + +.. autoclass:: ansys.mapdl.core._commands.session.list_controls.ListControls .. autosummary:: - :toctree: _autosummary/ + :template: base.rst + :toctree: _autosummary + - Mapdl.com - Mapdl.golist - Mapdl.gopr - Mapdl.nolist - Mapdl.nopr + ListControls.com + ListControls.golist + ListControls.gopr + ListControls.nolist + ListControls.nopr + ListControls.slashgo diff --git a/doc/source/mapdl_commands/session/processor_entry.rst b/doc/source/mapdl_commands/session/processor_entry.rst index 0cb79b4962..42810f8a07 100644 --- a/doc/source/mapdl_commands/session/processor_entry.rst +++ b/doc/source/mapdl_commands/session/processor_entry.rst @@ -1,24 +1,23 @@ -.. _ref_processor_entry_commands_api: -*************** -Processor entry -*************** +.. _ref_processor_entry: -.. currentmodule:: ansys.mapdl.core -These SESSION commands are used to enter and exit the various processors in the program. +ProcessorEntry +============== + + +.. currentmodule:: ansys.mapdl.core._commands.session.processor_entry + +.. autoclass:: ansys.mapdl.core._commands.session.processor_entry.ProcessorEntry .. autosummary:: - :toctree: _autosummary/ - - Mapdl.aux2 - Mapdl.aux3 - Mapdl.aux12 - Mapdl.aux15 - Mapdl.finish - Mapdl.map - Mapdl.post1 - Mapdl.post26 - Mapdl.prep7 - Mapdl.quit - Mapdl.slashsolu + :template: base.rst + :toctree: _autosummary + + + ProcessorEntry.finish + ProcessorEntry.post1 + ProcessorEntry.post26 + ProcessorEntry.prep7 + ProcessorEntry.quit + ProcessorEntry.slashsolu diff --git a/doc/source/mapdl_commands/session/run_controls.rst b/doc/source/mapdl_commands/session/run_controls.rst index 056810bc94..d3fe196843 100644 --- a/doc/source/mapdl_commands/session/run_controls.rst +++ b/doc/source/mapdl_commands/session/run_controls.rst @@ -1,29 +1,34 @@ -.. _ref_run_controls_commands_api: -************ -Run controls -************ +.. _ref_run_controls: -.. currentmodule:: ansys.mapdl.core -These SESSION commands control the overall characteristics of the -session, including the job name, Graphical User Interface behavior, and -file switching. +RunControls +=========== + + +.. currentmodule:: ansys.mapdl.core._commands.session.run_controls + +.. autoclass:: ansys.mapdl.core._commands.session.run_controls.RunControls .. autosummary:: - :toctree: _autosummary/ - - Mapdl.config - Mapdl.cwd - Mapdl.exit - Mapdl.filname - Mapdl.input - Mapdl.keyw - Mapdl.memm - Mapdl.nerr - Mapdl.pause - Mapdl.slashstatus - Mapdl.starstatus - Mapdl.syp - Mapdl.sys - Mapdl.unpause + :template: base.rst + :toctree: _autosummary + + + RunControls.config + RunControls.cwd + RunControls.filname + RunControls.input + RunControls.keyw + RunControls.memm + RunControls.menu + RunControls.mstart + RunControls.nerr + RunControls.output + RunControls.pause + RunControls.slashstatus + RunControls.syp + RunControls.sys + RunControls.ui + RunControls.uis + RunControls.unpause diff --git a/src/ansys/mapdl/core/_commands/session/__init__.py b/src/ansys/mapdl/core/_commands/session/__init__.py index eff5c0cf7f..43083dd622 100644 --- a/src/ansys/mapdl/core/_commands/session/__init__.py +++ b/src/ansys/mapdl/core/_commands/session/__init__.py @@ -20,4 +20,9 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. -from . import files, list_controls, processor_entry, run_controls +from . import ( + files, + list_controls, + processor_entry, + run_controls, +) diff --git a/src/ansys/mapdl/core/_commands/session/files.py b/src/ansys/mapdl/core/_commands/session/files.py index 438e3f4cc2..44fe591c66 100644 --- a/src/ansys/mapdl/core/_commands/session/files.py +++ b/src/ansys/mapdl/core/_commands/session/files.py @@ -20,676 +20,744 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. -"""These SESSION commands are for file operations, such as deleting, copying, and listing.""" - class Files: - def anstoasas(self, fname="", key="", **kwargs): - """Creates an ASAS input file from the current ANSYS model. - APDL Command: ANSTOASAS + def anstoaqwa( + self, + fname: str = "", + vertaxis: str = "", + gc: str = "", + rho: str = "", + hwl: str = "", + diffkey: int | str = "", + symxkey: int | str = "", + symykey: int | str = "", + **kwargs, + ): + r"""Creates an AQWA-LINE input file from the current Mechanical APDL model. + + Mechanical APDL Command: `ANSTOAQWA `_ Parameters ---------- - fname - ASAS file name. Defaults to Jobname. + fname : str + AQWA file name. Defaults to :file:`Jobname`. - key - Key indicating type of file to produce: + vertaxis : str + Axis in the vertical direction: + + * ``Y (or 2)`` - Global Y axis. + + * ``Z (or 3)`` - Global Z axis (default). + + gc : str + Gravitational acceleration. Defaults to 9.81. + + rho : str + Density of water. Defaults to 1025.0. + + hwl : str + Waterline height in model coordinates. Defaults to 0.0. + + diffkey : int or str + Diffracting model key: + + * ``0`` - Create a non-diffracting AQWA model. + + * ``1`` - Create a diffracting AQWA model (default). + + symxkey : int or str + Key indicating if model is symmetric about the global XZ plane: - 0 - ASAS file for use by ANSYS Aqwa (no loads written). Creates the file - Fname.asas. + * ``0`` - No symmetry about XZ plane (default). - 1 - ASAS file (all data written, including loads). Creates the file Fname.asas. + * ``1`` - Use symmetry about XZ plane. Only include (or select) half the model. - 2 - ASAS(NL) file. Creates the file Fname.asnl. + symykey : int or str + Key indicating if model is symmetric about the global YZ plane: + + * ``0`` - No symmetry about YZ plane (default). + + * ``1`` - Use symmetry about YZ plane. Only include (or select) half the model. Notes ----- - This command creates an input file for the ANSYS Asas Finite Element - Analysis System from the model and loads currently in the database, - based on the currently selected set of elements. Most common structural - element types are written, as well as sections (or real constants), - materials, boundary conditions and loads, and solution and load step - options. - Data Written + .. _ANSTOAQWA_notes: - The following data is written: + This command creates the input file ``Fname``.aqwa for the Ansys Aqwa Multi-Body Hydrodynamics + System + for diffraction analysis in AQWA-LINE from the model currently in the database, based on the + currently selected set of elements. The selected set must only include the hull envelope; no + internal structure should be selected. - Solution control options + There should be a line of nodes defined at the waterline. Only those elements that are entirely + below the waterline will be specified as diffracting. If there are no waterline nodes, there will be + no diffracting elements at the waterline, which will severely reduce the accuracy of the diffraction + analysis. - Nodes + The translator maps PLANE42, SHELL63, and ``SHELL181`` elements to PANELs, and maps PIPE16 and + PIPE59 elements to TUBEs. It does not recognize any other element types. Any material or geometric + properties can be used for the shell elements, as AQWA does not need any properties at all and the + command does not use them. All the shell elements below the water must have their normals pointing + outward. - Elements + TUBE elements in AQWA have material density, outside diameter, wall thickness, added mass, and drag + coefficients, so appropriate properties should be used in the Mechanical APDL model. PIPE59 elements + can + have added mass and damping coefficients; these will be written to the file. The Mechanical APDL + program + uses the inertia coefficient C M, whereas AQWA uses the added mass coefficient C A, where C M = (1 + + C A ). This correction is made automatically. - Material data + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - Geometry data + In AQWA the vertical axis is always the Z-axis. The command can convert a model built with either + the Y or Z-axis vertical, but the X-axis must be horizontal and should preferably be along the + fore/aft axis of the vessel. If the structure is symmetric and you wish to use the symmetry options, + you must only select one half or one quarter of the model, as appropriate. If you model a complete + vessel and specify X symmetry, the AQWA model will contain two sets of coincident elements. - Section data + If you are working from a model created for a structural analysis, it will probably be necessary to + remesh the model as the structural mesh is most likely finer than needed for a diffraction analysis. - ANSYS element components (ASAS sets) + If you enter this command interactively (with the GUI active) and no data is provided for the + command options, the application prompts you for their values. - Boundary conditions + You must verify the completeness and accuracy of the data written. - Loads + **AQWA-LINE Notes** - Added mass (via MASS21 element) + .. _ANSTOAQWA_aqwa: - Details are provided in the following sections. + The file will specify restart stages 1-2 only. It has no options except REST, so AQWA may fail if + any of the elements are badly shaped. - Not all data is written. You must verify the completeness and accuracy - of the data. Only loading at the current step is transferred; hence, no - load step history is captured. + The total mass is obtained by integrating over the wetted surface area and adding the TUBE masses, + so it should be reasonably accurate. However, the integration used is not as accurate as that in + AQWA, so there may be a small difference between the weight and buoyancy, particularly if tubes + represent a large portion of the model. - Solution Control Options + The position of the CG is unknown. A point mass is placed at the water-line above the CB, but you + should change this to the correct position. - The ASAS project name is defined as "ANSYS". + The moments of inertia are estimated based on the overall dimensions of the model and using standard + formulae for a ship. You should change these to the correct values. - The solution control options are converted as follows: + The maximum frequency is calculated from the maximum side length of the underwater elements. The + range of frequencies runs from 0.1 rad/s to the calculated maximum, in steps of 0.1 rad/s. - JOB: STAT SPIT: KGEOM + The directions are in steps of 15° over a range that is determined by the symmetry you have + specified, in accordance with the requirements of AQWA. + """ + command = f"ANSTOAQWA,{fname},{vertaxis},{gc},{rho},{hwl},{diffkey},{symxkey},{symykey}" + return self.run(command, **kwargs) - JOB: STAT SPIT: KGEOM + def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): + r"""Creates an ASAS input file from the current Mechanical APDL model. - For conversion to ASAS(NL), the large displacement option is set based - on NLGEOM, final load solution time is set based on TIME, and sub-step - times are set based on DELTIM or NSUBST (assuming constant step size). + Mechanical APDL Command: `ANSTOASAS `_ - Element Data + Parameters + ---------- + fname : str + ASAS file name. Defaults to :file:`Jobname`. - If you intend to use the data only with AQWA-WAVE, only the elements - that form the wetted surface are required. Selecting these elements - before invoking the ANSTOASAS command will improve performance. In - order for AQWA-WAVE to identify the direction of the wave loading, all - elements must be defined by nodes in a clockwise direction. For further - information, refer to the AQWA-WAVE manual. + key : int or str + Key indicating type of file to produce: - The element types are converted as follows: + * ``0`` - ASAS file for use by Ansys Aqwa (no loads written). Creates the file ``Fname``.asas. - SPR1: SPR2: if: rotational: spring: FLA2: (ASAS(L): only): if: - nodes: are: not: coincident: and: longitudinal: spring: + * ``1`` - ASAS file (all data written, including loads). Creates the file ``Fname``.asas. - QUM4: TRM3: -: if: Triangular + * ``2`` - ASAS(NL) file. Creates the file ``Fname``.asnl. - BRK8: TET4: -: if: Tetrahedral: BRK6: -: if: Prism + Notes + ----- - QUS4: TBC3: -: if: Triangular + .. _ANSTOASAS_notes: - QUM8: TRM6: -: if: Triangular + This command creates an input file for the Ansys Asas Finite Element Analysis System from the model + and loads currently in the database, based on the currently selected set of elements. Most common + structural element types are written, as well as sections (or real constants), materials, boundary + conditions and loads, and solution and load step options. - BR20: TE10: -: if: Tetrahedral: : BR15: -: if: Prism + **Data Written** - QUS4: TBC3: -: if: Triangular + The following data is written: - QUM4: TRM3: -: if: Triangular + * :ref:`Solution control options ` - QUM8: TRM6: -: if: Triangular + * Nodes - BRK8: TET4: -: if: Tetrahedral: BRK6: -: if: Prism + * :ref:`Elements ` - BR20: TE10: -: if: Tetrahedral: BR15: -: if: Prism + * :ref:`Material data ` - TCBM: -: if: ASAS(L): STF4: -: if: ASAS(NL) + * :ref:`Geometry data ` - Documentation for this legacy element type appears in the Feature - Archive. + * :ref:`Section data ` - Material Data + * Mechanical APDL element components (ASAS sets) - Linear isotropic material conversion is supported for ASAS and - ASAS(NL). + * :ref:`Boundary conditions ` - Geometry Data - """ - command = "ANSTOASAS,%s,%s" % (str(fname), str(key)) - return self.run(command, **kwargs) + * :ref:`Loads ` - def anstoaqwa( - self, - fname="", - vertaxis="", - gc="", - rho="", - hwl="", - diffkey="", - symxkey="", - symykey="", - **kwargs, - ): - """Creates an AQWA-LINE input file from the current ANSYS model. + * Added mass (via ``MASS21`` element) - APDL Command: ANSTOAQWA + Details are provided in the following sections. - Parameters - ---------- - fname - AQWA file name. Defaults to Jobname. + Not all data is written. You must verify the completeness and accuracy of the data. Only loading at + the current step is transferred; hence, no load step history is captured. - vertaxis - Axis in the vertical direction: + .. _solconop: - Y (or 2) - Global Y axis. + **Solution Control Options** - Z (or 3) - Global Z axis (default). + The ASAS project name is defined as "Ansys". - gc - Gravitational acceleration. Defaults to 9.81. + The solution control options are converted as follows: - rho - Density of water. Defaults to 1025.0. + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - hwl - Waterline height in model coordinates. Defaults to 0.0. + For conversion to ASAS(NL), the large displacement option is set based on :ref:`nlgeom`, final load + solution time is set based on :ref:`time`, and sub-step times are set based on :ref:`deltim` or + :ref:`nsubst` (assuming constant step size). - diffkey - Diffracting model key: + .. _elemdat: - 0 - Create a non-diffracting AQWA model. + **Element Data** - 1 - Create a diffracting AQWA model (default). + If you intend to use the data only with AQWA-WAVE, only the elements that form the wetted surface + are required. Selecting these elements before invoking the :ref:`anstoasas` command will improve + performance. In order for AQWA-WAVE to identify the direction of the wave loading, all elements must + be defined by nodes in a clockwise direction. For further information, refer to the AQWA-WAVE + manual. - symxkey - Key indicating if model is symmetric about the global XZ plane: + The element types are converted as follows: - 0 - No symmetry about XZ plane (default). + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - 1 - Use symmetry about XZ plane. Only include (or select) half the model. + .. _anstoasas_fn1: - symykey - Key indicating if model is symmetric about the global YZ plane: + Documentation for this archived element type appears in the `Feature Archive + `_. - 0 - No symmetry about YZ plane (default). + .. _matdat: - 1 - Use symmetry about YZ plane. Only include (or select) half the model. + **Material Data** - Notes - ----- - This command creates the input file Fname.aqwa for the ANSYS Aqwa - Multi-Body Hydrodynamics System for diffraction analysis in AQWA-LINE - from the model currently in the database, based on the currently - selected set of elements. The selected set must only include the hull - envelope; no internal structure should be selected. - - There should be a line of nodes defined at the waterline. Only those - elements that are entirely below the waterline will be specified as - diffracting. If there are no waterline nodes, there will be no - diffracting elements at the waterline, which will severely reduce the - accuracy of the diffraction analysis. - - The translator maps PLANE42, SHELL41, SHELL63, and SHELL181 elements to - PANELs, and maps PIPE16 and PIPE59 elements to TUBEs. It does not - recognize any other element types. Any material or geometric properties - can be used for the shell elements, as AQWA does not need any - properties at all and the command does not use them. All the shell - elements below the water must have their normals pointing outward. - - TUBE elements in AQWA have material density, outside diameter, wall - thickness, added mass, and drag coefficients, so appropriate properties - should be used in the ANSYS model. PIPE59 elements can have added mass - and damping coefficients; these will be written to the file. The ANSYS - program uses the inertia coefficient CM, whereas AQWA uses the added - mass coefficient CA, where CM = (1 + CA). This correction is made - automatically. - - In AQWA the vertical axis is always the Z-axis. The command can convert - a model built with either the Y or Z-axis vertical, but the X-axis must - be horizontal and should preferably be along the fore/aft axis of the - vessel. If the structure is symmetric and you wish to use the symmetry - options, you must only select one half or one quarter of the model, as - appropriate. If you model a complete vessel and specify X symmetry, the - AQWA model will contain two sets of coincident elements. - - If you are working from a model created for a structural analysis, it - will probably be necessary to remesh the model as the structural mesh - is most likely finer than needed for a diffraction analysis. - - If you enter this command interactively (with the GUI active) and no - data is provided for the command options, you will be prompted for - their values. + Linear isotropic material conversion is supported for ASAS and ASAS(NL). - You must verify the completeness and accuracy of the data written. - """ - command = "ANSTOAQWA,%s,%s,%s,%s,%s,%s,%s,%s" % ( - str(fname), - str(vertaxis), - str(gc), - str(rho), - str(hwl), - str(diffkey), - str(symxkey), - str(symykey), - ) - return self.run(command, **kwargs) + .. _geomdat: - def assign(self, ident="", fname="", ext="", lgkey="", **kwargs): - """Reassigns a file name to an ANSYS file identifier. + **Geometry Data** - APDL Command: /ASSIGN + The following ASAS element geometry data is supported: - Parameters - ---------- - ident - ANSYS file name identifier. Valid identifiers are: CMS, EMAT, - EROT, ESAV, FULL, LN07, LN09, LN11, LN20, LN21, LN22, LN25, LN31, - LN32, MODE, OSAV, RDSP, RFRQ, RMG, RST, RSTP, RTH, SELD, and SSCR. - See File Management and Files for file descriptions. If blank, - list currently reassigned files. - - fname - 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. - - ext - Filename extension (eight-character maximum). + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - lgkey - Key to specify local or global file name control for the specified - file identifier in a distributed-memory parallel processing - (Distributed ANSYS) run. For more information on local and global - files, see File Handling Conventions in the Parallel Processing - Guide. + For all beam elements, the third node position must be explicitly defined. If the position is not + defined, the program generates an error code (-1) in the output file. - BOTH - Reassign the file name for both the local and global files (default). + .. _sectdat: - LOCAL - Reassign the file name for only the local files. + **Section Data** - GLOBAL - Reassign the file name for only the global file. + No user sections are generated if AQWA-WAVE data is selected. - Notes - ----- - The reassignment of file names is valid only if it is done before the - file is used. All file reassignments are retained (not cleared) even - if the database is cleared [/CLEAR] or the Jobname is changed - [/FILNAME]. Assigned files may be overwritten. If file name arguments - (Fname, Ext, --) are blank, the default ANSYS assignment is restored. - Use SEOPT for SUB files and SEEXP for DSUB files. + The following sections are converted for ASAS and ASAS(NL): - This command is valid only at the Begin Level. + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + .. _boundcon: + + **Boundary Conditions** + + The following boundary conditions are converted for ASAS and ASAS(NL): + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + .. _loadsasas: - This command also checks to ensure that the path/file is valid and can - be written by the user. If it is not valid, an error message will be - returned. Ensure that the directory exists prior to using /ASSIGN - command. + **Loads** + + No user loading is generated if AQWA-WAVE data is selected. However, a load case (number 1000) is + automatically defined to identify the wetted surface of the elements for use by AQWA-WAVE based on + the normal surface loads applied to the solid or shell 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. + The following loads are converted for ASAS: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. """ - return self.run(f"/ASSIGN,{ident},{fname},{ext},,{lgkey}", **kwargs) + command = f"ANSTOASAS,{fname},{key}" + return self.run(command, **kwargs) - def slashclog(self, fname="", ext="", **kwargs): - """APDL Command: /CLOG + def assign( + self, ident: str = "", fname: str = "", ext: str = "", lgkey: str = "", **kwargs + ): + r"""Reassigns a file name to a Mechanical APDL file identifier. - Copies the session log file to a named file. + Mechanical APDL Command: `/ASSIGN `_ Parameters ---------- - fname - File name and directory path to which the log file is to be copied - (248 characters maximum, including directory). If you do not - specify a directory path, it will default to your working directory - and you can use all 248 characters for the file name. - - ext + ident : str + Mechanical APDL file name identifier. Valid identifiers are: CMS, EMAT, EROT, ESAV, FULL, LN07, + LN09, LN11, LN20, LN21, LN22, LN25, LN31, LN32, MODE, OSAV, RDSP, RFRQ, RMG, RST, RSTP, RTH, + SELD, and SSCR. See `File Management and Files + `_ + + 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. + + ext : str Filename extension (eight-character maximum). + lgkey : str + Key to specify local or global file name control for the specified file identifier in a distributed- + memory parallel processing run. For more information on local and global files, see File Handling Conventions in the `Parallel Processing Guide `_. + + * ``BOTH`` - Reassign the file name for both the local and global files (default). + + * ``LOCAL`` - Reassign the file name for only the local files. + + * ``GLOBAL`` - Reassign the file name for only the global file. + Notes ----- - This command is valid in any processor, but only during an interactive - run. + + .. _s-ASSIGN_notes: + + The reassignment of file names is valid only if it is done before the file is used. All file + reassignments are retained (not cleared) even if the database is cleared ( ``/CLEAR`` ) or the + Jobname is changed ( :ref:`filname` ). Assigned files may be overwritten. If file name arguments + (``Fname``, ``Ext``, ``--``) are blank, the default Mechanical APDL assignment is restored. Use + :ref:`seopt` for SUB files + and :ref:`seexp` for DSUB files. + + This command is valid only at the Begin level. + + This command also checks to ensure that the path/file is valid and can be written by the user. If it + is not valid, an error message will be returned. Ensure that the directory exists prior to using + :ref:`assign` command. """ - command = "/CLOG,%s,%s" % (str(fname), str(ext)) + command = f"/ASSIGN,{ident},{fname},{ext},,{lgkey}" return self.run(command, **kwargs) - def copy(self, fname1="", ext1="", fname2="", ext2="", distkey="", **kwargs): - """Copies a file. + def copy( + self, + fname1: str = "", + ext1: str = "", + fname2: str = "", + ext2: str = "", + distkey: str = "", + **kwargs, + ): + r"""Copies a file. - APDL Command: /COPY + Mechanical APDL Command: `/COPY `_ Parameters ---------- - fname1 - File name to be copied and its directory path (248 - characters maximum for both file name and directory). If - you do not specify a directory path, it will default to - your working directory and you can use all 248 characters - for the file name. - - ext1 - Filename extension (eight-character maximum). + fname1 : str + File name to be copied and its directory path (248 characters maximum for both file name and + directory). If you do not specify a directory path, it will default to your working directory + and you can use all 248 characters for the file name. - fname2 - File name to be created and its directory path (248 - characters maximum for both file name and directory). If - you do not specify a directory path, it will default to - your working directory and you can use all 248 characters - for the file name. + The file name defaults to the current :file:`Jobname`. - ext2 + ext1 : str Filename extension (eight-character maximum). - distkey - Key that specifies whether the copy operation is performed - on all processes in distributed parallel mode (Distributed - ANSYS): + fname2 : str + File name to be created and its directory path (248 characters maximum for both file name and + directory). If you do not specify a directory path, it will default to your working directory + and you can use all 248 characters for the file name. + + ``Fname2`` defaults to ``Fname1``. - 0 (OFF or NO) - The program performs the copy operation - only on the master process (default). + ext2 : str + Filename extension (eight-character maximum). ``Ext2`` defaults to ``Ext1``. - 1 (ON or YES) - The program performs the copy operation - locally on each process. + distkey : str + Key that specifies which copy operation is performed on all processes in distributed-memory parallel + mode : - 2 or BOTH - The program performs the copy operation for - Fname.Ext on the master process and for FnameN.Ext on all - processes. + * ``0 (OFF or NO)`` - The program performs the copy operation only on the master process (default). + + * ``1 (ON or YES)`` - The program performs the copy operation locally on each process. + + * ``2 or BOTH`` - The program performs the copy operation for ``Fname``. ``Ext`` on the master + process and for ``FnameN``. ``Ext`` on all processes. Notes ----- - The original file is untouched. Ex: /COPY,A,,,B copies file A - to B in the same directory. /COPY,A,DAT,,,INP copies the file - A.DAT to A.INP. See the Operations Guide for details. ANSYS - binary and ASCII files can be copied. - - In distributed parallel mode (Distributed ANSYS), only the - master process will copy Fname1.Ext1 to Fname2.Ext2 by - default. However, when DistKey is set to 1 (or ON or YES), the - command is executed by all processes. In this case, Fname1 and - Fname2 will automatically have the process rank appended to - them. This means Fname1N.Ext1 will be copied to Fname2N.Ext2 - by all processes, where N is the Distributed ANSYS process - rank. For more information see Differences in General - Behavior in the Parallel Processing Guide. + + .. _s-COPY_notes: + + The original file is untouched. Ex: :ref:`copy`,A,,,B copies file A to B in the same directory. + :ref:`copy`,A,DAT,,,INP copies the file :file:`A.DAT` to :file:`A.INP`. See the `Operations Guide + `_ for + details. Mechanical APDL binary and ASCII files can be copied. + + In distributed-memory parallel (DMP) mode, only the master process will copy ``Fname1``. ``Ext1`` to + ``Fname2``. ``Ext2`` by default. However, when ``DistKey`` is set to 1 (or ON, or YES) or 2 (or + BOTH), the command is executed by all processes. In this case, ``Fname1`` and ``Fname2`` will + automatically have the process rank appended to them. This means ``Fname1N``. ``Ext1`` will be + copied to ``Fname2N``. ``Ext2`` by all processes, where ``N`` is the DMP process rank. For more + information see in the `Parallel Processing Guide + `_. """ command = f"/COPY,{fname1},{ext1},,{fname2},{ext2},,{distkey}" return self.run(command, **kwargs) def fclean(self, **kwargs): - """Deletes all local files in all processors in a distributed parallel processing run. + r"""Deletes all local files in all processors in a distributed parallel processing run. - APDL Command: /FCLEAN - - Deletes all local files (``.rst``, ``.esav``, ``.emat``, ``.mode``, ``.mlv``, - ``.seld``, ``.dsub``, ``.ist``, ``.full``, ``.rdsp``, ``.rfrq``, ``.rnnn``, - ``.resf``, ``.stat``, ``.modesym``, ``.osave``, ``.erot``, ``.log``) - in all processors in a distributed parallel processing run. - - .. warning:: Because ``/FCLEAN`` deletes all local files, it should only be issued if you are sure that - none of those files are needed in downstream analyses. Deleting files that are necessary for - the next substep, load step, or analysis will prevent continuation of the run. + Mechanical APDL Command: `/FCLEAN `_ Notes ----- - Issue ``/FCLEAN`` to delete all local files having the current Jobname (``/FILNAME``) and save - disk space in a distributed parallel processing run. Like other file deletion commands, deletion happens - immediately upon issuing this command. Different than other file deletion commands, it enables the - convenience of deleting all ``Jobname.*`` local files without having to issue separate commands specifying - each file type + .. _s-FCLEAN_notes: - This command is valid only at the Begin Level. + Issue :ref:`fclean` to delete all local files having the current ``Jobname`` ( :ref:`filname` ) and + save disk space in a distributed parallel processing run. Like other file deletion commands, + deletion happens immediately upon issuing this command. Different than other file deletion commands, + it enables the convenience of deleting all :file:`Jobname.\*` local files without having to issue + separate commands specifying each file type. + + All :file:`.log` files except the master ( :file:`Jobname0.log` ) are deleted. + + .. warning:: + + Because /FCLEAN deletes all local files, it should only be issued if you are sure that none of + those files are needed in any downstream analyses. Deleting files that are necessary for + subsequent substeps, load steps, commands, or analyses will prevent continuation of the run. For + example, since the local files are combined into global files when you issue FINISH in the + solution processor, issuing /FCLEAN before FINISH in /SOLU will result in a program crash. """ - return self.run("/FCLEAN", **kwargs) + command = "/FCLEAN" + return self.run(command, **kwargs) + + def fcomp(self, ident: str = "", level: int | str = "", **kwargs): + r"""Specifies file-compression options. - def fcomp(self, ident="", level="", **kwargs): - """Specifies file compression level. + Mechanical APDL Command: `/FCOMP `_ Parameters ---------- - ident - ANSYS file name identifier. Input the label RST to compress - the following results files: .RST, .RSTP, .RTH, and .RMG. See - File Management and Files for file descriptions. + ident : str + Mechanical APDL file identifier. There is no default. Valid labels are: + + * ``RST`` - Results file. + + * ``DB`` - Database file. - level - Compression level. Valid input values are 0 (no compression - - default) to 5 (maximum compression). + * ``RNNN`` - Restart file. + + * ``OSAV`` - File created during a nonlinear analysis that contains a copy of :file:`ESAV` file from + the last converged substep. + + level : int or str + Compression level: + + * ``SPARSE`` - Use a sparsification scheme for file compression (default). + + * ``0`` - No file compression occurs. + + * ``n`` - A zlib-based file compression occurs using level number ``n``, which ranges from 1 to 5. Notes ----- - Command Default - File compression is not performed. - Specifies file compression for results files (.RST, .RSTP, .RTH, - and .RMG files). Records are compressed as they are written and - uncompressed as they are read (for example, by the SET command). + .. _s-FCOMP_notes: + + Specifies file compression options for results files ( :file:`.rst`, :file:`.rstp`, :file:`.rth`, + and :file:`.rmg` files), database files ( :file:`.db` and :file:`.rdb` ), certain restart files ( + :file:`.Rnnn` ), and the :file:`.osav` file created during a nonlinear analysis. (See `Program- + Generated Files + `_ + :ref:`set` command or the :ref:`resume` command). - See File Compression in the Basic Analysis Guide for more details. + For results files compressed using the sparsification scheme ( ``LEVEL`` = SPARSE, which is the + default), use the ``*XPL`` command to uncompress the file. For third party tools that need to read + the results file, use the method described in `Accessing Mechanical APDL Binary Files + `_ + + See in the `Basic Analysis Guide + `_ for more + details. + + This command is valid only at the Begin Level. """ - return self.run(f"/FCOMP,{ident},{level}", **kwargs) + command = f"/FCOMP,{ident},{level}" + return self.run(command, **kwargs) - def lgwrite(self, fname="", ext="", kedit="", remove_grpc_extra=True, **kwargs): - """Writes the database command log to a file. + def lgwrite(self, fname: str = "", ext: str = "", kedit: str = "", **kwargs): + r"""Writes the database command log to a file. - APDL Command: LGWRITE + Mechanical APDL Command: `LGWRITE `_ Parameters ---------- - fname : str, optional - 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 Jobname. + 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, optional - Filename extension (eight-character maximum). + ext : str + Filename extension (eight-character maximum). The extension defaults to LGW if ``Fname`` and + ``Ext`` are blank. - kedit : str, optional + kedit : str Flag to suppress nonessential commands: - * ``"NONE"`` - Do not suppress any commands (default). - * ``"COMMENT"`` - Write nonessential commands as comments (starting with !). - * ``"REMOVE"`` - Do not write nonessential commands or comments. + * ``NONE`` - Do not suppress any commands (default). + + * ``COMMENT`` - Write nonessential commands as comments (starting with !). - remove_grpc_extra : bool, default: True - Remove gRPC related content (like ``/OUT,anstmp``). This will be - ignored when MAPDL is not in gRPC mode. + * ``REMOVE`` - Do not write nonessential commands or comments. Notes ----- - Writes the database command log to a named file. The database - command log contains all commands that were used to create the - current database. These commands are recorded in the database - as they are issued, and saved in the database file (File.DB) - whenever the database is saved. The LGWRITE command extracts - these commands from the database and writes them to a file. - Nonessential commands (for listing, graphics displays, help, - etc.) can be excluded from the file by using the Kedit field. - The file resulting from LGWRITE can be used as command input - to the program. This command is most useful if the session - log file (File.LOG), which is normally saved during an - interactive session, has been lost or corrupted. - - This command is valid in any processor. - - Examples - -------- - Output the database command log to the local directory. - - >>> import os - >>> mapdl.prep7() - >>> mapdl.k(1, 0, 0, 0, mute=True) - >>> mapdl.k(2, 2, 0, 0) - >>> filename = os.path.join(os.getcwd(), 'log.txt') - >>> mapdl.lgwrite(filename, kedit='REMOVE') - Print the output from the log file. + .. _LGWRITE_notes: - >>> with open(filename) as fid: - ... lines = fid.readlines() - >>> print(''.join(lines)) - /BATCH - /PREP7, - K,1,0,0,0 - K,2,2,0,0 + Writes the database command log to a named file. The database command log contains all commands that + were used to create the current database. These commands are recorded in the database as they are + issued, and saved in the database file ( :file:`File.DB` ) whenever the database is saved. The + :ref:`lgwrite` command extracts these commands from the database and writes them to a file. + Nonessential commands (for listing, graphics displays, help, etc.) can be excluded from the file by + using the ``Kedit`` field. The file resulting from :ref:`lgwrite` can be used as command input to + the program. This command is most useful if the session log file ( :file:`File.LOG` ), which is + normally saved during an interactive session, has been lost or corrupted. + This command is valid in any processor. """ - return self.run(f"LGWRITE,{fname},{ext},,{kedit}") + command = f"LGWRITE,{fname},{ext},,{kedit}" + return self.run(command, **kwargs) - def starlist(self, fname="", ext="", **kwargs): - """Displays the contents of an external, coded file. + def slashclog(self, fname: str = "", ext: str = "", **kwargs): + r"""Copies the session log file to a named file. - APDL Command: ``*LIST`` + Mechanical APDL Command: `/CLOG `_ Parameters ---------- - fname - 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. - - ext + fname : str + File name and directory path to which the log file is to be copied (248 characters maximum, + including directory). If you do not specify a directory path, it will default to your working + directory and you can use all 248 characters for the file name. + + ext : str Filename extension (eight-character maximum). Notes ----- - Displays the contents of an external, coded file. The file to be - listed cannot be in use (open) at the time (except for the error - file, File.ERR, which may be displayed with ``*LIST,ERR``). - This command is valid in any processor. + .. _s-CLOG_notes: + + This command is valid in any processor, but only during an interactive run. """ - command = f"*LIST,{fname},{ext}" + command = f"/CLOG,{fname},{ext}" return self.run(command, **kwargs) - def rename(self, fname1="", ext1="", fname2="", ext2="", distkey="", **kwargs): - """Renames a file. + def slashdelete(self, fname: str = "", ext: str = "", distkey: str = "", **kwargs): + r"""Deletes a file. - APDL Command: /RENAME + Mechanical APDL Command: `/DELETE `_ Parameters ---------- - fname1 - The file to be renamed. You can also include an optional - directory path as part of the specified file name; if not, - the default file location is the working directory. + 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 the current + :file:`Jobname`. - ext1 + ext : str Filename extension (eight-character maximum). - fname2 - The new name for the file. You can also include an - optional directory path as part of the new file name; if - not, the default is the working directory. A maximum of - 248 characters is allowed for the file name (or combined - file name and directory path, if both are specified). - - ext2 - Filename extension (eight-character maximum). + distkey : str + Key that specifies which file deletion action is performed on all processes in distributed-memory + parallel mode: - distkey - Key that specifies whether the rename operation is - performed on all processes in distributed parallel mode - (Distributed ANSYS): + * ``0 (OFF or NO)`` - The program performs the file deletion only on the master process (default). - 1 (ON or YES) - The program performs the rename operation - locally on each process. + * ``1 (ON or YES)`` - The program performs the file deletion locally on each process. - 0 (OFF or NO) - The program performs the rename operation - only on the master process (default). + * ``2 or BOTH`` - The program performs file deletion for ``Fname``. ``Ext`` on the master process + and for ``FnameN``. ``Ext`` on all processes. Notes ----- - Renames a file. Ex: /RENAME,A,,,B renames file A to B in the - same directory. /RENAME,A,DAT,,,INP renames file A.DAT to - A.INP. On all systems, this command will overwrite any - existing file named B. See the Operations Guide for - details. Only ANSYS binary files should be renamed. Use /SYS - and system renaming commands for other files. - - In distributed parallel mode (Distributed ANSYS), only the - master process will rename Fname1.Ext1 to Fname2.Ext2 by - default. However, when DistKey is set to 1 (or ON or YES), the - command is executed by all processes. In this case, Fname1 and - Fname2 will automatically have the process rank appended to - them. This means Fname1N.Ext1 will be renamed to Fname2N.Ext2 - by all processes, where N is the Distributed ANSYS process - rank. For more information see Differences in General Behavior - in the Parallel Processing Guide. - - Renaming across system partitions may be internally done by a - copy and delete operation on some systems. - - This command is valid only at the Begin Level. + In distributed-memory parallel (DMP) mode, only the master process will delete ``Fname``. ``Ext`` by + default. However, when ``DistKey`` is set to 1 (or ON, or YES) or 2 (or BOTH), the command is + executed by all processes. In this case, ``Fname`` will automatically have the process rank appended + to it. This means ``FnameN``. ``Ext`` will be deleted by all processes, where ``N`` is the DMP + process rank. For more information see in the `Parallel Processing Guide + `_. """ - return self.run( - f"/RENAME,{fname1},{ext1},,{fname2},{ext2},,{distkey}", **kwargs - ) + command = f"/DELETE,{fname},{ext},,{distkey}" + return self.run(command, **kwargs) - def slashfdele(self, ident="", stat="", **kwargs): - """Deletes a binary file after it is used. + def slashfdele(self, ident: str = "", stat: str = "", **kwargs): + r"""Deletes a binary file after it is used. - APDL Command: /FDELE + Mechanical APDL Command: `/FDELE `_ Parameters ---------- - ident - ANSYS file name identifier. Valid identifiers are: EMAT, ESAV, - FULL, SUB, MODE, DSUB, USUB, OSAV, and SELD. See the Basic - Analysis Guide for file descriptions. + ident : str + Mechanical APDL file name identifier. Valid identifiers are: EMAT, ESAV, FULL, SUB, MODE, DSUB, + USUB, OSAV, and SELD. See the `Basic Analysis Guide + `_ for file + descriptions. - stat + stat : str Keep or delete key: - KEEP - Keep this file. + * ``KEEP`` - Keep this file. - DELE - Delete (or do not write, if not necessary) this file. + * ``DELE`` - Delete (or do not write, if not necessary) this file. Notes ----- - Deletes as soon as possible (or prevents writing) a binary file created - by the ANSYS program to save space. + + .. _s-FDELE_notes: + + Deletes as soon as possible (or prevents writing) a binary file created by Mechanical APDL to save + space. .. warning:: - Deleting files that are necessary for the next substep, - load step, or analysis will prevent continuation of the - run. - This command is valid only at the Begin Level. + Deleting files that are necessary for the next substep, load step, or analysis will prevent + continuation of the run. + + This command is valid only at the Begin level. """ command = f"/FDELE,{ident},{stat}" return self.run(command, **kwargs) - def slashdelete(self, fname="", ext="", distkey="", **kwargs): - """Deletes a file. + def slashrename( + self, + fname1: str = "", + ext1: str = "", + fname2: str = "", + ext2: str = "", + distkey: str = "", + **kwargs, + ): + r"""Renames a file. - APDL Command: /DELETE + Mechanical APDL Command: `/RENAME `_ Parameters ---------- - fname - 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. - - ext + fname1 : str + The file to be renamed. You can also include an optional directory path as part of the specified + file name; if not, the default file location is the working directory. + + File name defaults to the current :file:`Jobname`. + + ext1 : str Filename extension (eight-character maximum). - distkey - Key that specifies whether the file deletion is performed - on all processes in distributed parallel mode (Distributed - ANSYS): + fname2 : str + The new name for the file. You can also include an optional directory path as part of the new + file name; if not, the default is the working directory. A maximum of 248 characters is allowed + for the file name (or combined file name and directory path, if both are specified). + + ``Fname2`` defaults to ``Fname1``. + + ext2 : str + Filename extension (eight-character maximum). ``Ext2`` defaults to ``Ext1``. - 1 (ON or YES) - The program performs the file deletion - locally on each process. + distkey : str + Key that specifies which rename operation is performed on all processes in distributed-memory + parallel mode: - 0 (OFF or NO) - The program performs the file deletion - only on the master process (default). + * ``0 (OFF or NO)`` - The program performs the rename operation only on the master process + (default). + + * ``1 (ON or YES)`` - The program performs the rename operation locally on each process. + + * ``2 or BOTH`` - The program performs the rename operation for ``Fname``. ``Ext`` on the master + process and for ``FnameN``. ``Ext`` on all processes. Notes ----- - In distributed parallel mode (Distributed ANSYS), only the - master process will delete Fname.Ext by default. However, when - DistKey is set to 1 (or ON or YES), the command is executed by - all processes. In this case, Fname will automatically have the - process rank appended to it. This means FnameN.Ext will be - deleted by all processes, where N is the Distributed ANSYS - process rank. For more information see Differences in General - Behavior in the Parallel Processing Guide. + + .. _s-RENAME_notes: + + Renames a file. Ex: :ref:`slashrename`,A,,,B renames file A to B in the same directory. + :ref:`slashrename`,A,DAT,,,INP renames file A.DAT to A.INP. On all systems, this command will + overwrite any existing file named B. See the `Operations Guide + `_ for details. Only + Mechanical APDL binary files should + be renamed. Use :ref:`sys` and system renaming commands for other files. + + In distributed-memory parallel (DMP) mode, only the master process will rename ``Fname1``. ``Ext1`` + to ``Fname2``. ``Ext2`` by default. However, when ``DistKey`` is set to 1 (or ON, or YES) or 2 (or + BOTH), the command is executed by all processes. In this case, ``Fname1`` and ``Fname2`` will + automatically have the process rank appended to them. This means ``Fname1N``. ``Ext1`` will be + renamed to ``Fname2N``. ``Ext2`` by all processes, where ``N`` is the DMP process rank. For more + information see in the `Parallel Processing Guide + `_. + + Renaming across system partitions may be internally done by a copy and delete operation on some + systems. + + This command is valid only at the Begin level. """ - return self.run(f"/DELETE,{fname},{ext},,{distkey}", **kwargs) + command = f"/RENAME,{fname1},{ext1},,{fname2},{ext2},,{distkey}" + return self.run(command, **kwargs) + + def starlist(self, fname: str = "", ext: str = "", **kwargs): + r"""Displays the contents of an external, coded file. + + Mechanical APDL Command: `\*LIST `_ + + 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. + + ext : str + Filename extension (eight-character maximum). + + Notes + ----- + + .. _a-LIST_notes: + + Displays the contents of an external, coded file. The file to be listed cannot be in use (open) at + the time (except for the error file, :file:`Jobname.err` None, which may be displayed with + :ref:`starlist`,ERR). + + Use caution when you are listing active Mechanical APDL files via the List> Files> Other and File> + List> + Other menu paths. File I/O buffer and system configurations can result in incomplete listings unless + the files are closed. + + This command is valid in any processor. + """ + command = f"*LIST,{fname},{ext}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/session/list_controls.py b/src/ansys/mapdl/core/_commands/session/list_controls.py index ef12613c01..eadc78821c 100644 --- a/src/ansys/mapdl/core/_commands/session/list_controls.py +++ b/src/ansys/mapdl/core/_commands/session/list_controls.py @@ -22,101 +22,129 @@ class ListControls: - def com(self, comment="", **kwargs): - """Places a comment in the output. - APDL Command: /COM + def com(self, comment: str = "", **kwargs): + r"""Places a comment in the output. + + Mechanical APDL Command: `/COM `_ Parameters ---------- - comment + comment : str Comment string, up to 75 characters. Notes ----- - The output from this command consists of the comment string. This - command is similar to C*** except that the comment produced by C*** is - more easily identified in the output. Parameter substitution within the - comment occurs for every valid expression delimited by percent (%) - signs. Enclosing such an expression in single quotes prevents parameter - substitution. - - Another way to include a comment is to precede it with a ! character - (on the same line). The ! may be placed anywhere on the line, and any - input following it is ignored as a comment. No output is produced by - such a comment, but the comment line is included on the log file. This - is a convenient way to annotate the log file. + + .. _s-COM_notes: + + The output from this command consists of the comment string. This command is similar to ``C***`` + except that the comment produced by ``C***`` is more easily identified in the output. Parameter + substitution within the comment occurs for every valid expression delimited by percent (%) signs. + Enclosing such an expression in single quotes prevents parameter substitution. + + Another way to include a comment is to precede it with a ! character (on the same line). The ! may + be placed anywhere on the line, and any input following it is ignored as a comment. No output is + produced by such a comment, but the comment line is included on the log file. This is a convenient + way to annotate the log file. This command is valid anywhere. """ - command = f"/COM, {comment}" + command = f"/COM,{comment}" return self.run(command, **kwargs) def golist(self, **kwargs): - """Reactivates the suppressed data input listing. + r"""Reactivates the suppressed data input listing. - APDL Command: /GOLIST + Mechanical APDL Command: `/GOLIST `_ Notes ----- - Reactivates printout of the data input listing suppressed with /NOLIST. - This command is valid in any processor, but only within a batch run - [/BATCH]. + .. _s-GOLIST_notes: + + Reactivates printout of the data input listing suppressed with :ref:`nolist`. + + This command is valid in any processor, but only within a batch run ( ``/BATCH`` ). """ - command = "/GOLIST," + command = "/GOLIST" return self.run(command, **kwargs) def gopr(self, **kwargs): - """Reactivates suppressed printout. + r"""Reactivates suppressed printout. - APDL Command: /GOPR + Mechanical APDL Command: `/GOPR `_ Notes ----- - Reactivates printout suppressed with the /NOPR command. The /GO - command has the same function except that it does not produce a command - response from the program. + + .. _s-GOPR_notes: + + Reactivates printout suppressed with the :ref:`nopr` command. The :ref:`slashgo` command has the + same function except that it does not produce a command response from the program. This command is valid in any processor. """ - command = "/GOPR," + command = "/GOPR" return self.run(command, **kwargs) def nolist(self, **kwargs): - """Suppresses the data input listing. + r"""Suppresses the data input listing. - APDL Command: /NOLIST + Mechanical APDL Command: `/NOLIST `_ Notes ----- - Printout is suppressed until a /GOLIST command is read or the end of - the listing is encountered. - This command is valid in any processor, but only within a batch run - [/BATCH]. + .. _s-NOLIST_notes: + + Printout is suppressed until a :ref:`golist` command is read or the end of the listing is + encountered. + + This command is valid in any processor, but only within a batch run ( ``/BATCH`` ). """ - command = "/NOLIST," + command = "/NOLIST" return self.run(command, **kwargs) def nopr(self, **kwargs): - """Suppresses the expanded interpreted input data listing. + r"""Suppresses the expanded interpreted input data listing. - APDL Command: /NOPR + Mechanical APDL Command: `/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 /GOPR or /GO command is read. - Use of /NOPR is not recommended when the graphical user interface (GUI) - is active. The GUI sometimes issues "hidden" /NOPR and /GOPR command - sequences, which will countermand user-issued /NOPR commands, thus - making the use of /NOPR in the GUI environment unpredictable. + .. _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. + """ + command = "/NOPR" + return self.run(command, **kwargs) + + def slashgo(self, **kwargs): + r"""Reactivates suppressed printout. + + Mechanical APDL Command: `/GO `_ + + Notes + ----- + + .. _s-GO_notes: + + Reactivates printout suppressed with the :ref:`nopr` command without producing any output. The + :ref:`gopr` command has the same function except that it also produces a command response from the + program. This command is valid in any processor. """ - command = "/NOPR," + command = "/GO" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/session/processor_entry.py b/src/ansys/mapdl/core/_commands/session/processor_entry.py index 4a86f311e8..7614c6b2e1 100644 --- a/src/ansys/mapdl/core/_commands/session/processor_entry.py +++ b/src/ansys/mapdl/core/_commands/session/processor_entry.py @@ -20,173 +20,123 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. -"""These SESSION commands are used to enter and exit the various -processors in the program. -""" - class ProcessorEntry: - def aux2(self, **kwargs): - """Enters the binary file dumping processor. - - APDL Command: /AUX2 - - Notes - ----- - Enters the binary file dumping processor (ANSYS auxiliary processor - AUX2). This processor is used to dump the contents of certain ANSYS - binary files for visual examination. - This command is valid only at the Begin Level. - """ - command = "/AUX2," - return self.run(command, **kwargs) - - def aux3(self, **kwargs): - """Enters the results file editing processor. + def finish(self, **kwargs): + r"""Exits normally from a processor. - APDL Command: /AUX3 + Mechanical APDL Command: `FINISH `_ Notes ----- - Enters the results file editing processor (ANSYS auxiliary processor - AUX3). This processor is used to edit ANSYS results files. - This command is valid only at the Begin Level. - """ - command = "/AUX3," - return self.run(command, **kwargs) + .. _FINISH_notes: - def aux12(self, **kwargs): - """Enters the radiation processor. + This command exits any of the Mechanical APDL processors. - APDL Command: /AUX12 + When exiting the Mechanical APDL processors, data remains intact in the database, but the database + is not + automatically written to a file. (Issue :ref:`save` to write the database to a file.) - Notes - ----- - Enters the radiation processor (ANSYS auxiliary processor AUX12). This - processor supports the Radiation Matrix and the Radiosity Solver - methods. - - This command is valid only at the Begin Level. - """ - command = "/AUX12," - return self.run(command, **kwargs) + If exiting POST1 or POST26: - def aux15(self, **kwargs): - """Enters the IGES file transfer processor. + * POST1: Data in the database remains intact (including the POST1 element table data, the path table + data, the fatigue table data, and the load case pointers). - APDL Command: /AUX15 + * POST26: Data in the database remains intact, except that POST26 variables are erased and + specification commands (such as :ref:`file`, :ref:`prtime`, and :ref:`nprint` ) are reset. Issue + :ref:`quit` to exit the processor and bypass these exceptions. - Notes - ----- - Enters the IGES file transfer processor (ANSYS auxiliary processor - AUX15), used to read an IGES data file into the ANSYS program. + See :ref:`quit` for an alternate processor exit command. - This command is valid only at the Begin Level. + This command is valid in any processor. This command is not valid at the Begin level. """ - command = "/AUX15," + command = "FINISH" return self.run(command, **kwargs) - def finish(self, **kwargs): - """Exits normally from a processor. + def post1(self, **kwargs): + r"""Enters the database results postprocessor. - APDL Command: FINISH + Mechanical APDL Command: `/POST1 `_ Notes ----- - Exits any of the ANSYS processors or the DISPLAY program. For the - ANSYS processors, data will remain intact in the database but the - database is not automatically written to a file (use the SAVE command - to write the database to a file). See also the /QUIT command for an - alternate processor exit command. If exiting POST1, POST26, or OPT, - see additional notes below. - - POST1: Data in the database will remain intact, including the POST1 - element table data, the path table data, the fatigue table data, and - the load case pointers. - - POST26: Data in the database will remain intact, except that POST26 - variables are erased and specification commands (such as FILE, PRTIME, - NPRINT, etc.) are reset. Use the /QUIT command to exit the processor - and bypass these exceptions. - - This command is valid in any processor. This command is not valid at - the Begin level. - """ - command = "FINISH," - return self.run(command, **kwargs) - def post1(self, **kwargs): - """Enters the database results postprocessor. + .. _s-POST1_notes: - APDL Command: /POST1 - - Notes - ----- - Enters the general database results postprocessor (POST1). All load - symbols (/PBC, /PSF, or /PBF) are automatically turned off with this - command. + Enters the general database results postprocessor (POST1). All load symbols ( :ref:`pbc`, + :ref:`psf`, or :ref:`pbf` ) are automatically turned off with this command. This command is valid only at the Begin Level. """ - command = "/POST1," + command = "/POST1" return self.run(command, **kwargs) def post26(self, **kwargs): - """Enters the time-history results postprocessor. + r"""Enters the time-history results postprocessor. - APDL Command: /POST26 + Mechanical APDL Command: `/POST26 `_ Notes ----- + + .. _s-POST26_notes: + Enters the time-history results postprocessor (POST26). This command is valid only at the Begin Level. """ - command = "/POST26," + command = "/POST26" return self.run(command, **kwargs) def prep7(self, **kwargs): - """Enters the model creation preprocessor. + r"""Enters the model creation preprocessor. - APDL Command: /PREP7 + Mechanical APDL Command: `/PREP7 `_ Notes ----- + + .. _s-PREP7_notes: + Enters the general input data preprocessor (PREP7). This command is valid only at the Begin Level. """ - command = "/PREP7," + command = "/PREP7" return self.run(command, **kwargs) def quit(self, **kwargs): - """Exits a processor. + r"""Exits a processor. - APDL Command: /QUIT + Mechanical APDL Command: `/QUIT `_ Notes ----- - This is an alternative to the FINISH command. If any cleanup or file - writing is normally done by the FINISH command, it is bypassed if the - /QUIT command is used instead. A new processor may be entered after - this command. See the /EXIT command to terminate the run. - This command is valid in any processor. This command is not valid at - the Begin level. + .. _s-QUIT_notes: + + This is an alternative to the :ref:`finish` command. If any cleanup or file writing is normally done + by the :ref:`finish` command, it is bypassed if the :ref:`quit` command is used instead. A new + processor may be entered after this command. See the ``/EXIT`` command to terminate the run. + + This command is valid in any processor. This command is not valid at the Begin level. """ - command = "/QUIT," + command = "/QUIT" return self.run(command, **kwargs) def slashsolu(self, **kwargs): - """Enters the solution processor. + r"""Enters the solution processor. - APDL Command: /SOLU + Mechanical APDL Command: `/SOLU `_ Notes ----- + + .. _s-SOLU_notes: + This command is valid only at the Begin Level. """ - command = "/SOLU," + command = "/SOLU" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/session/run_controls.py b/src/ansys/mapdl/core/_commands/session/run_controls.py index 0c23e18886..18742071bc 100644 --- a/src/ansys/mapdl/core/_commands/session/run_controls.py +++ b/src/ansys/mapdl/core/_commands/session/run_controls.py @@ -20,137 +20,160 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. -"""These SESSION commands control the overall characteristics of the -session, including the jobname, Graphical User Interface behavior, and -file switching. -""" from ansys.mapdl.core.errors import MapdlRuntimeError class RunControls: - def config(self, lab="", value="", **kwargs): - """Assigns values to ANSYS configuration parameters. - APDL Command: /CONFIG + def config(self, lab: str = "", val: str = "", **kwargs): + r"""Assigns values to Mechanical APDL configuration parameters. + + Mechanical APDL Command: `/CONFIG `_ Parameters ---------- - lab + lab : str Configuration parameter to be changed: - NORSTGM - Option to write or not write geometry data to - the results file. VALUE is either 0 (write - geometry data) or 1 (do not write geometry - data). Useful when complex analyses will create - abnormally large files. Default is 0. + * ``NORSTGM`` - Option to write or not write geometry data to the results file: + + * When ``VAL`` = 0, write geometry data (default). + * When ``VAL`` = 1, does not write geometry data. + + Useful when complex analyses are likely to create abnormally large files. + + * ``NBUF`` - The number of buffers ( ``VAL`` = 1 to 32) per file in the solver. Default: ``VAL`` = + 4. + + * ``LOCFL`` - File open and close actions: + + * When ``VAL`` = 0, global (default). + * When ``VAL`` = 1, local. + + Applies to :file:`File.EROT`, :file:`File.ESAV`, and :file:`FileEMAT`. + + Typically used for large problems where locally closed files may be deleted earlier in the run via + :ref:`slashfdele`. + + * ``SZBIO`` - Record size ( ``VAL`` = 1024 to 4194304) of binary files (in integer words). + + Default: ``VAL`` = 16384 (system-dependent). + + * ``FSPLIT`` - Defines split points for binary files. ``VAL`` is the file split point in megawords. + + Default: ``VAL`` = Maximum file size for the system. + + * ``MXND`` - Maximum number of nodes. + + Default: ``VAL`` = 100 at first encounter. + + Dynamically expanded by doubling, even at first encounter, when the maximum is exceeded. + + * ``MXEL`` - Maximum number of elements. Default and expansion as for MXND. + + * ``MXKP`` - Maximum number of keypoints. Default and expansion as for MXND. - NBUF - VALUE is the number of buffers (1 to 32) per file - in the solver. Defaults to 4. + * ``MXLS`` - Maximum number of lines. Default and expansion as for MXND. - LOCFL - File open and close actions. For VALUE use: 0 for - global (default); 1 for local. Applicable to - File.EROT, File.ESAV, and File.EMAT. Typically - used for large problems where locally closed files - may be deleted earlier in the run with the /FDELE - command. + * ``MXAR`` - Maximum number of areas. Default and expansion as for MXND. - SZBIO - VALUE is the record size (1024 to 4194304) of - binary files (in integer words). Defaults to - 16384 (system dependent). + * ``MXVL`` - Maximum number of volumes. Default and expansion as for MXND. - ORDER - Automatic reordering scheme. For VALUE use: 0 for - WSORT,ALL; 1 for WAVES; 2 for both WSORT,ALL and - WAVES (default). + * ``MXRL`` - Maximum number of sets of real constants (element attributes). Default and expansion as + for MXND. - FSPLIT - Defines split points for binary files. VALUE is - the file split point in megawords and defaults to - the maximum file size for the system. + * ``MXCP`` - Maximum number of sets of coupled degrees of freedom. Default and expansion as for + MXND. - MXND - Maximum number of nodes. If not specified, defaults - to 100 at first encounter. Dynamically expanded by - doubling, even at first encounter, when maximum is - exceeded. + * ``MXCE`` - Maximum number of constraint equations. Default and expansion as for MXND. - MXEL - Maximum number of elements. Default and expansion as for MXND. + * ``NOELDB`` - Option to write or not write results into the database after a solution. - MXKP - Maximum number of keypoints. Default and expansion as for MXND. + * When ``VAL`` = 0 (default), writes results into the database. + * When ``VAL`` = 1, does not write results into the database. + * ``NUMLV`` - Maximum number of load vectors written on :file:`Jobname.MODE` file when ``MSUPkey`` = + YES on the :ref:`mxpand` command. - MXLS - Maximum number of lines. Default and expansion as for MXND. + Default: ``VAL`` = 1000 at first encounter. - MXAR - Maximum number of areas. Default and expansion as for MXND. + When the maximum is exceeded, the value is not expanded. - MXVL - Maximum number of volumes. Default and expansion as for MXND. + The NUMLV option is not supported for fast load vector generation ( ``FastLV`` = ON on the + :ref:`modcont` command). - MXRL - Maximum number of sets of real constants (element - attributes). Default and expansion as for MXND. + * ``NUMSUBLV`` - Maximum number of load vectors written on :file:`Jobname.SUB` file in + substructure/CMS generation pass. - MXCP - Maximum number of sets of coupled degrees of - freedom. Default and expansion as for MXND. + Default: ``VAL`` = 31 at first encounter. - MXCE - Maximum number of constraint equations. Default - and expansion as for MXND. + When the maximum is exceeded, the value is not expanded. - NOELDB - Option to write or not write results into the - database after a solution. When VALUE = 0 - (default), write results into the database. When - VALUE = 1, do not write results into the - database. + * ``GRW_NBUF`` - Option to automatically grow the number of file buffers for most binary files ( :file:`.ESAV`, + :file:`.EMAT`, :file:`.FULL`, and so on), with the exception of the results file and files written + by the sparse and PCG equation solvers (for example, :file:`.DSPxxxx` and :file:`.PCn` ). - DYNA_DBL - Option to invoke the double precision version - of the explicit dynamics solver LS-DYNA. When - VALUE = 0 (default), the single precision - version is used. When VALUE = 1, the double - precision version is used. + * When ``VAL`` = -1, the number of file buffers does not grow automatically for any file. + * When ``VAL`` = 0 (default), the number of file buffers may or may not grow automatically. The + logic is program-controlled. + * When ``VAL`` = 1, the number of file buffers automatically grows for most binary files to reduce + the amount of I/O. This option may require a significantly greater amount of memory than the + default behavior ( ``VAL`` = 0). + * ``MEBA_LIC`` - Option to control automatic checkout of a Mechanical batch license during solution when the + capability is not enabled, useful for PrepPost sessions: - STAT - Displays current values set by the /CONFIG command. + * When ``VAL`` = 0 (default), check out a license automatically when needed. + * When ``VAL`` = 1, bypass automatic license checkout. + * ``STAT`` - Displays current values set by the :ref:`config` command. - value - Value (an integer number) assigned to the configuration parameter. + val : str + Value (an integer number) assigned to the specified configuration parameter. Notes ----- - All configuration parameters have initial defaults, which in most cases - do not need to be changed. Where a specially configured version of the - ANSYS program is desired, the parameters may be changed with this - command. Issue /CONFIG,STAT to display current values. Changes must - be defined before the parameter is required. These changes (and - others) may also be incorporated into the config162.ans file which is - read upon execution of the program (see The Configuration File in the - Basic Analysis Guide). If the same configuration parameter appears in - both the configuration file and this command, this command overrides. - - Distributed ANSYS uses the default FSPLIT value, and forces NOELDB = 1 - and NORSTGM = 0 for all results files. The FSPLIT, NOELDB, and NORSTGM - options cannot be changed when using Distributed ANSYS. - - The /CONFIG command is not valid for the ANSYS Multiphysics 1, 2, or 3 - products. - - The ANSYS Multi-field solver (MFS and MFX) does not support - /CONFIG,NOELDB,1. The ANSYS Multi-field solver needs the updated ANSYS - database. + + .. _s-CONFIG_notes: + + All configuration parameters have initial defaults, which in most cases do not need to be changed. + Where a specially configured version of the Mechanical APDL program is desired, the parameters can + be + changed with this command. + + Issue :ref:`config`,STAT to display current values. + + Define changes before the parameter is required. + + These changes (and others) may also be incorporated into the :file:`config.ans` file, read in upon + execution of the program. (See `The Configuration File + `_ + in the `Basic Analysis Guide + `_.) If the same + configuration parameter appears in both the configuration file and + this command, this command overrides. + + Distributed-memory parallel DMP solutions use the default FSPLIT value and force NOELDB = 1 for all + results files. You cannot change the FSPLIT and NOELDB options for a DMP solution. """ - command = "/CONFIG,%s,%s" % (str(lab), str(value)) + command = f"/CONFIG,{lab},{val}" return self.run(command, **kwargs) - def cwd(self, dirpath="", **kwargs): - """Changes the current working directory. + def cwd(self, dirpath: str = "", **kwargs): + r"""Changes the current working directory. - ``dirpath`` must not contain any singular quotations/apostrophes. - These are not supported in APDL. - - APDL Command: /CWD + Mechanical APDL Command: `/CWD `_ Parameters ---------- - dirpath + dirpath : str The full path name of the new working directory. Notes ----- - After issuing the /CWD command, all new files opened with no default - directory specified (via the FILE, /COPY, or RESUME commands, for - example) default to the new ``dirpath`` directory. + + .. _s-CWD_notes: + + After issuing the /CWD command, all new files opened with no default directory specified (via the + :ref:`file`, :ref:`copy`, or :ref:`resume` commands, for example) default to the new ``DIRPATH`` + directory. Examples -------- @@ -162,7 +185,6 @@ def cwd(self, dirpath="", **kwargs): MAPDL on Linux example: >>> mapdl.cwd("/tmp/") - """ dirpath = str(dirpath) if not (dirpath.startswith("'") and dirpath.endswith("'")) and "'" in dirpath: @@ -171,519 +193,932 @@ def cwd(self, dirpath="", **kwargs): ) return self.run(f"/CWD,'{dirpath}'", **kwargs) - def filname(self, fname="", key="", **kwargs): - """Changes the Jobname for the analysis. + def filname(self, fname: str = "", key: str = "", **kwargs): + r"""Changes the Jobname for the analysis. - APDL Command: /FILNAME + Mechanical APDL Command: `/FILNAME `_ Parameters ---------- - fname - Name (32 characters maximum) to be used as the Jobname. Defaults - to the initial Jobname as specified on the ANSYS execution command, - or to file if none specified. + fname : str + Name (32 characters maximum) to be used as the :file:`Jobname`. Defaults to the initial + :file:`Jobname` as specified on the Mechanical APDL execution command, or to :file:`file` if + none specified. - key - Specify whether to use the existing log, error, lock, page, and - output files (.LOG, .ERR, .LOCK, .PAGE and .OUT) or start new - files. + key : str + Specify whether to use the existing log, error, lock, page, and output files ( :file:`.LOG`, :file:`.ERR`, :file:`.LOCK`, :file:`.PAGE` and :file:`.OUT` ) or + start new files. - 0, OFF - Continue using current log, error, lock, page, and output files. + * ``0, OFF`` - Continue using current log, error, lock, page, and output files. - 1, ON - Start new log, error, lock, page, and output files - (old log and error files are closed and saved, but - old lock, page, and output files are - deleted). Existing log and error files are - appended. + * ``1, ON`` - Start new log, error, lock, page, and output files (old log and error files are closed + and saved, but old lock, page, and output files are deleted). Existing log and error files are + appended. Notes ----- - All subsequently created files will be named with this Jobname if Key = - 0. Use Key = 1 to start new log, error, lock, page, and output files. - The previous Jobname is typically defined on the ANSYS program - execution line (see the Operations Guide). This command is useful when - different groups of files created throughout the run are to have - different names. For example, the command may be used before each - substructure pass to avoid overwriting files or having to rename each - file individually. + + .. _s-FILNAME_notes: + + All subsequently created files will be named with this :file:`Jobname` if ``Key`` = 0. Use ``Key`` = + 1 to start new log, error, lock, page, and output files. The previous :file:`Jobname` is typically + defined on the Mechanical APDL program execution line. (See the `Operations Guide + `_. + + This command is useful when different groups of files created throughout the run are to have + different names. For example, the command may be used before each substructure pass to avoid + overwriting files or having to rename each file individually. This command is valid only at the Begin level. """ - command = "/FILNAME,%s,%s" % (str(fname), str(key)) + command = f"/FILNAME,{fname},{key}" return self.run(command, **kwargs) - def input(self, fname="", ext="", dir="", line="", log="", **kwargs): - """Switches the input file for the commands that follow. + def input( + self, + fname: str = "", + ext: str = "", + dir_: str = "", + line: str = "", + log: int | str = "", + **kwargs, + ): + r"""Switches the input file for the commands that follow. - APDL Command: /INPUT + Mechanical APDL Command: `/INPUT `_ Parameters ---------- - fname - 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. - - ext + 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 the current + :file:`Jobname` if ``Ext`` is specified. + + ext : str Filename extension (eight-character maximum). - dir - Directory path (64 characters maximum). Defaults to current - directory. + dir_ : str + Directory path (64 characters maximum). Defaults to current directory. - line - A value indicating either a line number in the file or a user- - defined label in the file from which to begin reading the - input file. + line : str + A value indicating either a line number in the file or a user-defined label in the file from which + to begin reading the input file. - (blank), 0, or 1 - Begins reading from the top of the file (default). + * ``(blank), 0, or 1`` - Begins reading from the top of the file (default). - LINE_NUMBER - Begins reading from the specified line number in the file. + * ``LINE_NUMBER`` - Begins reading from the specified line number in the file. - :label - Begins reading from the first line beginning with the - matching user-defined label :label (beginning with a - colon (:), 8 characters maximum). + * ``label`` - Begins reading from the first line beginning with the matching user-defined label : + ``label`` (beginning with a colon (:), 8 characters maximum). - log - Indicates whether secondary input from this command should be - recorded in the command log (File.LOG) and the database log: + log : int or str + Indicates whether secondary input from this command should be recorded in the command log ( :file:`File.LOG` ) and the database log: - 0 - Record only the /INPUT command on the log (default). + * ``0`` - Record only the :ref:`input` command on the log (default). - 1 - Record commands in the specified secondary file as they are executed. + * ``1`` - Record commands in the specified secondary file as they are executed. Notes ----- - Switches the input file for the next commands. Commands are read - from this file until an end-of-file 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``, ``*USE``, ``*ULIB``, and the "Unknown - Command" Macro have less nesting available because each of these - operations also uses a level of file switching. For an - interactive run, a /INPUT,TERM switches to the terminal for the - next input. A /EOF read from the terminal then switches back to - the previous file. A /INPUT (with a blank second field) switches - back to the primary input file. - - Setting LOG = 1 on /INPUT causes all commands read from the - specified file to be recorded in the command log (File.LOG) and - the internal database command log [LGWRITE]. This option is - recommended if the log file will be used later . The LOG = 1 - option is only valid when the /INPUT occurs in the primary input - file. Using LOG = 1 on a nested /INPUT or on a /INPUT within a - do-loop will have no effect (i.e., commands in the secondary input + + .. _s-INPUT_notes: + + Switches the input file for the next commands. Commands are read from this file until an end-of-file + 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 + available because each of these operations also uses a level of file switching. For an interactive + run, a :ref:`input`,TERM switches to the terminal for the next input. A ``/EOF`` read from the + terminal then switches back to the previous file. A :ref:`input` (with a blank second field) + switches back to the primary input file. + + Setting ``LOG`` = 1 on :ref:`input` causes all commands read from the specified file to be recorded + in the command log ( :file:`File.LOG` ) and the internal database command log ( :ref:`lgwrite` ). + This option is recommended if the log file will be used later. The ``LOG`` = 1 option is only valid + when the :ref:`input` occurs in the primary input file. Using ``LOG`` = 1 on a nested :ref:`input` + or on a :ref:`input` within a do-loop will have no effect (that is, commands in the secondary input file are not written to the command log). - The Dir option is optional as the directory path can be included - directly in Fname. + The ``Dir`` option is optional as the directory path can be included directly in ``Fname``. - Examples - -------- - Run an input file relative to the location of MAPDL. + This command is valid in any processor. + """ + command = f"/INPUT,{fname},{ext},{dir_},{line},{log}" + return self.run(command, **kwargs) + + def keyw(self, **kwargs): + r"""Sets a keyword used by the GUI for context filtering (GUI). - >>> mapdl.input('my_input_file.inp') + Mechanical APDL Command: `KEYW `_ + Notes + ----- + + .. _KEYW_notes: + + This is a program-generated command and is not intended for your use. It is included here in the + documentation because it might appear in the log file ( :file:`Jobname.log` ). When using log files, + or portions of log files, as input, any included :ref:`keyw` commands may be left as is, or removed, + without consequence. """ - return self.run(f"/INPUT,{fname},{ext},{dir},{line},{log}", **kwargs) + command = "KEYW" + return self.run(command, **kwargs) - def keyw(self, keyword="", key="", **kwargs): - """Sets a keyword used by the GUI for context filtering (GUI). + def memm(self, lab: str = "", kywrd: str = "", **kwargs): + r"""Allows the current session to keep allocated memory - APDL Command: KEYW + Mechanical APDL Command: `MEMM `_ Parameters ---------- - keyword - A keyword which, when set to either true or false, changes the - behavior of the GUI. + lab : str + When ``Lab`` = KEEP, the memory manager's ability to acquire and keep memory is controlled by + ``Kywrd`` + + kywrd : str + Turns the memory "keep" mode on or off + + * ``ON`` - Keep any memory allocated during the analysis. - key - Keyword switch: + * ``OFF`` - Use memory dynamically and free it up to other users after use (default). - 0 - Sets the keyword to "false." + Notes + ----- + + .. _MEMM_notes: + + You can use the :ref:`memm` command to ensure that memory intensive operations will always have the + same memory available when the operations occur intermittently. Normally, if a large amount of + memory is allocated for a specific operation, it will be returned to the system once the operation + is finished. This option always maintains the highest level used during the analysis until the + analysis is finished. + + The :ref:`memm` command does not affect the value you specify with the -m switch. When you allocate + memory with the -m switch, that amount will always be available. However, if dynamic memory + allocation in excess of the -m value occurs, you can use the :ref:`memm` command to ensure that + amount is retained until the end of your analysis. + """ + command = f"MEMM,{lab},{kywrd}" + return self.run(command, **kwargs) + + def menu(self, key: str = "", **kwargs): + r"""Activates the Graphical User Interface (GUI). - 1 - Sets the keyword to "true." + Mechanical APDL Command: `/MENU `_ + + Parameters + ---------- + key : str + Activation key: + + * ``ON`` - Activates the menu system (device dependent). Notes ----- - Defines a keyword used by the GUI for context filtering. This is a - command generated by the GUI and may appear in the log file - (Jobname.LOG) if the GUI is used. This command is usually not typed in - directly in an ANSYS session. + + .. _s-MENU_notes: + + Activates the Graphical User Interface (GUI). + + .. warning:: + + if you include the /MENU,ON command in your start.ans, it should be the lastcommand in the file. + Any commands after /MENU,ON may be ignored. (It is not necessary to include the /SHOW and + /MENU,ON commands in start.ansif you will be using the launcher to enter the Mechanical APDL program.) This command is valid in any processor. """ - command = "KEYW,%s,%s" % (str(keyword), str(key)) + command = f"/MENU,{key}" return self.run(command, **kwargs) - def memm(self, lab="", kywrd="", **kwargs): - """Allows the current session to keep allocated memory. + def mstart(self, label: str = "", key: str = "", **kwargs): + r"""Controls the initial GUI components. - APDL Command: MEMM + Mechanical APDL Command: `/MSTART `_ Parameters ---------- - lab - When Lab = KEEP, the memory manager's ability to acquire and keep - memory is controlled by Kywrd + label : str + Label identifying the GUI component: - kywrd - Turns the memory "keep" mode on or off + * ``ZOOM`` - `Pan,Zoom, Rotate + `_ + dialog box, off by default. + + * ``WORK`` - `OffsetWorking Plane + `_ + dialog box, off by default. + + * ``WPSET`` - `WorkingPlane Settings + `_ + dialog box, off by default. + + * ``ABBR`` - `EditToolbar/Abbreviations + `_ + dialog box, off by default. + + * ``PARM`` - `ScalarParameters + `_ + dialog box, off by default. + + * ``SELE`` - Select Entities dialog box, off by default. + + * ``ANNO`` - Annotation dialog box, off by default. + + * ``HARD`` - Hard Copy dialog box, off by default. - ON - Keep any memory allocated during the analysis. + * ``UTIL`` - Activates the pre-6.1 (UIDL) GUI (off by default). - OFF - Use memory dynamically and free it up to other users after use (default). + key : str + Switch value: + + * ``OFF or 0`` - Component does not appear when GUI is initialized. + + * ``ON or 1`` - Component appears when GUI is initialized. Notes ----- - You can use the MEMM command to ensure that memory intensive operations - will always have the same memory available when the operations occur - intermittently. Normally, if a large amount of memory is allocated for - a specific operation, it will be returned to the system once the - operation is finished. This option always maintains the highest level - used during the analysis until the analysis is finished. - - The MEMM command does not affect the value you specify with the -m - switch. When you allocate memory with the -m switch, that amount will - always be available. However, if dynamic memory allocation in excess of - the-m value occurs, you can use the MEMM command to ensure that amount - is retained until the end of your analysis. + + .. _s-MSTART_notes: + + Controls which components appear when the Graphical User Interface (GUI) is initially brought up. + This command is valid only before the GUI is brought up ( :ref:`menu`,ON) and is intended to be used + in the :file:`start.ans` file. It only affects how the GUI is initialized ; you can always bring up + or close any component once you are in the GUI. + + This command is valid only at the Begin Level. """ - command = "MEMM,%s,%s" % (str(lab), str(kywrd)) + command = f"/MSTART,{label},{key}" return self.run(command, **kwargs) - def nerr(self, nmerr="", nmabt="", abort="", ifkey="", num="", **kwargs): - """Limits the number of warning and error messages displayed. + def nerr( + self, + nmerr: str = "", + nmabt: str = "", + ifkey: str = "", + num: int | str = "", + **kwargs, + ): + r"""Limits the number of warning and error messages displayed. - APDL Command: /NERR + Mechanical APDL Command: `/NERR `_ Parameters ---------- - nmerr - Maximum number of warning and error messages displayed per - command. Defaults to 5 for interactive runs with the GUI - turned on, 20 for interactive runs with the GUI turned - off, 200 for batch runs. If NMERR is negative, the - absolute value of NMERR is used as the maximum number of - warning and error messages written to the error file - (file.ERR) per command, as well as the maximum number of - messages displayed per command. - - nmabt - Maximum number of warning and error messages allowed per - command before run aborts (must be greater than zero). - Maximum value is 99,999,999. Defaults to 10,000. - - abort - Abort level key. Set to 0 for default abort behavior, -1 - to never abort, and -2 to abort after ``nmabt`` errors. - Altering the abort level key is not recommended, but can - be helpful for avoiding an abort within /BATCH mode but - using ``pyansys`` interactively. - - ifkey - Specifies whether or not to abort if an error occurs during a - /INPUT operation: - - 0 or OFF - Do not abort. This option is the default. - - 1 or ON - Abort. - - num - The number of invalid command warnings before a stop warning will - be issued: - - 0 - Disables the stop warning/error function. - - n - An integer value representing the number of warnings that will be encountered - before prompting the user to stop (default = 5). The first - error encountered will ALWAYS result in a prompt. + nmerr : str + Maximum number of warning and error messages displayed per command. Defaults to 5 for + interactive runs with the GUI turned on, 20 for interactive runs with the GUI turned off, 200 + for batch runs. If ``NMERR`` is negative, the absolute value of ``NMERR`` is used as the maximum + number of warning and error messages written to the error file ( :file:`Jobname.ERR` ) per + command, as well as the maximum number of messages displayed per command. + + nmabt : str + Maximum number of warning and error messages allowed per command before run aborts (must be + greater than zero). Maximum value is 99,999,999. Defaults to 10,000. + + ifkey : str + Specifies whether or not to abort if an error occurs during a :ref:`input` operation: + + * ``0, or OFF`` - Do not abort. This option is the default. + + * ``1, or ON`` - Abort. + + num : int or str + The number of invalid command warnings before a stop warning will be issued: + + * ``0`` - Disables the stop warning/error function. + + * ``n`` - An integer value representing the number of warnings that will be encountered before + prompting the user to stop (default = 5). The first error encountered will ALWAYS result in a + prompt. + + Invalid command warnings and error tracking are mutually exclusive. Notes ----- - Limits the number of warning and error messages displayed for any one - command in an interactive run. - Warning and error messages continue to be written to Jobname.ERR - regardless of these limits (unless NMERR is negative). + .. _s-NERR_notes: - Issue this command with NUM = n to specify the number of "invalid - command" warnings to be encountered before the user is prompted to - stop. You can then continue or abort the run. If you choose to abort - the run, the log file can be saved so that any of the processing up to - that point can be appended to an input that rectifies the condition. A - batch run always aborts on the first error. Issue /NERR,STAT to list - current settings. + Limits the number of warning and error messages displayed for any one command in an interactive run. - Issue /NERR,DEFA to reset values to initial defaults. + Warning and error messages continue to be written to :file:`Jobname.ERR` regardless of these limits, + unless ``NMERR`` is negative. There is no way to totally suppress writing of warning and error + messages to the error file. - An IFKEY value of 1 or ON causes the ANSYS program to abort immediately - upon encountering an error during a file /INPUT operation. However, use - of this option may cause the following conditions to occur: + Issue this command with ``NUM`` = ``n`` to specify the number of invalid command warnings to be + encountered before the user is prompted to stop. You can then continue or abort the run. If you + choose to abort the run, the log file can be saved so that any of the processing up to that point + can be appended to an input that rectifies the condition. A batch run always aborts on the first + error. Issue :ref:`nerr`,STAT to list current settings. - The /INPUT command may abort if issued for a log file (jobname.log). + Issue :ref:`nerr`,DEFA to reset values to initial defaults. - Some macros may abort. + An ``IFKEY`` value of 1 or ON causes Mechanical APDL to terminate immediately upon encountering an + error during a file :ref:`input` operation. However, use of this option may cause the following + conditions to occur: - A CAD connection may fail after reading only a small portion of a CAD - model. + * The :ref:`input` command may abort if issued for a log file ( :file:`jobname.log` ). + + * Some macros may terminate. + + * A CAD connection may fail after reading only a small portion of a CAD model. The command is valid in any processor. """ - command = "/NERR,%s,%s,%s,%s,%s" % ( - str(nmerr), - str(nmabt), - str(abort), - str(ifkey), - str(num), - ) + command = f"/NERR,{nmerr},{nmabt},,{ifkey},{num}" + return self.run(command, **kwargs) + + def output(self, fname: str = "", ext: str = "", loc: str = "", **kwargs): + r"""Redirects text output to a file or to the screen. + + Mechanical APDL Command: `/OUTPUT `_ + + Parameters + ---------- + fname : str + Filename and directory path (248 character maximum, including directory) to which text output + will be redirected (defaults to :file:`Jobname` if ``Ext`` is specified). For interactive runs, + ``Fname`` = TERM (or blank) redirects output to the screen. For batch runs, ``Fname`` = blank + (with all remaining command arguments blank) redirects output to the default system output file. + + ext : str + Filename extension (eight-character maximum). + + loc : str + Location within a file to which output will be written: + + * ``(blank)`` - Output is written starting at the top of the file (default). + + * ``APPEND`` - Output is appended to the existing file. + + Notes + ----- + + .. _s-OUTPUT_notes: + + Text output includes responses to every command and GUI function, notes, warnings, errors, and other + informational messages. Upon execution of :ref:`output`, ``Fname``, ``Ext``, ``...``, all subsequent + text output is redirected to the file :file:`Fname.Ext`. To redirect output back to the default + location, issue :ref:`output` (no arguments). + + When using the GUI, output from list operations ( :ref:`nlist`, :ref:`dlist`, etc.) is always sent + to a list window regardless of the :ref:`output` setting. The output can then be saved on a file or + copied to the :ref:`output` location using the File menu in the list window. + + This command is valid in any processor. + """ + command = f"/OUTPUT,{fname},{ext},,{loc}" return self.run(command, **kwargs) def pause(self, **kwargs): - """Temporarily releases the current product license. + r"""Temporarily releases the current product license. - APDL Command: PAUSE + Mechanical APDL Command: `PAUSE `_ Notes ----- - The PAUSE command temporarily releases (or pauses) the current product - license so that another application can use it. - This application consumes a license as soon as you launch it, and - retains that license until it is finished. If you launch the product - interactively, the license is retained until you either close the - application or issue a PAUSE command via the command line. + .. _PAUSE_notes: + + The :ref:`pause` command temporarily releases (or pauses) the current product license so that + another application can use it. - No other operation (other than SAVE or /EXIT) is possible in the - current application while use of the product license is paused. + This application consumes a license as soon as you launch it, and retains that license until it is + finished. If you launch the product interactively, the license is retained until you either close + the application or issue a :ref:`pause` command via the command line. - When the second application has finished and releases the license, - issue an UNPAUSE command via the command line to restore use of the - license to the current application. + No other operation (other than :ref:`save` or ``/EXIT`` ) is possible in the current application + while use of the product license is paused. - For more information, see the ANSYS, Inc. Licensing Guide. + When the second application has finished and releases the license, issue an :ref:`unpause` command + via the command line to restore use of the license to the current application. + + For more information, see the `Ansys Licensing Guide + `_. """ - command = "PAUSE," + command = "PAUSE" return self.run(command, **kwargs) - def slashstatus(self, lab="", **kwargs): - """Lists the status of items for the run. + def slashstatus(self, lab: str = "", **kwargs): + r"""Lists the status of items for the run. - APDL Command: /STATUS + Mechanical APDL Command: `/STATUS `_ Parameters ---------- - lab + lab : str Items to list status for: - ALL - List all below (default). + * ``ALL`` - List all below (default). - TITLE - List only titles, Jobname, and revision number. + * ``TITLE`` - List only titles, :file:`Jobname`, and revision number. - UNITS - List only units. + * ``UNITS`` - List only units. - MEM - List only memory data statistics. + * ``MEM`` - List only memory data statistics. - DB - List only database statistics + * ``DB`` - List only database statistics - CONFIG - List only configuration parameters. + * ``CONFIG`` - List only configuration parameters. - GLOBAL - Provides a global status summary. + * ``GLOBAL`` - Provides a global status summary. - SOLU - Provides a solution status summary. + * ``SOLU`` - Provides a solution status summary. - PROD - Provides a product summary. + * ``PROD`` - Provides a product summary. Notes ----- - Displays various items active for the run (such as the ANSYS revision - number, Jobname, titles, units, configuration parameters, database - statistics, etc.). + + .. _s-STATUS_notes: + + Displays various items active for the run (such as the Mechanical APDL revision number, + :file:`Jobname`, + titles, units, configuration parameters, database statistics, etc.). This command is valid in any processor. """ - return self.run(f"/STATUS,{lab}", **kwargs) + command = f"/STATUS,{lab}" + return self.run(command, **kwargs) - def starstatus( + def syp( self, - par="", - imin="", - imax="", - jmin="", - jmax="", - kmin="", - kmax="", - lmin="", - lmax="", - mmin="", - mmax="", - kpri="", + string: str = "", + arg1: str = "", + arg2: str = "", + arg3: str = "", + arg4: str = "", + arg5: str = "", + arg6: str = "", + arg7: str = "", + arg8: str = "", **kwargs, ): - """Lists the current parameters and abbreviations. + r"""Passes a command string and arguments to the operating system. - APDL Command: ``*STATUS`` + Mechanical APDL Command: `/SYP `_ Parameters ---------- - par - Specifies the parameter or sets of parameters listed. For array - parameters, use IMIN, IMAX, etc. to specify ranges. Use ``*DIM`` to - define array parameters. Use ``*VEDIT`` to review array parameters - interactively. Use ``*VWRITE`` to print array values in a formatted - output. If Par is blank, list all scalar parameter values, array - parameter dimensions, and abbreviations. If ARGX, list the active - set of local macro parameters (ARG1 to ARG9 and AR10 to AR99) - [``*USE``]. + string : str + Command string (cannot include commas). See also the :ref:`sys` command. + + arg1 : str + Arguments to be appended to the command string, separated by blanks, commas, or other delimiter + characters (see the `Operations Guide + `_). The + arguments may be numbers, parameters, or parametric expressions. + + arg2 : str + Arguments to be appended to the command string, separated by blanks, commas, or other delimiter + characters (see the `Operations Guide + `_). The + arguments may be numbers, parameters, or parametric expressions. + + arg3 : str + Arguments to be appended to the command string, separated by blanks, commas, or other delimiter + characters (see the `Operations Guide + `_). The + arguments may be numbers, parameters, or parametric expressions. + + arg4 : str + Arguments to be appended to the command string, separated by blanks, commas, or other delimiter + characters (see the `Operations Guide + `_). The + arguments may be numbers, parameters, or parametric expressions. + + arg5 : str + Arguments to be appended to the command string, separated by blanks, commas, or other delimiter + characters (see the `Operations Guide + `_). The + arguments may be numbers, parameters, or parametric expressions. + + arg6 : str + Arguments to be appended to the command string, separated by blanks, commas, or other delimiter + characters (see the `Operations Guide + `_). The + arguments may be numbers, parameters, or parametric expressions. + + arg7 : str + Arguments to be appended to the command string, separated by blanks, commas, or other delimiter + characters (see the `Operations Guide + `_). The + arguments may be numbers, parameters, or parametric expressions. + + arg8 : str + Arguments to be appended to the command string, separated by blanks, commas, or other delimiter + characters (see the `Operations Guide + `_). The + arguments may be numbers, parameters, or parametric expressions. - Lists all parameters (except local macro parameters and those with names beginning or ending with an underbar) and toolbar abbreviations. - Lists only parameters with names beginning with an underbar (_). These are - ANSYS internal parameters. + Notes + ----- - Lists only parameters with names ending with an underbar (_). A good APDL programming convention is to ensure that all parameters created by your system programmer are named with a trailing underbar. - Lists all toolbar abbreviations. + .. _s-SYP_notes: - Lists all parameters (except local macro parameters and those with names beginning or ending with an underbar). - Lists all APDL Math parameters, including vectors, matrices, and linear - solvers. + Passes a command string to the operating system for execution, along with arguments to be appended + to the command string. See the `Operations Guide + `_ for details. + Mechanical APDL may not be aware of your specific user + environment. For example, on Linux this command may not recognize aliases, depending on the hardware + platform and user environment. - Lists only the parameter specified. PARNAME cannot be a local macro parameter name. - Lists all local macro parameter values (ARG1- AR99) that are non-zero or non- - blank. + This command is valid in any processor. + """ + command = ( + f"/SYP,{string},{arg1},{arg2},{arg3},{arg4},{arg5},{arg6},{arg7},{arg8}" + ) + return self.run(command, **kwargs) - imin, imax, jmin, jmax, kmin, kmax, lmin, lmax, mmin, mmax - Range of array elements to display (in terms of the dimensions - (row, column, plane, book, and shelf). Minimum values default to - 1. Maximum values default to the maximum dimension values. Zero - may be input for IMIN, JMIN, and KMIN to display the index numbers. - See ``*TAXIS`` command to list index numbers of 4- and 5-D tables. + def sys(self, string: str = "", **kwargs): + r"""Passes a command string to the operating system. - kpri - Use this field to list your primary variable labels (X, Y, Z, TIME, - etc.). + Mechanical APDL Command: `/SYS `_ - List the labels (default). YES, Y, or ON are also valid entries. - Do not list the labels. NO, N, or OFF are also valid entries. + Parameters + ---------- + string : str + Command string, up to 639 characters (including blanks, commas, etc.). The specified string is + passed verbatim to the operating system, that is, no parameter substitution is performed. Notes ----- - You cannot obtain the value for a single local parameter (e.g., - ``*STATUS,ARG2``). You can only request all local parameters simultaneously - using ``*STATUS,ARGX``. + + .. _s-SYS_notes: + + Passes a command string to the operating system for execution (see the `Operations Guide + `_). Typical strings + are system commands such as list, copy, rename, etc. Control returns to Mechanical APDL after the + system + procedure is completed. Mechanical APDL may not be aware of your specific user environment. For + example, on + Linux this command may not recognize aliases, depending on the hardware platform and user + environment. This command is valid in any processor. """ - command = "*STATUS,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s" % ( - str(par), - str(imin), - str(imax), - str(jmin), - str(jmax), - str(kmin), - str(kmax), - str(lmin), - str(lmax), - str(mmin), - str(mmax), - str(kpri), - ) + command = f"/SYS,{string}" return self.run(command, **kwargs) - def syp( + def ui( self, - string="", - arg1="", - arg2="", - arg3="", - arg4="", - arg5="", - arg6="", - arg7="", - arg8="", + func: str = "", + type_: str = "", + format_: str = "", + screen: str = "", + color: str = "", + krev: str = "", + orient: str = "", + compress: str = "", + quality: str = "", **kwargs, ): - """Passes a command string and arguments to the operating system. + r"""Activates specified GUI dialog boxes. - APDL Command: /SYP + Mechanical APDL Command: `/UI `_ Parameters ---------- - string - Command string (cannot include commas). See also the /SYS command. + func : str + Label identifying the dialog box to be activated: + + * ``HELP`` - Activates the online help system. + + * ``VIEW`` - Activates the Pan, Zoom, Rotate dialog box + + * ``WPSE`` - Activates the Working Plane Settings dialog box. + + * ``WPVI`` - Activates the Offset Working Plane dialog box. + + * ``RESULT`` - Activates the Query Picking Menu for reviewing results. + + * ``QUERY`` - Activates the Query Picked Entities (preprocess) dialog box. + + * ``COPY`` - Activates the Hard Copy dialog box. + + * ``ANNO`` - Activates the 2D Annotation dialog box. + + * ``AN3D`` - Activates the 3D Annotation dialog box. + + * ``SELECT`` - Activates the Select Entities dialog box. + + * ``NSEL`` - Activates a picking menu to select nodes. + + * ``ESEL`` - Activates a picking menu to select elements. + + * ``KSEL`` - Activates a picking menu to select keypoints. + + * ``LSEL`` - Activates a picking menu to select lines. + + * ``ASEL`` - Activates a picking menu to select areas. + + * ``VSEL`` - Activates a picking menu to select volumes. + + * ``REFRESH`` - Refreshes the graphics window (non-UI mode only). + + * ``COLL`` - Controls the collapse of the Mechanical APDL main menu when a :ref:`finish` command is issued. + See Type below for a discussion of the arguments. + + type_ : str + Label identifying the type of select operation. Valid only for the following ``Func`` labels; NSEL, ESEL, KSEL, LSEL, ASEL, and VSEL: + + * ``S`` - Select a new set. + + * ``R`` - Reselect a set from the current set. + + * ``A`` - Additionally select a set and extend the current set. + + * ``U`` - Unselect a set from the current set. + + Label identifying the type of results data to be queried. Valid only for ``Func`` = RESULT: + + * ``NODE`` - Nodal solution data (h-elements only). + + * ``ELEMENT`` - Element solution data. + + .. _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: + + * ``YES, 1 or blank`` - Allows the Main Menu to collapse after :ref:`finish` command. + + * ``NO or 0`` - Prevents Main Menu collapse after :ref:`finish` command. - arg1, arg2, arg3, . . . , arg8 - Arguments to be appended to the command string, separated by - blanks, commas, or other delimiter characters (see the Operations - Guide). The arguments may be numbers, parameters, or parametric - expressions. + format_ : str + + * ``TIFF`` - Tagged Image File Format. + + * ``BMP`` - (PC only) Bitmap (Windows) file format. + + * ``WMF`` - (PC only) Windows Metafile format. + + * ``EMF`` - (PC only) Enhanced Metafile format. + + * ``JPEG`` - JPEG (Joint Photographic Experts Group) file format. + + screen : str + + * ``FULL`` - Saves the entire screen in the specified format. + + * ``GRAPH`` - Saves only the Mechanical APDL graphic window. + + color : str + + * ``MONO`` - A two color (black and white) file is saved. + + * ``GRAY`` - The specified file format is saved in gray scale. + + * ``COLOR`` - The file is saved at the specified color depth. + + krev : str + + * ``NORM`` - Saves file as shown on the screen. + + * ``REVERSE`` - Saves file with the background color reversed. + + orient : str + + * ``LANDSCAPE`` - Saves file in landscape mode. + + * ``PORTRAIT`` - Saves file in portrait mode. + + compress : str + + * ``YES`` - Compresses TIFF files and EPS files with TIFF preview (default). + + * ``NO`` - Saves files with no compression. + + quality : str + + * ``1,2,,,100`` - JPEG quality index, with 100 being the maximum quality level. Notes ----- - Passes a command string to the operating system for execution, along - with arguments to be appended to the command string. See the - Operations Guide for details. ANSYS may not be aware of your specific - user environment. For example, on Linux this command may not recognize - aliases, depending on the hardware platform and user environment. - This command is valid in any processor. + .. warning:: + + This function contains specificities regarding the argument definitions. + Please refer to the `command documentation `_ + for further explanations. + + .. _s-UI_notes: + + Allows you to activate specified GUI dialog boxes directly in either GUI or non-GUI mode. + + The :ref:`ui` command itself is valid in any processor, however certain dialog boxes are accessible + only in a particular processor (for example, :ref:`ui`,RESULT,... is valid only in the General + Postprocessor). + + Mechanical APDL JPEG software is based in part on the work of the Independent JPEG Group, Copyright + 1998, + Thomas G. Lane. """ - command = "/SYP,%s,%s,%s,%s,%s,%s,%s,%s,%s" % ( - str(string), - str(arg1), - str(arg2), - str(arg3), - str(arg4), - str(arg5), - str(arg6), - str(arg7), - str(arg8), - ) + command = f"/UI,{func},{type_},{format_},{screen},{color},{krev},{orient},{compress},{quality}" return self.run(command, **kwargs) - def sys(self, string="", **kwargs): - """Passes a command string to the operating system. + def uis(self, label: str = "", value: int | str = "", **kwargs): + r"""Controls the GUI behavior. - APDL Command: /SYS + Mechanical APDL Command: `/UIS `_ Parameters ---------- - string - Command string, up to 639 characters (including blanks, commas, - etc.). The specified string is passed verbatim to the operating - system, i.e., no parameter substitution is performed. + label : str + Behavior control key: + + * ``BORD`` - Controls the functionality of the mouse buttons for dynamic viewing mode only. When + ``Label`` = BORD, the three values that follow control the functionality of the LEFT, MIDDLE and + RIGHT buttons, respectively (see below). + + * ``MSGPOP`` - Controls which messages from the Mechanical APDL error-message subroutine are displayed in a + message dialog box. + + * ``REPLOT`` - Controls whether or not an automatic replot occurs after functions affecting the + model are executed. + + * ``ABORT`` - Controls whether or not the program displays dialog boxes to show the status of an + operation in progress and to cancel that operation. + + * ``DYNA`` - Controls whether the dynamic mode preview is a bounding box or the edge outline of the + model. This label only applies to 2D display devices (that is, :ref:`show`,XII or + :ref:`show`,WIN32). This "model edge outline" mode is only supported in PowerGraphics ( + :ref:`graphics`,POWER) and is intended for element, line, results, area, or volume displays. + + * ``PICK`` - Controls how graphical entities are highlighted from within the the Select menu. + + * ``POWER`` - Controls whether or not PowerGraphics is active when the GUI is initiated. Mechanical APDL + default status is PowerGraphics "ON"; this command is used (placed in the :file:`start.ans` file) + when full graphics is desired on start up. + + * ``DPRO`` - Controls whether or not the input window displays a dynamic prompt. The dynamic prompt + shows the correct command syntax for the command, as you are entering it. + + * ``UNDO`` - Controls whether or not the session editor includes nonessential commands or comments + in the file it creates. You can use this option to include comments and other materials in the + session editor file. + + * ``LEGE`` - Controls whether or not the multi-legend is activated when you start the GUI. The + multi-legend enables you to specify the location of your legend items in each of the five graphics + windows. You can place this option in your :file:`start.ans` file and have the GUI start with the + legend items in a pre-specified location. + + * ``PBAK`` - Controls whether or not the background shading is activated when you start the GUI. You + can place this option in your :file:`start.ans` file. + + * ``ZPIC`` - Controls the sorting order for entities that are coincident (directly in front of or + behind each other) to a picked spot on your model. When you pick a spot on your model that could + indicate two or more entities, a message warns you of this condition, and a list of the coincident + entities can be generated. The ``VALUE`` term (below) will determine the sort order. + + * ``HPOP`` - Controls the prioritization of your GUI windows when the contents are ported to a plot + or print file ( :ref:`ui`,COPY,SAVE). OpenGL (3D) graphics devices require that the Mechanical APDL + graphics window contents be set in front of all overlying windows in order to port them to a printer + or a file. This operation can sometimes conflict with :ref:`noerase` settings. See the ``VALUE`` + term (below) to determine the available control options. + + value : int or str + Values controlling behavior if ``Label`` = BORD: + + (These values control the operation according to syntax : :ref:`uis`,BORD, LEFT, MIDDLE, RIGHT ) + + * ``1`` - PAN, controls dynamic translations. + + * ``2`` - ZOOM, controls zoom, and dynamic rotation about the view vector. + + * ``3`` - ROTATE, controls dynamic rotation about the screen X and Y axes. + + You can designate any value for any button, or designate the same value for all three buttons. If no + value is specified, default is LEFT = PAN, MIDDLE = ZOOM and RIGHT = ROTATE. + + Values controlling behavior if ``Label`` = MSGPOP: + + * ``0`` - All messages displayed. + + * ``1`` - Only notes, warnings, and errors displayed. + + * ``2`` - Only warnings and errors displayed (default). + + * ``3`` - Only errors displayed. + + Values controlling behavior if ``Label`` = REPLOT: + + * ``0`` - No automatic replot. + + * ``1`` - Automatic replot (default). + + Values controlling behavior if ``Label`` = ABORT: + + * ``ON`` - Display status and cancellation dialog boxes (default). + + * ``OFF`` - Do not display status and cancellation dialog boxes. + + * ``1`` - Same as ON. + + * ``0`` - Same as OFF. + + Values controlling behavior if ``Label`` = DYNA: + + * ``0`` - Use model edge outline when possible (default). + + * ``1`` - Use bounding box preview. + + Values controlling behavior if ``Label`` = PICK: + + * ``0`` - Picked keypoints and nodes are enclosed by a square. Picked lines are overlaid by a + thicker line. Picked areas, volumes, and elements (non-point/non-line) are redrawn with highlighting + colors. However, if the pick is a box, circle, or polygon pick, the highlighting for all entitles + consists only of a square placed around the entity's centroid. + + * ``1`` - Picked entities are not highlighted. + + * ``2`` - 5.1 highlighting (that is, no XOR). + + * ``3`` - Picked entities are highlighted as in ``VALUE`` = 0, except that, for a box, circle, or + polygon pick, the picked areas, volumes, and elements (non-point/non-line) are redrawn with + highlighting colors. This technique is slower than the ``VALUE`` = 0 technique. + + Values controlling behavior if ``Label`` = POWER: + + * ``0`` - Start GUI in Full Graphics mode. + + * ``1`` - Start GUI in PowerGraphics mode (default). + + Values controlling behavior if ``Label`` = DPRO: + + * ``0 or OFF`` - Do not display the dynamic prompt. + + * ``1 or ON`` - Display the dynamic prompt (default). + + Values controlling behavior if ``Label`` = UNDO: + + * ``0 or None`` - Do not suppress any commands (default). + + * ``1 or Comment`` - Write the nonessential commands to the session editor file as comments (with a + ! at the beginning). + + * ``2 or Remove`` - Do not write nonessential commands or comments. + + Values controlling behavior if ``Label`` = LEGE: + + * ``0 or OFF`` - Start GUI with the enhanced legend off (default). + + * ``1 or ON`` - Start GUI with the enhanced legend capability activated. + + Values controlling behavior if ``Label`` = PBAK: + + * ``0 or OFF`` - Start the GUI with the no background shading (default). + + * ``1 or ON`` - Start the GUI with background shading activated. + + Values controlling behavior if ``Label`` = HPOP: + + * ``0 or OFF`` - No rewrite operations are performed to compensate for items that obscure or overlay + the graphics window (default). + + * ``1 or ON`` - The Graphics screen contents are replotted to ensure that they are situated in front + of all other windows. If :ref:`noerase` is detected, this operation is suppressed. Notes ----- - Passes a command string to the operating system for execution (see the - Operations Guide). Typical strings are system commands such as list, - copy, rename, etc. Control returns to the ANSYS program after the - system procedure is completed. ANSYS may not be aware of your - specific user environment. For example, on Linux this command may not - recognize aliases, depending on the hardware platform and user - environment. + + .. _s-UIS_notes: + + Controls certain features of the Graphical User Interface (GUI), including whether Mechanical APDL + displays + dialog boxes to show you the status of an operation (such as meshing or solution) in progress and to + enable you to cancel that operation. Issue :ref:`uis`,STAT for current status. Issue :ref:`uis`,DEFA + to reset default values for all labels. Issue :ref:`uis`, ``Label``,STAT and :ref:`uis`, + ``Label``,DEFA for status and to reset a specific ``Label`` item. + + A :ref:`uis`,HPOP,1 command employs a fast redraw method which does not allow entering the legend + logic for a :ref:`plopts`,INFO,1 or :ref:`plopts`,INFO,2 command. However, the legend is redrawn for + :ref:`plopts`,INFO,3 because that command also allows a fast redraw. This command is valid in any processor. """ - command = f"/SYS,{string}" + command = f"/UIS,{label},{value}" return self.run(command, **kwargs) def unpause(self, **kwargs): - """Restores use of a temporarily released product license. + r"""Restores use of a temporarily released product license. - APDL Command: UNPAUSE + Mechanical APDL Command: `UNPAUSE `_ Notes ----- - The UNPAUSE command restores use of a temporarily released (paused) - product license. The command is valid only after a previously issued - PAUSE command. - When use of the product license is paused via the PAUSE command, no - other operation (other than SAVE or /EXIT) is possible until you issue - the UNPAUSE command. + .. _UNPAUSE_notes: + + The :ref:`unpause` command restores use of a temporarily released (paused) product license. The + command is valid only after a previously issued :ref:`pause` command. + + When use of the product license is paused via the :ref:`pause` command, no other operation (other + than :ref:`save` or ``/EXIT`` ) is possible until you issue the :ref:`unpause` command. - For more information, see the documentation for the PAUSE command and - the ANSYS, Inc. Licensing Guide. + For more information, see the documentation for the :ref:`pause` command and the `Ansys Licensing + Guide `_. """ - command = "UNPAUSE," + command = "UNPAUSE" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/mapdl_extended.py b/src/ansys/mapdl/core/mapdl_extended.py index 3681bee8a5..0cdcec0d6d 100644 --- a/src/ansys/mapdl/core/mapdl_extended.py +++ b/src/ansys/mapdl/core/mapdl_extended.py @@ -375,14 +375,21 @@ def mpread(self, fname="", ext="", lib="", **kwargs): return self.input(fname) @wraps(_MapdlCore.cwd) - def cwd(self, *args, **kwargs): + def cwd(self, dirpath: str = "", **kwargs): """Wraps cwd.""" + dirpath = str(dirpath) + if not (dirpath.startswith("'") and dirpath.endswith("'")) and "'" in dirpath: + raise MapdlRuntimeError( + 'The CWD command does not accept paths that contain singular quotes "\'".' + ) + kwargs["mute"] = False + try: - output = super().cwd(*args, mute=False, **kwargs) + output = super().cwd(dirpath, **kwargs) except MapdlCommandIgnoredError as e: raise IncorrectWorkingDirectory(e.args[0]) - self._path = args[0] # caching + self._path = dirpath # caching return output @wraps(_MapdlCore.list) diff --git a/src/ansys/mapdl/core/mapdl_grpc.py b/src/ansys/mapdl/core/mapdl_grpc.py index 92965f2b66..2f9e2dfa6e 100644 --- a/src/ansys/mapdl/core/mapdl_grpc.py +++ b/src/ansys/mapdl/core/mapdl_grpc.py @@ -963,8 +963,8 @@ def _launch(self, start_parm, timeout=10): @supress_logging def _set_no_abort(self): """Do not abort MAPDL.""" - self._log.debug("Setting no abort") - self.nerr(abort=-1, mute=True) + self._log.debug("Setting to no abort") + self.run("/NERR,,,-1", mute=True) def _run_at_connect(self): """Run house-keeping commands when initially connecting to MAPDL.""" @@ -1793,7 +1793,7 @@ def input( ext : str, optional Filename extension (eight-character maximum). - dir : str, optional + dir_ : str, optional Directory path. The default is the current working directory. line : int, optional