diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 739a29436b..9e7026f6a8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -56,12 +56,12 @@ repos: hooks: - id: flake8 -- repo: https://github.com/codespell-project/codespell - rev: v2.3.0 - hooks: - - id: codespell - args: ["--toml", "pyproject.toml"] - additional_dependencies: ["tomli"] +# - repo: https://github.com/codespell-project/codespell +# rev: v2.3.0 +# hooks: +# - id: codespell +# args: ["--toml", "pyproject.toml"] +# additional_dependencies: ["tomli"] # - repo: https://github.com/pycqa/pydocstyle # rev: 6.1.1 diff --git a/doc/changelog.d/3385.added.md b/doc/changelog.d/3385.added.md new file mode 100644 index 0000000000..468e6a20ea --- /dev/null +++ b/doc/changelog.d/3385.added.md @@ -0,0 +1 @@ +feat: ``apdl`` submodule \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index d6b87ea018..4fb8fa3018 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -87,7 +87,9 @@ # -- General configuration --------------------------------------------------- extensions = [ + "ansys_sphinx_theme.extension.linkcode", "jupyter_sphinx", + "linuxdoc.rstFlatTable", "numpydoc", "sphinx.ext.autodoc", "sphinx.ext.autosummary", @@ -102,7 +104,6 @@ "sphinx_gallery.gen_gallery", "sphinxemoji.sphinxemoji", "sphinx.ext.graphviz", - "ansys_sphinx_theme.extension.linkcode", ] # Intersphinx mapping @@ -120,7 +121,8 @@ "ansys-tools-path": ("https://path.tools.docs.pyansys.com/version/stable/", None), } -suppress_warnings = ["label.*", "design.fa-build", "config.cache"] +# ref.ref warning needs to be readded when merging to main +suppress_warnings = ["label.*", "design.fa-build", "config.cache", "ref.ref"] sd_fontawesome_latex = True # Graphviz diagrams configuration diff --git a/doc/source/mapdl_commands/apdl/abbreviations.rst b/doc/source/mapdl_commands/apdl/abbreviations.rst index dd1daba0cd..8f104076c7 100644 --- a/doc/source/mapdl_commands/apdl/abbreviations.rst +++ b/doc/source/mapdl_commands/apdl/abbreviations.rst @@ -1,22 +1,21 @@ -.. _ref_abbreviations_commands_api: -************* -Abbreviations -************* +.. _ref_abbreviations: + -.. currentmodule:: ansys.mapdl.core +Abbreviations +============= -These APDL commands can be used to define abbreviations for longer commands, and to create user-defined commands. -.. note:: - It is probably easier to use Python strings instead of MAPDL - strings. +.. currentmodule:: ansys.mapdl.core._commands.apdl.abbreviations +.. autoclass:: ansys.mapdl.core._commands.apdl.abbreviations.Abbreviations .. autosummary:: - :toctree: _autosummary/ + :template: base.rst + :toctree: _autosummary + - Mapdl.abbr - Mapdl.abbres - Mapdl.abbsav - Mapdl.ucmd + Abbreviations.abbr + Abbreviations.abbres + Abbreviations.abbsav + Abbreviations.ucmd diff --git a/doc/source/mapdl_commands/apdl/array_parameters.rst b/doc/source/mapdl_commands/apdl/array_parameters.rst new file mode 100644 index 0000000000..d7cdcade7a --- /dev/null +++ b/doc/source/mapdl_commands/apdl/array_parameters.rst @@ -0,0 +1,37 @@ + +.. _ref_array_parameters: + + +ArrayParameters +=============== + + +.. currentmodule:: ansys.mapdl.core._commands.apdl.array_parameters + +.. autoclass:: ansys.mapdl.core._commands.apdl.array_parameters.ArrayParameters + +.. autosummary:: + :template: base.rst + :toctree: _autosummary + + + ArrayParameters.mfouri + ArrayParameters.mfun + ArrayParameters.moper + ArrayParameters.mwrite + ArrayParameters.sread + ArrayParameters.starvplot + ArrayParameters.starvput + ArrayParameters.toper + ArrayParameters.vabs + ArrayParameters.vcol + ArrayParameters.vcum + ArrayParameters.vfact + ArrayParameters.vfun + ArrayParameters.vitrp + ArrayParameters.vlen + ArrayParameters.vmask + ArrayParameters.voper + ArrayParameters.vscfun + ArrayParameters.vstat + ArrayParameters.vwrite diff --git a/doc/source/mapdl_commands/apdl/array_parm.rst b/doc/source/mapdl_commands/apdl/array_parm.rst deleted file mode 100644 index 2fb6e0a8bc..0000000000 --- a/doc/source/mapdl_commands/apdl/array_parm.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _ref_array_parameters_commands_api: - -**************** -Array parameters -**************** - -.. currentmodule:: ansys.mapdl.core - -These APDL commands are used to operate on parameter arrays (vectors and matrices). - -.. note:: - Many of these commands are kept for legacy compatibility. - - To interact with arrays in a more Pythonic manner, see the parameters class :ref:`ref_parameters_api` . - - For working with arrays outside of MAPDL, consider using `NumPy `_. - - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.mfouri - Mapdl.mfun - Mapdl.moper - Mapdl.mwrite - Mapdl.sread - Mapdl.toper - Mapdl.vabs - Mapdl.vcol - Mapdl.vcum - Mapdl.vfact - Mapdl.vfun - Mapdl.vitrp - Mapdl.vlen - Mapdl.vmask - Mapdl.voper - Mapdl.starvput - Mapdl.vscfun - Mapdl.vstat - Mapdl.vwrite diff --git a/doc/source/mapdl_commands/apdl/encryption_decryption.rst b/doc/source/mapdl_commands/apdl/encryption_decryption.rst new file mode 100644 index 0000000000..0a97fd24da --- /dev/null +++ b/doc/source/mapdl_commands/apdl/encryption_decryption.rst @@ -0,0 +1,21 @@ + +.. _ref_encryption_decryption: + + +EncryptionDecryption +==================== + + +.. currentmodule:: ansys.mapdl.core._commands.apdl.encryption_decryption + +.. autoclass:: ansys.mapdl.core._commands.apdl.encryption_decryption.EncryptionDecryption + +.. autosummary:: + :template: base.rst + :toctree: _autosummary + + + EncryptionDecryption.dbdecrypt + EncryptionDecryption.dbencrypt + EncryptionDecryption.decrypt + EncryptionDecryption.encrypt diff --git a/doc/source/mapdl_commands/apdl/index.rst b/doc/source/mapdl_commands/apdl/index.rst new file mode 100644 index 0000000000..96da86038a --- /dev/null +++ b/doc/source/mapdl_commands/apdl/index.rst @@ -0,0 +1,30 @@ + +.. _ref_apdl: + + +Apdl +==== + + +.. list-table:: + + * - :ref:`ref_macro_files` + * - :ref:`ref_parameter_definition` + * - :ref:`ref_matrix_operations` + * - :ref:`ref_abbreviations` + * - :ref:`ref_process_controls` + * - :ref:`ref_array_parameters` + * - :ref:`ref_encryption_decryption` + + +.. toctree:: + :maxdepth: 1 + :hidden: + + macro_files + parameter_definition + matrix_operations + abbreviations + process_controls + array_parameters + encryption_decryption diff --git a/doc/source/mapdl_commands/apdl/macro_files.rst b/doc/source/mapdl_commands/apdl/macro_files.rst index 6e7610f8ba..9de70cf512 100644 --- a/doc/source/mapdl_commands/apdl/macro_files.rst +++ b/doc/source/mapdl_commands/apdl/macro_files.rst @@ -1,35 +1,30 @@ -.. _ref_macro_files_commands_api: -*********** -Macro files -*********** +.. _ref_macro_files: -.. currentmodule:: ansys.mapdl.core -These APDL commands are used to build and execute command macros. +MacroFiles +========== -.. note:: - Most of the commands here should be replaced with Python - alternatives. For example, instead of using macros, use Python - functions. Instead of ``/MKDIR`` use ``os.mkdir``. -.. warning:: - Many of the commands here must be run in ``mapdl.non_interactive`` +.. currentmodule:: ansys.mapdl.core._commands.apdl.macro_files + +.. autoclass:: ansys.mapdl.core._commands.apdl.macro_files.MacroFiles .. autosummary:: - :toctree: _autosummary/ - - Mapdl.cfclos - Mapdl.cfopen - Mapdl.cfwrite - Mapdl.create - Mapdl.dflab - Mapdl.end - Mapdl.mkdir - Mapdl.msg - Mapdl.pmacro - Mapdl.psearch - Mapdl.rmdir - Mapdl.tee - Mapdl.ulib - Mapdl.use + :template: base.rst + :toctree: _autosummary + + + MacroFiles.cfclos + MacroFiles.cfopen + MacroFiles.cfwrite + MacroFiles.create + MacroFiles.end + MacroFiles.mkdir + MacroFiles.msg + MacroFiles.pmacro + MacroFiles.psearch + MacroFiles.rmdir + MacroFiles.slashtee + MacroFiles.ulib + MacroFiles.use diff --git a/doc/source/mapdl_commands/apdl/matrix_op.rst b/doc/source/mapdl_commands/apdl/matrix_op.rst deleted file mode 100644 index 07e35e9d9a..0000000000 --- a/doc/source/mapdl_commands/apdl/matrix_op.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _ref_matrix_operations_commands_api: - -***************** -Matrix operations -***************** - -.. currentmodule:: ansys.mapdl.core - -These APDL Math commands can be used to create, manipulate, and solve matrices. - -.. note:: - See the :ref:`mapdl_math_class_ref` for a more pythonic way of - interacting with APDLMath. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.axpy - Mapdl.comp - Mapdl.dmat - Mapdl.dot - Mapdl.eigen - Mapdl.export - Mapdl.fft - Mapdl.free - Mapdl.init - Mapdl.itengine - Mapdl.lsbac - Mapdl.lsdump - Mapdl.lsengine - Mapdl.lsfactor - Mapdl.lsrestore - Mapdl.merge - Mapdl.mult - Mapdl.nrm - Mapdl.remove - Mapdl.scal - Mapdl.smat - Mapdl.starprint - Mapdl.sort - Mapdl.vec - Mapdl.wrk diff --git a/doc/source/mapdl_commands/apdl/matrix_operations.rst b/doc/source/mapdl_commands/apdl/matrix_operations.rst new file mode 100644 index 0000000000..e0dece49a4 --- /dev/null +++ b/doc/source/mapdl_commands/apdl/matrix_operations.rst @@ -0,0 +1,45 @@ + +.. _ref_matrix_operations: + + +MatrixOperations +================ + + +.. currentmodule:: ansys.mapdl.core._commands.apdl.matrix_operations + +.. autoclass:: ansys.mapdl.core._commands.apdl.matrix_operations.MatrixOperations + +.. autosummary:: + :template: base.rst + :toctree: _autosummary + + + MatrixOperations.axpy + MatrixOperations.comp + MatrixOperations.dmat + MatrixOperations.dot + MatrixOperations.eigen + MatrixOperations.export + MatrixOperations.fft + MatrixOperations.free + MatrixOperations.hprod + MatrixOperations.init + MatrixOperations.itengine + MatrixOperations.lsbac + MatrixOperations.lsdump + MatrixOperations.lsengine + MatrixOperations.lsfactor + MatrixOperations.lsrestore + MatrixOperations.merge + MatrixOperations.mult + MatrixOperations.nrm + MatrixOperations.remove + MatrixOperations.scal + MatrixOperations.smat + MatrixOperations.starinquire + MatrixOperations.starprint + MatrixOperations.starrename + MatrixOperations.starsort + MatrixOperations.vec + MatrixOperations.wrk diff --git a/doc/source/mapdl_commands/apdl/parameter_definition.rst b/doc/source/mapdl_commands/apdl/parameter_definition.rst index 8a3b7f9171..88affe9918 100644 --- a/doc/source/mapdl_commands/apdl/parameter_definition.rst +++ b/doc/source/mapdl_commands/apdl/parameter_definition.rst @@ -1,24 +1,30 @@ -.. _ref_parameter_definition_commands_api: -******************** -Parameter definition -******************** +.. _ref_parameter_definition: -.. currentmodule:: ansys.mapdl.core -These APDL commands are used to define parameters and their values. +ParameterDefinition +=================== + + +.. currentmodule:: ansys.mapdl.core._commands.apdl.parameter_definition + +.. autoclass:: ansys.mapdl.core._commands.apdl.parameter_definition.ParameterDefinition .. autosummary:: - :toctree: _autosummary/ - - Mapdl.afun - Mapdl.dim - Mapdl.inquire - Mapdl.parres - Mapdl.parsav - Mapdl.starset - Mapdl.taxis - Mapdl.tread - Mapdl.vfill - Mapdl.starvget - Mapdl.vread + :template: base.rst + :toctree: _autosummary + + + ParameterDefinition.afun + ParameterDefinition.dim + ParameterDefinition.get + ParameterDefinition.inquire + ParameterDefinition.parres + ParameterDefinition.parsav + ParameterDefinition.starset + ParameterDefinition.starstatus + ParameterDefinition.starvget + ParameterDefinition.taxis + ParameterDefinition.tread + ParameterDefinition.vfill + ParameterDefinition.vread diff --git a/doc/source/mapdl_commands/apdl/process_controls.rst b/doc/source/mapdl_commands/apdl/process_controls.rst index 1bef331021..cf10acac95 100644 --- a/doc/source/mapdl_commands/apdl/process_controls.rst +++ b/doc/source/mapdl_commands/apdl/process_controls.rst @@ -1,34 +1,19 @@ -.. _ref_process_controls_api: -**************** -Process controls -**************** +.. _ref_process_controls: -.. currentmodule:: ansys.mapdl.core -These APDL commands can be used to control the order in which other -commands are processed. +ProcessControls +=============== -.. note:: - The following commands are not directly mapped to PyMAPDL. Use - `non-interactive` if you must use these commands, but ideally they - should be replaced by Python statements. - * ``*CYCLE`` - * ``*DO`` - * ``*DOWHILE`` - * ``*ELSE`` - * ``*ELSEIF`` - * ``*ENDDO`` - * ``*ENDIF`` - * ``*EXIT`` - * ``*GO`` - * ``*IF`` - * ``*REPEAT`` - * ``*RETURN`` +.. currentmodule:: ansys.mapdl.core._commands.apdl.process_controls +.. autoclass:: ansys.mapdl.core._commands.apdl.process_controls.ProcessControls .. autosummary:: - :toctree: _autosummary/ + :template: base.rst + :toctree: _autosummary - Mapdl.wait + + ProcessControls.starexit + ProcessControls.wait diff --git a/doc/source/mapdl_commands/index.rst b/doc/source/mapdl_commands/index.rst index 8eeba77bb3..62a6870e64 100644 --- a/doc/source/mapdl_commands/index.rst +++ b/doc/source/mapdl_commands/index.rst @@ -69,12 +69,7 @@ These commands make up the ANSYS Parametric Design Language :maxdepth: 1 :caption: APDL - apdl/parameter_definition - apdl/macro_files - apdl/abbreviations - apdl/array_parm - apdl/matrix_op - apdl/process_controls + apdl/index .. _ref_prep_commands: diff --git a/pyproject.toml b/pyproject.toml index 1aeb4c21be..1cea253558 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -82,6 +82,7 @@ doc = [ "jupyter_sphinx==0.5.3", "jupyter==1.1.1", "jupyterlab>=3.2.8", + "linuxdoc==20240924", "matplotlib==3.10.0", "nbformat==5.10.4", "numpydoc==1.8.0", @@ -157,7 +158,7 @@ omit = [ show_missing = true [tool.codespell] -skip = '*.pyc,*.txt,*.gif,*.png,*.jpg,*.js,*.html,*.doctree,*.ttf,*.woff,*.woff2,*.eot,*.mp4,*.inv,*.pickle,*.ipynb,flycheck*,./.git/*,./.hypothesis/*,*.yml,./doc/build/*,./doc/images/*,./dist/*,*~,.hypothesis*,./doc/source/examples/*,*cover,*.dat,*.mac,*.cdb,*.CDB,build,./docker/mapdl/v*,./factory/*,./ansys/mapdl/core/mapdl_functions.py,PKG-INFO,*.mypy_cache/*,./docker/mapdl/*,./_unused/*' +skip = '*.pyc,*.txt,*.gif,*.png,*.jpg,*.js,*.html,*.doctree,*.ttf,*.woff,*.woff2,*.eot,*.mp4,*.inv,*.pickle,*.ipynb,flycheck*,./.git/*,./.hypothesis/*,*.yml,./doc/build/*,./doc/images/*,./dist/*,*~,.hypothesis*,./doc/source/examples/*,*cover,*.dat,*.mac,*.cdb,*.CDB,build,./docker/mapdl/v*,./factory/*,./ansys/mapdl/core/mapdl_functions.py,PKG-INFO,*.mypy_cache/*,./docker/mapdl/*,./_unused/*,./src/ansys/mapdl/core/_commands/apdl/*' quiet-level = 3 ignore-regex=".*codespell-ignore$|NORML|POIN" ignore-words = "doc/styles/config/vocabularies/ANSYS/accept.txt" diff --git a/src/ansys/mapdl/core/_commands/apdl/__init__.py b/src/ansys/mapdl/core/_commands/apdl/__init__.py index dfdea9c457..0b2b9772bc 100644 --- a/src/ansys/mapdl/core/_commands/apdl/__init__.py +++ b/src/ansys/mapdl/core/_commands/apdl/__init__.py @@ -22,9 +22,10 @@ from . import ( abbreviations, - array_param, + array_parameters, + encryption_decryption, macro_files, - matrix_op, + matrix_operations, parameter_definition, process_controls, ) diff --git a/src/ansys/mapdl/core/_commands/apdl/abbreviations.py b/src/ansys/mapdl/core/_commands/apdl/abbreviations.py index 9958ac932a..2c139007d2 100644 --- a/src/ansys/mapdl/core/_commands/apdl/abbreviations.py +++ b/src/ansys/mapdl/core/_commands/apdl/abbreviations.py @@ -22,171 +22,167 @@ class Abbreviations: - def abbr(self, abbr="", string="", **kwargs): - """Defines an abbreviation. - APDL Command: ``*ABBR`` + def ucmd(self, cmd: str = "", srnum: str = "", **kwargs): + r"""Assigns a user-defined command name. + + Mechanical APDL Command: `/UCMD `_ Parameters ---------- - abbr - The abbreviation (up to 8 alphanumeric characters) used to - represent the string String. If Abbr is the same as an existing - ANSYS command, the abbreviation overrides. Avoid using an Abbr - which is the same as an ANSYS command. - - string - String of characters (60 maximum) represented by Abbr. - Cannot include a $ or any of the commands ``C***``, /COM, - /GOPR, /NOPR, /QUIT, /UI, or ``*END``. - - Use the ``*IF`` groups may not be abbreviated. If String - is blank, the abbreviation is deleted. To abbreviate - multiple commands, create an "unknown command" macro or - define String to execute a macro file [``*USE``] - containing the desired commands. + cmd : str + User-defined command name. Only the first four characters are significant. Must not conflict + with any Mechanical APDL command name or any user unknown-command macro name. + + srnum : str + User subroutine number (1 to 10) programmed for this command. For example, the command + :ref:`ucmd` ,MYCMD,3 will execute subroutine USER03 whenever the command **MYCMD** is entered. + Use a blank command name to disassociate ``SRNUM`` from its command. For example, :ref:`ucmd` + ,,3 removes **MYCMD** as a command. Notes ----- - Once the abbreviation Abbr is defined, you can issue it at the - beginning of a command line and follow it with a blank (or with a comma - and appended data), and the program will substitute the string String - for Abbr as the line is executed. Up to 100 abbreviations may exist at - any time and are available throughout the program. Abbreviations may be - redefined or deleted at any time. - - Use ``*STATUS`` to display the current list of abbreviations. For - abbreviations repeated with ``*REPEAT``, substitution occurs before the - repeat increments are applied. There are a number of abbreviations that - are predefined by the program (these can be deleted by using the blank - String option described above). Note that String will be written to the - File.LOG. + Assigns a user-defined command name to a user-programmable (system-dependent) subroutine. This + feature allows user-defined commands to be programmed into Mechanical APDL. Once programmed, this + command + can be input to the program like other commands, and can also be included in the Mechanical APDL + start-up + file. + + Up to 10 subroutines are available for user-defined commands (USER01 to USER10). You must have + system permission, system access, and knowledge to write, compile, and link the appropriate + subprocessors into Mechanical APDL at your site. + + All routines should be written in FORTRAN. For more information about FORTRAN compilers, refer to + either the `Ansys, Inc. Windows Installation Guide + `_ or + the Ansys, Inc. Linux Installation Guide for details specific to your platform or operating + system. + + The USER01 routine is commented and should be listed from the distribution media (system dependent) + for more details. + + Issue :ref:`ucmd` ,STAT to list all user-defined command names. + + Because a user-programmed command is a nonstandard use of the program, the verification of any + Mechanical APDL run incorporating these commands is your responsibility. In any contact with + Mechanical APDL + customer support regarding the performance of a custom version of Mechanical APDL, explicitly state + that a + user-programmable feature has been used. + + See `User-Programmable Features (UPFs) + `_ + `Guide to User-Programmable Features + `_ + + See :ref:`ulib` for another way of defining user commands. - This command is valid in any processor. + This command is valid only at the Begin Level. """ - command = f"*ABBR,{abbr},{string}" + command = f"/UCMD,{cmd},{srnum}" return self.run(command, **kwargs) - def abbres(self, lab="", fname="", ext="", **kwargs): - """Reads abbreviations from a coded file. + def abbres(self, lab: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Reads abbreviations from a coded file. - APDL Command: ABBRES + Mechanical APDL Command: `ABBRES `_ Parameters ---------- - lab + lab : str Label that specifies the read operation: - NEW - Replace current abbreviation set with these abbreviations (default). + * ``NEW`` - Replace current abbreviation set with these abbreviations (default). - CHANGE - Extend current abbreviation set with these abbreviations, replacing any of the - same name that already exist. + * ``CHANGE`` - Extend current abbreviation set with these abbreviations, replacing any of the same + name that already exist. - 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. + 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 ``Jobname``. - ext - Filename extension (eight-character maximum). + ext : str + Filename extension (eight-character maximum). The extension defaults to ABBR if ``Fname`` is + blank. Notes ----- - The abbreviation file may have been written with the ABBSAV command. Do - not issue ABBRES,NEW while inside an executing abbreviation. Doing so - will cause all data for the executing abbreviation to be deleted. + The abbreviation file may have been written with the :ref:`abbsav` command. Do not issue + :ref:`abbres` ,NEW while inside an executing abbreviation. Doing so will cause all data for the + executing abbreviation to be deleted. This command is valid in any processor. """ command = f"ABBRES,{lab},{fname},{ext}" return self.run(command, **kwargs) - def abbsav(self, lab="", fname="", ext="", **kwargs): - """Writes the current abbreviation set to a coded file. + def abbr(self, abbr: str = "", string: str = "", **kwargs): + r"""Defines an abbreviation. - APDL Command: ABBSAV + Mechanical APDL Command: `\*ABBR `_ Parameters ---------- - lab - Label that specifies the write operation. - - ALL - Write all abbreviations (default). - - 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. - - The file name defaults to Jobname. - - ext - Filename extension (eight-character maximum). The - extension defaults to ABBR if Fname is blank. + abbr : str + The abbreviation (up to 8 alphanumeric characters) used to represent the string ``String``. If + ``Abbr`` is the same as an existing Mechanical APDL command, the abbreviation overrides. Avoid + using an ``Abbr`` which is the same as an Mechanical APDL command. + + string : str + String of characters (60 maximum) represented by ``Abbr``. Cannot include a $ or any of the + commands ``C***``, :ref:`com`, :ref:`gopr`, :ref:`nopr`, :ref:`quit`, :ref:`ui`, or :ref:`end`. + Parameter names and commands of the ``\*DO`` and Use the ``\*IF`` groups may not be abbreviated. + If ``String`` is blank, the abbreviation is deleted. To abbreviate multiple commands, create an + "unknown command" macro or define ``String`` to execute a macro file ( :ref:`use` ) containing + the desired commands. Notes ----- - Existing abbreviations on this file, if any, will be overwritten. The - abbreviation file may be read with the ABBRES command. + Once the abbreviation ``Abbr`` is defined, you can issue it at the beginning of a command line and + follow it with a blank (or with a comma and appended data), and the program will substitute the + string ``String`` for ``Abbr`` as the line is executed. Up to 100 abbreviations may exist at any + time and are available throughout the program. Abbreviations may be redefined or deleted at any + time. + + Use :ref:`starstatus` to display the current list of abbreviations. For abbreviations repeated with + ``\*REPEAT``, substitution occurs before the repeat increments are applied. There are a number of + abbreviations that are predefined by the program (these can be deleted by using the blank ``String`` + option described above). Note that ``String`` will be written to the ``File.LOG``. This command is valid in any processor. """ - command = f"ABBSAV,{lab},{fname},{ext}" + command = f"*ABBR,{abbr},{string}" return self.run(command, **kwargs) - def ucmd(self, cmd="", srnum="", **kwargs): - """Assigns a user-defined command name. + def abbsav(self, lab: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Writes the current abbreviation set to a coded file. - APDL Command: /UCMD + Mechanical APDL Command: `ABBSAV `_ Parameters ---------- - cmd - User-defined command name. Only the first four characters are - significant. Must not conflict with any ANSYS command name or any - user "unknown command" macro name. - - srnum - User subroutine number (1 to 10) programmed for this command. For - example, the command /UCMD,MYCMD,3 will execute subroutine USER03 - whenever the command MYCMD is entered. Use a blank command name to - disassociate SRNUM from its command. For example, /UCMD,,3 removes - MYCMD as a command. + lab : str + Label that specifies the write operation: + + * ``ALL`` - Write all abbreviations (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. The file name defaults to ``Jobname``. + + ext : str + Filename extension (eight-character maximum). The extension defaults to ABBR if ``Fname`` is + blank. Notes ----- - Assigns a user-defined command name to a user-programmable (system- - dependent) subroutine. This feature allows user-defined commands to be - programmed into the ANSYS program. Once programmed, this command can - be input to the program like other commands, and can also be included - in the ANSYS start-up file. See ``*ULIB`` for another way of defining user - commands. - - Up to 10 subroutines are available for user-defined commands (USER01 to - USER10). Users must have system permission, system access, and - knowledge to write, compile, and link the appropriate subprocessors - into the ANSYS program at the site where it is to be run. All routines - should be written in FORTRAN. For more information on FORTRAN compilers - please refer to either the ANSYS, Inc. Windows Installation Guide or - the ANSYS, Inc. Linux Installation Guide for details specific to your - platform or operating system. The USER01 routine is commented and - should be listed from the distribution media (system dependent) for - more details. Issue /UCMD,STAT to list all user-defined command names. - Since a user-programmed command is a nonstandard use of the program, - the verification of any ANSYS run incorporating these commands is - entirely up to the user. In any contact with ANSYS customer support - regarding the performance of a custom version of the ANSYS program, you - should explicitly state that a user programmable feature has been used. - See the Advanced Analysis Guide for a general description of user- - programmable features and Guide to User-Programmable Features for a - detailed description of these features. + Existing abbreviations on this file, if any, will be overwritten. The abbreviation file may be read + with the :ref:`abbres` command. - This command is valid only at the Begin Level. + This command is valid in any processor. """ - command = f"/UCMD,{cmd},{srnum}" + command = f"ABBSAV,{lab},{fname},{ext}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/array_param.py b/src/ansys/mapdl/core/_commands/apdl/array_param.py deleted file mode 100644 index 31f255b895..0000000000 --- a/src/ansys/mapdl/core/_commands/apdl/array_param.py +++ /dev/null @@ -1,1535 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class ArrayParam: - def mfouri(self, oper="", coeff="", mode="", isym="", theta="", curve="", **kwargs): - """Calculates the coefficients for, or evaluates, a Fourier series. - - APDL Command: ``*MFOURI`` - - Parameters - ---------- - oper - Type of Fourier operation: - - FIT - Calculate Fourier coefficients COEFF from MODE, ISYM, - THETA, and CURVE. - - EVAL - Evaluate the Fourier curve CURVE from - COEFF, MODE, ISYM and THETA. - - coeff - Name of the array parameter vector containing the Fourier - coefficients (calculated if Oper = FIT, required as input if Oper = - EVAL). See ``*SET`` for name restrictions. - - mode - Name of the array parameter vector containing the mode numbers of - the desired Fourier terms. - - isym - Name of the array parameter vector containing the symmetry key for - the corresponding Fourier terms. The vector should contain keys - for each term as follows: - - 0 or 1 - Symmetric (cosine) term - - -1 - Antisymmetric (sine) term. - - theta, curve - Names of the array parameter vectors containing the theta vs. curve - description, respectively. Theta values should be input in - degrees. If Oper = FIT, one curve value should be supplied with - each theta value. If Oper = EVAL, one curve value will be - calculated for each theta value. - - Notes - ----- - Calculates the coefficients of a Fourier series for a given - curve, or evaluates the Fourier curve from the given (or - previously calculated) coefficients. The lengths of the - COEFF, MODE, and ISYM vectors must be the same--typically two - times the number of modes desired, since two terms (sine and - cosine) are generally required for each mode. The lengths of - the CURVE and THETA vectors should be the same or the smaller - of the two will be used. There should be a sufficient number - of points to adequately define the curve--at least two times - the number of coefficients. A starting array element number - (1) must be defined for each array parameter vector. - - The vector specifications ``*VLEN``, ``*VCOL``, ``*VABS``, - ``*VFACT``, and ``*VCUM`` do not apply to this command. Array - elements should not be skipped with the ``*VMASK`` and the - NINC value of the ``*VLEN`` specifications. The vector being - calculated (COEFF if Oper is FIT, or CURVE if Oper is EVAL) - must exist as a dimensioned array [``*DIM``]. - - This command is valid in any processor. - """ - command = f"*MFOURI,{oper},{coeff},{mode},{isym},{theta},{curve}" - return self.run(command, **kwargs) - - def mfun(self, parr="", func="", par1="", **kwargs): - """Copies or transposes an array parameter matrix. - - APDL Command: ``*MFUN`` - - Parameters - ---------- - parr - The name of the resulting array parameter matrix. See ``*SET`` for - name restrictions. - - func - Copy or transpose function: - - Par1 is copied to ParR - Par1 is transposed to ParR. Rows - (m) and columns (n) of Par1 matrix are transposed to - resulting ParR matrix of shape (n,m). - - par1 - Array parameter matrix input to the operation. - - Notes - ----- - Operates on one input array parameter matrix and produces one output - array parameter matrix according to: - - ParR = f(Par1) - - where the function (f) is either a copy or transpose, as described - above. - - Functions are based on the standard FORTRAN definitions where - possible. ParR may be the same as Par1. Starting array - element numbers must be defined for each array parameter - matrix if it does not start at the first location. For - example, ``*MFUN,A(1,5),COPY,B(2,3)`` copies matrix B - (starting at element (2,3)) to matrix A (starting at element - (1,5)). The diagonal corner elements for each submatrix must - be defined: the upper left corner by the array starting - element (on this command), the lower right corner by the - current values from the ``*VCOL`` and ``*VLEN`` commands. The - default values are the (1,1) element and the last element in - the matrix. No operations progress across matrix planes (in - the 3rd dimension). Absolute values and scale factors may be - applied to all parameters [``*VABS``, ``*VFACT``]. Results - may be cumulative [``*VCUM``]. - - Array elements should not be skipped with the ``*VMASK`` and the - NINC value of the ``*VLEN`` specifications. The number of - rows [``*VLEN``] applies to the Par1 array. See the - ``*VOPER`` command for details. - - This command is valid in any processor. - """ - command = f"*MFUN,{parr},{func},{par1}" - return self.run(command, **kwargs) - - def moper( - self, - parr="", - par1="", - oper="", - val1="", - val2="", - val3="", - val4="", - val5="", - val6="", - **kwargs, - ): - """Performs matrix operations on array parameter matrices. - - APDL Command: ``*MOPER`` - - Parameters - ---------- - parr - The name of the resulting array parameter matrix. See ``*SET`` for - name restrictions. - - par1 - First array parameter matrix input to the operation. For ``Oper = - MAP``, this is an ``N`` x 3 array of coordinate locations at which to - interpolate. ``ParR`` will then be an ``N(out)`` x ``M`` array containing the - interpolated values. - - oper - Matrix operations: - - * `INVERT` - ``(*MOPER, ParR, Par1, INVERT)`` - Square matrix invert: Inverts the ``n`` x ``n`` matrix in ``Par1`` - into ``ParR``. The matrix must be well conditioned. - - .. warning:: - - Non-independent or ill-conditioned equations can - cause erroneous results. - - For large matrices, use the - APDL Math operation ``*LSFACTOR`` for efficiency (see APDL - Math). - - * `MULT` - ``(*MOPER, ParR, Par1, MULT, Par2)`` - Matrix multiply: Multiplies ``Par1`` by ``Par2``. The number of - rows of ``Par2`` must equal the number of columns of ``Par1`` for - the operation. If ``Par2`` is input with a number of rows - greater than the number of columns of ``Par1``, matrices are - still multiplied. However, the operation only uses a - number of rows of ``Par2`` equal to the number of columns of - ``Par1``. - - * `COVAR` - ``(*MOPER, ParR, Par1, COVAR, Par2)`` - Covariance: The measure of association between two columns - of the input matrix (``Par1``). ``Par1``, of size m runs (rows) - by ``n`` data (columns) is first processed to produce a row - vector containing the mean of each column which is - transposed to a column vector (``Par2``) of n array elements. - The ``Par1`` and ``Par2`` operation then produces a resulting ``n`` x - ``n`` matrix (``ParR``) of covariances (with the variances as the - diagonal terms). - - * `CORR` - ``(*MOPER, ParR, Par1, CORR, Par2)`` - Correlation: The correlation coefficient between two - variables. The input matrix (``Par1``), of size m runs (rows) - by n data (columns), is first processed to produce a row - vector containing the mean of each column which is then - transposed to a column vector (``Par2``) of n array elements. - The ``Par1`` and ``Par2`` operation then produces a resulting ``n`` x - ``n`` matrix (``ParR``) of correlation coefficients (with a value - of 1.0 for the diagonal terms). - - * `SOLV` - ``(*MOPER, ParR, Par1, SOLV, Par2)`` - Solution of simultaneous equations: Solves the set of ``n`` - equations of n terms of the form ``an_1 x_1 + an_2 x_2 + ... + - an_n x_n = b_n`` where ``Par1`` contains the matrix of - a-coefficients, ``Par2`` the vector(s) of b-values, and ``ParR`` - the vector(s) of x-results. ``Par1`` must be a square matrix. - The equations must be linear, independent, and well - conditioned. - - **Warning**: Non-independent or ill-conditioned equations can - cause erroneous results. - For large matrices, use the - APDL Math operation ``*LSFACTOR`` for efficiency (see APDL - Math). - - * `SORT` - ``(*MOPER, ParR, Par1, SORT, Par2, n1, n2, n3)`` - Matrix sort: Sorts matrix ``Par1`` according to sort vector - ``Par2`` and places the result back in ``Par1``. Rows of ``Par1`` are - moved to the corresponding positions indicated by the - values of ``Par2``. ``Par2`` may be a column of ``Par1`` (in which - case it will also be reordered). Alternatively, you may - specify the column of ``Par1`` to sort using n1 (leaving ``Par2`` - blank). A secondary sort can be specified by column ``n2``, - and a third sort using ``n3``. ``ParR`` is the vector of initial - row positions (the permutation vector). Sorting ``Par1`` - according to ``ParR`` should reproduce the initial ordering. - - * `NNEAR` - ``(*MOPER, ParR, Par1, NNEAR, Toler)`` - Nearest Node: Quickly determine all the nodes within a - specified tolerance of a given array. ``ParR`` is a vector of - the nearest selected nodes, or 0 if no nodes are nearer - than ``Toler``. ``Par1`` is the ``n`` x 3 array of coordinate - locations. ``Toler`` defaults to 1 and is limited to the - maximum model size. - - * `ENEAR` - ``(*MOPER, ``ParR``, ``Par1``, ENEAR, Toler)`` - Nearest Element: Quickly determine the elements with - centroids that are within a specified tolerance of the - points in a given array. - ``ParR`` is a vector of the nearest - selected elements, or 0 if no element centroids are nearer - than ``Toler``. ``Par1`` is the ``n`` x 3 array of coordinate - locations. - - * `MAP` - ``(*MOPER, ParR, Par1, MAP, Par2, Par3, kDim, --, kOut, LIMIT)`` - Maps the results from one set of points to another. For - example, you can map pressures from a CFD analysis onto - your model for a structural analysis. - - * ``Par1`` is the ``Nout`` x 3 array of points that will be mapped - to. ``Par2`` is the ``Nin`` x ``M`` array that contains ``M`` values of - data to be interpolated at each point and corresponds to - the ``Nin`` x 3 points in ``Par3``. The resulting ``ParR`` is the ``Nout`` - x ``M`` array of mapped data points. - - For each point in the destination mesh, all possible - triangles in the source mesh are searched to find the best - triangle containing each point. It then does a linear - interpolation inside this triangle. You should carefully - specify your interpolation method and search criteria in - order to provide faster and more accurate results (see - ``LIMIT``, below). - - * ``kDim`` is the interpolation criteria. If ``kDim = 2 or 0``, two - dimensional interpolation is applied (interpolate on a - surface). If ``kDim = 3``, three dimensional interpolation is - applied (interpolate on a volume). - - * ``kOut`` specified how points outside of the domain are - handled. If ``kOut`` = 0, use the value(s) of the nearest - region point for points outside of the region. If ```kOut``` = - 1, set results outside of the region to zero. - - * `LIMIT` specifies the number of nearby points considered for - interpolation. The default is 20, and the minimum is - 5. Lower values will reduce processing time; however, some - distorted or irregular sets of points will require a - higher ``LIMIT`` value to encounter three nodes for - triangulation. - - Output points are incorrect if they are not within the - domain (area or volume) defined by the specified input - points. Also, calculations for out-of-bound points require - much more processing time than do points that are within - bounds. Results mapping is available from the command line - only. - - * `INTP` - ``(*MOPER, ParR, Par1, INTP, Par2)`` - Finds the elements that contain each point in the array of - ``n`` x 3 points in ``Par1``. ``Par2`` will contain the set of element - ID numbers and ``ParR`` will contain their ``n`` x 3 set of - natural element coordinates (values between -1 and - 1). ``Par1`` must be in global Cartesian coordinates. - - * `SGET` - ``(*MOPER, ParR, Par1, SGET, Par2, Label, Comp)`` - Gets the nodal solution item corresponding to Label and - Comp (see the PLNSOL command) and interpolates it to the - given element locations. ``Par1`` contains the ``n`` x 3 array of - natural element coordinates (values between -1 and 1) of - the ``n`` element ID numbers in ``Par2``. ``Par1`` and ``Par2`` are - usually the output of the ``*MOPER,,,INTP`` operation. ``ParR`` - contains the ``n`` interpolated results. - - * ``Val1, Val2, ..., Val6`` - Additional input used in the operation. The meanings of - ``Val1`` through ``Val6`` vary depending on the specified matrix - operation. See the description of Oper for details. - """ - command = ( - f"*MOPER,{parr},{par1},{oper},{val1},{val2},{val3},{val4},{val5},{val6}" - ) - return self.run(command, **kwargs) - - def mwrite( - self, parr="", fname="", ext="", label="", n1="", n2="", n3="", **kwargs - ): - """Writes a matrix to a file in a formatted sequence. - - APDL Command: ``*MWRITE`` - - .. warning:: - This command cannot be run interactively. See - :func:`non_interactive `. - - Parameters - ---------- - parr - The name of the array parameter. See ``*SET`` for name restrictions. - - 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). - - label - Can use a value of ``IJK``, ``IKJ``, ``JIK``, ``JKI``, ``KIJ``, ``KJI``, or blank (``JIK``). - - n1, n2, n3 - Write as ``(((ParR(i,j,k), k = 1,n1), i = 1, n2), j = 1, n3)`` for - ``Label = KIJ``. ``n1``, ``n2``, and ``n3`` default to the corresponding dimensions - of the array parameter ParR. - - Notes - ----- - Writes a matrix or vector to a specified file in a formatted sequence. - You can also use the ``*VWRITE`` command to write data to a specified file. - Both commands contain format descriptors on the line immediately - following the command. The format descriptors can be in either Fortran - or C format. - - Fortran format descriptors are enclosed in parentheses. They must - immediately follow the ``*MWRITE`` command on a separate line of the same - input file. The word FORMAT should not be included. The format must - specify the number of fields to be written per line, the field width, - the placement of the decimal point, etc. There should be one field - descriptor for each data item written. The write operation uses the - available system FORTRAN FORMAT conventions (see your system FORTRAN - manual). Any standard FORTRAN real format (such as (4F6.0), - (E10.3,2X,D8.2), etc.) and character format (A) may be used. Integer - (I) and list-directed (``*``) descriptors may not be used. Text may be - included in the format as a quoted string. The FORTRAN descriptor must - be enclosed in parentheses and the format must not exceed 80 characters - (including parentheses). - - The "C" format descriptors are used if the first character of the - format descriptor line is not a left parenthesis. "C" format - descriptors may be up to 80 characters long, consisting of text strings - and predefined "data descriptors" between the strings where numeric or - alphanumeric character data are to be inserted. The normal descriptors - are %I for integer data, %G for double precision data, %C for - alphanumeric character data, and %/ for a line break. There must be one - data descriptor for each specified value in the order of the specified - values. The enhanced formats described in ``*MSG`` may also be used. - - The starting array element number must be defined. Looping continues in - the directions indicated by the Label argument. The number of loops and - loop skipping may also be controlled with the ``*VLEN`` and ``*VMASK`` - commands, which work in the n2 direction (by row on the output file), - and by the ``*VCOL`` command, which works in the n1 direction (by column - in the output file). The vector specifications ``*VABS`` and ``*VFACT`` apply - to this command, while ``*VCUM`` does not apply to this command. See the - ``*VOPER`` command for details. If you are in the GUI, the ``*MWRITE`` command - must be contained in an externally prepared file and read into ANSYS - (i.e., ``*USE``, ``/INPUT``, etc.). - - This command is valid in any processor. - """ - command = f"*MWRITE,{parr},{fname},{ext},,{label},{n1},{n2},{n3}" - return self.run(command, **kwargs) - - def starvput( - self, - parr="", - entity="", - entnum="", - item1="", - it1num="", - item2="", - it2num="", - kloop="", - **kwargs, - ): - """Restores array parameter values into the ANSYS database. - - APDL Command: ``*VPUT`` - - Parameters - ---------- - parr - The name of the input vector array parameter. See ``*SET`` for name - restrictions. The parameter must exist as a dimensioned array - [``*DIM``] with data input. - - entity - Entity keyword. Valid keywords are shown for Entity = in the table - below. - - entnum - The number of the entity (as shown for ENTNUM= in the table below). - - item1 - The name of a particular item for the given entity. Valid items - are as shown in the Item1 columns of the table below. - - it1num - The number (or label) for the specified Item1 (if any). Valid - IT1NUM values are as shown in the IT1NUM columns of the table - below. Some Item1 labels do not require an IT1NUM value. - - item2, it2num - A second set of item labels and numbers to further qualify the item - for which data is to be stored. Most items do not require this - level of information. - - kloop - Field to be looped on: - - Loop on the ENTNUM field (default). - Loop on the Item1 field. - - Loop on the IT1NUM field. Successive items are as shown with IT1NUM. - Loop on the Item2 field. - - Notes - ----- - The ``*VPUT`` command is not supported for PowerGraphics - displays. Inconsistent results may be obtained if this - command is not used in /GRAPHICS, FULL. - - Plot and print operations entered via the GUI (Utility Menu> - Pltcrtls, Utility Menu> Plot) incorporate the AVPRIN - command. This means that the principal and equivalent values - are recalculated. If you use ``*VPUT`` to put data back into - the database, issue the plot commands from the command line to - preserve your data. - - This operation is basically the inverse of the ``*VGET`` - operation. Vector items are put directly (without any - coordinate system transformation) into the ANSYS database. - Items can only replace existing items of the database and not - create new items. Degree of freedom results that are replaced - in the database are available for all subsequent - postprocessing operations. Other results are changed - temporarily and are available mainly for the immediately - following print and display operations. The vector - specification ``*VCUM`` does not apply to this command. The - valid labels for the location fields (Entity, ENTNUM, Item1, - and IT1NUM) are listed below. Item2 and IT2NUM are not - currently used. Not all items from the ``*VGET`` list are - allowed on ``*VPUT`` since putting values into some locations - could cause the database to be inconsistent. - - This command is valid in any processor. - - """ - command = ( - f"*VPUT,{parr},{entity},{entnum},{item1},{it1num},{item2},{it2num},{kloop}" - ) - return self.run(command, **kwargs) - - def sread( - self, - strarray="", - fname="", - ext="", - nchar="", - nskip="", - nread="", - **kwargs, - ): - """Reads a file into a string array parameter. - - APDL Command: ``*SREAD`` - - Parameters - ---------- - strarray - Name of the "string array" parameter which will hold the read file. - String array parameters are similar to character arrays, but each - array element can be as long as 128 characters. If the string - parameter does not exist, it will be created. The array will be - created as: ``*DIM,StrArray,STRING,nChar,nRead``` - - 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). - - nchar - Number of characters per line to read (default is length of the - longest line in the file). - - nskip - Number of lines to skip at the start of the file (default is 0). - - nread - Number of lines to read from the file (default is the entire file). - - Notes - ----- - The ``*SREAD`` command reads from a file into a string array - parameter. The file must be an ASCII text file. - """ - command = f"*SREAD,{strarray},{fname},{ext},,{nchar},{nskip},{nread}" - return self.run(command, **kwargs) - - def toper( - self, - parr="", - par1="", - oper="", - par2="", - fact1="", - fact2="", - con1="", - **kwargs, - ): - """Operates on table parameters. - - APDL Command: ``*TOPER`` - - Parameters - ---------- - parr - Name of the resulting table parameter. The command will create a - table array parameter with this name. Any existing parameter with - this name will be overwritten. - - par1 - Name of the first table parameter. - - oper - The operation to be performed: ``ADD``. The operation is: - ``ParR(i,j,k) = FACT1*Par1(i,j,k) + FACT2 *Par2(i,j,k) +CON1`` - - par2 - Name of the second table parameter. - - fact1 - The first table parameter multiplying constant. Defaults to 1. - - fact2 - The second table parameter multiplying constant. Defaults to 1. - - con1 - The constant increment for offset. Defaults to 0. - - Notes - ----- - ``*TOPER`` operates on table parameters according to: - ``ParR(i,j,k) = FACT1*Par1(i,j,k) + FACT2 *Par2(i,j,k) +CON1`` - - Par1 and Par2 must have the same dimensions and the same variable names - corresponding to those dimensions. Par1 and Par2 must also have - identical index values for rows, columns, etc. - - If you want a local coordinate system for the resulting array, you must - dimension it as such using the ``*DIM`` command before issuing ``*TOPER``. - - This command is valid in any processor. - """ - command = f"*TOPER,{parr},{par1},{oper},{par2},{fact1},{fact2},{con1}" - return self.run(command, **kwargs) - - def vabs(self, kabsr="", kabs1="", kabs2="", kabs3="", **kwargs): - """Applies the absolute value function to array parameters. - - APDL Command: ``*VABS`` - - Parameters - ---------- - kabsr - Absolute value of results parameter: - - Do not take absolute value of results parameter (``ParR``). - Take absolute value. - - kabs1 - Absolute value of first parameter: - - Do not take absolute value of first parameter (``Par1`` or ``ParI``). - Take absolute value. - - kabs2 - Absolute value of second parameter: - - Do not take absolute value of second parameter (``Par2`` or ``ParJ``). - Take absolute value. - - kabs3 - Absolute value of third parameter: - - Do not take absolute value of third parameter (``Par3`` or ``ParK``). - Take absolute value. - - Notes - ----- - Applies an absolute value to parameters used in certain ``*VXX`` and ``*MXX`` - operations. Typical absolute value applications are of the form: - - ``ParR = |f(|Par1|)|`` - - or - - ``ParR = |(|Par1| o |Par2|)|`` - - The absolute values are applied to each input parameter value before - the operation and to the result value after the operation. Absolute - values are applied before the scale factors so that negative scale - factors may be used. The absolute value settings are reset to the - default (no absolute value) after each ``*VXX`` or ``*MXX`` operation. Use - ``*VSTAT`` to list settings. - - This command is valid in any processor. - """ - command = f"*VABS,{kabsr},{kabs1},{kabs2},{kabs3}" - return self.run(command, **kwargs) - - def vcol(self, ncol1="", ncol2="", **kwargs): - """Specifies the number of columns in matrix operations. - - APDL Command: ``*VCOL`` - - Parameters - ---------- - ncol1 - Number of columns to be used for Par1 with ``*MXX`` operations. - Defaults to whatever is needed to fill the result array. - - ncol2 - Number of columns to be used for Par2 with ``*MXX`` operations. - Defaults to whatever is needed to fill the result array. - - Notes - ----- - Specifies the number of columns to be used in array parameter matrix - operations. The size of the submatrix used is determined from the - upper left starting array element (defined on the operation command) to - the lower right array element (defined by the number of columns on this - command and the number of rows on the ``*VLEN`` command). - - The default NCOL is calculated from the maximum number of columns of - the result array (the ``*DIM`` column dimension) minus the starting - location + 1. For example, ``*DIM,R,,1,10`` and a starting location of - R(1,7) gives a default of 4 columns ( starting with R(1,7), R(1,8), - R(1,9), and R(1,10)). Repeat operations automatically terminate at the - last column of the result array. Existing values in the rows and - columns of the results matrix remain unchanged where not overwritten by - the requested input or operation values. - - The column control settings are reset to the defaults after each ``*MXX`` - operation. Use ``*VSTAT`` to list settings. - - This command is valid in any processor. - """ - command = f"*VCOL,{ncol1},{ncol2}" - return self.run(command, **kwargs) - - def vcum(self, key="", **kwargs): - """Allows array parameter results to add to existing results. - - APDL Command: ``*VCUM`` - - Parameters - ---------- - key - Accumulation key: - - Overwrite results. - Add results to the current value of the results parameter. - - Notes - ----- - Allows results from certain ``*VXX`` and ``*MXX`` operations to overwrite or - add to existing results. The cumulative operation is of the form: - - ``ParR = ParR + ParR(Previous)`` - - The cumulative setting is reset to the default (overwrite) after each - ``*VXX`` or ``*MXX`` operation. Use ``*VSTAT`` to list settings. - - This command is valid in any processor. - """ - command = f"*VCUM,{key}" - return self.run(command, **kwargs) - - def vfact(self, factr="", fact1="", fact2="", fact3="", **kwargs): - """Applies a scale factor to array parameters. - - APDL Command: ``*VFACT`` - - Parameters - ---------- - factr - Scale factor applied to results (``ParR``) parameter. Defaults to 1.0. - - fact1 - Scale factor applied to first parameter (``Par1`` or ``ParI``). Defaults - to 1.0. - - fact2 - Scale factor applied to second parameter (``Par2`` or ``ParJ``). Defaults - to 1.0. - - fact3 - Scale factor applied to third parameter (``Par3`` or ``ParK``). Defaults - to 1.0. - - Notes - ----- - Applies a scale factor to parameters used in certain ``*VXX`` and ``*MXX`` - operations. Typical scale factor applications are of the form: - - ``ParR = FACTR*f(FACT1*Par1)`` - - or - - ``ParR = FACTR*((FACT1*Par1) o (FACT2*Par2))`` - - The factors are applied to each input parameter value before the - operation and to the result value after the operation. The scale - factor settings are reset to the default (1.0) after each ``*VXX`` or ``*MXX`` - operation. Use ``*VSTAT`` to list settings. - - This command is valid in any processor. - """ - command = f"*VFACT,{factr},{fact1},{fact2},{fact3}" - return self.run(command, **kwargs) - - def vfun(self, parr="", func="", par1="", con1="", con2="", con3="", **kwargs): - """Performs a function on a single array parameter. - - APDL Command: ``*VFUN`` - - Parameters - ---------- - parr - The name of the resulting numeric array parameter vector. See ``*SET`` - for name restrictions. - - func - Function to be performed: - - * ACOS - Arccosine: ``ACOS(Par1)``. - - * ``ASIN`` - Arcsine: ``ASIN(Par1)``. - - * ``ASORT`` - ``Par1`` is sorted in ascending order. ``*VCOL``, ``*VMASK``, - ``*VCUM``, and ``*VLEN,,NINC`` do not apply. - ``*VLEN,NROW`` does apply. - - * ``ATAN`` - Arctangent: ``ATAN(Par1)`` - - * ``COMP`` - Compress: Selectively compresses data set. "True" - (``*VMASK``) values of ``Par1`` (or row positions to be considered - according to the ``NINC`` value on the ``*VLEN`` command) are - written in compressed form to ``ParR``, starting at the - specified position. - - * ``COPY`` - Copy: ``Par1`` copied to ``ParR``. - - * ``COS`` - Cosine: ``COS(Par1)``. - - * ``COSH`` - Hyperbolic cosine: ``COSH(Par1)``. - - * ``DIRCOS`` - Direction cosines of the principal stresses (nX9). ``Par1`` - contains the nX6 component stresses for the ``n`` locations of - the calculations. - - * ``DSORT`` - ``Par1`` is sorted in descending order. - ``*VCOL``, ``*VMASK``, ``*VCUM``, and ``*VLEN,,NINC`` do not apply. - ``*VLEN,NROW`` does apply. - - * ``EURLER`` - Euler angles of the principal stresses (nX3). ``Par1`` - contains the nX6 component stresses for the ``n`` locations of - the calculations. - - * ``EXP`` - Exponential: ``EXP(Par1)``. - - * ``EXPA`` - Expand: Reverse of the COMP function. All elements of - ``Par1`` (starting at the position specified) are written in - expanded form to corresponding "true" (``*VMASK``) positions - (or row positions to be considered according to the ``NINC`` - value on the ``*VLEN`` command) of ``ParR``. - - * ``LOG`` - Natural logarithm: ``LOG(Par1)``. - - * ``LOG10`` - Common logarithm: ``LOG10(Par1)``. - - * ``NINT`` - Nearest integer: 2.783 becomes 3.0, -1.75 becomes -2.0. - - * ``NOT`` - Logical complement: values 0.0 (false) become 1.0 (true). - Values > 0.0 (true) become 0.0 (false). - - * ``PRIN`` - Principal stresses (nX5). ``Par1`` contains the ``nX6`` component stresses - for the ``n`` locations of the calculations. - - * ``PWR`` - Power function: ``Par1**CON1``. Exponentiation of any negative - number in the vector ``Par1`` to a non-integer power is - performed by exponentiating the positive number and - prepending the minus sign. For example, ``-4**2.3`` is - ``-(4**2.3)``. - - * ``SIN`` - Sine: ``SIN(Par1)`` - - * ``SINH`` - Hyperbolic sine: ``SINH(Par1)``. - - * ``SQRT`` - Square root: ``SQRT(Par1)``. - - * ``TAN`` - Tangent: ``TAN(Par1)``. - - * ``TANH`` - Hyperbolic tangent: ``TANH(Par1)``. - - * ``TANG`` - Tangent to a path at a point: the slope at a point is determined by linear interpolation half - way between the previous and next points. Points are assumed to be in the global Cartesian - coordinate system. Path points are specified in array ``Par1`` (having 3 consecutive columns - of data, with the columns containing the ``x``, ``y``, and ``z`` coordinate locations, respectively, of - the points). Only the starting row index and the column index for the x coordinates are - specified, such as ``A(1,1)``. The y and z coordinates of the vector are assumed to begin in the - corresponding next columns, such as ``A(1,2)`` and ``A(1,3)``. The tangent result, ``ParR``, must also - have 3 consecutive columns of data and will contain the tangent direction vector (normalized - to 1.0); such as 1,0,0 for an x-direction vector. - - * ``NORM`` - Normal to a path and an input vector at a point: determined from the cross-product of the - calculated tangent vector (see ``TANG``) and the input direction vector (with the ``i``, - ``j``, and ``k`` components input as ``CON1``, ``CON2``, and ``CON3``). - Points are assumed to be in the global Cartesian coordinate system. - Path points are specified in array ``Par1`` (having 3 consecutive - columns of data, with the columns containing the ``x``, ``y``, and ``z`` - coordinate locations, respectively, of the points). - Only the starting row index and the column index for the ``x`` coordinates - are specified, such as ``A(1,1)``. The ``y`` and ``z`` coordinates of the vector are assumed to begin - in the corresponding next columns, such as ``A(1,2)`` and ``A(1,3)``. The normal result, ``ParR``, - must also have 3 consecutive columns of data and will contain the normal direction vector - (normalized to 1.0); such as ``1,0,0`` for an x-direction vector - - * ``LOCAL`` - Transforms global Cartesian coordinates of a point to the coordinates of a specified system: - points to be transformed are specified in array ``Par1`` (having 3 consecutive columns of - data, with the columns containing the ``x``, ``y``, and ``z`` global Cartesian coordinate locations, - respectively, of the points). - Only the starting row index and the column index for the ``x`` - coordinates are specified, such as ``A(1,1)``. - The y and z coordinates of the vector are assumed - to begin in the corresponding next columns, such as ``A(1,2)`` and ``A(1,3)``. - Results are transformed to coordinate system ``CON1`` (which may be any valid coordinate system number, - such as 1,2,11,12, etc.). The transformed result, ``ParR``, must also have 3 consecutive columns - of data and will contain the corresponding transformed coordinate locations. - - * ``GLOBAL`` - Transforms specified coordinates of a point to global Cartesian coordinates: points to be - transformed are specified in array ``Par1`` (having 3 consecutive columns of data, with the - columns containing the local coordinate locations (``x``, ``y``, ``z`` or ``r``, ``θ``, ``z`` - or etc.) of the points). - Only the starting row index and the column index for the x coordinates are specified, such - as ``A(1,1)``. - The y and z coordinates (or ``θ`` and ``z``, or etc.) of the vector are assumed to begin - in the corresponding next columns, such as ``A(1,2)`` and ``A(1,3)``. - Local coordinate locations are assumed to be in coordinate system ``CON1`` - (which may be any valid coordinate system number, such as 1,2,11,12, etc.). - The transformed result, ``ParR``, must also have 3 consecutive - columns of data, with the columns containing the global Cartesian ``x``, y, and z coordinate - locations, respectively. - - par1 - Array parameter vector in the operation. - - con1, con2, con3 - Constants (used only with the PWR, NORM, LOCAL, and GLOBAL - functions). - - Notes - ----- - Operates on one input array parameter vector and produces one output - array parameter vector according to: - - ``ParR = f(Par1)`` - - """ - command = f"*VFUN,{parr},{func},{par1},{con1},{con2},{con3}" - return self.run(command, **kwargs) - - def vitrp(self, parr="", part="", pari="", parj="", park="", **kwargs): - """Forms an array parameter by interpolation of a table. - - APDL Command: ``*VITRP`` - - Parameters - ---------- - parr - The name of the resulting array parameter. See ``*SET`` for name - restrictions. - - part - The name of the TABLE array parameter. The parameter must exist as - a dimensioned array of type TABLE [``*DIM``]. - - pari - Array parameter vector of I (row) index values for interpolation in - ParT. - - parj - Array parameter vector of J (column) index values for interpolation - in ParT (which must be at least 2-D). - - park - Array parameter vector of K (depth) index values for interpolation - in ParT (which must be 3-D). - - Notes - ----- - Forms an array parameter (of type ``ARRAY``) by interpolating values of an - array parameter (of type ``TABLE``) at specified table index locations - according to: - - ``ParR = f(ParT, Parl, ParJ, ParK)`` - - where ``ParT`` is the type ``TABLE`` array parameter, and ``ParI``, ``ParJ``, ``ParK`` are - the type ``ARRAY`` array parameter vectors of index values for - interpolation in ``ParT``. See the ``*DIM`` command for ``TABLE`` and ``ARRAY`` - declaration types. Linear interpolation is used. The starting array - element number for the ``TABLE`` array (``ParT``) is not used (but a value must - be input). Starting array element numbers must be defined for each - array parameter vector if it does not start at the first location. For - example, ``*VITRP,R(5),TAB(1,1),X(2),Y(4)`` uses the second element of X - and the fourth element of Y as index values (row and column) for a 2-D - interpolation in ``TAB`` and stores the result in the fifth element of R. - Operations continue on successive array elements ``[*VLEN, *VMASK]`` with - the default being all successive elements. Absolute values and scale - factors may be applied to the result parameter ``[*VABS, *VFACT]``. - Results may be cumulative ``[*VCUM]``. See the ``*VOPER`` command for details. - - This command is valid in any processor. - """ - command = f"*VITRP,{parr},{part},{pari},{parj},{park}" - return self.run(command, **kwargs) - - def vlen(self, nrow="", ninc="", **kwargs): - """Specifies the number of rows to be used in array parameter operations. - - APDL Command: ``*VLEN`` - - Parameters - ---------- - nrow - Number of rows to be used with the ``*VXX`` or ``*MXX`` operations. - Defaults to the number of rows needed to fill the result array. - - ninc - Perform the operation on every NINC row (defaults to 1). - - Notes - ----- - Specifies the number of rows to be used in array parameter operations. - The size of the submatrix used is determined from the upper left - starting array element (defined on the operation command) to the lower - right array element (defined by the number of rows on this command and - the number of columns on the ``*VCOL`` command). ``NINC`` allows skipping row - operations for some operation commands. Skipped rows are included in - the row count. The starting row number must be defined on the - operation command for each parameter read and for the result written. - - The default ``NROW`` is calculated from the maximum number of rows of the - result array (the ``*DIM`` row dimension) minus the starting location + 1. - For example, ``*DIM,R,,10`` and a starting location of ``R(7)`` gives a default - of 4 loops (filling ``R(7)``, ``R(8)``, ``R(9)``, and ``R(10)``). Repeat operations - automatically terminate at the last row of the result array. Existing - values in the rows and columns of the results matrix remain unchanged - where not overwritten by the requested input or operation values. - - The stride (``NINC``) allows operations to be performed at regular - intervals. It has no effect on the total number of row operations. - Skipped operations retain the previous result. For example, ``*DIM,R,,6,`` - with a starting location of ``R(1)``, ``NROW = 10``, and ``NINC = 2`` calculates - values for locations ``R(1)``, ``R(3)``, and ``R(5)`` and retains values for - locations ``R(2)``, ``R(4)``, and ``R(6)``. A more general skip control may be - done by masking ``[*VMASK]``. The row control settings are reset to the - defaults after each ``*VXX`` or ``*MXX`` operation. Use ``*VSTAT`` to list - settings. - - This command is valid in any processor. - """ - command = f"*VLEN,{nrow},{ninc}" - return self.run(command, **kwargs) - - def vmask(self, par="", **kwargs): - """Specifies an array parameter as a masking vector. - - APDL Command: ``*VMASK`` - - Parameters - ---------- - par - Name of the mask parameter. The starting subscript must also be - specified. - - Notes - ----- - Specifies the name of the parameter whose values are to be checked for - each resulting row operation. The mask vector usually contains only 0 - (for false) and 1 (for true) values. For each row operation the - corresponding mask vector value is checked. A true value allows the - operation to be done. A false value skips the operation (and retains - the previous results). A mask vector can be created from direct input, - such as ``M(1) = 1,0,0,1,1,0,1``; or from the DATA function of the ``*VFILL`` - command. The NOT function of the ``*VFUN`` command can be used to reverse - the logical sense of the mask vector. The logical compare operations - (``LT``, ``LE``, ``EQ``, ``NE``, ``GE``, and ``GT``) of - the ``*VOPER`` command also produce a mask - vector by operating on two other vectors. Any numeric vector can be - used as a mask vector since the actual interpretation assumes values - less than 0.0 are 0.0 (false) and values greater than 0.0 are 1.0 - (true). If the mask vector is not specified (or has fewer values than - the result vector), true (1.0) values are assumed for the unspecified - values. Another skip control may be input with ``NINC`` on the ``*VLEN`` - command. If both are present, operations occur only when both are - true. The mask setting is reset to the default (no mask) after each - ``*VXX`` or ``*MXX`` operation. Use ``*VSTAT`` to list settings. - - This command is valid in any processor. - """ - command = f"*VMASK,{par}" - return self.run(command, **kwargs) - - def voper(self, parr="", par1="", oper="", par2="", con1="", con2="", **kwargs): - """Operates on two array parameters. - - APDL Command: ``*VOPER`` - - Parameters - ---------- - PARR - The name of the resulting array parameter vector. See ``*SET`` for - name restrictions. - - PAR1 - First array parameter vector in the operation. May also be a - scalar parameter or a literal constant. - - OPER - Operations: - - * ``ADD`` - Addition: ``Par1+Par2``. - - * ``SUB`` - Subtraction: ``Par1-Par2``. - - * ``MULT`` - Multiplication: ``Par1*Par2``. - - * ``DIV`` - Division: ``Par1/Par2`` (a divide by zero results in a value of zero). - - * ``MIN`` - Minimum: minimum of ``Par1`` and ``Par2``. - - * ``MAX`` - Maximum: maximum of ``Par1`` and ``Par2``. - - * ``LT`` - Less than comparison: ``Par1= Par2`` gives 1.0 if - true, 0.0 if false. - - * ``GT`` - Greater than comparison: ``Par1>Par2`` - gives 1.0 if true, 0.0 if false. - - * ``DER`` - First derivative: - - .. math:: - - \\dfrac{\\mathrm{d}(\\mathrm{Par1})}{\\mathrm{d}(\\mathrm{Par2})} - - The derivative at a point is determined over points - half way between the previous and next points - (by linear interpolation). - ``Par1`` must be a function (a unique ``Par1`` - value for each ``Par2`` - value) and ``Par2`` must be in ascending order. - - * ``DER2`` - Second derivative: - - .. math:: - - \\dfrac{\\mathrm{d}^2(\\mathrm{Par1})}{\\mathrm{d}(\\mathrm{Par2})^2} - - See also ``DER1``. - - * ``INT1`` - Single integral: - - .. math:: - - \\int Par1 \\, d(Par2) - - where ``CON1`` is the integration constant. - The integral at a point is - determined by using the single integration procedure - described in the Mechanical APDL Theory Reference. - - * ``INT2`` - Double integral: - - .. math:: - - \\iint Par1 \\, d(Par2) - - where ``CON1`` is the integration constant of the first - integral and ``CON2`` is the integration constant - of the second integral. If ``Par1`` - contains acceleration data, ``CON1`` is the initial velocity - and ``CON2`` is the initial displacement. See also ``INT1``. - - * ``DOT`` - Dot product: ``Par1 . Par2``. - ``Par1`` and ``Par2`` must each have - three consecutive columns of data, with the columns - containing the ``i``, ``j``, and ``k`` vector components, - respectively. Only the starting row index and the column - index for the ``i`` components are specified for ``Par1`` and - ``Par2``, such as ``A(1,1)``. The ``j`` and ``k`` components of the - vector are assumed to begin in the corresponding next - columns, such as ``A(1,2)`` and ``A(1,3)``. - - * ``CROSS`` - Cross product: ``Par1 x Par2``. - ``Par1``, ``Par2``, and ``ParR`` must each have 3 components, - respectively. Only the starting row index and the column - index for the i components are specified for ``Par1``, ``Par2``, - and ``ParR``, such as ``A(1,1)``. The j and k components of the - vector are assumed to begin in the corresponding next - columns, such as ``A(1,2)`` and ``A(1,3)``. - - * ``GATH`` - Gather: For a vector of position numbers, ``Par2``, copy the - value of ``Par1`` at each position number to ParR. Example: - for ``Par1 = 10,20,30,40`` and ``Par2 = 2,4,1``; ``ParR = - 20,40,10``. - - * ``SCAT`` - Scatter: Opposite of ``GATH`` operation. For a - vector of position numbers, ``Par2``, copy the value of ``Par1`` - to that position number in ``ParR``. Example: for ``Par1 = - 10,20,30,40,50`` and ``Par2 = 2,1,0,5,3``; ``ParR = 20,10,50,0,40``. - - * ``ATN2`` - Arctangent: arctangent of ``Par1/Par2`` with the sign of each - component considered. - - * ``LOCAL`` - Transform the data in ``Par1`` from - the global Cartesian coordinate system to the local - coordinate system given in ``CON1``. ``Par1`` must be an ``N`` x 3 - (i.e., vector) or an ``N`` x 6 (i.e., stress or strain tensor) - array. If the local coordinate system is a cylindrical, - spherical, or toroidal system, then you must provide the - global Cartesian coordinates in ``Par2`` as an ``N`` x 3 array. - Set ``CON2 = 1`` if the data is strain data. - - * ``GLOBAL`` - Transform the data in ``Par1`` from the local coordinate system given in ``CON1`` to the global - Cartesian coordinate system. ``Par1`` must be an ``N`` x 3 (that is, vector) or an ``N`` x 6 (that is, - stress or strain tensor) array. If the local coordinate system is a cylindrical, spherical, or - toroidal system, then you must provide the global Cartesian coordinates in ``Par2`` as an ``N`` - x 3 array. Set ``CON2 = 1`` if the data is strain data. - - PAR2 - Second array parameter vector in the operation. May also be a - scalar parameter or a literal constant. - - CON1 - First constant (used only with the ``INT1`` and ``INT2`` operations). - - CON2 - Second constant (used only with the ``INT2`` operation). - - Notes - ----- - Operates on two input array parameter vectors and produces one output - array parameter vector according to: - - ``ParR = Par1 o Par2`` - - where the operations (o) are described below. ParR may be the same as - ``Par1`` or ``Par2``. Absolute values and scale factors may be applied to all - parameters [``*VABS``, ``*VFACT``]. Results may be cumulative [``*VCUM``]. - Starting array element numbers must be defined for each array parameter - vector if it does not start at the first location, such as - ``*VOPER,A,B(5),ADD,C(3)`` which adds the third element of C to the fifth - element of B and stores the result in the first element of A. - Operations continue on successive array elements ``[*VLEN, *VMASK]`` with - the default being all successive elements. Skipping array elements via - ``*VMASK`` or ``*VLEN`` for the ``DER`` and ``INT`` functions skips only the writing - of the results (skipped array element data are used in all - calculations). - - Parameter functions and operations are available to operate on a scalar - parameter or a single element of an array parameter, such as ``SQRT(B)`` or - ``SQRT(A(4))``. See the ``*SET`` command for details. Operations on a - sequence of array elements can be done by repeating the desired - function or operation in a do-loop ``[*DO]``. The vector operations within - the ANSYS program (``*VXX`` commands) are internally programmed do-loops - that conveniently perform the indicated operation over a sequence of - array elements. If the array is multidimensional, only the first - subscript is incremented in the do-loop, that is, the operation repeats - in column vector fashion "down" the array. For example, for ``A(1,5)``, - ``A(2,5)``, ``A(3,5)``, etc. The starting location of the row index must be - defined for each parameter read and for the result written. - - The default number of loops is from the starting result location to the - last result location and can be altered with the ``*VLEN`` command. A - logical mask vector may be defined to control at which locations the - operations are to be skipped [``*VMASK``]. The default is to skip no - locations. Repeat operations automatically terminate at the last array - element of the result array column if the number of loops is undefined - or if it exceeds the last result array element. Zeroes are used in - operations for values read beyond the last array element of an input - array column. Existing values in the rows and columns of the results - matrix - """ - command = f"*VOPER,{parr},{par1},{oper},{par2},{con1},{con2}" - return self.run(command, **kwargs) - - def vscfun(self, parr="", func="", par1="", **kwargs): - """Determines properties of an array parameter. - - APDL Command: ``*VSCFUN`` - - Parameters - ---------- - parr - The name of the resulting scalar parameter. See ``*SET`` for name - restrictions. - - func - Functions: - - * ``MAX`` - Maximum: the maximum ``Par1`` array element value. - - * ``MIN`` - Minimum: the minimum ``Par1`` array element value. - - * ``LMAX`` - Index location of the maximum ``Par1`` array element value. - Array ``Par1`` is searched starting from its specified - index. - - * ``LMIN`` - Index location of the minimum ``Par1`` array element - value. Array ``Par1`` is searched starting from its specified - index. - - * ``FIRST`` - Index location of the first nonzero value in array ``Par1``. - Array ``Par1`` is searched starting from its specified - index. - - * ``LAST`` - Index location of the last nonzero value in array - ``Par1``. Array ``Par1`` is searched starting from its specified - index. - - * ``SUM`` - Sum: ``Par1`` (the summation of the ``Par1`` array element - values). - - * ``MEDI`` - Median: value of ``Par1`` at which there are an - equal number of values above and below. - - * ``MEAN`` - Mean: ``(σ Par1)/NUM``, where ``NUM`` is the number of summed - values. - - * ``VARI`` - Variance: ``(σ ((Par1-MEAN)**2))/NUM``. - - * ``STDV`` - Standard deviation: square root of ``VARI``. - - * ``RMS`` - Root-mean-square: square root of ``(σ (Par1**2))/NUM``. - - * ``NUM`` - Number: the number of summed values (masked values are not counted). - - par1 - Array parameter vector in the operation. - - Notes - ----- - Operates on one input array parameter vector and produces one output - scalar parameter according to: - - ``ParR = f(Par1)`` - - where the functions (f) are described below. The starting array element - number must be defined for the array parameter vector. For example, - ``*VSCFUN,MU,MEAN,A(1)`` finds the mean of the ``A`` vector values, starting - from the first value and stores the result as parameter ``MU``. Operations - use successive array elements ``[*VLEN, *VMASK]`` with the default being - all successive array elements. Absolute values and scale factors may - be applied to all parameters ``[*VABS, *VFACT]``. Results may be - cumulative ``[*VCUM]``. See the ``*VOPER`` command for details. - - This command is valid in any processor. - """ - command = f"*VSCFUN,{parr},{func},{par1}" - return self.run(command, **kwargs) - - def vstat(self, **kwargs): - """Lists the current specifications for the array parameters. - - APDL Command: ``*VSTAT`` - - Notes - ----- - Lists the current specifications for the ``*VABS``, ``*VCOL``, - ``*VCUM``, ``*VFACT``, ``*VLEN``, and ``*VMASK`` commands. - - This command is valid in any processor. - """ - command = f"*VSTAT," - return self.run(command, **kwargs) - - def vwrite( - self, - par1="", - par2="", - par3="", - par4="", - par5="", - par6="", - par7="", - par8="", - par9="", - par10="", - par11="", - par12="", - par13="", - par14="", - par15="", - par16="", - par17="", - par18="", - par19="", - **kwargs, - ): - """Writes data to a file in a formatted sequence. - - APDL Command: ``*VWRITE`` - - .. warning:: - This command cannot be run interactively. See - :func:`non_interactive `. - - Parameters - ---------- - par1, par2, par3, . . . , par19 - You can write up to 19 parameters (or constants) at a time. Any Par - values after a blank Par value are ignored. If you leave them all - blank, one line will be written (to write a title or a blank line). - If you input the keyword SEQU, a sequence of numbers (starting from - 1) will be written for that item. - - Notes - ----- - You use ``*VWRITE`` to write data to a file in a formatted sequence. Data - items (Par1, Par2, etc.) may be array parameters, scalar parameters, - character parameters (scalar or array), or constants. You must - evaluate expressions and functions in the data item fields before using - the ``*VWRITE`` command, since initially they will be evaluated to a - constant and remain constant throughout the operation. Unless a file - is defined with the ``*CFOPEN`` command, data is written to the standard - output file. Data written to the standard output file may be diverted - to a different file by first switching the current output file with the - /OUTPUT command. You can also use the ``*MWRITE`` command to write data to - a specified file. Both commands contain format descriptors on the line - immediately following the command. The format descriptors can be in - either Fortran or C format. - - You must enclose Fortran format descriptors in parentheses. They must - immediately follow the ``*VWRITE`` command on a separate line of the same - input file. Do not include the word FORMAT. The format must specify - the number of fields to be written per line, the field width, the - placement of the decimal point, etc. You should use one field - descriptor for each data item written. The write operation uses your - system's available FORTRAN FORMAT conventions (see your system FORTRAN - manual). You can use any standard FORTRAN real format (such as - (4F6.0), (E10.3,2X,D8.2), etc.) and alphanumeric format (A). - Alphanumeric strings are limited to a maximum of 8 characters for any - field (A8) using the Fortran format. Use the "C" format for string - arrays larger than 8 characters. Integer (I) and list-directed (*) - descriptors may not be used. You can include text in the format as a - quoted string. The parentheses must be included in the format and the - format must not exceed 80 characters (including parentheses). The - output line length is limited to 128 characters. - - The "C" format descriptors are used if the first character of the - format descriptor line is not a left parenthesis. "C" format - descriptors are up to 80 characters long, consisting of text strings - and predefined "data descriptors" between the strings where numeric or - alphanumeric character data will be inserted. The normal descriptors - are %I for integer data, %G for double precision data, %C for - alphanumeric character data, and %/ for a line break. There must be one - data descriptor for each specified value (8 maximum) in the order of - the specified values. The enhanced formats described in ``*MSG`` may also - be used. - - For array parameter items, you must define the starting array - element number. Looping continues (incrementing the vector - index number of each array parameter by one) each time you - output a line, until the maximum array vector element is - written. For example, ``*VWRITE,A(1)`` followed by (F6.0) - will write one value per output line, i.e., A(1), A(2), A(3), - A(4), etc. You write constants and scalar parameters with the - same values for each loop. You can also control the number of - loops and loop skipping with the ``*VLEN`` and ``*VMASK`` - commands. The vector specifications ``*VABS``, ``*VFACT``, - and ``*VCUM`` do not apply to this command. If looping - continues beyond the supplied data array's length, zeros will - be output for numeric array parameters and blanks for - character array parameters. For multi-dimensioned array - parameters, only the first (row) subscript is incremented. - See the ``*VOPER`` command for details. If you are in the GUI, - the ``*VWRITE`` command must be contained in an externally - prepared file and read into ANSYS (i.e., ``*USE``, /INPUT, etc.). - - This command is valid in any processor. - - """ - command = f"*VWRITE,{par1},{par2},{par3},{par4},{par5},{par6},{par7},{par8},{par9},{par10},{par11},{par12},{par13},{par14},{par15},{par16},{par17},{par18},{par19}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/array_parameters.py b/src/ansys/mapdl/core/_commands/apdl/array_parameters.py new file mode 100644 index 0000000000..44e59578a1 --- /dev/null +++ b/src/ansys/mapdl/core/_commands/apdl/array_parameters.py @@ -0,0 +1,1767 @@ +# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + + +class ArrayParameters: + + def mfun(self, parr: str = "", func: str = "", par1: str = "", **kwargs): + r"""Copies or transposes an array parameter matrix. + + Mechanical APDL Command: `\*MFUN `_ + + Parameters + ---------- + parr : str + The name of the resulting array parameter matrix. See :ref:`starset` for name restrictions. + + func : str + Copy or transpose function: + + * ``COPY`` - ``Par1`` is copied to ``ParR`` + + * ``TRAN`` - ``Par1`` is transposed to ``ParR``. Rows (m) and columns (n) of ``Par1`` matrix are + transposed to resulting ``ParR`` matrix of shape (n,m). + + par1 : str + Array parameter matrix input to the operation. + + Notes + ----- + Operates on one input array parameter matrix and produces one output array parameter matrix + according to: ``ParR`` = f( ``Par1`` ) + + where the function (f) is either a copy or transpose, as described above. + + Functions are based on the standard FORTRAN definitions where possible. ``ParR`` may be the same as + ``Par1``. Starting array element numbers must be defined for each array parameter matrix if it does + not start at the first location. For example, :ref:`mfun` ,A(1,5),COPY,B(2,3) copies matrix B + (starting at element (2,3)) to matrix A (starting at element (1,5)). The diagonal corner elements + for each submatrix must be defined: the upper left corner by the array starting element (on this + command), the lower right corner by the current values from the :ref:`vcol` and :ref:`vlen` + commands. The default values are the (1,1) element and the last element in the matrix. No operations + progress across matrix planes (in the 3rd dimension). Absolute values and scale factors may be + applied to all parameters ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). + Array elements should not be skipped with the :ref:`vmask` and the ``NINC`` value of the :ref:`vlen` + specifications. The number of rows ( :ref:`vlen` ) applies to the ``Par1`` array. See the + :ref:`voper` command for details. + + This command is valid in any processor. + """ + command = f"*MFUN,{parr},{func},{par1}" + return self.run(command, **kwargs) + + def mwrite( + self, + parr: str = "", + fname: str = "", + ext: str = "", + label: str = "", + n1: str = "", + n2: str = "", + n3: str = "", + **kwargs, + ): + r"""Writes a matrix to a file in a formatted sequence. + + Mechanical APDL Command: `\*MWRITE `_ + + .. warning:: + This command must be run using :func:`non_interactive ` + Please visit `Unsupported Interactive Commands `_ + for further information. + + Parameters + ---------- + parr : str + The name of the array parameter. See :ref:`starset` for name restrictions. + + 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. If the file name fields are left blank, the + default file is the current output file. + + ext : str + Filename extension (eight-character maximum). + + label : str + Can use a value of IJK, IKJ, JIK, JKI, KIJ, KJI, or blank (JIK). + + n1 : str + Write as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n1,`` + ``n2,`` and ``n3`` default to the corresponding dimensions of the array parameter ParR. + + n2 : str + Write as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n1,`` + ``n2,`` and ``n3`` default to the corresponding dimensions of the array parameter ParR. + + n3 : str + Write as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n1,`` + ``n2,`` and ``n3`` default to the corresponding dimensions of the array parameter ParR. + + Notes + ----- + Writes a matrix or vector to a specified file in a formatted sequence. You can also use the + :ref:`vwrite` command to write data to a specified file. Both commands contain format descriptors on + the line immediately following the command. The format descriptors can be in either FORTRAN or C + format. + + FORTRAN format descriptors are enclosed in parentheses. They must immediately follow the + :ref:`mwrite` command on a separate line of the same input file. The word FORMAT should not be + included. The format must specify the number of fields to be written per line, the field width, the + placement of the decimal point, etc. There should be one field descriptor for each data item + written. The write operation uses the available system FORTRAN FORMAT conventions (see your system + FORTRAN manual). Any standard FORTRAN real format (such as (4F6.0), (E10.3,2X,D8.2), etc.) and + character format (A) may be used. Integer (I) + and list-directed (\2) descriptors may not be used. Text may be included in the format as a quoted + string. The FORTRAN descriptor must be enclosed in parentheses and the format must not exceed 80 + characters (including parentheses). + + The "C" format descriptors are used if the first character of the format descriptor line is not a + left parenthesis. "C" format descriptors may be up to 80 characters long, consisting of text strings + and predefined "data descriptors" between the strings where numeric or alphanumeric character data + are to be inserted. The normal descriptors are %I for integer data, %G for double precision data, %C + for alphanumeric character data, and %/ for a line break. There must be one data descriptor for each + specified value in the order of the specified values. The enhanced formats described in :ref:`msg` + can also be used. + + The starting array element number must be defined. Looping continues in the directions indicated by + the Label argument. The number of loops and loop skipping may also be controlled via :ref:`vlen` and + :ref:`vmask`, which work in the ``n2`` direction (by row on the output file), and by :ref:`vcol` , + which works in the ``n1`` direction (by column in the output file). The vector specifications + :ref:`vabs` and :ref:`vfact` apply to this command, while :ref:`vcum` does not apply to this + command. See :ref:`voper` for details. If you are in the GUI, the :ref:`mwrite` command must be + contained in an externally prepared file and read into Mechanical APDL (that is, :ref:`use` , + :ref:`input`, etc.). + + This command is valid in any processor. + """ + command = f"*MWRITE,{parr},{fname},{ext},,{label},{n1},{n2},{n3}" + return self.run(command, **kwargs) + + def moper( + self, + parr: str = "", + par1: str = "", + oper: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + **kwargs, + ): + r"""Performs matrix operations on array parameter matrices. + + Mechanical APDL Command: `\*MOPER `_ + + Parameters + ---------- + parr : str + The name of the resulting array parameter matrix. See :ref:`starset` for name restrictions. + + par1 : str + First array parameter matrix input to the operation. + + oper : str + Matrix operations. Usage of the ``Val1`` through ``Val6`` arguments varies for each operation, as described below: + + * ``INVERT`` - ( :ref:`moper`, ``ParR``, ``Par1``, INVERT) + + Square matrix invert: Inverts the n x n matrix in Par1 into ParR . The matrix must be well + conditioned. + + Non-independent or ill-conditioned equations can cause erroneous results. + + For large matrices, use the APDL Math operation :ref:`lsfactor` for efficiency (see `APDL Math + `_ + + * ``MULT`` - ( :ref:`moper`, ``ParR``, ``Par1``, MULT, ``Par2`` ) + + Matrix multiply: Multiplies ``Par1`` by ``Par2``. The number of rows of ``Par2`` must equal the + number of columns of ``Par1`` for the operation. If ``Par2`` is input with a number of rows + greater than the number of columns of ``Par1``, matrices are still multiplied. However, the + operation only uses a number of rows of ``Par2`` equal to the number of columns of ``Par1``. + + * ``COVAR`` - ( :ref:`moper`, ``ParR``, ``Par1``, COVAR, ``Par2`` ) + + Covariance: The measure of association between columns of the ``Par1`` input matrix. ``Par1`` of + size m runs (rows) by n data (columns) is first processed to produce a row vector containing the + mean of each column, which is transposed to the output column vector ``Par2`` of n array + elements. The ``Par1`` and ``Par2`` operation then produces ``ParR``, a resulting n x n matrix + of covariances (with the variances as the diagonal terms). + + * ``CORR`` - ( :ref:`moper`, ``ParR``, ``Par1``, CORR, ``Par2`` ) + + Correlation: The correlation coefficient between columns of the ``Par1`` input matrix. ``Par1`` of + size m runs (rows) by n data (columns) is first processed to produce a row vector containing the + mean of each column, which is then transposed to the output column vector ``Par2`` of n array + elements. The ``Par1`` and ``Par2`` operation then produces ``ParR``, a resulting n x n matrix + of correlation coefficients (with a value of 1.0 for the diagonal terms). + + * ``SOLV`` - ( :ref:`moper`, ``ParR``, ``Par1``, SOLV, ``Par2`` ) + + Solution of simultaneous equations: Solves the set of ``n`` equations of ``n`` terms of the form a + n1 x 1 + a n2 x 2 + :sup:`...` + a nn x n = b n where ``Par1`` contains the matrix of + a-coefficients, ``Par2`` contains the vector(s) of b-values, and ``ParR`` contains the vector(s) + of x-results. ``Par1`` must be a square matrix. The equations must be linear, independent, and + well conditioned. + + Non-independent or ill-conditioned equations can cause erroneous results. + + For large matrices, use the APDL Math operation :ref:`lsfactor` for efficiency (see `APDL Math + `_ + + * ``SORT`` - ( :ref:`moper`, ``ParR``, ``Par1``, SORT, ``Par2``, ``n1``, ``n2``, ``n3`` ) + + Matrix sort: Sorts the columns of matrix ``Par1`` according to sort vector ``Par2`` and places the + result back into ``Par1``. Rows of ``Par1`` are moved to the corresponding positions indicated + by the values of ``Par2``. ``Par2`` may be a column of ``Par1`` (in which case it will also be + reordered). Alternatively, you may specify the column of ``Par1`` to sort using ``n1`` (leaving + ``Par2`` blank). A secondary sort can be specified by column ``n2``, and a third sort using + column ``n3``. ``ParR`` is the vector of initial row positions (the permutation vector). + Sorting ``Par1`` according to ``ParR`` should reproduce the initial ordering. + + * ``NNEAR`` - ( :ref:`moper`, ``ParR``, ``Par1``, NNEAR, ``Toler`` ) + + Nearest Node: Finds the nodes nearest to the given set of points in ``Par1``, where ``Par1`` is + an n x 3 array of coordinate locations. ``ParR`` is a vector of the nearest selected nodes, or 0 + if no nodes are nearer than ``Toler``. ``Toler`` defaults to 1 and is limited to the maximum + model size. + + * ``ENEAR`` - ( :ref:`moper`, ``ParR``, ``Par1``, ENEAR, ``Toler`` ) + + Nearest Element: Finds the elements nearest to the given set of points in ``Par1``, where + ``Par1`` is an n x 3 array of coordinate locations. ``ParR`` is a vector of the nearest selected + elements, or 0 if no element centroids are nearer than ``Toler``. ``Toler`` defaults to 1 and + is limited to the maximum model size. + + * ``MAP`` - ( :ref:`moper`, ``ParR``, ``Par1``, MAP, ``Par2``, ``Par3``, ``kDim``, ``--``, + ``kOut``, ``LIMIT`` ) + + Maps the results from one set of points to another. For example, you can map pressures from a CFD + analysis onto your model for a structural analysis. + + ``Par1`` is the Nout x 3 array of points that will be mapped to. ``Par2`` is the Nin x M array + that contains M values of data to be interpolated at each point and corresponds to the Nin x 3 + points in ``Par3``. The resulting ``ParR`` is the Nout x M array of mapped data points. + + For each point in the destination mesh, all possible triangles in the source mesh are searched to + find the best triangle containing each point. It then does a linear interpolation inside this + triangle. You should carefully specify your interpolation method and search criteria in order to + provide faster and more accurate results (see ``LIMIT``, below). + + ``kDim`` is the interpolation criteria. If ``kDim`` = 2 or 0, two dimensional interpolation is + applied (interpolate on a surface). If ``kDim`` = 3, three dimensional interpolation is applied + (interpolate on a volume). + + ``kOut`` specified how points outside of the domain are handled. If ``kOut`` = 0, use the value(s) + of the nearest region point for points outside of the region. If ``kOut`` = 1, set results + outside of the region to zero. + + ``LIMIT`` specifies the number of nearby points considered for interpolation. The default is 20, + and the minimum is 5. Lower values will reduce processing time; however, some distorted or + irregular sets of points will require a higher ``LIMIT`` value to encounter three nodes for + triangulation. + + Output points are incorrect if they are not within the domain (area or volume) defined by the + specified input points. Also, calculations for out-of-bound points require much more processing + time than do points that are within bounds. Results mapping is available from the command line + only. + + * ``INTP`` - ( :ref:`moper`, ``ParR``, ``Par1``, INTP, ``Par2`` ) + + Finds the elements that contain each point in the array of n x 3 points in ``Par1``. ``Par2`` + will contain the set of element ID numbers and ``ParR`` will contain their n x 3 set of natural + element coordinates (values between -1 and 1). ``Par1`` must be in global Cartesian coordinates. + + * ``SGET`` - ( :ref:`moper`, ``ParR``, ``Par1``, SGET, ``Par2``, ``Label``, ``Comp`` ) + + Gets the nodal solution item corresponding to ``Label`` and ``Comp`` (see the :ref:`plnsol` + command) and interpolates it to the given element locations. ``Par1`` contains the n x 3 array + of natural element coordinates (values between -1 and 1) of the n element ID numbers in ``Par2`` + . ``Par1`` and ``Par2`` are usually the output of the :ref:`moper`,,,INTP operation. ``ParR`` + contains the n interpolated results. + + val1 : str + Additional input used in the operation. The meanings of ``Val1`` through ``Val6`` vary depending + on the specified matrix operation. See the description of ``Oper`` for details. + + val2 : str + Additional input used in the operation. The meanings of ``Val1`` through ``Val6`` vary depending + on the specified matrix operation. See the description of ``Oper`` for details. + + val3 : str + Additional input used in the operation. The meanings of ``Val1`` through ``Val6`` vary depending + on the specified matrix operation. See the description of ``Oper`` for details. + + val4 : str + Additional input used in the operation. The meanings of ``Val1`` through ``Val6`` vary depending + on the specified matrix operation. See the description of ``Oper`` for details. + + val5 : str + Additional input used in the operation. The meanings of ``Val1`` through ``Val6`` vary depending + on the specified matrix operation. See the description of ``Oper`` for details. + + val6 : str + Additional input used in the operation. The meanings of ``Val1`` through ``Val6`` vary depending + on the specified matrix operation. See the description of ``Oper`` for details. + + Notes + ----- + Each starting array element number must be defined for each array parameter matrix if it does not + start at the first location. For example, :ref:`moper` ,A(2,3),B(1,4),MULT,C(1,5) multiplies + submatrix B (starting at element (1,4)) by submatrix C (starting at element (1,5)) and puts the + result in matrix A (starting at element (2,3)). + + The diagonal corner elements for each submatrix must be defined: the upper left corner by the array + starting element (on this command), the lower right corner by the current values from the + :ref:`vcol` and :ref:`vlen` commands. The default values are the (1,1) element and the last element + in the matrix. No operations progress across matrix planes (in the 3rd dimension). Absolute values + and scale factors may be applied to all parameters ( :ref:`vabs`, :ref:`vfact` ). Results may be + cumulative ( :ref:`vcum` ). Array elements should not be skipped with the :ref:`vmask` and the + ``NINC`` value of the :ref:`vlen` specifications. See the :ref:`voper` command for details. + + This command is valid in any processor. + """ + command = ( + f"*MOPER,{parr},{par1},{oper},{val1},{val2},{val3},{val4},{val5},{val6}" + ) + return self.run(command, **kwargs) + + def mfouri( + self, + oper: str = "", + coeff: str = "", + mode: str = "", + isym: str = "", + theta: str = "", + curve: str = "", + **kwargs, + ): + r"""Calculates the coefficients for, or evaluates, a Fourier series. + + Mechanical APDL Command: `\*MFOURI `_ + + Parameters + ---------- + oper : str + Type of Fourier operation: + + * ``FIT`` - Calculate Fourier coefficients ``COEFF`` from ``MODE``, ``ISYM``, ``THETA``, and + ``CURVE``. + + * ``EVAL`` - Evaluate the Fourier curve ``CURVE`` from ``COEFF``, ``MODE``, ``ISYM`` and + ``THETA`` + + coeff : str + Name of the array parameter vector containing the Fourier coefficients (calculated if ``Oper`` = + FIT, required as input if ``Oper`` = EVAL). See :ref:`starset` for name restrictions. + + mode : str + Name of the array parameter vector containing the mode numbers of the desired Fourier terms. + + isym : str + Name of the array parameter vector containing the symmetry key for the corresponding Fourier terms. + The vector should contain keys for each term as follows: + + * ``0 or 1`` - Symmetric (cosine) term + + * ``-1`` - Antisymmetric (sine) term. + + theta : str + Names of the array parameter vectors containing the theta vs. curve description, respectively. + Theta values should be input in degrees. If ``Oper`` = FIT, one curve value should be supplied + with each theta value. If ``Oper`` = EVAL, one curve value will be calculated for each theta + value. + + curve : str + Names of the array parameter vectors containing the theta vs. curve description, respectively. + Theta values should be input in degrees. If ``Oper`` = FIT, one curve value should be supplied + with each theta value. If ``Oper`` = EVAL, one curve value will be calculated for each theta + value. + + Notes + ----- + Calculates the coefficients of a Fourier series for a given curve, or evaluates the Fourier curve + from the given (or previously calculated) coefficients. The lengths of the ``COEFF``, ``MODE``, + and ``ISYM`` vectors must be the same--typically two times the number of modes desired, since two + terms (sine and cosine) are generally required for each mode. The lengths of the ``CURVE`` and + ``THETA`` vectors should be the same or the smaller of the two will be used. There should be a + sufficient number of points to adequately define the curve--at least two times the number of + coefficients. A starting array element number (1) must be defined for each array parameter vector. + The vector specifications :ref:`vlen`, :ref:`vcol`, :ref:`vabs`, :ref:`vfact`, and :ref:`vcum` + do not apply to this command. Array elements should not be skipped with the :ref:`vmask` and the + ``NINC`` value of the :ref:`vlen` specifications. The vector being calculated ( ``COEFF`` if + ``Oper`` is FIT, or ``CURVE`` if ``Oper`` is EVAL) must exist as a dimensioned array ( :ref:`dim` ). + + This command is valid in any processor. + """ + command = f"*MFOURI,{oper},{coeff},{mode},{isym},{theta},{curve}" + return self.run(command, **kwargs) + + def sread( + self, + strarray: str = "", + fname: str = "", + ext: str = "", + nchar: str = "", + nskip: str = "", + nread: str = "", + **kwargs, + ): + r"""Reads a file into a string array parameter. + + Mechanical APDL Command: `\*SREAD `_ + + Parameters + ---------- + strarray : str + Name of the string array parameter which will hold the read file. String array parameters are + similar to character arrays, but each array element can be as long as 248 characters. If the + string parameter does not exist, it will be created. The array will be created as: + *DIM,StrArray,STRING,nChar,nRead + + 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). + + nchar : str + Number of characters per line to read (default is length of the longest line in the file). + + nskip : str + Number of lines to skip at the start of the file (default is 0). + + nread : str + Number of lines to read from the file (default is the entire file). + + Notes + ----- + The :ref:`sread` command reads from a file into a string array parameter. The file must be an ASCII + text file. + """ + command = f"*SREAD,{strarray},{fname},{ext},,{nchar},{nskip},{nread}" + return self.run(command, **kwargs) + + def toper( + self, + parr: str = "", + par1: str = "", + oper: str = "", + par2: str = "", + fact1: str = "", + fact2: str = "", + con1: str = "", + **kwargs, + ): + r"""Operates on table parameters. + + Mechanical APDL Command: `\*TOPER `_ + + Parameters + ---------- + parr : str + Name of the resulting table parameter. The command will create a table array parameter with this + name. Any existing parameter with this name will be overwritten. + + par1 : str + Name of the first table parameter. + + oper : str + The operation to be performed: ADD. The operation is: ParR(i,j,k) = FACT1\2Par1(i,j,k) + FACT2 + *Par2(i,j,k) +CON1 + + par2 : str + Name of the second table parameter. + + fact1 : str + The first table parameter multiplying constant. Defaults to 1. + + fact2 : str + The second table parameter multiplying constant. Defaults to 1. + + con1 : str + The constant increment for offset. Defaults to 0. + + Notes + ----- + :ref:`toper` operates on table parameters according to: ParR(i,j,k) = FACT1\2Par1(i,j,k) + FACT2 + *Par2(i,j,k) +CON1 + + Par1 and Par2 must have the same dimensions and the same variable names corresponding to those + dimensions. Par1 and Par2 must also have identical index values for rows, columns, etc. + + If you want a local coordinate system for the resulting array, you must dimension it as such using + the :ref:`dim` command before issuing :ref:`toper` . + + This command is valid in any processor. + """ + command = f"*TOPER,{parr},{par1},{oper},{par2},{fact1},{fact2},{con1}" + return self.run(command, **kwargs) + + def starvplot( + self, + parx: str = "", + pary: str = "", + y2: str = "", + y3: str = "", + y4: str = "", + y5: str = "", + y6: str = "", + y7: str = "", + y8: str = "", + **kwargs, + ): + r"""Graphs columns (vectors) of array parameters. + + Mechanical APDL Command: `\*VPLOT `_ + + Parameters + ---------- + parx : str + Name of the array parameter whose column vector values will be the abscissa of the graph. If + blank, row subscript numbers are used instead. ``ParX`` is not sorted by the program. + + pary : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. + + y2 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. + + y3 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. + + y4 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. + + y5 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. + + y6 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. + + y7 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. + + y8 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. + + Notes + ----- + The column to be graphed and the starting row for each array parameter must be specified as + subscripts. Additional columns of the ``ParY`` array parameter may be graphed by specifying column + numbers for ``Y2``, ``Y3``, ..., ``Y8``. For example, :ref:`starvplot` ,TIME (4,6), DISP + (8,1),2,3 specifies that the 1st, 2nd, and 3rd columns of array parameter DISP (all starting at row + 8) are to be graphed against the 6th column of array parameter TIME (starting at row 4). The columns + are graphed from the starting row to their maximum extent. See the :ref:`vlen` and :ref:`vmask` + commands to limit or skip data to be graphed. The array parameters specified on the :ref:`starvplot` + command must be of the same type (type ARRAY or TABLE; ( :ref:`dim` ). Arrays of type TABLE are + graphed as continuous curves. Arrays of type ARRAY is displayed in bar chart fashion. + + The normal curve labeling scheme for :ref:`starvplot` is to label curve 1 "COL 1", curve 2 "COL 2" + and so on. You can use the :ref:`gcolumn` command to apply user-specified labels (8 characters + maximum) to your curves. See `Modifying Curve Labels + `_ + in the `Ansys Parametric Design Language Guide + `_ ANSYS Parametric + Design Language Guide for more information on using :ref:`gcolumn`. + + + When a graph plot reaches minimum or maximum y-axis limits, the program indicates the condition by + clipping the graph. The clip appears as a horizontal magenta line. Mechanical APDL calculates y-axis + limits + automatically; however, you can modify the (YMIN and YMAX) limits via the :ref:`yrange` command. + + This command is valid in any processor. + """ + command = f"*VPLOT,{parx},{pary},{y2},{y3},{y4},{y5},{y6},{y7},{y8}" + return self.run(command, **kwargs) + + def vmask(self, par: str = "", **kwargs): + r"""Specifies an array parameter as a masking vector. + + Mechanical APDL Command: `\*VMASK `_ + + Parameters + ---------- + par : str + Name of the mask parameter. The starting subscript must also be specified. + + Notes + ----- + Specifies the name of the parameter whose values are to be checked for each resulting row operation. + The mask vector usually contains only 0 (for false) and 1 (for true) values. For each row operation + the corresponding mask vector value is checked. A true value allows the operation to be done. A + false value skips the operation (and retains the previous results). A mask vector can be created + from direct input, such as M(1) = 1,0,0,1,1,0,1; or from the DATA function of the :ref:`vfill` + command. The NOT function of the :ref:`vfun` command can be used to reverse the logical sense of the + mask vector. The logical compare operations (LT, LE, EQ, NE, GE, and GT) of the :ref:`voper` command + also produce a mask vector by operating on two other vectors. Any numeric vector can be used as a + mask vector since the actual interpretation assumes values less than 0.0 are 0.0 (false) and values + greater than 0.0 are 1.0 (true). If the mask vector is not specified (or has fewer values than the + result vector), true (1.0) values are assumed for the unspecified values. Another skip control may + be input with ``NINC`` on the :ref:`vlen` command. If both are present, operations occur only when + both are true. The mask setting is reset to the default (no mask) after each **\*V** ``XX`` or + **\*M** ``XX`` operation. Use :ref:`vstat` to list settings. + + This command is valid in any processor. + """ + command = f"*VMASK,{par}" + return self.run(command, **kwargs) + + def vcol(self, ncol1: str = "", ncol2: str = "", **kwargs): + r"""Specifies the number of columns in matrix operations. + + Mechanical APDL Command: `\*VCOL `_ + + Parameters + ---------- + ncol1 : str + Number of columns to be used for Par1 with **\*M** ``XX`` operations. Defaults to whatever is + needed to fill the result array. + + ncol2 : str + Number of columns to be used for Par2 with **\*M** ``XX`` operations. Defaults to whatever is + needed to fill the result array. + + Notes + ----- + Specifies the number of columns to be used in array parameter matrix operations. The size of the + submatrix used is determined from the upper left starting array element (defined on the operation + command) to the lower right array element (defined by the number of columns on this command and the + number of rows on the :ref:`vlen` command). + + The default ``NCOL`` is calculated from the maximum number of columns of the result array (the + :ref:`dim` column dimension) minus the starting location + 1. For example, :ref:`dim` ,R,,1,10 and a + starting location of R(1,7) gives a default of 4 columns ( starting with R(1,7), R(1,8), R(1,9), and + R(1,10)). Repeat operations automatically terminate at the last column of the result array. Existing + values in the rows and columns of the results matrix remain unchanged where not overwritten by the + requested input or operation values. + + The column control settings are reset to the defaults after each **\*M** ``XX`` operation. Use + :ref:`vstat` to list settings. + + This command is valid in any processor. + """ + command = f"*VCOL,{ncol1},{ncol2}" + return self.run(command, **kwargs) + + def vscfun(self, parr: str = "", func: str = "", par1: str = "", **kwargs): + r"""Determines properties of an array parameter. + + Mechanical APDL Command: `\*VSCFUN `_ + + Parameters + ---------- + parr : str + The name of the resulting scalar parameter. See :ref:`starset` for name restrictions. + + func : str + Functions: + + * ``MAX`` - Maximum: the maximum ``Par1`` array element value. + + * ``MIN`` - Minimum: the minimum ``Par1`` array element value. + + * ``LMAX`` - Index location of the maximum ``Par1`` array element value. Array ``Par1`` is + searched starting from its specified index. + + * ``LMIN`` - Index location of the minimum ``Par1`` array element value. Array ``Par1`` is + searched starting from its specified index. + + * ``FIRST`` - Index location of the first nonzero value in array ``Par1``. Array ``Par1`` is + searched starting from its specified index. + + * ``LAST`` - Index location of the last nonzero value in array ``Par1``. Array ``Par1`` is + searched starting from its specified index. + + * ``SUM`` - Sum: ``Par1`` (the summation of the ``Par1`` array element values). + + * ``MEDI`` - Median: value of ``Par1`` at which there are an equal number of values above and + below. + + * ``MEAN`` - Mean: (σ Par1)/NUM, where NUM is the number of summed values. + + * ``VARI`` - Variance: (σ (( ``Par1`` -MEAN)**2))/NUM. + + * ``STDV`` - Standard deviation: square root of VARI. + + * ``RMS`` - Root-mean-square: square root of (σ ( ``Par1`` **2))/NUM. + + * ``NUM`` - Number: the number of summed values (masked values are not counted). + + par1 : str + Array parameter vector in the operation. + + Notes + ----- + Operates on one input array parameter vector and produces one output scalar parameter according to: + ``ParR`` = f( ``Par1`` ) + + where the functions (f) are described below. The starting array element number must be defined for + the array parameter vector. For example, :ref:`vscfun` ,MU,MEAN,A(1) finds the mean of the A vector + values, starting from the first value and stores the result as parameter MU. Operations use + successive array elements ( :ref:`vlen`, :ref:`vmask` ) with the default being all successive array + elements. Absolute values and scale factors may be applied to all parameters ( :ref:`vabs` , + :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). See the :ref:`voper` command for details. + + This command is valid in any processor. + """ + command = f"*VSCFUN,{parr},{func},{par1}" + return self.run(command, **kwargs) + + def vstat(self, **kwargs): + r"""Lists the current specifications for the array parameters. + + Mechanical APDL Command: `\*VSTAT `_ + + Notes + ----- + Lists the current specifications for the :ref:`vabs`, :ref:`vcol`, :ref:`vcum`, :ref:`vfact` , + :ref:`vlen`, and :ref:`vmask` commands. + + This command is valid in any processor. + """ + command = "*VSTAT" + return self.run(command, **kwargs) + + def voper( + self, + parr: str = "", + par1: str = "", + oper: str = "", + par2: str = "", + con1: str = "", + con2: str = "", + **kwargs, + ): + r"""Operates on two array parameters. + + Mechanical APDL Command: `\*VOPER `_ + + Parameters + ---------- + parr : str + The name of the resulting array parameter vector. See :ref:`starset` for name restrictions. + + par1 : str + First array parameter vector in the operation. May also be a scalar parameter or a literal + constant. + + oper : str + Operations: + + * ``ADD`` - Addition: ``Par1`` + ``Par2``. + + * ``SUB`` - Subtraction: ``Par1`` - ``Par2``. + + * ``MULT`` - Multiplication: ``Par1`` * ``Par2``. + + * ``DIV`` - Division: ``Par1`` / ``Par2`` (a divide by zero results in a value of zero). + + * ``MIN`` - Minimum: minimum of ``Par1`` and ``Par2``. + + * ``MAX`` - Maximum: maximum of ``Par1`` and ``Par2``. + + * ``LT`` - Less than comparison: ``Par1`` < ``Par2`` gives 1.0 if true, 0.0 if false. + + * ``LE`` - Less than or equal comparison: ``Par1`` :math:`` ``Par2`` gives 1.0 if true, 0.0 if + false. + + * ``EQ`` - Equal comparison: ``Par1`` = ``Par2`` gives 1.0 if true, 0.0 if false. + + * ``NE`` - Not equal comparison: ``Par1`` ≠ ``Par2`` gives 1.0 if true, 0.0 if false. + + * ``GE`` - Greater than or equal comparison: ``Par1`` :math:`` Par2 gives 1.0 if true, 0.0 if + false. + + * ``GT`` - Greater than comparison: ``Par1`` > ``Par2`` gives 1.0 if true, 0.0 if false. + + * ``DER1`` - First derivative: d( ``Par1`` )/d( ``Par2`` ). The derivative at a point is + determined over points half way between the previous and next points (by linear interpolation). + ``Par1`` must be a function (a unique ``Par1`` value for each ``Par2`` value) and ``Par2`` must + be in ascending order. + + * ``DER2`` - Second derivative: d :sup:`2` ( ``Par1`` )/d( ``Par2`` ) :sup:`2`. See also DER1. + + * ``INT1`` - Single integral: ``Par1`` d( ``Par2`` ), where ``CON1`` is the integration constant. + The integral at a point is determined by using the single integration procedure described in the + `Theory Reference `_ Mechanical APDL Theory Reference. + + * ``INT2`` - Double integral: ``Par1`` d( ``Par2`` ), where ``CON1`` is the integration constant + of the first integral and ``CON2`` is the integration constant of the second integral. If + ``Par1`` contains acceleration data, ``CON1`` is the initial velocity and ``CON2`` is the + initial displacement. See also INT1. + + * ``DOT`` - Dot product: ``Par1``. ``Par2``. ``Par1`` and ``Par2`` must each have three + consecutive columns of data, with the columns containing the i, j, and k vector components, + respectively. Only the starting row index and the column index for the i components are + specified for ``Par1`` and ``Par2``, such as A(1,1). The j and k components of the vector are + assumed to begin in the corresponding next columns, such as A(1,2) and A(1,3). + + * ``CROSS`` - Cross product: ``Par1`` x ``Par2``. ``Par1``, ``Par2``, and ``ParR`` must each + have 3 components, respectively. Only the starting row index and the column index for the i + components are specified for ``Par1``, ``Par2``, and ``ParR``, such as A(1,1). The j and k + components of the vector are assumed to begin in the corresponding next columns, such as A(1,2) + and A(1,3). + + * ``GATH`` - Gather: For a vector of position numbers, ``Par2``, copy the value of ``Par1`` at + each position number to ``ParR``. Example: for ``Par1`` = 10,20,30,40 and ``Par2`` = 2,4,1; + ``ParR`` = 20,40,10. + + * ``SCAT`` - Scatter: Opposite of GATH operation. For a vector of position numbers, ``Par2``, + copy the value of ``Par1`` to that position number in ``ParR``. Example: for ``Par1`` = + 10,20,30,40,50 and ``Par2`` = 2,1,0,5,3; ``ParR`` = 20,10,50,0,40. + + * ``ATN2`` - Arctangent: arctangent of ``Par1`` / ``Par2`` with the sign of each component + considered. + + * ``LOCAL`` - Transform the data in ``Par1`` from the global Cartesian coordinate system to the + local coordinate system given in ``CON1``. ``Par1`` must be an N x 3 (that is, vector) or an N + x 6 (that is, stress or strain tensor) array. If the local coordinate system is a cylindrical, + spherical, or toroidal system, then you must provide the global Cartesian coordinates in + ``Par2`` as an N x 3 array. Set ``CON2`` = 1 if the data is strain data. + + * ``GLOBAL`` - Transform the data in ``Par1`` from the local coordinate system given in ``CON1`` + to the global Cartesian coordinate system. ``Par1`` must be an N x 3 (that is, vector) or an N x + 6 (that is, stress or strain tensor) array. If the local coordinate system is a cylindrical, + spherical, or toroidal system, then you must provide the global Cartesian coordinates in + ``Par2`` as an N x 3 array. Set ``CON2`` = 1 if the data is strain data. + + par2 : str + Second array parameter vector in the operation. May also be a scalar parameter or a literal + constant. + + con1 : str + First constant (used only with the INT1 and INT2 operations). + + con2 : str + Second constant (used only with the INT2 operation). + + Notes + ----- + Operates on two input array parameter vectors and produces one output array parameter vector + according to: ``ParR`` = ``Par1`` o ``Par2`` + + where the operations (o) are described below. ``ParR`` can be the same as ``Par1`` or ``Par2``. + + Absolute values and scale factors can be applied to all parameters ( :ref:`vabs`, :ref:`vfact` ). + Results can be cumulative ( :ref:`vcum` ). + + Starting array element numbers must be defined for each array parameter vector if it does not start + at the first location, such as :ref:`voper` ,A,B(5),ADD,C(3) which adds the third element of C to + the fifth element of B and stores the result in the first element of A. + + Operations continue on successive array elements ( :ref:`vlen`, :ref:`vmask` ) with the default + being all successive elements. + + Skipping array elements via :ref:`vmask` or :ref:`vlen` for the DER and INT functions skips only + the writing of the results (skipped array element data are used in all calculations). + + Parameter functions and operations are available to operate on a scalar parameter or a single + element of an array parameter, such as SQRT(B) or SQRT(A(4)). (See :ref:`starset` for more + information.) + + Operations on a sequence of array elements can be performed by repeating the desired function or + operation in a do-loop ( ``\*DO`` ). The vector operations within Mechanical APDLm ( **\*V** ``XX`` + commands) are internally programmed do-loops that conveniently perform the indicated operation over + a sequence of array elements. If the array is multidimensional, only the first subscript is + incremented in the do-loop; that is, the operation repeats in column vector fashion down the array. + For example, for A(1,5), A(2,5), A(3,5), etc. The starting location of the row index must be defined + for each parameter read and for the result written. + + The default number of loops is from the starting result location to the last result location and can + be altered via :ref:`vlen`. + + A logical mask vector can be defined to control at which locations the operations are to be skipped + ( :ref:`vmask` ). The default is to skip no locations. + + Repeat operations automatically terminate at the last array element of the result array column if + the number of loops is undefined or if it exceeds the last result array element. + + Zeroes are used in operations for values read beyond the last array element of an input array + column. Existing values in the rows and columns of the results matrix remain unchanged where not + changed by the requested operation values. + + The result array column may be the same as the input array column, as results in progress are stored + in a temporary array until being moved to the results array at the end of the operation. Results may + be overwritten or accumulated with the existing results ( :ref:`vcum` ). The default is to overwrite + results. + + The absolute value can be used for each parameter read or written ( :ref:`vabs` ). A scale factor + (defaulting to 1.0) is also applied to each parameter read and written ( :ref:`vfact` ). + + This command is valid in any processor. + """ + command = f"*VOPER,{parr},{par1},{oper},{par2},{con1},{con2}" + return self.run(command, **kwargs) + + def vwrite( + self, + par1: str = "", + par2: str = "", + par3: str = "", + par4: str = "", + par5: str = "", + par6: str = "", + par7: str = "", + par8: str = "", + par9: str = "", + par10: str = "", + par11: str = "", + par12: str = "", + par13: str = "", + par14: str = "", + par15: str = "", + par16: str = "", + par17: str = "", + par18: str = "", + par19: str = "", + **kwargs, + ): + r"""Writes data to a file in a formatted sequence. + + Mechanical APDL Command: `\*VWRITE `_ + + .. warning:: + This command must be run using :func:`non_interactive ` + Please visit `Unsupported Interactive Commands `_ + for further information. + + Parameters + ---------- + par1 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par2 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par3 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par4 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par5 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par6 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par7 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par8 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par9 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par10 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par11 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par12 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par13 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par14 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par15 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par16 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par17 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par18 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + par19 : str + You can write up to 19 parameters (or constants) at a time. Any Par values after a blank Par + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. + + Notes + ----- + You use :ref:`vwrite` to write data to a file in a formatted sequence. Data items ( ``Par1``, + ``Par2``, etc.) may be array parameters, scalar parameters, character parameters (scalar or array), + or constants. You must evaluate expressions and functions in the data item fields before using the + :ref:`vwrite` command, since initially they will be evaluated to a constant and remain constant + throughout the operation. Unless a file is defined with the :ref:`cfopen` command, data is written + to the standard output file. Data written to the standard output file may be diverted to a different + file by first switching the current output file with the :ref:`output` command. You can also use the + :ref:`mwrite` command to write data to a specified file. Both commands contain format descriptors on + the line immediately following the command. The format descriptors can be in either FORTRAN or C + format. + + You must enclose FORTRAN format descriptors in parentheses. They must immediately follow the + :ref:`vwrite` command on a separate line of the same input file. Do not include the word FORMAT. The + format must specify the number of fields to be written per line, the field width, the placement of + the decimal point, etc. You should use one field descriptor for each data item written. The write + operation uses your system's available FORTRAN FORMAT conventions (see your system FORTRAN manual). + You can use any standard FORTRAN real format (such as (4F6.0), (E10.3,2X,D8.2), etc.) and + alphanumeric format (A). Alphanumeric strings + are limited to a maximum of 8 characters for any field (A8) using the FORTRAN format. Use the "C" + format for string arrays larger than 8 characters. Integer (I) and list-directed (\2) descriptors may + not be used. You can include text in the format as a quoted string. The parentheses must be included + in the format and the format must not exceed 80 characters (including parentheses). The output line + length is + limited to 128 characters. + + The "C" format descriptors are used if the first character of the format descriptor line is not a + left parenthesis. "C" format descriptors are up to 80 characters long, consisting of text strings + and predefined "data descriptors" between the strings where numeric or alphanumeric character data + will be inserted. The normal descriptors are %I for integer data, %G for double precision data, %C + for alphanumeric character data, and %/ for a line break. There must be one data descriptor for each + specified value (8 maximum) in the order of the specified values. The enhanced formats described in + :ref:`msg` may also be used. + + For array parameter items, you must define the starting array element number. Looping continues + (incrementing the vector index number of each array parameter by one) each time you output a line, + until the maximum array vector element is written. For example, :ref:`vwrite`,A(1) followed by + (F6.0) will write one value per output line, that is, A(1), A(2), A(3), A(4), etc. You write + constants and scalar parameters with the same values for each loop. You can also control the number + of loops and loop skipping with the :ref:`vlen` and :ref:`vmask` commands. The vector specifications + :ref:`vabs`, :ref:`vfact`, and :ref:`vcum` do not apply to this command. If looping continues + beyond the supplied data array's length, zeros will be output for numeric array parameters and + blanks for character array parameters. For multi-dimensioned array parameters, only the first (row) + subscript is incremented. See the :ref:`voper` command for details. If you are in the GUI, the + :ref:`vwrite` command must be contained in an externally prepared file and read into Mechanical APDL + (that is, :ref:`use`, :ref:`input`, etc.). + + If ``Par`` is a table array name, the subscripts refer to the index numbers of the table and not the + index values of its primary variables. See :ref:`starset` if you want to evaluate a table array at + certain values of its primary variables for writing. + + This command is valid in any processor. + """ + command = f"*VWRITE,{par1},{par2},{par3},{par4},{par5},{par6},{par7},{par8},{par9},{par10},{par11},{par12},{par13},{par14},{par15},{par16},{par17},{par18},{par19}" + return self.run(command, **kwargs) + + def vitrp( + self, + parr: str = "", + part: str = "", + pari: str = "", + parj: str = "", + park: str = "", + **kwargs, + ): + r"""Forms an array parameter by interpolation of a table. + + Mechanical APDL Command: `\*VITRP `_ + + Parameters + ---------- + parr : str + The name of the resulting array parameter. See :ref:`starset` for name restrictions. + + part : str + The name of the TABLE array parameter. The parameter must exist as a dimensioned array of type + TABLE ( :ref:`dim` ). + + pari : str + Array parameter vector of I (row) index values for interpolation in ``ParT``. + + parj : str + Array parameter vector of J (column) index values for interpolation in ``ParT`` (which must be + at least 2D). + + park : str + Array parameter vector of K (depth) index values for interpolation in ``ParT`` (which must be + 3D). + + Notes + ----- + Forms an array parameter (of type ARRAY) by interpolating values of an array parameter (of type + TABLE) at specified table index locations according to: ``ParR`` = f( ``ParT``, ``Parl``, ``ParJ`` + , ``ParK`` ) + + where ``ParT`` is the type TABLE array parameter, and ``ParI``, ``ParJ``, ``ParK`` are the type + ARRAY array parameter vectors of index values for interpolation in ``ParT``. See the :ref:`dim` + command for TABLE and ARRAY declaration types. Linear interpolation is used. The starting array + element number for the TABLE array ( ``ParT`` ) is not used (but a value must be input). Starting + array element numbers must be defined for each array parameter vector if it does not start at the + first location. For example, :ref:`vitrp` ,R(5),TAB(1,1),X(2),Y(4) uses the second element of X and + the fourth element of Y as index values (row and column) for a 2D interpolation in TAB and stores + the result in the fifth element of R. Operations continue on successive array elements ( :ref:`vlen` + , :ref:`vmask` ) with the default being all successive elements. Absolute values and scale factors + may be applied to the result parameter ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( + :ref:`vcum` ). See the :ref:`voper` command for details. + + This command is valid in any processor. + """ + command = f"*VITRP,{parr},{part},{pari},{parj},{park}" + return self.run(command, **kwargs) + + def vabs( + self, + kabsr: str = "", + kabs1: str = "", + kabs2: str = "", + kabs3: str = "", + **kwargs, + ): + r"""Applies the absolute value function to array parameters. + + Mechanical APDL Command: `\*VABS `_ + + Parameters + ---------- + kabsr : str + Absolute value of results parameter: + + * ``0`` - Do not take absolute value of results parameter (ParR). + + * ``1`` - Take absolute value. + + kabs1 : str + Absolute value of first parameter: + + * ``0`` - Do not take absolute value of first parameter (Par1 or ParI). + + * ``1`` - Take absolute value. + + kabs2 : str + Absolute value of second parameter: + + * ``0`` - Do not take absolute value of second parameter (Par2 or ParJ). + + * ``1`` - Take absolute value. + + kabs3 : str + Absolute value of third parameter: + + * ``0`` - Do not take absolute value of third parameter (Par3 or ParK). + + * ``1`` - Take absolute value. + + Notes + ----- + Applies an absolute value to parameters used in certain **\*V** ``XX`` and **\*M** ``XX`` + operations. Typical absolute value applications are of the form: ParR = \|f(\|Par1\|)\| + + or + + ParR = \|(\|Par1\| o \|Par2\|)\| + + The absolute values are applied to each input parameter value before the operation and to the result + value after the operation. Absolute values are applied before the scale factors so that negative + scale factors may be used. The absolute value settings are reset to the default (no absolute value) + after each **\*V** ``XX`` or **\*M** ``XX`` operation. Use :ref:`vstat` to list settings. + + This command is valid in any processor. + """ + command = f"*VABS,{kabsr},{kabs1},{kabs2},{kabs3}" + return self.run(command, **kwargs) + + def starvput( + self, + parr: str = "", + entity: str = "", + entnum: str = "", + item1: str = "", + it1num: str = "", + item2: str = "", + it2num: str = "", + kloop: str = "", + **kwargs, + ): + r"""Restores array parameter values into the Mechanical APDL database. + + Mechanical APDL Command: `\*VPUT `_ + + Parameters + ---------- + parr : str + The name of the input vector array parameter. See :ref:`starset` for name restrictions. The + parameter must exist as a dimensioned array ( :ref:`dim` ) with data input. + + entity : str + Entity keyword. Valid keywords are shown for ``Entity`` = in the table below. + + entnum : str + The number of the entity (as shown for ``ENTNUM`` = in the table below). + + item1 : str + The name of a particular item for the given entity. Valid items are as shown in the ``Item1`` + columns of the table below. + + it1num : str + The number (or label) for the specified ``Item1`` (if any). Valid ``IT1NUM`` values are as shown + in the ``IT1NUM`` columns of the table below. Some ``Item1`` labels do not require an ``IT1NUM`` + value. + + item2 : str + A second set of item labels and numbers to further qualify the item for which data is to be + stored. Most items do not require this level of information. + + it2num : str + A second set of item labels and numbers to further qualify the item for which data is to be + stored. Most items do not require this level of information. + + kloop : str + Field to be looped on: + + * ``0 or 2`` - Loop on the ``ENTNUM`` field (default). + + * ``3`` - Loop on the ``Item1`` field. + + * ``4`` - Loop on the ``IT1NUM`` field. Successive items are as shown with ``IT1NUM``. + + * ``5`` - Loop on the ``Item2`` field. + + * ``6`` - Loop on the ``IT2NUM`` field. Successive items are as shown with ``IT2NUM``. + + Notes + ----- + The :ref:`starvput` command is not supported for PowerGraphics displays. Inconsistent results may be + obtained if this command is not used in :ref:`graphics`, FULL. + + Plot and print operations entered via the GUI ( Utility Menu> Pltcrtls, Utility Menu> Plot ) + incorporate the :ref:`avprin` command. This means that the principal and equivalent values are + recalculated. If you use :ref:`starvput` to put data back into the database, issue the plot commands + from the command line to preserve your data. + + This operation is basically the inverse of the :ref:`starvget` operation. Vector items are put + directly (without any coordinate system transformation) into the Mechanical APDL database. Items can + only replace existing items of the database and not create new items. Degree of freedom results that + are replaced in the database are available for all subsequent postprocessing operations. Other + results are changed temporarily and are available mainly for the immediately following print and + display operations. The vector specification :ref:`vcum` does not apply to this command. The valid + labels for the location fields ( ``Entity``, ``ENTNUM``, ``Item1``, and ``IT1NUM`` ) are listed + below. ``Item2`` and ``IT2NUM`` are not currently used. Not all items from the :ref:`starvget` list + are allowed on :ref:`starvput`, as putting values into some locations could cause the database to + be inconsistent. + + This command is valid in any processor. + + **\*VPUT - POST1 Items** + + .. flat-table:: ``Entity`` = NODE, ``ENTNUM`` = ``n`` (node number) + :header-rows: 1 + + * - Item1 + - IT1NUM + - Description + * - Valid labels for nodal degree of freedom results are: + * - U + - X, Y, Z + - X, Y, or Z structural displacement. + * - ROT + - X, Y, Z + - X, Y, or Z structural rotation. + * - TEMP + - + - Temperature. For SHELL131 and SHELL132 elements with KEYOPT(3) = 0 or 1, use TBOT, TE2, TE3, ..., TTOP instead of TEMP. Alternative getfunctions: TEMP(N), TBOT(N), TE2(N), etc. + * - PRES + - + - Pressure. + * - VOLT + - + - Electric potential. + * - MAG + - + - Magnetic scalar potential. + * - V + - X, Y, Z + - X, Y, or Z fluid velocity. X, Y, or Z nodal velocity in a transient structural analysis (analysiswith :ref:`antype` ,TRANS). + * - A + - X, Y, Z + - X, Y, or Z magnetic vector potential. X, Y, or Z nodal acceleration in a transient structuralanalysis (analysis with :ref:`antype` ,TRANS). + * - CONC + - + - Concentration. + * - CURR + - + - Current. + * - EMF + - + - Electromotive force drop. + * - Valid labels for element nodal results are: + * - Item1 + - IT1NUM + - Description + * - S + - X, Y, Z, XY, YZ, XZ + - Component stress. + * - " + - 1, 2, 3 + - Principal stress. + * - " + - INT, EQV + - Stress intensity or equivalent stress. + * - EPTO + - X, Y, Z, XY, YZ, XZ + - Component total strain (EPEL + EPPL + EPCR). + * - " + - 1,2,3 + - Principal total strain. + * - " + - INT, EQV + - Total strain intensity or total equivalent strain. + * - EPEL + - X, Y, Z, XY, YZ, XZ + - Component elastic strain. + * - " + - 1, 2, 3 + - Principal elastic strain. + * - " + - INT, EQV + - Elastic strain intensity or elastic equivalent strain. + * - EPPL + - X, Y, Z, XY, YZ, XZ + - Component plastic strain. + * - " + - 1,2,3 + - Principal plastic strain. + * - " + - INT, EQV + - Plastic strain intensity or plastic equivalent strain. + * - EPCR + - X, Y, Z, XY, YZ, XZ + - Component creep strain. + * - " + - 1, 2, 3 + - Principal creep strain. + * - " + - INT, EQV + - Creep strain intensity or creep equivalent strain. + * - EPTH + - X, Y, Z, XY, YZ, XZ + - Component thermal strain. + * - " + - 1, 2, 3 + - Principal thermal strain. + * - " + - INT, EQV + - Thermal strain intensity or thermal equivalent strain. + * - EPSW + - + - Swelling strain. + * - NL + - SEPL + - Equivalent stress (from stress-strain curve). + * - " + - SRAT + - Stress state ratio. + * - " + - HPRES + - Hydrostatic pressure. + * - " + - EPEQ + - Accumulated equivalent plastic strain. + * - " + - PSV + - Plastic state variable. + * - " + - PLWK + - Plastic work/volume. + * - TG + - X, Y, Z + - Component thermal gradient. + * - TF + - X, Y, Z + - Component thermal flux. + * - PG + - X, Y, Z + - Component pressure gradient. + * - EF + - X, Y, Z + - Component electric field. + * - D + - X, Y, Z + - Component electric flux density. + * - H + - X, Y, Z + - Component magnetic field intensity. + * - B + - X, Y, Z + - Component magnetic flux density. + * - FMAG + - X, Y, Z + - Component electromagnetic force. + * - **Entity= ELEM,** ``ENTNUM`` = ``n`` (element number) + * - Valid labels for element results are: + * - Item1 + - IT1NUM + - Description + * - ETAB + - Lab + - Any user-defined element table label ( :ref:`etable` ). + + """ + command = ( + f"*VPUT,{parr},{entity},{entnum},{item1},{it1num},{item2},{it2num},{kloop}" + ) + return self.run(command, **kwargs) + + def vfun( + self, + parr: str = "", + func: str = "", + par1: str = "", + con1: str = "", + con2: str = "", + con3: str = "", + **kwargs, + ): + r"""Performs a function on a single array parameter. + + Mechanical APDL Command: `\*VFUN `_ + + Parameters + ---------- + parr : str + The name of the resulting numeric array parameter vector. See :ref:`starset` for name + restrictions. + + func : str + Function to be performed: + + * ``ACOS`` - Arccosine: ACOS( ``Par1`` ). + + * ``ASIN`` - Arcsine: ASIN( ``Par1`` ). + + * ``ASORT`` - Par1 is sorted in ascending order. :ref:`vcol`, :ref:`vmask`, :ref:`vcum`, and + :ref:`vlen`,,NINC do not apply. :ref:`vlen`,NROW does apply. + + * ``ATAN`` - Arctangent: ATAN( ``Par1`` ). + + * ``COMP`` - Compress: Selectively compresses data set. "True" ( :ref:`vmask` ) values of ``Par1`` + (or row positions to be considered according to the ``NINC`` value on the :ref:`vlen` command) + are written in compressed form to ``ParR``, starting at the specified position. + + * ``COPY`` - Copy: ``Par1`` copied to ``ParR``. + + * ``COS`` - Cosine: COS( ``Par1`` ). + + * ``COSH`` - Hyperbolic cosine: COSH( ``Par1`` ). + + * ``DIRCOS`` - Direction cosines of the principal stresses ( ``n`` X9). ``Par1`` contains the + ``n`` X6 component stresses for the ``n`` locations of the calculations. + + * ``DSORT`` - ``Par1`` is sorted in descending order. :ref:`vcol`, :ref:`vmask`, :ref:`vcum`, + and :ref:`vlen`,,NINC do not apply. :ref:`vlen`,NROW does apply. + + * ``EULER`` - Euler angles of the principal stresses ( ``n`` X3). ``Par1`` contains the ``n`` X6 + component stresses for the ``n`` locations of the calculations. + + * ``EXP`` - Exponential: EXP( ``Par1`` ). + + * ``EXPA`` - Expand: Reverse of the COMP function. All elements of ``Par1`` (starting at the + position specified) are written in expanded form to corresponding "true" ( :ref:`vmask` ) + positions (or row positions to be considered according to the ``NINC`` value on the :ref:`vlen` + command) of ``ParR``. + + * ``LOG`` - Natural logarithm: LOG( ``Par1`` ). + + * ``LOG10`` - Common logarithm: LOG10( ``Par1`` ). + + * ``NINT`` - Nearest integer: 2.783 becomes 3.0, -1.75 becomes -2.0. + + * ``NOT`` - Logical complement: values :math:`` 0.0 (false) become 1.0 (true). Values > 0.0 + (true) become0.0 (false). + + * ``PRIN`` - Principal stresses ( ``n`` X5). ``Par1`` contains the ``n`` X6 component stresses for + the ``n`` locations of the calculations. + + * ``PWR`` - Power function: ``Par1`` ** ``CON1``. Exponentiation of any negative number in the + vector ``Par1`` to a non-integer power is performed by exponentiating the positive number and + prepending the minus sign. For example, -4**2.3 is -(4**2.3). + + * ``SIN`` - Sine: SIN( ``Par1`` ). + + * ``SINH`` - Hyperbolic sine: SINH( ``Par1`` ). + + * ``SQRT`` - Square root: SQRT( ``Par1`` ). + + * ``TAN`` - Tangent: TAN( ``Par1`` ). + + * ``TANH`` - Hyperbolic tangent: TANH( ``Par1`` ). + + * ``TANG`` - Tangent to a path at a point: the slope at a point is determined by linear + interpolation half way between the previous and next points. Points are assumed to be in the + global Cartesian coordinate system. Path points are specified in array ``Par1`` (having 3 + consecutive columns of data, with the columns containing the x, y, and z coordinate locations, + respectively, of the points). Only the starting row index and the column index for the x + coordinates are specified, such as A(1,1). The y and z coordinates of the vector are assumed to + begin in the corresponding next columns, such as A(1,2) and A(1,3). The tangent result, ``ParR`` + , must also have 3 consecutive columns of data and will contain the tangent direction vector + (normalized to 1.0); such as 1,0,0 for an x-direction vector. + + * ``NORM`` - Normal to a path and an input vector at a point: determined from the cross-product of + the calculated tangent vector (see TANG) and the input direction vector (with the i, j, and k + components input as ``CON1``, ``CON2``, and ``CON3`` ). Points are assumed to be in the global + Cartesian coordinate system. Path points are specified in array ``Par1`` (having 3 consecutive + columns of data, with the columns containing the x, y, and z coordinate locations, respectively, + of the points). Only the starting row index and the column index for the x coordinates are + specified, such as A(1,1). The y and z coordinates of the vector are assumed to begin in the + corresponding next columns, such as A(1,2) and A(1,3). The normal result, ``ParR``, must also + have 3 consecutive columns of data and will contain the normal direction vector (normalized to + 1.0); such as 1,0,0 for an x-direction vector. + + * ``LOCAL`` - Transforms global Cartesian coordinates of a point to the coordinates of a specified + system: points to be transformed are specified in array ``Par1`` (having 3 consecutive columns + of data, with the columns containing the x, y, and z global Cartesian coordinate locations, + respectively, of the points). Only the starting row index and the column index for the x + coordinates are specified, such as A(1,1). The y and z coordinates of the vector are assumed to + begin in the corresponding next columns, such as A(1,2) and A(1,3). Results are transformed to + coordinate system ``CON1`` (which may be any valid coordinate system number, such as 1,2,11,12, + etc.). The transformed result, ``ParR``, must also have 3 consecutive columns of data and will + contain the corresponding transformed coordinate locations. + + * ``GLOBAL`` - Transforms specified coordinates of a point to global Cartesian coordinates: points + to be transformed are specified in array ``Par1`` (having 3 consecutive columns of data, with + the columns containing the local coordinate locations (x, y, z or r, θ, z or etc.) of the + points). Only the starting row index and the column index for the x coordinates are specified, + such as A(1,1). The y and z coordinates (or θ and z, or etc.) of the vector are assumed + to begin in the corresponding next columns, such as A(1,2) and A(1,3). Local coordinate + locations are assumed to be in coordinate system ``CON1`` (which may be any valid coordinate + system number, such as 1,2,11,12, etc.). The transformed result, ``ParR``, must also have 3 + consecutive columns of data, with the columns containing the global Cartesian x, y, and z + coordinate locations, respectively. + + par1 : str + Array parameter vector in the operation. + + con1 : str + Constants (used only with the PWR, NORM, LOCAL, and GLOBAL functions). + + con2 : str + Constants (used only with the PWR, NORM, LOCAL, and GLOBAL functions). + + con3 : str + Constants (used only with the PWR, NORM, LOCAL, and GLOBAL functions). + + Notes + ----- + Operates on one input array parameter vector and produces one output array parameter vector + according to: ``ParR`` = f( ``Par1`` ) + + where the functions (f) are described below. Functions are based on the standard FORTRAN definitions + where possible. Out-of-range function results (or results with exponents whose magnitudes are + approximately greater than 32 or less than -32) produce a zero value. Input and output for angular + functions may be radians (default) or degrees ( :ref:`afun` ). ``ParR`` may be the same as ``Par1`` + . Starting array element numbers must be defined for each array parameter vector if it does not + start at the first location. For example, :ref:`vfun` ,A,SQRT,B(5) takes the square root of the + fifth element of B and stores the result in the first element of A. Operations continue on + successive array elements ( :ref:`vlen`, :ref:`vmask` ) with the default being all successive + elements. Absolute values and scale factors may be applied to all parameters ( :ref:`vabs` , + :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). Skipping array elements via :ref:`vmask` + or :ref:`vlen` for the TANG and NORM functions skips only the writing of the results (skipped array + element data are used in all calculations). See the :ref:`voper` command for details. + + This command is valid in any processor. + """ + command = f"*VFUN,{parr},{func},{par1},{con1},{con2},{con3}" + return self.run(command, **kwargs) + + def vfact( + self, + factr: str = "", + fact1: str = "", + fact2: str = "", + fact3: str = "", + **kwargs, + ): + r"""Applies a scale factor to array parameters. + + Mechanical APDL Command: `\*VFACT `_ + + Parameters + ---------- + factr : str + Scale factor applied to results (ParR) parameter. Defaults to 1.0. + + fact1 : str + Scale factor applied to first parameter (Par1 or ParI). Defaults to 1.0. + + fact2 : str + Scale factor applied to second parameter (Par2 or ParJ). Defaults to 1.0. + + fact3 : str + Scale factor applied to third parameter (Par3 or ParK). Defaults to 1.0. + + Notes + ----- + Applies a scale factor to parameters used in certain **\*V** ``XX`` and **\*M** ``XX`` operations. + Typical scale factor applications are of the form: ParR = ``FACTR`` *f( ``FACT1`` *Par1) + + or + + ParR = ``FACTR`` *(( ``FACT1`` *Par1) o ( ``FACT2`` *Par2)) + + The factors are applied to each input parameter value before the operation and to the result value + after the operation. The scale factor settings are reset to the default (1.0) after each **\*V** + ``XX`` or **\*M** ``XX`` operation. Use :ref:`vstat` to list settings. + + This command is valid in any processor. + """ + command = f"*VFACT,{factr},{fact1},{fact2},{fact3}" + return self.run(command, **kwargs) + + def vcum(self, key: str = "", **kwargs): + r"""Allows array parameter results to add to existing results. + + Mechanical APDL Command: `\*VCUM `_ + + Parameters + ---------- + key : str + Accumulation key: + + * ``0`` - Overwrite results. + + * ``1`` - Add results to the current value of the results parameter. + + Notes + ----- + Allows results from certain **\*V** ``XX`` and **\*M** ``XX`` operations to overwrite or add to + existing results. The cumulative operation is of the form: ParR = ParR + ParR(Previous) + + The cumulative setting is reset to the default (overwrite) after each **\*V** ``XX`` or **\*M** + ``XX`` operation. Use :ref:`vstat` to list settings. + + This command is valid in any processor. + """ + command = f"*VCUM,{key}" + return self.run(command, **kwargs) + + def vlen(self, nrow: str = "", ninc: str = "", **kwargs): + r"""Specifies the number of rows to be used in array parameter operations. + + Mechanical APDL Command: `\*VLEN `_ + + Parameters + ---------- + nrow : str + Number of rows to be used with the **\*V** ``XX`` or **\*M** ``XX`` operations. Defaults to the + number of rows needed to fill the result array. + + ninc : str + Perform the operation on every ``NINC`` row (defaults to 1). + + Notes + ----- + Specifies the number of rows to be used in array parameter operations. The size of the submatrix + used is determined from the upper left starting array element (defined on the operation command) to + the lower right array element (defined by the number of rows on this command and the number of + columns on the :ref:`vcol` command). ``NINC`` allows skipping row operations for some operation + commands. Skipped rows are included in the row count. The starting row number must be defined on the + operation command for each parameter read and for the result written. + + The default ``NROW`` is calculated from the maximum number of rows of the result array (the + :ref:`dim` row dimension) minus the starting location + 1. For example, :ref:`dim` ,R,,10 and a + starting location of R(7) gives a default of 4 loops (filling R(7), R(8), R(9), and R(10)). Repeat + operations automatically terminate at the last row of the result array. Existing values in the rows + and columns of the results matrix remain unchanged where not overwritten by the requested input or + operation values. + + The stride ( ``NINC`` ) allows operations to be performed at regular intervals. It has no effect on + the total number of row operations. Skipped operations retain the previous result. For example, + :ref:`dim` ,R,,6, with a starting location of R(1), ``NROW`` = 10, and ``NINC`` = 2 calculates + values for locations R(1), R(3), and R(5) and retains values for locations R(2), R(4), and R(6). A + more general skip control may be done by masking ( :ref:`vmask` ). The row control settings are + reset to the defaults after each **\*V** ``XX`` or **\*M** ``XX`` operation. Use :ref:`vstat` to + list settings. + + This command is valid in any processor. + """ + command = f"*VLEN,{nrow},{ninc}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/encryption_decryption.py b/src/ansys/mapdl/core/_commands/apdl/encryption_decryption.py new file mode 100644 index 0000000000..3ea4b21ae6 --- /dev/null +++ b/src/ansys/mapdl/core/_commands/apdl/encryption_decryption.py @@ -0,0 +1,218 @@ +# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + + +class EncryptionDecryption: + + def encrypt(self, key: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Controls encryption of command input. + + Mechanical APDL Command: `/ENCRYPT `_ + + Parameters + ---------- + key : str + Encryption key used to encrypt the data (32-character maximum). A character parameter may be + used. If the key is unspecified, encryption is turned off. + + fname : str + Name of file (including directory path) where the encrypted commands are written (248-character + maximum for both file name and directory). An unspecified directory path defaults to the working + directory; in this case, you can use all 248 characters for the file name. + + ext : str + File name extension (eight-character maximum). + + Notes + ----- + This command opens the encrypted file specified by ``Fname`` and ``Ext`` for writing encrypted input + commands. + + Issuing this command results in a new file that overwrites any data in an existing file by the same + name. When the encrypted file is written, the first line in the file is ``/DECRYPT`` + ,PASSWORD,OPENSSL and the last line is ``/DECRYPT``. + + See `Encrypting Command Input and Other Data + `_ + :ref:`encrypt` and performing encryption and decryption. + """ + command = f"/ENCRYPT,{key},{fname},{ext}" + return self.run(command, **kwargs) + + def decrypt(self, key1: str = "", key2: str = "", **kwargs): + r"""Controls decryption of command input. + + Mechanical APDL Command: `/DECRYPT `_ + + Parameters + ---------- + key1 : str + Key to decrypt the encrypted input created by :ref:`encrypt` . The only valid label is PASSWORD. + + key2 : str + Key to decrypt the encrypted input or to set the global encryption key. The following are valid + inputs: + + If ``Key2`` = OPENSSL or is blank, then decryption commences and the previously set global + encryption key is used for decryption. If ``Key2`` has a value, then that value is set as the + global encryption key. If ``Key2`` = OFF, then the global encryption password previously set by + the command :ref:`decrypt` ,PASSWORD, ``Key2`` is reset. + + Notes + ----- + When decrypting an encrypted input, ``/DECRYPT,PASSWORD,OPENSSL`` must appear as the first line of + the encrypted file. The line is inserted automatically when you issue :ref:`encrypt` to create the + encrypted file. + + To read an encrypted file, enter :ref:`decrypt` ,PASSWORD, ``Key2`` anywhere in the standard input + file to set the global encryption key. The encryption key must be set before reading in the + encrypted input. + + :ref:`decrypt` is also valid when entered in the Command Input Window of the Mechanical APDL user + interface. + + See `Encrypting Command Input and Other Data + `_ + :ref:`decrypt` and performing encryption and decryption. + """ + command = f"/DECRYPT,{key1},{key2}" + return self.run(command, **kwargs) + + def dbdecrypt( + self, + keya: str = "", + keyb: str = "", + datatype: str = "", + num1: str = "", + num2: str = "", + inc: str = "", + **kwargs, + ): + r"""Controls decryption of material data in the database file. + + Mechanical APDL Command: `/DBDECRYPT `_ + + Parameters + ---------- + keya : str + Decryption key A (32-character maximum). This key is used to decrypt the data in a one-level + encryption or to control access to the data in a two-level encryption. Leave this field blank if + you do not have key A. + + keyb : str + Decryption key B (32-character maximum). This key is used to decrypt the data in a two-level + encryption. Leave this field blank if the database file is encrypted with one-level encryption. + + datatype : str + Type of data to decrypt. Must be set to MAT for material data. + + num1 : str + Decrypt materials from material number ``NUM1`` to ``NUM2`` (defaults to ``NUM1`` ) in steps of + ``INC`` (defaults to 1). If ``NUM1`` = ALL (default), ``NUM2`` and ``INC`` are ignored. + + num2 : str + Decrypt materials from material number ``NUM1`` to ``NUM2`` (defaults to ``NUM1`` ) in steps of + ``INC`` (defaults to 1). If ``NUM1`` = ALL (default), ``NUM2`` and ``INC`` are ignored. + + inc : str + Decrypt materials from material number ``NUM1`` to ``NUM2`` (defaults to ``NUM1`` ) in steps of + ``INC`` (defaults to 1). If ``NUM1`` = ALL (default), ``NUM2`` and ``INC`` are ignored. + + Notes + ----- + This command decrypts data in the database file. It must be issued before resuming the database file + ( :ref:`resume` command). Only ``KeyA`` is required for a one-level encryption . For a `two-level + encryption + `_ + , inputting ``KeyB`` gives you partial access to the data. Inputting both ``KeyA`` and ``KeyB`` + gives you full access. + + For more information about using :ref:`dbdecrypt` in the encryption/decryption procedure, see + `Encrypting Material Data + `_ + :ref:`dbencrypt` command. + + This command is valid in any processor. + """ + command = f"/DBDECRYPT,{keya},{keyb},{datatype},{num1},{num2},{inc}" + return self.run(command, **kwargs) + + def dbencrypt( + self, + keya: str = "", + keyb: str = "", + datatype: str = "", + num1: str = "", + num2: str = "", + inc: str = "", + **kwargs, + ): + r"""Controls encryption of material data in the database file. + + Mechanical APDL Command: `/DBENCRYPT `_ + + Parameters + ---------- + keya : str + Encryption key A (32-character maximum). This key is used to encrypt the data in a one-level + encryption or to control access to the data in a two-level encryption. + + keyb : str + Encryption key B (32-character maximum). This key is used to encrypt the data in a two-level + encryption . If ``KeyB`` is not specified, a one-level encryption is used to encrypt the data. + + datatype : str + Type of data to encrypt. Must be set to MAT for material data. + + num1 : str + Encrypt materials from material number ``NUM1`` to ``NUM2`` (defaults to ``NUM1`` ) in steps of + ``INC`` (defaults to 1). If ``NUM1`` = ALL (default), ``NUM2`` and ``INC`` are ignored. + + num2 : str + Encrypt materials from material number ``NUM1`` to ``NUM2`` (defaults to ``NUM1`` ) in steps of + ``INC`` (defaults to 1). If ``NUM1`` = ALL (default), ``NUM2`` and ``INC`` are ignored. + + inc : str + Encrypt materials from material number ``NUM1`` to ``NUM2`` (defaults to ``NUM1`` ) in steps of + ``INC`` (defaults to 1). If ``NUM1`` = ALL (default), ``NUM2`` and ``INC`` are ignored. + + Notes + ----- + This command encrypts data in the database file. It must be issued before saving the database file ( + :ref:`save` command). + + For a one-level encryption, specify only ``KeyA`` and set ``NUM1`` to ALL. ( ``NUM2`` and ``INC`` + are not used.) + + For a `two-level encryption + `_ + , specify both ``KeyA`` and ``KeyB``. Also specify ``NUM1``, ``NUM2``, and ``INC`` as needed. + + For more information about using :ref:`dbencrypt` in the encryption/decryption procedure, see + `Encrypting Material Data + `_ + :ref:`dbdecrypt` command. + + This command is valid in any processor. + """ + command = f"/DBENCRYPT,{keya},{keyb},{datatype},{num1},{num2},{inc}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/macro_files.py b/src/ansys/mapdl/core/_commands/apdl/macro_files.py index 3c26402ca1..459533ba12 100644 --- a/src/ansys/mapdl/core/_commands/apdl/macro_files.py +++ b/src/ansys/mapdl/core/_commands/apdl/macro_files.py @@ -22,570 +22,693 @@ class MacroFiles: - def cfclos(self, **kwargs): - """Closes the "command" file. - APDL Command: ``*CFCLOS`` + def pmacro(self, **kwargs): + r"""Specifies that macro contents be written to the session log file. + + Mechanical APDL Command: `/PMACRO `_ Notes ----- - This command is valid in any processor. + This command forces the contents of a macro or other input file to be written to ``Jobname.LOG``. + It is valid only within a macro or input file, and should be placed at the top of the file. + :ref:`pmacro` should be included in any macro or input file that calls GUI functions. """ - command = f"*CFCLOS," + command = "/PMACRO" return self.run(command, **kwargs) - def cfopen(self, fname="", ext="", loc="", **kwargs): - """Opens a "command" file. + def psearch(self, pname: str = "", **kwargs): + r"""Specifies a directory to be searched for "unknown command" macro files. - APDL Command: ``*CFOPEN`` - - .. warning:: - This command must be run using :func:`non_interactive - ` + Mechanical APDL Command: `/PSEARCH `_ 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). - - loc - Determines whether existing file will be overwritten or appended: - - (blank) : The existing file will be overwritten. - APPEND : The file will be appended to the existing file. + pname : str + Path name (64 characters maximum, and must include the final delimiter) of the middle directory + to be searched. Defaults to the user home directory. If ``Pname`` = OFF, search only the program + and current working directories. If ``Pname`` = STAT, list the current middle directory and show + the ANSYS_MACROLIB setting. Notes ----- - Data processed with the ``*VWRITE`` command will also be written to this - file if the file is open when the ``*VWRITE`` command is issued. + Specifies the pathname of a directory for file searches when reading unknown-command macro files. - This command is valid in any processor. + The search for the files is typically from the program directory, then from the user home directory, + and then from the current working directory. The command allows the middle directory searched to be + other than the user home directory. + + This command is valid only at the Begin level. """ - return self.run(f"*CFOPEN,{fname},{ext},,{loc}", **kwargs) + command = f"/PSEARCH,{pname}" + return self.run(command, **kwargs) - def cfwrite(self, command="", **kwargs): - """Writes an ANSYS command (or similar string) to a "command" file. + def ulib(self, fname: str = "", ext: str = "", **kwargs): + r"""Identifies a macro library file. - APDL Command: ``*CFWRITE`` + Mechanical APDL Command: `\*ULIB `_ Parameters ---------- - command - Command or string to be written. The standard command form of a - label followed by arguments separated by commas is assumed. - Command may be a parameter assignment (e.g., ``*CFWRITE, A = 5``). + fname : str + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, + you can use all 248 characters for the file name. + + ext : str + Filename extension (eight-character maximum). Notes ----- - Writes an ANSYS command (or similar string) to the file opened - with ``*CFOPEN``. The Command string is not executed (except - that numeric and character parameter substitution and - operations (with embedded ``*``, /, >,$ etc. characters) are - performed before writing). When used with ``*GET`` results - and parameter substitution, an ANSYS command can be created - from results and then read back into the ANSYS program (or - used elsewhere). For example, if the command - ``*CFWRITE,BF,NNUM,TEMP,TVAL`` is used in a do-loop, where - TVAL is a parameter value returned from the ``*GET`` operation - and NNUM is a specified or returned parameter value, a series - of BF commands, with numerical values substituted for the two - parameters, will be written. To create a file without - parameter substitution, use ``*CREATE``. + Identifies a macro library file for the :ref:`use` command. + + A library of macros allows blocks of often-used commands to be stacked and executed from a single + file. The macro blocks must be enclosed within block identifier and terminator lines as shown in + this example: Macro Blocks + + .. code:: apdl + + ABC! Any valid alphanumeric name (32 characters maximum) + ! identifying this data block + ---! Mechanical APDL data-input commands + --- + --- + /EOF! Terminator for this data block + XYZ! Identify another data block (if desired) + ---! Mechanical APDL data-input commands + --- + --- + /EOF! Terminator for this data block + (etc.) + + To add comment lines to a macro block, place them anywhere within the macro block, including + directly on the lines where the macro block identifier and the macro + block terminator appear as shown in the example. Do not place comment lines (or any other lines) + outside of a macro block. + + The name of the macro library file is identified for reading via :ref:`ulib` . The name of the macro + block is identified via :ref:`use` . + + Commands within the macro block are copied to a temporary file (of the macro block name) during the + :ref:`use` operation and executed as if a macro file of that name had been created. The temporary + file is deleted after it has been used. + + Macro block names should be acceptable file names (system-dependent) and should not match user- + created macro file names, as the user-created macro file is used first (if it exists) before the + library file is searched. + + Macro blocks may be stacked in any order. Branching ( ``\*GO`` or ``\*IF`` ) external to the macro + block is not allowed. This command is valid in any processor. """ - command = f"*CFWRITE,{command}" + command = f"*ULIB,{fname},{ext}" return self.run(command, **kwargs) - def create(self, fname="", ext="", **kwargs): - """Opens (creates) a macro file. + def use( + self, + name: str = "", + arg1: str = "", + arg2: str = "", + arg3: str = "", + arg4: str = "", + arg5: str = "", + arg6: str = "", + arg7: str = "", + arg8: str = "", + arg9: str = "", + ar10: str = "", + ar11: str = "", + ar12: str = "", + ar13: str = "", + ar14: str = "", + ag15: str = "", + ar16: str = "", + ar17: str = "", + ar18: str = "", + **kwargs, + ): + r"""Executes a macro file. - APDL Command: ``*CREATE`` - - .. warning:: - This command must be run using :func:`non_interactive - ` + Mechanical APDL Command: `\*USE `_ 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). + name : str + Name (32 characters maximum, beginning with a letter) identifying the macro file or a macro + block on a macro library file. + + arg1 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg2 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg3 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg4 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg5 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg6 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg7 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg8 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg9 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + ar10 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation `_ + for further information. + + ar11 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation `_ + for further information. + + ar12 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation `_ + for further information. + + ar13 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation `_ + for further information. + + ar14 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation `_ + for further information. + + ag15 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation `_ + for further information. + + ar16 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation `_ + for further information. + + ar17 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation `_ + for further information. + + ar18 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation `_ + for further information. Notes ----- - See the ``*USE`` command for a discussion of macros. All - commands following the ``*CREATE`` command, up to the ``*END`` - command, are written to the specified file without being - executed. An existing file of the same name, if any, will be - overwritten. Parameter values are not substituted for - parameter names in the commands when the commands are written - to the file. Use ``*CFWRITE`` to create a file if this is - desired. The resulting macro may be executed with a ``*USE`` - command (which also allows parameters to be passed into the - macro) or a /INPUT command (which does not allow parameters to - be passed in). Several macros may be stacked into a library - file ``[*ULIB]``. You cannot use ``*CREATE`` within a DO loop. + Causes execution of a macro file called ``Name``, or, if not found, a macro block " ``Name`` " on + the macro library file ( :ref:`ulib` ). Argument values (numeric or character) are passed into the + file or block and substituted for local parameters ARG1, ARG2, ..., AR18. The file ``Name`` may also + be executed as an "unknown command" (that is, without the :ref:`use` command name) as described + below. + + A macro is a sequence of Mechanical APDL commands (as many as needed) recorded in a file or in a + macro + block in a library file (specified with the :ref:`ulib` command). The file or block is typically + executed via :ref:`use` . In addition to command, numerical and alphanumeric data, the macro can + include parameters which will be assigned numerical or alphanumerical character values when the + macro is used. Use of the macro can be repeated (within a do-loop, for example) with the parameters + incremented. + + A macro is defined within a run by enclosing a sequence of data input commands between :ref:`create` + and :ref:`end` commands. The data input commands are passive (not executed) while being written to + the macro file. The macro file (without :ref:`create` and :ref:`end` ) can also be created external + to Mechanical APDL. + + Up to 99 specially named scalar parameters, ARG1 to AR99, are locally available to each macro: + + The prefix for the first nine parameters is ARG, and the prefix for the remaining 90 parameters is + AR. + A local parameter is not affected by, nor does it affect, other parameters, even those of the same + name, which are used outside of the macro. The only way a local parameter can affect, or be affected + by, parameters outside the macro is if values are passed out of, or into, the macro by an argument + list. + Parameters ARG1 through AR18 can have their values (numeric or character) passed via the argument + list on :ref:`use` . (ARG1 through AR19 can be passed as arguments on the unknown-command macro.) + Parameters AR19 through AR99 (AR20 through AR99 in the unknown-command macro) are available solely + for use within the macro; they cannot be passed via an argument list. + Local parameters are available to do-loops and to :ref:`input` files processed within the macro. In + addition to an ARG1--AR99 set for each macro, another ARG1--AR99 set is available external to all + macros, local to "non-macro" space. + + A macro is exited after its last line is executed. Macros may be nested (such as a :ref:`use` or an + unknown command within a macro). Each nested macro has its own set of 99 local parameters. Only one + set of local parameters can be active at a time and that is the set corresponding to the macro + currently being executed or to the set external to all macros (if any). When a nested macro + completes execution, the previous set of local parameters once again becomes available. Issue + :ref:`starstatus` ,ARGX to view current macro parameter values. + + An alternate way of executing a macro file is via the unknown-command route. If a command unknown to + Mechanical APDL is entered, a search for a file of that name (plus a ``.MAC`` suffix) is made. If + the file exists, it is executed, if not, the "unknown command" message is output. Thus, you can + write your own commands in terms of other Mechanical APDL commands. The procedure is similar to + issuing :ref:`use` with the unknown command in the ``Name`` field. For example, the command **CMD** + ,10,20,30 is internally similar to :ref:`use` ,CMD,10,20,30. The macro file named ``CMD.MAC`` is + executed with the three parameters. The :ref:`use` macro description also applies to the unknown- + command macro, except that various directories are searched and a suffix ( ``.MAC`` ) is assumed. + Also, a macro library file is not searched. + + A three-level directory search for the unknown-command macro file may be available. The search order + may be: 1) a high-level system directory, 2) the log-in directory, and 3) the local (working) + directory. Issue :ref:`psearch` to change the directory search path. For an unknown command **CMD** + , the first file named ``CMD.MAC`` found to exist in the search order is executed. The command can + be input in lower-, upper-, or mixed-case; however, it converts to uppercase automatically before + the file name search occurs. On systems that preserve the case as it was input, a file matching the + upper-case name is used first, followed by a file with the matching the lower-case name, and finally + a file matching the mixed-case name. All macro files placed in the ``apdl`` directory must be upper- + case. + + Because undocumented commands exist in Mechanical APDL, you should issue the command intended for + the macro + file name to ensure that the unknown-command message is output in the processor where it is to be + used. If the macro is to be used in other processors, the other processors must also be checked. This command is valid in any processor. """ - return self.run(f"*CREATE,{fname},{ext}", **kwargs) + command = f"*USE,{name},{arg1},{arg2},{arg3},{arg4},{arg5},{arg6},{arg7},{arg8},{arg9},{ar10},{ar11},{ar12},{ar13},{ar14},{ag15},{ar16},{ar17},{ar18}" + return self.run(command, **kwargs) - def dflab(self, dof="", displab="", forcelab="", **kwargs): - """Changes degree-of-freedom labels for user custom elements. + def cfwrite(self, command: str = "", **kwargs): + r"""Writes a Mechanical APDL command (or similar string) to a "command" file. - APDL Command: /DFLAB + Mechanical APDL Command: `\*CFWRITE `_ Parameters ---------- - dof - Number between 1 and 32 indicating which degree of freedom is to - have its labels changed. For a list of these quantities, see the - degree-of-freedom table in the echprm.inc file. The first few - quantities follow: + command : str + Command or string to be written. The standard command form of a label followed by arguments + separated by commas is assumed. ``Command`` may be a parameter assignment (for example, + :ref:`cfwrite`, A = 5). - displab - New label (four-character maximum) for the displacement label. The - prior label is no longer valid. + Notes + ----- + Writes a Mechanical APDL command (or similar string) to the file opened via :ref:`cfopen` . The + ``Command`` string is not executed (except that numeric and character parameter substitution and + operations (with imbedded *, /, >, etc. characters) are performed before writing). - forcelab - New label (four-character maximum) for the force label for this - degree of freedom. The prior label is no longer valid. + When used with :ref:`get` results and parameter substitution, a command can be created from results + and then read back into the Mechanical APDL program (or used elsewhere). For example, if the command + :ref:`cfwrite` ,BF,NNUM,TEMP,TVAL is used in a do-loop, where TVAL is a parameter value returned + from the :ref:`get` operation and NNUM is a specified or returned parameter value, a series of + :ref:`bf` commands, with numerical values substituted for the two parameters, will be written. + + To create a file without parameter substitution, issue :ref:`create` . + + This command is valid in any processor. + """ + command = f"*CFWRITE,{command}" + return self.run(command, **kwargs) + + def cfclos(self, **kwargs): + r"""Closes the "command" file. + + Mechanical APDL Command: `\*CFCLOS `_ Notes ----- - The /DFLAB command is rarely used. Use it if you are writing a custom - element and want to use degrees of freedom that are not part of the - standard element set. + This command is valid in any processor. """ - command = f"/DFLAB,{dof},{displab},{forcelab}" + command = "*CFCLOS" return self.run(command, **kwargs) - def end(self, **kwargs): - """Closes a macro file. + def cfopen(self, fname: str = "", ext: str = "", loc: str = "", **kwargs): + r"""Opens a "command" file. + + Mechanical APDL Command: `\*CFOPEN `_ + + 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 ``Jobname``. - APDL Command: ``*END`` + ext : str + Filename extension (eight-character maximum). The extension defaults to CMD if ``Fname`` is + blank. + + loc : str + Determines whether existing file will be overwritten or appended: + + * ```` - The existing file will be overwritten. + + * ``APPEND`` - The file will be appended to the existing file. Notes ----- - Closes a file opened with ``*CREATE``. The ``*END`` command is an 8-character - command (to differentiate it from ``*ENDIF``). If you add commented text - on that same line but do not allow enough spaces between ``*END`` and the - "!" that indicates the comment text, the ``*END`` will attempt to interpret - the "!" as the 8th character and will fail. + Mechanical APDL commands specified by the :ref:`cfwrite` command are written to the file opened by + :ref:`cfopen` . Data processed with the :ref:`vwrite` command are also written to this file if the + file is open when the :ref:`vwrite` command is issued. + + Issue the :ref:`cfclos` command to close the command file. This command is valid in any processor. """ - command = f"*END," + command = f"*CFOPEN,{fname},{ext},,{loc}" return self.run(command, **kwargs) - def mkdir(self, dir_="", **kwargs): - """Creates a directory. + def create(self, fname: str = "", ext: str = "", **kwargs): + r"""Opens (creates) a macro file. + + Mechanical APDL Command: `\*CREATE `_ - APDL Command: /MKDIR + .. warning:: + This command must be run using :func:`non_interactive ` + Please visit `Unsupported Interactive Commands `_ + for further information. Parameters ---------- - dir_ - The directory to create (248 characters maximum on Linux; - 233 on Windows). If no path is provided, it will be - created in the current working directory. Must be a valid - name (and path) for the system you are working on. + 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. Do not use a directory path if file is to be + read with the macro ``Name`` option of the :ref:`use` command. + + ext : str + Filename extension (eight-character maximum). ``Ext`` should not be used if file is to be read + with the macro ``Name`` option of the :ref:`use` command. Notes ----- - It is recommended to just use ``os.mkdir`` + See the :ref:`use` command for a discussion of macros. All commands following the :ref:`create` + command, up to the :ref:`end` command, are written to the specified file without being executed. An + existing file of the same name, if any, will be overwritten. Parameter values are not substituted + for parameter names in the commands when the commands are written to the file. Use :ref:`cfwrite` to + create a file if this is desired. The resulting macro may be executed with a :ref:`use` command + (which also allows parameters to be passed into the macro) or a :ref:`input` command (which does not + allow parameters to be passed in). Several macros may be stacked into a library file ( :ref:`ulib` + ). You cannot use :ref:`create` within a DO loop. - Creates a directory on the computer ANSYS is currently running on. + This command is valid in any processor. """ - command = f"/MKDIR,{dir_}" + command = f"*CREATE,{fname},{ext}" return self.run(command, **kwargs) def msg( self, - lab="", - val1="", - val2="", - val3="", - val4="", - val5="", - val6="", - val7="", - val8="", + lab: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + val7: str = "", + val8: str = "", **kwargs, ): - """Writes an output message via the ANSYS message subroutine. + r"""Writes an output message via the Mechanical APDL message subroutine. - APDL Command: ``*MSG`` + Mechanical APDL Command: `\*MSG `_ Parameters ---------- - lab + lab : str Label for output and termination control: - Writes the message with no heading (default). - Writes the - message with a "NOTE" heading. + * ``INFO`` - Writes the message with no heading (default). + + * ``NOTE`` - Writes the message with a "NOTE" heading. + + * ``WARN`` - Writes the message with a "WARNING" heading. Also writes the message to the errors + file, ``Jobname.ERR``. + + * ``ERROR`` - Writes the message with a "ERROR" heading and causes run termination (if batch) at + earliest "clean exit" point. Also writes the message to the errors file, ``Jobname.ERR``. + + * ``FATAL`` - Writes the message with a "FATAL ERROR" heading and causes run termination + immediately. Also writes the message to the errors file, ``Jobname.ERR``. - Writes the message with a "WARNING" heading. Also writes - the message to the errors file, Jobname.ERR. - Writes the - message with a "ERROR" heading and causes run termination - (if batch) at earliest "clean exit" point. Also writes - the message to the errors file, Jobname.ERR. + * ``UI`` - Writes the message with a "NOTE" heading and displays it in the message dialog box. + This option is most useful in GUI mode. - Writes the message with a "FATAL ERROR" heading and causes - run termination immediately. Also writes the message to - the errors file, Jobname.ERR. - Writes the message with a - "NOTE" heading and displays it in the message dialog box. - This option is most useful in GUI mode. + val1 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. - val1, val2, val3, . . . , val8 - Numeric or alphanumeric character values to be included in message. - Values may be the results of parameter evaluations. All numeric - values are assumed to be double precision. The FORTRAN nearest - integer (NINT) function is used to form integers for the %I - specifier. + val2 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. + + val3 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. + + val4 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. + + val5 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. + + val6 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. + + val7 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. + + val8 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. Notes ----- - Allows writing an output message via the ANSYS message subroutine. - Also allows run termination control. This command is used only when - contained in a prepared file read into the ANSYS program (i.e., - ``*USE,/INPUT``, etc.). A message format must immediately follow the ``*MSG`` + Allows writing an output message via the Mechanical APDL message subroutine. Also allows run + termination + control. This command is used only when contained in a prepared file read into the Mechanical APDL + program + (that is, :ref:`use`, :ref:`input`, etc.). A message format must immediately follow the :ref:`msg` command (on a separate line, without parentheses, as described below). - The message format may be up to 80 characters long, consisting of text - strings and predefined "data descriptors" between the strings where - numeric or alphanumeric character data are to be inserted. The normal - descriptors are %I for integer data, %G for double precision data, %C - for alphanumeric character data, and %/ for a line break. The - corresponding FORTRAN data descriptors are I9, 1PG16.9 and A8, - respectively. Each descriptor must be preceded by a blank. There must - be one data descriptor for each specified value (8 maximum) in the - order of the specified values. - - Enhanced descriptions may also be used: - - Do not begin ``*MSG`` format lines with ``*IF``, ``*ELSE`` , - ``*ELSEIF``, or ``*ENDIF`` . If the last nonblank character - of the message format is an ampersand (&), a second line will - also be read as a continuation of the format. Up to nine - continuations (ten total lines) may be read. If normal - descriptions are used, then consecutive blanks are condensed - into one blank upon output, and a period is appended. Up to - ten lines of output of 72 characters each may be produced - (using the %/ descriptor). Two examples follow. - - Here is an example of the ``*MSG`` command and a format to print a message - with two integer values and one real value: + The message format may be up to 80 characters long, consisting of text strings and predefined "data + descriptors" between the strings where numeric or alphanumeric character data are to be inserted. + The normal descriptors are %I for integer data, %G for double precision data, %C for alphanumeric + character data, and %/ for a line break. The corresponding FORTRAN data descriptors are I9, 1PG16.9 + and A8, respectively. Each descriptor must be preceded by a blank. There must be one data descriptor + for each specified value (8 maximum) in the order of the specified values. + + Enhanced descriptions may also be used: InformalTables need to be added. + + Do not begin :ref:`msg` format lines with ``\*IF``, ``\*ELSE``, ``\*ELSEIF``, or ``\*ENDIF``. If the + last nonblank character of the message format is an ampersand (&), a second line will also be read + as a continuation of the format. Up to nine continuations (ten total lines) may be read. If normal + descriptions are used, then consecutive blanks are condensed into one blank upon output, and a + period is appended. Up to ten lines of output of 72 characters each may be produced (using the %/ + descriptor). Two examples follow. + + Here is an example of the :ref:`msg` command and a format to print a message with two integer values + and one real value: + + .. code:: apdl + + *MSG, INFO, 'Inner',25,1.2,148 + Radius ( %C) = %I, Thick = %G, Length = %I The output line is: - Here is an example illustrating multiline displays in GUI message - windows: + .. code:: apdl - Note:: : The /UIS,MSGPOP command controls which messages are displayed - in the message dialog box when the GUI is active. All messages - produced by the ``*MSG`` command are subject to the /UIS specification, - with one exception, If Lab = UI, the message will be displayed in the - dialog box regardless of the /UIS specification. + Radius (Inner) = 25, Thick = 1.2, Length = 148. - This command is valid in any processor. + Here is an example illustrating multiline displays in GUI message windows: - """ - command = f"*MSG,{lab},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8}" - return self.run(command, **kwargs) + .. code:: apdl - def pmacro(self, **kwargs): - """Specifies that macro contents be written to the session log file. + *MSG,UI,Vcoilrms,THTAv,Icoilrms,THTAi,Papprnt,Pelec,PF,indctnc + Coil RMS voltage, RMS current, apparent pwr, actual pwr, pwr factor: %/& + Vcoil = %G V (electrical angle = %G DEG) %/& + Icoil = %G A (electrical angle = %G DEG) %/& + APPARENT POWER = %G W %/& + ACTUAL POWER = %G W %/& + Power factor: %G %/& + Inductance = %G %/& + VALUES ARE FOR ENTIRE COIL (NOT JUST THE MODELED SECTOR) - APDL Command: /PMACRO + The :ref:`uis` ,MSGPOP command controls which messages are displayed in the message dialog box when + the GUI is active. All messages produced by the :ref:`msg` command are subject to the :ref:`uis` + specification, with one exception, If ``Lab`` = UI, the message will be displayed in the dialog box + regardless of the :ref:`uis` specification. - Notes - ----- - This command forces the contents of a macro or other input file to be - written to Jobname.LOG. It is valid only within a macro or input file, - and should be placed at the top of the file. /PMACRO should be - included in any macro or input file that calls GUI functions. + This command is valid in any processor. """ - command = f"/PMACRO," + command = f"*MSG,{lab},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8}" return self.run(command, **kwargs) - def psearch(self, pname="", **kwargs): - """Specifies a directory to be searched for "unknown command" macro files. + def mkdir(self, dir_: str = "", **kwargs): + r"""Creates a directory. - APDL Command: /PSEARCH + Mechanical APDL Command: `/MKDIR `_ Parameters ---------- - pname - Path name (64 characters maximum, and must include the final - delimiter) of the middle directory to be searched. Defaults to the - user home directory. If Pname = OFF, search only the ANSYS and - current working directories. If Pname = STAT, list the current - middle directory and show the ANSYS_MACROLIB setting. + dir_ : str + The directory to create (248 characters maximum on Linux; 233 on Windows). If no path is + provided, it will be created in the current working directory. Must be a valid name (and path) + for the system you are working on. Notes ----- - Specifies the pathname of a directory for file searches when reading - "unknown command" macro files. The search for the files is typically - from the ANSYS directory, then from the user home directory, and then - from the current working directory. This command allows the middle - directory searched to be other than the user home directory. - - This command is valid only at the Begin Level. + Creates a directory on the computer Mechanical APDL is currently running on. """ - command = f"/PSEARCH,{pname}" + command = f"/MKDIR,{dir_}" return self.run(command, **kwargs) - def rmdir(self, dir_="", **kwargs): - """Removes (deletes) a directory. + def end(self, **kwargs): + r"""Closes a macro file. - APDL Command: /RMDIR - - Parameters - ---------- - dir\\_ - The directory to remove. If no path is provided, it will be assumed - to be in the current working directory. All files in the directory - are also removed. + Mechanical APDL Command: `\*END `_ Notes ----- - Removes a directory on the computer ANSYS is currently running on. No - warning or prompt is given, so use with extreme caution. + Closes a file opened with :ref:`create` . The :ref:`end` command is an 8-character command (to + differentiate it from ``\*ENDIF`` ). If you add commented text on that same line but do not allow + enough spaces between :ref:`end` and the "!" that indicates the comment text, the :ref:`end` will + attempt to interpret the "!" as the 8th character and will fail. + + This command is valid in any processor. """ - command = f"/RMDIR,{dir_}" + command = "*END" return self.run(command, **kwargs) - def tee(self, label="", fname="", ext="", **kwargs): - """Writes a list of commands to a specified file at the same time that the + def slashtee(self, label: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Writes a list of commands to a specified file at the same time that the commands are being executed. - APDL Command: /TEE - commands are being executed. + Mechanical APDL Command: `/TEE `_ Parameters ---------- - label - Indicates how ANSYS is to interpret this /TEE command: - - Signals the beginning of the command text that is to be - written to Fname. If Fname already exists, specifying NEW - causes the contents of Fname to be overwritten. - - Indicates that you want to append to Fname the command - text that follows. - - 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). + label : str + Specifies how Mechanical APDL is to interpret this :ref:`slashtee` command: - Notes - ----- - You can use the /TEE command to record a macro to a specified file at - the same time that the macro is being executed. It is similar to the - Linux tee command. + * ``NEW`` - Signals the beginning of the command text that is to be written to ``Fname``. If + ``Fname`` already exists, specifying NEW causes the contents of ``Fname`` to be overwritten. - For more information about the /TEE command, see the Introducing APDL - of the ANSYS Parametric Design Language Guide. + * ``APPEND`` - Indicates that you want to append to ``Fname`` the command text that follows. - The following example illustrates the use of the /TEE command. If you - issue these commands: + * ``END`` - Signals the end of the command text that is to be written to or appended to ``Fname`` + . - the content of myfile.mac is: + 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. - This command is valid in any processor, but only during an interactive - run. - """ - command = f"/TEE,{label},{fname},{ext}" - return self.run(command, **kwargs) + ext : str + Filename extension (eight-character maximum). If you plan to execute the file as if it were a + Mechanical APDL command, use the extension ``.mac``. - def ulib(self, fname="", ext="", **kwargs): - """Identifies a macro library file. + Notes + ----- + You can use the :ref:`slashtee` command to record a macro to a specified file at the same time that + the macro is being executed. It is similar to the Linux **tee** command. - APDL Command: ``*ULIB`` + For more information about the :ref:`slashtee` command, see the of the `Ansys Parametric Design + Language Guide `_ + ANSYS Parametric Design Language Guide. - 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. + The following example illustrates the use of the :ref:`slashtee` command. If you issue these + commands: - ext - Filename extension (eight-character maximum). + .. code:: apdl - Notes - ----- - Identifies a macro library file for the ``*USE`` command. A - library of macros allows blocks of often used ANSYS commands - to be stacked and executed from a single file. The macro - blocks must be enclosed within block identifier and terminator - lines as shown in the example below. If you want to add - comment lines to a macro block, you may place them anywhere - within the macro block. (This includes placing them directly - on the lines where the macro block identifier and the macro - block terminator appear, as shown in the example.) Do not - place comment lines (or any other lines) outside of a macro - block. - - The name of the macro library file is identified for reading - on the ``*ULIB`` command. The name of the macro block is - identified on the ``*USE`` command. The commands within the macro - block are copied to a temporary file (of the macro block name) - during the ``*USE`` operation and executed as if a macro file of - that name had been created by the user. The temporary file is - deleted after it has been used. Macro block names should be - acceptable filenames (system dependent) and should not match - user created macro file names, since the user macro file will - be used first (if it exists) before the library file is - searched. Macro blocks may be stacked in any order. - Branching [``*GO`` or ``*IF``] external to the macro block is not - allowed. + /tee,new,myfile,mac + et,1,42,0,0,1 + ex,1,3e7 + /tee,end + /tee,append,myfile,mac + n,1,8 + n,5,11 + fill + ngen,5,5,1,5,1,0,1 + /tee,end - This command is valid in any processor. + the content of **myfile.mac** is: + + .. code:: apdl + + et,1,42,0,0,1 + ex,1,3e7 + n,1,8 + n,5,11 + fill + ngen,5,5,1,5,1,0,1 + + This command is valid in any processor, but only during an interactive run. """ - command = f"*ULIB,{fname},{ext}" + command = f"/TEE,{label},{fname},{ext}" return self.run(command, **kwargs) - def use( - self, - name="", - arg1="", - arg2="", - arg3="", - arg4="", - arg5="", - arg6="", - arg7="", - arg8="", - arg9="", - ar10="", - ar11="", - ar12="", - ar13="", - ar14="", - ag15="", - ar16="", - ar17="", - ar18="", - **kwargs, - ): - """Executes a macro file. + def rmdir(self, dir_: str = "", **kwargs): + r"""Removes (deletes) a directory. - APDL Command: ``*USE`` + Mechanical APDL Command: `/RMDIR `_ Parameters ---------- - name - Name (32 characters maximum, beginning with a letter) identifying - the macro file or a macro block on a macro library file. - - arg1, arg2, arg3, . . . , ar18 - Values passed into the file or block where the parameters ARG1 - through ARG9 and AR10 through AR18 are referenced. Values may be - numbers, alphanumeric character strings (up to 32 characters - enclosed in single quotes), parameters (numeric or character) or - parametric expressions. See below for additional details. + dir_ : str + The directory to remove. If no path is provided, it will be assumed to be in the current working + directory. All files in the directory are also removed. Notes ----- - Causes execution of a macro file called Name, or, if not found, a macro - block "Name" on the macro library file [``*ULIB``]. Argument values - (numeric or character) are passed into the file or block and - substituted for local parameters ARG1, ARG2, ..., AR18. The file Name - may also be executed as an "unknown command" (i.e., without the ``*USE`` - command name) as described below. - - A macro is a sequence of ANSYS commands (as many as needed) recorded in - a file or in a macro block in a library file (specified with the ``*ULIB`` - command). The file or block is typically executed with the ``*USE`` - command. In addition to command, numerical and alphanumeric data, the - macro may include parameters which will be assigned numerical or - alphanumerical character values when the macro is used. Use of the - macro may be repeated (within a do-loop, for example) with the - parameters incremented. A macro is defined within a run by "enclosing" - a sequence of data input commands between a ``*CREATE`` and a ``*END`` - command. The data input commands are passive (not executed) while - being written to the macro file. The macro file (without ``*CREATE`` and - ``*END`` ) can also be created external to ANSYS. - - Up to 99 specially named scalar parameters called ARG1 to AR99 are - locally available to each macro. Note that the prefix for the first 9 - parameters is "ARG," while the prefix for the last 90 is "AR." A local - parameter is one which is not affected by, nor does it affect, other - parameters, even those of the same name, which are used outside of the - macro. The only way a local parameter can affect, or be affected by, - parameters outside the macro is if values are passed out of, or into, - the macro by an argument list. Parameters ARG1 through AR18 can have - their values (numeric or character) passed via the argument list on the - ``*USE`` command (ARG1 through AR19 can be passed as arguments on the - "unknown command" macro). Parameters AR19 through AR99 (AR20 through - AR99 in the "unknown command" macro) are available solely for use - within the macro; they cannot be passed via an argument list. Local - parameters are available to do-loops and to /INPUT files processed - within the macro. In addition to an ARG1--AR99 set for each macro, - another ARG1--AR99 set is available external to all macros, local to - "non-macro" space. - - A macro is exited after its last line is executed. Macros may be - nested (such as a ``*USE`` or an "unknown command" within a macro). Each - nested macro has its own set of 99 local parameters. Only one set of - local parameters can be active at a time and that is the set - corresponding to the macro currently being executed or to the set - external to all macros (if any). When a nested macro completes - execution, the previous set of local parameters once again becomes - available. Use ``*STATUS,ARGX`` to view current macro parameter values. - - An alternate way of executing a macro file is via the "unknown command" - route. If a command unknown to the ANSYS program is entered, a search - for a file of that name (plus a .MAC suffix) is made. If the file - exists, it is executed, if not, the "unknown command" message is - output. Thus, users can write their own commands in terms of other - ANSYS commands. The procedure is similar to issuing the ``*USE`` command - with the unknown command in the Name field. For example, the command - CMD,10,20,30 is internally similar to ``*USE,CMD,10,20,30``. The macro - file named CMD.MAC will be executed with the three parameters. The - ``*USE`` macro description also applies to the "unknown command" macro, - except that various directories are searched and a suffix (.MAC) is - assumed. Also, a macro library file is not searched. - - A three-level directory search for the "unknown command" macro file may - be available (see the Operations Guide). The search order may be: 1) a - high-level system directory, 2) the login directory, and 3) the local - (working) directory. Use the /PSEARCH command to change the directory - search path. For an "unknown command" CMD, the first file named - CMD.MAC found to exist in the search order will be executed. The - command may be input as upper or lower case, however, it is converted - to upper case before the file name search occurs. On systems that - uniquely support both upper and lower case file names, the file with - the matching lower case name will be used if it exists, otherwise, the - file with the matching upper case name will be used. All macro files - placed in the apdl directory must be upper case. - - Note, since undocumented commands exist in the ANSYS program, the user - should issue the command intended for the macro file name to be sure - the "unknown command" message is output in the processor where it's to - be used. If the macro is to be used in other processors, the other - processors must also be checked. - - This command is valid in any processor. + Removes a directory on the computer on which Mechanical APDL is currently running. No warning or + prompt is + given, so use with extreme caution. """ - command = f"*USE,{name},{arg1},{arg2},{arg3},{arg4},{arg5},{arg6},{arg7},{arg8},{arg9},{ar10},{ar11},{ar12},{ar13},{ar14},{ag15},{ar16},{ar17},{ar18}" + command = f"/RMDIR,{dir_}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/matrix_op.py b/src/ansys/mapdl/core/_commands/apdl/matrix_op.py deleted file mode 100644 index 35ae6eaa2b..0000000000 --- a/src/ansys/mapdl/core/_commands/apdl/matrix_op.py +++ /dev/null @@ -1,999 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class MatrixOP: - def axpy(self, vr="", vi="", m1="", wr="", wi="", m2="", **kwargs): - """Performs the matrix operation ``M2= v*M1 + w*M2``. - - APDL Command: ``*AXPY`` - - Parameters - ---------- - vr, vi - The real and imaginary parts of the scalar v. Default value is 0. - - m1 - Name of matrix M1. If not specified, the operation ``M2 = w*M2`` will - be performed. - - wr, wi - The real and imaginary parts of the scalar w. Default value is 0. - - m2 - Name of matrix M2. Must be specified. - - Notes - ----- - The matrices M1 and M2 must have the same dimensions and same type - (dense or sparse). If M2 is real, vi and wi are ignored. - """ - command = f"*AXPY,{vr},{vi},{m1},{wr},{wi},{m2}" - return self.run(command, **kwargs) - - def comp(self, matrix="", algorithm="", threshold="", **kwargs): - """Compresses the columns of a matrix using a specified algorithm. - - APDL Command: ``*COMP`` - - Parameters - ---------- - matrix - Name of the matrix to compress. - - algorithm - Algorithm to use: - - Singular value decomposition algorithm (default). - Modified Gram-Schmidt algorithm. - - threshold - Numerical threshold value used to manage the compression. Default - value for SVD is 1E-7; default value for MGS is 1E-14. - - Notes - ----- - The algorithms available through this command are only applicable to - dense matrices that were created using the ``*DMAT`` command. - - Columns which are linearly dependent on others are removed, leaving the - independent or basis vectors. The matrix is resized according to the - new size determined by the algorithm. - """ - command = f"*COMP,{matrix},{algorithm},{threshold}" - return self.run(command, **kwargs) - - def dmat( - self, - matrix="", - type_="", - method="", - val1="", - val2="", - val3="", - val4="", - val5="", - **kwargs, - ): - """Creates a dense matrix. - - APDL Command: ``*DMAT`` - - Parameters - ---------- - matrix - Name used to identify the matrix. Must be specified. - - type\\_ - Matrix type: - - Double precision real values (default). - Complex double precision values. - - method - Method used to create the matrix: - - Allocate space for a matrix (default). - Resize an - existing matrix to new row and column dimensions. Values - are kept from the original matrix. If the dimensions - specified by Val1 (rows) and Val2 (columns) are greater - than the original matrix size, the additional entries are - assigned a value of zero. - - Copy an existing matrix. - Link to an existing matrix. The - memory will be shared between the original matrix and the - new matrix. This is useful for manipulating a submatrix of - a larger matrix. The Val1 through Val5 arguments will be - used to specify the lower and upper bounds of row and - column numbers from the original matrix. - - val1, val2, val3, val4, val5 - Additional input. The meaning of Val1 through Val5 will vary - depending on the specified Method. See details below. - - Notes - ----- - This command allows you to create a dense matrix. To create a sparse - matrix, use the ``*SMAT`` command. ``*SMAT`` is recommended for large matrices - obtained from the .FULL or .HBMAT file. Refer to the HBMAT command - documentation for more information about .FULL file contents. - - Use the ``*VEC`` command to create a vector. - - For very large matrices, use the OUTOFCORE option (Method = ALLOC or - COPY) to keep some of the matrix on disk if there is insufficient - memory. - - When importing a dense matrix from a DMIG file, you can define the - formatting of the file using the Val3 and Val4 fields. - - """ - command = f"*DMAT,{matrix},{type_},{method},{val1},{val2},{val3},{val4},{val5}" - return self.run(command, **kwargs) - - def dot(self, vector1="", vector2="", par_real="", par_imag="", **kwargs): - """Computes the dot (or inner) product of two vectors. - - APDL Command: ``*DOT`` - - Parameters - ---------- - vector1 - Name of first vector; must have been previously specified by a ``*VEC`` - command. - - vector2 - Name of second vector; must have been previously specified by a - ``*VEC`` command. - - par_real - Parameter name that contains the result. - - par_imag - Parameter name that contains the imaginary part of the result (used - only for complex vectors). - - Notes - ----- - If Vector1 and Vector2 are complex, the complex conjugate of Vector1 is - used to compute the result (Par_Real, Par_Imag). - """ - command = f"*DOT,{vector1},{vector2},{par_real},{par_imag}" - return self.run(command, **kwargs) - - def eigen(self, kmatrix="", mmatrix="", cmatrix="", evals="", evects="", **kwargs): - """Performs a modal solution with unsymmetric or damping matrices. - - APDL Command: ``*EIGEN`` - - Parameters - ---------- - kmatrix - Name of the stiffness matrix. May be a real or complex-valued - matrix. - - mmatrix - Name of the mass matrix. - - cmatrix - Name of the damping matrix (used only for MODOPT,DAMP). - - evals - Name of the output eigenvalues vector. It will be an m-long ``*VEC`` - vector of complex values, where m is the number of eigenvalues - requested (MODOPT). - - evects - Name of the output eigenvector matrix. It will be a n x m ``*DMAT`` - (dense) matrix of complex values, where n is the size of the matrix - and m is the number of eigenvalues requested (MODOPT). - - Notes - ----- - Use the command ANTYPE,MODAL and the MODOPT command to specify the - modal solution options. Only MODOPT,DAMP, MODOPT,UNSYM, MODOPT,LANB, - and MODOPT,SUBSP are supported. - - ``*EIGEN`` with Block Lanczos (LANB) only supports sparse matrices. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"*EIGEN,{kmatrix},{mmatrix},{cmatrix},{evals},{evects}" - return self.run(command, **kwargs) - - def export( - self, - matrix="", - format_="", - fname="", - val1="", - val2="", - val3="", - **kwargs, - ): - """Exports a matrix to a file in the specified format. - - APDL Command: ``*EXPORT`` - - Parameters - ---------- - matrix - Name of the matrix to export (must be a matrix previously created - with ``*DMAT`` or ``*SMAT``, or a vector previously created with ``*VEC``). - - format\\_ - Format of the output file: - - Export the matrix in the Matrix Market Format. - Export - the matrix in the SUB file format. - - Export the matrix in the Harwell-Boeing file format. - - Export the matrix in a native format, to be re-imported - using the ``*DMAT`` or ``*SMAT`` command. - - Export the matrix to an existing EMAT file. - Export the - matrix to an APDL array parameter. - - Export the matrix profile to a Postscript file. - Export - the matrix in the DMIG file format. - - fname - Name of the file, or name of the array parameter if Format = APDL. - - val1, val2, val3 - Additional input. The meaning of Val1 through Val3 will vary - depending on the specified Format. See table below for details. - - Notes - ----- - Only sparse matrices can be exported to Postscript files. This option - plots the matrix profile as a series of dots. - - If you want to create a .SUB file from several matrices, you need to - set Val3 = WAIT for all matrices but the last, and Val3 = DONE for the - last one. The export will be effective at the last ``*EXPORT`` command. - - To create a .SUB file or .DMIG file from scratch, you must supply the - row information array. (Specify this array in the Val2 field for .SUB - or in the Val1 field for .DMIG.) This must be an m x 2 array, where m - is the size of the matrix. The first column is the node number and the - second column is the DOF number corresponding to each row of the - matrix. - - The ``*EXPORT`` command is not applicable to sparse matrices initialized - from .FULL files by means of the NOD2BCS option on the ``*SMAT`` command - (i.e., ``*SMAT,,,IMPORT,FULL,,NOD2BCS``). - """ - command = f"*EXPORT,{matrix},{format_},{fname},{val1},{val2},{val3}" - return self.run(command, **kwargs) - - def fft( - self, - type_="", - inputdata="", - outputdata="", - dim1="", - dim2="", - resultformat="", - **kwargs, - ): - """Computes the fast Fourier transformation of a specified matrix or - - APDL Command: ``*FFT`` - vector. - - Parameters - ---------- - type\\_ - Type of FFT transformation: - - Forward FFT computation (default). - Backward FFT computation. - - inputdata - Name of matrix or vector for which the FFT will be computed. This - can be a dense matrix (created by the ``*DMAT`` command) or a vector - (created by the ``*VEC`` command). Data can be real or complex values. - There is no default value for this argument. - - outputdata - Name of matrix or vector where the FFT results will be stored. The - type of this argument must be consistent with InputData (see table - below). There is no default value for this argument. - - dim1 - The number of terms to consider for a vector, or the number of rows - for a matrix. Defaults to the whole input vector or all the rows of - the matrix. - - dim2 - The number of columns to consider for a matrix. Defaults to all the - columns of the matrix. (Valid only for matrices.) - - resultformat - Specifies the result format: - - Returns the full result. That is, the result matches the - dimension specified on this command (DIM1, DIM2). - - Returns partial results. For real input data, there is a - symmetry in the results of the Fourier transform as some - coefficients are conjugated. The partial format uses this - symmetry to optimize the storage of the results. (Valid - only for real data.) - - Notes - ----- - In the example that follows, the fast Fourier transformation is used to - filter frequencies from a noisy input signal. - """ - command = f"*FFT,{type_},{inputdata},{outputdata},{dim1},{dim2},{resultformat}" - return self.run(command, **kwargs) - - def free(self, name="", **kwargs): - """Deletes a matrix or a solver object and frees its memory allocation. - - APDL Command: ``*FREE`` - - Parameters - ---------- - name - Name of the matrix or solver object to delete. Use Name = ALL to - delete all APDL Math matrices and solver objects. Use Name = WRK - to delete all APDL Math matrices and solver objects that belong to - a given workspace. - - val1 - If Name = WRK, Val1 is to set the memory workspace number. - - Notes - ----- - A /CLEAR command will automatically delete all the current APDL Math - objects. - """ - command = f"*FREE,{name}" - return self.run(command, **kwargs) - - def init(self, name="", method="", val1="", val2="", val3="", **kwargs): - """Initializes a vector or dense matrix. - - APDL Command: ``*INIT`` - - Parameters - ---------- - name - Vector or matrix which will be initialized. This can be a vector - (created by the ``*VEC`` command) or a dense matrix (created by the - ``*DMAT`` command). - - method - Initialization method to use: - - Fill the vector/matrix with zeros (default). - Fill the vector/matrix with a constant value. - - Fill the vector/matrix with random values. - Fill the nth diagonal of the matrix with a constant value. Other values are not - overwritten. - - val1, val2, val3 - Additional input. The meaning of Val1 through Val3 will vary - depending on the specified Method. See details below. - - Notes - ----- - This command initializes a previously defined vector (``*VEC``) or dense - matrix (``*DMAT``). - """ - command = f"*INIT,{name},{method},{val1},{val2},{val3}" - return self.run(command, **kwargs) - - def itengine( - self, - type_="", - enginename="", - precondname="", - matrix="", - rhsvector="", - solvector="", - maxiter="", - toler="", - **kwargs, - ): - """Performs a solution using an iterative solver. - - APDL Command: ``*ITENGINE`` - - Parameters - ---------- - type\\_ - Specifies the algorithm to be used: - - enginename - Name used to identify this iterative solver engine. Must be - specified. - - precondname - Linear solver engine name (``*LSENGINE``) identifying the factored - matrix to be used as the preconditioner. - - matrix - Name of the matrix to solve. - - rhsvector - Matrix (load vector) name. - - solvector - Solution vector name. If non-zero, it will be taken as the initial - vector for the iterative process. - - maxiter - Maximum number of iterations allowed. Default is 2 times the number - of rows in the matrix. - - toler - Convergence tolerance. Default is 1.0E-8. - - Notes - ----- - This command solves Ax = b using a preconditioned conjugate gradient - algorithm. It uses an existing factored system as the preconditioner. - This solution method is useful if an existing matrix has been solved - and minor changes have been made to the matrix. - """ - command = f"*ITENGINE,{type_},{enginename},{precondname},{matrix},{rhsvector},{solvector},{maxiter},{toler}" - return self.run(command, **kwargs) - - def lsbac(self, enginename="", rhsvector="", solvector="", **kwargs): - """Performs the solve (forward/backward substitution) of a - factorized linear system. - - APDL Command: ``*LSBAC`` - - Parameters - ---------- - enginename - Name used to identify this engine. Must have been previously - created using ``*LSENGINE`` and factorized using ``*LSFACTOR``. - - rhsvector - Name of vector containing the right-hand side (load) vectors as - input. Must have been previously defined as a ``*VEC`` vector or a - ``*DMAT`` matrix. - - solvector - Name of vector that will contain the solution vectors upon - completion. Must be predefined as a ``*VEC`` vector or ``*DMAT`` matrix. - - Notes - ----- - This command performs forward and back substitution to obtain the - solution to the linear matrix equation Ax = b. The matrix engine must - have been previously defined using ``*LSENGINE``, and the matrix factored - using ``*LSFACTOR``. - - You can use the ``*DMAT,,,COPY`` (or ``*VEC,,,COPY``) command to copy the load - vector to the solution vector in order to predefine it with the - appropriate size. - """ - command = f"*LSBAC,{enginename},{rhsvector},{solvector}" - return self.run(command, **kwargs) - - def lsdump(self, enginename="", filename="", **kwargs): - """Dumps a linear solver engine to a binary File. - - APDL Command: ``*LSDUMP`` - - Parameters - ---------- - enginename - Name used to identify this engine. Must have been previously - created using ``*LSENGINE`` and factorized using ``*LSFACTOR``. - - filename - Name of the file to create. - - Notes - ----- - Dumps a previously factorized linear solver system to a binary file. - Only LAPACK and BCS linear solvers can be used with this feature. The - Linear Solver can later be restored with the ``*LSRESTORE`` command. - - A BCS Sparse Solver can be dumped only if uses the INCORE memory option - (see BCSOPTION). - """ - command = f"*LSDUMP,{enginename},{filename}" - return self.run(command, **kwargs) - - def lsengine(self, type_="", enginename="", matrix="", option="", **kwargs): - """Creates a linear solver engine. - - APDL Command: ``*LSENGINE`` - - Parameters - ---------- - type_ - Specifies the algorithm to be used: - - * ``"BCS"`` - Boeing sparse solver (default if applied to - sparse matrices). - - * ``"DSS"`` : MKL sparse linear solver (Intel Windows and - Linux systems only). - - * ``"LAPACK"`` : LAPACK dense matrix linear solver (default if - applied to dense matrices). - - * ``"DSP"`` : Distributed sparse solver. - - enginename - Name used to identify this engine. Must be specified. - - matrix - Name of the matrix to solve. - - option - Option to control the memory mode of the DSS solver (used only - if ``type='dss'``): - - * ``"INCORE"`` : In-core memory mode - - * ``"OUTOFCORE"`` : Out-of-core memory mode - - Notes - ----- - This command creates a linear solver engine. - - The BCS, DSS, and DSP solvers can only be used with sparse matrices. - For dense matrices, use the LAPACK solver. - """ - command = f"*LSENGINE,{type_},{enginename},{matrix},{option}" - return self.run(command, **kwargs) - - def lsfactor(self, enginename="", option="", **kwargs): - """Performs the numerical factorization of a linear solver system. - - APDL Command: ``*LSFACTOR`` - - Parameters - ---------- - enginename - Name used to identify this engine. Must have been previously - created using ``*LSENGINE``. - - option - Option to invert the matrix, used only with an LAPACK engine - (``*LSENGINE,LAPACK``): - - Notes - ----- - Performs the computationally intensive, memory intensive factorization - of a matrix specified by ``*LSENGINE``, using the solver engine also - specified by ``*LSENGINE``. - """ - command = f"*LSFACTOR,{enginename},{option}" - return self.run(command, **kwargs) - - def lsrestore(self, enginename="", filename="", **kwargs): - """Restores a linear solver engine from a binary file. - - APDL Command: ``*LSRESTORE`` - - Parameters - ---------- - enginename - Name used to identify this engine. - - filename - Name of the file to read from. - - Notes - ----- - Restores a previously dumped Linear Solver (see the ``*LSDUMP`` command). - This Linear Solver can be used to solve a linear system using the - ``*LSBAC`` command. - """ - command = "*LSRESTORE,%s,%s" % (str(enginename), str(filename)) - return self.run(command, **kwargs) - - def merge(self, name1="", name2="", val1="", val2="", **kwargs): - """Merges two dense matrices or vectors into one. - - APDL Command: ``*MERGE`` - - Parameters - ---------- - name1 - Name of the matrix or vector to extend. - - name2 - Name of the matrix or vector to be merged into ``name1``. - - val1 - If ``name1`` refers to a dense matrix created by the ``*DMAT`` - command then the column or row number indicating where the new values - are to be inserted into the Name1 matrix. - - If ``name` refers to a vector created by ``*VEC`` then this is the - row number indicating where the new values are to be inserted - into the ``name1`` vector. - - val2 - Specifies how the ``name2`` matrix or vector is copied into - the ``name1`` matrix. - - * ``"COL"`` : Insert the new values at the column location - specified by ``val1`` (default). - * ``"row"`` : Insert the new values at the row location - specified by ``val1``. - - Notes - ----- - ``merge`` can be used to add new columns or rows to a dense matrix - that was created by the ``*DMAT`` command. In this case, ``name1`` must - be the name of the dense matrix and ``name2`` must refer to a vector - or another dense matrix. - - ``*MERGE`` can also be used to add new rows to a vector that was - created by the ``*VEC`` command. In this case, ``name1`` and - ``name2`` must both refer to vectors. - - In all cases, the values of the original matrix or vector are - retained, and the matrix or vector is resized to accommodate the - additional rows or columns. - """ - return self.run(f"MERGE,{name1},{name2},{val1},{val2}", **kwargs) - - def mult(self, m1="", t1="", m2="", t2="", m3="", **kwargs): - """Performs the matrix multiplication ``M3 = M1(T1)*M2(T2)``. - - APDL Command: ``*MULT`` - - Parameters - ---------- - m1 - Name of matrix M1. Must have been previously specified by a ``*DMAT`` - or ``*SMAT`` command. - - t1 - Transpose key. Set T1 = TRANS to use the transpose of M1. If blank, - transpose will not be used. - - m2 - Name of matrix M2. Must have been previously specified by a ``*DMAT`` - command. - - t2 - Transpose key. Set T2 = TRANS to use the transpose of M2. If blank, - transpose will not be used. - - m3 - Name of resulting matrix, M3. Must be specified. - - Notes - ----- - The matrices must be dimensionally consistent such that the number of - columns of M1 (or the transposed matrix, if requested) is equal to the - number of rows of M2 (or the transposed matrix, if requested). - - You cannot multiply two sparse matrices with this command (that is, M1 - and M2 cannot both be sparse). The resulting matrix, M3, will always be - a dense matrix, no matter what combination of input matrices is used - (dense*sparse, sparse*dense, or dense*dense). - """ - command = f"*MULT,{m1},{t1},{m2},{t2},{m3}" - return self.run(command, **kwargs) - - def nrm(self, name="", normtype="", parr="", normalize="", **kwargs): - """Computes the norm of the specified matrix or vector. - - APDL Command: ``*NRM`` - - Parameters - ---------- - name - Matrix or vector for which the norm will be computed. This - can be a dense matrix (created by the ``*DMAT`` command), - a sparse matrix (created by the ``*SMAT`` command) or a - vector (created by the ``*VEC`` command) - - normtype - Mathematical norm to use: - - - L2 (Euclidean or SRSS) norm (default). - - L1 (absolute sum) norm (vectors only). - - parr - Parameter name that contains the result. - - normalize - Normalization key; to be used only for vectors created by ``*VEC``: - - Normalize the vector such that the norm is 1.0. - Do not - normalize the vector (default). - - Notes - ----- - The NRM2 option corresponds to the Euclidean or L2 norm and is - applicable to either vectors or matrices. The NRM1 option corresponds - to the L1 norm and is applicable to vectors only. The NRMINF option is - the maximum norm and is applicable to either vectors or matrices. - """ - command = f"*NRM,{name},{normtype},{parr},{normalize}" - return self.run(command, **kwargs) - - def remove(self, name="", val1="", val2="", val3="", **kwargs): - """Suppresses rows or columns of a dense matrix or a vector. - - APDL Command: ``*REMOVE`` - - Parameters - ---------- - name - Name of the matrix or vector to be revised. - - val1 - First row or column number to suppress if ``name`` is a dense - matrix. First value index to suppress if ``name`` is a - vector. - - Val2 - Last row or column number to suppress if ``name`` is a dense - matrix. Last value index to suppress if ``name`` is a - vector. - - Val3 - Specifies what to remove if ``name`` is a dense matrix. - - * ``"COL"`` : Remove columns of the matrix (default). - - * ``"ROW"`` : Remove rows of the matrix. - - Notes - ----- - The values of the original matrix or vector specified by Name are - retained. The matrix or vector is resized to the new number of - rows and columns. - """ - return self.run(f"REMOVE,{name},{val1},{val2},{val3}", **kwargs) - - def scal(self, name="", val1="", val2="", **kwargs): - """Scales a vector or matrix by a constant or a vector. - - APDL Command: ``*SCAL`` - - Parameters - ---------- - name - Name used to identify the vector or matrix to be scaled. Must - be specified. - - val1 - When scaling a matrix or a vector by a scalar value, Val1 is - the real part of the constant to use (default = 1). - - When scaling a matrix or a vector by a vector, Val1 is the - name of the vector used for the scaling operation. - - val2 - The imaginary part of the constant to use (default = 0). - This value is used only if the vector or matrix specified by - Name is complex. - - val2 is only valid for scaling by a constant. It is not - used when scaling by a vector. - - Notes - ----- - This command can be applied to vectors and matrices created by the - ``*VEC``, ``*DMAT`` and ``*SMAT`` commands. - - Data types must be consistent between the vectors and matrices - being scaled and the scaling vector (or constant value). - - When scaling a matrix with a vector, the matrix must be square - and the scaling vector must be the same size. - - Scaling a matrix with a vector, is available only on - MAPDL V23.2 and greater. - - """ - return self.run(f"*SCAL,{name},{val1},{val2}", **kwargs) - - def smat( - self, - matrix="", - type_="", - method="", - val1="", - val2="", - val3="", - val4="", - **kwargs, - ): - """Creates a sparse matrix. - - APDL Command: ``*SMAT`` - - Parameters - ---------- - matrix - Name used to identify the matrix. Must be specified. - - type\\_ - Matrix type: - - Double precision real values (default). - Complex double precision values. - - method - Method used to create the matrix: - - Copy an existing matrix. - Import the matrix from a file. - - val1, val2, val3, val4 - Additional input. The meaning of Val1 through Val3 will - vary depending on the specified Method. See in your ansys - documentation. - - Notes - ----- - Use the ``*DMAT`` command to create a dense matrix. - - Unlike the ``*DMAT`` command, the ``*SMAT`` command cannot be used to allocate - a sparse matrix. - - For more information on the NOD2BCS and USR2BCS mapping vectors, see - Degree of Freedom Ordering in the ANSYS Parametric Design Language - Guide. - - For more information about .FULL file contents, see the HBMAT in the - Command Reference. - """ - command = f"*SMAT,{matrix},{type_},{method},{val1},{val2},{val3},{val4}" - return self.run(command, **kwargs) - - def starprint(self, matrix="", fname="", **kwargs): - """Prints the matrix values to a file. - - APDL Command: ``*PRINT`` - - Parameters - ---------- - matrix - Name of matrix or vector to print. Must be specified. - - fname - File name. If blank, matrix is written to the output file. - - Notes - ----- - The matrix may be a dense matrix (``*DMAT``), a sparse matrix - (``*SMAT``), or a vector (``*VEC``). Only the non-zero entries - of the matrix are printed. - """ - command = f"*PRINT,{matrix},{fname}" - return self.run(command, **kwargs) - - def sort(self, **kwargs): - """Specifies "Sort settings" as the subsequent status topic. - - APDL Command: SORT - - Notes - ----- - This is a status [STAT] topic command. Status topic commands are - generated by the GUI and will appear in the log file (Jobname.LOG) if - status is requested for some items under Utility Menu> List> Status. - This command will be immediately followed by a STAT command, which will - report the status for the specified topic. - - If entered directly into the program, the STAT command should - immediately follow this command. - """ - command = f"SORT," - return self.run(command, **kwargs) - - def vec( - self, - vector="", - type_="", - method="", - val1="", - val2="", - val3="", - val4="", - **kwargs, - ): - """Creates a vector. - - APDL Command: ``*VEC`` - - Parameters - ---------- - vector - Name used to identify the vector. Must be specified. - - type_ - Vector type: - - * ``"D"`` : Double precision real values (default). - - * ``"Z"`` : Complex double precision values. - - * ``"I"`` : Integer values. - - method - Method used to create the vector: - - * ``"ALLOC"`` : Allocate space for a vector (default). - - * ``"RESIZE"`` : Resize an existing vector to a new - length. Values are kept from the original vector. If the - length specified by Val1 is greater than the original vector - length, the additional rows are assigned a value of zero. - - * ``"COPY"`` : Copy an existing vector. - - * ``"IMPORT"`` : Import the vector from a file. - - * ``"LINK"`` : Link to a column of an existing dense ``*DMAT`` - matrix and use it in subsequent vector calculations. Any - changes to the vector are also made to the corresponding - matrix column (memory is shared). - - Copy an existing vector. - Import the vector from a file. - - val1, val2, val3, val4, val5 - Additional input. The meaning of ``val1`` through ``val5`` will vary - depending on the specified Method. See: - https://www.mm.bme.hu/~gyebro/files/ans_help_v182/ans_cmd/Hlp_C_VEC.html - - Notes - ----- - Use the ``*DMAT`` command to create a matrix. - - For more information on the BACK and FORWARD nodal mapping vectors, see - Degree of Freedom Ordering in the ANSYS Parametric Design Language - Guide. - """ - command = f"*VEC,{vector},{type_},{method},{val1},{val2},{val3},{val4}" - return self.run(command, **kwargs) - - def wrk(self, num="", **kwargs): - """Sets the active workspace number. - - APDL Command: ``*WRK`` - - Parameters - ---------- - num - Number of the active memory workspace for APDLMath vector and - matrices. All the following APDLMath vectors and matrices will - belong to this memory workspace, until the next call to the ``*WRK`` - command. By default, all the APDLMath objects belong to workspace - number 1. - - Notes - ----- - This feature enables you to associate a set of vector and matrices in a - given memory workspace, so that you can easily manage the free step: - - This feature can be useful to free all the temporary APDLMath variables - inside a MACRO in one call. - """ - command = "*WRK,%s" % (str(num)) - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/matrix_operations.py b/src/ansys/mapdl/core/_commands/apdl/matrix_operations.py new file mode 100644 index 0000000000..2d2e41d381 --- /dev/null +++ b/src/ansys/mapdl/core/_commands/apdl/matrix_operations.py @@ -0,0 +1,1365 @@ +# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + + +class MatrixOperations: + + def starprint(self, matrix: str = "", fname: str = "", **kwargs): + r"""Prints the matrix values to a file. + + Mechanical APDL Command: `\*PRINT `_ + + Parameters + ---------- + matrix : str + Name of matrix or vector to print. Must be specified. + + fname : str + File name (case-sensitive, 32-character maximum). If blank, matrix is written to the output + file. + + Notes + ----- + The matrix may be a dense matrix ( :ref:`dmat` ), a sparse matrix ( :ref:`smat` ), or a vector ( + :ref:`vec` ). Only the non-zero entries of the matrix are printed. + """ + command = f"*PRINT,{matrix},{fname}" + return self.run(command, **kwargs) + + def free(self, name: str = "", val1: str = "", **kwargs): + r"""Deletes a matrix or a solver object and frees its memory allocation. + + Mechanical APDL Command: `\*FREE `_ + + Parameters + ---------- + name : str + Name of the matrix or solver object to delete. Use ``Name`` = ALL to delete all APDL Math + matrices and solver objects. Use ``Name`` = WRK to delete all APDL Math matrices and solver + objects that belong to a given workspace. + + val1 : str + If ``Name`` = WRK, ``Val1`` is the memory workspace number. + + Notes + ----- + A :ref:`clear` command will automatically delete all the current APDL Math objects. + """ + command = f"*FREE,{name},{val1}" + return self.run(command, **kwargs) + + def fft( + self, + type_: str = "", + inputdata: str = "", + outputdata: str = "", + dim1: str = "", + dim2: str = "", + resultformat: str = "", + **kwargs, + ): + r"""Computes the fast Fourier transformation of a specified matrix or vector. + + Mechanical APDL Command: `\*FFT `_ + + Parameters + ---------- + type_ : str + Type of FFT transformation: + + * ``FORW`` - Forward FFT computation (default). + + * ``BACK`` - Backward FFT computation. + + inputdata : str + Name of matrix or vector for which the FFT will be computed. This can be a dense matrix (created + by the :ref:`dmat` command) or a vector (created by the :ref:`vec` command). Data can be real or + complex values. There is no default value for this argument. + + outputdata : str + Name of matrix or vector where the FFT results will be stored. The type of this argument must be + consistent with ``InputData`` (see table below). There is no default value for this argument. + + InformalTables need to be added. + + dim1 : str + The number of terms to consider for a vector, or the number of rows for a matrix. Defaults to + the whole input vector or all the rows of the matrix. + + dim2 : str + The number of columns to consider for a matrix. Defaults to all the columns of the matrix. + (Valid only for matrices.) + + resultformat : str + Specifies the result format: + + * ``FULL`` - Returns the full result. That is, the result matches the dimension specified on this + command ( ``DIM1``, ``DIM2`` ). + + * ``PART`` - Returns partial results. For real input data, there is a symmetry in the results of + the Fourier transform as some coefficients are conjugated. The partial format uses this symmetry + to optimize the storage of the results. (Valid only for real data.) + + Notes + ----- + In the example that follows, the fast Fourier transformation is used to filter frequencies from a + noisy input signal. + """ + command = f"*FFT,{type_},{inputdata},{outputdata},{dim1},{dim2},{resultformat}" + return self.run(command, **kwargs) + + def wrk(self, num: str = "", **kwargs): + r"""Sets the active workspace number. + + Mechanical APDL Command: `\*WRK `_ + + Parameters + ---------- + num : str + Number of the active memory workspace for APDLMath vector and matrices. All the following + APDLMath vectors and matrices will belong to this memory workspace, until the next call to the + :ref:`wrk` command. By default, all the APDLMath objects belong to workspace number 1. + + Notes + ----- + This feature enables you to associate a set of vector and matrices in a given memory workspace, so + that you can easily manage the free step: + + .. code:: apdl + + *VEC,V,D,ALLOC,5 ! V belongs to the default Workspace 1 + + *WRK,2 ! Set the active workspace as the number 2 + + *VEC,W,D,IMPORT,FULL,file.full,RHS ! W belongs to the Workspace 2 + *SMAT,K,D,IMPORT,FULL,file.full,STIFF ! K belongs to the Workspace 2 + *DMAT,M,ALLOC,10,10 ! M belongs to the Workspace 2 + ... + *FREE,WRK,2 ! W, K and M are deleted, but not V + + *PRINT,V + + This feature can be useful to free all the temporary APDLMath variables inside a MACRO in one call. + """ + command = f"*WRK,{num}" + return self.run(command, **kwargs) + + def comp( + self, + matrix: str = "", + algorithm: str = "", + threshold: str = "", + val1: str = "", + val2: str = "", + **kwargs, + ): + r"""Compresses a matrix using a specified algorithm. + + Mechanical APDL Command: `\*COMP `_ + + Parameters + ---------- + matrix : str + Name of the matrix to compress. + + algorithm : str + Algorithm or method to use: + + * ``SVD`` - Singular value decomposition algorithm (default). + + * ``MGS`` - Modified Gram-Schmidt algorithm. + + * ``SPARSE`` - Compress a sparse matrix based on the threshold value. + + threshold : str + Numerical threshold value used to manage the compression. The default value depends on the + method of compression: 1E-7 for SVD; 1E-14 for MGS; 1E-16 for SPARSE. + + val1 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. + + val2 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. + + Notes + ----- + The SVD and MGS algorithms are only applicable to dense matrices that were created using the + :ref:`dmat` command. Columns that are linearly dependent on others are removed, leaving the + independent or basis vectors. The matrix is resized according to the new size determined by the + algorithm. + + For the SVD algorithm, the singular value decomposition of an input matrix :math:`` is a + factorization of the form: + + M = U Σ V * + Here, the :math:`` matrix is replaced by the :math:`` matrix, according to the specified + threshold. + + The SPARSE compression method is only applicable to sparse matrices that were created using the + :ref:`smat` command. All terms that have an absolute value below the specified threshold, relative + to the maximum value in the matrix, are removed from the original matrix. For example, given a + sparse matrix having 100 as the largest term and ``THRESHOLD`` = 0.5, all terms having an absolute + value below 0.5\2100 = 50 are removed. + """ + command = f"*COMP,{matrix},{algorithm},{threshold},{val1},{val2}" + return self.run(command, **kwargs) + + def nrm( + self, + name: str = "", + normtype: str = "", + parr: str = "", + normalize: str = "", + **kwargs, + ): + r"""Computes the norm of the specified matrix or vector. + + Mechanical APDL Command: `\*NRM `_ + + Parameters + ---------- + name : str + Matrix or vector for which the norm will be computed. This can be a dense matrix (created by the + :ref:`dmat` command), a sparse matrix (created by the :ref:`smat` command) or a vector (created + by the :ref:`vec` command) + + normtype : str + Mathematical norm to use: + + * ``NRM2`` - L2 (Euclidian or SRSS) norm (default). + + * ``NRM1`` - L1 (absolute sum) norm (vectors and dense matrices only). + + * ``NRMINF`` - Maximum norm. + + parr : str + Parameter name that contains the result. + + normalize : str + Normalization key; to be used only for vectors created by :ref:`vec` : + + * ``YES`` - Normalize the vector such that the norm is 1.0. + + * ``NO`` - Do not normalize the vector (default). + + Notes + ----- + The NRM2 option corresponds to the Euclidian or L2 norm and is applicable to either vectors or + matrices: + + :math:``, :math:`` + + :math:``, :math:`` where :math:`` is the complex conjugate of :math:`` + + :math:``, :math:`` = largest eigenvalue of :math:`` + + The NRM1 option corresponds to the L1 norm and is applicable to vectors and dense matrices: + + :math:`` or :math:``, :math:`` + + :math:`` or :math:``, :math:`` + + The NRMINF option is the maximum norm and is applicable to either vectors or matrices: + + :math:`` or :math:``, :math:`` + + :math:`` or :math:``, :math:`` + """ + command = f"*NRM,{name},{normtype},{parr},{normalize}" + return self.run(command, **kwargs) + + def merge( + self, name1: str = "", name2: str = "", val1: str = "", val2: str = "", **kwargs + ): + r"""Merges two dense matrices or vectors into one. + + Mechanical APDL Command: `\*MERGE `_ + + Parameters + ---------- + name1 : str + Name of the matrix or vector to extend. + + name2 : str + Name of the matrix or vector to be merged into ``Name1``. + + val1 : str + Additional input. The meaning of ``Val1`` and ``Val2`` varies depending on the entity type + (matrix or vector). See details below. + + val2 : str + Additional input. The meaning of ``Val1`` and ``Val2`` varies depending on the entity type + (matrix or vector). See details below. + + Notes + ----- + :ref:`merge` can be used to add new columns or rows to a dense matrix that was created by the + :ref:`dmat` command. In this case, ``Name1`` must be the name of the dense matrix and ``Name2`` must + refer to a vector or another dense matrix. + + The following two examples demonstrate merging columns into a dense matrix. + + .. figure::../../images/gMERGE1.png + + The following example demonstrates merging rows into a dense matrix. + + .. figure::../../images/gMERGE3.png + + :ref:`merge` can also be used to add new rows to a vector that was created by the :ref:`vec` + command. In this case, ``Name1`` and ``Name2`` must both refer to vectors, as demonstrated in the + example below. + + .. figure::../../images/gMERGE2.png + + In all cases, the values of the original matrix or vector are retained, and the matrix or vector is + resized to accommodate the additional rows or columns. + """ + command = f"*MERGE,{name1},{name2},{val1},{val2}" + return self.run(command, **kwargs) + + def mult( + self, + m1: str = "", + t1: str = "", + m2: str = "", + t2: str = "", + m3: str = "", + **kwargs, + ): + r"""Performs the matrix multiplication M3 = M1 :sup:`(T1)` *M2 :sup:`(T2)` . + + Mechanical APDL Command: `\*MULT `_ + + Parameters + ---------- + m1 : str + Name of matrix ``M1``. Must have been previously specified by a :ref:`dmat` or :ref:`smat` + command. + + t1 : str + Transpose key. Set ``T1`` = TRANS to use the non-conjugate transpose of ``M1``. Set ``T1`` = + CTRANS to use the conjugate transpose of ``M1``. CTRANS is only applicable when the ``M1`` + matrix is complex. If blank, transpose will not be used. + + m2 : str + Name of matrix ``M2``. Must have been previously specified by a :ref:`dmat` command. + + t2 : str + Transpose key. Set ``T2`` = TRANS to use the non-conjugate transpose of ``M2``. Set ``T2`` = + CTRANS to use the conjugate transpose of ``M2``. CTRANS is only applicable when the ``M2`` + matrix is complex. If blank, transpose will not be used. + + m3 : str + Name of resulting matrix, ``M3``. Must be specified. + + Notes + ----- + The matrices must be dimensionally consistent such that the number of columns of ``M1`` (or the + transposed matrix, if requested) is equal to the number of rows of ``M2`` (or the transposed matrix, + if requested). + + You cannot multiply two sparse matrices with this command (that is, ``M1`` and ``M2`` cannot both be + sparse). The resulting matrix, ``M3``, will always be a dense matrix, no matter what combination of + input matrices is used (dense\2sparse, sparse\2dense, or dense\2dense). + """ + command = f"*MULT,{m1},{t1},{m2},{t2},{m3}" + return self.run(command, **kwargs) + + def starinquire(self, obj: str = "", property_: str = "", var1: str = "", **kwargs): + r"""Retrieves properties of an existing APDL Math object. + + Mechanical APDL Command: `\*INQUIRE `_ + + Parameters + ---------- + obj : str + Name of the vector or matrix of interest. + + property_ : str + Object property to get: + + * ``DIM1`` - First dimension of a matrix, or size of a vector. + + * ``DIM2`` - Second dimension of a matrix. + + var1 : str + Name of the resulting parameter that contains the property value. + + Notes + ----- + The following example demonstrates using :ref:`starinquire` to get the number of rows and columns of + an existing matrix. + + .. code:: apdl + + *SMAT,K,D,IMPORT,FULL,file.full,STIFF ! Import the stiffness matrix from an existing FULL file + *INQUIRE,K,DIM1,NROW ! Get the first dimension of the stiffness matrix + *INQUIRE,K,DIM2,NCOL ! Get the second dimension of the stiffness matrix + /COM, K matrix size: %NROW% x %NCOL% + """ + command = f"*INQUIRE,{obj},{property_},{var1}" + return self.run(command, **kwargs) + + def itengine( + self, + type_: str = "", + enginename: str = "", + precondname: str = "", + matrix: str = "", + rhsvector: str = "", + solvector: str = "", + maxiter: str = "", + toler: str = "", + **kwargs, + ): + r"""Performs a solution using an iterative solver. + + Mechanical APDL Command: `\*ITENGINE `_ + + Parameters + ---------- + type_ : str + Specifies the algorithm to be used: + + * ``PCG`` - Preconditioned conjugate gradient (default). + + enginename : str + Name used to identify this iterative solver engine. Must be specified. + + precondname : str + Linear solver engine name ( :ref:`lsengine` ) identifying the factored matrix to be used as the + preconditioner. + + matrix : str + Name of the matrix to solve. + + rhsvector : str + Matrix (load vector) name. + + solvector : str + Solution vector name. If non-zero, it will be taken as the initial vector for the iterative + process. + + maxiter : str + Maximum number of iterations allowed. Default is 2 times the number of rows in the matrix. + + toler : str + Convergence tolerance. Default is 1.0E-8. + + Notes + ----- + This command solves Ax = b using a preconditioned conjugate gradient algorithm. It uses an existing + factored system as the preconditioner. This solution method is useful if an existing matrix has been + solved and minor changes have been made to the matrix. + """ + command = f"*ITENGINE,{type_},{enginename},{precondname},{matrix},{rhsvector},{solvector},{maxiter},{toler}" + return self.run(command, **kwargs) + + def init( + self, + name: str = "", + method: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + **kwargs, + ): + r"""Initializes a vector or matrix. + + Mechanical APDL Command: `\*INIT `_ + + Parameters + ---------- + name : str + Vector or matrix which will be initialized. This can be a vector (created by the :ref:`vec` + command), a dense matrix (created by the :ref:`dmat` command), or a sparse matrix (created by + the :ref:`smat` command). + + method : str + Initialization method to use: + + * ``ZERO`` - Fill the vector/matrix with zeros (default). + + * ``CONST`` - Fill the vector/matrix with a constant value. + + * ``RAND`` - Fill the vector/matrix with random values. + + * ``DIAG`` - Fill the ``n`` th diagonal of the matrix with a constant value. Other values are not + overwritten. For this option, ``Name`` must be a dense matrix. + + * ``ADIAG`` - Fill the ``n`` th anti-diagonal of the matrix with a constant value. Other values + are not overwritten. For this option, ``Name`` must be a dense matrix. + + * ``CONJ`` - Take the complex conjugate of the values in the vector/matrix (no change for non- + complex values). + + * ``FILTER`` - Initialize a subset of values of a vector using a filtering vector. For this + option, ``Name`` must be a vector. + + val1 : str + Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified + ``Method``. See details below. + + val2 : str + Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified + ``Method``. See details below. + + val3 : str + Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified + ``Method``. See details below. + + Notes + ----- + This command initializes a previously defined vector ( :ref:`vec` ), dense matrix ( :ref:`dmat` ), + or sparse matrix ( :ref:`smat` ). + """ + command = f"*INIT,{name},{method},{val1},{val2},{val3}" + return self.run(command, **kwargs) + + def export( + self, + matrix: str = "", + format_: str = "", + fname: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + **kwargs, + ): + r"""Exports a matrix to a file in the specified format. + + Mechanical APDL Command: `\*EXPORT `_ + + Parameters + ---------- + matrix : str + Name of the matrix to export (must be a matrix previously created with :ref:`dmat` or + :ref:`smat`, or a vector previously created with :ref:`vec` ). + + format_ : str + Format of the output file: + + * ``MMF`` - Export the matrix in the Matrix Market Format. + + * ``SUB`` - Export the matrix in the ``SUB`` file format. + + * ``HBMAT`` - Export the matrix in the Harwell-Boeing file format. + + * ``MAT`` - Export the matrix in a native format, to be re-imported using the :ref:`dmat` or + :ref:`smat` command. + + * ``EMAT`` - Export the matrix to an existing ``EMAT`` file. + + * ``APDL`` - Export the matrix to an APDL array parameter. + + * ``PS`` - Export the matrix profile to a Postscript file. + + * ``DMIG`` - Export the matrix in the ``DMIG`` file format. + + * ``CSV`` - Export the matrix to an ASCII CSV (comma-separated values) file. + + fname : str + Name of the file (case-sensitive, 32-character maximum), or name of the array parameter if + ``Format`` = APDL (no default) . + + val1 : str + Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified + ``Format``. See table below for details. + + val2 : str + Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified + ``Format``. See table below for details. + + val3 : str + Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified + ``Format``. See table below for details. + + Notes + ----- + Only sparse matrices can be exported to Postscript files. This option plots the matrix profile as a + series of dots. + + If you want to create a ``.SUB`` file from several matrices, you need to set ``Val3`` = WAIT for all + matrices but the last, and ``Val3`` = DONE for the last one. The export will be effective at the + last :ref:`export` command. + + To create a ``.SUB`` file or ``.DMIG`` file from scratch, you must supply the row information array. + (Specify this array in the ``Val2`` field for ``.SUB`` or in the ``Val1`` field for ``.DMIG``.) + This must be an ``m`` x 2 array, where ``m`` is the size of the matrix. The first column is the node + number and the second column is the DOF number corresponding to each row of the matrix. + + When exporting an HBMAT file in ASCII format, you can include the matrix type in the header of the + file by specifying the matrix type in the ``Val2`` field. The matrix type is not included in the + header if ``Val2`` is empty. If ``Val1`` = BINARY, ``Val2`` is not used. + + The :ref:`export` command is not applicable to sparse matrices initialized from ``.FULL`` files by + means of the NOD2SOLV option on the :ref:`smat` command (that is, :ref:`smat` + ,,,IMPORT,FULL,,NOD2SOLV). + + The ``.CSV`` file format does not support sparse matrices. + """ + command = f"*EXPORT,{matrix},{format_},{fname},{val1},{val2},{val3}" + return self.run(command, **kwargs) + + def eigen( + self, + kmatrix: str = "", + mmatrix: str = "", + cmatrix: str = "", + evals: str = "", + evects: str = "", + **kwargs, + ): + r"""Performs a modal solution with unsymmetric or damping matrices. + + Mechanical APDL Command: `\*EIGEN `_ + + Parameters + ---------- + kmatrix : str + Name of the stiffness matrix. May be a real or complex-valued matrix. + + mmatrix : str + Name of the mass matrix. + + cmatrix : str + Name of the damping matrix (used only for :ref:`modopt` ,DAMP). + + evals : str + Name of the output eigenvalues vector. It will be an ``m`` -long :ref:`vec` vector of complex + values, where ``m`` is the number of eigenvalues requested ( :ref:`modopt` ). + + evects : str + Name of the output eigenvector matrix. It will be a ``n`` x ``m`` :ref:`dmat` (dense) matrix of + complex values, where ``n`` is the size of the matrix and ``m`` is the number of eigenvalues + requested ( :ref:`modopt` ). + + Notes + ----- + Use the command :ref:`antype` ,MODAL and the :ref:`modopt` command to specify the modal solution + options. Only :ref:`modopt` ,DAMP, :ref:`modopt` ,UNSYM, :ref:`modopt` ,LANB, and :ref:`modopt` + ,SUBSP are supported. + + :ref:`eigen` with Block Lanczos (LANB) only supports sparse matrices. Distributed-Memory Parallel + (DMP) Restriction This command is not supported in a DMP solution. + """ + command = f"*EIGEN,{kmatrix},{mmatrix},{cmatrix},{evals},{evects}" + return self.run(command, **kwargs) + + def smat( + self, + matrix: str = "", + type_: str = "", + method: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + **kwargs, + ): + r"""Creates a sparse matrix. + + Mechanical APDL Command: `\*SMAT `_ + + Parameters + ---------- + matrix : str + Name used to identify the matrix. Must be specified. + + type_ : str + Matrix type: + + * ``D`` - Double precision real values (default). + + * ``Z`` - Complex double precision values. + + method : str + Method used to create the matrix: + + * ``ALLOC`` - Allocate a new matrix. + + * ``COPY`` - Copy an existing matrix. + + * ``IMPORT`` - Import the matrix from a file. + + val1 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + val2 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + val3 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + val4 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + val5 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + Notes + ----- + Use the :ref:`dmat` command to create a dense matrix. + + For more information on the CSR format, see `Creating a Sparse Matrix Using the CSR Format + `_ + + For more information on the NOD2SOLV and USR2SOLV mapping vectors, see. + + For more information about ``.FULL`` file contents, see the :ref:`hbmat` in the `Command Reference + `_ Command + Reference. + """ + command = f"*SMAT,{matrix},{type_},{method},{val1},{val2},{val3},{val4},{val5}" + return self.run(command, **kwargs) + + def starsort( + self, + name: str = "", + sorttype: str = "", + val1: str = "", + val2: str = "", + **kwargs, + ): + r"""Sorts the values of the specified vector. + + Mechanical APDL Command: `\*SORT `_ + + Parameters + ---------- + name : str + Name of the vector to be sorted. This vector can contain real or complex values. + + sorttype : str + Criteria used to sort the values: + + * ``VALUE`` - Values are sorted based on their real value (default). + + * ``ABS`` - Values are sorted based on their absolute value. + + * ``PERM`` - Values are sorted based on the input permutation vector ( ``Val1`` ). + + val1 : str + Additional input. The meaning of ``Val1``, ``Val2`` varies depending on the specified + ``SortType``. See below for details. + + val2 : str + Additional input. The meaning of ``Val1``, ``Val2`` varies depending on the specified + ``SortType``. See below for details. + + Notes + ----- + The examples below demonstrate using :ref:`starsort` to sort the values of an input vector. + + The following input: + + .. code:: apdl + + *VEC,V,I,ALLOC,5 + V(1)=5,-3,2,0,-1 + *SORT,V,VALUE + *PRINT,V + + generates this output: + + .. code:: apdl + + -3 -1 0 2 5 + + To reverse the order, this input: + + .. code:: apdl + + *SORT,V,VALUE,,1 + *PRINT,V + + generates this output: + + .. code:: apdl + + 5 2 0 -1 -3 + """ + command = f"*SORT,{name},{sorttype},{val1},{val2}" + return self.run(command, **kwargs) + + def scal(self, name: str = "", val1: str = "", val2: str = "", **kwargs): + r"""Scales a vector or matrix by a constant. + + Mechanical APDL Command: `\*SCAL `_ + + Parameters + ---------- + name : str + Name used to identify the vector or matrix to be scaled. Must be specified. + + val1 : str + The real part of the constant to use (default = 1). + + val2 : str + The imaginary part of the constant to use (default = 0). This value is used only if the vector + or matrix specified by ``Name`` is complex. + + Notes + ----- + This command can be applied to vectors and matrices created by the :ref:`vec`, :ref:`dmat` and + :ref:`smat` commands. + """ + command = f"*SCAL,{name},{val1},{val2}" + return self.run(command, **kwargs) + + def vec( + self, + vector: str = "", + type_: str = "", + method: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + **kwargs, + ): + r"""Creates a vector. + + Mechanical APDL Command: `\*VEC `_ + + Parameters + ---------- + vector : str + Name used to identify the vector. Must be specified. + + type_ : str + Vector type: + + * ``D`` - Double precision real values (default). + + * ``Z`` - Complex double precision values. + + * ``I`` - Integer values. + + method : str + Method used to create the vector: + + * ``ALLOC`` - Allocate space for a vector (default). + + * ``RESIZE`` - Resize an existing vector to a new length. Values are kept from the original + vector. If the length specified by ``Val1`` is greater than the original vector length, the + additional rows are assigned a value of zero. + + * ``COPY`` - Copy an existing vector. + + * ``IMPORT`` - Import the vector from a file. + + * ``LINK`` - Link to a column of an existing dense :ref:`dmat` matrix and use it in subsequent + vector calculations. Any changes to the vector are also made to the corresponding matrix column + (memory is shared). + + val1 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + val2 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + val3 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + val4 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + Notes + ----- + Use the :ref:`dmat` command to create a matrix. + + For more information on the BACK and FORWARD nodal mapping vectors, see in the `Ansys Parametric + Design Language Guide + `_ ANSYS Parametric + Design Language Guide. + """ + command = f"*VEC,{vector},{type_},{method},{val1},{val2},{val3},{val4}" + return self.run(command, **kwargs) + + def hprod(self, a: str = "", b: str = "", c: str = "", **kwargs): + r"""Performs a Hadamard vector product (C = A∘B). + + Mechanical APDL Command: `\*HPROD `_ + + Parameters + ---------- + a : str + Name of vector A. Must have been previously created by a :ref:`vec` command. + + b : str + Name of vector B. Must have been previously created by a :ref:`vec` command. + + c : str + Name of vector C. Must be specified (no default). + + Notes + ----- + For two vectors ``A`` and ``B`` of the same dimension ``n``, the Hadamard product (A∘B) is a vector + of the same dimension as the operands, with elements given by: + + A ∘ B i = A i * B i + This command is limited to vector operands. + """ + command = f"*HPROD,{a},{b},{c}" + return self.run(command, **kwargs) + + def lsengine( + self, + type_: str = "", + enginename: str = "", + matrix: str = "", + option: str = "", + **kwargs, + ): + r"""Creates a linear solver engine. + + Mechanical APDL Command: `\*LSENGINE `_ + + Parameters + ---------- + type_ : str + Specifies the algorithm to be used: + + * ``DSS`` - MKL sparse linear solver. + + * ``LAPACK`` - LAPACK dense matrix linear solver (default if applied to dense matrices). + + * ``DSP`` - Distributed sparse solver (default for sparse matrices). + + enginename : str + Name used to identify this engine. Must be specified. + + matrix : str + Name of the matrix to solve. + + option : str + Option to control the memory mode of the DSS solver (used only if ``Type`` = DSS): + + * ``INCORE`` - In-core memory mode. + + * ``OUTOFCORE`` - Out-of-core memory mode. + + Notes + ----- + This command creates a linear solver engine. + + The DSS and DSP solvers can only be used with sparse matrices. For dense matrices, use the LAPACK + solver. + """ + command = f"*LSENGINE,{type_},{enginename},{matrix},{option}" + return self.run(command, **kwargs) + + def lsfactor(self, enginename: str = "", option: str = "", **kwargs): + r"""Performs the numerical factorization of a linear solver system. + + Mechanical APDL Command: `\*LSFACTOR `_ + + Parameters + ---------- + enginename : str + Name used to identify this engine. Must have been previously created using :ref:`lsengine` . + + option : str + Option to invert the matrix, used only with an LAPACK engine ( :ref:`lsengine` ,LAPACK): + + * ``INVERT`` - Invert the matrix. + + Notes + ----- + Performs the computationally intensive, memory intensive factorization of a matrix specified by + :ref:`lsengine`, using the solver engine also specified by :ref:`lsengine` . + """ + command = f"*LSFACTOR,{enginename},{option}" + return self.run(command, **kwargs) + + def lsrestore(self, enginename: str = "", filename: str = "", **kwargs): + r"""Restores a linear solver engine from a binary file. + + Mechanical APDL Command: `\*LSRESTORE `_ + + Parameters + ---------- + enginename : str + Name used to identify this engine. + + filename : str + Name of the file to read from. + + Notes + ----- + Restores a previously dumped Linear Solver (see the :ref:`lsdump` command). This Linear Solver can + be used to solve a linear system using the :ref:`lsbac` command. + + + """ + command = f"*LSRESTORE,{enginename},{filename}" + return self.run(command, **kwargs) + + def lsbac( + self, + enginename: str = "", + rhsvector: str = "", + solvector: str = "", + transkey: str = "", + **kwargs, + ): + r"""Performs the solve (forward/backward substitution) of a factorized linear system. + + Mechanical APDL Command: `\*LSBAC `_ + + Parameters + ---------- + enginename : str + Name used to identify this engine. Must have been previously created using :ref:`lsengine` and + factorized using :ref:`lsfactor` . + + rhsvector : str + Name of vector containing the right-hand side (load) vectors as input. Must have been previously + defined as a :ref:`vec` vector or a :ref:`dmat` matrix. + + solvector : str + Name of vector that will contain the solution vectors upon completion. Must be predefined as a + :ref:`vec` vector or :ref:`dmat` matrix. + + transkey : str + Transpose key. Set ``TransKey`` = TRANS to solve the transposed linear system. If blank, + transpose will not be used. + + Notes + ----- + This command performs forward and back substitution to obtain the solution to the linear matrix + equation Ax = b (or A :sup:`T` x = b if ``TransKey`` = TRANS). The matrix engine must have been + previously defined using :ref:`lsengine`, and the matrix factored using :ref:`lsfactor` . + + You can use the :ref:`dmat` ,,,COPY (or :ref:`vec` ,,,COPY) command to copy the load vector to the + solution vector in order to predefine it with the appropriate size. + """ + command = f"*LSBAC,{enginename},{rhsvector},{solvector},{transkey}" + return self.run(command, **kwargs) + + def lsdump(self, enginename: str = "", filename: str = "", **kwargs): + r"""Dumps a linear solver engine to a binary File. + + Mechanical APDL Command: `\*LSDUMP `_ + + Parameters + ---------- + enginename : str + Name used to identify this engine. Must have been previously created using :ref:`lsengine` and + factorized using :ref:`lsfactor` . + + filename : str + Name of the file to create. + + Notes + ----- + Dumps a previously factorized linear solver system to a binary file. Only LAPACK and BCS linear + solvers can be used with this feature. The Linear Solver can later be restored with the + :ref:`lsrestore` command. + + A BCS Sparse Solver can be dumped only if uses the ``INCORE`` memory option (see :ref:`bcsoption` ). + + + """ + command = f"*LSDUMP,{enginename},{filename}" + return self.run(command, **kwargs) + + def remove( + self, name: str = "", val1: str = "", val2: str = "", val3: str = "", **kwargs + ): + r"""Suppresses rows or columns of a dense matrix or a vector. + + Mechanical APDL Command: `\*REMOVE `_ + + Parameters + ---------- + name : str + Name of the matrix or vector to be revised. + + val1 : str + Additional input. The meaning of ``Val1`` to ``Val3`` varies depending on the entity type + (matrix or vector). See details below. + + val2 : str + Additional input. The meaning of ``Val1`` to ``Val3`` varies depending on the entity type + (matrix or vector). See details below. + + val3 : str + Additional input. The meaning of ``Val1`` to ``Val3`` varies depending on the entity type + (matrix or vector). See details below. + + Notes + ----- + The values of the original matrix or vector specified by ``Name`` are retained. The matrix or vector + is resized to the new number of rows and columns. + """ + command = f"*REMOVE,{name},{val1},{val2},{val3}" + return self.run(command, **kwargs) + + def starrename(self, oldname: str = "", newname: str = "", **kwargs): + r"""Renames an existing vector or matrix. + + Mechanical APDL Command: `\*RENAME `_ + + Parameters + ---------- + oldname : str + Name of the existing vector or matrix to be renamed. + + newname : str + New name for the vector or matrix. + + Notes + ----- + The :ref:`starrename` command is used to rename `APDL Math + `_ objects. + """ + command = f"*RENAME,{oldname},{newname}" + return self.run(command, **kwargs) + + def axpy( + self, + vr: str = "", + vi: str = "", + m1: str = "", + wr: str = "", + wi: str = "", + m2: str = "", + **kwargs, + ): + r"""Performs the matrix operation M2= v\2M1 + w\2M2. + + Mechanical APDL Command: `\*AXPY `_ + + Parameters + ---------- + vr : str + The real and imaginary parts of the scalar ``v``. Default value is 0. + + vi : str + The real and imaginary parts of the scalar ``v``. Default value is 0. + + m1 : str + Name of matrix ``M1``. If not specified, the operation M2 = w\2M2 will be performed. + + wr : str + The real and imaginary parts of the scalar ``w``. Default value is 0. + + wi : str + The real and imaginary parts of the scalar ``w``. Default value is 0. + + m2 : str + Name of matrix ``M2``. Must be specified. + + Notes + ----- + The matrices ``M1`` and ``M2`` must have the same dimensions and same type (dense or sparse). If + ``M2`` is real, ``vi`` and ``wi`` are ignored. + """ + command = f"*AXPY,{vr},{vi},{m1},{wr},{wi},{m2}" + return self.run(command, **kwargs) + + def dmat( + self, + matrix: str = "", + type_: str = "", + method: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + **kwargs, + ): + r"""Creates a dense matrix. + + Mechanical APDL Command: `\*DMAT `_ + + Parameters + ---------- + matrix : str + Name used to identify the matrix. Must be specified. + + type_ : str + Matrix type: + + * ``D`` - Double precision real values (default). + + * ``Z`` - Complex double precision values. + + * ``I`` - Integer values. + + method : str + Method used to create the matrix: + + * ``ALLOC`` - Allocate space for a matrix (default). + + * ``RESIZE`` - Resize an existing matrix to new row and column dimensions. Values are kept from + the original matrix. If the dimensions specified by ``Val1`` (rows) and ``Val2`` (columns) are + greater than the original matrix size, the additional entries are assigned a value of zero. + + * ``COPY`` - Copy an existing matrix. + + * ``LINK`` - Link to an existing matrix. The memory will be shared between the original matrix and + the new matrix. This is useful for manipulating a submatrix of a larger matrix. The ``Val1`` + through ``Val5`` arguments will be used to specify the lower and upper bounds of row and column + numbers from the original matrix. + + * ``IMPORT`` - Import the matrix from a file. + + val1 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + val2 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + val3 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + val4 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + val5 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. + + Notes + ----- + This command allows you to create a dense matrix. To create a sparse matrix, use the :ref:`smat` + command. :ref:`smat` is recommended for large matrices obtained from the ``.FULL`` or ``.HBMAT`` + file. Refer to the :ref:`hbmat` command documentation for more information about ``.FULL`` file + contents. + + Use the :ref:`vec` command to create a vector. + + For very large matrices, use the OUTOFCORE option ( ``Method`` = ALLOC or COPY) to keep some of the + matrix on disk if there is insufficient memory. + + When importing a dense matrix from a **DMIG** file, you can define the formatting of the file using + the ``Val3`` and ``Val4`` fields. Here are a few different example of formats: + + A LARGE field format file (using ``Val3`` = ``LARGE``): + + .. code:: apdl + + ... + DMIG* KAAX 21 2 + * 21 1-2.261491337E+08 + ... + + A FREE field format file with blank separators (using ``Val4`` = ``S``): + + .. code:: apdl + + ... + DMIG stiff 1 2 1 2 29988. + 1 6 149940. 2 2 -29988. + 2 6 149940. + ... + + A FREE field format file with a comma separator (using ``Val4`` = ``,``): + + .. code:: apdl + + ... + DMIG,KF,22321,3,,22321,2,-5.00E+6 + DMIG,KF,22320,3,,22320,2,-5.00E+6 + ... + + **Requirement when importing matrices from a Nastran DMIG file:** To ensure that the ``.sub`` file + is properly generated from matrices imported from Nastran **DMIG** file, the generalized coordinates + for a CMS superelement (SPOINTS in Nastran) must appear last (have + highest ID number). + """ + command = f"*DMAT,{matrix},{type_},{method},{val1},{val2},{val3},{val4},{val5}" + return self.run(command, **kwargs) + + def dot( + self, + vector1: str = "", + vector2: str = "", + par_real: str = "", + par_imag: str = "", + conj: str = "", + **kwargs, + ): + r"""Computes the dot (or inner) product of two vectors. + + Mechanical APDL Command: `\*DOT `_ + + Parameters + ---------- + vector1 : str + Name of first vector; must have been previously specified by a :ref:`vec` command. + + vector2 : str + Name of second vector; must have been previously specified by a :ref:`vec` command. + + par_real : str + Parameter name that contains the result. + + par_imag : str + Parameter name that contains the imaginary part of the result (used only for complex vectors). + + conj : str + Key to specify use of the conjugate of ``Vector1`` when the vectors are complex: + + * ``TRUE`` - Use the conjugate of ``Vector1`` (default). + + * ``FALSE`` - Do not use the conjugate of ``Vector1``. + + Notes + ----- + If ``Vector1`` and ``Vector2`` are complex, the complex conjugate of ``Vector1`` is used to compute + the result ( ``Par_Real``, ``Par_Imag`` ). Therefore, **\*DOT** applied to complex vectors performs + the operation: + + r e s = V 1 * ⋅ V 2 + Set ``Conj`` = FALSE if you do not want to use the conjugate of ``Vector1``. In this case, the + operation is: + + r e s = V 1 ⋅ V 2 + """ + command = f"*DOT,{vector1},{vector2},{par_real},{par_imag},{conj}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/parameter_definition.py b/src/ansys/mapdl/core/_commands/apdl/parameter_definition.py index 37e27f1f20..5629b921aa 100644 --- a/src/ansys/mapdl/core/_commands/apdl/parameter_definition.py +++ b/src/ansys/mapdl/core/_commands/apdl/parameter_definition.py @@ -22,301 +22,172 @@ class ParameterDefinition: - def afun(self, lab="", **kwargs): - """Specifies units for angular functions in parameter expressions. - APDL Command: ``*AFUN`` + def parres(self, lab: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Reads parameters from a file. + + Mechanical APDL Command: `PARRES `_ Parameters ---------- - lab - Specifies the units to be used: + lab : str + Read operation: - Use radians for input and output of parameter angular functions (default). - Use degrees for input and output of parameter angular functions. + * ``NEW`` - Replace current parameter set with these parameters (default). - Notes - ----- - Only the SIN, COS, TAN, ASIN, ACOS, ATAN, ATAN2, ANGLEK, and ANGLEN - functions ``[*SET, *VFUN]`` are affected by this command. - """ - command = f"*AFUN,{lab}" - return self.run(command, **kwargs) + * ``CHANGE`` - Extend current parameter set with these parameters, replacing any that already + exist. - def dim( - self, - par="", - type_="", - imax="", - jmax="", - kmax="", - var1="", - var2="", - var3="", - csysid="", - **kwargs, - ): - """Defines an array parameter and its dimensions. + 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 ``Jobname``. - APDL Command: ``*DIM`` + ext : str + Filename extension (eight-character maximum). The extension defaults to PARM if ``Fname`` is + blank. - Parameters - ---------- - par - Name of parameter to be dimensioned. See ``*SET`` for name - restrictions. + Notes + ----- + Reads parameters from a coded file. The parameter file may have been written with the :ref:`parsav` + command. The parameters read may replace or change the current parameter set. - type\\_ - Array type: + This command is valid in any processor. - Arrays are similar to standard FORTRAN arrays (indices are - integers) (default). Index numbers for the rows, columns, - and planes are sequential values beginning with one. Used - for 1-, 2-, or 3-D arrays. - Same as ARRAY, but used to - specify 4-D arrays. - - Same as ARRAY, but used to specify 5-D arrays. - Array - entries are character strings (up to 8 characters each). - Index numbers for rows, columns, and planes are sequential - values beginning with one. - - Array indices are real (non-integer) numbers which must be - defined when filling the table. Index numbers for the - rows and columns are stored in the zero column and row - "array elements" and are initially assigned a near-zero - value. Index numbers must be in ascending order and are - used only for retrieving an array element. When - retrieving an array element with a real index that does - not match a specified index, linear interpolation is done - among the nearest indices and the corresponding array - element values [``*SET``]. Used for 1-, 2-, or 3-D tables. - - Same as TABLE, but used to specify 4-D tables. - - Same as TABLE, but used to specify 5-D tables. - Array - entries are character strings (up to IMAX each). Index - numbers for columns and planes are sequential values - beginning with 1. Row index is character position in - string. - - imax - Extent of first dimension (row). (For Type = STRING, IMAX is - rounded up to the next multiple of eight and has a limit of 248). - Defaults to 1. - - jmax - Extent of second dimension (column). Defaults to 1. - - kmax - Extent of third dimension (plane). Defaults to 1. - - var1 - Variable name corresponding to the first dimension (row) for Type = - TABLE. Defaults to Row. - - var2 - Variable name corresponding to the second dimension (column) for - Type = TABLE. Defaults to Column. - - var3 - Variable name corresponding to the third dimension (plane) for Type - = TABLE. Defaults to Plane. - - csysid - An integer corresponding to the coordinate system ID Number. + Examples + -------- + Read a local parameter file. - Notes - ----- - Up to three dimensions (row, column, and plane) may be defined using - ARRAY and TABLE. Use ARR4, ARR5, TAB4, and TAB5 to define up to five - dimensions (row, column, plane, book, and shelf). An index number is - associated with each row, column, and plane. For array and table type - parameters, element values are initialized to zero. For character and - string parameters, element values are initialized to (blank). A - defined parameter must be deleted [``*SET``] before its dimensions can be - changed. Scalar (single valued) parameters should not be dimensioned. - ``*DIM,A,,3`` defines a vector array with elements A(1), A(2), and A(3). - ``*DIM,B,,2,3`` defines a 2x3 array with elements B(1,1), B(2,1), B(1,2), - B(2,2), B(1,3), and B(2,3). Use ``*STATUS,Par`` to display elements of - array Par. You can write formatted data files (tabular formatting) from - data held in arrays through the ``*VWRITE`` command. - - If you use table parameters to define boundary conditions, then Var1, - Var2, and/or Var3 can either specify a primary variable (listed in - Table: 130:: ``*DIM`` - Primary Variables) or can be an independent - parameter. If specifying an independent parameter, then you must - define an additional table for the independent parameter. The - additional table must have the same name as the independent parameter - and may be a function of one or more primary variables or another - independent parameter. All independent parameters must relate to a - primary variable. - - Tabular load arrays can be defined in both global Cartesian (default) - or local (see below) coordinate systems by specifying CSYSID, as - defined in LOCAL. For batch operations, you must specify your - coordinate system first. - - The following constraints apply when you specify a local coordinate - system for your tabular loads: - - If you are specifying a 4- or 5-D array or table, four additional - fields (LMAX, MMAX, Var4, and Var5) are available. Thus, for a 4-D - table, the command syntax would be: - - For a 5-D table, the command syntax would be: - - You cannot create or edit 4- or 5-D arrays or tables using the GUI. - - See Array Parameters for a detailed discussion on and examples for - using array parameters. - - Table: 130:: : ``*DIM`` - Primary Variables + >>> mapdl.parres('parm.PARM') + """ + return self.run(f"PARRES, {lab}, {fname}, {ext}") - Specify PRESSURE as the independent variable (not PRES). + def parsav(self, lab: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Writes parameters to a file. - The X, Y, and Z coordinate locations listed above are valid in global - Cartesian, or local (Cartesian, cylindrical and spherical) coordinate - systems. The VELOCITY label is applicable only to the calculated fluid - velocity in element FLUID116. + Mechanical APDL Command: `PARSAV `_ - When using PRESSURE as a primary variable, the underlying element must - have the pressure DOF associated with it, or it must be a supported - contact element. + Parameters + ---------- + lab : str + Write operation: - The gap/penetration label (GAP) is only used for defining certain - contact element real constants. + * ``SCALAR`` - Write only scalar parameters (default). - The frequency label (FREQ) is valid for harmonic analyses only. + * ``ALL`` - Write scalar and array parameters. Parameters may be numeric or alphanumeric. - The OMEGS, ECCENT, and THETA primary variables only apply to the - COMBI214 element. The amplitude of the rotational velocity (OMEGS) is - an absolute value, so only positive values of OMEGS are valid. The - eccentricity (ECCENT) and phase shift (THETA) labels are only valid for - nonlinear analyses. + 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 ``Jobname``. - If you use table parameters to define boundary conditions, the table - names (Par) must not exceed 32 characters. + ext : str + Filename extension (eight-character maximum). The extension defaults to PARM if ``Fname`` is + blank. - In thermal analyses, if you apply tabular loads as a function of - temperature but the rest of the model is linear (e.g., includes no - temperature-dependent material properties or radiation ), you should - turn on Newton-Raphson iterations (NROPT,FULL) to evaluate the - temperature-dependent tabular boundary conditions correctly. + Notes + ----- + Writes the current parameters to a coded file. Previous parameters on this file, if any, will be + overwritten. The parameter file may be read with the :ref:`parres` command. + + :ref:`parsav` / :ref:`parres` operations truncate some long decimal strings, and can cause differing + values in your solution data when other operations are performed. A good practice is to limit the + number of decimal places you will use before and after these operations. This command is valid in any processor. """ - command = ( - f"*DIM,{par},{type_},{imax},{jmax},{kmax},{var1},{var2},{var3},{csysid}" - ) + command = f"PARSAV,{lab},{fname},{ext}" return self.run(command, **kwargs) def get( self, - par="", - entity="", - entnum="", - item1="", - it1num="", - item2="", - it2num="", + par: str = "", + entity: str = "", + entnum: str = "", + item1: str = "", + it1num: str = "", + item2: str = "", + it2num: str = "", **kwargs, ): - """Retrieves a value and stores it as a scalar parameter or part of an array parameter. - - APDL Command: ``*GET`` - - See the full MADPL command at `*GET - `_ - - GET retrieves a value for a specified item and stores the - value as a scalar parameter, or as a value in a user-named - array parameter. An item is identified by various keyword, - label, and number combinations. Usage is similar to the SET - command except that the parameter values are retrieved from - previously input or calculated results. For example, - ``GET,A,ELEM,5,CENT,X`` returns the centroid x-location of element - 5 and stores the result as parameter A. GET command - operations, along with the associated Get functions return - values in the active coordinate system unless stated - otherwise. A Get function is an alternative in- line function - that can be used to retrieve a value instead of the GET - command (see Using In-line Get Functions for more - information). - Both GET and VGET retrieve information from the active data - stored in memory. The database is often the source, and - sometimes the information is retrieved from common memory - blocks that the program uses to manipulate - information. Although POST1 and POST26 operations use a .rst - file, GET data is accessed from the database or from the - common blocks. Get operations do not access the .rst file - directly. For repeated gets of sequential items, such as from - a series of elements, see the VGET command. - Most items are stored in the database after they are - calculated and are available anytime thereafter. Items are - grouped according to where they are usually first defined or - calculated. Preprocessing data will often not reflect the - calculated values generated from section data. Do not use GET - to obtain data from elements that use calculated section data, - such as beams or shells. Most of the general items listed - below are available from all modules. + r"""Retrieves a value and stores it as a scalar parameter or part of an array parameter. + + Mechanical APDL Command: `\*GET `_ Parameters ---------- - par : str, optional - The name of the resulting parameter. See \\*SET for name - restrictions. + par : str + The name of the resulting parameter. See :ref:`starset` for name restrictions. + + entity : str + Entity keyword. Valid keywords are NODE, ELEM, KP, LINE, AREA, VOLU, etc., as shown for + ``Entity`` = in the tables below. + + entnum : str + The number or label for the entity (as shown for ``ENTNUM`` = in the tables below). In some + cases, a zero (or blank) ``ENTNUM`` represents all entities of the set. - entity - Entity keyword. Valid keywords are NODE, ELEM, KP, LINE, - AREA, VOLU, PDS, etc., as shown for Entity = in the tables - below. - - entnum - The number or label for the entity (as shown for ENTNUM = - in the tables below). In some cases, a zero (or blank) - ENTNUM represents all entities of the set. - - item1 - The name of a particular item for the given entity. - - it1num - The number (or label) for the specified Item1 (if - any). Valid IT1NUM values are as shown in the IT1NUM - columns of the tables below. Some Item1 labels do not - require an IT1NUM value. - - item2, it2num - A second set of item labels and numbers to further qualify - the item for which data are to be retrieved. Most items do - not require this level of information. - - item3 - A third set of item labels to further qualify - the item for which data are to be retrieved. Almost all items do - not require this level of information. - - item3 : str, optional - A third set of item labels and numbers to further qualify the item - for which data are to be retrieved. Most items do not require this - level of information. - - it3num : str, int, optional - The number (or label) for the specified ``item3`` (if - any). Some ``item3`` labels do not require an ``it3num`` - value. - - item4 : str, optional - A fourth set of item labels and numbers to further qualify the item - for which data are to be retrieved. Most items do not require this level of information. - - it4num : str, int, optional - The number (or label) for the specified ``item4`` (if - any). Some ``item4`` labels do not require an ``it4num`` - value. + item1 : str + The name of a particular item for the given entity. Valid items are as shown in the ``Item1`` + columns of the tables below. + + it1num : str + The number (or label) for the specified ``Item1`` (if any). Valid ``IT1NUM`` values are as shown + in the ``IT1NUM`` columns of the tables below. Some ``Item1`` labels do not require an + ``IT1NUM`` value. + + item2 : str + A second set of item labels and numbers to further qualify the item for which data are to be + retrieved. Most items do not require this level of information. + + it2num : str + A second set of item labels and numbers to further qualify the item for which data are to be + retrieved. Most items do not require this level of information. Returns ------- float Floating point value of the parameter. + Notes + ----- + :ref:`get` retrieves a value for a specified item and stores the value as a scalar parameter, or as + a value in a user-named array parameter. An item is identified by various keyword, label, and number + combinations. Usage is similar to the :ref:`starset` command except that the parameter values are + retrieved from previously input or calculated results. + + :ref:`get` Usage :ref:`get` ,A,ELEM,5,CENT,X returns the centroid x location of element 5 and stores + the result as parameter A. + + :ref:`get` command operations, and corresponding get functions, return values in the active + coordinate system ( :ref:`csys` for input data or :ref:`rsys` for results data) unless stated + otherwise. + + A get function is an alternative in-line function that can be used instead of the :ref:`get` command + to retrieve a value. For more information, see. + + Both :ref:`get` and :ref:`starvget` retrieve information from the active data stored in memory. The + database is often the source, and sometimes the information is retrieved from common memory blocks + that the program uses to manipulate information. Although POST1 and POST26 operations use a + ``\2.rst`` file, :ref:`get` data is accessed from the database or from the common blocks. Get + operations do not access the ``\2.rst`` file directly. For repeated gets of sequential items, such as + from a series of elements, see the :ref:`starvget` command. + + Most items are stored in the database after they are calculated and are available anytime + thereafter. Items are grouped according to where they are usually first defined or calculated. + Preprocessing data will often not reflect the calculated values generated from section data. Do not + use :ref:`get` to obtain data from elements that use calculated section data, such as beams or + shells. + + When the value retrieved by :ref:`get` is a component name, the resulting character parameter is + limited to 32 characters. If the component name is longer than 32 characters, the remaining + characters are ignored. + + Most of the general items listed below are available from all modules. Each of the sections for + accessing :ref:`get` parameters are shown in the following order: + + The :ref:`get` command is valid in any processor. + Examples -------- Retrieve the number of nodes @@ -331,18 +202,21 @@ def get( >>> value = mapdl.get(entity='node', item1='count') >>> value 3003 - """ command = f"*GET,{par},{entity},{entnum},{item1},{it1num},{item2},{it2num}" return self.run(command, **kwargs) - def inquire(self, strarray="", func="", arg1="", arg2="", **kwargs): - """Returns system information. - - By default, with no arguments, it returns the working directory. + def inquire( + self, + strarray: str = "", + func: str = "", + arg1: str = "", + arg2: str = "", + **kwargs, + ): + r"""Returns system information to a parameter. - >>> mapdl.inquire() - C:\\Users\\user\\AppData\\Local\\Temp\\ansys_nynvxsaooh + Mechanical APDL Command: `/INQUIRE `_ Parameters ---------- @@ -351,8 +225,8 @@ def inquire(self, strarray="", func="", arg1="", arg2="", **kwargs): Normally, if used in a python script you should just work with the return value from this method. func : str, optional - Specifies the type of system information returned. See the - notes section for more information. + Specifies the type of system information returned. See the + notes section for more information. arg1 : str, optional First argument. See notes for ``arg1`` definition. arg2 : str, optional @@ -368,22 +242,22 @@ def inquire(self, strarray="", func="", arg1="", arg2="", **kwargs): The ``/INQUIRE`` command is valid in any processor. .. warning:: - Take note that from version 0.60.4 and later, the command behaviour - has been changed. - Previously, the ``StrArray`` argument was omitted. For example: - >>> mapdl.inquire('DIRECTORY') - C:\\Users\\user\\AppData\\Local\\Temp\\ansys_nynvxsaooh + Take note that from version 0.60.4 and later, the command behaviour + has been changed. + Previously, the ``StrArray`` argument was omitted. For example: + >>> mapdl.inquire('DIRECTORY') + C:\\Users\\user\\AppData\\Local\\Temp\\ansys_nynvxsaooh - Now this will raise an exception. - The default behaviour now, requires to input ``StrArray``: - >>> mapdl.inquire('', 'DIRECTORY') - C:\\Users\\user\\AppData\\Local\\Temp\\ansys_nynvxsaooh + Now this will raise an exception. + The default behaviour now, requires to input ``StrArray``: + >>> mapdl.inquire('', 'DIRECTORY') + C:\\Users\\user\\AppData\\Local\\Temp\\ansys_nynvxsaooh **GENERAL FUNC OPTIONS** - ``LOGIN`` - Returns the pathname of the login directory on Linux - systems or the pathname of the default directory (including - drive letter) on Windows systems. + systems or the pathname of the default directory (including + drive letter) on Windows systems. - ``DOCU`` - Pathname of the ANSYS documentation directory. - ``APDL`` - Pathname of the ANSYS APDL directory. - ``PROG`` - Pathname of the ANSYS executable directory. @@ -396,7 +270,6 @@ def inquire(self, strarray="", func="", arg1="", arg2="", **kwargs): - ``RSTEXT`` - Result file extension. - ``OUTPUT`` - Current output file name. - **RETURNING THE VALUE OF AN ENVIRONMENT VARIABLE TO A PARAMETER** If ``FUNC=ENV``, the command format is ``/INQUIRE,StrArray,ENV,ENVNAME,Substring``. @@ -405,15 +278,14 @@ def inquire(self, strarray="", func="", arg1="", arg2="", **kwargs): The following defines the remaining fields: Envname: - Specifies the name of the environment variable. + Specifies the name of the environment variable. Substring: - If ``Substring = 1``, the first substring (up to the first colon (:)) is returned. - If ``Substring = 2``, the second substring is returned, etc. For Windows platforms, - the separating character is semicolon (;). - If this argument is either blank or 0, the entire value of the environment - variable is returned. - + If ``Substring = 1``, the first substring (up to the first colon (:)) is returned. + If ``Substring = 2``, the second substring is returned, etc. For Windows platforms, + the separating character is semicolon (;). + If this argument is either blank or 0, the entire value of the environment + variable is returned. **RETURNING THE VALUE OF A TITLE TO A PARAMETER** @@ -422,7 +294,6 @@ def inquire(self, strarray="", func="", arg1="", arg2="", **kwargs): value is ``1`` or blank, the title is returned. If the value is ``2`` through ``5``, a corresponding subtitle is returned (``2`` denoting the first subtitle, and so on). - **RETURNING INFORMATION ABOUT A FILE TO A PARAMETER** The ``/INQUIRE`` command can also return information about specified files @@ -431,42 +302,42 @@ def inquire(self, strarray="", func="", arg1="", arg2="", **kwargs): The following defines the fields: Parameter: - Name of the parameter that will hold the returned values. + Name of the parameter that will hold the returned values. Func: - Specifies the type of file information returned: + Specifies the type of file information returned: - EXIST: - Returns a ``1`` if the specified file exists, and ``0`` if it does not. + EXIST: + Returns a ``1`` if the specified file exists, and ``0`` if it does not. - DATE: - Returns the date stamp of the specified file in the format ``*yyyymmdd.hhmmss*``. + DATE: + Returns the date stamp of the specified file in the format ``\2yyyymmdd.hhmmss*``. - SIZE: - Returns the size of the specified file in MB. + SIZE: + Returns the size of the specified file in MB. - WRITE: - Returns the status of the write attribute. A ``0`` denotes no write permission while a ``1`` denotes - write permission. + WRITE: + Returns the status of the write attribute. A ``0`` denotes no write permission while a ``1`` denotes + write permission. - READ: - Returns the status of the read attribute. A ``0`` denotes no read permission while a ``1`` denotes read - permission. + READ: + Returns the status of the read attribute. A ``0`` denotes no read permission while a ``1`` denotes read + permission. - EXEC: - Returns the status of the execute attribute (this has meaning only on Linux). A ``0`` denotes no - execute permission while a ``1`` denotes execute permission. + EXEC: + Returns the status of the execute attribute (this has meaning only on Linux). A ``0`` denotes no + execute permission while a ``1`` denotes execute permission. - LINES: - Returns the number of lines in an ASCII file. + LINES: + Returns the number of lines in an ASCII file. 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. + 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). + Filename extension (eight-character maximum). Examples -------- @@ -491,662 +362,1097 @@ def inquire(self, strarray="", func="", arg1="", arg2="", **kwargs): """ return self.run(f"/INQUIRE,{strarray},{func},{arg1},{arg2}", **kwargs) - def parres(self, lab="", fname="", ext="", **kwargs): - """Reads parameters from a file. + def starset( + self, + par: str = "", + value: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + val7: str = "", + val8: str = "", + val9: str = "", + val10: str = "", + **kwargs, + ): + r"""Assigns values to user-named parameters. - APDL Command: PARRES + Mechanical APDL Command: `\*SET `_ - Reads parameters from a coded file. The parameter file may - have been written with the PARSAV command. The parameters - read may replace or change the current parameter set. + Parameters + ---------- + par : str + An alphanumeric name used to identify this parameter. ``Par`` can contain up to 32 characters, + beginning with a letter and containing only letters, numbers, and underscores. Examples: ABC + A3X TOP_END + + Command names, function names, label names, component and assembly names, etc., are invalid, as + are parameter names beginning with an underscore (for example, _LOOP ). + + Parameter names ending in an underscore are not listed by the :ref:`starstatus` command. Array + parameter names must be followed by a subscript, and the entire expression must be 32 characters + or less. Examples: A(1,1) NEW_VAL(3,2,5) RESULT(1000) + + There is no character parameter substitution for the ``Par`` field. Table parameters used in + command fields (where constant values are normally given) are limited to 32 characters. + + value : str + Numerical value or alphanumeric character string (up to 32 characters enclosed in single quotes) + to be assigned to this parameter. Examples: A(1,3)=7.4 B='ABC3' Can also be a parameter or a + parametric expression. Examples: C=A(1,3) A(2,2)=(C+4)/2 . If ``VALUE`` is the table array + name, the subscripts are the values of the primary variables and the table is evaluated at these + specified index values. + + If blank, delete this parameter. Example: A= deletes parameter A . + + val2 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. Examples: + *SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and *SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11' . + + val3 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. Examples: + *SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and *SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11' . + + val4 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. Examples: + *SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and *SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11' . + + val5 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. Examples: + *SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and *SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11' . + + val6 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. Examples: + *SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and *SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11' . + + val7 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. Examples: + *SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and *SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11' . + + val8 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. Examples: + *SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and *SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11' . + + val9 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. Examples: + *SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and *SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11' . + + val10 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. Examples: + *SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and *SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11' . + + Notes + ----- + Assigns values to user-named parameters that can be substituted later in the run. The equivalent + (and recommended) format is ``Par`` = ``VALUE``, ``VAL2``, ``VAL3``, ..., ``VAL10`` + + which can be used in place of :ref:`starset`, ``Par``, ... for convenience. This command is valid in any processor. + Parameters (numeric or character) can be scalars (single valued) or arrays (multiple valued in one, + two, or three dimensions). An unlimited number of parameter names can be defined in any run. For + very large numbers of parameters, it is most efficient to define them in alphabetical order. + + Parameter values can be redefined at any time. Array parameters can also be assigned values within a + do-loop ( ``\*DO`` ) for convenience. Internally programmed do-loop commands are also available with + the **\*V** ``XX`` commands ( :ref:`vfill` ). Parameter values (except for parameters ending in an + underscore) can be listed with the :ref:`starstatus` command, displayed via :ref:`starvplot` + (numeric parameters only), and modified via ``\*VEDIT`` (numeric parameters only). + + Older program-provided macro files can use parameter names that do not begin with an underscore. + Using these macros embedded in your own macros may cause conflicts if the same parameter names are + used. + + Parameters can also be resolved in comments created via :ref:`com`. A parameter can be deleted by + redefining it with a blank ``VALUE``. If the parameter is an array, the entire array is deleted. + Parameters can also be defined by a response to a query via ``\*ASK`` or from a Mechanical APDL- + provided value via :ref:`get`. + + Array parameters must be dimensioned ( :ref:`dim` ) before being assigned values unless they are the + result of an array operation or defined using the implied loop convention. + + Undefined scalar parameters are initialized to a near-zero value. Numeric array parameters are + initialized to zero when dimensioned, and character array parameters are initialized to blank. + + An existing array parameter must be deleted before it can be redimensioned. + + Array parameter names must be followed by a subscript list (enclosed in parentheses) identifying the + element of the array. The subscript list can have one, two, or three values (separated by commas). + Typical array parameter elements are A(1,1), NEW_VAL(3,2,5), RESULT(1000). Subscripts for defining + an array element must be integers (or parameter expressions that evaluate to integers). Non-integer + values are rounded to the nearest integer value. + + All array parameters are stored as 3D arrays with the unspecified dimensions set to 1. For example, + the 4th array element of a 1-dimensional array, A(4), is stored as array element A(4,1,1). + + Arrays adhere to standard FORTRAN conventions. + + If the parameter name ``Par`` is input in a numeric argument of a command, the numeric value of the + parameter (as assigned with :ref:`starset`, :ref:`get`, =, etc.) is substituted into the command + at that point. Substitution occurs only if the parameter name is used between blanks, commas, + parentheses, or arithmetic operators (or any combination) in a numeric argument. Substitution can be + prevented by enclosing the parameter name ``Par`` within single quotes ( ' ), if the parameter is + alone in the argument; if the parameter is part of an arithmetic expression, the entire expression + must be enclosed within single quotes to prevent substitution. In either case the character string + will be used instead of the numeric value (and the string will be taken as 0.0 if it is in a numeric + argument). + + A forced substitution is available in the text fields of :ref:`title`, :ref:`stitle`, + :ref:`tlabel`, :ref:`an3d`, :ref:`syp` ( ``ARG1`` -- ``ARG8`` ), and :ref:`abbr` by enclosing the + parameter within percent (%) signs. Also, parameter substitution can be forced within the file name + or extension fields of commands having these fields by enclosing the parameter within percent (%) + signs. Array parameters ( :ref:`dim` ) must include a subscript (within parentheses) to identify the + array element whose value is to be substituted, such as A(1,3). Out-of-range subscripts result in an + error message. Non-integer subscripts are allowed when identifying a TABLE array element for + substitution. A proportional linear interpolation of values among the nearest array elements is + performed before substitution. Interpolation is done in all three dimensions. + + Interpolation is based upon the assigned index numbers which must be defined when the table is + filled ( :ref:`dim` ). + + Most alphanumeric arguments permit the use of character parameter substitution. When the parameter + name ``Par`` input, the alphanumeric value of the parameter is substituted into the command at that + point. Substitution can be suppressed by enclosing the parameter name within single quotes ( ' ). + Forced substitution is available in some fields by enclosing the parameter name within percent (%) + signs. Valid forced substitution fields include command name fields, ``Fname`` (filename) or ``Ext`` + (extension) arguments, :ref:`abbr` command ( ``Abbr`` arguments), :ref:`title` and :ref:`stitle` + commands ( ``Title`` argument) and :ref:`tlabel` command ( ``Text`` argument). Character parameter + substitution is also available in the ``\*ASK``, :ref:`an3d`, :ref:`cfwrite`, ``\*IF``, + ``\*ELSEIF``, :ref:`msg`, :ref:`starset`, :ref:`use`, :ref:`vread`, and :ref:`vwrite` commands. + Character array parameters must include a subscript (within parentheses) to identify the array + element whose value is to be substituted. + + If a parameter operation expression is input in a numeric argument, the numeric value of the + expression is substituted into the command + at that point. Allowable operation expressions are of the form E1oE2oE3 ...oE10 + + where E1, E2, etc. are expressions connected by operators (o). The allowable operations (o) are + - + * / ** < > + + For example, A+B**C/D\*E is a valid operation expression. The * represents multiplication and the ** + represents exponentiation. + + Exponentiation of a negative number (without parentheses) to an integer power follows standard + FORTRAN hierarchy conventions; that is, the positive number is exponentiated and then the sign is + attached. Thus, -4**2 is evaluated as -16. If parentheses are applied, such as (-4)**2, the result + is 16. + + A parameter is evaluated as a number within parentheses before exponentiation. Exponentiation of a + negative number to a non-integer power is performed by exponentiating the positive number and + prepending the minus sign, for example, -4**2.3 is -(4**2.3). The < and > operators allow + conditional substitution. For example, E1`_ + Parameters ---------- - lab - Read operation. + par : str + Specifies the parameter or sets of parameters listed. For array parameters, use ``IMIN``, ``IMAX``, etc. to specify ranges. Use :ref:`dim` to define array parameters. Use ``\*VEDIT`` to review array parameters interactively. Use :ref:`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) ( :ref:`use` ). - NEW - Replace current parameter set with these parameters (default). + The following are possible values for ``Par`` - CHANGE - Extend current parameter set with these - parameters, replacing any that already exist. + * ```` - Lists all parameters (except local macro parameters and those with names beginning or + ending with an underbar) and toolbar abbreviations. - 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. + * ``_PRM`` - Lists only parameters with names beginning with an underbar (_). These are Mechanical APDL + internal parameters. - The file name defaults to Jobname. + * ``PRM_`` - 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. - ext - Filename extension (eight-character maximum). The - extension defaults to PARM if Fname is blank. + * ``ABBR`` - Lists all toolbar abbreviations. - Examples - -------- - Read a local parameter file. + * ``PARM`` - Lists all parameters (except local macro parameters and those with names beginning or + ending with an underbar). - >>> mapdl.parres('parm.PARM') + * ``MATH`` - Lists all APDL Math parameters, including vectors, matrices, and linear solvers. - """ - return self.run(f"PARRES, {lab}, {fname}, {ext}") + * ``PARNAME`` - Lists only the parameter specified. ``PARNAME`` cannot be a local macro parameter + name. - def parsav(self, lab="", fname="", ext="", **kwargs): - """Writes parameters to a file. + * ``ARGX`` - Lists all local macro parameter values (ARG1- AR99) that are non-zero or non-blank. - APDL Command: PARSAV + imin : str + 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 + :ref:`taxis` command to list index numbers of 4- and 5-D tables. - Parameters - ---------- - lab - Write operation: + imax : str + 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 + :ref:`taxis` command to list index numbers of 4- and 5-D tables. - - ``'SCALAR'`` : Write only scalar parameters (default). - - ``'ALL'`` : Write scalar and array parameters. - Parameters may be numeric or alphanumeric. + jmin : str + 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 + :ref:`taxis` command to list index numbers of 4- and 5-D tables. - 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. + jmax : str + 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 + :ref:`taxis` command to list index numbers of 4- and 5-D tables. - ext - Filename extension (eight-character maximum). + kmin : str + 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 + :ref:`taxis` command to list index numbers of 4- and 5-D tables. + + kmax : str + 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 + :ref:`taxis` command to list index numbers of 4- and 5-D tables. + + lmin : str + 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 + :ref:`taxis` command to list index numbers of 4- and 5-D tables. + + lmax : str + 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 + :ref:`taxis` command to list index numbers of 4- and 5-D tables. + + mmin : str + 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 + :ref:`taxis` command to list index numbers of 4- and 5-D tables. + + mmax : str + 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 + :ref:`taxis` command to list index numbers of 4- and 5-D tables. + + kpri : int or str + Use this field to list your primary variable labels (X, Y, Z, TIME, etc.). + + * ``1`` - List the labels (default). YES, Y, or ON are also valid entries. + + * ``0`` - Do not list the labels. NO, N, or OFF are also valid entries. Notes ----- - Writes the current parameters to a coded file. Previous - parameters on this file, if any, will be overwritten. The - parameter file may be read with the PARRES command. - - PARSAV/PARRES operations truncate some long decimal strings, - and can cause differing values in your solution data when - other operations are performed. A good practice is to limit - the number of decimal places you will use before and after - these operations. + You cannot obtain the value for a single local parameter (for example, :ref:`starstatus` ,ARG2). You + can only request all local parameters simultaneously using :ref:`starstatus` ,ARGX. This command is valid in any processor. """ - command = f"PARSAV,{lab},{fname},{ext}" + command = f"*STATUS,{par},{imin},{imax},{jmin},{jmax},{kmin},{kmax},{lmin},{lmax},{mmin},{mmax},{kpri}" return self.run(command, **kwargs) - def starset( - self, - par="", - value="", - val2="", - val3="", - val4="", - val5="", - val6="", - val7="", - val8="", - val9="", - val10="", - **kwargs, + def tread( + self, par: str = "", fname: str = "", ext: str = "", nskip: str = "", **kwargs ): - """Assigns values to user-named parameters. + r"""Reads data from an external file into a table array parameter. - APDL Command: ``*SET`` + Mechanical APDL Command: `\*TREAD `_ Parameters ---------- - par - An alphanumeric name used to identify this parameter. Par may be - up to 32 characters, beginning with a letter and containing only - letters, numbers, and underscores. Examples: ABC A3X TOP_END. - ANSYS command names, function names, label names, component and - assembly names, etc., should not be used. Parameter names - beginning with an underscore (e.g., _LOOP) are reserved for use by - ANSYS and should be avoided. Parameter names ending in an - underscore are not listed by the ``*STATUS`` command. Array parameter - names must be followed by a subscript, and the entire expression - must be 32 characters or less. Examples: A(1,1) NEW_VAL(3,2,5) - RESULT(1000). There is no character parameter substitution for the - Par field. Table parameters that are used in command fields (where - constant values are normally given) are limited to 32 characters. - - value - Numerical value or alphanumeric character string (up to 32 - characters enclosed in single quotes) to be assigned to this - parameter. Examples: A(1,3)=7.4 B='ABC3'. May also be a - parameter or a parametric expression. Examples: C=A(1,3) - A(2,2)=(C+4)/2. If blank, delete this parameter. Example: A= - deletes parameter A. - - val2, val3, val4, val5, val6, val7, val8, val9, val10 - If Par is an array parameter, values VAL2 through VAL10 (up to the - last nonblank value) are sequentially assigned to the succeeding - array elements of the column. Example: ``*SET,A(1,4),10,11`` assigns - ``A(1,4)=10, A(2,4)=11``. ``*SET,B(2,3),'file10','file11'`` assigns - ``B(2,3)='file10', B(3,3)='file11'``. + par : str + Table array parameter name as defined by the :ref:`dim` command. - Notes - ----- - Assigns values to user-named parameters that may be substituted later - in the run. The equivalent (and recommended) format is + 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. File name has no default. - ``Par = VALUE,VAL2,VAL3, . . . , VAL10`` + ext : str + Filename extension (eight-character maximum). Extension has no default. - which may be used in place of ``*SET,Par, : ...`` for convenience. + nskip : str + Number of comment lines at the beginning of the file being read that will be skipped during the + reading. Default = 0. - This command is valid in any processor. + Notes + ----- + Use this command to read in a table of data from an external file into a table array parameter. The + external file may be created using a text editor or by an external application or program. To be + used by :ref:`tread`, the external file's encoding format must be UTF-8, and the file must be in + tab-delimited, blank-delimited, or comma-delimited format. The TABLE type array parameter must be + defined before you can read in an external file. See :ref:`dim` for more information. - Parameters (numeric or character) may be scalars (single valued) or - arrays (multiple valued in one, two, or three dimensions). An unlimited - number of parameter names may be defined in any ANSYS run. For very - large numbers of parameters, it is most efficient to define them in - alphabetical order. - - Parameter values may be redefined at any time. Array parameters may - also be assigned values within a do-loop [``*DO``] for convenience. - Internally programmed do-loop commands are also available with the ``*VXX`` - commands (``*VFILL``). Parameter values (except for parameters ending in - an underscore) may be listed with the ``*STATUS`` command, displayed with - the ``*VPLOT`` command (numeric parameters only), and modified with the - ``*VEDIT`` command (numeric parameters only). - - Older ANSYS-supplied macro files may use parameter names that do not - begin with an underscore. Using these macros embedded in your own - macros may cause conflicts if the same parameter names are used. - - Parameters can also be resolved in comments created by the /COM command - (see /COM for complete documentation). A parameter can be deleted by - redefining it with a blank VALUE. If the parameter is an array, the - entire array is deleted. Parameters may also be defined by a response - to a query with the ``*ASK`` command or from an "ANSYS-supplied" value - with the ``*GET`` command. - - Array parameters must be dimensioned [``*DIM``] before being assigned - values unless they are the result of an array operation or defined - using the implied loop convention. Scalar parameters that are not - defined are initialized to a "near" zero value. Numeric array - parameters are initialized to zero when dimensioned, and character - array parameters are initialized to blank. An existing array parameter - must be deleted before it can be redimensioned. Array parameter names - must be followed by a subscript list (enclosed in parentheses) - identifying the element of the array. The subscript list may have one, - two, or three values (separated by commas). Typical array parameter - elements are A(1,1), NEW_VAL(3,2,5), RESULT(1000). Subscripts for - defining an array element must be integers (or parameter expressions - that evaluate to integers). Non-integer values are rounded to the - nearest integer value. All array parameters are stored as 3-D arrays - with the unspecified dimensions set to 1. For example, the 4th array - element of a 1-dimensional array, A(4), is stored as array element - A(4,1,1). Arrays are patterned after standard FORTRAN conventions. - - If the parameter name Par is input in a numeric argument of a command, - the numeric value of the parameter (as assigned with ``*SET``, ``*GET``, =, - etc.) is substituted into the command at that point. Substitution - occurs only if the parameter name is used between blanks, commas, - parentheses, or arithmetic operators (or any combination) in a numeric - argument. Substitution can be prevented by enclosing the parameter - name Par within single quotes ( ' ), if the parameter is alone in the - argument; if the parameter is part of an arithmetic expression, the - entire expression must be enclosed within single quotes to prevent - substitution. In either case the character string will be used instead - of the numeric value (and the string will be taken as 0.0 if it is in a - numeric argument). - - A forced substitution is available in the text fields of the /TITLE, - /STITLE, /TLABEL, /AN3D, /SYP (ARG1--ARG8), and ``*ABBR`` commands by - enclosing the parameter within percent (%) signs. Also, parameter - substitution may be forced within the file name or extension fields of - commands having these fields by enclosing the parameter within percent - (%) signs. Array parameters [``*DIM``] must include a subscript (within - parentheses) to identify the array element whose value is to be - substituted, such as A(1,3). Out-of-range subscripts result in an - error message. Non-integer subscripts are allowed when identifying a - TABLE array element for substitution. A proportional linear - interpolation of values among the nearest array elements is performed - before substitution. Interpolation is done in all three dimensions. - - Note:: : Interpolation is based upon the assigned index numbers which - must be defined when the table is filled [``*DIM``]. - - Most alphanumeric arguments permit the use of character - parameter substitution. When the parameter name Par input, - the alphanumeric value of the parameter is substituted into - the command at that point. Substitution can be suppressed by - enclosing the parameter name within single quotes ( ' ). - Forced substitution is available in some fields by enclosing - the parameter name within percent (%) signs. Valid forced - substitution fields include command name fields, Fname - (filename) or Ext (extension) arguments, ``*ABBR`` command - (Abbr arguments), /TITLE and /STITLE commands (Title argument) - and /TLABEL command (Text argument). Character parameter - substitution is also available in the ``*ASK``, /AN3D, - ``*CFWRITE``, ``*IF``, ``*ELSEIF``, ``*MSG``, ``*SET``, - ``*USE``, ``*VREAD``, and ``*VWRITE`` commands. Character array - parameters must include a subscript (within parentheses) to - identify the array element whose value is to be substituted. - - If a parameter operation expression is input in a numeric argument, the - numeric value of the expression is substituted into the command at that - point. Allowable operation expressions are of the form - - ``E1oE2oE3: ...oE10`` - - where E1, E2, etc. are expressions connected by operators (o). The - allowable operations (o) are - - ``+ - * / ** < >`` - - For example, ``A+B**C/D*E`` is a valid operation expression. The ``*`` - represents multiplication and the ``**`` represents exponentiation. + This command is not applicable to 4- or 5-D tables. """ - command = f"*SET,{par},{value},{val2},{val3},{val4},{val5},{val6},{val7},{val8},{val9},{val10}" + command = f"*TREAD,{par},{fname},{ext},,{nskip}" return self.run(command, **kwargs) - def starvget( + def taxis( self, - parr="", - entity="", - entnum="", - item1="", - it1num="", - item2="", - it2num="", - kloop="", + parmloc: str = "", + naxis: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + val7: str = "", + val8: str = "", + val9: str = "", + val10: str = "", **kwargs, ): - """Retrieves values and stores them into an array parameter. + r"""Defines table index numbers. - APDL Command: ``*VGET`` + Mechanical APDL Command: `\*TAXIS `_ Parameters ---------- - parr - The name of the resulting vector array parameter. See ``*SET`` for - name restrictions. + parmloc : str + Name and starting location in the table array parameter for indexing. Indexing occurs along the + axis defined with ``nAxis``. - entity - Entity keyword. Valid keywords are NODE, ELEM, KP, LINE, AREA, - VOLU, etc. as shown for Entity = in the tables below. + naxis : str + Axis along which indexing occurs. Valid labels are: - entnum - The number of the entity (as shown for ENTNUM = in the tables - below). + * ``1`` - Corresponds to Row. Default. - item1 - The name of a particular item for the given entity. Valid items - are as shown in the Item1 columns of the tables below. + * ``2`` - Corresponds to Column. - it1num - The number (or label) for the specified Item1 (if any). Valid - IT1NUM values are as shown in the IT1NUM columns of the tables - below. Some Item1 labels do not require an IT1NUM value. + * ``3`` - Corresponds to Plane. - item2, it2num - A second set of item labels and numbers to further qualify the item - for which data is to be retrieved. Most items do not require this - level of information. + * ``4`` - Corresponds to Book. - kloop - Field to be looped on: + * ``5`` - Corresponds to Shelf. + + * ``ALL`` - Lists all index numbers. Valid only if ``Val1`` = LIST. + + val1 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. + + To list the index values specified with ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, + ``Val2`` - ``Val10`` are ignored. + + val2 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. + + To list the index values specified with ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, + ``Val2`` - ``Val10`` are ignored. + + val3 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. + + To list the index values specified with ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, + ``Val2`` - ``Val10`` are ignored. + + val4 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. + + To list the index values specified with ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, + ``Val2`` - ``Val10`` are ignored. + + val5 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. - ``0`` or ``2`` : Loop on the ENTNUM field (default). + To list the index values specified with ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, + ``Val2`` - ``Val10`` are ignored. - ``3`` : Loop on the Item1 field. + val6 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. - ``4`` : Loop on the IT1NUM field. Successive items are as shown with IT1NUM. + To list the index values specified with ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, + ``Val2`` - ``Val10`` are ignored. - ``5`` : Loop on the Item2 field. + val7 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. - ``6`` : Loop on the IT2NUM field. Successive items are as shown with IT2NUM. + To list the index values specified with ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, + ``Val2`` - ``Val10`` are ignored. + + val8 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. + + To list the index values specified with ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, + ``Val2`` - ``Val10`` are ignored. + + val9 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. + + To list the index values specified with ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, + ``Val2`` - ``Val10`` are ignored. + + val10 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. + + To list the index values specified with ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, + ``Val2`` - ``Val10`` are ignored. Notes ----- - Retrieves values for specified items and stores the values in an output - vector of a user-named array parameter according to: - - ``ParR = f(Entity, ENTNUM, Item1, IT1NUM, Item2, IT2NUM)`` - - where (f) is the ``*GET`` function; Entity, Item1, and Item2 - are keywords; and ENTNUM, IT1NUM, and IT2NUM are numbers or - labels corresponding to the keywords. Looping continues over - successive entity numbers (ENTNUM) for the KLOOP default. For - example, ``*VGET,A(1),ELEM,5,CENT,X`` returns the centroid - x-location of element 5 and stores the result in the first - location of A. Retrieving continues with element 6, 7, 8, - etc., regardless of whether the element exists or is selected, - until successive array locations are filled. Use ``*VLEN`` or - ``*VMASK`` to skip locations. Absolute values and scale - factors may be applied to the result parameter [``*VABS``, - ``*VFACT``]. Results may be cumulative [``*VCUM``]. See the - ``*VOPER`` command for general details. Results can be put - back into an analysis by writing a file of the desired input - commands with the ``*VWRITE`` command. See also the ``*VPUT`` - command. + :ref:`taxis` is a convenient method to define table index values. These values reside in the zero + column, row, etc. Instead of filling values in these zero location spots, use the :ref:`taxis` + command. For example, - Both ``*GET`` and ``*VGET`` retrieve information from the - active data stored in memory. The database is often the - source, and sometimes the information is retrieved from common - memory blocks that ANSYS uses to manipulate - information. Although POST1 and POST26 operations use a ``*.rst`` - file, GET data is accessed from the database or from the - common blocks. Get operations do not access the ``*.rst`` file - directly. + .. code:: apdl - The ``*VGET`` command retrieves both the unprocessed real and the imaginary - parts (original and duplicate sector nodes and elements) of a cyclic - symmetry solution. + *TAXIS,longtable(1,4,1,1),2,1.0,2.2,3.5,4.7,5.9 - For each of the sections for accessing ``*VGET`` parameters see: - https://www.mm.bme.hu/~gyebro/files/ans_help_v182/ans_cmd/Hlp_C_VGET_st.html + would fill index values 1.0, 2.2, 3.5, 4.7, and 5.9 in ``nAxis`` 2 (column location), starting at + location 4. - This command is valid in any processor. + To list index numbers, issue :ref:`taxis`, ``ParmLoc``, ``nAxis``, LIST, where ``nAxis`` = 1 + through 5 or ALL. """ - command = ( - f"*VGET,{parr},{entity},{entnum},{item1},{it1num},{item2},{it2num},{kloop}" - ) + command = f"*TAXIS,{parmloc},{naxis},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8},{val9},{val10}" return self.run(command, **kwargs) - def taxis( + def vread( self, - parmloc="", - naxis="", - val1="", - val2="", - val3="", - val4="", - val5="", - val6="", - val7="", - val8="", - val9="", - val10="", + parr: str = "", + fname: str = "", + ext: str = "", + label: str = "", + n1: str = "", + n2: str = "", + n3: str = "", + nskip: str = "", **kwargs, ): - """Defines table index numbers. + r"""Reads data and produces an array parameter vector or matrix. - APDL Command: ``*TAXIS`` + Mechanical APDL Command: `\*VREAD `_ Parameters ---------- - parmloc - Name and starting location in the table array parameter for - indexing. Indexing occurs along the axis defined with nAxis. + parr : str + The name of the resulting array parameter vector. See :ref:`starset` for name restrictions. The + parameter must exist as a dimensioned array ( :ref:`dim` ). String arrays are limited to a + maximum of 8 characters. + + 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. If the ``Fname`` field is left blank, reading + continues from the current input device, such as the terminal. + + ext : str + Filename extension (eight-character maximum). - naxis - Axis along which indexing occurs. Valid labels are: + label : str + Can take a value of IJK, IKJ, JIK, JKI, KIJ, KJI, or blank (IJK). - Corresponds to Row. Default. - Corresponds to Column. + n1 : str + Read as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n2`` and + ``n3`` default to 1. - Corresponds to Plane. - Corresponds to Book. + n2 : str + Read as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n2`` and + ``n3`` default to 1. - Corresponds to Shelf. - Lists all index numbers. Valid only if Val1 = LIST. + n3 : str + Read as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n2`` and + ``n3`` default to 1. - val1, val2, val3, . . . , val10 - Values of the index numbers for the axis nAxis, starting from the - table array parameter location ParmLoc. You can define up to ten - values. + nskip : str + Number of lines at the beginning of the file being read that will be skipped during the reading. + Default = 0. Notes ----- - ``*TAXIS`` is a convenient method to define table index values. These - values reside in the zero column, row, etc. Instead of filling values - in these zero location spots, use the ``*TAXIS`` command. + Reads data from a file and fills in an array parameter vector or matrix. Data are read from a + formatted file or, if the menu is off ( :ref:`menu` ,OFF) and ``Fname`` is blank, from the next + input lines. The format of the data to be read must be input immediately following the :ref:`vread` + command. The format specifies the number of fields to be read per record, the field width, and the + placement of the decimal point (if none specified in the value). The read operation follows the + available FORTRAN FORMAT conventions of the system (see your system FORTRAN manual). Any standard + FORTRAN real format (such as (4F6.0), (E10.3,2X,D8.2), etc.) or alphanumeric format (A) may be used. + Alphanumeric + strings are limited to a maximum of 8 characters for any field (A8). For storage of string arrays + greater than 8 characters, the \*SREAD command can be used. Integer (I) and list-directed (\2) + descriptors may not be used. The parentheses must be included in the format and the format must not + exceed 80 characters (including parentheses). The input line length is + limited to 128 characters. + + A starting array element number must be defined for the result array parameter vector (numeric or + character). For example, entering these two lines: + + .. code:: apdl + + *VREAD,A(1),ARRAYVAL + (2F6.0) + + will read two values from each line of file ARRAYVAL and assign the values to A(1), A(2), A(3), etc. + Reading continues until successive row elements ( :ref:`vlen`, :ref:`vmask`, :ref:`dim` ) are + filled. + + For an array parameter matrix, a starting array element row and column number must be defined. For + example, entering these two lines: + + .. code:: apdl + + *VREAD,A(1,1),ARRAYVAL,,,IJK,10,2 + (2F6.0) + + will read two values from each line of file ARRAYVAL and assign the values to A(1,1), A(2,1), + A(3,1), etc. Reading continues until ``n1`` (10) successive row elements are filled. Once the + maximum row number is reached, subsequent data will be read into the next column (for example, + A(1,2), A(2,2), A(3,2), etc.) - To list index numbers, issue ```*TAXIS,ParmLoc, nAxis, LIST,`` where - nAxis = 1 through 5 or ALL. + For numerical parameters, absolute values and scale factors may be applied to the result parameter ( + :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). See the :ref:`voper` + command for details. If you are in the GUI the :ref:`vread` command must be contained in an + externally prepared file read into Mechanical APDL (that is, :ref:`use`, :ref:`input`, etc.). + + This command is not applicable to 4- or 5-D arrays. + + This command is valid in any processor. """ - command = f"*TAXIS,{parmloc},{naxis},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8},{val9},{val10}" + command = f"*VREAD,{parr},{fname},{ext},,{label},{n1},{n2},{n3},{nskip}" return self.run(command, **kwargs) - def tread(self, par="", fname="", ext="", nskip="", **kwargs): - """Reads data from an external file into a table array parameter. + def starvget( + self, + parr: str = "", + entity: str = "", + entnum: str = "", + item1: str = "", + it1num: str = "", + item2: str = "", + it2num: str = "", + kloop: str = "", + **kwargs, + ): + r"""Retrieves values and stores them into an array parameter. - APDL Command: ``*TREAD`` + Mechanical APDL Command: `\*VGET `_ Parameters ---------- - par - Table array parameter name as defined by the ``*DIM`` command. + parr : str + The name of the resulting vector array parameter. See :ref:`starset` for name restrictions. The + program creates the array parameter if it does not exist. - 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. + entity : str + Entity keyword. Valid keywords are NODE, ELEM, KP, LINE, AREA, VOLU, etc. as shown for + ``Entity`` = in the tables below. - ext - Filename extension (eight-character maximum). + entnum : str + The number of the entity (as shown for ``ENTNUM`` = in the tables below). + + item1 : str + The name of a particular item for the given entity. Valid items are as shown in the ``Item1`` + columns of the tables below. + + it1num : str + The number (or label) for the specified ``Item1`` (if any). Valid ``IT1NUM`` values are as shown + in the ``IT1NUM`` columns of the tables below. Some ``Item1`` labels do not require an + ``IT1NUM`` value. + + item2 : str + A second set of item labels and numbers to further qualify the item for which data is to be + retrieved. Most items do not require this level of information. - nskip - Number of comment lines at the beginning of the file being read - that will be skipped during the reading. Default = 0. + it2num : str + A second set of item labels and numbers to further qualify the item for which data is to be + retrieved. Most items do not require this level of information. + + kloop : str + Field to be looped on: + + * ``0 or 2`` - Loop on the ``ENTNUM`` field (default). + + * ``3`` - Loop on the ``Item1`` field. + + * ``4`` - Loop on the ``IT1NUM`` field. Successive items are as shown with ``IT1NUM``. + + * ``5`` - Loop on the ``Item2`` field. + + * ``6`` - Loop on the ``IT2NUM`` field. Successive items are as shown with ``IT2NUM``. Notes ----- - Use this command to read in a table of data from an external file into - an ANSYS table array parameter. The external file may be created using - a text editor or by an external application or program. The external - file must be in tab-delimited, blank-delimited, or comma-delimited - format to be used by ``*TREAD``. The ANSYS TABLE type array parameter must - be defined before you can read in an external file. See ``*DIM`` for more - information. + Retrieves values for specified items and stores the values in an output vector of a user-named array + parameter according to: ``ParR`` = f( ``Entity``, ``ENTNUM``, ``Item1``, ``IT1NUM``, ``Item2``, + ``IT2NUM`` ) + + where (f) is the :ref:`get` function; ``Entity``, ``Item1``, and ``Item2`` are keywords; and + ``ENTNUM``, ``IT1NUM``, and ``IT2NUM`` are numbers or labels corresponding to the keywords. + Looping continues over successive entity numbers ( ``ENTNUM`` ) for the ``KLOOP`` default. For + example, :ref:`starvget`,A(1),ELEM,5,CENT,X returns the centroid x-location of element 5 and stores + the result in the first location of A. Retrieving continues with element 6, 7, 8, etc., regardless + of whether the element exists or is selected, until successive array locations are filled. Use + :ref:`vlen` or :ref:`vmask` to skip locations. Absolute values and scale factors may be applied to + the result parameter ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). See + the :ref:`voper` command for general details. Results can be put back into an analysis by writing a + file of the desired input commands with the :ref:`vwrite` command. See also the :ref:`starvput` + command. - This command is not applicable to 4- or 5-D tables. + Both :ref:`get` and :ref:`starvget` retrieve information from the active data stored in memory. The + database is often the source, and sometimes the information is retrieved from common memory blocks + that Mechanical APDL uses to manipulate information. Although POST1 and POST26 operations use a + ``\2.rst`` file, GET data is accessed from the database or from the common blocks. Get operations do + not access the ``\2.rst`` file directly. + + The :ref:`starvget` command retrieves both the unprocessed real and the imaginary parts (original + and duplicate sector nodes and elements) of a `cyclic symmetry + `_ solution. + + Each of the sections for accessing \*VGET parameters are shown in the following order: + + `\*VGET PREP7 Items + `_ + `\*VGET POST1 Items + `_ + + This command is valid in any processor. """ - command = f"*TREAD,{par},{fname},{ext},,{nskip}" + command = ( + f"*VGET,{parr},{entity},{entnum},{item1},{it1num},{item2},{it2num},{kloop}" + ) return self.run(command, **kwargs) def vfill( self, - parr="", - func="", - con1="", - con2="", - con3="", - con4="", - con5="", - con6="", - con7="", - con8="", - con9="", - con10="", + parr: str = "", + func: str = "", + con1: str = "", + con2: str = "", + con3: str = "", + con4: str = "", + con5: str = "", + con6: str = "", + con7: str = "", + con8: str = "", + con9: str = "", + con10: str = "", **kwargs, ): - """Fills an array parameter. + r"""Fills an array parameter. - APDL Command: ``*VFILL`` + Mechanical APDL Command: `\*VFILL `_ Parameters ---------- - parr - The name of the resulting numeric array parameter vector. See ``*SET`` - for name restrictions. + parr : str + The name of the resulting numeric array parameter vector. See :ref:`starset` for name + restrictions. - func + func : str Fill function: - DATA - Assign specified values CON1, CON2, etc. to successive - array elements. Up to 10 assignments may be made at a - time. Any CON values after a blank CON value are - ignored. - Assign ramp function values: ``CON1+((n-1)*CON2)`` - , where n is the loop number [``*VLEN``]. To specify a - constant function (no ramp), set CON2 to zero. - - RAMP - Assign random number values based on a uniform - distribution RAND(CON1,CON2), where: - Assign random - sample of Gaussian distributions GDIS(CON1,CON2). - - RAND - Assign random number values based on a uniform - distribution RAND(CON1,CON2), where CON1 is the lower - bound (defaults to 0.0) and CON2 is the upper bound - (defaults to 1.0) - - GDIS - Assign random sample of Gaussian distributions - GDIS(CON1,CON2) where CON1 is the mean (defaults to 0.0), - and CON2 is the standard deviation (defaults to 1.0) - - TRIA - Assigns random number values based on a triangular - distribution TRIA(CON1,CON2,CON3) where CON1 is the lower - bound (defaults to 0.0), CON2 is the location of the peak - value (CON1 ≤ CON2 ≤CON3; CON2 defaults to 0 if CON1 ≤ 0 ≤ - CON3, CON1 if 0 ≤ CON1, or CON3 if CON3 ≤ 0), and CON3 is - the upper bound (defaults to 1.0 + CON1 if CON1 ≥ 0 or 0.0 - if CON1 ≤ 0) - - BETA - Assigns random number values based on a beta - distribution BETA(CON1,CON2,CON3,CON4) where: CON1 is the - lower bound (defaults to 0.0), CON2 is the upper bound - (defaults to 1.0 + CON1 if CON1 ≥ 0 or 0.0 if CON1 ≤ 0), and CON3 - and CON4 are the alpha and beta parameters, respectively, - of the beta function. Alpha and beta must both be - positive; they default to 1.0. - - GAMM - Assigns random number values based on a gamma - distribution: GAMM(CON1,CON2,CON3) where: CON1 is the - lower bound (defaults to 0.0), CON2 and CON3 are the alpha - and beta parameters, respectively, of the gamma - function. Alpha and beta must both be positive; they - default to 1.0. - - RIGID - Generates the rigid body modes with respect to the - reference point coordinates (CON1, CON2, CON3). The - dimensions of the array parameter ParR are (dim1,dim2) - where dim1 is the maximum node number (including internal - nodes but excluding orientation nodes) multiplied by the - number of degrees of freedom, and dim2 is the number of - rigid body modes (which corresponds to the number of - structural degrees of freedom). - - CLUSTER - Generates excitation frequencies with clustering - option CLUSTER(CON1,CON2,CON3,CON4,%CON5%) where: - - - CON1 is the lower end of the frequency range in Hz (0 < CON1) - - CON2 is the upper end of the frequency range in Hz (CON1 < CON2) - - CON3 is the number of points on each side of the natural - frequency (4 ≤ CON3 ≤ 20, defaults to 4) - - CON4 is the constant damping ratio value or an array - parameter (size NFR) specifying the damping ratios (if - zero or blank, defaults to constant damping ratio of - 0.005) - - CON5 is an array parameter (size NFR) specifying the - natural frequencies in Hz - - The dimension of the resulting array parameter ParR is - less than ``2+NFR*(2*CON3+1)`` where NFR is the number of - natural frequencies defined in CON5. - - con1, con2, con3, . . . , con10 + * ``DATA`` - Assign specified values ``CON1``, ``CON2``, etc. to successive array elements. Up + to 10 assignments may be made at a time. Any CON values after a blank CON value are ignored. + + * ``RAMP`` - Assign ramp function values: ``CON1`` +((n-1)* ``CON2`` ), where n is the loop number + ( :ref:`vlen` ). To specify a constant function (no ramp), set ``CON2`` to zero. + + * ``RAND`` - Assign random number values based on a uniform distribution RAND( ``CON1``, ``CON2`` + ), where: + + ``CON1`` is the lower bound (defaults to 0.0) ``CON2`` is the upper bound (defaults to 1.0) + + * ``GDIS`` - Assign random sample of Gaussian distributions GDIS( ``CON1``, ``CON2`` ) where: + + ``CON1`` is the mean (defaults to 0.0) ``CON2`` is the standard deviation (defaults to 1.0) + + * ``TRIA`` - Assigns random number values based on a triangular distribution TRIA( ``CON1``, + ``CON2``, ``CON3`` ) where: + + ``CON1`` is the lower bound (defaults to 0.0) ``CON2`` is the location of the peak value ( + ``CON1`` ≤ ``CON2`` ≤ ``CON3`` ; ``CON2`` defaults to 0 if ``CON1`` ≤ 0 ≤ ``CON3``, ``CON1`` if + 0 ≤ ``CON1``, or ``CON3`` if ``CON3`` ≤ 0) ``CON3`` is the upper bound (defaults to 1.0 + + ``CON1`` if ``CON1`` ≥ 0 or 0.0 if ``CON1`` ≤ 0) + + * ``BETA`` - Assigns random number values based on a beta distribution BETA( ``CON1``, ``CON2``, + ``CON3``, ``CON4`` ) where: + + ``CON1`` is the lower bound (defaults to 0.0) ``CON2`` is the upper bound (defaults to 1.0 + + ``CON1`` if ``CON1`` ≥ 0 or 0.0 if ``CON1`` ≤ 0) ``CON3`` and ``CON4`` are the alpha and beta + parameters, respectively, of the beta function. Alpha and beta must both be positive; they + default to 1.0. + + * ``GAMM`` - Assigns random number values based on a gamma distribution: GAMM( ``CON1``, ``CON2`` + , ``CON3`` ) where: + + ``CON1`` is the lower bound (defaults to 0.0) ``CON2`` and ``CON3`` are the alpha and beta + parameters, respectively, of the gamma function. Alpha and beta must both be positive; they + default to 1.0. + + * ``RIGID`` - Generates the rigid body modes with respect to the reference point coordinates ( + ``CON1``, ``CON2``, ``CON3`` ). The dimensions of the array parameter ``ParR`` are (dim 1 ,dim + 2 ) where dim 1 is the maximum node number (including internal nodes but excluding orientation + nodes ) multiplied by the number of degrees of freedom, and dim 2 is the number of rigid body + modes (which corresponds to the number of structural degrees of freedom). + + * ``CLUSTER`` - Generates excitation frequencies with clustering option CLUSTER( ``CON1``, + ``CON2``, ``CON3``, ``CON4``, ``%CON5%`` ) where: + + ``CON1`` is the lower end of the frequency range in Hz (0 < ``CON1`` ) ``CON2`` is the upper end + of the frequency range in Hz ( ``CON1`` < ``CON2`` ) ``CON3`` is the number of points on each + side of the natural frequency (4 ≤ ``CON3`` ≤ 20, defaults to 4) ``CON4`` is the constant + damping ratio value or an array parameter (size NFR) specifying the damping ratios (if zero or + blank, defaults to constant damping ratio of 0.005) ``CON5`` is an array parameter (size NFR) + specifying the natural frequencies in Hz The dimension of the resulting array parameter ParR is + less than 2+NFR\2(2* ``CON3`` +1) where NFR is the number of natural frequencies defined in + ``CON5``. + + con1 : str + Constants used with above functions. + + con2 : str + Constants used with above functions. + + con3 : str + Constants used with above functions. + + con4 : str + Constants used with above functions. + + con5 : str + Constants used with above functions. + + con6 : str + Constants used with above functions. + + con7 : str + Constants used with above functions. + + con8 : str + Constants used with above functions. + + con9 : str + Constants used with above functions. + + con10 : str Constants used with above functions. Notes ----- - Operates on input data and produces one output array parameter vector - according to: - - ParR = f(CON1, CON2, : ...) + Operates on input data and produces one output array parameter vector according to: ``ParR`` = f( + ``CON1``, ``CON2``, ...) - where the functions (f) are described above. Operations use successive - array elements [``*VLEN``, ``*VMASK``] with the default being all successive - elements. For example, ``*VFILL,A,RAMP,1,10`` assigns A(1) = 1.0, A(2) = - 11.0, A(3) = 21.0, etc. ``*VFILL,B(5,1),DATA,1.5,3.0`` assigns ``B(5,1) = - 1.5 and B(6,1) = 3.0``. Absolute values and scale factors may be applied - to the result parameter [``*VABS``, ``*VFACT``]. Results may be cumulative - [``*VCUM``]. See the ``*VOPER`` command for details. + where the functions (f) are described above. Operations use successive array elements ( :ref:`vlen` + , :ref:`vmask` ) with the default being all successive elements. For example, :ref:`vfill` + ,A,RAMP,1,10 assigns A(1) = 1.0, A(2) = 11.0, A(3) = 21.0, etc. :ref:`vfill` ,B(5,1),DATA,1.5,3.0 + assigns B(5,1) = 1.5 and B(6,1) = 3.0. Absolute values and scale factors may be applied to the + result parameter ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). See the + :ref:`voper` command for details. This command is valid in any processor. """ command = f"*VFILL,{parr},{func},{con1},{con2},{con3},{con4},{con5},{con6},{con7},{con8},{con9},{con10}" return self.run(command, **kwargs) - def vread( + def afun(self, lab: str = "", **kwargs): + r"""Specifies units for angular functions in parameter expressions. + + Mechanical APDL Command: `\*AFUN `_ + + Parameters + ---------- + lab : str + Specifies the units to be used: + + * ``RAD`` - Use radians for input and output of parameter angular functions (default). + + * ``DEG`` - Use degrees for input and output of parameter angular functions. + + * ``STAT`` - Show current setting (DEG or RAD) for this command. + + Notes + ----- + Only the SIN, COS, TAN, ASIN, ACOS, ATAN, ATAN2, ANGLEK, and ANGLEN functions ( :ref:`starset` , + :ref:`vfun` ) are affected by this command. + """ + command = f"*AFUN,{lab}" + return self.run(command, **kwargs) + + def dim( self, - parr="", - fname="", - ext="", - label="", - n1="", - n2="", - n3="", - nskip="", + par: str = "", + type_: str = "", + imax: str = "", + jmax: str = "", + kmax: str = "", + var1: str = "", + var2: str = "", + var3: str = "", + csysid: str = "", **kwargs, ): - """Reads data and produces an array parameter vector or matrix. + r"""Defines an array parameter and its dimensions. - APDL Command: ``*VREAD`` + Mechanical APDL Command: `\*DIM `_ Parameters ---------- - parr - The name of the resulting array parameter vector. See ``*SET`` for - name restrictions. The parameter must exist as a dimensioned array - [``*DIM``]. String arrays are limited to a maximum of 8 characters. - - 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). + par : str + Name of parameter to be dimensioned. See :ref:`starset` for name restrictions. - label - Can take a value of IJK, IKJ, JIK, JKI, KIJ, KJI, or blank (IJK). + type_ : str + Array type: + + * ``ARRAY`` - Arrays are similar to standard FORTRAN arrays (indices are integers) (default). + Index numbers for the rows, columns, and planes are sequential values beginning with one. Used + for 1-, 2-, or 3D arrays. + + * ``ARR4`` - Same as ARRAY, but used to specify 4-D arrays. + + * ``ARR5`` - Same as ARRAY, but used to specify 5-D arrays. + + * ``CHAR`` - Array entries are character strings (up to 8 characters each). Index numbers for + rows, columns, and planes are sequential values beginning with one. + + * ``TABLE`` - Array indices are real (non-integer) numbers which must be defined when filling the + table. Index numbers for the rows and columns are stored in the zero column and row "array + elements" and are initially assigned a near-zero value. Index numbers must be in ascending order + and are used only for retrieving an array element. When retrieving an array element with a real + index that does not match a specified index, linear interpolation is done among the nearest + indices and the corresponding array element values ( :ref:`starset` ). Used for 1-, 2-, or 3D + tables. + + * ``TAB4`` - Same as TABLE, but used to specify 4-D tables. + + * ``TAB5`` - Same as TABLE, but used to specify 5-D tables. + + * ``STRING`` - Array entries are character strings (up to IMAX each). Index numbers for columns + and planes are sequential values beginning with 1. Row index is character position in string. + + imax : str + Extent of first dimension (row). (For ``Type`` = STRING, ``IMAX`` is rounded up to the next + multiple of eight and has a limit of 248). Default = 1. + + jmax : str + Extent of second dimension (column). Default = 1. + + kmax : str + Extent of third dimension (plane). Default = 1. + + var1 : str + Variable name corresponding to the first dimension (row) for ``Type`` = TABLE, TAB4, or TAB5. + Default = Row. - n1, n2, n3 - Read as (((ParR (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for - Label = KIJ. n2 and n3 default to 1. + var2 : str + Variable name corresponding to the second dimension (column) for ``Type`` = TABLE, TAB4, or + TAB5. Default = Column. - nskip - Number of lines at the beginning of the file being read that will - be skipped during the reading. Default = 0. + var3 : str + Variable name corresponding to the third dimension (plane) for ``Type`` = TABLE, TAB4, TAB5. + Default = Plane. + + csysid : str + An integer corresponding to the coordinate system ID number. Default = 0 (global Cartesian). Notes ----- - Reads data from a file and fills in an array parameter vector or - matrix. Data are read from a formatted file or, if the menu is off - [/MENU,OFF] and Fname is blank, from the next input lines. The format - of the data to be read must be input immediately following the ``*VREAD`` - command. The format specifies the number of fields to be read per - record, the field width, and the placement of the decimal point (if - none specified in the value). The read operation follows the available - FORTRAN FORMAT conventions of the system (see your system FORTRAN - manual). Any standard FORTRAN real format (such as (4F6.0), - (E10.3,2X,D8.2), etc.) or alphanumeric format (A) may be used. - Alphanumeric strings are limited to a maximum of 8 characters for any - field (A8). For storage of string arrays greater than 8 characters, the - ``*SREAD`` command can be used. Integer (I) and list-directed (*) - descriptors may not be used. The parentheses must be included in the - format and the format must not exceed 80 characters (including - parentheses). The input line length is limited to 128 characters. - - A starting array element number must be defined for the result array - parameter vector (numeric or character). For example, entering these - two lines: - - will read two values from each line of file ARRAYVAL and assign the - values to A(1), A(2), A(3), etc. Reading continues until successive - row elements [``*VLEN``, ``*VMASK``, ``*DIM``] are filled. - - For an array parameter matrix, a starting array element row and column - number must be defined. For example, entering these two lines: - - will read two values from each line of file ARRAYVAL and assign the - values to A(1,1), A(2,1), A(3,1), etc. Reading continues until n1 (10) - successive row elements are filled. Once the maximum row number is - reached, subsequent data will be read into the next column (e.g., - A(1,2), A(2,2), A(3,2), etc.) + Up to three dimensions (row, column, and plane) may be defined using ARRAY and TABLE. Use ARR4, + ARR5, TAB4, and TAB5 to define up to five dimensions (row, column, plane, book, and shelf). An index + number is associated with each row, column, and plane. For array and table type parameters, element + values are initialized to zero. For character and string parameters, element values are initialized + to (blank). A defined parameter must be deleted ( :ref:`starset` ) before its dimensions can be + changed. Scalar (single valued) parameters should not be dimensioned. :ref:`dim`,A,,3 defines a + vector array with elements A(1), A(2), and A(3). :ref:`dim`,B,,2,3 defines a 2x3 array with + elements B(1,1), B(2,1), B(1,2), B(2,2), B(1,3), and B(2,3). Use :ref:`starstatus`, ``Par`` to + display elements of array ``Par``. You can write formatted data files (tabular formatting) from + data held in arrays through the :ref:`vwrite` command. + + If you use table parameters to define boundary conditions, then ``Var1``, ``Var2``, and/or + ``Var3`` can either specify a primary variable (listed in ) or can be an independent parameter. If + specifying an independent parameter, then you must define an additional table for the independent + parameter. The additional table must have the same name as the independent parameter and may be a + function of one or more primary variables or another independent parameter. All independent + parameters must relate to a primary variable. + + Tabular load arrays can be defined in both global Cartesian (default), cylindrical, spherical, or + local (see below) coordinate systems by specifying ``CSYSID``, as defined in :ref:`local`. + Coordinate system ``CSYSID`` must exist prior to issuing the :ref:`dim` command. + + **The following constraints apply when specifying a local coordinate system for your tabular + loads:** + + Only Cartesian, cylindrical and spherical coordinate systems are supported + Angle values for Y in cylindrical or spherical coordinate systems must be input in degrees and must + be positive values between 0 and 360 degrees (0 :math:`` Y :math:`` 360) + Angle values for Z in spherical coordinate system must be input in degrees and must be positive + values between -90 and +90 ( -90 :math:`` Z :math:`` 90) + + If specifying a 4- or 5-D array or table, four additional fields ( ``LMAX``, ``MMAX``, ``Var4``, + and ``Var5`` ) are available. Thus, for a 4-D table, the command syntax would be: + + .. code:: apdl + + *DIM,Par,Type,IMAX,JMAX,KMAX,LMAX,Var1,Var2,Var3,Var4,CSYSID + + For a 5-D table, the command syntax is: + + .. code:: apdl + + *DIM,Par,Type,IMAX,JMAX,KMAX,LMAX,MMAX,Var1,Var2,Var3,Var4,Var5,CSYSID + + You cannot create or edit 4- or 5-D arrays or tables via the GUI. + + For more information, see `Array Parameters + `_ + + **\*DIM - Primary Variables** + + .. flat-table:: + :header-rows: 1 + + * - Primary Variable + - Label for ``Var1, Var2, Var3, Var4, Var5`` + * - Time + - TIME + * - Frequency + - FREQ + * - X-coordinate location + - X + * - Y-coordinate location + - Y + * - Z-coordinate location + - Z + * - Temperature + - TEMP + * - Velocity + - VELOCITY + * - Pressure + - PRESSURE [ ] + * - Geometric gap/penetration + - GAP + * - Cyclic sector number + - SECTOR + * - Amplitude of the rotational velocity vector + - OMEGS + * - Eccentricity + - ECCENT + * - Phase shift + - THETA + * - Element number + - ELEM + * - Node number + - NODE + * - Concentration + - CONC - For numerical parameters, absolute values and scale factors may be - applied to the result parameter [``*VABS``, ``*VFACT``]. Results may be - cumulative [``*VCUM``]. See the ``*VOPER`` command for details. If you are in - the GUI the ``*VREAD`` command must be contained in an externally prepared - file read into the ANSYS program (i.e., ``*USE``, /INPUT, etc.). - This command is not applicable to 4- or 5-D arrays. + Specify PRESSURE as the independent variable (not PRES). + + The X, Y, and Z coordinate locations listed above are valid in global Cartesian, or local + (Cartesian, cylindrical and spherical) coordinate systems. The VELOCITY label is applicable only to + the calculated fluid velocity in element FLUID116 . + + When using PRESSURE as a primary variable, the underlying element must have the pressure DOF + associated with it, or it must be a supported contact element. + + The gap/penetration label (GAP) is only used for defining certain contact element real constants. + + The frequency label (FREQ) is valid for harmonic analyses only. + + The node and element labels (NODE and ELEM) allow you to use node and element numbers as primary + variables, and their axis values should be integers. + + The OMEGS, ECCENT, and THETA primary variables only apply to the COMBI214 element. The amplitude of + the rotational velocity (OMEGS) is an absolute value, so only positive + values of OMEGS are valid. The eccentricity (ECCENT) and phase shift (THETA) labels are only valid + for nonlinear analyses. + + If you use table parameters to define boundary conditions, the table names ( ``Par`` ) must not + exceed 32 characters. + + In thermal analyses, if you apply tabular loads as a function of temperature but the rest of the + model is linear (for example, includes no temperature-dependent material properties or radiation ), + you should turn on Newton-Raphson iterations ( :ref:`nropt`,FULL) to evaluate the temperature- + dependent tabular boundary conditions correctly. This command is valid in any processor. """ - command = f"*VREAD,{parr},{fname},{ext},,{label},{n1},{n2},{n3},{nskip}" + command = ( + f"*DIM,{par},{type_},{imax},{jmax},{kmax},{var1},{var2},{var3},{csysid}" + ) return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/process_controls.py b/src/ansys/mapdl/core/_commands/apdl/process_controls.py index 1225b5cae5..21e7345496 100644 --- a/src/ansys/mapdl/core/_commands/apdl/process_controls.py +++ b/src/ansys/mapdl/core/_commands/apdl/process_controls.py @@ -22,27 +22,40 @@ class ProcessControls: - def wait(self, dtime="", **kwargs): - """APDL Command: /WAIT - Causes a delay before the reading of the next command. + def wait(self, dtime: str = "", **kwargs): + r"""Causes a delay before the reading of the next command. + + Mechanical APDL Command: `/WAIT `_ Parameters ---------- - dtime + dtime : str Time delay (in seconds). Maximum time delay is 59 seconds. Notes ----- - You should consider using ``time.sleep(dtime)`` - - The command following the /WAIT will not be processed until the - specified wait time increment has elapsed. Useful when reading from a - prepared input file to cause a pause, for example, after a display - command so that the display can be reviewed for a period of time. - Another "wait" feature is available via the ``*ASK`` command. + The command following the :ref:`wait` will not be processed until the specified wait time increment + has elapsed. Useful when reading from a prepared input file to cause a pause, for example, after a + display command so that the display can be reviewed for a period of time. Another "wait" feature is + available via the ``\*ASK`` command. This command is valid in any processor. """ command = f"/WAIT,{dtime}" return self.run(command, **kwargs) + + def starexit(self, **kwargs): + r"""Exits a do-loop. + + Mechanical APDL Command: `\*EXIT `_ + + Notes + ----- + The command following the ``\*ENDDO`` is executed next. The exit option may also be conditional [Use + the ``\*IF`` ]. The :ref:`starexit` command must appear on the same file as the ``\*DO`` command. + + This command is valid in any processor. + """ + command = "*EXIT" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/commands.py b/src/ansys/mapdl/core/commands.py index 935284e19d..93c55b323a 100644 --- a/src/ansys/mapdl/core/commands.py +++ b/src/ansys/mapdl/core/commands.py @@ -357,11 +357,12 @@ class PreprocessorCommands( pass -class APDLCommands( +class Apdl( apdl.abbreviations.Abbreviations, - apdl.array_param.ArrayParam, + apdl.array_parameters.ArrayParameters, + apdl.encryption_decryption.EncryptionDecryption, apdl.macro_files.MacroFiles, - apdl.matrix_op.MatrixOP, + apdl.matrix_operations.MatrixOperations, apdl.parameter_definition.ParameterDefinition, apdl.process_controls.ProcessControls, ): @@ -500,7 +501,7 @@ class InqFunctions(inq_func.inq_function): class Commands( - APDLCommands, + Apdl, Aux2Commands, Aux12Commands, DatabaseCommands, diff --git a/src/ansys/mapdl/core/mapdl_core.py b/src/ansys/mapdl/core/mapdl_core.py index 94626cf9c3..444d901fc7 100644 --- a/src/ansys/mapdl/core/mapdl_core.py +++ b/src/ansys/mapdl/core/mapdl_core.py @@ -1569,7 +1569,6 @@ def open_apdl_log( """ if self._apdl_log is not None: raise MapdlRuntimeError("APDL command logging already enabled") - self._log.debug("Opening ANSYS log file at %s", filename) if mode not in ["w", "a", "x"]: diff --git a/tests/test_krylov.py b/tests/test_krylov.py index 9a3c83c456..2cec66114e 100644 --- a/tests/test_krylov.py +++ b/tests/test_krylov.py @@ -35,7 +35,7 @@ PATH = os.path.dirname(os.path.abspath(__file__)) -# Krylov Apdl Macro Files +# Krylov APDL Macro Files lib_path = os.path.join(PATH, "test_files") # Results from APDL Macro to compare with PyMAPDL results