From d594b8199b89d32c616fd5839c0d1cf632a32575 Mon Sep 17 00:00:00 2001 From: Camille <78221213+clatapie@users.noreply.github.com> Date: Tue, 6 May 2025 13:03:02 +0200 Subject: [PATCH 01/13] feat: ``session`` submodule --- doc/source/mapdl_commands/session/files.rst | 42 +- doc/source/mapdl_commands/session/index.rst | 22 + .../mapdl_commands/session/list_controls.rst | 29 +- .../session/processor_entry.rst | 37 +- .../mapdl_commands/session/run_controls.rst | 54 +- .../mapdl/core/_commands/session/__init__.py | 7 +- .../mapdl/core/_commands/session/files.py | 1000 ++++++------ .../core/_commands/session/list_controls.py | 138 +- .../core/_commands/session/processor_entry.py | 162 +- .../core/_commands/session/run_controls.py | 1399 +++++++++++------ 10 files changed, 1727 insertions(+), 1163 deletions(-) create mode 100644 doc/source/mapdl_commands/session/index.rst 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..3e59f940a0 --- /dev/null +++ b/doc/source/mapdl_commands/session/index.rst @@ -0,0 +1,22 @@ + +.. _ref_session: + +Session +======= + +.. list-table:: + + * - :ref:`ref_run_controls` + * - :ref:`ref_processor_entry` + * - :ref:`ref_files` + * - :ref:`ref_list_controls` + + +.. toctree:: + :maxdepth: 1 + :hidden: + + run_controls + processor_entry + files + list_controls 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..8169e9157c 100644 --- a/doc/source/mapdl_commands/session/run_controls.rst +++ b/doc/source/mapdl_commands/session/run_controls.rst @@ -1,29 +1,35 @@ -.. _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.slashexit + 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..5b27d35843 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 lgwrite(self, fname: str = "", ext: str = "", kedit: str = "", **kwargs): + r"""Writes the database command log to a file. + + Mechanical APDL Command: `LGWRITE `_ Parameters ---------- - fname - ASAS 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`. - key - Key indicating type of file to produce: + ext : str + Filename extension (eight-character maximum). The extension defaults to LGW if ``Fname`` and + ``Ext`` are blank. - 0 - ASAS file for use by ANSYS Aqwa (no loads written). Creates the file - Fname.asas. + kedit : str + Flag to suppress nonessential commands: + + * ``NONE`` - Do not suppress any commands (default). - 1 - ASAS file (all data written, including loads). Creates the file Fname.asas. + * ``COMMENT`` - Write nonessential commands as comments (starting with !). - 2 - ASAS(NL) file. Creates the file Fname.asnl. + * ``REMOVE`` - Do not write nonessential commands or comments. 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 + .. _LGWRITE_notes: - The following data is written: + 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. - Solution control options + This command is valid in any processor. + """ + command = f"LGWRITE,{fname},{ext},,{kedit}" + return self.run(command, **kwargs) - Nodes + def starlist(self, fname: str = "", ext: str = "", **kwargs): + r"""Displays the contents of an external, coded file. - Elements + Mechanical APDL Command: `\*LIST `_ - Material data + 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. - Geometry data + ext : str + Filename extension (eight-character maximum). - Section data + Notes + ----- - ANSYS element components (ASAS sets) + .. _a-LIST_notes: - Boundary conditions + 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). - Loads + 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. - Added mass (via MASS21 element) + This command is valid in any processor. + """ + command = f"*LIST,{fname},{ext}" + return self.run(command, **kwargs) - Details are provided in the following sections. + def slashrename( + self, + fname1: str = "", + ext1: str = "", + fname2: str = "", + ext2: str = "", + distkey: str = "", + **kwargs, + ): + r"""Renames a file. - 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. + Mechanical APDL Command: `/RENAME `_ - Solution Control Options + Parameters + ---------- + 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. - The ASAS project name is defined as "ANSYS". + File name defaults to the current :file:`Jobname`. - The solution control options are converted as follows: + ext1 : str + Filename extension (eight-character maximum). - JOB: STAT SPIT: KGEOM + 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). - JOB: STAT SPIT: KGEOM + ``Fname2`` defaults to ``Fname1``. - 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). + ext2 : str + Filename extension (eight-character maximum). ``Ext2`` defaults to ``Ext1``. - Element Data + distkey : str + Key that specifies which rename operation is performed on all processes in distributed-memory + parallel mode: - 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. + * ``0 (OFF or NO)`` - The program performs the rename operation only on the master process + (default). - The element types are converted as follows: + * ``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 + ----- + + .. _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. + """ + command = f"/RENAME,{fname1},{ext1},,{fname2},{ext2},,{distkey}" + return self.run(command, **kwargs) + + def slashclog(self, fname: str = "", ext: str = "", **kwargs): + r"""Copies the session log file to a named file. + + Mechanical APDL Command: `/CLOG `_ + + Parameters + ---------- + 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 + ----- + + .. _s-CLOG_notes: - SPR1: SPR2: if: rotational: spring: FLA2: (ASAS(L): only): if: - nodes: are: not: coincident: and: longitudinal: spring: + This command is valid in any processor, but only during an interactive run. + """ + command = f"/CLOG,{fname},{ext}" + return self.run(command, **kwargs) + + def copy( + self, + fname1: str = "", + ext1: str = "", + fname2: str = "", + ext2: str = "", + distkey: str = "", + **kwargs, + ): + r"""Copies a file. - QUM4: TRM3: -: if: Triangular + Mechanical APDL Command: `/COPY `_ - BRK8: TET4: -: if: Tetrahedral: BRK6: -: if: Prism + Parameters + ---------- + 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. - QUS4: TBC3: -: if: Triangular + The file name defaults to the current :file:`Jobname`. - QUM8: TRM6: -: if: Triangular + ext1 : str + Filename extension (eight-character maximum). - BR20: TE10: -: if: Tetrahedral: : BR15: -: if: Prism + 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. - QUS4: TBC3: -: if: Triangular + ``Fname2`` defaults to ``Fname1``. - QUM4: TRM3: -: if: Triangular + ext2 : str + Filename extension (eight-character maximum). ``Ext2`` defaults to ``Ext1``. - QUM8: TRM6: -: if: Triangular + distkey : str + Key that specifies which copy operation is performed on all processes in distributed-memory parallel + mode : - BRK8: TET4: -: if: Tetrahedral: BRK6: -: if: Prism + * ``0 (OFF or NO)`` - The program performs the copy operation only on the master process (default). - BR20: TE10: -: if: Tetrahedral: BR15: -: if: Prism + * ``1 (ON or YES)`` - The program performs the copy operation locally on each process. - TCBM: -: if: ASAS(L): STF4: -: if: ASAS(NL) + * ``2 or BOTH`` - The program performs the copy operation for ``Fname``. ``Ext`` on the master + process and for ``FnameN``. ``Ext`` on all processes. - Documentation for this legacy element type appears in the Feature - Archive. + Notes + ----- - Material Data + .. _s-COPY_notes: - Linear isotropic material conversion is supported for ASAS and - ASAS(NL). + 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. - Geometry Data + 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 = "ANSTOASAS,%s,%s" % (str(fname), str(key)) + command = f"/COPY,{fname1},{ext1},,{fname2},{ext2},,{distkey}" return self.run(command, **kwargs) def anstoaqwa( self, - fname="", - vertaxis="", - gc="", - rho="", - hwl="", - diffkey="", - symxkey="", - symykey="", + fname: str = "", + vertaxis: str = "", + gc: str = "", + rho: str = "", + hwl: str = "", + diffkey: int | str = "", + symxkey: int | str = "", + symykey: int | str = "", **kwargs, ): - """Creates an AQWA-LINE input file from the current ANSYS model. + r"""Creates an AQWA-LINE input file from the current Mechanical APDL model. - APDL Command: ANSTOAQWA + Mechanical APDL Command: `ANSTOAQWA `_ Parameters ---------- - fname - AQWA file name. Defaults to Jobname. + fname : str + AQWA file name. Defaults to :file:`Jobname`. - vertaxis + vertaxis : str Axis in the vertical direction: - Y (or 2) - Global Y axis. + * ``Y (or 2)`` - Global Y axis. - Z (or 3) - Global Z axis (default). + * ``Z (or 3)`` - Global Z axis (default). - gc + gc : str Gravitational acceleration. Defaults to 9.81. - rho + rho : str Density of water. Defaults to 1025.0. - hwl + hwl : str Waterline height in model coordinates. Defaults to 0.0. - diffkey + diffkey : int or str Diffracting model key: - 0 - Create a non-diffracting AQWA model. + * ``0`` - Create a non-diffracting AQWA model. - 1 - Create a diffracting AQWA model (default). + * ``1`` - Create a diffracting AQWA model (default). - symxkey + symxkey : int or str Key indicating if model is symmetric about the global XZ plane: - 0 - No symmetry about XZ plane (default). + * ``0`` - No symmetry about XZ plane (default). - 1 - Use symmetry about XZ plane. Only include (or select) half the model. + * ``1`` - Use symmetry about XZ plane. Only include (or select) half the model. - symykey + symykey : int or str Key indicating if model is symmetric about the global YZ plane: - 0 - No symmetry about YZ plane (default). + * ``0`` - No symmetry about YZ plane (default). - 1 - Use symmetry about YZ plane. Only include (or select) half the model. + * ``1`` - Use symmetry about YZ plane. Only include (or select) half the model. 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. + + .. _ANSTOAQWA_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, 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 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. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + 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, the application prompts you for their values. You must verify the completeness and accuracy of the data written. + + **AQWA-LINE Notes** + + .. _ANSTOAQWA_aqwa: + + 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. + + 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. + + 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 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 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. + + 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 = "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), - ) + command = f"ANSTOAQWA,{fname},{vertaxis},{gc},{rho},{hwl},{diffkey},{symxkey},{symykey}" return self.run(command, **kwargs) - def assign(self, ident="", fname="", ext="", lgkey="", **kwargs): - """Reassigns a file name to an ANSYS file identifier. + def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): + r"""Creates an ASAS input file from the current Mechanical APDL model. - APDL Command: /ASSIGN + Mechanical APDL Command: `ANSTOASAS `_ 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). + fname : str + ASAS file name. Defaults to :file:`Jobname`. - 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. + key : int or str + Key indicating type of file to produce: - BOTH - Reassign the file name for both the local and global files (default). + * ``0`` - ASAS file for use by Ansys Aqwa (no loads written). Creates the file ``Fname``.asas. - LOCAL - Reassign the file name for only the local files. + * ``1`` - ASAS file (all data written, including loads). Creates the file ``Fname``.asas. - GLOBAL - Reassign the file name for only the global file. + * ``2`` - ASAS(NL) file. Creates the file ``Fname``.asnl. 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. - This command is valid only at the Begin Level. + .. _ANSTOASAS_notes: - 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. - """ - return self.run(f"/ASSIGN,{ident},{fname},{ext},,{lgkey}", **kwargs) + 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. - def slashclog(self, fname="", ext="", **kwargs): - """APDL Command: /CLOG + **Data Written** - Copies the session log file to a named file. + The following data is written: - 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. + * :ref:`Solution control options ` - ext - Filename extension (eight-character maximum). + * Nodes - Notes - ----- - This command is valid in any processor, but only during an interactive - run. - """ - command = "/CLOG,%s,%s" % (str(fname), str(ext)) - return self.run(command, **kwargs) + * :ref:`Elements ` - def copy(self, fname1="", ext1="", fname2="", ext2="", distkey="", **kwargs): - """Copies a file. + * :ref:`Material data ` - APDL Command: /COPY + * :ref:`Geometry data ` - 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). + * :ref:`Section data ` - 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. + * Mechanical APDL element components (ASAS sets) - ext2 - Filename extension (eight-character maximum). + * :ref:`Boundary conditions ` - distkey - Key that specifies whether the copy operation is performed - on all processes in distributed parallel mode (Distributed - ANSYS): + * :ref:`Loads ` - 0 (OFF or NO) - The program performs the copy operation - only on the master process (default). + * Added mass (via ``MASS21``element) - 1 (ON or YES) - The program performs the copy operation - locally on each process. + Details are provided in the following sections. - 2 or BOTH - The program performs the copy operation for - Fname.Ext on the master process and for FnameN.Ext on all - processes. + 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. - 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. - """ - command = f"/COPY,{fname1},{ext1},,{fname2},{ext2},,{distkey}" - return self.run(command, **kwargs) + .. _solconop: - def fclean(self, **kwargs): - """Deletes all local files in all processors in a distributed parallel processing run. + **Solution Control Options** - APDL Command: /FCLEAN + The ASAS project name is defined as "Ansys". - 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. + The solution control options are converted as follows: - .. 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. + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - Notes - ----- + 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). - 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 + .. _elemdat: - This command is valid only at the Begin Level. - """ - return self.run("/FCLEAN", **kwargs) + **Element Data** - def fcomp(self, ident="", level="", **kwargs): - """Specifies file compression level. + 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. - 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. + The element types are converted as follows: - level - Compression level. Valid input values are 0 (no compression - - default) to 5 (maximum compression). + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - Notes - ----- - Command Default - File compression is not performed. + .. _anstoasas_fn1: - 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). + Documentation for this archived element type appears in the `Feature Archive + `_. - See File Compression in the Basic Analysis Guide for more details. - """ - return self.run(f"/FCOMP,{ident},{level}", **kwargs) + .. _matdat: - def lgwrite(self, fname="", ext="", kedit="", remove_grpc_extra=True, **kwargs): - """Writes the database command log to a file. + **Material Data** - APDL Command: LGWRITE + Linear isotropic material conversion is supported for ASAS and ASAS(NL). - 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. + .. _geomdat: - The file name defaults to Jobname. + **Geometry Data** - ext : str, optional - Filename extension (eight-character maximum). + The following ASAS element geometry data is supported: - kedit : str, optional - Flag to suppress nonessential commands: + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - * ``"NONE"`` - Do not suppress any commands (default). - * ``"COMMENT"`` - Write nonessential commands as comments (starting with !). - * ``"REMOVE"`` - Do not write nonessential commands or comments. + 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. - remove_grpc_extra : bool, default: True - Remove gRPC related content (like ``/OUT,anstmp``). This will be - ignored when MAPDL is not in gRPC mode. + .. _sectdat: - 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. + **Section Data** - This command is valid in any processor. + No user sections are generated if AQWA-WAVE data is selected. + + The following sections 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. + + .. _boundcon: + + **Boundary Conditions** + + The following boundary conditions are converted for ASAS and ASAS(NL): - Examples - -------- - Output the database command log to the local directory. + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - >>> 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') + .. _loadsasas: - Print the output from the log file. + **Loads** - >>> with open(filename) as fid: - ... lines = fid.readlines() - >>> print(''.join(lines)) - /BATCH - /PREP7, - K,1,0,0,0 - K,2,2,0,0 + 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"LGWRITE,{fname},{ext},,{kedit}") + command = f"ANSTOASAS,{fname},{key}" + return self.run(command, **kwargs) - def starlist(self, fname="", ext="", **kwargs): - """Displays the contents of an external, coded file. + def assign( + self, ident: str = "", fname: str = "", ext: str = "", lgkey: str = "", **kwargs + ): + r"""Reassigns a file name to a Mechanical APDL file identifier. - APDL Command: ``*LIST`` + Mechanical APDL Command: `/ASSIGN `_ 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 + 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 ----- - 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-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 = f"*LIST,{fname},{ext}" + command = f"/ASSIGN,{ident},{fname},{ext},,{lgkey}" 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 fcomp(self, ident: str = "", level: int | str = "", **kwargs): + r"""Specifies file-compression options. - APDL Command: /DELETE + Mechanical APDL Command: `/FCOMP `_ 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 - Filename extension (eight-character maximum). + ident : str + Mechanical APDL file identifier. There is no default. Valid labels are: + + * ``RST`` - Results file. + + * ``DB`` - Database file. + + * ``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: - distkey - Key that specifies whether the file deletion is performed - on all processes in distributed parallel mode (Distributed - ANSYS): + * ``SPARSE`` - Use a sparsification scheme for file compression (default). - 1 (ON or YES) - The program performs the file deletion - locally on each process. + * ``0`` - No file compression occurs. - 0 (OFF or NO) - The program performs the file deletion - only on the master process (default). + * ``n`` - A zlib-based file compression occurs using level number ``n``, which ranges from 1 to 5. 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-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). + + 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"/DELETE,{fname},{ext},,{distkey}", **kwargs) + command = f"/FCOMP,{ident},{level}" + return self.run(command, **kwargs) + + def fclean(self, **kwargs): + r"""Deletes all local files in all processors in a distributed parallel processing run. + + Mechanical APDL Command: `/FCLEAN `_ + + Notes + ----- + + .. _s-FCLEAN_notes: + + 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. + """ + command = "/FCLEAN" + 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..8a4d7920b7 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 golist(self, **kwargs): + r"""Reactivates the suppressed data input listing. - Parameters - ---------- - comment - Comment string, up to 75 characters. + Mechanical APDL Command: `/GOLIST `_ 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. + .. _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 = f"/COM, {comment}" + command = "/GOLIST" return self.run(command, **kwargs) - def golist(self, **kwargs): - """Reactivates the suppressed data input listing. + def gopr(self, **kwargs): + r"""Reactivates suppressed printout. - APDL Command: /GOLIST + Mechanical APDL Command: `/GOPR `_ 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-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 = "/GOLIST," + command = "/GOPR" return self.run(command, **kwargs) - def gopr(self, **kwargs): - """Reactivates suppressed printout. + def slashgo(self, **kwargs): + r"""Reactivates suppressed printout. - APDL Command: /GOPR + Mechanical APDL Command: `/GO `_ 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-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 = "/GOPR," + command = "/GO" + return self.run(command, **kwargs) + + def nopr(self, **kwargs): + r"""Suppresses the expanded interpreted input data listing. + + Mechanical APDL Command: `/NOPR `_ + + Notes + ----- + + .. _s-NOPR_notes: + + Suppresses printout of interpreted input data, including information labeled as "Notes." When this + printout is not suppressed, the data input to the analysis is echoed to the output file in an + expanded format. Printout is suppressed until a :ref:`gopr` or :ref:`slashgo` command is read. + + Use of :ref:`nopr` is not recommended when the graphical user interface (GUI) is active. The GUI + sometimes issues "hidden" :ref:`nopr` and :ref:`gopr` command sequences, which will countermand + user-issued :ref:`nopr` commands, thus making the use of :ref:`nopr` in the GUI environment + unpredictable. + + This command is valid in any processor. + """ + command = "/NOPR" 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. + def com(self, comment: str = "", **kwargs): + r"""Places a comment in the output. + + Mechanical APDL Command: `/COM `_ - APDL Command: /NOPR + Parameters + ---------- + comment : str + Comment string, up to 75 characters. 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-COM_notes: - This command is valid in any processor. + 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 = "/NOPR," + command = f"/COM,{comment}" 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..645c6f8314 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 + def post26(self, **kwargs): + r"""Enters the time-history results postprocessor. + + Mechanical APDL Command: `/POST26 `_ 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. - APDL Command: /AUX3 + .. _s-POST26_notes: - Notes - ----- - Enters the results file editing processor (ANSYS auxiliary processor - AUX3). This processor is used to edit ANSYS results files. + Enters the time-history results postprocessor (POST26). This command is valid only at the Begin Level. """ - command = "/AUX3," + command = "/POST26" return self.run(command, **kwargs) - def aux12(self, **kwargs): - """Enters the radiation processor. + def post1(self, **kwargs): + r"""Enters the database results postprocessor. - APDL Command: /AUX12 + Mechanical APDL Command: `/POST1 `_ Notes ----- - Enters the radiation processor (ANSYS auxiliary processor AUX12). This - processor supports the Radiation Matrix and the Radiosity Solver - methods. + + .. _s-POST1_notes: + + 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 = "/AUX12," + command = "/POST1" return self.run(command, **kwargs) - def aux15(self, **kwargs): - """Enters the IGES file transfer processor. + def prep7(self, **kwargs): + r"""Enters the model creation preprocessor. - APDL Command: /AUX15 + Mechanical APDL Command: `/PREP7 `_ Notes ----- - Enters the IGES file transfer processor (ANSYS auxiliary processor - AUX15), used to read an IGES data file into the ANSYS program. + + .. _s-PREP7_notes: + + Enters the general input data preprocessor (PREP7). This command is valid only at the Begin Level. """ - command = "/AUX15," + command = "/PREP7" return self.run(command, **kwargs) - def finish(self, **kwargs): - """Exits normally from a processor. + def quit(self, **kwargs): + r"""Exits a processor. - APDL Command: FINISH + Mechanical APDL Command: `/QUIT `_ 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. - APDL Command: /POST1 + .. _s-QUIT_notes: - Notes - ----- - Enters the general database results postprocessor (POST1). All load - symbols (/PBC, /PSF, or /PBF) are automatically turned off with this - command. + 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 :ref:`slashexit` command to terminate the run. - 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 = "/POST1," + command = "/QUIT" return self.run(command, **kwargs) - def post26(self, **kwargs): - """Enters the time-history results postprocessor. + def slashsolu(self, **kwargs): + r"""Enters the solution processor. - APDL Command: /POST26 + Mechanical APDL Command: `/SOLU `_ Notes ----- - Enters the time-history results postprocessor (POST26). + + .. _s-SOLU_notes: This command is valid only at the Begin Level. """ - command = "/POST26," + command = "/SOLU" return self.run(command, **kwargs) - def prep7(self, **kwargs): - """Enters the model creation preprocessor. + def finish(self, **kwargs): + r"""Exits normally from a processor. - APDL Command: /PREP7 + Mechanical APDL Command: `FINISH `_ Notes ----- - Enters the general input data preprocessor (PREP7). - This command is valid only at the Begin Level. - """ - command = "/PREP7," - return self.run(command, **kwargs) + .. _FINISH_notes: - def quit(self, **kwargs): - """Exits a processor. + This command exits any of the Mechanical APDL processors. - APDL Command: /QUIT + 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 - ----- - 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. + If exiting POST1 or POST26: - This command is valid in any processor. This command is not valid at - the Begin level. - """ - command = "/QUIT," - return self.run(command, **kwargs) + * 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). - def slashsolu(self, **kwargs): - """Enters the solution processor. + * 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. - APDL Command: /SOLU + See :ref:`quit` for an alternate processor exit command. - Notes - ----- - 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 = "/SOLU," + command = "FINISH" 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 757e2b8707..b03a9da92e 100644 --- a/src/ansys/mapdl/core/_commands/session/run_controls.py +++ b/src/ansys/mapdl/core/_commands/session/run_controls.py @@ -20,670 +20,1147 @@ # 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 - Parameters - ---------- - lab - Configuration parameter to be changed: + def keyw(self, **kwargs): + r"""Sets a keyword used by the GUI for context filtering (GUI). - 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. + Mechanical APDL Command: `KEYW `_ - NBUF - VALUE is the number of buffers (1 to 32) per file - in the solver. Defaults to 4. + Notes + ----- - 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. + .. _KEYW_notes: - SZBIO - VALUE is the record size (1024 to 4194304) of - binary files (in integer words). Defaults to - 16384 (system dependent). + 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. + """ + command = "KEYW" + return self.run(command, **kwargs) - ORDER - Automatic reordering scheme. For VALUE use: 0 for - WSORT,ALL; 1 for WAVES; 2 for both WSORT,ALL and - WAVES (default). + def slashexit(self, slab: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Stops the run and returns control to the system. - 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. + Mechanical APDL Command: `/EXIT `_ - 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. + Parameters + ---------- + slab : str + Mode for saving the database: - MXEL - Maximum number of elements. Default and expansion as for MXND. + * ``MODEL`` - Save the model data (solid model, finite element model, loadings, etc.) only + (default). - MXKP - Maximum number of keypoints. Default and expansion as for MXND. + * ``SOLU`` - Save the model data and the solution data (nodal and element results). - MXLS - Maximum number of lines. Default and expansion as for MXND. + * ``ALL`` - Save the model data, solution data and post data (element tables, path results, etc.) - MXAR - Maximum number of areas. Default and expansion as for MXND. + * ``NOSAVE`` - Do not save any data on :file:`File.DB` (an existing DB file will not be + overwritten). - MXVL - Maximum number of volumes. Default and expansion as for MXND. + 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`. - MXRL - Maximum number of sets of real constants (element - attributes). Default and expansion as for MXND. + ext : str + Filename extension (eight-character maximum). The extension defaults to DB if ``Fname`` is + blank. - MXCP - Maximum number of sets of coupled degrees of - freedom. Default and expansion as for MXND. + Notes + ----- - MXCE - Maximum number of constraint equations. Default - and expansion as for MXND. + .. _s-EXIT_notes: - 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. + The current database information may be written on :file:`File.DB` or a named file. If + :file:`File.DB` already exists, a backup file ( :file:`File.DBB` ) will also be written whenever a + new :file:`File.DB` is written. - 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. + This command is valid in any processor. Issuing this command at any point will exit the program. + """ + command = f"/EXIT,{slab},{fname},{ext}" + return self.run(command, **kwargs) - STAT - Displays current values set by the /CONFIG command. + def pause(self, **kwargs): + r"""Temporarily releases the current product license. - value - Value (an integer number) assigned to the configuration parameter. + Mechanical APDL Command: `PAUSE `_ 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. + + .. _PAUSE_notes: + + The :ref:`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 :ref:`pause` command via the command line. + + No other operation (other than :ref:`save` or :ref:`slashexit` ) is possible in the current + application while use of the product license is paused. + + 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 = "/CONFIG,%s,%s" % (str(lab), str(value)) + command = "PAUSE" return self.run(command, **kwargs) - def cwd(self, dirpath="", **kwargs): - """Changes the current working directory. - - ``dirpath`` must not contain any singular quotations/apostrophes. - These are not supported in APDL. + def uis(self, label: str = "", value: int | str = "", **kwargs): + r"""Controls the GUI behavior. - APDL Command: /CWD + Mechanical APDL Command: `/UIS `_ Parameters ---------- - dirpath - The full path name of the new working directory. + label : str + Behavior control key: - 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. + * ``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). - Examples - -------- - Change MAPDL's working directory to ``"C:/temp"``. This - assumes that MAPDL running on Windows. + * ``MSGPOP`` - Controls which messages from the Mechanical APDL error-message subroutine are displayed in a + message dialog box. - >>> mapdl.cwd("C:/temp") + * ``REPLOT`` - Controls whether or not an automatic replot occurs after functions affecting the + model are executed. - MAPDL on Linux example: + * ``ABORT`` - Controls whether or not the program displays dialog boxes to show the status of an + operation in progress and to cancel that operation. - >>> mapdl.cwd("/tmp/") + * ``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. - """ - 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 "' - ) - return self.run(f"/CWD,'{dirpath}'", **kwargs) + * ``PICK`` - Controls how graphical entities are highlighted from within the the Select menu. - def filname(self, fname="", key="", **kwargs): - """Changes the Jobname for the analysis. + * ``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. - APDL Command: /FILNAME + * ``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. - 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. + * ``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: - key - Specify whether to use the existing log, error, lock, page, and - output files (.LOG, .ERR, .LOCK, .PAGE and .OUT) or start new - files. + * ``0 or OFF`` - Start GUI with the enhanced legend off (default). - 0, OFF - Continue using current log, error, lock, page, and output files. + * ``1 or ON`` - Start GUI with the enhanced legend capability activated. - 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. + 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 ----- - 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. - This command is valid only at the Begin level. + .. _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 = "/FILNAME,%s,%s" % (str(fname), str(key)) + command = f"/UIS,{label},{value}" return self.run(command, **kwargs) - def input(self, fname="", ext="", dir="", line="", log="", **kwargs): - """Switches the input file for the commands that follow. + def ui( + self, + func: str = "", + type_: str = "", + format_: str = "", + screen: str = "", + color: str = "", + krev: str = "", + orient: str = "", + compress: str = "", + quality: str = "", + **kwargs, + ): + r"""Activates specified GUI dialog boxes. - APDL Command: /INPUT + Mechanical APDL Command: `/UI `_ 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 - Filename extension (eight-character maximum). + 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: - dir - Directory path (64 characters maximum). Defaults to current - directory. + * ``YES, 1 or blank`` - Allows the Main Menu to collapse after :ref:`finish` command. - 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. + * ``NO or 0`` - Prevents Main Menu collapse after :ref:`finish` command. - (blank), 0, or 1 - Begins reading from the top of the file (default). + format_ : str - LINE_NUMBER - Begins reading from the specified line number in the file. + * ``TIFF`` - Tagged Image File Format. - :label - Begins reading from the first line beginning with the - matching user-defined label :label (beginning with a - colon (:), 8 characters maximum). + * ``BMP`` - (PC only) Bitmap (Windows) file format. - log - Indicates whether secondary input from this command should be - recorded in the command log (File.LOG) and the database log: + * ``WMF`` - (PC only) Windows Metafile format. - 0 - Record only the /INPUT command on the log (default). + * ``EMF`` - (PC only) Enhanced Metafile format. - 1 - Record commands in the specified secondary file as they are executed. + * ``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 ----- - 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 - file are not written to the command log). - The Dir option is optional as the directory path can be included - directly in Fname. + .. warning:: - Examples - -------- - Run an input file relative to the location of MAPDL. + This function contains specificities regarding the argument definitions. + Please refer to the `command documentation `_ + for further explanations. - >>> mapdl.input('my_input_file.inp') + .. _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. """ - return self.run(f"/INPUT,{fname},{ext},{dir},{line},{log}", **kwargs) + command = f"/UI,{func},{type_},{format_},{screen},{color},{krev},{orient},{compress},{quality}" + return self.run(command, **kwargs) - def keyw(self, keyword="", key="", **kwargs): - """Sets a keyword used by the GUI for context filtering (GUI). + def unpause(self, **kwargs): + r"""Restores use of a temporarily released product license. - APDL Command: KEYW + Mechanical APDL Command: `UNPAUSE `_ + + Notes + ----- + + .. _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 :ref:`slashexit` ) is possible until you issue the :ref:`unpause` command. + + For more information, see the documentation for the :ref:`pause` command and the `Ansys Licensing + Guide + `_. + """ + command = "UNPAUSE" + return self.run(command, **kwargs) + + def mstart(self, label: str = "", key: str = "", **kwargs): + r"""Controls the initial GUI components. + + Mechanical APDL Command: `/MSTART `_ Parameters ---------- - keyword - A keyword which, when set to either true or false, changes the - behavior of the GUI. + label : str + Label identifying the GUI component: + + * ``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. - key - Keyword switch: + * ``ANNO`` - Annotation dialog box, off by default. - 0 - Sets the keyword to "false." + * ``HARD`` - Hard Copy dialog box, off by default. - 1 - Sets the keyword to "true." + * ``UTIL`` - Activates the pre-6.1 (UIDL) GUI (off by 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 ----- - 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. - This command is valid in any processor. + .. _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 = "KEYW,%s,%s" % (str(keyword), str(key)) + command = f"/MSTART,{label},{key}" return self.run(command, **kwargs) - def memm(self, lab="", kywrd="", **kwargs): - """Allows the current session to keep allocated memory. + def memm(self, lab: str = "", kywrd: str = "", **kwargs): + r"""Allows the current session to keep allocated memory - APDL Command: MEMM + Mechanical APDL Command: `MEMM `_ Parameters ---------- - lab - When Lab = KEEP, the memory manager's ability to acquire and keep - memory is controlled by Kywrd + lab : str + When ``Lab`` = KEEP, the memory manager's ability to acquire and keep memory is controlled by + ``Kywrd`` - kywrd + kywrd : str Turns the memory "keep" mode on or off - ON - Keep any memory allocated during the analysis. + * ``ON`` - Keep any memory allocated during the analysis. - OFF - Use memory dynamically and free it up to other users after use (default). + * ``OFF`` - Use memory dynamically and free it up to other users after use (default). 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. + + .. _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). + + Mechanical APDL Command: `/MENU `_ + + Parameters + ---------- + key : str + Activation key: + + * ``ON`` - Activates the menu system (device dependent). + + Notes + ----- + + .. _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 = "MEMM,%s,%s" % (str(lab), str(kywrd)) + command = f"/MENU,{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 pause(self, **kwargs): - """Temporarily releases the current product license. + 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 `_ - APDL Command: PAUSE + 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 ----- - 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. + .. _s-OUTPUT_notes: - No other operation (other than SAVE or /EXIT) is possible in the - current application while use of the product license is paused. + 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 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. + 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. - For more information, see the ANSYS, Inc. Licensing Guide. + This command is valid in any processor. """ - command = "PAUSE," + command = f"/OUTPUT,{fname},{ext},,{loc}" return self.run(command, **kwargs) - def slashstatus(self, lab="", **kwargs): - """Lists the status of items for the run. + 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: /STATUS + Mechanical APDL Command: `/INPUT `_ Parameters ---------- - lab - Items to list status for: + 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. - ALL - List all below (default). + ext : str + Filename extension (eight-character maximum). - TITLE - List only titles, Jobname, and revision number. + dir_ : str + Directory path (64 characters maximum). Defaults to current directory. - UNITS - List only units. + 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. - MEM - List only memory data statistics. + * ``(blank), 0, or 1`` - Begins reading from the top of the file (default). - DB - List only database statistics + * ``LINE_NUMBER`` - Begins reading from the specified line number in the file. - CONFIG - List only configuration parameters. + * ``:, label`` - Begins reading from the first line beginning with the matching user-defined label : + ``label`` (beginning with a colon (:), 8 characters maximum). - GLOBAL - Provides a global status summary. + 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: - SOLU - Provides a solution status summary. + * ``0`` - Record only the :ref:`input` command on the log (default). - PROD - Provides a product summary. + * ``1`` - Record commands in the specified secondary file as they are executed. Notes ----- - Displays various items active for the run (such as the ANSYS revision - number, Jobname, titles, units, configuration parameters, database - statistics, etc.). + + .. _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``. This command is valid in any processor. """ - return self.run(f"/STATUS,{lab}", **kwargs) + command = f"/INPUT,{fname},{ext},{dir_},{line},{log}" + return self.run(command, **kwargs) - def starstatus( - self, - par="", - imin="", - imax="", - jmin="", - jmax="", - kmin="", - kmax="", - lmin="", - lmax="", - mmin="", - mmax="", - kpri="", - **kwargs, - ): - """Lists the current parameters and abbreviations. + def cwd(self, dirpath: str = "", **kwargs): + r"""Changes the current working directory. + + Mechanical APDL Command: `/CWD `_ + + Parameters + ---------- + dirpath : str + The full path name of the new working directory. + + Notes + ----- + + .. _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 + -------- + Change MAPDL's working directory to ``"C:/temp"``. This + assumes that MAPDL running on Windows. + + >>> mapdl.cwd("C:/temp") + + MAPDL on Linux example: + + >>> mapdl.cwd("/tmp/") + """ + 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 "' + ) + return self.run(f"/CWD,'{dirpath}'", **kwargs) - APDL Command: ``*STATUS`` + def config(self, lab: str = "", val: str = "", **kwargs): + r"""Assigns values to Mechanical APDL configuration parameters. + + Mechanical APDL Command: `/CONFIG `_ 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``]. + lab : str + Configuration parameter to be changed: + + * ``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. + + * ``MXLS`` - Maximum number of lines. Default and expansion as for MXND. + + * ``MXAR`` - Maximum number of areas. Default and expansion as for MXND. + + * ``MXVL`` - Maximum number of volumes. Default and expansion as for MXND. + + * ``MXRL`` - Maximum number of sets of real constants (element attributes). Default and expansion as + for MXND. + + * ``MXCP`` - Maximum number of sets of coupled degrees of freedom. Default and expansion as for + MXND. + + * ``MXCE`` - Maximum number of constraint equations. Default and expansion as for MXND. + + * ``NOELDB`` - Option to write or not write results into the database after a solution. + + * 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. + + Default: ``VAL`` = 1000 at first encounter. + + When the maximum is exceeded, the value is not expanded. + + The NUMLV option is not supported for fast load vector generation ( ``FastLV`` = ON on the + :ref:`modcont` command). + + * ``NUMSUBLV`` - Maximum number of load vectors written on :file:`Jobname.SUB` file in + substructure/CMS generation pass. + + Default: ``VAL`` = 31 at first encounter. + + When the maximum is exceeded, the value is not expanded. + + * ``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` ). + + * 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: + + * 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. - 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. + val : str + Value (an integer number) assigned to the specified configuration parameter. - 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. + Notes + ----- + + .. _s-CONFIG_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. + 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. - 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. + Issue :ref:`config`,STAT to display current values. - 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. + Define changes before the parameter is required. - kpri - Use this field to list your primary variable labels (X, Y, Z, TIME, - etc.). + 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 = f"/CONFIG,{lab},{val}" + return self.run(command, **kwargs) - 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. + def sys(self, string: str = "", **kwargs): + r"""Passes a command string to the operating system. + + Mechanical APDL Command: `/SYS `_ + + 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( self, - string="", - arg1="", - arg2="", - arg3="", - arg4="", - arg5="", - arg6="", - arg7="", - arg8="", + string: str = "", + arg1: str = "", + arg2: str = "", + arg3: str = "", + arg4: str = "", + arg5: str = "", + arg6: str = "", + arg7: str = "", + arg8: str = "", **kwargs, ): - """Passes a command string and arguments to the operating system. + r"""Passes a command string and arguments to the operating system. - APDL Command: /SYP + Mechanical APDL Command: `/SYP `_ Parameters ---------- - string - Command string (cannot include commas). See also the /SYS 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. + 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. 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. + + .. _s-SYP_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. + 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 = "/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"/SYP,{string},{arg1},{arg2},{arg3},{arg4},{arg5},{arg6},{arg7},{arg8}" ) return self.run(command, **kwargs) - def sys(self, string="", **kwargs): - """Passes a command string to the operating system. + def slashstatus(self, lab: str = "", **kwargs): + r"""Lists the status of items for the run. - APDL Command: /SYS + Mechanical APDL Command: `/STATUS `_ 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. + lab : str + Items to list status for: + + * ``ALL`` - List all below (default). + + * ``TITLE`` - List only titles, :file:`Jobname`, and revision number. + + * ``UNITS`` - List only units. + + * ``MEM`` - List only memory data statistics. + + * ``DB`` - List only database statistics + + * ``CONFIG`` - List only configuration parameters. + + * ``GLOBAL`` - Provides a global status summary. + + * ``SOLU`` - Provides a solution status summary. + + * ``PROD`` - Provides a product summary. 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-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. """ - command = f"/SYS,{string}" + command = f"/STATUS,{lab}" return self.run(command, **kwargs) - def unpause(self, **kwargs): - """Restores use of a temporarily released product license. + def filname(self, fname: str = "", key: str = "", **kwargs): + r"""Changes the Jobname for the analysis. + + Mechanical APDL Command: `/FILNAME `_ + + Parameters + ---------- + 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. - APDL Command: UNPAUSE + 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. + + * ``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 ----- - 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. + .. _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 + `_. - For more information, see the documentation for the PAUSE command and - the ANSYS, Inc. Licensing 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 = "UNPAUSE," + command = f"/FILNAME,{fname},{key}" return self.run(command, **kwargs) From b7d185a0b59ec3c195ca1970c0fc4b338805a72c Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Tue, 6 May 2025 11:04:54 +0000 Subject: [PATCH 02/13] chore: adding changelog file 3894.documentation.md [dependabot-skip] --- doc/changelog.d/3894.documentation.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/3894.documentation.md diff --git a/doc/changelog.d/3894.documentation.md b/doc/changelog.d/3894.documentation.md new file mode 100644 index 0000000000..71ec2482d7 --- /dev/null +++ b/doc/changelog.d/3894.documentation.md @@ -0,0 +1 @@ +feat: ``session`` submodule \ No newline at end of file From d7e2653d9a2adac4b05bc528d2495f6920c8e752 Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Tue, 6 May 2025 11:06:14 +0000 Subject: [PATCH 03/13] chore: adding changelog file 3895.documentation.md [dependabot-skip] --- doc/changelog.d/3895.documentation.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/3895.documentation.md diff --git a/doc/changelog.d/3895.documentation.md b/doc/changelog.d/3895.documentation.md new file mode 100644 index 0000000000..71ec2482d7 --- /dev/null +++ b/doc/changelog.d/3895.documentation.md @@ -0,0 +1 @@ +feat: ``session`` submodule \ No newline at end of file From d270dec277f133f9315152312a10c625f5500a57 Mon Sep 17 00:00:00 2001 From: Camille <78221213+clatapie@users.noreply.github.com> Date: Fri, 23 May 2025 17:59:21 +0200 Subject: [PATCH 04/13] feat: commands ordered by name --- doc/source/mapdl_commands/session/index.rst | 8 +- .../mapdl/core/_commands/session/files.py | 588 +++---- .../core/_commands/session/list_controls.py | 108 +- .../core/_commands/session/processor_entry.py | 26 +- .../core/_commands/session/run_controls.py | 1441 ++++++++--------- src/ansys/mapdl/core/mapdl_grpc.py | 2 +- 6 files changed, 1086 insertions(+), 1087 deletions(-) diff --git a/doc/source/mapdl_commands/session/index.rst b/doc/source/mapdl_commands/session/index.rst index 3e59f940a0..9218113b63 100644 --- a/doc/source/mapdl_commands/session/index.rst +++ b/doc/source/mapdl_commands/session/index.rst @@ -6,17 +6,17 @@ Session .. list-table:: - * - :ref:`ref_run_controls` - * - :ref:`ref_processor_entry` * - :ref:`ref_files` * - :ref:`ref_list_controls` + * - :ref:`ref_run_controls` + * - :ref:`ref_processor_entry` .. toctree:: :maxdepth: 1 :hidden: - run_controls - processor_entry files list_controls + run_controls + processor_entry diff --git a/src/ansys/mapdl/core/_commands/session/files.py b/src/ansys/mapdl/core/_commands/session/files.py index 5b27d35843..475d37925f 100644 --- a/src/ansys/mapdl/core/_commands/session/files.py +++ b/src/ansys/mapdl/core/_commands/session/files.py @@ -23,57 +23,55 @@ class Files: - def lgwrite(self, fname: str = "", ext: str = "", kedit: str = "", **kwargs): - r"""Writes the database command log to a file. + def starlist(self, fname: str = "", ext: str = "", **kwargs): + r"""Displays the contents of an external, coded file. - Mechanical APDL Command: `LGWRITE `_ + 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. The file name defaults to :file:`Jobname`. + you can use all 248 characters for the file name. ext : str - Filename extension (eight-character maximum). The extension defaults to LGW if ``Fname`` and - ``Ext`` are blank. - - 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. + Filename extension (eight-character maximum). Notes ----- - .. _LGWRITE_notes: + .. _a-LIST_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:`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. + 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"LGWRITE,{fname},{ext},,{kedit}" + command = f"*LIST,{fname},{ext}" return self.run(command, **kwargs) - def starlist(self, fname: str = "", ext: str = "", **kwargs): - r"""Displays the contents of an external, coded file. + def assign( + self, ident: str = "", fname: str = "", ext: str = "", lgkey: str = "", **kwargs + ): + r"""Reassigns a file name to a Mechanical APDL file identifier. - Mechanical APDL Command: `\*LIST `_ + Mechanical APDL Command: `/ASSIGN `_ Parameters ---------- + 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, @@ -82,26 +80,63 @@ def starlist(self, fname: str = "", ext: str = "", **kwargs): 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 ----- - .. _a-LIST_notes: + .. _s-ASSIGN_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). + 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. - 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 only at the Begin level. - This command is valid in any processor. + 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 = f"*LIST,{fname},{ext}" + command = f"/ASSIGN,{ident},{fname},{ext},,{lgkey}" return self.run(command, **kwargs) - def slashrename( + def slashclog(self, fname: str = "", ext: str = "", **kwargs): + r"""Copies the session log file to a named file. + + Mechanical APDL Command: `/CLOG `_ + + Parameters + ---------- + 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 + ----- + + .. _s-CLOG_notes: + + This command is valid in any processor, but only during an interactive run. + """ + command = f"/CLOG,{fname},{ext}" + return self.run(command, **kwargs) + + def copy( self, fname1: str = "", ext1: str = "", @@ -110,25 +145,26 @@ def slashrename( distkey: str = "", **kwargs, ): - r"""Renames a file. + r"""Copies a file. - Mechanical APDL Command: `/RENAME `_ + Mechanical APDL Command: `/COPY `_ Parameters ---------- 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 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. - File name defaults to the current :file:`Jobname`. + The file name defaults to the current :file:`Jobname`. ext1 : str Filename extension (eight-character maximum). 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). + 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``. @@ -136,71 +172,198 @@ def slashrename( Filename extension (eight-character maximum). ``Ext2`` defaults to ``Ext1``. distkey : str - Key that specifies which rename operation is performed on all processes in distributed-memory - parallel mode: + Key that specifies which copy operation is performed on all processes in distributed-memory parallel + mode : - * ``0 (OFF or NO)`` - The program performs the rename operation only on the master process - (default). + * ``0 (OFF or NO)`` - The program performs the copy operation 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 copy operation locally on each process. - * ``2 or BOTH`` - The program performs the rename operation for ``Fname``. ``Ext`` on the master + * ``2 or BOTH`` - The program performs the copy operation for ``Fname``. ``Ext`` on the master process and for ``FnameN``. ``Ext`` on all processes. Notes ----- - .. _s-RENAME_notes: + .. _s-COPY_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. + 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 rename ``Fname1``. ``Ext1`` - to ``Fname2``. ``Ext2`` by default. However, when ``DistKey`` is set to 1 (or ON, or YES) or 2 (or + 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 - renamed to ``Fname2N``. ``Ext2`` by all processes, where ``N`` is the DMP process rank. For more + copied 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. """ - command = f"/RENAME,{fname1},{ext1},,{fname2},{ext2},,{distkey}" + command = f"/COPY,{fname1},{ext1},,{fname2},{ext2},,{distkey}" return self.run(command, **kwargs) - def slashclog(self, fname: str = "", ext: str = "", **kwargs): - r"""Copies the session log file to a named file. + def slashdelete(self, fname: str = "", ext: str = "", distkey: str = "", **kwargs): + r"""Deletes a file. - Mechanical APDL Command: `/CLOG `_ + Mechanical APDL Command: `/DELETE `_ Parameters ---------- 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. + 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`. ext : str Filename extension (eight-character maximum). + distkey : str + Key that specifies which file deletion action 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). + + * ``1 (ON or YES)`` - The program performs the file deletion locally on each process. + + * ``2 or BOTH`` - The program performs file deletion for ``Fname``. ``Ext`` on the master process + and for ``FnameN``. ``Ext`` on all processes. + Notes ----- + 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 + `_. + """ + command = f"/DELETE,{fname},{ext},,{distkey}" + return self.run(command, **kwargs) - .. _s-CLOG_notes: + def fclean(self, **kwargs): + r"""Deletes all local files in all processors in a distributed parallel processing run. - This command is valid in any processor, but only during an interactive run. + Mechanical APDL Command: `/FCLEAN `_ + + Notes + ----- + + .. _s-FCLEAN_notes: + + 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. """ - command = f"/CLOG,{fname},{ext}" + command = "/FCLEAN" return self.run(command, **kwargs) - def copy( + def fcomp(self, ident: str = "", level: int | str = "", **kwargs): + r"""Specifies file-compression options. + + Mechanical APDL Command: `/FCOMP `_ + + Parameters + ---------- + ident : str + Mechanical APDL file identifier. There is no default. Valid labels are: + + * ``RST`` - Results file. + + * ``DB`` - Database file. + + * ``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 + ----- + + .. _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). + + 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. + """ + command = f"/FCOMP,{ident},{level}" + return self.run(command, **kwargs) + + def slashfdele(self, ident: str = "", stat: str = "", **kwargs): + r"""Deletes a binary file after it is used. + + Mechanical APDL Command: `/FDELE `_ + + Parameters + ---------- + 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 : str + Keep or delete key: + + * ``KEEP`` - Keep this file. + + * ``DELE`` - Delete (or do not write, if not necessary) this file. + + Notes + ----- + + .. _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. + """ + command = f"/FDELE,{ident},{stat}" + return self.run(command, **kwargs) + + def slashrename( self, fname1: str = "", ext1: str = "", @@ -209,26 +372,25 @@ def copy( distkey: str = "", **kwargs, ): - r"""Copies a file. + r"""Renames a file. - Mechanical APDL Command: `/COPY `_ + Mechanical APDL Command: `/RENAME `_ Parameters ---------- 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. + 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. - The file name defaults to the current :file:`Jobname`. + File name defaults to the current :file:`Jobname`. ext1 : str Filename extension (eight-character maximum). 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. + 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``. @@ -236,35 +398,43 @@ def copy( Filename extension (eight-character maximum). ``Ext2`` defaults to ``Ext1``. distkey : str - Key that specifies which copy operation is performed on all processes in distributed-memory parallel - mode : + Key that specifies which rename operation is performed on all processes in distributed-memory + parallel mode: - * ``0 (OFF or NO)`` - The program performs the copy operation 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 copy operation locally on each process. + * ``1 (ON or YES)`` - The program performs the rename operation locally on each process. - * ``2 or BOTH`` - The program performs the copy operation for ``Fname``. ``Ext`` on the master + * ``2 or BOTH`` - The program performs the rename operation for ``Fname``. ``Ext`` on the master process and for ``FnameN``. ``Ext`` on all processes. Notes ----- - .. _s-COPY_notes: + .. _s-RENAME_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. + 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 copy ``Fname1``. ``Ext1`` to - ``Fname2``. ``Ext2`` by default. However, when ``DistKey`` is set to 1 (or ON, or YES) or 2 (or + 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 - copied to ``Fname2N``. ``Ext2`` by all processes, where ``N`` is the DMP process rank. For more + 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. """ - command = f"/COPY,{fname1},{ext1},,{fname2},{ext2},,{distkey}" + command = f"/RENAME,{fname1},{ext1},,{fname2},{ext2},,{distkey}" return self.run(command, **kwargs) def anstoaqwa( @@ -548,216 +718,46 @@ def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): command = f"ANSTOASAS,{fname},{key}" return self.run(command, **kwargs) - def assign( - self, ident: str = "", fname: str = "", ext: str = "", lgkey: str = "", **kwargs - ): - r"""Reassigns a file name to a Mechanical APDL file identifier. - - Mechanical APDL Command: `/ASSIGN `_ - - Parameters - ---------- - 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 - ----- - - .. _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 = f"/ASSIGN,{ident},{fname},{ext},,{lgkey}" - return self.run(command, **kwargs) - - def slashdelete(self, fname: str = "", ext: str = "", distkey: str = "", **kwargs): - r"""Deletes a file. + def lgwrite(self, fname: str = "", ext: str = "", kedit: str = "", **kwargs): + r"""Writes the database command log to a file. - Mechanical APDL Command: `/DELETE `_ + Mechanical APDL Command: `LGWRITE `_ Parameters ---------- fname : str File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, - you can use all 248 characters for the file name. The file name defaults to the current - :file:`Jobname`. + you can use all 248 characters for the file name. The file name defaults to :file:`Jobname`. ext : str - Filename extension (eight-character maximum). - - distkey : str - Key that specifies which file deletion action 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). - - * ``1 (ON or YES)`` - The program performs the file deletion locally on each process. - - * ``2 or BOTH`` - The program performs file deletion for ``Fname``. ``Ext`` on the master process - and for ``FnameN``. ``Ext`` on all processes. - - Notes - ----- - 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 - `_. - """ - command = f"/DELETE,{fname},{ext},,{distkey}" - return self.run(command, **kwargs) - - def slashfdele(self, ident: str = "", stat: str = "", **kwargs): - r"""Deletes a binary file after it is used. - - Mechanical APDL Command: `/FDELE `_ - - Parameters - ---------- - 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 : str - Keep or delete key: - - * ``KEEP`` - Keep this file. - - * ``DELE`` - Delete (or do not write, if not necessary) this file. - - Notes - ----- - - .. _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. - """ - command = f"/FDELE,{ident},{stat}" - return self.run(command, **kwargs) - - def fcomp(self, ident: str = "", level: int | str = "", **kwargs): - r"""Specifies file-compression options. - - Mechanical APDL Command: `/FCOMP `_ - - Parameters - ---------- - ident : str - Mechanical APDL file identifier. There is no default. Valid labels are: - - * ``RST`` - Results file. - - * ``DB`` - Database file. - - * ``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 - ----- - - .. _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). - - 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 - `_ + Filename extension (eight-character maximum). The extension defaults to LGW if ``Fname`` and + ``Ext`` are blank. - See in the `Basic Analysis Guide - `_ for more - details. + kedit : str + Flag to suppress nonessential commands: - This command is valid only at the Begin Level. - """ - command = f"/FCOMP,{ident},{level}" - return self.run(command, **kwargs) + * ``NONE`` - Do not suppress any commands (default). - def fclean(self, **kwargs): - r"""Deletes all local files in all processors in a distributed parallel processing run. + * ``COMMENT`` - Write nonessential commands as comments (starting with !). - Mechanical APDL Command: `/FCLEAN `_ + * ``REMOVE`` - Do not write nonessential commands or comments. Notes ----- - .. _s-FCLEAN_notes: - - 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. + .. _LGWRITE_notes: - .. warning:: + 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. - 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. + This command is valid in any processor. """ - command = "/FCLEAN" + command = f"LGWRITE,{fname},{ext},,{kedit}" 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 8a4d7920b7..914d11d6c1 100644 --- a/src/ansys/mapdl/core/_commands/session/list_controls.py +++ b/src/ansys/mapdl/core/_commands/session/list_controls.py @@ -23,82 +23,88 @@ class ListControls: - def golist(self, **kwargs): - r"""Reactivates the suppressed data input listing. + def com(self, comment: str = "", **kwargs): + r"""Places a comment in the output. - Mechanical APDL Command: `/GOLIST `_ + Mechanical APDL Command: `/COM `_ + + Parameters + ---------- + comment : str + Comment string, up to 75 characters. Notes ----- - .. _s-GOLIST_notes: + .. _s-COM_notes: - Reactivates printout of the data input listing suppressed with :ref:`nolist`. + 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. - This command is valid in any processor, but only within a batch run ( ``/BATCH`` ). + 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 = "/GOLIST" + command = f"/COM,{comment}" return self.run(command, **kwargs) - def gopr(self, **kwargs): + def slashgo(self, **kwargs): r"""Reactivates suppressed printout. - Mechanical APDL Command: `/GOPR `_ + Mechanical APDL Command: `/GO `_ Notes ----- - .. _s-GOPR_notes: + .. _s-GO_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. + 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 = "/GOPR" + command = "/GO" return self.run(command, **kwargs) - def slashgo(self, **kwargs): - r"""Reactivates suppressed printout. + def golist(self, **kwargs): + r"""Reactivates the suppressed data input listing. - Mechanical APDL Command: `/GO `_ + Mechanical APDL Command: `/GOLIST `_ Notes ----- - .. _s-GO_notes: + .. _s-GOLIST_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. + Reactivates printout of the data input listing suppressed with :ref:`nolist`. - This command is valid in any processor. + This command is valid in any processor, but only within a batch run ( ``/BATCH`` ). """ - command = "/GO" + command = "/GOLIST" return self.run(command, **kwargs) - def nopr(self, **kwargs): - r"""Suppresses the expanded interpreted input data listing. + def gopr(self, **kwargs): + r"""Reactivates suppressed printout. - Mechanical APDL Command: `/NOPR `_ + Mechanical APDL Command: `/GOPR `_ Notes ----- - .. _s-NOPR_notes: - - Suppresses printout of interpreted input data, including information labeled as "Notes." When this - printout is not suppressed, the data input to the analysis is echoed to the output file in an - expanded format. Printout is suppressed until a :ref:`gopr` or :ref:`slashgo` command is read. + .. _s-GOPR_notes: - 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. + 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 = "/NOPR" + command = "/GOPR" return self.run(command, **kwargs) def nolist(self, **kwargs): @@ -119,32 +125,26 @@ def nolist(self, **kwargs): command = "/NOLIST" return self.run(command, **kwargs) - def com(self, comment: str = "", **kwargs): - r"""Places a comment in the output. - - Mechanical APDL Command: `/COM `_ + def nopr(self, **kwargs): + r"""Suppresses the expanded interpreted input data listing. - Parameters - ---------- - comment : str - Comment string, up to 75 characters. + Mechanical APDL Command: `/NOPR `_ Notes ----- - .. _s-COM_notes: + .. _s-NOPR_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. + 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. - 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. + 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 anywhere. + This command is valid in any processor. """ - command = f"/COM,{comment}" + command = "/NOPR" 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 645c6f8314..88e78f8ee0 100644 --- a/src/ansys/mapdl/core/_commands/session/processor_entry.py +++ b/src/ansys/mapdl/core/_commands/session/processor_entry.py @@ -23,39 +23,39 @@ class ProcessorEntry: - def post26(self, **kwargs): - r"""Enters the time-history results postprocessor. + def post1(self, **kwargs): + r"""Enters the database results postprocessor. - Mechanical APDL Command: `/POST26 `_ + Mechanical APDL Command: `/POST1 `_ Notes ----- - .. _s-POST26_notes: + .. _s-POST1_notes: - Enters the time-history results postprocessor (POST26). + 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 = "/POST26" + command = "/POST1" return self.run(command, **kwargs) - def post1(self, **kwargs): - r"""Enters the database results postprocessor. + def post26(self, **kwargs): + r"""Enters the time-history results postprocessor. - Mechanical APDL Command: `/POST1 `_ + Mechanical APDL Command: `/POST26 `_ Notes ----- - .. _s-POST1_notes: + .. _s-POST26_notes: - Enters the general database results postprocessor (POST1). All load symbols ( :ref:`pbc`, - :ref:`psf`, or :ref:`pbf` ) are automatically turned off with this command. + Enters the time-history results postprocessor (POST26). This command is valid only at the Begin Level. """ - command = "/POST1" + command = "/POST26" return self.run(command, **kwargs) def prep7(self, **kwargs): diff --git a/src/ansys/mapdl/core/_commands/session/run_controls.py b/src/ansys/mapdl/core/_commands/session/run_controls.py index b03a9da92e..2489418ff9 100644 --- a/src/ansys/mapdl/core/_commands/session/run_controls.py +++ b/src/ansys/mapdl/core/_commands/session/run_controls.py @@ -23,24 +23,174 @@ class RunControls: - def keyw(self, **kwargs): - r"""Sets a keyword used by the GUI for context filtering (GUI). + def config(self, lab: str = "", val: str = "", **kwargs): + r"""Assigns values to Mechanical APDL configuration parameters. - Mechanical APDL Command: `KEYW `_ + Mechanical APDL Command: `/CONFIG `_ + + Parameters + ---------- + lab : str + Configuration parameter to be changed: + + * ``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. + + * ``MXLS`` - Maximum number of lines. Default and expansion as for MXND. + + * ``MXAR`` - Maximum number of areas. Default and expansion as for MXND. + + * ``MXVL`` - Maximum number of volumes. Default and expansion as for MXND. + + * ``MXRL`` - Maximum number of sets of real constants (element attributes). Default and expansion as + for MXND. + + * ``MXCP`` - Maximum number of sets of coupled degrees of freedom. Default and expansion as for + MXND. + + * ``MXCE`` - Maximum number of constraint equations. Default and expansion as for MXND. + + * ``NOELDB`` - Option to write or not write results into the database after a solution. + + * 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. + + Default: ``VAL`` = 1000 at first encounter. + + When the maximum is exceeded, the value is not expanded. + + The NUMLV option is not supported for fast load vector generation ( ``FastLV`` = ON on the + :ref:`modcont` command). + + * ``NUMSUBLV`` - Maximum number of load vectors written on :file:`Jobname.SUB` file in + substructure/CMS generation pass. + + Default: ``VAL`` = 31 at first encounter. + + When the maximum is exceeded, the value is not expanded. + + * ``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` ). + + * 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: + + * 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. + + val : str + Value (an integer number) assigned to the specified configuration parameter. Notes ----- - .. _KEYW_notes: + .. _s-CONFIG_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. + 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 = "KEYW" + command = f"/CONFIG,{lab},{val}" return self.run(command, **kwargs) + def cwd(self, dirpath: str = "", **kwargs): + r"""Changes the current working directory. + + Mechanical APDL Command: `/CWD `_ + + Parameters + ---------- + dirpath : str + The full path name of the new working directory. + + Notes + ----- + + .. _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 + -------- + Change MAPDL's working directory to ``"C:/temp"``. This + assumes that MAPDL running on Windows. + + >>> mapdl.cwd("C:/temp") + + MAPDL on Linux example: + + >>> mapdl.cwd("/tmp/") + """ + 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 "\'".' + ) + return self.run(f"/CWD,'{dirpath}'", **kwargs) + def slashexit(self, slab: str = "", fname: str = "", ext: str = "", **kwargs): r"""Stops the run and returns control to the system. @@ -84,395 +234,149 @@ def slashexit(self, slab: str = "", fname: str = "", ext: str = "", **kwargs): command = f"/EXIT,{slab},{fname},{ext}" return self.run(command, **kwargs) - def pause(self, **kwargs): - r"""Temporarily releases the current product license. + def filname(self, fname: str = "", key: str = "", **kwargs): + r"""Changes the Jobname for the analysis. - Mechanical APDL Command: `PAUSE `_ + Mechanical APDL Command: `/FILNAME `_ - Notes - ----- + Parameters + ---------- + 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. - .. _PAUSE_notes: + 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. - The :ref:`pause` command temporarily releases (or pauses) the current product license so that - another application can use it. + * ``0, OFF`` - Continue using current log, error, lock, page, and output files. - 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. + * ``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. - No other operation (other than :ref:`save` or :ref:`slashexit` ) is possible in the current - application while use of the product license is paused. + Notes + ----- - 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. + .. _s-FILNAME_notes: - For more information, see the `Ansys Licensing Guide - `_. + 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 = "PAUSE" + command = f"/FILNAME,{fname},{key}" return self.run(command, **kwargs) - def uis(self, label: str = "", value: int | str = "", **kwargs): - r"""Controls the GUI behavior. + 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. - Mechanical APDL Command: `/UIS `_ + Mechanical APDL Command: `/INPUT `_ Parameters ---------- - label : str - Behavior control key: + 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. - * ``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). + ext : str + Filename extension (eight-character maximum). - * ``MSGPOP`` - Controls which messages from the Mechanical APDL error-message subroutine are displayed in a - message dialog box. + dir_ : str + Directory path (64 characters maximum). Defaults to current directory. - * ``REPLOT`` - Controls whether or not an automatic replot occurs after functions affecting the - model are executed. + 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. - * ``ABORT`` - Controls whether or not the program displays dialog boxes to show the status of an - operation in progress and to cancel that operation. + * ``(blank), 0, or 1`` - Begins reading from the top of the file (default). - * ``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). + * ``LINE_NUMBER`` - Begins reading from the specified line number in the file. - * ``1 or ON`` - Start the GUI with background shading activated. + * ``:, label`` - Begins reading from the first line beginning with the matching user-defined label : + ``label`` (beginning with a colon (:), 8 characters maximum). - Values controlling behavior if ``Label`` = HPOP: + 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 or OFF`` - No rewrite operations are performed to compensate for items that obscure or overlay - the graphics window (default). + * ``0`` - Record only the :ref:`input` command on the log (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. + * ``1`` - Record commands in the specified secondary file as they are executed. Notes ----- - .. _s-UIS_notes: + .. _s-INPUT_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. + 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. - 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. + 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``. This command is valid in any processor. """ - command = f"/UIS,{label},{value}" + command = f"/INPUT,{fname},{ext},{dir_},{line},{log}" return self.run(command, **kwargs) - def ui( - self, - func: str = "", - type_: str = "", - format_: str = "", - screen: str = "", - color: str = "", - krev: str = "", - orient: str = "", - compress: str = "", - quality: str = "", - **kwargs, - ): - r"""Activates specified GUI dialog boxes. + def menu(self, key: str = "", **kwargs): + r"""Activates the Graphical User Interface (GUI). - Mechanical APDL Command: `/UI `_ + Mechanical APDL Command: `/MENU `_ Parameters ---------- - 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. - - 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 + key : str + Activation key: - * ``1,2,,,100`` - JPEG quality index, with 100 being the maximum quality level. + * ``ON`` - Activates the menu system (device dependent). Notes ----- - .. 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 = f"/UI,{func},{type_},{format_},{screen},{color},{krev},{orient},{compress},{quality}" - return self.run(command, **kwargs) - - def unpause(self, **kwargs): - r"""Restores use of a temporarily released product license. - - Mechanical APDL Command: `UNPAUSE `_ - - Notes - ----- + .. _s-MENU_notes: - .. _UNPAUSE_notes: + Activates the Graphical User Interface (GUI). - 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. + .. warning:: - When use of the product license is paused via the :ref:`pause` command, no other operation (other - than :ref:`save` or :ref:`slashexit` ) is possible until you issue the :ref:`unpause` command. + 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.) - For more information, see the documentation for the :ref:`pause` command and the `Ansys Licensing - Guide - `_. + This command is valid in any processor. """ - command = "UNPAUSE" + command = f"/MENU,{key}" return self.run(command, **kwargs) def mstart(self, label: str = "", key: str = "", **kwargs): @@ -530,76 +434,9 @@ def mstart(self, label: str = "", key: str = "", **kwargs): 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 = f"/MSTART,{label},{key}" - return self.run(command, **kwargs) - - def memm(self, lab: str = "", kywrd: str = "", **kwargs): - r"""Allows the current session to keep allocated memory - - Mechanical APDL Command: `MEMM `_ - - Parameters - ---------- - 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. - - * ``OFF`` - Use memory dynamically and free it up to other users after use (default). - - 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). - - Mechanical APDL Command: `/MENU `_ - - Parameters - ---------- - key : str - Activation key: - - * ``ON`` - Activates the menu system (device dependent). - - Notes - ----- - - .. _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. + This command is valid only at the Begin Level. """ - command = f"/MENU,{key}" + command = f"/MSTART,{label},{key}" return self.run(command, **kwargs) def nerr( @@ -721,446 +558,608 @@ def output(self, fname: str = "", ext: str = "", loc: str = "", **kwargs): command = f"/OUTPUT,{fname},{ext},,{loc}" return self.run(command, **kwargs) - def input( + def slashstatus(self, lab: str = "", **kwargs): + r"""Lists the status of items for the run. + + Mechanical APDL Command: `/STATUS `_ + + Parameters + ---------- + lab : str + Items to list status for: + + * ``ALL`` - List all below (default). + + * ``TITLE`` - List only titles, :file:`Jobname`, and revision number. + + * ``UNITS`` - List only units. + + * ``MEM`` - List only memory data statistics. + + * ``DB`` - List only database statistics + + * ``CONFIG`` - List only configuration parameters. + + * ``GLOBAL`` - Provides a global status summary. + + * ``SOLU`` - Provides a solution status summary. + + * ``PROD`` - Provides a product summary. + + Notes + ----- + + .. _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. + """ + command = f"/STATUS,{lab}" + return self.run(command, **kwargs) + + def syp( self, - fname: str = "", - ext: str = "", - dir_: str = "", - line: str = "", - log: int | str = "", + string: str = "", + arg1: str = "", + arg2: str = "", + arg3: str = "", + arg4: str = "", + arg5: str = "", + arg6: str = "", + arg7: str = "", + arg8: str = "", **kwargs, ): - r"""Switches the input file for the commands that follow. + r"""Passes a command string and arguments to the operating system. + + Mechanical APDL Command: `/SYP `_ + + Parameters + ---------- + 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. + + Notes + ----- + + .. _s-SYP_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. + 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 = ( + f"/SYP,{string},{arg1},{arg2},{arg3},{arg4},{arg5},{arg6},{arg7},{arg8}" + ) + return self.run(command, **kwargs) + + def sys(self, string: str = "", **kwargs): + r"""Passes a command string to the operating system. + + Mechanical APDL Command: `/SYS `_ + + 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 + ----- + + .. _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 = f"/SYS,{string}" + return self.run(command, **kwargs) + + def ui( + self, + func: str = "", + type_: str = "", + format_: str = "", + screen: str = "", + color: str = "", + krev: str = "", + orient: str = "", + compress: str = "", + quality: str = "", + **kwargs, + ): + r"""Activates specified GUI dialog boxes. + + Mechanical APDL Command: `/UI `_ + + Parameters + ---------- + 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. + + format_ : str + + * ``TIFF`` - Tagged Image File Format. + + * ``BMP`` - (PC only) Bitmap (Windows) file format. - Mechanical APDL Command: `/INPUT `_ + * ``WMF`` - (PC only) Windows Metafile format. - Parameters - ---------- - fname : str - File name and directory path (248 characters maximum, including the characters needed for the - directory path). An unspecified directory path defaults to the working directory; in this case, - you can use all 248 characters for the file name. The file name defaults to the current - :file:`Jobname` if ``Ext`` is specified. + * ``EMF`` - (PC only) Enhanced Metafile format. - ext : str - Filename extension (eight-character maximum). + * ``JPEG`` - JPEG (Joint Photographic Experts Group) file format. - dir_ : str - Directory path (64 characters maximum). Defaults to current directory. + screen : str - 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. + * ``FULL`` - Saves the entire screen in the specified format. - * ``(blank), 0, or 1`` - Begins reading from the top of the file (default). + * ``GRAPH`` - Saves only the Mechanical APDL graphic window. - * ``LINE_NUMBER`` - Begins reading from the specified line number in the file. + color : str - * ``:, label`` - Begins reading from the first line beginning with the matching user-defined label : - ``label`` (beginning with a colon (:), 8 characters maximum). + * ``MONO`` - A two color (black and white) file is saved. - 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: + * ``GRAY`` - The specified file format is saved in gray scale. - * ``0`` - Record only the :ref:`input` command on the log (default). + * ``COLOR`` - The file is saved at the specified color depth. - * ``1`` - Record commands in the specified secondary file as they are executed. + krev : str - Notes - ----- + * ``NORM`` - Saves file as shown on the screen. - .. _s-INPUT_notes: + * ``REVERSE`` - Saves file with the background color reversed. - 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. + orient : str - 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). + * ``LANDSCAPE`` - Saves file in landscape mode. - The ``Dir`` option is optional as the directory path can be included directly in ``Fname``. + * ``PORTRAIT`` - Saves file in portrait mode. - This command is valid in any processor. - """ - command = f"/INPUT,{fname},{ext},{dir_},{line},{log}" - return self.run(command, **kwargs) + compress : str - def cwd(self, dirpath: str = "", **kwargs): - r"""Changes the current working directory. + * ``YES`` - Compresses TIFF files and EPS files with TIFF preview (default). - Mechanical APDL Command: `/CWD `_ + * ``NO`` - Saves files with no compression. - Parameters - ---------- - dirpath : str - The full path name of the new working directory. + quality : str + + * ``1,2,,,100`` - JPEG quality index, with 100 being the maximum quality level. Notes ----- - .. _s-CWD_notes: + .. warning:: - 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. + This function contains specificities regarding the argument definitions. + Please refer to the `command documentation `_ + for further explanations. - Examples - -------- - Change MAPDL's working directory to ``"C:/temp"``. This - assumes that MAPDL running on Windows. + .. _s-UI_notes: - >>> mapdl.cwd("C:/temp") + Allows you to activate specified GUI dialog boxes directly in either GUI or non-GUI mode. - MAPDL on Linux example: + 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). - >>> mapdl.cwd("/tmp/") + Mechanical APDL JPEG software is based in part on the work of the Independent JPEG Group, Copyright + 1998, + Thomas G. Lane. """ - 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 "' - ) - return self.run(f"/CWD,'{dirpath}'", **kwargs) + command = f"/UI,{func},{type_},{format_},{screen},{color},{krev},{orient},{compress},{quality}" + return self.run(command, **kwargs) - def config(self, lab: str = "", val: str = "", **kwargs): - r"""Assigns values to Mechanical APDL configuration parameters. + def uis(self, label: str = "", value: int | str = "", **kwargs): + r"""Controls the GUI behavior. - Mechanical APDL Command: `/CONFIG `_ + Mechanical APDL Command: `/UIS `_ Parameters ---------- - lab : str - Configuration parameter to be changed: + label : str + Behavior control key: - * ``NORSTGM`` - Option to write or not write geometry data to the results file: + * ``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). - * When ``VAL`` = 0, write geometry data (default). - * When ``VAL`` = 1, does not write geometry data. + * ``MSGPOP`` - Controls which messages from the Mechanical APDL error-message subroutine are displayed in a + message dialog box. - Useful when complex analyses are likely to create abnormally large files. + * ``REPLOT`` - Controls whether or not an automatic replot occurs after functions affecting the + model are executed. - * ``NBUF`` - The number of buffers ( ``VAL`` = 1 to 32) per file in the solver. Default: ``VAL`` = - 4. + * ``ABORT`` - Controls whether or not the program displays dialog boxes to show the status of an + operation in progress and to cancel that operation. - * ``LOCFL`` - File open and close actions: + * ``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. - * When ``VAL`` = 0, global (default). - * When ``VAL`` = 1, local. + * ``PICK`` - Controls how graphical entities are highlighted from within the the Select menu. - Applies to :file:`File.EROT`, :file:`File.ESAV`, and :file:`FileEMAT`. + * ``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. - Typically used for large problems where locally closed files may be deleted earlier in the run via - :ref:`slashfdele`. + * ``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. - * ``SZBIO`` - Record size ( ``VAL`` = 1024 to 4194304) of binary files (in integer words). + * ``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. - Default: ``VAL`` = 16384 (system-dependent). + * ``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. - * ``FSPLIT`` - Defines split points for binary files. ``VAL`` is the file split point in megawords. + * ``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. - Default: ``VAL`` = Maximum file size for the system. + * ``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. - * ``MXND`` - Maximum number of nodes. + * ``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. - Default: ``VAL`` = 100 at first encounter. + value : int or str + Values controlling behavior if ``Label`` = BORD: - Dynamically expanded by doubling, even at first encounter, when the maximum is exceeded. + (These values control the operation according to syntax : :ref:`uis`,BORD, LEFT, MIDDLE, RIGHT ) - * ``MXEL`` - Maximum number of elements. Default and expansion as for MXND. + * ``1`` - PAN, controls dynamic translations. - * ``MXKP`` - Maximum number of keypoints. Default and expansion as for MXND. + * ``2`` - ZOOM, controls zoom, and dynamic rotation about the view vector. - * ``MXLS`` - Maximum number of lines. Default and expansion as for MXND. + * ``3`` - ROTATE, controls dynamic rotation about the screen X and Y axes. - * ``MXAR`` - Maximum number of areas. Default and expansion as for MXND. + 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. - * ``MXVL`` - Maximum number of volumes. Default and expansion as for MXND. + Values controlling behavior if ``Label`` = MSGPOP: - * ``MXRL`` - Maximum number of sets of real constants (element attributes). Default and expansion as - for MXND. + * ``0`` - All messages displayed. - * ``MXCP`` - Maximum number of sets of coupled degrees of freedom. Default and expansion as for - MXND. + * ``1`` - Only notes, warnings, and errors displayed. - * ``MXCE`` - Maximum number of constraint equations. Default and expansion as for MXND. + * ``2`` - Only warnings and errors displayed (default). - * ``NOELDB`` - Option to write or not write results into the database after a solution. + * ``3`` - Only errors displayed. - * 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. + Values controlling behavior if ``Label`` = REPLOT: - Default: ``VAL`` = 1000 at first encounter. + * ``0`` - No automatic replot. - When the maximum is exceeded, the value is not expanded. + * ``1`` - Automatic replot (default). - The NUMLV option is not supported for fast load vector generation ( ``FastLV`` = ON on the - :ref:`modcont` command). + Values controlling behavior if ``Label`` = ABORT: - * ``NUMSUBLV`` - Maximum number of load vectors written on :file:`Jobname.SUB` file in - substructure/CMS generation pass. + * ``ON`` - Display status and cancellation dialog boxes (default). - Default: ``VAL`` = 31 at first encounter. + * ``OFF`` - Do not display status and cancellation dialog boxes. - When the maximum is exceeded, the value is not expanded. + * ``1`` - Same as ON. - * ``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` ). + * ``0`` - Same as OFF. - * 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: + Values controlling behavior if ``Label`` = DYNA: - * 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. + * ``0`` - Use model edge outline when possible (default). - val : str - Value (an integer number) assigned to the specified configuration parameter. + * ``1`` - Use bounding box preview. - Notes - ----- + Values controlling behavior if ``Label`` = PICK: - .. _s-CONFIG_notes: + * ``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). - 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. + Values controlling behavior if ``Label`` = DPRO: - Issue :ref:`config`,STAT to display current values. + * ``0 or OFF`` - Do not display the dynamic prompt. - Define changes before the parameter is required. + * ``1 or ON`` - Display the dynamic prompt (default). - 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. + Values controlling behavior if ``Label`` = UNDO: - 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 = f"/CONFIG,{lab},{val}" - return self.run(command, **kwargs) + * ``0 or None`` - Do not suppress any commands (default). - def sys(self, string: str = "", **kwargs): - r"""Passes a command string to the operating system. + * ``1 or Comment`` - Write the nonessential commands to the session editor file as comments (with a + ! at the beginning). - Mechanical APDL Command: `/SYS `_ + * ``2 or Remove`` - Do not write nonessential commands or comments. - 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. + Values controlling behavior if ``Label`` = LEGE: - Notes - ----- + * ``0 or OFF`` - Start GUI with the enhanced legend off (default). - .. _s-SYS_notes: + * ``1 or ON`` - Start GUI with the enhanced legend capability activated. - 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. + Values controlling behavior if ``Label`` = PBAK: - This command is valid in any processor. - """ - command = f"/SYS,{string}" - return self.run(command, **kwargs) + * ``0 or OFF`` - Start the GUI with the no background shading (default). - def syp( - self, - string: str = "", - arg1: str = "", - arg2: str = "", - arg3: str = "", - arg4: str = "", - arg5: str = "", - arg6: str = "", - arg7: str = "", - arg8: str = "", - **kwargs, - ): - r"""Passes a command string and arguments to the operating system. + * ``1 or ON`` - Start the GUI with background shading activated. - Mechanical APDL Command: `/SYP `_ + Values controlling behavior if ``Label`` = HPOP: - Parameters - ---------- - string : str - Command string (cannot include commas). See also the :ref:`sys` command. + * ``0 or OFF`` - No rewrite operations are performed to compensate for items that obscure or overlay + the graphics window (default). - 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. + * ``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. - 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. + Notes + ----- - 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. + .. _s-UIS_notes: - 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. + 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. - 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. + 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. - 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. + This command is valid in any processor. + """ + command = f"/UIS,{label},{value}" + return self.run(command, **kwargs) - 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. + def keyw(self, **kwargs): + r"""Sets a keyword used by the GUI for context filtering (GUI). - 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. + Mechanical APDL Command: `KEYW `_ Notes ----- - .. _s-SYP_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. - 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. + .. _KEYW_notes: - This command is valid in any processor. + 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. """ - command = ( - f"/SYP,{string},{arg1},{arg2},{arg3},{arg4},{arg5},{arg6},{arg7},{arg8}" - ) + command = "KEYW" return self.run(command, **kwargs) - def slashstatus(self, lab: str = "", **kwargs): - r"""Lists the status of items for the run. + def memm(self, lab: str = "", kywrd: str = "", **kwargs): + r"""Allows the current session to keep allocated memory - Mechanical APDL Command: `/STATUS `_ + Mechanical APDL Command: `MEMM `_ Parameters ---------- lab : str - Items to list status for: + When ``Lab`` = KEEP, the memory manager's ability to acquire and keep memory is controlled by + ``Kywrd`` - * ``ALL`` - List all below (default). + kywrd : str + Turns the memory "keep" mode on or off - * ``TITLE`` - List only titles, :file:`Jobname`, and revision number. + * ``ON`` - Keep any memory allocated during the analysis. - * ``UNITS`` - List only units. + * ``OFF`` - Use memory dynamically and free it up to other users after use (default). - * ``MEM`` - List only memory data statistics. + Notes + ----- - * ``DB`` - List only database statistics + .. _MEMM_notes: - * ``CONFIG`` - List only configuration parameters. + 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. - * ``GLOBAL`` - Provides a global status summary. + 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) - * ``SOLU`` - Provides a solution status summary. + def pause(self, **kwargs): + r"""Temporarily releases the current product license. - * ``PROD`` - Provides a product summary. + Mechanical APDL Command: `PAUSE `_ Notes ----- - .. _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.). + .. _PAUSE_notes: - This command is valid in any processor. - """ - command = f"/STATUS,{lab}" - return self.run(command, **kwargs) + The :ref:`pause` command temporarily releases (or pauses) the current product license so that + another application can use it. - def filname(self, fname: str = "", key: str = "", **kwargs): - r"""Changes the Jobname for the analysis. + 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. - Mechanical APDL Command: `/FILNAME `_ + No other operation (other than :ref:`save` or :ref:`slashexit` ) is possible in the current + application while use of the product license is paused. - Parameters - ---------- - 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. + 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. - 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. + For more information, see the `Ansys Licensing Guide + `_. + """ + command = "PAUSE" + return self.run(command, **kwargs) - * ``0, OFF`` - Continue using current log, error, lock, page, and output files. + def unpause(self, **kwargs): + r"""Restores use of a temporarily released product license. - * ``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. + Mechanical APDL Command: `UNPAUSE `_ Notes ----- - .. _s-FILNAME_notes: + .. _UNPAUSE_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 - `_. + 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. - 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. + When use of the product license is paused via the :ref:`pause` command, no other operation (other + than :ref:`save` or :ref:`slashexit` ) is possible until you issue the :ref:`unpause` command. - This command is valid only at the Begin level. + For more information, see the documentation for the :ref:`pause` command and the `Ansys Licensing + Guide `_. """ - command = f"/FILNAME,{fname},{key}" + command = "UNPAUSE" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/mapdl_grpc.py b/src/ansys/mapdl/core/mapdl_grpc.py index 3a5d075a56..3d5c4d0115 100644 --- a/src/ansys/mapdl/core/mapdl_grpc.py +++ b/src/ansys/mapdl/core/mapdl_grpc.py @@ -1767,7 +1767,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 From f46fea4e4c495c5608e79f9c4c814db2bb67a76f Mon Sep 17 00:00:00 2001 From: Camille <78221213+clatapie@users.noreply.github.com> Date: Fri, 23 May 2025 18:22:04 +0200 Subject: [PATCH 05/13] feat: commands ordered by pyname --- .../mapdl/core/_commands/session/files.py | 950 +++++++++--------- .../core/_commands/session/list_controls.py | 38 +- .../core/_commands/session/processor_entry.py | 64 +- .../core/_commands/session/run_controls.py | 254 ++--- 4 files changed, 653 insertions(+), 653 deletions(-) diff --git a/src/ansys/mapdl/core/_commands/session/files.py b/src/ansys/mapdl/core/_commands/session/files.py index 475d37925f..dc436cbe1d 100644 --- a/src/ansys/mapdl/core/_commands/session/files.py +++ b/src/ansys/mapdl/core/_commands/session/files.py @@ -23,347 +23,342 @@ class Files: - def starlist(self, fname: str = "", ext: str = "", **kwargs): - r"""Displays the contents of an external, coded file. + 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: `\*LIST `_ + Mechanical APDL Command: `ANSTOAQWA `_ 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. + AQWA file name. Defaults to :file:`Jobname`. - ext : str - Filename extension (eight-character maximum). + vertaxis : str + Axis in the vertical direction: - Notes - ----- + * ``Y (or 2)`` - Global Y axis. - .. _a-LIST_notes: + * ``Z (or 3)`` - Global Z axis (default). - 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). + gc : str + Gravitational acceleration. Defaults to 9.81. - 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. + rho : str + Density of water. Defaults to 1025.0. - This command is valid in any processor. - """ - command = f"*LIST,{fname},{ext}" - return self.run(command, **kwargs) + hwl : str + Waterline height in model coordinates. Defaults to 0.0. - def assign( - self, ident: str = "", fname: str = "", ext: str = "", lgkey: str = "", **kwargs - ): - r"""Reassigns a file name to a Mechanical APDL file identifier. + diffkey : int or str + Diffracting model key: - Mechanical APDL Command: `/ASSIGN `_ + * ``0`` - Create a non-diffracting AQWA model. - Parameters - ---------- - 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 - `_ + * ``1`` - Create a diffracting AQWA model (default). - 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. + symxkey : int or str + Key indicating if model is symmetric about the global XZ plane: - ext : str - Filename extension (eight-character maximum). + * ``0`` - No symmetry about XZ plane (default). - 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 `_. + * ``1`` - Use symmetry about XZ plane. Only include (or select) half the model. - * ``BOTH`` - Reassign the file name for both the local and global files (default). + symykey : int or str + Key indicating if model is symmetric about the global YZ plane: - * ``LOCAL`` - Reassign the file name for only the local files. + * ``0`` - No symmetry about YZ plane (default). - * ``GLOBAL`` - Reassign the file name for only the global file. + * ``1`` - Use symmetry about YZ plane. Only include (or select) half the model. Notes ----- - .. _s-ASSIGN_notes: + .. _ANSTOAQWA_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 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. - This command is valid only at the Begin level. + 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. - 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. + 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. + + 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. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + 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, the application prompts you for their values. + + You must verify the completeness and accuracy of the data written. + + **AQWA-LINE Notes** + + .. _ANSTOAQWA_aqwa: + + 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. + + 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. + + 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 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 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. + + 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"/ASSIGN,{ident},{fname},{ext},,{lgkey}" + command = f"ANSTOAQWA,{fname},{vertaxis},{gc},{rho},{hwl},{diffkey},{symxkey},{symykey}" return self.run(command, **kwargs) - def slashclog(self, fname: str = "", ext: str = "", **kwargs): - r"""Copies the session log file to a named file. + def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): + r"""Creates an ASAS input file from the current Mechanical APDL model. - Mechanical APDL Command: `/CLOG `_ + Mechanical APDL Command: `ANSTOASAS `_ Parameters ---------- 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. + ASAS file name. Defaults to :file:`Jobname`. - ext : str - Filename extension (eight-character maximum). + key : int or str + Key indicating type of file to produce: + + * ``0`` - ASAS file for use by Ansys Aqwa (no loads written). Creates the file ``Fname``.asas. + + * ``1`` - ASAS file (all data written, including loads). Creates the file ``Fname``.asas. + + * ``2`` - ASAS(NL) file. Creates the file ``Fname``.asnl. Notes ----- - .. _s-CLOG_notes: - - This command is valid in any processor, but only during an interactive run. - """ - command = f"/CLOG,{fname},{ext}" - return self.run(command, **kwargs) + .. _ANSTOASAS_notes: - def copy( - self, - fname1: str = "", - ext1: str = "", - fname2: str = "", - ext2: str = "", - distkey: str = "", - **kwargs, - ): - r"""Copies a file. + 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. - Mechanical APDL Command: `/COPY `_ + **Data Written** - Parameters - ---------- - 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. + The following data is written: - The file name defaults to the current :file:`Jobname`. + * :ref:`Solution control options ` - ext1 : str - Filename extension (eight-character maximum). + * Nodes - 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. + * :ref:`Elements ` - ``Fname2`` defaults to ``Fname1``. + * :ref:`Material data ` - ext2 : str - Filename extension (eight-character maximum). ``Ext2`` defaults to ``Ext1``. + * :ref:`Geometry data ` - distkey : str - Key that specifies which copy operation is performed on all processes in distributed-memory parallel - mode : + * :ref:`Section data ` - * ``0 (OFF or NO)`` - The program performs the copy operation only on the master process (default). + * Mechanical APDL element components (ASAS sets) - * ``1 (ON or YES)`` - The program performs the copy operation locally on each process. + * :ref:`Boundary conditions ` - * ``2 or BOTH`` - The program performs the copy operation for ``Fname``. ``Ext`` on the master - process and for ``FnameN``. ``Ext`` on all processes. + * :ref:`Loads ` - Notes - ----- + * Added mass (via ``MASS21``element) - .. _s-COPY_notes: + Details are provided in the following sections. - 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. + 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. - 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) + .. _solconop: - def slashdelete(self, fname: str = "", ext: str = "", distkey: str = "", **kwargs): - r"""Deletes a file. + **Solution Control Options** - Mechanical APDL Command: `/DELETE `_ + The ASAS project name is defined as "Ansys". - Parameters - ---------- - fname : str - File name and directory path (248 characters maximum, including the characters needed for the - directory path). An unspecified directory path defaults to the working directory; in this case, - you can use all 248 characters for the file name. The file name defaults to the current - :file:`Jobname`. + The solution control options are converted as follows: - ext : str - Filename extension (eight-character maximum). + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - distkey : str - Key that specifies which file deletion action is performed on all processes in distributed-memory - parallel mode: + 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). - * ``0 (OFF or NO)`` - The program performs the file deletion only on the master process (default). + .. _elemdat: - * ``1 (ON or YES)`` - The program performs the file deletion locally on each process. + **Element Data** - * ``2 or BOTH`` - The program performs file deletion for ``Fname``. ``Ext`` on the master process - and for ``FnameN``. ``Ext`` on all processes. + 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. - Notes - ----- - 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 - `_. - """ - command = f"/DELETE,{fname},{ext},,{distkey}" - return self.run(command, **kwargs) + The element types are converted as follows: - def fclean(self, **kwargs): - r"""Deletes all local files in all processors in a distributed parallel processing run. + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - Mechanical APDL Command: `/FCLEAN `_ + .. _anstoasas_fn1: - Notes - ----- + Documentation for this archived element type appears in the `Feature Archive + `_. - .. _s-FCLEAN_notes: + .. _matdat: - 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. + **Material Data** - All :file:`.log` files except the master ( :file:`Jobname0.log` ) are deleted. + Linear isotropic material conversion is supported for ASAS and ASAS(NL). - .. warning:: + .. _geomdat: - 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. - """ - command = "/FCLEAN" - return self.run(command, **kwargs) + **Geometry Data** - def fcomp(self, ident: str = "", level: int | str = "", **kwargs): - r"""Specifies file-compression options. + The following ASAS element geometry data is supported: - Mechanical APDL Command: `/FCOMP `_ + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - Parameters - ---------- - ident : str - Mechanical APDL file identifier. There is no default. Valid labels are: + 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. - * ``RST`` - Results file. + .. _sectdat: - * ``DB`` - Database file. + **Section Data** - * ``RNNN`` - Restart file. + No user sections are generated if AQWA-WAVE data is selected. - * ``OSAV`` - File created during a nonlinear analysis that contains a copy of :file:`ESAV` file from - the last converged substep. + The following sections are converted for ASAS and ASAS(NL): - level : int or str - Compression level: + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - * ``SPARSE`` - Use a sparsification scheme for file compression (default). + .. _boundcon: - * ``0`` - No file compression occurs. + **Boundary Conditions** - * ``n`` - A zlib-based file compression occurs using level number ``n``, which ranges from 1 to 5. + The following boundary conditions are converted for ASAS and ASAS(NL): - Notes - ----- + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - .. _s-FCOMP_notes: + .. _loadsasas: - 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). + **Loads** - 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 - `_ + 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. - See in the `Basic Analysis Guide - `_ for more - details. + 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 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. """ - command = f"/FCOMP,{ident},{level}" + command = f"ANSTOASAS,{fname},{key}" return self.run(command, **kwargs) - def slashfdele(self, ident: str = "", stat: str = "", **kwargs): - r"""Deletes a binary file after it is used. + def assign( + self, ident: str = "", fname: str = "", ext: str = "", lgkey: str = "", **kwargs + ): + r"""Reassigns a file name to a Mechanical APDL file identifier. - Mechanical APDL Command: `/FDELE `_ + Mechanical APDL Command: `/ASSIGN `_ Parameters ---------- 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. + 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 + `_ - stat : str - Keep or delete key: + 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. - * ``KEEP`` - Keep this file. + ext : str + Filename extension (eight-character maximum). - * ``DELE`` - Delete (or do not write, if not necessary) this file. + 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 `_. - Notes - ----- + * ``BOTH`` - Reassign the file name for both the local and global files (default). - .. _s-FDELE_notes: + * ``LOCAL`` - Reassign the file name for only the local files. - Deletes as soon as possible (or prevents writing) a binary file created by Mechanical APDL to save - space. + * ``GLOBAL`` - Reassign the file name for only the global file. - .. warning:: + Notes + ----- + + .. _s-ASSIGN_notes: - Deleting files that are necessary for the next substep, load step, or analysis will prevent - continuation of the run. + 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 = f"/FDELE,{ident},{stat}" + command = f"/ASSIGN,{ident},{fname},{ext},,{lgkey}" return self.run(command, **kwargs) - def slashrename( + def copy( self, fname1: str = "", ext1: str = "", @@ -372,25 +367,26 @@ def slashrename( distkey: str = "", **kwargs, ): - r"""Renames a file. + r"""Copies a file. - Mechanical APDL Command: `/RENAME `_ + Mechanical APDL Command: `/COPY `_ Parameters ---------- 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 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. - File name defaults to the current :file:`Jobname`. + The file name defaults to the current :file:`Jobname`. ext1 : str Filename extension (eight-character maximum). 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). + 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``. @@ -398,366 +394,370 @@ def slashrename( Filename extension (eight-character maximum). ``Ext2`` defaults to ``Ext1``. distkey : str - Key that specifies which rename operation is performed on all processes in distributed-memory - parallel mode: + Key that specifies which copy operation is performed on all processes in distributed-memory parallel + mode : - * ``0 (OFF or NO)`` - The program performs the rename operation only on the master process - (default). + * ``0 (OFF or NO)`` - The program performs the copy operation 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 copy operation locally on each process. - * ``2 or BOTH`` - The program performs the rename operation for ``Fname``. ``Ext`` on the master + * ``2 or BOTH`` - The program performs the copy operation for ``Fname``. ``Ext`` on the master process and for ``FnameN``. ``Ext`` on all processes. Notes ----- - .. _s-RENAME_notes: + .. _s-COPY_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. + 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 rename ``Fname1``. ``Ext1`` - to ``Fname2``. ``Ext2`` by default. However, when ``DistKey`` is set to 1 (or ON, or YES) or 2 (or + 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 - renamed to ``Fname2N``. ``Ext2`` by all processes, where ``N`` is the DMP process rank. For more + copied 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. """ - command = f"/RENAME,{fname1},{ext1},,{fname2},{ext2},,{distkey}" + command = f"/COPY,{fname1},{ext1},,{fname2},{ext2},,{distkey}" return self.run(command, **kwargs) - 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. + def fclean(self, **kwargs): + r"""Deletes all local files in all processors in a distributed parallel processing run. - Mechanical APDL Command: `ANSTOAQWA `_ + Mechanical APDL Command: `/FCLEAN `_ - Parameters - ---------- - fname : str - AQWA file name. Defaults to :file:`Jobname`. + Notes + ----- - vertaxis : str - Axis in the vertical direction: + .. _s-FCLEAN_notes: - * ``Y (or 2)`` - Global Y axis. + 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. - * ``Z (or 3)`` - Global Z axis (default). + All :file:`.log` files except the master ( :file:`Jobname0.log` ) are deleted. - gc : str - Gravitational acceleration. Defaults to 9.81. + .. warning:: - rho : str - Density of water. Defaults to 1025.0. + 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. + """ + command = "/FCLEAN" + return self.run(command, **kwargs) - hwl : str - Waterline height in model coordinates. Defaults to 0.0. + def fcomp(self, ident: str = "", level: int | str = "", **kwargs): + r"""Specifies file-compression options. - diffkey : int or str - Diffracting model key: + Mechanical APDL Command: `/FCOMP `_ - * ``0`` - Create a non-diffracting AQWA model. + Parameters + ---------- + ident : str + Mechanical APDL file identifier. There is no default. Valid labels are: - * ``1`` - Create a diffracting AQWA model (default). + * ``RST`` - Results file. - symxkey : int or str - Key indicating if model is symmetric about the global XZ plane: + * ``DB`` - Database file. - * ``0`` - No symmetry about XZ plane (default). + * ``RNNN`` - Restart file. - * ``1`` - Use symmetry about XZ plane. Only include (or select) half the model. + * ``OSAV`` - File created during a nonlinear analysis that contains a copy of :file:`ESAV` file from + the last converged substep. - symykey : int or str - Key indicating if model is symmetric about the global YZ plane: + level : int or str + Compression level: - * ``0`` - No symmetry about YZ plane (default). + * ``SPARSE`` - Use a sparsification scheme for file compression (default). - * ``1`` - Use symmetry about YZ plane. Only include (or select) half the model. + * ``0`` - No file compression occurs. + + * ``n`` - A zlib-based file compression occurs using level number ``n``, which ranges from 1 to 5. Notes ----- - .. _ANSTOAQWA_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, 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 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. - - This command contains some tables and extra information which can be inspected in the original - documentation pointed above. - - 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, the application prompts you for their values. - - You must verify the completeness and accuracy of the data written. - - **AQWA-LINE Notes** - - .. _ANSTOAQWA_aqwa: - - 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. - - 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. + .. _s-FCOMP_notes: - 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. + 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). - 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. + 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 + `_ - 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. + See in the `Basic Analysis Guide + `_ for more + details. - 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. + This command is valid only at the Begin Level. """ - command = f"ANSTOAQWA,{fname},{vertaxis},{gc},{rho},{hwl},{diffkey},{symxkey},{symykey}" + command = f"/FCOMP,{ident},{level}" return self.run(command, **kwargs) - def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): - r"""Creates an ASAS input file from the current Mechanical APDL model. + def lgwrite(self, fname: str = "", ext: str = "", kedit: str = "", **kwargs): + r"""Writes the database command log to a file. - Mechanical APDL Command: `ANSTOASAS `_ + Mechanical APDL Command: `LGWRITE `_ Parameters ---------- fname : str - ASAS file name. Defaults to :file:`Jobname`. - - key : int or str - Key indicating type of file to produce: + 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`. - * ``0`` - ASAS file for use by Ansys Aqwa (no loads written). Creates the file ``Fname``.asas. + ext : str + Filename extension (eight-character maximum). The extension defaults to LGW if ``Fname`` and + ``Ext`` are blank. - * ``1`` - ASAS file (all data written, including loads). Creates the file ``Fname``.asas. + kedit : str + Flag to suppress nonessential commands: - * ``2`` - ASAS(NL) file. Creates the file ``Fname``.asnl. + * ``NONE`` - Do not suppress any commands (default). - Notes - ----- + * ``COMMENT`` - Write nonessential commands as comments (starting with !). - .. _ANSTOASAS_notes: + * ``REMOVE`` - Do not write nonessential commands or comments. - 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. + Notes + ----- - **Data Written** + .. _LGWRITE_notes: - The following data is written: + 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. - * :ref:`Solution control options ` + This command is valid in any processor. + """ + command = f"LGWRITE,{fname},{ext},,{kedit}" + return self.run(command, **kwargs) - * Nodes + def slashclog(self, fname: str = "", ext: str = "", **kwargs): + r"""Copies the session log file to a named file. - * :ref:`Elements ` + Mechanical APDL Command: `/CLOG `_ - * :ref:`Material data ` + Parameters + ---------- + 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. - * :ref:`Geometry data ` + ext : str + Filename extension (eight-character maximum). - * :ref:`Section data ` + Notes + ----- - * Mechanical APDL element components (ASAS sets) + .. _s-CLOG_notes: - * :ref:`Boundary conditions ` + This command is valid in any processor, but only during an interactive run. + """ + command = f"/CLOG,{fname},{ext}" + return self.run(command, **kwargs) - * :ref:`Loads ` + def slashdelete(self, fname: str = "", ext: str = "", distkey: str = "", **kwargs): + r"""Deletes a file. - * Added mass (via ``MASS21``element) + Mechanical APDL Command: `/DELETE `_ - Details are provided in the following sections. + Parameters + ---------- + fname : str + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, + you can use all 248 characters for the file name. The file name defaults to the current + :file:`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. + ext : str + Filename extension (eight-character maximum). - .. _solconop: + distkey : str + Key that specifies which file deletion action is performed on all processes in distributed-memory + parallel mode: - **Solution Control Options** + * ``0 (OFF or NO)`` - The program performs the file deletion only on the master process (default). - The ASAS project name is defined as "Ansys". + * ``1 (ON or YES)`` - The program performs the file deletion locally on each process. - The solution control options are converted as follows: + * ``2 or BOTH`` - The program performs file deletion for ``Fname``. ``Ext`` on the master process + and for ``FnameN``. ``Ext`` on all processes. - This command contains some tables and extra information which can be inspected in the original - documentation pointed above. + Notes + ----- + 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 + `_. + """ + command = f"/DELETE,{fname},{ext},,{distkey}" + return self.run(command, **kwargs) - 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). + def slashfdele(self, ident: str = "", stat: str = "", **kwargs): + r"""Deletes a binary file after it is used. - .. _elemdat: + Mechanical APDL Command: `/FDELE `_ - **Element Data** + Parameters + ---------- + 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. - 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. + stat : str + Keep or delete key: - The element types are converted as follows: + * ``KEEP`` - Keep this file. - This command contains some tables and extra information which can be inspected in the original - documentation pointed above. + * ``DELE`` - Delete (or do not write, if not necessary) this file. - .. _anstoasas_fn1: + Notes + ----- - Documentation for this archived element type appears in the `Feature Archive - `_. + .. _s-FDELE_notes: - .. _matdat: + Deletes as soon as possible (or prevents writing) a binary file created by Mechanical APDL to save + space. - **Material Data** + .. warning:: - Linear isotropic material conversion is supported for ASAS and ASAS(NL). + Deleting files that are necessary for the next substep, load step, or analysis will prevent + continuation of the run. - .. _geomdat: + This command is valid only at the Begin level. + """ + command = f"/FDELE,{ident},{stat}" + return self.run(command, **kwargs) - **Geometry Data** + def slashrename( + self, + fname1: str = "", + ext1: str = "", + fname2: str = "", + ext2: str = "", + distkey: str = "", + **kwargs, + ): + r"""Renames a file. - The following ASAS element geometry data is supported: + Mechanical APDL Command: `/RENAME `_ - This command contains some tables and extra information which can be inspected in the original - documentation pointed above. + Parameters + ---------- + 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. - 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. + File name defaults to the current :file:`Jobname`. - .. _sectdat: + ext1 : str + Filename extension (eight-character maximum). - **Section Data** + 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). - No user sections are generated if AQWA-WAVE data is selected. + ``Fname2`` defaults to ``Fname1``. - The following sections are converted for ASAS and ASAS(NL): + ext2 : str + Filename extension (eight-character maximum). ``Ext2`` defaults to ``Ext1``. - This command contains some tables and extra information which can be inspected in the original - documentation pointed above. + distkey : str + Key that specifies which rename operation is performed on all processes in distributed-memory + parallel mode: - .. _boundcon: + * ``0 (OFF or NO)`` - The program performs the rename operation only on the master process + (default). - **Boundary Conditions** + * ``1 (ON or YES)`` - The program performs the rename operation locally on each process. - The following boundary conditions are converted for ASAS and ASAS(NL): + * ``2 or BOTH`` - The program performs the rename operation for ``Fname``. ``Ext`` on the master + process and for ``FnameN``. ``Ext`` on all processes. - This command contains some tables and extra information which can be inspected in the original - documentation pointed above. + Notes + ----- - .. _loadsasas: + .. _s-RENAME_notes: - **Loads** + 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. - 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. + 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 + `_. - 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: + Renaming across system partitions may be internally done by a copy and delete operation on some + systems. - This command contains some tables and extra information which can be inspected in the original - documentation pointed above. + This command is valid only at the Begin level. """ - command = f"ANSTOASAS,{fname},{key}" + command = f"/RENAME,{fname1},{ext1},,{fname2},{ext2},,{distkey}" return self.run(command, **kwargs) - def lgwrite(self, fname: str = "", ext: str = "", kedit: str = "", **kwargs): - r"""Writes the database command log to a file. + def starlist(self, fname: str = "", ext: str = "", **kwargs): + r"""Displays the contents of an external, coded file. - Mechanical APDL Command: `LGWRITE `_ + 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. The file name defaults to :file:`Jobname`. + you can use all 248 characters for the file name. ext : str - Filename extension (eight-character maximum). The extension defaults to LGW if ``Fname`` and - ``Ext`` are blank. - - 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. + Filename extension (eight-character maximum). Notes ----- - .. _LGWRITE_notes: + .. _a-LIST_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:`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. + 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"LGWRITE,{fname},{ext},,{kedit}" + 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 914d11d6c1..eadc78821c 100644 --- a/src/ansys/mapdl/core/_commands/session/list_controls.py +++ b/src/ansys/mapdl/core/_commands/session/list_controls.py @@ -53,25 +53,6 @@ def com(self, comment: str = "", **kwargs): command = f"/COM,{comment}" 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 = "/GO" - return self.run(command, **kwargs) - def golist(self, **kwargs): r"""Reactivates the suppressed data input listing. @@ -148,3 +129,22 @@ def nopr(self, **kwargs): """ 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 = "/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 88e78f8ee0..ec1fca7c85 100644 --- a/src/ansys/mapdl/core/_commands/session/processor_entry.py +++ b/src/ansys/mapdl/core/_commands/session/processor_entry.py @@ -23,6 +23,38 @@ class ProcessorEntry: + def finish(self, **kwargs): + r"""Exits normally from a processor. + + Mechanical APDL Command: `FINISH `_ + + Notes + ----- + + .. _FINISH_notes: + + This command exits any of the Mechanical APDL processors. + + 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.) + + If exiting POST1 or POST26: + + * 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). + + * 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. + + See :ref:`quit` for an alternate processor exit command. + + 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): r"""Enters the database results postprocessor. @@ -108,35 +140,3 @@ def slashsolu(self, **kwargs): """ command = "/SOLU" return self.run(command, **kwargs) - - def finish(self, **kwargs): - r"""Exits normally from a processor. - - Mechanical APDL Command: `FINISH `_ - - Notes - ----- - - .. _FINISH_notes: - - This command exits any of the Mechanical APDL processors. - - 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.) - - If exiting POST1 or POST26: - - * 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). - - * 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. - - See :ref:`quit` for an alternate processor exit command. - - This command is valid in any processor. This command is not valid at the Begin level. - """ - command = "FINISH" - 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 2489418ff9..a376c5fb6a 100644 --- a/src/ansys/mapdl/core/_commands/session/run_controls.py +++ b/src/ansys/mapdl/core/_commands/session/run_controls.py @@ -191,49 +191,6 @@ def cwd(self, dirpath: str = "", **kwargs): ) return self.run(f"/CWD,'{dirpath}'", **kwargs) - def slashexit(self, slab: str = "", fname: str = "", ext: str = "", **kwargs): - r"""Stops the run and returns control to the system. - - Mechanical APDL Command: `/EXIT `_ - - Parameters - ---------- - slab : str - Mode for saving the database: - - * ``MODEL`` - Save the model data (solid model, finite element model, loadings, etc.) only - (default). - - * ``SOLU`` - Save the model data and the solution data (nodal and element results). - - * ``ALL`` - Save the model data, solution data and post data (element tables, path results, etc.) - - * ``NOSAVE`` - Do not save any data on :file:`File.DB` (an existing DB file will not be - overwritten). - - fname : str - File name and directory path (248 characters maximum, including the characters needed for the - directory path). An unspecified directory path defaults to the working directory; in this case, - you can use all 248 characters for the file name. The file name, defaults to :file:`Jobname`. - - ext : str - Filename extension (eight-character maximum). The extension defaults to DB if ``Fname`` is - blank. - - Notes - ----- - - .. _s-EXIT_notes: - - The current database information may be written on :file:`File.DB` or a named file. If - :file:`File.DB` already exists, a backup file ( :file:`File.DBB` ) will also be written whenever a - new :file:`File.DB` is written. - - This command is valid in any processor. Issuing this command at any point will exit the program. - """ - command = f"/EXIT,{slab},{fname},{ext}" - return self.run(command, **kwargs) - def filname(self, fname: str = "", key: str = "", **kwargs): r"""Changes the Jobname for the analysis. @@ -349,6 +306,61 @@ def input( 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). + + 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. + """ + command = "KEYW" + return self.run(command, **kwargs) + + def memm(self, lab: str = "", kywrd: str = "", **kwargs): + r"""Allows the current session to keep allocated memory + + Mechanical APDL Command: `MEMM `_ + + Parameters + ---------- + 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. + + * ``OFF`` - Use memory dynamically and free it up to other users after use (default). + + 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). @@ -558,6 +570,78 @@ def output(self, fname: str = "", ext: str = "", loc: str = "", **kwargs): command = f"/OUTPUT,{fname},{ext},,{loc}" return self.run(command, **kwargs) + def pause(self, **kwargs): + r"""Temporarily releases the current product license. + + Mechanical APDL Command: `PAUSE `_ + + Notes + ----- + + .. _PAUSE_notes: + + The :ref:`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 :ref:`pause` command via the command line. + + No other operation (other than :ref:`save` or :ref:`slashexit` ) is possible in the current + application while use of the product license is paused. + + 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" + return self.run(command, **kwargs) + + def slashexit(self, slab: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Stops the run and returns control to the system. + + Mechanical APDL Command: `/EXIT `_ + + Parameters + ---------- + slab : str + Mode for saving the database: + + * ``MODEL`` - Save the model data (solid model, finite element model, loadings, etc.) only + (default). + + * ``SOLU`` - Save the model data and the solution data (nodal and element results). + + * ``ALL`` - Save the model data, solution data and post data (element tables, path results, etc.) + + * ``NOSAVE`` - Do not save any data on :file:`File.DB` (an existing DB file will not be + overwritten). + + fname : str + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, + you can use all 248 characters for the file name. The file name, defaults to :file:`Jobname`. + + ext : str + Filename extension (eight-character maximum). The extension defaults to DB if ``Fname`` is + blank. + + Notes + ----- + + .. _s-EXIT_notes: + + The current database information may be written on :file:`File.DB` or a named file. If + :file:`File.DB` already exists, a backup file ( :file:`File.DBB` ) will also be written whenever a + new :file:`File.DB` is written. + + This command is valid in any processor. Issuing this command at any point will exit the program. + """ + command = f"/EXIT,{slab},{fname},{ext}" + return self.run(command, **kwargs) + def slashstatus(self, lab: str = "", **kwargs): r"""Lists the status of items for the run. @@ -1058,90 +1142,6 @@ def uis(self, label: str = "", value: int | str = "", **kwargs): command = f"/UIS,{label},{value}" return self.run(command, **kwargs) - def keyw(self, **kwargs): - r"""Sets a keyword used by the GUI for context filtering (GUI). - - 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. - """ - command = "KEYW" - return self.run(command, **kwargs) - - def memm(self, lab: str = "", kywrd: str = "", **kwargs): - r"""Allows the current session to keep allocated memory - - Mechanical APDL Command: `MEMM `_ - - Parameters - ---------- - 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. - - * ``OFF`` - Use memory dynamically and free it up to other users after use (default). - - 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 pause(self, **kwargs): - r"""Temporarily releases the current product license. - - Mechanical APDL Command: `PAUSE `_ - - Notes - ----- - - .. _PAUSE_notes: - - The :ref:`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 :ref:`pause` command via the command line. - - No other operation (other than :ref:`save` or :ref:`slashexit` ) is possible in the current - application while use of the product license is paused. - - 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" - return self.run(command, **kwargs) - def unpause(self, **kwargs): r"""Restores use of a temporarily released product license. From d3153d76034b36bd18a4f3a2b0fdabd56a693a99 Mon Sep 17 00:00:00 2001 From: Camille <78221213+clatapie@users.noreply.github.com> Date: Fri, 23 May 2025 19:19:12 +0200 Subject: [PATCH 06/13] fix: removing ``slashexit`` + commenting ``mypy`` as it is not working --- .pre-commit-config.yaml | 10 ++-- .../mapdl_commands/session/run_controls.rst | 1 - .../core/_commands/session/processor_entry.py | 2 +- .../core/_commands/session/run_controls.py | 49 ++----------------- 4 files changed, 9 insertions(+), 53 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b02f569fb5..c74fae481b 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -14,11 +14,11 @@ ci: repos: -- repo: https://github.com/pre-commit/mirrors-mypy - rev: v1.15.0 - hooks: - - id: mypy - args: [ --follow-imports=silent, --config-file=pyproject.toml] +# - repo: https://github.com/pre-commit/mirrors-mypy +# rev: v1.15.0 +# hooks: +# - id: mypy +# args: [ --follow-imports=silent, --config-file=pyproject.toml] - repo: https://github.com/ansys/pre-commit-hooks rev: v0.5.2 diff --git a/doc/source/mapdl_commands/session/run_controls.rst b/doc/source/mapdl_commands/session/run_controls.rst index 8169e9157c..d3fe196843 100644 --- a/doc/source/mapdl_commands/session/run_controls.rst +++ b/doc/source/mapdl_commands/session/run_controls.rst @@ -26,7 +26,6 @@ RunControls RunControls.nerr RunControls.output RunControls.pause - RunControls.slashexit RunControls.slashstatus RunControls.syp RunControls.sys diff --git a/src/ansys/mapdl/core/_commands/session/processor_entry.py b/src/ansys/mapdl/core/_commands/session/processor_entry.py index ec1fca7c85..7614c6b2e1 100644 --- a/src/ansys/mapdl/core/_commands/session/processor_entry.py +++ b/src/ansys/mapdl/core/_commands/session/processor_entry.py @@ -119,7 +119,7 @@ def quit(self, **kwargs): 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 :ref:`slashexit` command to terminate the run. + 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. """ diff --git a/src/ansys/mapdl/core/_commands/session/run_controls.py b/src/ansys/mapdl/core/_commands/session/run_controls.py index a376c5fb6a..d23fb8c50b 100644 --- a/src/ansys/mapdl/core/_commands/session/run_controls.py +++ b/src/ansys/mapdl/core/_commands/session/run_controls.py @@ -587,8 +587,8 @@ def pause(self, **kwargs): 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. - No other operation (other than :ref:`save` or :ref:`slashexit` ) is possible in the current - application while use of the product license is paused. + No other operation (other than :ref:`save` or ``/EXIT`` ) is possible in the current application + while use of the product license is paused. 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. @@ -599,49 +599,6 @@ def pause(self, **kwargs): command = "PAUSE" return self.run(command, **kwargs) - def slashexit(self, slab: str = "", fname: str = "", ext: str = "", **kwargs): - r"""Stops the run and returns control to the system. - - Mechanical APDL Command: `/EXIT `_ - - Parameters - ---------- - slab : str - Mode for saving the database: - - * ``MODEL`` - Save the model data (solid model, finite element model, loadings, etc.) only - (default). - - * ``SOLU`` - Save the model data and the solution data (nodal and element results). - - * ``ALL`` - Save the model data, solution data and post data (element tables, path results, etc.) - - * ``NOSAVE`` - Do not save any data on :file:`File.DB` (an existing DB file will not be - overwritten). - - fname : str - File name and directory path (248 characters maximum, including the characters needed for the - directory path). An unspecified directory path defaults to the working directory; in this case, - you can use all 248 characters for the file name. The file name, defaults to :file:`Jobname`. - - ext : str - Filename extension (eight-character maximum). The extension defaults to DB if ``Fname`` is - blank. - - Notes - ----- - - .. _s-EXIT_notes: - - The current database information may be written on :file:`File.DB` or a named file. If - :file:`File.DB` already exists, a backup file ( :file:`File.DBB` ) will also be written whenever a - new :file:`File.DB` is written. - - This command is valid in any processor. Issuing this command at any point will exit the program. - """ - command = f"/EXIT,{slab},{fname},{ext}" - return self.run(command, **kwargs) - def slashstatus(self, lab: str = "", **kwargs): r"""Lists the status of items for the run. @@ -1156,7 +1113,7 @@ def unpause(self, **kwargs): 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 :ref:`slashexit` ) is possible until you issue the :ref:`unpause` command. + than :ref:`save` or ``/EXIT`` ) is possible until you issue the :ref:`unpause` command. For more information, see the documentation for the :ref:`pause` command and the `Ansys Licensing Guide `_. From 16afab37e1809a614f9a6445f295004300ae8ef1 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 27 May 2025 13:19:16 +0200 Subject: [PATCH 07/13] fix: update no abort logging and command execution in MapdlGrpc class to use `run` since the `abort` argument is not public. --- src/ansys/mapdl/core/mapdl_grpc.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/ansys/mapdl/core/mapdl_grpc.py b/src/ansys/mapdl/core/mapdl_grpc.py index 3d5c4d0115..461b82faa6 100644 --- a/src/ansys/mapdl/core/mapdl_grpc.py +++ b/src/ansys/mapdl/core/mapdl_grpc.py @@ -937,8 +937,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.""" From dd610d54716d3918beb386402eaca3de0bcd737e Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 27 May 2025 13:19:31 +0200 Subject: [PATCH 08/13] fix: uncomment mypy hook configuration in pre-commit settings --- .pre-commit-config.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c74fae481b..b02f569fb5 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -14,11 +14,11 @@ ci: repos: -# - repo: https://github.com/pre-commit/mirrors-mypy -# rev: v1.15.0 -# hooks: -# - id: mypy -# args: [ --follow-imports=silent, --config-file=pyproject.toml] +- repo: https://github.com/pre-commit/mirrors-mypy + rev: v1.15.0 + hooks: + - id: mypy + args: [ --follow-imports=silent, --config-file=pyproject.toml] - repo: https://github.com/ansys/pre-commit-hooks rev: v0.5.2 From 0ec8c46175d8f22d3c34f9010d725c1f6db8f3b3 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 27 May 2025 13:20:31 +0200 Subject: [PATCH 09/13] delete: remove duplicated fragment --- doc/changelog.d/3894.documentation.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 doc/changelog.d/3894.documentation.md diff --git a/doc/changelog.d/3894.documentation.md b/doc/changelog.d/3894.documentation.md deleted file mode 100644 index 71ec2482d7..0000000000 --- a/doc/changelog.d/3894.documentation.md +++ /dev/null @@ -1 +0,0 @@ -feat: ``session`` submodule \ No newline at end of file From 1f4797574f825d4828b54332d45be70d69b96cea Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 27 May 2025 13:55:05 +0200 Subject: [PATCH 10/13] fix: improve cwd method to validate directory paths and handle quotes in instead of the original class. --- .../mapdl/core/_commands/session/run_controls.py | 5 ----- src/ansys/mapdl/core/mapdl_extended.py | 13 ++++++++++--- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/src/ansys/mapdl/core/_commands/session/run_controls.py b/src/ansys/mapdl/core/_commands/session/run_controls.py index d23fb8c50b..dcb2c9d0f6 100644 --- a/src/ansys/mapdl/core/_commands/session/run_controls.py +++ b/src/ansys/mapdl/core/_commands/session/run_controls.py @@ -184,11 +184,6 @@ def cwd(self, dirpath: str = "", **kwargs): >>> mapdl.cwd("/tmp/") """ - 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 "\'".' - ) return self.run(f"/CWD,'{dirpath}'", **kwargs) def filname(self, fname: str = "", key: str = "", **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) From f9eea4ed7ca990210ff703bb43dda7c7498ca697 Mon Sep 17 00:00:00 2001 From: Camille <78221213+clatapie@users.noreply.github.com> Date: Fri, 30 May 2025 18:16:51 +0200 Subject: [PATCH 11/13] feat: adding latest enhancements --- src/ansys/mapdl/core/_commands/session/files.py | 10 +++++----- src/ansys/mapdl/core/_commands/session/run_controls.py | 9 ++++++++- 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/src/ansys/mapdl/core/_commands/session/files.py b/src/ansys/mapdl/core/_commands/session/files.py index dc436cbe1d..c60479c084 100644 --- a/src/ansys/mapdl/core/_commands/session/files.py +++ b/src/ansys/mapdl/core/_commands/session/files.py @@ -97,8 +97,8 @@ def anstoaqwa( no diffracting elements at the waterline, which will severely reduce the accuracy of the diffraction analysis. - 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 + 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. @@ -206,7 +206,7 @@ def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): * :ref:`Loads ` - * Added mass (via ``MASS21``element) + * Added mass (via ``MASS21`` element) Details are provided in the following sections. @@ -294,8 +294,8 @@ def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): 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. + 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 diff --git a/src/ansys/mapdl/core/_commands/session/run_controls.py b/src/ansys/mapdl/core/_commands/session/run_controls.py index dcb2c9d0f6..34c5dd6737 100644 --- a/src/ansys/mapdl/core/_commands/session/run_controls.py +++ b/src/ansys/mapdl/core/_commands/session/run_controls.py @@ -20,6 +20,8 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. +from ansys.mapdl.core.errors import MapdlRuntimeError + class RunControls: @@ -184,6 +186,11 @@ def cwd(self, dirpath: str = "", **kwargs): >>> mapdl.cwd("/tmp/") """ + 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 "\'".' + ) return self.run(f"/CWD,'{dirpath}'", **kwargs) def filname(self, fname: str = "", key: str = "", **kwargs): @@ -262,7 +269,7 @@ def input( * ``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`` - Begins reading from the first line beginning with the matching user-defined label : ``label`` (beginning with a colon (:), 8 characters maximum). log : int or str From b20d38210d7d358f9abbba267d2bdbdade66136b Mon Sep 17 00:00:00 2001 From: Camille <78221213+clatapie@users.noreply.github.com> Date: Tue, 3 Jun 2025 14:41:27 +0200 Subject: [PATCH 12/13] feat: applying latest ``pyconverter-xml2py`` changes --- src/ansys/mapdl/core/_commands/session/files.py | 16 ++++++++-------- .../mapdl/core/_commands/session/run_controls.py | 4 ++-- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/src/ansys/mapdl/core/_commands/session/files.py b/src/ansys/mapdl/core/_commands/session/files.py index c60479c084..44fe591c66 100644 --- a/src/ansys/mapdl/core/_commands/session/files.py +++ b/src/ansys/mapdl/core/_commands/session/files.py @@ -215,7 +215,7 @@ def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): .. _solconop: - **Solution Control Options** + **Solution Control Options** The ASAS project name is defined as "Ansys". @@ -230,7 +230,7 @@ def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): .. _elemdat: - **Element Data** + **Element Data** 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 @@ -250,13 +250,13 @@ def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): .. _matdat: - **Material Data** + **Material Data** Linear isotropic material conversion is supported for ASAS and ASAS(NL). .. _geomdat: - **Geometry Data** + **Geometry Data** The following ASAS element geometry data is supported: @@ -268,7 +268,7 @@ def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): .. _sectdat: - **Section Data** + **Section Data** No user sections are generated if AQWA-WAVE data is selected. @@ -279,7 +279,7 @@ def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): .. _boundcon: - **Boundary Conditions** + **Boundary Conditions** The following boundary conditions are converted for ASAS and ASAS(NL): @@ -288,7 +288,7 @@ def anstoasas(self, fname: str = "", key: int | str = "", **kwargs): .. _loadsasas: - **Loads** + **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 @@ -495,7 +495,7 @@ def fcomp(self, ident: str = "", level: int | str = "", **kwargs): :ref:`set` command or the :ref:`resume` command). 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 + 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 `_ diff --git a/src/ansys/mapdl/core/_commands/session/run_controls.py b/src/ansys/mapdl/core/_commands/session/run_controls.py index 34c5dd6737..18742071bc 100644 --- a/src/ansys/mapdl/core/_commands/session/run_controls.py +++ b/src/ansys/mapdl/core/_commands/session/run_controls.py @@ -288,7 +288,7 @@ def input( 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 + 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) @@ -840,7 +840,7 @@ def ui( .. _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: + 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. From 009cfda504eee9c6f97d06f3a2305fc9dce2f529 Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Tue, 3 Jun 2025 15:25:08 +0000 Subject: [PATCH 13/13] chore: adding changelog file 3895.miscellaneous.md [dependabot-skip] --- doc/changelog.d/3895.documentation.md | 1 - doc/changelog.d/3895.miscellaneous.md | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) delete mode 100644 doc/changelog.d/3895.documentation.md create mode 100644 doc/changelog.d/3895.miscellaneous.md diff --git a/doc/changelog.d/3895.documentation.md b/doc/changelog.d/3895.documentation.md deleted file mode 100644 index 71ec2482d7..0000000000 --- a/doc/changelog.d/3895.documentation.md +++ /dev/null @@ -1 +0,0 @@ -feat: ``session`` submodule \ No newline at end of file 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