diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 888deef9e0..cc3c8632fd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -33,7 +33,7 @@ env: DPF_PORT: 21004 MAPDL_PACKAGE: ghcr.io/ansys/mapdl ON_CI: True - PYTEST_ARGUMENTS: '-vvv -rxXsa --color=yes --durations=10 --random-order --random-order-bucket=class --maxfail=10 --reruns 3 --reruns-delay 4 --cov=ansys.mapdl.core --cov-report=html' + PYTEST_ARGUMENTS: '-vvv -rxXsa --color=yes --durations=10 --random-order --random-order-bucket=class --maxfail=100 --reruns 3 --reruns-delay 4 --cov=ansys.mapdl.core --cov-report=html' BUILD_CHEATSHEET: True 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..2e79ef12e5 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.ucmd + Abbreviations.abbres + Abbreviations.abbr + Abbreviations.abbsav 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..32f6956deb --- /dev/null +++ b/doc/source/mapdl_commands/apdl/array_parameters.rst @@ -0,0 +1,38 @@ + +.. _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.mfun + ArrayParameters.mwrite + ArrayParameters.moper + ArrayParameters.mfouri + ArrayParameters.sread + ArrayParameters.toper + ArrayParameters.starvplot + ArrayParameters.vmask + ArrayParameters.vcol + ArrayParameters.vscfun + ArrayParameters.vstat + ArrayParameters.voper + ArrayParameters.vwrite + ArrayParameters.vitrp + ArrayParameters.vabs + ArrayParameters.starvput + ArrayParameters.vfun + ArrayParameters.vfact + ArrayParameters.vcum + ArrayParameters.vedit + ArrayParameters.vlen 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..be0ed87bbe --- /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.encrypt + EncryptionDecryption.decrypt + EncryptionDecryption.dbdecrypt + EncryptionDecryption.dbencrypt 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..8b28aa0ac3 100644 --- a/doc/source/mapdl_commands/apdl/macro_files.rst +++ b/doc/source/mapdl_commands/apdl/macro_files.rst @@ -1,35 +1,29 @@ -.. _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.pmacro + MacroFiles.psearch + MacroFiles.ulib + MacroFiles.use + MacroFiles.cfwrite + MacroFiles.cfclos + MacroFiles.cfopen + MacroFiles.create + MacroFiles.msg + MacroFiles.mkdir + MacroFiles.slashtee + MacroFiles.rmdir 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..e9c9f45f6d --- /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.starprint + MatrixOperations.free + MatrixOperations.fft + MatrixOperations.wrk + MatrixOperations.comp + MatrixOperations.nrm + MatrixOperations.merge + MatrixOperations.mult + MatrixOperations.starinquire + MatrixOperations.itengine + MatrixOperations.init + MatrixOperations.export + MatrixOperations.eigen + MatrixOperations.smat + MatrixOperations.starsort + MatrixOperations.scal + MatrixOperations.vec + MatrixOperations.hprod + MatrixOperations.lsengine + MatrixOperations.lsfactor + MatrixOperations.lsrestore + MatrixOperations.lsbac + MatrixOperations.lsdump + MatrixOperations.remove + MatrixOperations.starrename + MatrixOperations.axpy + MatrixOperations.dmat + MatrixOperations.dot diff --git a/doc/source/mapdl_commands/apdl/parameter_definition.rst b/doc/source/mapdl_commands/apdl/parameter_definition.rst index 8a3b7f9171..21d01002e1 100644 --- a/doc/source/mapdl_commands/apdl/parameter_definition.rst +++ b/doc/source/mapdl_commands/apdl/parameter_definition.rst @@ -1,24 +1,31 @@ -.. _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.parres + ParameterDefinition.parsav + ParameterDefinition.get + ParameterDefinition.inquire + ParameterDefinition.starset + ParameterDefinition.starstatus + ParameterDefinition.tread + ParameterDefinition.taxis + ParameterDefinition.vread + ParameterDefinition.starvget + ParameterDefinition.vfill + ParameterDefinition.afun + ParameterDefinition.stardel + ParameterDefinition.dim diff --git a/doc/source/mapdl_commands/apdl/process_controls.rst b/doc/source/mapdl_commands/apdl/process_controls.rst index 1bef331021..76cf70a87c 100644 --- a/doc/source/mapdl_commands/apdl/process_controls.rst +++ b/doc/source/mapdl_commands/apdl/process_controls.rst @@ -1,34 +1,27 @@ -.. _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/ - - Mapdl.wait + :template: base.rst + :toctree: _autosummary + + + ProcessControls.stargo + ProcessControls.wait + ProcessControls.cycle + ProcessControls.endif + ProcessControls.elseif + ProcessControls.starexit + ProcessControls.enddo + ProcessControls.repeat + ProcessControls.dowhile + ProcessControls.do 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/examples/00-mapdl-examples/transient_thermal.py b/examples/00-mapdl-examples/transient_thermal.py index e199b3dbe2..f8a8e7ca7b 100644 --- a/examples/00-mapdl-examples/transient_thermal.py +++ b/examples/00-mapdl-examples/transient_thermal.py @@ -290,7 +290,7 @@ plt.plot(my_bulk[:, 0], my_bulk[:, 1], ":", label="Input") plt.legend() plt.xlabel("Time (seconds)") -plt.ylabel("Temperature ($^\circ$F)") +plt.ylabel("Temperature (°F)") plt.show() ############################################################################### diff --git a/pyproject.toml b/pyproject.toml index c14c4f6868..16e27eaf8a 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.9.2", "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/*,./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 81269ecb9c..08c1de8a4d 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 8567d9c234..66bb8f9d7b 100644 --- a/src/ansys/mapdl/core/_commands/apdl/abbreviations.py +++ b/src/ansys/mapdl/core/_commands/apdl/abbreviations.py @@ -22,171 +22,139 @@ 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. - - This command is valid in any processor. + 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 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 : 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``. - 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). + 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. - - This command is valid in any processor. + 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 :ref:`c`, :ref:`com`, :ref:`gopr`, :ref:`nopr`, :ref:`quit`, :ref:`ui`, or + :ref:`end`. Parameter names and commands of the :ref:`do` and Use the :ref:`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 :ref:`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. - - This command is valid only at the Begin Level. + 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 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 8306549d67..0000000000 --- a/src/ansys/mapdl/core/_commands/apdl/array_param.py +++ /dev/null @@ -1,1535 +0,0 @@ -# Copyright (C) 2016 - 2024 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..9eca20b52f --- /dev/null +++ b/src/ansys/mapdl/core/_commands/apdl/array_parameters.py @@ -0,0 +1,1559 @@ +# Copyright (C) 2016 - 2024 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 `_ + + 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 (\*) 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\*Par1(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\*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 :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 `_ for more information on using :ref:`gcolumn`. Caret 243? 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 = f"*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 `_. + * ``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 ( :ref:`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 `_ + + 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 (\*) 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 vedit(self, par: str = "", **kwargs): + r"""Allows numerical array parameters to be graphically edited. + + Mechanical APDL Command: `\*VEDIT `_ + + Parameters + ---------- + par : str + Name of the array parameter to be edited. + + Notes + ----- + Invokes a graphical editing system that displays array parameter values in matrix form, and allows + the use of the mouse to edit individual values. The starting array subscripts must be defined, such + as :ref:`vedit` ,A(4,6,1), to indicate the section of the array to be edited. The array section + starts at the specified array element and continues to the maximum extent of the array parameter. + Row and column index values may be set or changed in any plane, and those values will be applied to + all planes. The menu system must be on ( :ref:`menu` ) when this command is issued. Graphical + editing is not available for character array parameters. The :ref:`vedit` command can not be used in + a macro or other secondary input file. This command is not applicable to 4- or 5-D arrays. This + command is valid in any processor. + """ + command = f"*VEDIT,{par}" + 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..20ec8c66ca --- /dev/null +++ b/src/ansys/mapdl/core/_commands/apdl/encryption_decryption.py @@ -0,0 +1,195 @@ +# Copyright (C) 2016 - 2024 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 1593861eae..663dff1c10 100644 --- a/src/ansys/mapdl/core/_commands/apdl/macro_files.py +++ b/src/ansys/mapdl/core/_commands/apdl/macro_files.py @@ -22,570 +22,609 @@ 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 = f"/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. - - This command is valid in any processor. + Specifies the pathname of a directory for file searches when reading unknown-command macro files. + 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:: + + 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 ( :ref:`stargo` or :ref:`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. - - APDL Command: ``*CREATE`` + 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. - .. 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. - - This command is valid in any processor. + 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: - - displab - New label (four-character maximum) for the displacement label. The - prior label is no longer valid. - - forcelab - New label (four-character maximum) for the force label for this - degree of freedom. The prior label is no longer valid. + 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). 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. + 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). 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"/DFLAB,{dof},{displab},{forcelab}" + command = f"*CFWRITE,{command}" return self.run(command, **kwargs) - def end(self, **kwargs): - """Closes a macro file. + def cfclos(self, **kwargs): + r"""Closes the "command" file. - APDL Command: ``*END`` + Mechanical APDL Command: `\*CFCLOS `_ 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. - This command is valid in any processor. """ - command = f"*END," + command = f"*CFCLOS" return self.run(command, **kwargs) - def mkdir(self, dir_="", **kwargs): - """Creates a directory. + def cfopen(self, fname: str = "", ext: str = "", loc: str = "", **kwargs): + r"""Opens a "command" file. - APDL Command: /MKDIR + Mechanical APDL Command: `\*CFOPEN `_ 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. The file name defaults to ``Jobname``. + + 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 ----- - It is recommended to just use ``os.mkdir`` + 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"*CFOPEN,{fname},{ext},,{loc}" + return self.run(command, **kwargs) + + def create(self, fname: str = "", ext: str = "", **kwargs): + r"""Opens (creates) a macro file. + + Mechanical APDL Command: `\*CREATE `_ + + 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. Do not use a directory path if file is to be read with the macro ``Name`` option of + the :ref:`use` command. - Creates a directory on the computer ANSYS is currently running on. + 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 + ----- + 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. 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. - - 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. - - 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, 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. + * ``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``. + * ``UI`` - 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. + + 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`` - 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: + 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 output line is: + 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. - Here is an example illustrating multiline displays in GUI message - windows: + Enhanced descriptions may also be used: InformalTables need to be added. - 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. + Do not begin :ref:`msg` format lines with :ref:`if`, :ref:`else`, :ref:`elseif`, or :ref:`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. - This command is valid in any processor. + Here is an example of the :ref:`msg` command and a format to print a message with two integer values and one real value: - """ - command = f"*MSG,{lab},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8}" - return self.run(command, **kwargs) + .. code:: - def pmacro(self, **kwargs): - """Specifies that macro contents be written to the session log file. + \*MSG, INFO, 'Inner',25,1.2,148 + Radius ( %C) = %I, Thick = %G, Length = %I + + The output line is: - APDL Command: /PMACRO + .. code:: - 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. - """ - command = f"/PMACRO," - return self.run(command, **kwargs) + Radius (Inner) = 25, Thick = 1.2, Length = 148. - def psearch(self, pname="", **kwargs): - """Specifies a directory to be searched for "unknown command" macro files. + Here is an example illustrating multiline displays in GUI message windows: - APDL Command: /PSEARCH + .. code:: - 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. + \*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) - 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. + 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. - This command is valid only at the Begin Level. + This command is valid in any processor. """ - command = f"/PSEARCH,{pname}" + command = f"*MSG,{lab},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8}" return self.run(command, **kwargs) - def rmdir(self, dir_="", **kwargs): - """Removes (deletes) a directory. + def mkdir(self, dir: str = "", **kwargs): + r"""Creates a directory. - APDL Command: /RMDIR + Mechanical APDL Command: `/MKDIR `_ 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. + 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 ----- - Removes a directory on the computer ANSYS is currently running on. No - warning or prompt is given, so use with extreme caution. + Creates a directory on the computer Mechanical APDL is currently running on. """ - command = f"/RMDIR,{dir_}" + command = f"/MKDIR,{dir}" 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. + * ``APPEND`` - Indicates that you want to append to ``Fname`` the command text that follows. + * ``END`` - Signals the end of the command text that is to be written to or appended to ``Fname``. - For more information about the /TEE command, see the Introducing APDL - of the ANSYS Parametric Design Language Guide. + 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 following example illustrates the use of the /TEE command. If you - issue these commands: + 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``. - the content of myfile.mac is: + 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. - This command is valid in any processor, but only during an interactive - run. - """ - command = f"/TEE,{label},{fname},{ext}" - return self.run(command, **kwargs) + For more information about the :ref:`slashtee` command, see the of the `Ansys Parametric Design Language Guide `_. - def ulib(self, fname="", ext="", **kwargs): - """Identifies a macro library file. + The following example illustrates the use of the :ref:`slashtee` command. If you issue these commands: - APDL Command: ``*ULIB`` + .. code:: - 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. + /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 - ext - Filename extension (eight-character maximum). + the content of myfile.mac is: - 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. + .. code:: - This command is valid in any processor. + 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 ac4af814e6..0000000000 --- a/src/ansys/mapdl/core/_commands/apdl/matrix_op.py +++ /dev/null @@ -1,999 +0,0 @@ -# Copyright (C) 2016 - 2024 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..c0fd5b85f8 --- /dev/null +++ b/src/ansys/mapdl/core/_commands/apdl/matrix_operations.py @@ -0,0 +1,1236 @@ +# Copyright (C) 2016 - 2024 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:: + + \*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: .. math:: 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\*100 = 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\*sparse, sparse\*dense, or dense\*dense). + """ + 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:: + + \*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 = 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:: + + \*VEC,V,I,ALLOC,5 + V(1)=5,-3,2,0,-1 + \*SORT,V,VALUE + \*PRINT,V + + generates this output: + + .. code:: + + -3 -1 0 2 5 + + To reverse the order, this input: + + .. code:: + + \*SORT,V,VALUE,,1 + \*PRINT,V + + generates this output: + + .. code:: + + 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 `_. + """ + 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: .. math:: 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. Caret 122? + """ + 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` ). Caret 7? + """ + 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\*M1 + w\*M2. + + 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\*M2 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:: + ... + DMIG\* KAAX 21 2 + * 21 1-2.261491337E+08 + ... + A FREE field format file with blank separators (using ``Val4`` = ’S’): + .. code:: + ... + 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:: + ... + 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: .. math:: Set ``Conj`` = FALSE if you do not want to use the conjugate of + ``Vector1``. In this case, the operation is: .. math:: + """ + 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 75915afe8e..43f737a868 100644 --- a/src/ansys/mapdl/core/_commands/apdl/parameter_definition.py +++ b/src/ansys/mapdl/core/_commands/apdl/parameter_definition.py @@ -22,301 +22,150 @@ 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. - Parameters - ---------- - lab - Specifies the units to be used: - - Use radians for input and output of parameter angular functions (default). - Use degrees for input and output of parameter angular functions. - - 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) - - def dim( - self, - par="", - type_="", - imax="", - jmax="", - kmax="", - var1="", - var2="", - var3="", - csysid="", - **kwargs, - ): - """Defines an array parameter and its dimensions. - - APDL Command: ``*DIM`` + Mechanical APDL Command: `PARRES `_ Parameters ---------- - par - Name of parameter to be dimensioned. See ``*SET`` for name - restrictions. + lab : str + Read operation: - type\\_ - Array type: + * ``NEW`` - Replace current parameter set with these parameters (default). + * ``CHANGE`` - Extend current parameter set with these parameters, replacing any that already exist. + + 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``. - 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. + ext : str + Filename extension (eight-character maximum). The extension defaults to PARM if ``Fname`` is blank. 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 + 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. This command is valid + in any processor. - Specify PRESSURE as the independent variable (not PRES). + Examples + -------- + Read a local parameter 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. + >>> mapdl.parres('parm.PARM') + """ + return self.run(f"PARRES, {lab}, {fname}, {ext}") - 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. + def parsav(self, lab: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Writes parameters to a file. - The gap/penetration label (GAP) is only used for defining certain - contact element real constants. + Mechanical APDL Command: `PARSAV `_ - The frequency label (FREQ) is valid for harmonic analyses only. + Parameters + ---------- + lab : str + Write operation: - 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. + * ``SCALAR`` - Write only scalar parameters (default). + * ``ALL`` - Write scalar and array parameters. Parameters may be numeric or alphanumeric. - If you use table parameters to define boundary conditions, the table - names (Par) must not exceed 32 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. The file name defaults to ``Jobname``. - 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. + ext : str + Filename extension (eight-character maximum). The extension defaults to PARM if ``Fname`` is blank. - This command is valid in any processor. + 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. + + 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. - 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. + 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 ``\*.rst`` file, :ref:`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 :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 +180,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 +203,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 +220,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** + \*\*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,8 +248,7 @@ 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** + \*\*RETURNING THE VALUE OF AN ENVIRONMENT VARIABLE TO A PARAMETER\*\* If ``FUNC=ENV``, the command format is ``/INQUIRE,StrArray,ENV,ENVNAME,Substring``. In this instance, ENV specifies that the command should return the @@ -405,25 +256,23 @@ 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** + \*\*RETURNING THE VALUE OF A TITLE TO A PARAMETER\*\* If ``FUNC = TITLE``, the command format is ``/INQUIRE,StrArray,TITLE,Title_num``. In this context, the value of Title_num can be blank or ``1`` through ``5``. If the 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** + \*\*RETURNING INFORMATION ABOUT A FILE TO A PARAMETER\*\* The ``/INQUIRE`` command can also return information about specified files within the file system. @@ -431,42 +280,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 ``\*yyyymmdd.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,355 +340,621 @@ 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'. - This command is valid in any processor. + 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 ( :ref:`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 :ref:`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 :ref:`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 :ref:`ask`, :ref:`an3d`, :ref:`cfwrite`, :ref:`if` , + :ref:`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 :ref:`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` ). + + The following are possible values for ``Par`` + + * ```` - Lists all parameters (except local macro parameters and those with names beginning or + ending with an underbar) and toolbar abbreviations. + * ``_PRM`` - Lists only parameters with names beginning with an underbar (_). These are Mechanical APDL + internal parameters. + * ``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. + * ``ABBR`` - Lists all toolbar abbreviations. + * ``PARM`` - Lists all parameters (except local macro parameters and those with names beginning or + ending with an underbar). + * ``MATH`` - Lists all APDL Math parameters, including vectors, matrices, and linear solvers. + * ``PARNAME`` - Lists only the parameter specified. ``PARNAME`` cannot be a local macro parameter + name. + * ``ARGX`` - Lists all local macro parameter values (ARG1- AR99) that are non-zero or non-blank. + + 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. + + 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. + + 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. + + 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. + + 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. - NEW - Replace current parameter set with these parameters (default). + Notes + ----- + 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"*STATUS,{par},{imin},{imax},{jmin},{jmax},{kmin},{kmax},{lmin},{lmax},{mmin},{mmax},{kpri}" + return self.run(command, **kwargs) - CHANGE - Extend current parameter set with these - parameters, replacing any that already exist. + def tread( + self, par: str = "", fname: str = "", ext: str = "", nskip: str = "", **kwargs + ): + r"""Reads data from an external file into a table array parameter. - 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. + Mechanical APDL Command: `\*TREAD `_ - The file name defaults to Jobname. + Parameters + ---------- + par : str + Table array parameter name as defined by the :ref:`dim` command. - ext - Filename extension (eight-character maximum). The - extension defaults to PARM if Fname is blank. + 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. - Examples - -------- - Read a local parameter file. + ext : str + Filename extension (eight-character maximum). Extension has no default. - >>> mapdl.parres('parm.PARM') + nskip : str + Number of comment lines at the beginning of the file being read that will be skipped during the + reading. Default = 0. + 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. This command + is not applicable to 4- or 5-D tables. """ - return self.run(f"PARRES, {lab}, {fname}, {ext}") + command = f"*TREAD,{par},{fname},{ext},,{nskip}" + return self.run(command, **kwargs) - def parsav(self, lab="", fname="", ext="", **kwargs): - """Writes parameters to a file. + def taxis( + self, + 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, + ): + r"""Defines table index numbers. - APDL Command: PARSAV + Mechanical APDL Command: `\*TAXIS `_ Parameters ---------- - lab - Write operation: - - - ``'SCALAR'`` : Write only scalar parameters (default). - - ``'ALL'`` : Write scalar and array parameters. - Parameters may be numeric or alphanumeric. - - 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). + parmloc : str + Name and starting location in the table array parameter for indexing. Indexing occurs along the + axis defined with ``nAxis``. + + naxis : str + Axis along which indexing occurs. Valid labels are: + + * ``1`` - Corresponds to Row. Default. + * ``2`` - Corresponds to Column. + * ``3`` - Corresponds to Plane. + * ``4`` - Corresponds to Book. + * ``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. To list the index values specified with + ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, ``Val2`` - ``Val10`` are ignored. + + 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. To list the index values specified with + ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, ``Val2`` - ``Val10`` are ignored. + + 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. 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 ----- - 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. + :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, - 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. + .. code:: - This command is valid in any processor. + \*TAXIS,longtable(1,4,1,1),2,1.0,2.2,3.5,4.7,5.9 + ``nAxis`` 2 (column location), starting at location 4. + + To list index numbers, issue :ref:`taxis`, ``ParmLoc``, ``nAxis``, LIST, where ``nAxis`` = 1 through 5 or ALL. """ - command = f"PARSAV,{lab},{fname},{ext}" + command = f"*TAXIS,{parmloc},{naxis},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8},{val9},{val10}" return self.run(command, **kwargs) - def starset( + def vread( self, - par="", - value="", - 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, ): - """Assigns values to user-named parameters. + r"""Reads data and produces an array parameter vector or matrix. - APDL Command: ``*SET`` + Mechanical APDL Command: `\*VREAD `_ 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'``. + 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). + + label : str + Can take a value of IJK, IKJ, JIK, JKI, KIJ, KJI, or blank (IJK). + + 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. + + 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. + + 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. + + nskip : str + Number of lines at the beginning of the file being read that will be skipped during the reading. + Default = 0. Notes ----- - Assigns values to user-named parameters that may be substituted later - in the run. The equivalent (and recommended) format is + 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 (\*) + 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. - ``Par = VALUE,VAL2,VAL3, . . . , VAL10`` + A starting array element number must be defined for the result array parameter vector (numeric or + character). For example, entering these two lines: - which may be used in place of ``*SET,Par, : ...`` for convenience. + .. code:: - This command is valid in any processor. + \*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:: + + \*VREAD,A(1,1),ARRAYVAL,,,IJK,10,2 + (2F6.0) - 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. + 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.) + + 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"*SET,{par},{value},{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 starvget( self, - parr="", - entity="", - entnum="", - item1="", - it1num="", - item2="", - it2num="", - kloop="", + parr: str = "", + entity: str = "", + entnum: str = "", + item1: str = "", + it1num: str = "", + item2: str = "", + it2num: str = "", + kloop: str = "", **kwargs, ): - """Retrieves values and stores them into an array parameter. + r"""Retrieves values and stores them into an array parameter. - APDL Command: ``*VGET`` + Mechanical APDL Command: `\*VGET `_ Parameters ---------- - parr - The name of the resulting vector array parameter. See ``*SET`` for - name restrictions. + 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. - entity - Entity keyword. Valid keywords are NODE, ELEM, KP, LINE, AREA, - VOLU, etc. as shown for Entity = in the tables below. + entity : str + Entity keyword. Valid keywords are NODE, ELEM, KP, LINE, AREA, VOLU, etc. as shown for + ``Entity`` = in the tables below. - entnum - The number of the entity (as shown for ENTNUM = in the tables - below). + entnum : str + The number of the entity (as shown for ``ENTNUM`` = in the tables below). - item1 - The name of a particular item for the given entity. Valid items - are as shown in the Item1 columns of 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 - 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. + 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, 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. + 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. - kloop - Field to be looped on: - - ``0`` or ``2`` : Loop on the ENTNUM field (default). - - ``3`` : Loop on the Item1 field. + 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. - ``4`` : Loop on the IT1NUM field. Successive items are as shown with IT1NUM. - - ``5`` : Loop on the Item2 field. + kloop : str + Field to be looped on: - ``6`` : Loop on the IT2NUM field. Successive items are as shown with IT2NUM. + * ``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 ----- - 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. - - 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. - - The ``*VGET`` command retrieves both the unprocessed real and the imaginary - parts (original and duplicate sector nodes and elements) of a cyclic - symmetry solution. - - 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 - + 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. 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 ``\*.rst`` file, GET data is accessed from the database or from the common + blocks. Get operations do not access the ``\*.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 = ( @@ -847,306 +962,363 @@ def starvget( ) return self.run(command, **kwargs) - def taxis( + def vfill( self, - parmloc="", - naxis="", - val1="", - val2="", - val3="", - val4="", - val5="", - val6="", - val7="", - val8="", - val9="", - val10="", + 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, ): - """Defines table index numbers. + r"""Fills an array parameter. - APDL Command: ``*TAXIS`` + Mechanical APDL Command: `\*VFILL `_ 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 numeric array parameter vector. See :ref:`starset` for name + restrictions. + + 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. + * ``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\* ``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. - naxis - Axis along which indexing occurs. Valid labels are: + con5 : str + Constants used with above functions. - Corresponds to Row. Default. - Corresponds to Column. + con6 : str + Constants used with above functions. - Corresponds to Plane. - Corresponds to Book. + con7 : str + Constants used with above functions. - Corresponds to Shelf. - Lists all index numbers. Valid only if Val1 = LIST. + con8 : str + Constants used with above functions. - 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. + con9 : str + Constants used with above functions. + + con10 : str + Constants used with above functions. 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. - - To list index numbers, issue ```*TAXIS,ParmLoc, nAxis, LIST,`` where - nAxis = 1 through 5 or ALL. + 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 ( :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"*TAXIS,{parmloc},{naxis},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8},{val9},{val10}" + command = f"*VFILL,{parr},{func},{con1},{con2},{con3},{con4},{con5},{con6},{con7},{con8},{con9},{con10}" 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 afun(self, lab: str = "", **kwargs): + r"""Specifies units for angular functions in parameter expressions. - APDL Command: ``*TREAD`` + Mechanical APDL Command: `\*AFUN `_ Parameters ---------- - par - Table array parameter name as defined by the ``*DIM`` command. - - 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). + lab : str + Specifies the units to be used: - nskip - Number of comment lines at the beginning of the file being read - that will be skipped during the reading. Default = 0. + * ``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 ----- - 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. - - This command is not applicable to 4- or 5-D tables. + Only the SIN, COS, TAN, ASIN, ACOS, ATAN, ATAN2, ANGLEK, and ANGLEN functions ( :ref:`starset` , + :ref:`vfun` ) are affected by this command. """ - command = f"*TREAD,{par},{fname},{ext},,{nskip}" + command = f"*AFUN,{lab}" return self.run(command, **kwargs) - def vfill( - self, - parr="", - func="", - con1="", - con2="", - con3="", - con4="", - con5="", - con6="", - con7="", - con8="", - con9="", - con10="", - **kwargs, - ): - """Fills an array parameter. + def stardel(self, val1: str = "", val2: str = "", **kwargs): + r"""Deletes a parameter or parameters (GUI). - APDL Command: ``*VFILL`` + Mechanical APDL Command: `\*DEL `_ Parameters ---------- - parr - The name of the resulting numeric array parameter vector. See ``*SET`` - for name restrictions. - - func - 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 - Constants used with above functions. + val1 : str + Command behavior key: + + * ``ALL`` - Delete all user-defined parameters, or all user-defined parameters `and` all system + parameters, as specified by ``Val2``. + * ```` - Delete the parameter(s) specified by ``Val2``. + * ``ParmName`` - Delete a single named parameter, specified here. ( ``Val2`` is not used in this + case.) + + val2 : str + The parameter or parameters to delete (used only when ``Val1`` = ALL or (blank)): + + * ``LOC`` - When ``Val1`` is (blank), specifies the location of the parameter within the `Array + Parameters + `_ + dialog box. The location number is based on an alphabetically ordered list of all parameters in + the database. + * ``_PRM`` - When ``Val1`` is ALL, deletes all parameters, including those named with a leading + underscore (_) (except _STATUS and _RETURN). When ``Val1`` is (blank), deletes only those + parameters named with a leading underscore (_) (except _STATUS and _RETURN). + * ``PRM_`` - When ``Val1`` is (blank), deletes only those parameters named with a trailing + underscore (_). + * ```` - When ``Val1`` is ALL, a (blank) value for ``Val2`` causes `all` user-defined parameters to + be deleted. Notes ----- - 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. - - This command is valid in any processor. + This is a command generally created by the graphical user interface (GUI). It appears in the log + file ( ``Jobname.LOG`` ) if an array parameter is deleted from within the Array Parameters dialog. + Usage examples: Delete all user-defined parameters: :ref:`stardel`,ALL Delete only those user- + defined parameters named with a trailing underscore: :ref:`stardel`,,PRM Delete all user-defined + `and` all system parameters (except for _STATUS and _RETURN): :ref:`stardel`,ALL,_PRM Delete a + parameter by specifying its location within the Array Parameters dialog: :ref:`stardel`, ``LOC`` + Delete a single specified parameter by name: :ref:`stardel`, ``ParmName`` (You cannot specify more + than one named parameter at a time.) The :ref:`stardel` command does not free up memory but only + deletes the specified reference. For example, memory usage increases from the continued issuance of + :ref:`stardel` and :ref:`dim` within :ref:`dowhile` loops, as arrays are stored in the database + (memory) and :ref:`stardel` removes only the ``reference`` to the array. To release the memory in + use, issue the :ref:`save` command after :ref:`stardel`. This command is valid in any processor. """ - command = f"*VFILL,{parr},{func},{con1},{con2},{con3},{con4},{con5},{con6},{con7},{con8},{con9},{con10}" + command = f"*DEL,{val1},{val2}" return self.run(command, **kwargs) - def vread( + 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). - - 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. + type : str + Array type: - nskip - Number of lines at the beginning of the file being read that will - be skipped during the reading. Default = 0. + * ``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. + + var2 : str + Variable name corresponding to the second dimension (column) for ``Type`` = TABLE, TAB4, or + TAB5. Default = Column. + + 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.) - - 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.). + 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:: + + \*DIM,Par,Type,IMAX,JMAX,KMAX,LMAX,Var1,Var2,Var3,Var4,CSYSID + + For a 5-D table, the command syntax is: + + .. code:: + + \*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 - 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 69d48e02e6..bdc7622846 100644 --- a/src/ansys/mapdl/core/_commands/apdl/process_controls.py +++ b/src/ansys/mapdl/core/_commands/apdl/process_controls.py @@ -22,27 +22,324 @@ class ProcessControls: - def wait(self, dtime="", **kwargs): - """APDL Command: /WAIT - Causes a delay before the reading of the next command. + def stargo(self, base: str = "", **kwargs): + r"""Causes a specified line on the input file to be read next. + + Mechanical APDL Command: `\*GO `_ Parameters ---------- - dtime - Time delay (in seconds). Maximum time delay is 59 seconds. + base : str + "Go to" action: + + * ``:, label`` - A user-defined label (beginning with a colon (:), 8 characters maximum). The + command reader will skip (and wrap to the beginning of the file, if necessary) to the first line + that begins with the matching : ``label``. .. warning:: This label option may not be mixed + with do-loop or if-then-else constructs. + * ``STOP`` - This action will cause an exit from the Mechanical APDL program at this line. Notes ----- - You should consider using ``time.sleep(dtime)`` + Causes the next read to be from a specified line on the input file. Lines may be skipped or reread. + The :ref:`stargo` command will `not` be executed unless it is part of a macro, user file (processed + by :ref:`use` ), an alternate input file (processed by :ref:`input` ), or unless it is used in a + batch-mode input stream. Jumping into, out of, or within a do-loop or an if-then-else construct to a + : ``label`` line is not allowed. This command is valid in any processor. + """ + command = f"*GO,{base}" + return self.run(command, **kwargs) + + def wait(self, dtime: str = "", **kwargs): + r"""Causes a delay before the reading of the next command. - 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. + Mechanical APDL Command: `/WAIT `_ - This command is valid in any processor. + Parameters + ---------- + dtime : str + Time delay (in seconds). Maximum time delay is 59 seconds. + + Notes + ----- + 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 :ref:`ask` command. This command is valid in any processor. """ command = f"/WAIT,{dtime}" return self.run(command, **kwargs) + + def cycle(self, **kwargs): + r"""Bypasses commands within a do-loop. + + Mechanical APDL Command: `\*CYCLE `_ + + Notes + ----- + Bypasses all commands between this command and the :ref:`enddo` command within a do-loop. The next + loop (if applicable) is initiated. The cycle option may also be conditionally executed [Use the + :ref:`if` ]. The :ref:`cycle` command must appear on the same file as the :ref:`do` command. This + command is valid in any processor. + """ + command = f"*CYCLE" + return self.run(command, **kwargs) + + def endif(self, **kwargs): + r"""Ends an if-then-else. + + Mechanical APDL Command: `\*ENDIF `_ + + Notes + ----- + Required terminator for the if-then-else construct. See :ref:`if` for details. If a batch input + stream hits an end-of-file during a false :ref:`if` condition, the analysis will not terminate + normally. You will need to terminate it externally (use either the Linux "kill" function or the + Windows task manager). The :ref:`endif` command must appear on the same file as the :ref:`if` + command, and all six characters must be input. This command is valid in any processor. + """ + command = f"*ENDIF" + return self.run(command, **kwargs) + + def elseif( + self, + val1: str = "", + oper1: str = "", + val2: str = "", + conj: str = "", + val3: str = "", + oper2: str = "", + val4: str = "", + **kwargs, + ): + r"""Separates an intermediate if-then-else block. + + Mechanical APDL Command: `\*ELSEIF `_ + + Parameters + ---------- + val1 : str + First numerical value (or parameter which evaluates to numerical value) in the conditional + comparison operation. ``VAL1``, ``VAL2``, ``VAL3``, and ``VAL4`` can also be character + strings (enclosed in quotes) or parameters for ``Oper`` = EQ and NE only. + + oper1 : str + Operation label. A tolerance of 1.0E-10 is used for comparisons between real numbers: + + * ``EQ`` - Equal (for ``VAL1`` = ``VAL2`` ). + * ``NE`` - Not equal (for ``VAL1`` ≠ ``VAL2`` ). + * ``LT`` - Less than (for ``VAL1`` < ``VAL2`` ). + * ``GT`` - Greater than (for ``VAL1`` > ``VAL2`` ). + * ``LE`` - Less than or equal (for ``VAL1`` :math:`` ``VAL2`` ). + * ``GE`` - Greater than or equal (for ``VAL1`` :math:`` ``VAL2`` ). + * ``ABLT`` - Absolute values of ``VAL1`` and ``VAL2`` before < operation. + * ``ABGT`` - Absolute values of ``VAL1`` and ``VAL2`` before > operation. + + val2 : str + Second numerical value (or parameter which evaluates to numerical value) in the conditional + comparison operation. + + conj : str + (Optional) Connection between two logical clauses. + + * ``AND -`` - True if both clauses ( ``Oper1`` and ``Oper2`` ) are true. + * ``OR -`` - True if either clause is true. + * ``XOR -`` - True if either (but not both) clause is true. + + val3 : str + (Optional) Third numerical value (or parameter which evaluates to numerical value). + + oper2 : str + (Optional) Operation label. This will have the same labels as ``Oper1``, except it uses + ``Val3`` and ``Val4``. A tolerance of 1.0E-10 is used for comparisons between real numbers. + + val4 : str + (Optional) Fourth numerical value (or parameter value which evaluates to a numerical value). + + Notes + ----- + Optional intermediate block separator within an if-then-else construct. All seven characters of the + command name (\*ELSEIF) must be input. This command is similar to the :ref:`if` command except that + the ``Base`` field is not used. The :ref:`if`, :ref:`elseif`, :ref:`else`, and :ref:`endif` + commands for each if-then-else construct must all be read from the same file (or keyboard). This + command is valid in any processor. + """ + command = f"*ELSEIF,{val1},{oper1},{val2},{conj},{val3},{oper2},{val4}" + return self.run(command, **kwargs) + + def starexit(self, **kwargs): + r"""Exits a do-loop. + + Mechanical APDL Command: `\*EXIT `_ + + Notes + ----- + The command following the :ref:`enddo` is executed next. The exit option may also be conditional + [Use the :ref:`if` ]. The :ref:`starexit` command must appear on the same file as the :ref:`do` + command. This command is valid in any processor. + """ + command = f"*EXIT" + return self.run(command, **kwargs) + + def enddo(self, **kwargs): + r"""Ends a do-loop and starts the looping action. + + Mechanical APDL Command: `\*ENDDO `_ + + Notes + ----- + One :ref:`enddo` is required for each nested do-loop. The :ref:`enddo` command must appear on the + same file as the :ref:`do` command, and all six characters must be input. This command is valid in + any processor. + """ + command = f"*ENDDO" + return self.run(command, **kwargs) + + def repeat( + self, + ntot: str = "", + vinc1: str = "", + vinc2: str = "", + vinc3: str = "", + vinc4: str = "", + vinc5: str = "", + vinc6: str = "", + vinc7: str = "", + vinc8: str = "", + vinc9: str = "", + vinc10: str = "", + vinc11: str = "", + **kwargs, + ): + r"""Repeats the previous command. + + Mechanical APDL Command: `\*REPEAT `_ + + Parameters + ---------- + ntot : str + Number of times the preceding command is executed (including the initial execution). Must be 2 + or greater. ``NTOT`` of 2 causes one repeat (for a total of 2 executions). + + vinc1 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc2 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc3 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc4 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc5 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc6 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc7 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc8 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc9 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc10 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc11 : str + Value increments applied to first through eleventh data fields of the preceding command. + + Notes + ----- + :ref:`repeat` must immediately follow the command that is to be repeated. The numeric arguments of + the initial command may be incremented in the generated commands. The numeric increment values may + be integer or real, positive or negative, zero or blank. Alphanumeric arguments cannot be + incremented. For large values of ``NTOT``, consider printout suppression ( :ref:`nopr` command) + first. Most commands beginning with slash (/), star (\*), as well as "unknown command" macros, + cannot be repeated. For these commands, or if more than one command is to be repeated, include them + within a do-loop. File switching commands (those reading additional commands) cannot be repeated. If + a :ref:`repeat` command immediately follows another :ref:`repeat` command, the repeat action only + applies to the last non- :ref:`repeat` command. Also, :ref:`repeat` should not be used in + interactive mode immediately after a) a command (or its log file equivalent) that uses picking, or + b) a command that requires a response from the user. This command is valid in any processor. + """ + command = f"*REPEAT,{ntot},{vinc1},{vinc2},{vinc3},{vinc4},{vinc5},{vinc6},{vinc7},{vinc8},{vinc9},{vinc10},{vinc11}" + return self.run(command, **kwargs) + + def dowhile(self, par: str = "", **kwargs): + r"""Loops repeatedly through the next :ref:`enddo` command. + + Mechanical APDL Command: `\*DOWHILE `_ + + Parameters + ---------- + par : str + The name of the scalar parameter to be used as the loop index. There is no character parameter + substitution for the ``Par`` field. + + Notes + ----- + :ref:`dowhile` loops repeatedly through the next :ref:`enddo` command as long as ``Par`` is greater + than zero. The block of commands following the :ref:`dowhile` command (up to the :ref:`enddo` + command) is executed repeatedly until some loop control is satisfied. Printout is automatically + suppressed on all loops after the first (include a :ref:`gopr` command to restore the printout). The + command line loop control ( ``Par`` ) must be input; however, :ref:`if` within the block can also be + used to control looping ( :ref:`starexit`, :ref:`cycle` ). One level of internal file switching is + used for each nested :ref:`dowhile`. Twenty levels of nested do-loops are allowed. This command is + valid in any processor. + """ + command = f"*DOWHILE,{par}" + return self.run(command, **kwargs) + + def do( + self, par: str = "", ival: str = "", fval: str = "", inc: str = "", **kwargs + ): + r"""Defines the beginning of a do-loop. + + Mechanical APDL Command: `\*DO `_ + + Parameters + ---------- + par : str + The name of the scalar parameter to be used as the loop index. See :ref:`starset` for name + restrictions. Any existing parameter of the same name will be redefined. There is no character + parameter substitution for the ``Par`` field. + + ival : str + Initially assign ``IVAL`` to ``Par``. Increment ``IVAL`` by ``INC`` for each successive loop. If + ``IVAL`` exceeds ``FVAL`` and ``INC`` is positive, the loop is not executed. ``INC`` defaults to + 1. Negative increments and non-integer numbers are allowed. + + fval : str + Initially assign ``IVAL`` to ``Par``. Increment ``IVAL`` by ``INC`` for each successive loop. If + ``IVAL`` exceeds ``FVAL`` and ``INC`` is positive, the loop is not executed. ``INC`` defaults to + 1. Negative increments and non-integer numbers are allowed. + + inc : str + Initially assign ``IVAL`` to ``Par``. Increment ``IVAL`` by ``INC`` for each successive loop. If + ``IVAL`` exceeds ``FVAL`` and ``INC`` is positive, the loop is not executed. ``INC`` defaults to + 1. Negative increments and non-integer numbers are allowed. + + Notes + ----- + The block of commands following the :ref:`do` command (up to the :ref:`enddo` command) is executed + repeatedly until some loop control is satisfied. Printout is automatically suppressed on all loops + after the first (include a :ref:`gopr` command to restore the printout). The command line loop + control ( ``Par``, ``IVAL``, ``FVAL``, ``INC`` ) must be input; however, a Use the :ref:`if` + within the block can also be used to control looping ( :ref:`starexit`, :ref:`cycle` ). One level + of internal file switching is used for each nested :ref:`do`. Twenty levels of nested do-loops are + allowed. Do-loops that include :ref:`input`, :ref:`use`, or an "Unknown Command" macro, have less + nesting available because each of these operations also uses a level of file switching. The + :ref:`do`, :ref:`enddo`, and any :ref:`cycle` and :ref:`starexit` commands for a do-loop must all + be read from the same file (or keyboard). You cannot use the `MULTIPRO + `_ + or :ref:`create` commands within a :ref:`do` -loop. Picking operations should also not be used + within a :ref:`do` -loop. This command is valid in any processor. + """ + command = f"*DO,{par},{ival},{fval},{inc}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/commands.py b/src/ansys/mapdl/core/commands.py index 25e88dd528..796032c134 100644 --- a/src/ansys/mapdl/core/commands.py +++ b/src/ansys/mapdl/core/commands.py @@ -345,11 +345,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, ): @@ -488,7 +489,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 b04700bb0a..ea5fadc0e5 100644 --- a/src/ansys/mapdl/core/mapdl_core.py +++ b/src/ansys/mapdl/core/mapdl_core.py @@ -1560,7 +1560,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"]: @@ -2249,7 +2248,7 @@ def run( % (command, INVAL_COMMANDS[command[:3].upper()]) ) raise exception - elif command[:4].upper() in INVAL_COMMANDS: + elif len(command) == 4 and command.upper() in INVAL_COMMANDS: exception = MapdlRuntimeError( 'Invalid PyMAPDL command "%s"\n\n%s' % (command, INVAL_COMMANDS[command[:4].upper()]) diff --git a/tests/test_krylov.py b/tests/test_krylov.py index cab575a733..1d62d9eeed 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