diff --git a/doc/changelog.d/3983.documentation.md b/doc/changelog.d/3983.documentation.md deleted file mode 100644 index 666249628e..0000000000 --- a/doc/changelog.d/3983.documentation.md +++ /dev/null @@ -1 +0,0 @@ -Feat: ``post1`` submodule (1/2) - disabled due to merging branch issue \ No newline at end of file diff --git a/doc/changelog.d/4002.miscellaneous.md b/doc/changelog.d/4002.miscellaneous.md new file mode 100644 index 0000000000..b86df9cd07 --- /dev/null +++ b/doc/changelog.d/4002.miscellaneous.md @@ -0,0 +1 @@ +Feat: ``post1`` submodule (2/2) \ No newline at end of file diff --git a/doc/source/mapdl_commands/post1/index.rst b/doc/source/mapdl_commands/post1/index.rst index 1ce6027e03..304dddb680 100644 --- a/doc/source/mapdl_commands/post1/index.rst +++ b/doc/source/mapdl_commands/post1/index.rst @@ -11,7 +11,7 @@ Post1 * - :ref:`ref_controls` * - :ref:`ref_special_purpose` * - :ref:`ref_status` - * - :ref:`_ref_magnetics_calculations` + * - :ref:`ref_magnetics_calculations` * - :ref:`ref_element_table` * - :ref:`ref_failure_criteria` * - :ref:`ref__fatigue` @@ -29,11 +29,11 @@ Post1 :hidden: animation - setup + set_up controls - special + special_purpose status - magnetics_calc + magnetics_calculations element_table failure_criteria _fatigue diff --git a/doc/source/mapdl_commands/post1/magnetics_calc.rst b/doc/source/mapdl_commands/post1/magnetics_calc.rst deleted file mode 100644 index 99384917a9..0000000000 --- a/doc/source/mapdl_commands/post1/magnetics_calc.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _ref_magnetics_calculations: - -********************** -Magnetics calculations -********************** - -.. currentmodule:: ansys.mapdl.core - -These POST1 commands are used for special purpose magnetics -postprocessing. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.curr2d - Mapdl.emagerr - Mapdl.emf - Mapdl.emft - Mapdl.fluxv - Mapdl.mmf - Mapdl.plf2d - Mapdl.powerh - Mapdl.senergy diff --git a/doc/source/mapdl_commands/post1/magnetics_calculations.rst b/doc/source/mapdl_commands/post1/magnetics_calculations.rst new file mode 100644 index 0000000000..56068418c1 --- /dev/null +++ b/doc/source/mapdl_commands/post1/magnetics_calculations.rst @@ -0,0 +1,26 @@ + +.. _ref_magnetics_calculations: + + +MagneticsCalculations +===================== + + +.. currentmodule:: ansys.mapdl.core._commands.post1.magnetics_calculations + +.. autoclass:: ansys.mapdl.core._commands.post1.magnetics_calculations.MagneticsCalculations + +.. autosummary:: + :template: base.rst + :toctree: _autosummary + + + MagneticsCalculations.curr2d + MagneticsCalculations.emagerr + MagneticsCalculations.emf + MagneticsCalculations.emft + MagneticsCalculations.fluxv + MagneticsCalculations.mmf + MagneticsCalculations.plf2d + MagneticsCalculations.powerh + MagneticsCalculations.senergy diff --git a/doc/source/mapdl_commands/post1/path_operations.rst b/doc/source/mapdl_commands/post1/path_operations.rst index a51b3f2eb9..6928df8578 100644 --- a/doc/source/mapdl_commands/post1/path_operations.rst +++ b/doc/source/mapdl_commands/post1/path_operations.rst @@ -1,33 +1,38 @@ -.. _ref_path_operations_api: -*************** -Path operations -*************** +.. _ref_path_operations: -.. currentmodule:: ansys.mapdl.core -These POST1 commands are used for path operations. +PathOperations +============== + + +.. currentmodule:: ansys.mapdl.core._commands.post1.path_operations + +.. autoclass:: ansys.mapdl.core._commands.post1.path_operations.PathOperations .. autosummary:: - :toctree: _autosummary/ - - Mapdl.padele - Mapdl.paget - Mapdl.paput - Mapdl.paresu - Mapdl.pasave - Mapdl.path - Mapdl.pcalc - Mapdl.pcross - Mapdl.pdef - Mapdl.pdot - Mapdl.plpagm - Mapdl.plpath - Mapdl.plsect - Mapdl.pmap - Mapdl.ppath - Mapdl.prange - Mapdl.prpath - Mapdl.prsect - Mapdl.psel - Mapdl.pvect + :template: base.rst + :toctree: _autosummary + + + PathOperations.fssect + PathOperations.padele + PathOperations.paget + PathOperations.paput + PathOperations.paresu + PathOperations.pasave + PathOperations.path + PathOperations.pcalc + PathOperations.pcross + PathOperations.pdef + PathOperations.pdot + PathOperations.plpagm + PathOperations.plpath + PathOperations.plsect + PathOperations.pmap + PathOperations.ppath + PathOperations.prange + PathOperations.prpath + PathOperations.prsect + PathOperations.psel + PathOperations.pvect diff --git a/doc/source/mapdl_commands/post1/results.rst b/doc/source/mapdl_commands/post1/results.rst index 22f57701a3..61d05206fa 100644 --- a/doc/source/mapdl_commands/post1/results.rst +++ b/doc/source/mapdl_commands/post1/results.rst @@ -1,34 +1,38 @@ -.. _ref_results_api: -******* +.. _ref_results: + + Results -******* +======= + -.. currentmodule:: ansys.mapdl.core +.. currentmodule:: ansys.mapdl.core._commands.post1.results -These POST1 commands are used to process results, such as -degree-of-freedom results, nodal stresses, and element summable and -non-summable miscellaneous data. +.. autoclass:: ansys.mapdl.core._commands.post1.results.Results .. autosummary:: - :toctree: _autosummary/ - - Mapdl.nsort - Mapdl.nusort - Mapdl.plcint - Mapdl.pldisp - Mapdl.plesol - Mapdl.plnsol - Mapdl.plorb - Mapdl.prenergy - Mapdl.prorb - Mapdl.plvect - Mapdl.prcint - Mapdl.presol - Mapdl.prjsol - Mapdl.prnld - Mapdl.prnsol - Mapdl.prrfor - Mapdl.prrsol - Mapdl.prvect - Mapdl.sumtype + :template: base.rst + :toctree: _autosummary + + + Results.lcsum + Results.nsort + Results.nusort + Results.plcint + Results.plcksurf + Results.pldisp + Results.plesol + Results.plnsol + Results.plorb + Results.plvect + Results.prcint + Results.prenergy + Results.presol + Results.prjsol + Results.prnld + Results.prnsol + Results.prorb + Results.prrfor + Results.prrsol + Results.prvect + Results.sumtype diff --git a/doc/source/mapdl_commands/post1/set_up.rst b/doc/source/mapdl_commands/post1/set_up.rst new file mode 100644 index 0000000000..10d50cd3e9 --- /dev/null +++ b/doc/source/mapdl_commands/post1/set_up.rst @@ -0,0 +1,26 @@ + +.. _ref_set_up: + + +SetUp +===== + + +.. currentmodule:: ansys.mapdl.core._commands.post1.set_up + +.. autoclass:: ansys.mapdl.core._commands.post1.set_up.SetUp + +.. autosummary:: + :template: base.rst + :toctree: _autosummary + + + SetUp.append + SetUp.desol + SetUp.detab + SetUp.dnsol + SetUp.hrcplx + SetUp.rescombine + SetUp.reset + SetUp.set + SetUp.subset diff --git a/doc/source/mapdl_commands/post1/setup.rst b/doc/source/mapdl_commands/post1/setup.rst deleted file mode 100644 index 6a280fdac8..0000000000 --- a/doc/source/mapdl_commands/post1/setup.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _ref_set_up: - -***** -Setup -***** - -.. currentmodule:: ansys.mapdl.core - -These POST1 commands are used to put data into the database for -postprocessing. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.append - Mapdl.desol - Mapdl.dnsol - Mapdl.hrcplx - Mapdl.rescombine - Mapdl.subset - Mapdl.set diff --git a/doc/source/mapdl_commands/post1/special.rst b/doc/source/mapdl_commands/post1/special.rst deleted file mode 100644 index c744dcd136..0000000000 --- a/doc/source/mapdl_commands/post1/special.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _ref_special_purpose: - -*************** -Special purpose -*************** - -.. currentmodule:: ansys.mapdl.core - -These POST1 commands are used for various special purposes. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.bfint - Mapdl.cbdof - Mapdl.cmsfile - Mapdl.cyccalc - Mapdl.cycfiles - Mapdl.cycphase - Mapdl.cycspec - Mapdl.exoption - Mapdl.expand - Mapdl.exprofile - Mapdl.exunit - Mapdl.fssparm - Mapdl.fsum - Mapdl.hfang - Mapdl.hfsym - Mapdl.intsrf - Mapdl.kcalc - Mapdl.nforce - Mapdl.nldpost - Mapdl.plcamp - Mapdl.plcfreq - Mapdl.plchist - Mapdl.plfar - Mapdl.plmc - Mapdl.plnear - Mapdl.plzz - Mapdl.pras - Mapdl.prcamp - Mapdl.prfar - Mapdl.prnear - Mapdl.reswrite - Mapdl.rmflvec - Mapdl.rsplit - Mapdl.rstmac - Mapdl.spoint - Mapdl.spmwrite diff --git a/doc/source/mapdl_commands/post1/special_purpose.rst b/doc/source/mapdl_commands/post1/special_purpose.rst new file mode 100644 index 0000000000..7bc2163122 --- /dev/null +++ b/doc/source/mapdl_commands/post1/special_purpose.rst @@ -0,0 +1,56 @@ + +.. _ref_special_purpose: + + +SpecialPurpose +============== + + +.. currentmodule:: ansys.mapdl.core._commands.post1.special_purpose + +.. autoclass:: ansys.mapdl.core._commands.post1.special_purpose.SpecialPurpose + +.. autosummary:: + :template: base.rst + :toctree: _autosummary + + + SpecialPurpose.bfint + SpecialPurpose.cbdof + SpecialPurpose.cmsfile + SpecialPurpose.cyccalc + SpecialPurpose.cycfiles + SpecialPurpose.cycphase + SpecialPurpose.cycspec + SpecialPurpose.exoption + SpecialPurpose.expand + SpecialPurpose.exprofile + SpecialPurpose.exunit + SpecialPurpose.fssparm + SpecialPurpose.fsum + SpecialPurpose.hfang + SpecialPurpose.hfsym + SpecialPurpose.macopt + SpecialPurpose.nforce + SpecialPurpose.nldpost + SpecialPurpose.plas + SpecialPurpose.plcamp + SpecialPurpose.plcfreq + SpecialPurpose.plchist + SpecialPurpose.plfar + SpecialPurpose.plmc + SpecialPurpose.plnear + SpecialPurpose.plzz + SpecialPurpose.pras + SpecialPurpose.prcamp + SpecialPurpose.prfar + SpecialPurpose.prmc + SpecialPurpose.prnear + SpecialPurpose.reswrite + SpecialPurpose.rmflvec + SpecialPurpose.rsplit + SpecialPurpose.rstmac + SpecialPurpose.slashexpand + SpecialPurpose.spmwrite + SpecialPurpose.spoint + SpecialPurpose.vtkwrite diff --git a/doc/source/mapdl_commands/post1/status.rst b/doc/source/mapdl_commands/post1/status.rst index 447abdfddc..87bbb6dc3f 100644 --- a/doc/source/mapdl_commands/post1/status.rst +++ b/doc/source/mapdl_commands/post1/status.rst @@ -1,19 +1,26 @@ -.. _ref_status_post1: -****** +.. _ref_status: + + Status -****** +====== + -.. currentmodule:: ansys.mapdl.core +.. currentmodule:: ansys.mapdl.core._commands.post1.status -These POST1 commands are for use with the STAT command. +.. autoclass:: ansys.mapdl.core._commands.post1.status.Status .. autosummary:: - :toctree: _autosummary/ - - Mapdl.calc - Mapdl.datadef - Mapdl.display - Mapdl.lccalc - Mapdl.point - Mapdl.spec + :template: base.rst + :toctree: _autosummary + + + Status.calc + Status.datadef + Status.define + Status.display + Status.lccalc + Status.point + Status.print + Status.sort + Status.spec diff --git a/doc/source/mapdl_commands/post1/surface_operations.rst b/doc/source/mapdl_commands/post1/surface_operations.rst index 7f292a0cc6..832d3fe11b 100644 --- a/doc/source/mapdl_commands/post1/surface_operations.rst +++ b/doc/source/mapdl_commands/post1/surface_operations.rst @@ -1,26 +1,29 @@ -.. _ref_surface_operations_api: -****************** -Surface operations -****************** +.. _ref_surface_operations: -.. currentmodule:: ansys.mapdl.core -These POST1 commands are used to define an arbitrary surface and to -develop results information for that surface. +SurfaceOperations +================= + + +.. currentmodule:: ansys.mapdl.core._commands.post1.surface_operations + +.. autoclass:: ansys.mapdl.core._commands.post1.surface_operations.SurfaceOperations .. autosummary:: - :toctree: _autosummary/ - - Mapdl.sucalc - Mapdl.sucr - Mapdl.sudel - Mapdl.sueval - Mapdl.suget - Mapdl.sumap - Mapdl.supl - Mapdl.supr - Mapdl.suresu - Mapdl.susave - Mapdl.susel - Mapdl.suvect + :template: base.rst + :toctree: _autosummary + + + SurfaceOperations.sucalc + SurfaceOperations.sucr + SurfaceOperations.sudel + SurfaceOperations.sueval + SurfaceOperations.suget + SurfaceOperations.sumap + SurfaceOperations.supl + SurfaceOperations.supr + SurfaceOperations.suresu + SurfaceOperations.susave + SurfaceOperations.susel + SurfaceOperations.suvect diff --git a/doc/source/mapdl_commands/post1/trace_points.rst b/doc/source/mapdl_commands/post1/trace_points.rst index fa94cb96cb..607ba87f66 100644 --- a/doc/source/mapdl_commands/post1/trace_points.rst +++ b/doc/source/mapdl_commands/post1/trace_points.rst @@ -1,18 +1,21 @@ -.. _ref_trace Points_api: -************ -Trace points -************ +.. _ref_trace_points: -.. currentmodule:: ansys.mapdl.core -These POST1 commands are used to trace particle motions in a flow -stream. +TracePoints +=========== + + +.. currentmodule:: ansys.mapdl.core._commands.post1.trace_points + +.. autoclass:: ansys.mapdl.core._commands.post1.trace_points.TracePoints .. autosummary:: - :toctree: _autosummary/ + :template: base.rst + :toctree: _autosummary + - Mapdl.pltrac - Mapdl.trpdel - Mapdl.trplis - Mapdl.trpoin + TracePoints.pltrac + TracePoints.trpdel + TracePoints.trplis + TracePoints.trpoin diff --git a/src/ansys/mapdl/core/_commands/post1/__init__.py b/src/ansys/mapdl/core/_commands/post1/__init__.py index 353dd0822d..311aecf846 100644 --- a/src/ansys/mapdl/core/_commands/post1/__init__.py +++ b/src/ansys/mapdl/core/_commands/post1/__init__.py @@ -29,4 +29,12 @@ failure_criteria, listing, load_case_calculations, + magnetics_calculations, + path_operations, + results, + set_up, + special_purpose, + status, + surface_operations, + trace_points, ) diff --git a/src/ansys/mapdl/core/_commands/post1/animation.py b/src/ansys/mapdl/core/_commands/post1/animation.py index 49ee920fc4..20f72067a0 100644 --- a/src/ansys/mapdl/core/_commands/post1/animation.py +++ b/src/ansys/mapdl/core/_commands/post1/animation.py @@ -157,7 +157,7 @@ def ancyc( .. _ANCYC_notes: - The :ref:`ancyc` command is valid in a `modal cyclic symmetryanalysis + The :ref:`ancyc` command is valid in a `modal cyclic symmetry analysis `_ only. @@ -174,7 +174,7 @@ def ancyc( wave animation is applicable only to nodal diameters (harmonic indices) greater than 0 and less than ``N`` / 2 (where ``N`` is the number of cyclic sectors in the model). - For more information, see `Applying a Traveling Wave Animation to theCyclic Model + For more information, see `Applying a Traveling Wave Animation to the Cyclic Model `_ in the `Cyclic Symmetry Analysis Guide `_. diff --git a/src/ansys/mapdl/core/_commands/post1/element_table.py b/src/ansys/mapdl/core/_commands/post1/element_table.py index 223307f963..b9791518b6 100644 --- a/src/ansys/mapdl/core/_commands/post1/element_table.py +++ b/src/ansys/mapdl/core/_commands/post1/element_table.py @@ -181,7 +181,7 @@ def etable( into the element table for further "worksheet" manipulation. (See `Getting Started `_ ``Item`` and ``Comp`` labels for the component name method is shown in :ref:`ETABLE_tab_1`. See - :ref:`ETABLE_tab_2`for a list of selected result ( ``Item`` = SRES) ``Comp`` labels. + :ref:`ETABLE_tab_2` for a list of selected result ( ``Item`` = SRES) ``Comp`` labels. The sequence number method enables you to view results for data that is not averaged (such as pressures at nodes, temperatures at integration points, etc.), or data that is not easily described diff --git a/src/ansys/mapdl/core/_commands/post1/listing.py b/src/ansys/mapdl/core/_commands/post1/listing.py index 33f2627145..1c8f873321 100644 --- a/src/ansys/mapdl/core/_commands/post1/listing.py +++ b/src/ansys/mapdl/core/_commands/post1/listing.py @@ -258,7 +258,7 @@ def prerr(self, **kwargs): The structural approximation is based on the energy error (which is similar in concept to the strain energy) and represents the error associated with the discrepancy between the calculated stress field - and the globally continuous stress field (see `POST1 - Error ApproximationTechnique + and the globally continuous stress field (see `POST1 - Error Approximation Technique `_ in the `Mechanical APDL Theory Reference `_). This diff --git a/src/ansys/mapdl/core/_commands/post1/load_case_calculations.py b/src/ansys/mapdl/core/_commands/post1/load_case_calculations.py index 5b1f8ec9e0..9ae4d27d85 100644 --- a/src/ansys/mapdl/core/_commands/post1/load_case_calculations.py +++ b/src/ansys/mapdl/core/_commands/post1/load_case_calculations.py @@ -99,7 +99,7 @@ def lcdef( ---------- lcno : str Arbitrary pointer number (1-99) to be assigned to the load case specified by ``LSTEP``, - ``SBSTEP`` and by the :ref:`file` command. Defaults to 1 + previous value. + ``SBSTEP`` and by the ``FILE`` command. Defaults to 1 + previous value. lstep : str Load step number to be defined as the load case. Defaults to one. diff --git a/src/ansys/mapdl/core/_commands/post1/magnetics_calculations.py b/src/ansys/mapdl/core/_commands/post1/magnetics_calculations.py new file mode 100644 index 0000000000..de95af266c --- /dev/null +++ b/src/ansys/mapdl/core/_commands/post1/magnetics_calculations.py @@ -0,0 +1,306 @@ +# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + + +class MagneticsCalculations: + + def curr2d(self, **kwargs): + r"""Calculates current flow in a 2D conductor. + + Mechanical APDL Command: `CURR2D `_ + + Notes + ----- + + .. _CURR2D_notes: + + :ref:`curr2d` invokes a macro which calculates the total current flowing in a conducting body for a + 2D planar or axisymmetric magnetic field analysis. The currents may be applied source currents or + induced currents (eddy currents). The elements of the conducting region must be selected before this + command is issued. The total current calculated by the macro is stored in the parameter TCURR. Also, + the total current and total current density are stored on a per-element basis in the element table ( + :ref:`etable` ) with the labels TCURR and JT, respectively. Use the :ref:`pletab` and :ref:`pretab` + commands to plot and list the element table items. + """ + command = "CURR2D" + return self.run(command, **kwargs) + + def emagerr(self, **kwargs): + r"""Calculates the relative error in an electrostatic or electromagnetic field analysis. + + Mechanical APDL Command: `EMAGERR `_ + + Notes + ----- + + .. _EMAGERR_notes: + + The relative error is an approximation of the mesh discretization error associated with a solution. + It is based on the discrepancy between the unaveraged, element-nodal field values and the averaged, + nodal field values. The calculation is valid within a material boundary and does not consider the + error in continuity of fields across dissimilar materials. + + For electrostatics, the field values evaluated are the electric field strength (EFSUM) and the + electric flux density (DSUM). A relative error norm of each is calculated on a per-element basis and + stored in the element table ( :ref:`etable` ) with the labels EF_ERR and D_ERR. Normalized error + values EFN_ERR and DN_ERR are also calculated and stored in the element table. Corresponding + quantities for electromagnetics are H_ERR, B_ERR, HN_ERR, and BN_ERR, which are calculated from the + magnetic field intensity (HSUM) and the magnetic flux density (BSUM). The normalized error value is + the relative error norm value divided by the peak element-nodal field value for the currently + selected elements. + + Use the :ref:`pletab` and :ref:`pretab` commands to plot and list the error norms and normalized + error values. + """ + command = "EMAGERR" + return self.run(command, **kwargs) + + def emf(self, **kwargs): + r"""Calculates the electromotive force (emf), or voltage drop along a predefined path. + + Mechanical APDL Command: `EMF `_ + + Notes + ----- + + .. _EMF_notes: + + :ref:`emf` invokes a Mechanical APDL macro which calculates the electromotive force (emf), or + voltage drop + along a predefined path (specified with the :ref:`path` command). It is valid for both 2D and 3D + electric field analysis. The calculated emf value is stored in the parameter EMF. + + You must define a line path (via the :ref:`path` command) before issuing the :ref:`emf` command + macro. The macro uses calculated values of the electric field (EF), and uses path operations for the + calculations. All path items are cleared when the macro finishes executing. + + The :ref:`emf` macro sets the "ACCURATE" mapping method and "MAT" discontinuity option on the + :ref:`pmap` command. The program retains these settings after executing the macro. + """ + command = "EMF" + return self.run(command, **kwargs) + + def emft(self, **kwargs): + r"""Summarizes electromagnetic forces and torques. + + Mechanical APDL Command: `EMFT `_ + + Notes + ----- + Use this command to summarize electromagnetic force and torque in both static electric and magnetic + problems. To use this command, select the nodes in the region of interest and make sure that all + elements are selected. If :ref:`rsys` = 0, the force is reported in the global Cartesian coordinate + system. If :ref:`rsys` ≠ 0, force is reported in the specified coordinate system. However, for + torque, if :ref:`rsys` ≠ 0, this command will account for the shift and rotation as specified by + :ref:`rsys`, but will report only the Cartesian components. + + Forces are stored as items _FXSUM, _FYSUM, _FZSUM, and _FSSUM. Torque is stored as items _TXSUM, + _TYSUM, _TZSUM, and _TSSUM. + + This command is valid only with ``PLANE121``, ``SOLID122``, ``SOLID123``, ``PLANE222``, + ``PLANE223``, ``SOLID225``, ``SOLID226``, ``SOLID227``, ``PLANE233``, ``SOLID236`` and ``SOLID237`` + elements. + """ + command = "EMFT" + return self.run(command, **kwargs) + + def fluxv(self, **kwargs): + r"""Calculates the flux passing through a closed contour. + + Mechanical APDL Command: `FLUXV `_ + + Notes + ----- + + .. _FLUXV_notes: + + :ref:`fluxv` invokes a Mechanical APDL macro which calculates the flux passing through a closed + contour + (path) predefined by :ref:`path`. + + The calculated flux is stored in the parameter FLUX. + + In a 2D analysis, at least two nodes must be defined on the path. In 3D, a path of nodes describing + a closed contour must be specified (that is, the first and last node in the path specification must + be the same). + + A counterclockwise ordering of nodes on the :ref:`ppath` command gives the correct sign on flux. + + Path operations are used for the calculations, and all path items are cleared upon completion. + + This macro is available for vector potential formulations only. + """ + command = "FLUXV" + return self.run(command, **kwargs) + + def mmf(self, **kwargs): + r"""Calculates the magnetomotive force along a path. + + Mechanical APDL Command: `MMF `_ + + Notes + ----- + + .. _MMF_notes: + + :ref:`mmf` invokes a Mechanical APDL macro which calculates the magnetomotive force (mmf) along a + predefined path ( :ref:`path` ). It is valid for both 2D and 3D magnetic field analyses. The + calculated mmf value is stored in the parameter MMF. + + A closed path ( :ref:`path` ), passing through the magnetic circuit for which mmf is to be + calculated, must be defined before this command is issued. A counterclockwise ordering of points on + the :ref:`ppath` command will yield the correct sign on the mmf. The mmf is based on Ampere's Law. + The macro makes use of calculated values of field intensity (H), and uses path operations for the + calculations. All path items are cleared upon completion. The :ref:`mmf` macro sets the "ACCURATE" + mapping method and "MAT" discontinuity option of the :ref:`pmap` command. + """ + command = "MMF" + return self.run(command, **kwargs) + + def plf2d( + self, + ncont: str = "", + olay: int | str = "", + anum: str = "", + win: str = "", + **kwargs, + ): + r"""Generates a contour line plot of equipotentials. + + Mechanical APDL Command: `PLF2D `_ + + Parameters + ---------- + ncont : str + Number of contour lines to display. Issue in multiples of 9 (that is, 9, 18, 27, etc.). Default + is 27 contour lines. + + olay : int or str + Overlay: + + * ``0`` - Overlay edge outlines by material number. + + * ``1`` - Overlay edge outlines by real constant number. + + anum : str + Highest material or real constant attribute number. Command will cycle through ``ANUM`` element + display overlays. Defaults to 10. + + win : str + Window number to which command applies. Defaults to 1. + + Notes + ----- + + .. _PLF2D_notes: + + :ref:`plf2d` invokes a Mechanical APDL macro which plots equipotentials of the degree of freedom AZ. + The + equipotential lines are parallel to flux lines and thus give a good representation of flux patterns. + + In the axisymmetric case, the display is actually r * AZ where r is the node radius. + + The macro overlays ( ``OLAY`` ) edge outlines by material number or real constant number ( ``ANUM`` + ) and enables you to control the number of contour lines to display ( ``NCONT`` ). + """ + command = f"PLF2D,{ncont},{olay},{anum},{win}" + return self.run(command, **kwargs) + + def powerh(self, **kwargs): + r"""Calculates the rms power loss in a conductor or lossy dielectric. + + Mechanical APDL Command: `POWERH `_ + + Notes + ----- + + .. _POWERH_notes: + + :ref:`powerh` invokes a Mechanical APDL macro which calculates the time-averaged (rms) power loss in + a + conductor or lossy dielectric material from a harmonic analysis. The power loss is stored in the + parameter PAVG. + + Conductor losses include solid conductors and surface conductors approximated by impedance or + shielding boundary conditions. The power-loss density for solid conductors or dielectrics is + stored in the element table with the label PLOSSD and may be listed ( :ref:`pretab` ) or displayed ( + :ref:`pletab` ). PLOSSD does not include surface losses. + + The elements of the conducting region must be selected before this command is issued. + + :ref:`powerh` is valid for 2D and 3D analyses. + """ + command = "POWERH" + return self.run(command, **kwargs) + + def senergy(self, opt: int | str = "", antype: int | str = "", **kwargs): + r"""Determines the stored magnetic energy or co-energy. + + Mechanical APDL Command: `SENERGY `_ + + Parameters + ---------- + opt : int or str + Item to be calculated: + + * ``0`` - Stored magnetic energy. + + * ``1`` - Stored magnetic co-energy. + + antype : int or str + Analysis type: + + * ``0`` - Static or transient. + + * ``1`` - Harmonic. + + Notes + ----- + + .. _SENERGY_notes: + + :ref:`senergy` invokes a Mechanical APDL macro which calculates the stored magnetic energy or co- + energy for + all selected elements. (For a harmonic analysis, the macro calculates a time-averaged (rms) stored + energy.) + + A summary table listing the energy by material number is generated. The energy density is also + calculated and stored on a per-element basis in the element table ( :ref:`etable` ) with the label + MG_ENG (energy density) or MG_COENG (co-energy density). The macro erases all other items in the + element table and retains only the energy density or co-energy density. + + Issue :ref:`pletab` and :ref:`pretab` to plot and list the energy density. + + The macro is valid for static and low-frequency magnetic field formulations. + + The macro will not calculate stored energy and co-energy for the following cases: + + * Orthotropic nonlinear permanent magnets. + + * Orthotropic nonlinear permeable materials. + + * Temperature dependent materials. + + :ref:`senergy` is restricted to MKSA units. + """ + command = f"SENERGY,{opt},{antype}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1/path_operations.py b/src/ansys/mapdl/core/_commands/post1/path_operations.py new file mode 100644 index 0000000000..8b85c707ee --- /dev/null +++ b/src/ansys/mapdl/core/_commands/post1/path_operations.py @@ -0,0 +1,1428 @@ +# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + + +class PathOperations: + + def fssect( + self, + rho: str = "", + nev: str = "", + nlod: str = "", + kbr: int | str = "", + **kwargs, + ): + r"""Calculates and stores total linearized stress components. + + Mechanical APDL Command: `FSSECT `_ + + Parameters + ---------- + rho : str + In-plane (X-Y) average radius of curvature of the inside and outside surfaces of an axisymmetric + section. If zero (or blank), a plane or 3D structure is assumed. If nonzero, an axisymmetric + structure is assumed. Use a suitably large number (see the `Mechanical APDL Theory Reference + `_) or use -1 + for an axisymmetric straight section. + + nev : str + Event number to be associated with these stresses (defaults to 1). + + nlod : str + Loading number to be associated with these stresses (defaults to 1). + + kbr : int or str + For an axisymmetric analysis ( ``RHO`` ≠ 0): + + * ``0`` - Include the thickness-direction bending stresses + + * ``1`` - Ignore the thickness-direction bending stresses + + * ``2`` - Include the thickness-direction bending stress using the same formula as the Y (axial + direction ) bending stress. Also use the same formula for the shear stress. + + Notes + ----- + + .. _FSSECT_notes: + + Calculates and stores the total linearized stress components at the ends of a section path ( + :ref:`path` ) (as defined by the first two nodes with the :ref:`ppath` command). The path must be + entirely within the selected elements (that is, there must not be any element gaps along the path). + Stresses are stored according to the fatigue event number and loading number specified. Locations + (one for each node) are associated with those previously defined for these nodes (FL) or else they + are automatically defined. Stresses are separated into six total components (SX through SXZ) and six + membrane-plus-bending (SX through SXZ) components. The temperature at each end point and the current + time are also stored along with the total stress components. Calculations are made from the stresses + currently in the database (last :ref:`set` or :ref:`lcase` command). Stresses are stored as section + coordinate components if axisymmetric or as global Cartesian coordinate components otherwise, + regardless of the active results coordinate system ( :ref:`rsys` ). The FSLIST command may be used + to list stresses. The FS command can be used to modify stored stresses. See also the :ref:`prsect` + and :ref:`plsect` commands for similar calculations. + """ + command = f"FSSECT,{rho},{nev},{nlod},{kbr}" + return self.run(command, **kwargs) + + def padele(self, delopt: str = "", **kwargs): + r"""Deletes a defined path. + + Mechanical APDL Command: `PADELE `_ + + **Command default:** + + .. _PADELE_default: + + Deletes the currently active path. + + Parameters + ---------- + delopt : str + Path delete option (one of the following): + + * ``ALL`` - Delete all defined paths. + + * ``NAME`` - Delete a specific path from the list of path definitions. (Substitute the actual path + name for NAME.) + + Notes + ----- + + .. _PADELE_notes: + + Paths are identified by individual path names. To review the current list of path names, issue the + command :ref:`path`,STATUS. + + This command is valid in the general postprocessor. + """ + command = f"PADELE,{delopt}" + return self.run(command, **kwargs) + + def paget(self, parray: str = "", popt: str = "", **kwargs): + r"""Writes current path information into an array variable. + + Mechanical APDL Command: `PAGET `_ + + Parameters + ---------- + parray : str + The name of the array parameter that Mechanical APDL creates to store the path information. If + the array parameter already exists, it will be replaced with the current path information. + + popt : str + Determines how data will be stored in the parameter specified with ``PARRAY`` : + + * ``POINTS`` - Store the path points, the nodes (if any), and coordinate system. (For information on + defining paths and path points, see the descriptions of the :ref:`path` and :ref:`ppath` commands.) + + * ``TABLE`` - Store the path data items. (See the :ref:`pdef` command description for path data + items.) + + * ``LABEL`` - Stores path data labels. + + Notes + ----- + + .. _PAGET_notes: + + Use the :ref:`paget` command with the :ref:`paput` command to store and retrieve path data in array + variables for archiving purposes. + + When retrieving path information, restore the path points (POINTS option) first, then the path data + (TABLE option), and then the path labels (LABEL option). + """ + command = f"PAGET,{parray},{popt}" + return self.run(command, **kwargs) + + def paput(self, parray: str = "", popt: str = "", **kwargs): + r"""Retrieves path information from an array variable. + + Mechanical APDL Command: `PAPUT `_ + + Parameters + ---------- + parray : str + Name of the array variable containing the path information. + + popt : str + Specifies which path data to retrieve: + + * ``POINTS`` - Retrieve path point information (specified with the :ref:`ppath` command and stored + with the :ref:`paget`,POINTS command). The path data name will be assigned to the path points. + + * ``TABLE`` - Retrieve path data items (defined via the :ref:`pdef` command and stored with the + :ref:`paget`,,TABLE command). + + * ``LABEL`` - Retrieve path labels stored with the :ref:`paget`,,LABEL command. + + Notes + ----- + + .. _PAPUT_notes: + + When retrieving path information, restore path points (POINTS option) first, then the path data + (TABLE option), and then the path labels (LABEL option). + """ + command = f"PAPUT,{parray},{popt}" + return self.run(command, **kwargs) + + def paresu(self, lab: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Restores previously saved paths from a file. + + Mechanical APDL Command: `PARESU `_ + + Parameters + ---------- + lab : str + Read operation: + + * ``ALL`` - Read all paths from the selected file (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 :file:`Jobname`. + + ext : str + Filename extension (eight-character maximum). The extension defaults to PATH if ``Fname`` is + blank. + + Notes + ----- + + .. _PARESU_notes: + + This command removes all paths from virtual memory and then reads path data from a file written with + the :ref:`pasave` command. All paths on the file will be restored. All paths currently in memory + will be deleted. + """ + command = f"PARESU,{lab},{fname},{ext}" + return self.run(command, **kwargs) + + def pasave(self, lab: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Saves selected paths to an external file. + + Mechanical APDL Command: `PASAVE `_ + + Parameters + ---------- + lab : str + Write operation: + + * ``S`` - Saves only selected paths. + + * ``ALL`` - Saves all paths (default). + + * ``Pname`` - Saves the named path (from the :ref:`psel` command). + + fname : str + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, + you can use all 248 characters for the file name. + + The file name defaults to :file:`Jobname`. + + ext : str + Filename extension (eight-character maximum). + + The extension defaults to PATH if ``Fname`` is blank. + + Notes + ----- + + .. _PASAVE_notes: + + Saves the paths selected with the :ref:`psel` command to an external file (default + :file:`Jobname.path` ). + + Previous paths on this file, if any, are overwritten. The path file can be read via :ref:`paresu`. + + This command is valid in POST1. + """ + command = f"PASAVE,{lab},{fname},{ext}" + return self.run(command, **kwargs) + + def path( + self, name: str = "", npts: str = "", nsets: str = "", ndiv: str = "", **kwargs + ): + r"""Defines a path name and establishes parameters for the path. + + Mechanical APDL Command: `PATH `_ + + Parameters + ---------- + name : str + Name for this path (eight characters maximum. If ``nPts`` is blank, set the current path to the + path with this name. If ``nPts`` is greater than zero, create a path of this name. If a path + with this name already exists, replace it with a new path. If the ``NAME`` value is STATUS, + display the status for path settings. + + npts : str + The number of points used to define this path. The minimum number is two, and the maximum is + 1000. Default is 2. + + nsets : str + The number of sets of data which you can map to this path. You must specify at least four: X, Y, + Z, and S. Default is 30. + + ndiv : str + The number of divisions between adjacent points. Default is 20. There is no maximum number of + divisions. + + Notes + ----- + + .. _PATH_notes: + + The :ref:`path` command is used to define parameters for establishing a path. The path geometry is + created by the :ref:`ppath` command. Multiple paths may be defined and named; however, only one path + may be active for data interpolation ( :ref:`pdef` ) and data operations ( :ref:`pcalc`, etc.). Path + geometry points and data are stored in memory while in POST1. If you leave POST1, the path + information is erased. Path geometry and data may be saved in a file by archiving the data using the + :ref:`pasave` command. Path information may be restored by retrieving the data using the + :ref:`paresu` command. + + For overlapping nodes, the lowest numbered node is assigned to the path. + + The number of divisions defined using ``nDiv`` does NOT affect the number of divisions used by + :ref:`plsect` and :ref:`prsect`. + + For information on displaying paths you have defined, see `Mapping Results onto a Path + `_ + """ + command = f"PATH,{name},{npts},{nsets},{ndiv}" + return self.run(command, **kwargs) + + def pcalc( + self, + oper: str = "", + labr: str = "", + lab1: str = "", + lab2: str = "", + fact1: str = "", + fact2: str = "", + const: str = "", + **kwargs, + ): + r"""Forms additional labeled path items by operating on existing path items. + + Mechanical APDL Command: `PCALC `_ + + Parameters + ---------- + oper : str + Type of operation to be performed. See :ref:`PCALC_notes` below for specific descriptions of each operation: + + * ``ADD`` - Adds two existing path items. + + * ``MULT`` - Multiplies two existing path items. + + * ``DIV`` - Divides two existing path items (a divide by zero results in a value of zero). + + * ``EXP`` - Exponentiates and adds existing path items. + + * ``DERI`` - Finds a derivative. + + * ``INTG`` - Finds an integral. + + * ``SIN`` - Sine. + + * ``COS`` - Cosine. + + * ``ASIN`` - Arcsine. + + * ``ACOS`` - Arccosine. + + * ``LOG`` - Natural log. + + labr : str + Label assigned to the resulting path item. + + lab1 : str + First labeled path item in operation. + + lab2 : str + Second labeled path item in operation. ``Lab2`` must not be blank for the MULT, DIV, DERI, and + INTG operations. + + fact1 : str + Factor applied to ``Lab1``. A (blank) or '0' entry defaults to 1.0. + + fact2 : str + Factor applied to ``Lab2``. A (blank) or '0' entry defaults to 1.0. + + const : str + Constant value (defaults to 0.0). + + Notes + ----- + + .. _PCALC_notes: + + If ``Oper`` = ADD, the command format is: + + :ref:`pcalc`,ADD, ``LabR``, ``Lab1``, ``Lab2``, ``FACT1``, ``FACT2``, ``CONST`` + + This operation adds two existing path items according to the operation: + + ``LabR`` = ( ``FACT1`` x ``Lab1`` ) + ( ``FACT2`` x ``Lab2`` ) + ``CONST`` + + It may be used to scale the results for a single path item. + + If ``Oper`` = MULT, the command format is: + + :ref:`pcalc`,MULT, ``LabR``, ``Lab1``, ``Lab2``, ``FACT1`` + + ``Lab2`` must not be blank. This operation multiplies two existing path items according to the + operation: + + ``LabR`` = ``Lab1`` x ``Lab2`` x ``FACT1`` + + If ``Oper`` = DIV, the command format is: + + :ref:`pcalc`,DIV, ``LabR``, ``Lab1``, ``Lab2``, ``FACT1`` + + ``Lab2`` must not be blank. This operation divides two existing path items according to the + operation: + + ``LabR`` = ( ``Lab1`` / ``Lab2`` ) x ``FACT1`` + + If ``Oper`` = EXP, the command format is: + + :ref:`pcalc`,EXP, ``LabR``, ``Lab1``, ``Lab2``, ``FACT1``, ``FACT2`` + + This operation exponentiates and adds existing path items according to the operation: + + ``LabR`` = (\| ``Lab1`` \| :sup:`FACT1` ) + (\| ``Lab2`` \| :sup:`FACT2` \|) + + If ``Oper`` = DERI, the command format is: + + :ref:`pcalc`,DERI, ``LabR``, ``Lab1``, ``Lab2``, ``FACT1`` + + ``Lab2`` must not be blank. This operation finds a derivative according to the operation: + + ``LabR`` = ``FACT1`` x d( ``Lab1`` )/d( ``Lab2`` ) + + If ``Oper`` = INTG, the command format is: + + :ref:`pcalc`,INTG, ``LabR``, ``Lab1``, ``Lab2``, ``FACT1`` + + ``Lab2`` must not be blank. This operation finds an integral according to the operation: + + .. math:: + + equation_not_available + + Use S for ``Lab2`` to integrate ``Lab1`` with respect to the path length. S, the distance along the + path, is automatically calculated by the program when a path item is created with the :ref:`pdef` + command. + + If ``Oper`` = SIN, COS, ASIN, ACOS, or LOG, the command format is: + + :ref:`pcalc`,Oper, ``LabR``, ``Lab1``, ``FACT1``, ``CONST`` + + where the function (SIN, COS, ASIN, ACOS or LOG) is substituted for ``Oper`` and ``Lab2`` is blank. + + The operation finds the resulting path item according to one of the following formulas: + + ``LabR`` = FACT2 x ``sin(FACT1 x Lab1) + CONST`` + + ``LabR`` = FACT2 x ``cos(FACT1 x Lab1) + CONST`` + + ``LabR`` = FACT2 x ``sin`` -1(FACT1 x Lab1) + CONST + + ``LabR`` = FACT2 x ``cos`` -1(FACT1 x Lab1) + CONST + + ``LabR`` = FACT2 x ``log(FACT1 x Lab1) + CONST`` + + """ + command = f"PCALC,{oper},{labr},{lab1},{lab2},{fact1},{fact2},{const}" + return self.run(command, **kwargs) + + def pcross( + self, + labxr: str = "", + labyr: str = "", + labzr: str = "", + labx1: str = "", + laby1: str = "", + labz1: str = "", + labx2: str = "", + laby2: str = "", + labz2: str = "", + **kwargs, + ): + r"""Calculates the cross product of two path vectors along the current path. + + Mechanical APDL Command: `PCROSS `_ + + Parameters + ---------- + labxr : str + Label assigned to X-component of resultant vector. + + labyr : str + Label assigned to Y-component of resultant vector. + + labzr : str + Label assigned to Z-component of resultant vector. + + labx1 : str + X-component of first vector label (labeled path item). + + laby1 : str + Y-component of first vector label. + + labz1 : str + Z-component of first vector label. + + labx2 : str + X-component of second vector label (labeled path item). + + laby2 : str + Y-component of second vector label. + + labz2 : str + Z-component of second vector label. + """ + command = f"PCROSS,{labxr},{labyr},{labzr},{labx1},{laby1},{labz1},{labx2},{laby2},{labz2}" + return self.run(command, **kwargs) + + def pdef( + self, lab: str = "", item: str = "", comp: str = "", avglab: str = "", **kwargs + ): + r"""Interpolates an item onto a path. + + Mechanical APDL Command: `PDEF `_ + + Parameters + ---------- + lab : str + Label assigned to the resulting path item (8 characters maximum). This item may be used as input + for other path operations. + + item : str + Label identifying the item for interpolation. Valid item labels are shown in :ref:`pdef_tab_1` + below. Some items also require a component label. + + comp : str + Component of the item (if required). Valid component labels are shown in :ref:`pdef_tab_1` + below. + + avglab : str + Option to average across element boundaries: + + * ``AVG`` - Average element results across elements (default). + + * ``NOAV`` - Do not average element results across elements. If the parameter ``DISCON`` = MAT on + the :ref:`pmap` command, this option is automatically invoked. + + Notes + ----- + + .. _PDEF_notes: + + Defines and interpolates a labeled path item along a predefined path ( :ref:`path` ). Path item + results are in the global Cartesian coordinate directions unless transformed ( :ref:`rsys` ). A path + item must be defined before it can be used with other path operations. Additional path items may be + defined from the :ref:`pvect`, :ref:`pcalc`, :ref:`pdot`, and :ref:`pcross` commands. Path items may + be listed ( :ref:`prpath` ) or displayed ( :ref:`plpath`, :ref:`plpagm` ). A maximum number of path + items permitted is established by the ``nSets`` argument specified with the :ref:`path` command. + + When you create the first path item ( :ref:`pdef` or :ref:`pvect` ), the program automatically + interpolates four path items which are used to describe the geometry of the path. These predefined + items are the position of the interpolated path points (labels XG, YG, and ZG) in global Cartesian + coordinates, and the path length (label S). For alternate methods of mapping the path geometry (to + include, for example, material discontinuity) see the :ref:`pmap` command. These items may also be + listed or displayed with the :ref:`prpath`, :ref:`plpath`, and :ref:`plpagm` commands. + + .. _Onyx27480: + + If specifying that load case operations act on principal/equivalent stresses ( :ref:`sumtype`,PRIN), + derived quantities (principal and equivalent stresses/strains) will be zero for path plots. A + typical use for such a case involves mode combinations in a response spectrum analysis. + + The number of interpolation points on the path is defined by the ``nDiv`` argument on the + :ref:`path` command. See `Mapping Nodal and Element Data onto the Path + `_ + :ref:`pdef`,STAT to list the path item labels. Use :ref:`pdef`,CLEAR to erase all labeled path + items, except the path geometry items (XG, YG, ZG, S). + + See also `Mapping Results onto a Path + `_ + + .. _pdef_tab_1: + + PDEF - Valid Item and Component Labels + ************************************** + + .. flat-table:: + :header-rows: 1 + + * - Item + - Comp + - Description + * - Valid item and component labels for nodal degree of freedom results are: + * - U + - X, Y, Z, SUM + - X, Y, or Z structural displacement or vector sum. + * - ROT + - X, Y, Z, SUM + - X, Y, or Z structural rotation or vector sum. + * - TEMP[ :ref:`PDEF_temp` ] + - + - Temperature. + * - PRES + - + - Pressure. + * - VOLT + - + - Electric potential. + * - MAG + - + - Magnetic scalar potential. + * - V + - X, Y, Z, SUM + - X, Y, or Z fluid velocity or vector sum. + * - A + - X, Y, Z, SUM + - X, Y, or Z magnetic vector potential or vector sum. + * - CONC + - + - Concentration. + * - CURR + - + - Current. + * - EMF + - + - Electromotive force drop. + * - Valid item and component labels for element results are: + * - 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. + * - For contact results PowerGraphics is applicable for 3D models only. + * - CONT + - STAT :ref:`PDEFcontstat` + - Contact status. + * - " + - PENE + - Contact penetration. + * - " + - PRES + - Contact pressure. + * - " + - SFRIC + - Contact friction stress. + * - " + - STOT + - Contact total stress (pressure plus friction). + * - " + - SLIDE + - Contact sliding distance. + * - " + - GAP + - Contact gap distance. + * - " + - FLUX + - Total heat flux at contact surface. + * - TG + - X, Y, Z, SUM + - Component thermal gradient or vector sum. + * - TF + - X, Y, Z, SUM + - Component thermal flux or vector sum. + * - PG + - X, Y, Z, SUM + - Component pressure gradient or vector sum. + * - EF + - X, Y, Z, SUM + - Component electric field or vector sum. + * - D + - X, Y, Z, SUM + - Component electric flux density or vector sum. + * - JC + - X, Y, Z, SUM + - Component conduction current density or vector sum (for elements that support conduction current calculation) + * - H + - X, Y, Z, SUM + - Component magnetic field intensity or vector sum. + * - B + - X, Y, Z, SUM + - Component magnetic flux density or vector sum. + * - CG + - X, Y, Z, SUM + - Component concentration gradient or vector sum + * - DF + - X, Y, Z, SUM + - Component diffusion flux density or vector sum + * - FMAG + - X, Y, Z, SUM + - Component electromagnetic force or vector sum. + * - ETAB + - Lab + - Any user-defined element table label (see :ref:`etable` command). + * - BFE + - TEMP + - Applied and calculated temperatures along a defined path. + * - SPL + - + - Sound pressure level. + * - SPLA + - + - A-weighted sound pressure level (dBA). + + .. _PDEF_temp: + + For ``SHELL131`` and ``SHELL132`` elements with KEYOPT(3) = 0 or 1, use the labels TBOT, TE2, + TE3,..., TTOP instead of TEMP. + + .. _PDEFcontstat: + + For more information on the meaning of contact status and its possible values, see `Reviewing + Results in POST1 + `_ + """ + command = f"PDEF,{lab},{item},{comp},{avglab}" + return self.run(command, **kwargs) + + def pdot( + self, + labr: str = "", + labx1: str = "", + laby1: str = "", + labz1: str = "", + labx2: str = "", + laby2: str = "", + labz2: str = "", + **kwargs, + ): + r"""Calculates the dot product of two path vectors along the current path. + + Mechanical APDL Command: `PDOT `_ + + Parameters + ---------- + labr : str + Label assigned to dot product result. + + labx1 : str + X-component of first vector label (labeled path item). + + laby1 : str + Y-component of first vector label (labeled path item). + + labz1 : str + Z-component of first vector label (labeled path item). + + labx2 : str + X-component of second vector label (labeled path item). + + laby2 : str + Y-component of second vector label (labeled path item). + + labz2 : str + Z-component of second vector label (labeled path item). + """ + command = f"PDOT,{labr},{labx1},{laby1},{labz1},{labx2},{laby2},{labz2}" + return self.run(command, **kwargs) + + def plpagm(self, item: str = "", gscale: str = "", nopt: str = "", **kwargs): + r"""Displays path items along the path geometry. + + Mechanical APDL Command: `PLPAGM `_ + + Parameters + ---------- + item : str + The path data item to be displayed on the currently active path (defined by the :ref:`path` + command). Valid path items are those defined with the :ref:`pdef` or :ref:`plnear` commands. + + gscale : str + Scale factor for the offset from the path for the path data item displays. Defaults to 1.0. + + nopt : str + Determines how data is displayed: + + * ``(blank)`` - Do not display nodes, and scale the display based on the currently selected node set + (default). + + * ``NODE`` - Display path item data along with the currently selected set of nodes. The display + geometry is scaled to the selected node set. + + Notes + ----- + + .. _PLPAGM_notes: + + You can use the ``Gscale`` argument to scale the contour display offset from the path for clarity. + You need to type all six characters to issue this command. + + Fore more information, see `Mapping Results onto a Path + `_ + """ + command = f"PLPAGM,{item},{gscale},{nopt}" + return self.run(command, **kwargs) + + def plpath( + self, + lab1: str = "", + lab2: str = "", + lab3: str = "", + lab4: str = "", + lab5: str = "", + lab6: str = "", + **kwargs, + ): + r"""Displays path items on a graph. + + Mechanical APDL Command: `PLPATH `_ + + Parameters + ---------- + lab1 : str + Labels identifying the path items to be displayed. Up to six items may be drawn per frame. + Predefined path geometry items XG, YG, ZG, and S ( :ref:`pdef` ) may also be displayed. + + lab2 : str + Labels identifying the path items to be displayed. Up to six items may be drawn per frame. + Predefined path geometry items XG, YG, ZG, and S ( :ref:`pdef` ) may also be displayed. + + lab3 : str + Labels identifying the path items to be displayed. Up to six items may be drawn per frame. + Predefined path geometry items XG, YG, ZG, and S ( :ref:`pdef` ) may also be displayed. + + lab4 : str + Labels identifying the path items to be displayed. Up to six items may be drawn per frame. + Predefined path geometry items XG, YG, ZG, and S ( :ref:`pdef` ) may also be displayed. + + lab5 : str + Labels identifying the path items to be displayed. Up to six items may be drawn per frame. + Predefined path geometry items XG, YG, ZG, and S ( :ref:`pdef` ) may also be displayed. + + lab6 : str + Labels identifying the path items to be displayed. Up to six items may be drawn per frame. + Predefined path geometry items XG, YG, ZG, and S ( :ref:`pdef` ) may also be displayed. + + Notes + ----- + + .. _PLPATH_notes: + + The path must have been defined by the :ref:`path` and :ref:`ppath` commands. Path items and their + labels must have been defined with the :ref:`pdef`, :ref:`pvect`, :ref:`pcalc`, :ref:`pdot`, + :ref:`pcross`, or :ref:`plnear` commands. Path items may also be printed with the :ref:`prpath` + command. Graph scaling may be controlled with the :ref:`xrange`, :ref:`yrange`, and :ref:`prange` + commands. You need to type all six characters to issue this command. + + Fore more information, see `Mapping Results onto a Path + `_ + """ + command = f"PLPATH,{lab1},{lab2},{lab3},{lab4},{lab5},{lab6}" + return self.run(command, **kwargs) + + def plsect( + self, + item: str = "", + comp: str = "", + rho: str = "", + kbr: int | str = "", + kbr3d: int | str = "", + **kwargs, + ): + r"""Displays membrane and membrane-plus-bending linearized stresses. + + Mechanical APDL Command: `PLSECT `_ + + Parameters + ---------- + item : str + Label identifying the item to be processed. Valid item labels are shown in :ref:`plsect_tab_1` + below. Items also require a component label. + + comp : str + Component of the item. Valid component labels are shown in :ref:`plsect_tab_1` below. + + rho : str + In-plane (X-Y) average radius of curvature of the inside and outside surfaces of an axisymmetric + section. If zero (or blank), a plane or 3D structure is assumed. If nonzero, an axisymmetric + structure is assumed. Use a very large number (or -1) for an axisymmetric straight section. + + kbr : int or str + Through-thickness bending stresses key for an axisymmetric analysis ( ``RHO`` ≠ 0): + + * ``0`` - Include the thickness-direction bending stresses. + + * ``1`` - Ignore the thickness-direction bending stresses. + + * ``2`` - Include the thickness-direction bending stress using the same formula as the Y (axial + direction ) bending stress. Also use the same formula for the shear stress. + + kbr3d : int or str + Through-thickness bending stresses key for 3D geometry ( ``RHO`` = 0): + + * ``0`` - Include the thickness-direction bending stresses. + + * ``1`` - Ignore the following thickness-direction bending stresses: SX, SXY, SXZ + + Notes + ----- + + .. _PLSECT_notes: + + Calculates and displays the membrane and membrane-plus-bending linearized stresses (as described for + the :ref:`prsect` command) along a path section ( :ref:`path` ) as a graph. The path section is + defined by two points specified with the :ref:`ppath` command. For linearized stress calculations, + the path must be defined with nodes. The path must be entirely within the selected elements (that + is, there must not be any element gaps along the path). The total stress (equivalent to the + :ref:`plpath` display) is also displayed. This command always uses 48 divisions along the path, + regardless of the number of divisions defined by :ref:`path`. + + In analyses of 3D models with ``RHO`` = 0, ignoring the calculated out-of-plane bending stresses is + recommended in some scenarios when determining the linearized bending stresses. If ``KBR3D`` = 0, + all calculated stresses are included in the linearized bending-stress calculations. If ``KBR3D`` = + 1, these calculated out-of-plane bending stresses are ignored in the linearized bending-stress + calculations: SX, SXY, SXZ. (The principal bending-stress calculation for S1, S2, S3, SINT, and SEQV + is performed with these zeroed components.) + + Portions of this command are not supported by PowerGraphics ( :ref:`graphics`,POWER). + + .. _plsect_tab_1: + + PLSECT - Valid Item and Component Labels + **************************************** + + .. flat-table:: + :header-rows: 1 + + * - Item + - Comp + - Description + * - Valid item and component labels for element results are: + * - S + - X, Y, Z, XY, YZ, XZ + - Component stress. + * - " + - 1, 2, 3 + - Principal stress. + * - " + - INT, EQV + - Stress intensity or equivalent stress. + + """ + command = f"PLSECT,{item},{comp},{rho},{kbr},{kbr3d}" + return self.run(command, **kwargs) + + def pmap(self, form: str = "", discon: str = "", **kwargs): + r"""Creates mapping of the path geometry by defining path interpolation division points. + + Mechanical APDL Command: `PMAP `_ + + Parameters + ---------- + form : str + Defines the mapping method: + + * ``UNIFORM`` - Maps uniform divisions (specified on the ``nDiv`` argument of the :ref:`path` + command) between specified points. This is the default. + + * ``ACCURATE`` - Map geometry using a small division at the beginning and end of each segment. This + gives you accurate derivatives, integrals, tangents, and normals for curves which do not have + continuous slopes at the specified points. To create nonuniform divisions, the ``nDiv`` argument of + the :ref:`path` command must be greater than 2. + + discon : str + Sets mapping for discontinuities in the field. The divisions are modified to put a point just + before and just after the discontinuity. The valid label is MAT, for a material discontinuity. + No discontinuity is the default. Discontinuity mapping involves the NOAV option on the + :ref:`pdef` command. + """ + command = f"PMAP,{form},{discon}" + return self.run(command, **kwargs) + + def ppath( + self, + point: str = "", + node: str = "", + x: str = "", + y: str = "", + z: str = "", + cs: str = "", + **kwargs, + ): + r"""Defines a path by picking or defining nodes, or locations on the currently active working plane, or + by entering specific coordinate locations. + + Mechanical APDL Command: `PPATH `_ + + Parameters + ---------- + point : str + The point number. It must be greater than zero and less than or equal to the ``nPts`` value + specified on the :ref:`path` command if graphical picking is not being used. + + node : str + The node number defining this point. If blank, use the X, Y, Z coordinates to define the point. + A valid node number will override ``X``, ``Y``, ``Z`` coordinate arguments. + + x : str + The location of the point in the global Cartesian coordinate system. Use these arguments only if + you omit the ``NODE`` argument. + + y : str + The location of the point in the global Cartesian coordinate system. Use these arguments only if + you omit the ``NODE`` argument. + + z : str + The location of the point in the global Cartesian coordinate system. Use these arguments only if + you omit the ``NODE`` argument. + + cs : str + The coordinate system for interpolation of the path between the previous point and this point. + Omit this argument if you wish to use the currently active ( :ref:`csys` ) coordinate system. If + the coordinate system of two adjacent points is different, the ``CS`` value of the latter point + will be used. + + Notes + ----- + + .. _PPATH_notes: + + For linearized stress calculations, the path must be defined with nodes. + + This command is designed and works best in interactive (GUI) mode, using the menu paths listed + below. For command line operations, issue :ref:`ppath`,P to define your path by picking nodes. + + For information on displaying paths you have defined, see `Mapping Results onto a Path + `_ + """ + command = f"PPATH,{point},{node},{x},{y},{z},{cs}" + return self.run(command, **kwargs) + + def prange( + self, linc: str = "", vmin: str = "", vmax: str = "", xvar: str = "", **kwargs + ): + r"""Determines the path range. + + Mechanical APDL Command: `PRANGE `_ + + **Command default:** + + .. _PRANGE_default: + + Include every interpolation point and entire path distance. + + Parameters + ---------- + linc : str + Set the range for listing or displaying the table locations between a minimum value ( ``VMIN`` ) + and a maximum value ( ``VMAX`` ) of the path distance with a location increment of ``LINC`` + (defaults to 1). The first location begins at ``VMIN``. + + vmin : str + Set the range for listing or displaying the table locations between a minimum value ( ``VMIN`` ) + and a maximum value ( ``VMAX`` ) of the path distance with a location increment of ``LINC`` + (defaults to 1). The first location begins at ``VMIN``. + + vmax : str + Set the range for listing or displaying the table locations between a minimum value ( ``VMIN`` ) + and a maximum value ( ``VMAX`` ) of the path distance with a location increment of ``LINC`` + (defaults to 1). The first location begins at ``VMIN``. + + xvar : str + Path variable item to be used as the x-axis plot variable. Any valid path variable may be used ( + :ref:`pdef` command). Default variable is the path distance, S. + + Notes + ----- + + .. _PRANGE_notes: + + Determines the path distance range for use with the :ref:`prpath` and :ref:`plpath` commands. + """ + command = f"PRANGE,{linc},{vmin},{vmax},{xvar}" + return self.run(command, **kwargs) + + def prpath( + self, + lab1: str = "", + lab2: str = "", + lab3: str = "", + lab4: str = "", + lab5: str = "", + lab6: str = "", + **kwargs, + ): + r"""Prints path items along a geometry path. + + Mechanical APDL Command: `PRPATH `_ + + Parameters + ---------- + lab1 : str + Labels identifying the path items to be printed. Up to six items may be printed at a time. + Predefined path geometry items XG, YZ, ZG, and S ( :ref:`pdef` ) may also be printed. + + lab2 : str + Labels identifying the path items to be printed. Up to six items may be printed at a time. + Predefined path geometry items XG, YZ, ZG, and S ( :ref:`pdef` ) may also be printed. + + lab3 : str + Labels identifying the path items to be printed. Up to six items may be printed at a time. + Predefined path geometry items XG, YZ, ZG, and S ( :ref:`pdef` ) may also be printed. + + lab4 : str + Labels identifying the path items to be printed. Up to six items may be printed at a time. + Predefined path geometry items XG, YZ, ZG, and S ( :ref:`pdef` ) may also be printed. + + lab5 : str + Labels identifying the path items to be printed. Up to six items may be printed at a time. + Predefined path geometry items XG, YZ, ZG, and S ( :ref:`pdef` ) may also be printed. + + lab6 : str + Labels identifying the path items to be printed. Up to six items may be printed at a time. + Predefined path geometry items XG, YZ, ZG, and S ( :ref:`pdef` ) may also be printed. + + Notes + ----- + + .. _PRPATH_notes: + + Prints path items with respect to a geometry path (as defined by the :ref:`path` and :ref:`ppath` + commands). Path items and their labels must have been defined with the :ref:`pdef`, :ref:`pvect`, + :ref:`pcalc`, :ref:`pdot`, :ref:`pcross`, or :ref:`prnear` commands. Path items may also be + displayed with the :ref:`plpath` and :ref:`plpagm` commands. See the :ref:`prange` command for range + control of the path. + + Fore more information, see `Mapping Results onto a Path + `_ + """ + command = f"PRPATH,{lab1},{lab2},{lab3},{lab4},{lab5},{lab6}" + return self.run(command, **kwargs) + + def prsect( + self, rho: str = "", kbr: int | str = "", kbr3d: int | str = "", **kwargs + ): + r"""Calculates and prints linearized stresses along a section path. + + Mechanical APDL Command: `PRSECT `_ + + Parameters + ---------- + rho : str + In-plane (X-Y) average radius of curvature of the inside and outside surfaces of an axisymmetric + section. If zero (or blank), a plane or 3D structure is assumed. If nonzero, an axisymmetric + structure is assumed. Use any large number (or -1) for an axisymmetric straight section. + + kbr : int or str + Through-thickness bending stresses key for an axisymmetric analysis ( ``RHO`` ≠ 0): + + * ``0`` - Include the thickness-direction bending stresses. + + * ``1`` - Ignore the thickness-direction bending stresses. + + * ``2`` - Include the thickness-direction bending stress using the same formula as the Y (axial + direction ) bending stress. Also use the same formula for the shear stress. + + kbr3d : int or str + Through-thickness bending stresses key for 3D geometry ( ``RHO`` = 0): + + * ``0`` - Include the thickness-direction bending stresses. + + * ``1`` - Ignore the following thickness-direction bending stresses: SX, SXY, SXZ + + Notes + ----- + + .. _PRSECT_notes: + + You may want to linearize the stresses through a section and separate them into categories for + various code calculations. :ref:`prsect` calculates and reports linearized stresses along a section + path. The linearized stresses are also separated into membrane, bending, membrane plus bending, + peak, and total stress categories. + + Define your section path ( :ref:`path` and :ref:`ppath` with the NODE option). Your path must lie + entirely within the selected set of elements (that is, no element gaps may exist along the path). + :ref:`path` and :ref:`ppath` only retrieve the two end nodes; the path data is not retained. The + section path is defined by the two end nodes, and by 47 intermediate points that are automatically + determined by linear interpolation in the active display coordinate system ( :ref:`dsys` ). The + number and location of the intermediate points are not affected by the number of divisions set by + :ref:`path`,, ``nDiv``. + + Your linearized component stress values are obtained by interpolating each element``s average corner + nodal values along the section path points within each path element. :ref:`prsect` reports the + linearized component and principal stresses for each stress category at the beginning, mid-length, + and end of the section path. :ref:`prpath` can be used to report the total stresses at the + intermediate points. + + Section paths can be through any set of solid (2D plane, 2D axisymmetric or 3D) elements; however, + section paths are usually defined to be through the thickness of the structure and normal to the + inner and outer structure surfaces. Section paths (in-plane only) can also be defined for shell + element structures. + + If the ``RHO`` option is set to indicate the axisymmetric option (non-zero), :ref:`prsect` reports + the linearized stresses in the section coordinates (SX - along the path, SY - normal to the path, + and SZ - hoop direction). If the ``RHO`` option is set to indicate the 2D planar or 3D option (zero + or blank), :ref:`prsect` reports the linearized stresses in the active results coordinate system ( + :ref:`rsys` ]. If the ``RHO`` option is zero or blank and either :ref:`rsys`, SOLU or :ref:`rsys`, + -1 are active, the linearized stresses are calculated and reported in the global Cartesian + coordinate system. + + Linearized stress calculations should be performed in a rectangular coordinate system. Principal + stresses are recalculated from the component stresses and are invariant with the coordinate system + as long as SX is in the same direction at all points along the defined path. The :ref:`plsect` + command displays the linearized stresses in the same coordinate system as reported by :ref:`prsect`. + + Stress components through the section are linearized by a line integral method and separated into + constant membrane stresses, bending stresses varying linearly between end points, and peak stresses + (defined as the difference between the actual (total) stress and the membrane plus bending + combination). + + For nonaxisymmetric structures, the bending stresses are calculated such that the neutral axis is at + the midpoint of the path. Axisymmetric results include the effects of both the radius of revolution + (automatically determined from the node locations) and the in-plane average radius of curvature of + the section surfaces (user input). + + For axisymmetric cases, Mechanical APDL calculates the linearized bending stress in the through- + thickness + direction as the difference between the total outer fiber stress and the membrane stress if ``KBR`` + = 0. The calculation method may be conservative for locations with a highly nonlinear variation of + stress in the through-thickness direction. Alternatively, you can specify ``KBR`` = 2 to calculate + the bending stress using the same method and formula as the Y (axial direction) bending stress. For + more information, see the discussion of `axisymmetric cases + `_ + (specifically ) in the `Mechanical APDL Theory Reference + `_. + + In analyses of 3D models with ``RHO`` = 0, ignoring the calculated out-of-plane bending stresses is + recommended in some scenarios when determining the linearized bending stresses. If ``KBR3D`` = 0, + all calculated stresses are included in the linearized bending-stress calculations. If ``KBR3D`` = + 1, these calculated out-of-plane bending stresses are ignored in the linearized bending-stress + calculations: SX, SXY, SXZ. (The principal bending-stress calculation for S1, S2, S3, SINT, and SEQV + is performed with these zeroed components.) + + Portions of this command are not supported by PowerGraphics ( :ref:`graphics`,POWER]. + """ + command = f"PRSECT,{rho},{kbr},{kbr3d}" + return self.run(command, **kwargs) + + def psel( + self, + type_: str = "", + pname1: str = "", + pname2: str = "", + pname3: str = "", + pname4: str = "", + pname5: str = "", + pname6: str = "", + pname7: str = "", + pname8: str = "", + pname9: str = "", + pname10: str = "", + **kwargs, + ): + r"""Selects a path or paths. + + Mechanical APDL Command: `PSEL `_ + + Parameters + ---------- + type_ : str + Label identifying the type of select: + + * ``S`` - Select a new path. + + * ``R`` - Reselect a path from the current set of paths. + + * ``A`` - Additionally select a path and extend the current set of paths. + + * ``U`` - Unselect a path from the current set of paths. + + * ``ALL`` - Restore the full set of paths. + + * ``NONE`` - Unselect the full set of paths. + + * ``INV`` - Invert the current set of paths (selected becomes unselected and vice versa). + + pname1 : str + Name of existing path(s). + + pname2 : str + Name of existing path(s). + + pname3 : str + Name of existing path(s). + + pname4 : str + Name of existing path(s). + + pname5 : str + Name of existing path(s). + + pname6 : str + Name of existing path(s). + + pname7 : str + Name of existing path(s). + + pname8 : str + Name of existing path(s). + + pname9 : str + Name of existing path(s). + + pname10 : str + Name of existing path(s). + + Notes + ----- + + .. _PSEL_notes: + + Selects a path or multiple paths, up to ten. Data are flagged as selected and unselected; no data + are actually deleted from the database. There is no default for this command; you must specify a + type and pathname. + """ + command = f"PSEL,{type_},{pname1},{pname2},{pname3},{pname4},{pname5},{pname6},{pname7},{pname8},{pname9},{pname10}" + return self.run(command, **kwargs) + + def pvect( + self, + oper: str = "", + labxr: str = "", + labyr: str = "", + labzr: str = "", + **kwargs, + ): + r"""Interpolates a set of items onto a path. + + Mechanical APDL Command: `PVECT `_ + + Parameters + ---------- + oper : str + Valid operations for geometry operations along a path are: + + * ``NORM`` - Defines a unit normal vector at each interpolation point in the direction of the cross + product of the tangent to the path and the active Z axis. Resulting vector components are in the + active coordinate system (which must be Cartesian). + + * ``TANG`` - Defines a unit vector tangent to the path at each interpolation point. Vector + components are in the active coordinate system (which must be Cartesian). + + * ``RADI`` - Defines the position vector of each interpolation point of the path from the center of + the active coordinate system (which must be Cartesian). + + labxr : str + Label (8 characters maximum) assigned to X-component of the resulting vector. + + labyr : str + Label (8 characters maximum) assigned to Y-component of the resulting vector. + + labzr : str + Label (8 characters maximum) assigned to Z-component of the resulting vector. + + Notes + ----- + + .. _PVECT_notes: + + Defines and interpolates a set of labeled path items along predefined path ( :ref:`path` ) and + performs various geometric operations on these path items. A path item must be defined before it can + be used with other path operations. Additional path items may be defined with the :ref:`pdef`, + :ref:`pcalc`, :ref:`pdot`, and :ref:`pcross` commands. Path items may be listed or displayed with + the :ref:`plpath`, :ref:`plpagm` and :ref:`prpath` commands. Path geometry items (XG, YG, ZG, S) are + automatically interpolated (in the active CSYS) if not done so previously with the :ref:`pdef` + command. + """ + command = f"PVECT,{oper},{labxr},{labyr},{labzr}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1/results.py b/src/ansys/mapdl/core/_commands/post1/results.py new file mode 100644 index 0000000000..5566f6f8a0 --- /dev/null +++ b/src/ansys/mapdl/core/_commands/post1/results.py @@ -0,0 +1,3746 @@ +# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + + +class Results: + + def lcsum(self, lab: str = "", **kwargs): + r"""Specifies whether to process non-summable items in load case operations. + + Mechanical APDL Command: `LCSUM `_ + + Parameters + ---------- + lab : str + Combination option + + * ``(blank)`` - Only combine summable items [default]. + + * ``ALL`` - Combine all items including non summable items. + + Notes + ----- + + .. _LCSUM_notes: + + Allows non-summable items (e.g. plastic strains) to be included in load combinations. Issue + :ref:`lcsum`,ALL before the first load case operation ( **LC** ``XX`` command). May also be used to + include nonsummable items in the appending of a results file ( :ref:`rappnd` command). + + For details on using load case combination, see `Creating and Combining Load Cases + `_ + """ + command = f"LCSUM,{lab}" + return self.run(command, **kwargs) + + def nsort( + self, + item: str = "", + comp: str = "", + order: int | str = "", + kabs: int | str = "", + numb: str = "", + sel: str = "", + **kwargs, + ): + r"""Sorts nodal data. + + Mechanical APDL Command: `NSORT `_ + + Parameters + ---------- + item : str + Label identifying the item to be sorted on. Valid item labels are shown in the table below. Some + items also require a component label. + + comp : str + Component of the item (if required). Valid component labels are shown in the table below. + + order : int or str + Order of sort operation: + + * ``0`` - Sort into descending order. + + * ``1`` - Sort into ascending order. + + kabs : int or str + Absolute value key: + + * ``0`` - Sort according to real value. + + * ``1`` - Sort according to absolute value. + + numb : str + Number of nodal data records to be sorted in ascending or descending order ( ``ORDER`` ) before + sort is stopped (remainder will be in unsorted sequence) (defaults to all nodes). + + sel : str + Allows selection of nodes in the sorted field. + + * ``(blank)`` - No selection (default). + + * ``SELECT`` - Select the nodes in the sorted list. + + Notes + ----- + + .. _NSORT_notes: + + Values are in the active coordinate system ( :ref:`csys` for input data or :ref:`rsys` for results + data). Various element results also depend upon the recalculation method and the selected results + location ( :ref:`avprin`, :ref:`rsys`, :ref:`shell`, :ref:`esel`, and :ref:`nsel` ). If simultaneous + load cases are stored, the last sorted sequence formed from any load case applies to all load cases. + Use :ref:`nusort` to restore the original order. This command is not valid with PowerGraphics. + + .. _nsort_tab_1: + + NSORT - Valid Item and Component Labels + *************************************** + + .. flat-table:: Valid Item and Component Labels :ref:`nsort`, ``Item,Comp,ORDER,KABS,NUMB,SEL`` + :header-rows: 2 + + * - Valid item and component labels for input values are: + * - Item + - Comp + - Description + * - LOC + - X, Y, Z + - X, Y, or Z location. + * - ANG + - XY, YZ, ZX + - THXY, THYZ, or THZX rotation angle. + + + .. _nsort_tab_2: + + NSORT - Valid Item and Component Labels for Nodal DOF Result Values + ******************************************************************* + + .. flat-table:: + :header-rows: 1 + + * - Item + - Comp + - Description + * - U + - X, Y, Z, SUM + - X, Y, or Z structural displacement or vector sum. + * - ROT + - X, Y, Z, SUM + - X, Y, or Z structural rotation or vector sum. + * - TEMP + - + - Temperature (includes TEMP, TBOT, TE2, TE3,..., TTOP values). + * - PRES + - + - Pressure. + * - VOLT + - + - Electric potential. + * - MAG + - + - Magnetic scalar potential. + * - V + - X, Y, Z, SUM + - X, Y, or Z fluid velocity or vector sum. + * - A + - X, Y, Z, SUM + - X, Y, or Z magnetic vector potential or vector sum. + * - CONC + - + - Concentration + * - CURR + - + - Current. + * - EMF + - + - Electromotive force drop. + + + .. _nsort_tab_3: + + NSORT - Valid Item and Component Labels for Element Result Values + ***************************************************************** + + .. flat-table:: + :header-rows: 1 + + * - Item + - Comp + - 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. + * - EPDI + - X, Y, Z, XY, YZ, XZ + - Component diffusion strain. + * - " + - 1, 2, 3 + - Principal diffusion strain. + * - " + - INT, EQV + - Diffusion strain intensity or diffusion equivalent 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. + * - FAIL + - MAX + - Maximum of all active failure criteria defined at the current location. (See the :ref:`fctyp` command for details.) [ :ref:`NSORTinputneed` ] + * - " + - EMAX + - Maximum Strain Failure Criterion [ :ref:`NSORTinputneed` ] + * - " + - SMAX + - Maximum Stress Failure Criterion [ :ref:`NSORTinputneed` ] + * - " + - TWSI + - Tsai-Wu Strength Index Failure Criterion [ :ref:`NSORTinputneed` ] + * - " + - TWSR + - Inverse of Tsai-Wu Strength Ratio Index Failure Criterion [ :ref:`NSORTinputneed` ] + * - " + - HFIB + - Hashin Fiber Failure Criterion. [ :ref:`NSORTinputneed` ][ :ref:`nsort_tab_elemlim` ] + * - " + - HMAT + - Hashin Matrix Failure Criterion. [ :ref:`NSORTinputneed` ][ :ref:`nsort_tab_elemlim` ] + * - " + - PFIB + - Puck Fiber Failure Criterion. [ :ref:`NSORTinputneed` ][ :ref:`nsort_tab_elemlim` ] + * - " + - PMAT + - Puck Matrix Failure Criterion. [ :ref:`NSORTinputneed` ][ :ref:`nsort_tab_elemlim` ] + * - " + - USR1, USR2,..., USR9 + - User-defined failure criteria [ :ref:`NSORTinputneed` ][ :ref:`nsort_tab_elemlim` ][ :ref:`NSORT_ftnote_failcritroutine` ] + * - CONT + - STAT [ :ref:`NSORTcontstat` ] + - Contact status. + * - " + - PENE + - Contact penetration. + * - " + - PRES + - Contact pressure. + * - " + - SFRIC + - Contact friction stress. + * - " + - STOT + - Contact total stress (pressure plus friction). + * - " + - SLIDE + - Contact sliding distance. + * - TG + - X, Y, Z, SUM + - Component thermal gradient or vector sum. + * - TF + - X, Y, Z, SUM + - Component thermal flux or vector sum. + * - PG + - X, Y, Z, SUM + - Component pressure gradient or vector sum. + * - EF + - X, Y, Z, SUM + - Component electric field or vector sum. + * - D + - X, Y, Z, SUM + - Component electric flux density or vector sum. + * - H + - X, Y, Z, SUM + - Component magnetic field intensity or vector sum. + * - B + - X, Y, Z, SUM + - Component magnetic flux density or vector sum. + * - CG + - X, Y, Z, SUM + - Component concentration gradient or vector sum + * - DF + - X, Y, Z, SUM + - Component diffusion flux density or vector sum + * - FMAG + - X, Y, Z, SUM + - Component electromagnetic forces or vector sum. + + .. _NSORTinputneed: + + Works only if failure criteria information is provided. (For more information, see the documentation + for the :ref:`fc` and :ref:`tb` commands.) + + .. _nsort_tab_elemlim: + + Must be added via the :ref:`fctyp` command first. + + .. _NSORT_ftnote_failcritroutine: + + Works only if user failure criteria routine is provided. + + .. _NSORTcontstat: + + For more information about contact status and its possible values, see `Reviewing Results in POST1 + `_ + """ + command = f"NSORT,{item},{comp},{order},{kabs},{numb},{sel}" + return self.run(command, **kwargs) + + def nusort(self, **kwargs): + r"""Restores original order for nodal data. + + Mechanical APDL Command: `NUSORT `_ + + Notes + ----- + + .. _NUSORT_notes: + + This command restores the nodal data to its original order (sorted in ascending node number + sequence) after an :ref:`nsort` command. Changing the selected nodal set ( :ref:`nsel` ) also + restores the original nodal order. + """ + command = "NUSORT" + return self.run(command, **kwargs) + + def plcint( + self, + action: str = "", + id_: str = "", + node: str = "", + cont: str = "", + dtype: str = "", + **kwargs, + ): + r"""Plots the fracture parameter ( :ref:`cint` ) result data. + + Mechanical APDL Command: `PLCINT `_ + + Parameters + ---------- + action : str + * ``PATH`` - Plots :ref:`cint` quantities according to path number (default). + + * ``FRONT`` - Plots :ref:`cint` quantities distribution along the crack front. + + id_ : str + Crack ID number. + + node : str + Crack tip node number (default = ALL). + + Use only for ``ACTION`` = PATH. Plots :ref:`cint` contour for an individual crack tip node. + + cont : str + Contour number (Default = ALL). + + Use only for ``ACTION`` = FRONT. Plots :ref:`cint` distribution along the crack for a given + path. + + dtype : str + Data type to output: + + * ``JINT`` - J-integral (default) + + * ``IIN1`` - Interaction integral 1 + + * ``IIN2`` - Interaction integral 2 + + * ``IIN3`` - Interaction integral 3 + + * ``K1`` - Mode 1 stress-intensity factor + + * ``K2`` - Mode 2 stress-intensity factor + + * ``K3`` - Mode 3 stress-intensity factor + + * ``G1`` - Mode 1 energy release rate + + * ``G2`` - Mode 2 energy release rate + + * ``G3`` - Mode 3 energy release rate + + * ``GT`` - Total energy release rate + + * ``MFTX`` - Total material force X + + * ``MFTY`` - Total material force Y + + * ``MFTZ`` - Total material force Z + + * ``TSTRESS`` - T-stress + + * ``CEXT`` - Crack extension + + * ``CSTAR`` - C\2-integral + + Notes + ----- + + .. _PLCINT_notes: + + The :ref:`plcint` command is not available for `XFEM-based crack-growth + `_ + analyses results processing. + """ + command = f"PLCINT,{action},{id_},{node},{cont},{dtype}" + return self.run(command, **kwargs) + + def plcksurf(self, modeldisplay: int | str = "", **kwargs): + r"""Plots the Φ = 0 level set surface in an `XFEM-based crack analysis + `_ + + Mechanical APDL Command: `PLCKSURF `_ + + Parameters + ---------- + modeldisplay : int or str + Solid model display behavior: + + * ``0`` - No display of the solid model (default). + + * ``1`` - Solid model displayed with translucency and edges disabled. + + Notes + ----- + + .. _PLCKSURF_notes: + + The :ref:`plcksurf` command is available only for `XFEM-based crack analysis + `_ + during results processing. + """ + command = f"PLCKSURF,{modeldisplay}" + return self.run(command, **kwargs) + + def pldisp(self, kund: int | str = "", **kwargs): + r"""Displays the displaced structure. + + Mechanical APDL Command: `PLDISP `_ + + Parameters + ---------- + kund : int or str + Undisplaced shape key: + + * ``0`` - Display only displaced structure. + + * ``1`` - Overlay displaced display with similar undisplaced display (appearance is system- + dependent). + + * ``2`` - Same as 1 except overlay with undisplaced edge display (appearance is system-dependent). + + Notes + ----- + + .. _PLDISP_notes: + + Displays the displaced structure for the selected elements. + + For information on true scale plots, refer to the description of the :ref:`slashdscale` command ( + :ref:`slashdscale`,,1.0). + """ + command = f"PLDISP,{kund}" + return self.run(command, **kwargs) + + def plesol( + self, + item: str = "", + comp: str = "", + kund: int | str = "", + fact: str = "", + avg: int | str = "", + **kwargs, + ): + r"""Displays solution results as discontinuous element contours. + + Mechanical APDL Command: `PLESOL `_ + + Parameters + ---------- + item : str + Label identifying the item. Valid item labels are shown in the table below. Some items also + require a component label. + + comp : str + Component of the item (if required). Valid component labels are shown in the table below. + + kund : int or str + Undisplaced shape key: + + * ``0`` - Do not overlay undeformed structure display. + + * ``1`` - Overlay displaced contour plot with undeformed display (appearance is system-dependent). + + * ``2`` - Overlay displaced contour plot with undeformed edge display (appearance is system- + dependent). + + fact : str + Scale factor for 2D display of contact items. Default = 1. To invert the display, specify a + negative scaling factor. + + avg : int or str + Specifies whether results of reinforcing members within the same reinforcing element are smoothed: + + * ``0`` - Disable smoothing. + + * ``1`` - Enable smoothing (default), displaying constant results of reinforcing members if the base + elements are low-order, and linear results when the base elements are high-order. + + Notes + ----- + + .. _PLESOL_notes: + + :ref:`plesol` displays the solution results as element contours discontinuous across element + boundaries for the selected elements. + + For example, :ref:`plesol`,S,X displays the X component of stress S (that is, the SX stress + component). Various element results depend on the calculation method and the selected results + location ( :ref:`avprin`, :ref:`rsys`, and :ref:`esel` ). + + Contours are determined by linear interpolation within each element, unaffected by the surrounding + elements; that is, no nodal averaging occurs. The discontinuity between contours of adjacent + elements is an indication of the gradient across elements. Component results are displayed in the + active results coordinate system ( :ref:`rsys` [default is global Cartesian]). + + To display items not available via :ref:`plesol` (such as line element results), see :ref:`etable` + and :ref:`pletab`. + + For PowerGraphics displays ( :ref:`graphics`,POWER), results are plotted only for the model exterior + surface. Items not supported by PowerGraphics are noted in :ref:`plesol_tab_1`. + + The results displayed by :ref:`plesol` are unaffected by any requested nodal-averaged results ( + :ref:`outres`,NAR). For more information, see `Nodal-Averaged Results + `_ + + For ``Item`` = SRES, selected result ( :ref:`osresult` ) values are output. See :ref:`PLESOL_tab_2`. + + .. _plesol_tab_1: + + PLESOL - General Result Item and Component Labels + ************************************************* + + .. flat-table:: General Item and Component Labels :ref:`plesol`, ``Item, Comp`` + :header-rows: 1 + + * - Item + - Comp + - Description + * - :rspan:`3` S + - X, Y, Z, XY, YZ, XZ + - Component stress. + * - 1, 2, 3 + - Principal stress. + * - INT + - Stress intensity. + * - EQV + - Equivalent stress. + * - :rspan:`3` EPEL + - X, Y, Z, XY, YZ, XZ + - Component elastic strain. + * - 1, 2, 3 + - Principal elastic strain. + * - INT + - Elastic strain intensity. + * - EQV + - Elastic equivalent strain. + * - :rspan:`3` EPDI + - X, Y, Z, XY, YZ, XZ + - Component diffusion strain. Not supported by PowerGraphics. + * - 1, 2, 3 + - Principal diffusion strain. + * - EQV + - Diffusion equivalent strain. + * - INT + - Diffusion strain intensity. + * - :rspan:`3` EPPL + - X, Y, Z, XY, YZ, XZ + - Component plastic strain. + * - 1, 2, 3 + - Principal plastic strain. + * - INT + - Plastic strain intensity. + * - EQV + - Plastic equivalent strain. + * - :rspan:`3` EPCR + - X, Y, Z, XY, YZ, XZ + - Component creep strain. + * - 1, 2, 3 + - Principal creep strain. + * - INT + - Creep strain intensity. + * - EQV + - Creep equivalent strain. + * - :rspan:`3` EPTH + - X, Y, Z, XY, YZ, XZ + - Component thermal strain. + * - 1, 2, 3 + - Principal thermal strain. + * - INT + - Thermal strain intensity. + * - EQV + - Thermal equivalent strain. + * - EPSW + - + - Swelling strain. + * - :rspan:`3` EPTO + - X, Y, Z, XY, YZ, XZ + - Component total mechanical strain (EPEL + EPPL + EPCR). + * - 1, 2, 3 + - Principal total mechanical strain. + * - INT + - Total mechanical strain intensity. + * - EQV + - Total mechanical equivalent strain. + * - :rspan:`3` EPTT + - X, Y, Z, XY, YZ, XZ + - Total mechanical, thermal, diffusion, and swelling strain (EPEL + EPPL + EPCR + EPTH + EPDI + EPSW). + * - 1, 2, 3 + - Principal total mechanical, thermal, diffusion, and swelling strain. + * - INT + - Total mechanical, thermal, diffusion, and swelling strain intensity. + * - EQV + - Total mechanical, thermal, diffusion, and swelling equivalent strain. + * - :rspan:`6` NL + - SEPL + - Equivalent stress (from stress-strain curve). + * - SRAT + - Stress state ratio. + * - HPRES + - Hydrostatic pressure. + * - EPEQ + - Accumulated equivalent plastic strain. + * - CREQ + - Accumulated equivalent creep strain. + * - PSV + - Plastic state variable. + * - PLWK + - Plastic work/volume. + * - :rspan:`7` SEND + - ELASTIC The results for this postprocessing SEND component are invalid for ``ELBOW290`` if that element is used with viscoelastic or viscohyperelastic materials. + - Elastic strain energy density. (For `viscoelastic `_ and `sintering `_ materials, the `stored energy `_.) + * - PLASTIC + - Plastic strain energy density. + * - CREEP + - Creep strain energy density. + * - DAMAGE + - Damage strain energy density. + * - VDAM + - Viscoelastic dissipation energy density. + * - VREG + - Visco-regularization strain energy density. + * - DISS + - Structural-thermal dissipation. + * - ENTO + - Total strain energy density (sum of ELASTIC, PLASTIC, and CREEP strain energy densities). + * - :rspan:`1` CDM + - DMG + - Damage variable. + * - LM + - Maximum previous strain energy for virgin material. + * - :rspan:`13` FAIL + - MAX + - Maximum of all active failure criteria defined at the current location. Works only if failure criteria are provided ( :ref:`fc` and :ref:`tb` ). + * - EMAX + - Maximum Strain Failure Criterion. + * - SMAX + - Maximum Stress Failure Criterion. + * - TWSI + - Tsai-Wu Strength Index Failure Criterion. + * - TWSR + - Inverse of Tsai-Wu Strength Ratio Index Failure Criterion + * - HFIB + - Hashin Fiber Failure Criterion. Must first be added ( :ref:`fctyp`. + * - HMAT + - Hashin Matrix Failure Criterion. + * - PFIB + - Puck Fiber Failure Criterion. + * - PMAT + - Puck Matrix Failure Criterion. + * - L3FB + - LaRc03 Fiber Failure Criterion. + * - L3MT + - LaRc03 Matrix Failure Criterion. + * - L4FB + - LaRc04 Fiber Failure Criterion. + * - L4MT + - LaRc04 Matrix Failure Criterion. + * - USR1, USR2,..., USR9 + - User-defined failure criteria. USR1 through USR9 require a failure-criteria routine. + * - :rspan:`4` PFC + - MAX Failure criteria are based on the effective stresses in the damaged material. + - Maximum of all failure criteria defined at current location. + * - FT + - Fiber tensile failure criteria. + * - FC + - Fiber compressive failure criteria. + * - MT + - Matrix tensile failure criteria. + * - MC + - Matrix compressive failure criteria. + * - :rspan:`7` PDMG + - STAT + - Damage status (0 = undamaged, 1 = damaged, 2 = completely damaged). + * - FT + - Fiber tensile damage variable. + * - FC + - Fiber compressive damage variable. + * - MT + - Matrix tensile damage variable. + * - MC + - Matrix compressive damage variable. + * - S + - Shear damage variable (S). + * - SED + - Energy dissipated per unit volume. + * - SEDV + - Energy per unit volume due to viscous damping. + * - :rspan:`2` FCMX + - LAY + - Layer number where the maximum of all active failure criteria over the entire element occurs. + * - FC + - Number of the maximum-failure criterion over the entire element: * 1 = EMAX * 2 = SMAX * 3 = TWSI * 4 = TWSR * 5 = PFIB * 6 = PMAT * 7 = HFIB * 8 = HMAT * 9 = L3FB * 10 = L3MT * 11 = L4FB * 12 = L4MT * 13~21 = USR1~USR9 + * - VAL + - Value of the maximum failure criterion over the entire element: + * - SVAR + - 1, 2, 3,... N + - State variable. + * - GKS + - X, XY, XZ + - Gasket component stress. + * - GKD + - X, XY, XZ + - Gasket component total closure. + * - GKDI + - X, XY, XZ + - Gasket component total inelastic closure. + * - GKTH + - X, XY, XZ + - Gasket component thermal closure. + * - SS + - X, XY, XZ + - Interface traction (stress). + * - SD + - X, XY, XZ + - Interface separation. + * - :rspan:`9` CONT + - STAT + - Contact status: For MPC-based contact definitions, the value of STAT can be negative, indicating that one or more contact constraints were intentionally removed to prevent overconstraint. STAT = -3 is used for MPC bonded contact; STAT = -2 is used for MPC no-separation contact. * 3 = closed and sticking * 2 = closed and sliding * 1 = open but near contact * 0 = open and not near contact + * - PENE + - Contact penetration. + * - PRES + - Contact pressure. + * - SFRIC + - Contact friction stress. + * - STOT + - Contact total stress (pressure plus friction). + * - SLIDE + - Contact sliding distance. + * - GAP + - Contact gap distance. + * - FLUX + - Total heat flux at contact surface. + * - CNOS + - Total number of contact status changes during substep. + * - FPRS + - Fluid penetration pressure. + * - TG ``Comp`` = SUM is not supported for coupled pore-pressure-thermal (CPT ``nnn`` ) elements. + - X, Y, Z, SUM + - Component thermal gradient or vector sum. + * - TF + - X, Y, Z, SUM + - Component thermal flux or vector sum. + * - PG + - X, Y, Z, SUM + - Component or vector sum of velocity or energy density flux (room acoustics). + * - EF + - X, Y, Z, SUM + - Component electric field or vector sum. + * - D + - X, Y, Z, SUM + - Component electric flux density or vector sum. + * - H + - X, Y, Z, SUM + - Component magnetic field intensity or vector sum. + * - B + - X, Y, Z, SUM + - Component magnetic flux density or vector sum. + * - CG + - X, Y, Z, SUM + - Component concentration gradient or vector sum. + * - DF + - X, Y, Z, SUM + - Component diffusion flux density or vector sum. + * - FMAG + - X, Y, Z, SUM + - Component electromagnetic force or vector sum. + * - P + - X, Y, Z, SUM + - Poynting vector component or sum. + * - SERR Some element- and material-type limitations apply. (See :ref:`prerr`.) + - + - Structural error energy. + * - SDSG + - + - Absolute value of the maximum variation of any nodal stress component. + * - TERR + - + - Thermal error energy. + * - TDSG + - + - Absolute value of the maximum variation of any nodal thermal gradient component. + * - F + - X, Y, Z + - X, Y, or Z structural force. Do not use :ref:`plesol` to obtain contact force values for contact elements. (The force values reported may not be accurate for these elements.) Use :ref:`etable` instead. + * - M + - X, Y, Z + - X, Y, or Z structural moment. + * - HEAT + - + - Heat flow. + * - FLOW + - + - Fluid flow. + * - AMPS + - + - Current flow. Use :ref:`force` for type. + * - CHRG + - + - Charge. Use :ref:`force` for type. + * - FLUX + - + - Magnetic flux. + * - CSG + - X, Y, Z + - X, Y, or Z magnetic current segment component. + * - RATE + - + - Diffusion flow rate. + * - SENE + - + - "Stiffness" energy or thermal heat dissipation. Same as TENE. + * - STEN + - + - Elemental energy dissipation due to `stabilization `_. + * - TENE + - + - Thermal heat dissipation or "stiffness" energy. Same as SENE. + * - KENE + - + - Kinetic energy. + * - ASENE + - + - Amplitude "stiffness" energy. + * - PSENE + - + - Peak "stiffness" energy. + * - AKENE + - + - Amplitude kinetic energy. + * - PKENE + - + - Peak kinetic energy. + * - DENE + - + - Damping energy. + * - WEXT WEXT is calculated for element-based loading only (and not for nodal-force loading). WEXT is stored on elements to which loading has been applied; if surface elements are added on top of other elements, for example, and pressure loading is applied to the surface elements, WEXT is available for the surface elements only. + - + - Work due to external load. + * - AENE + - + - Artificial energy due to hourglass control/drill stiffness or due to contact stabilization. + * - JHEAT + - + - Element Joule heat generation. + * - JS + - X, Y, Z, SUM + - Source current density for low-frequency magnetic analyses. Total current density (sum of conduction and displacement current densities) in low frequency electric analyses. Components (X, Y, Z) and vector sum (SUM). + * - JT + - X, Y, Z, SUM + - Total measureable current density in low-frequency electromagnetic analyses. (Conduction current density in a low-frequency electric analysis.) Components (X, Y, Z) and vector sum (SUM). + * - JC + - X, Y, Z, SUM + - Conduction current density for elements that support conduction current calculation. Components (X, Y, Z) and vector sum (SUM). + * - MRE + - + - Magnetic Reynolds number. + * - VOLU + - + - Volume of volume element. + * - CENT + - X, Y, Z + - Centroid X, Y, or Z location (based on shape function) in the active coordinate system. + * - BFE + - TEMP For `reinforcing `_ elements ``REINF264`` and ``REINF265``, issue :ref:`plesol` ,BFE,TEMP to plot the corner-point temperature of each member. You can also plot intersection-point temperature gradients ( :ref:`plesol`,TG) and intersection-point heat flux ( :ref:`plesol`,TF). For higher-order reinforcing members (generated when using higher-order base elements), the midpoint values are not available for the reinforcing members. + - Body temperatures (calculated from applied temperatures) as used in solution (area and volume elements only). For ``SOLID278`` and ``SOLID279`` with KEYOPT(3) = 2, use :ref:`plesol`,BFE,TEMP to plot the temperature distribution through the thickness of the element. When other thermal elements are included in the model, they should be unselected to avoid plotting undefined information. + * - SMISC + - ``snum`` + - Element summable miscellaneous data value at sequence number ``snum`` (shown in the Output Data section of each element description. + * - NMISC + - ``snum`` + - Element non-summable miscellaneous data value at sequence number ``snum`` (shown in the Output Data section of each element description. + * - CAP + - C0,X0,K0,ZONE, DPLS,VPLS + - Material cap plasticity model only: Cohesion; hydrostatic compaction yielding stress; I1 at the transition point at which the shear and compaction envelopes intersect; zone = 0: elastic state, zone = 1: compaction zone, zone = 2: shear zone, zone = 3: expansion zone; effective deviatoric plastic strain; volume plastic strain. + * - EDPC + - CSIG,CSTR + - Material EDP creep model only (not including the cap model): Equivalent creep stress; equivalent creep strain. + * - FICT + - TEMP + - Fictive temperature. + * - :rspan:`3` ESIG + - X,Y,Z,XY,YZ,ZX + - Components of Biot``s effective stress. + * - 1, 2, 3 + - Principal stresses of Biot``s effective stress. + * - INT + - Stress intensity of Biot``s effective stress. + * - EQV + - Equivalent stress of Biot``s effective stress. + * - :rspan:`2` DPAR + - TPOR + - Total porosity (Gurson material model). + * - GPOR + - Porosity due to void growth. + * - NPOR + - Porosity due to void nucleation. + * - FFLX + - X,Y,Z + - Fluid flow flux in poromechanics. + * - FGRA + - X,Y,Z + - Fluid pore-pressure gradient in poromechanics. + * - MENE + - + - Acoustic potential energy. + * - PMSV + - VRAT, PPRE, DSAT, RPER + - Void volume ratio, pore pressure, degree of saturation, and relative permeability for coupled pore-pressure-thermal elements. + * - YSIDX + - TENS,SHEA + - Yield surface activity status for Mohr-Coulomb, soil, concrete, and joint rock material models: 1 = yielded, 0 = not yielded. + * - FPIDX + - TF01,SF01, TF02,SF02, TF03,SF03, TF04,SF04 + - Failure plane surface activity status for concrete and joint rock material models: 1 = yielded, 0 = not yielded. Tension and shear failure status are available for all four sets of failure planes. + * - NS + - X, Y, Z, XY, YZ, XZ + - `Nominal strain `_ for hyperelastic material, reported in the current configuration (unaffected by :ref:`rsys` ). + * - MPLA + - DMAC, DMAX + - Microplane damage, macroscopic and maximum values. + * - MPDP + - TOTA, TENS, COMP, RW + - Microplane homogenized total, tension, and compression damages (TOTA, TENS, COMP), and split weight factor (RW). + * - DAMAGE + - 1,2,3,MAX + - Damage in directions 1, 2, 3 (1, 2, 3) and the maximum damage (MAX). + * - GDMG + - + - Damage + * - IDIS + - + - Structural-thermal dissipation rate + * - BKS + - X, Y, Z, XY, YZ, XZ + - Total `nonlinear kinematic backstress `_ reported in the current configuration (unaffected by :ref:`rsys` ). Available for 3D, plane strain, and axisymmetric elements. + * - BKS1,...,BKS5 + - X, Y, Z, XY, YZ, XZ + - Superimposed components of the total `nonlinear kinematic backstress`_ reported in the current configuration (unaffected by :ref:`rsys` ). Available for 3D, plane strain, and axisymmetric elements when more than one superimposed back-stress component is defined. + * - EPFR + - + - Free strain in porous media + * - SNDI + - X, Y, Z, SUM + - Component sound intensity or vector sum. + * - FC1S + - 1,2,3,4,5,6 + - First set of six components of FCC crystal slip. Available for 3D elements only. + * - FC2S + - 1,2,3,4,5,6 + - Second set of six components of FCC crystal slip. Available for 3D elements only. + * - HC1S + - 1,2,3,4,5,6 + - Six components of HCP crystal slip on basal and prismatic systems. Available for 3D elements only. + * - HC2S + - 1,2,3,4,5,6 + - Six components of HCP crystal slip on pyramidal system. Available for 3D elements only. + * - HC3S + - 1,2,3,4,5,6 + - First set of six components of HCP crystal slip on the first-order pyramidal system. Available for 3D elements only. + * - HC4S + - 1,2,3,4,5,6 + - Second set of six components of HCP crystal slip on the first-order pyramidal system. Available for 3D elements only. + * - HC5S + - 1,2,3,4,5,6 + - Six components of HCP crystal slip on the second-order pyramidal system. Available for 3D elements only. + * - BC1S + - 1,2,3,4,5,6 + - First set of six components of BCC slip on 111 plane. Available for 3D elements only. + * - BC2S + - 1,2,3,4,5,6 + - Second set of six components of BCC slip on 111 plane. Available for 3D elements only. + * - BC3S + - 1,2,3,4,5,6 + - First set of six components of BCC slip on 112 plane. Available for 3D elements only. + * - BC4S + - 1,2,3,4,5,6 + - Second set of six components of BCC slip on 112 plane. Available for 3D elements only. + * - BC5S + - 1,2,3,4,5,6 + - First set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - BC6S + - 1,2,3,4,5,6 + - Second set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - BC7S + - 1,2,3,4,5,6 + - Third set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - BC8S + - 1,2,3,4,5,6 + - Fourth set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - FC1H + - 1,2,3,4,5,6 + - First set of six components of FCC crystal hardness. Available for 3D elements only. + * - FC2H + - 1,2,3,4,5,6 + - Second set of six components of FCC crystal hardness. Available for 3D elements only. + * - HC1H + - 1,2,3,4,5,6 + - Sixcomponents of HCP crystal hardness on basal and prismatic systems. Available for 3D elements. + * - HC2H + - 1,2,3,4,5,6 + - Six components of HCP crystal hardness on pyramidal system. Available for 3D elements only. + * - HC3H + - 1,2,3,4,5,6 + - First set of six components of HCP crystal hardness on the first-order pyramidal system. Available for 3D elements only. + * - HC4H + - 1,2,3,4,5,6 + - Second set of six components of HCP crystal hardness on the first-order pyramidal system. Available for 3D elements only. + * - HC5H + - 1,2,3,4,5,6 + - Six components of HCP crystal hardness on the second-order pyramidal system. Available for 3D elements only. + * - BC1H + - 1,2,3,4,5,6 + - First set of six components of BCC hardness on 111 plane. Available for 3D elements only. + * - BC2H + - 1,2,3,4,5,6 + - Second set of six components of BCC hardness on 111 plane. Available for 3D elements only. + * - BC3H + - 1,2,3,4,5,6 + - First set of six components of BCC hardness on 112 plane. Available for 3D elements only. + * - BC4H + - 1,2,3,4,5,6 + - Second set of six components of BCC hardness on 112 plane. Available for 3D elements only. + * - BC5H + - 1,2,3,4,5,6 + - First set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - BC6H + - 1,2,3,4,5,6 + - Second set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - BC7H + - 1,2,3,4,5,6 + - Third set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - BC8H + - 1,2,3,4,5,6 + - Fourth set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - XELG + - 1,2,3,45,6,EQV + - Crystal Lagrangian strain in 11, 22, 33, 12, 23,13 directions and its equivalent. Available for 3D elements only. + * - SINT + - RHO, ETA, SSTR, GRAIN + - Sintering relative density, viscosity, sintering stress, and average grain size values. + + + .. _PLESOL_tab_2: + + PLESOL - Selected Result Component Labels + ***************************************** + + .. flat-table:: Selected Result Component Labels :ref:`plesol`,SRES, ``Comp`` + :header-rows: 1 + + * - Comp + - Description + * - SVAR ``n`` + - The ``n`` th state variable. + * - FLDUF0 ``n`` + - The ``n`` th user-defined field variable. + + """ + command = f"PLESOL,{item},{comp},{kund},{fact},{avg}" + return self.run(command, **kwargs) + + def plnsol( + self, + item: str = "", + comp: str = "", + kund: int | str = "", + fact: str = "", + fileid: str = "", + avg: str = "", + datakey: str = "", + **kwargs, + ): + r"""Displays solution results as continuous element contours. + + Mechanical APDL Command: `PLNSOL `_ + + Parameters + ---------- + item : str + Label identifying the item. Valid item labels are shown in the table below. Some items also + require a component label. + + comp : str + Component of the item (if required). Valid component labels are shown in the table below. + + kund : int or str + Undisplaced shape key: + + * ``0`` - Do not overlay undeformed structure display. + + * ``1`` - Overlay displaced contour plot with undeformed display (appearance is system-dependent). + + * ``2`` - Overlay displaced contour plot with undeformed edge display (appearance is system- + dependent). + + fact : str + Scale factor for 2D display for contact items. Default value is 1. A negative scaling factor + inverts the display. + + fileid : str + The file index number (obtained via :ref:`nldiag`,NRRE,ON). Valid only for ``Item`` = NRRE. + + avg : str + Specifies whether random acoustic results are averaged. Valid only for ``Item`` = U and PRES. + + * ``(blank)`` - No averaging (default). + + * ``AVG`` - Display averaged results for random acoustics. + + datakey : str + Key to specify which data is plotted: + + * ``AUTO`` - `Nodal-averaged results + `_ are + used, if available; otherwise, the element-based data is used, if available. (Default.) + + * ``ESOL`` - Only element-based results are used. If they are not available, the command is ignored. + + * ``NAR`` - Only nodal-averaged results are used. If they are not available, the command is ignored. + + Notes + ----- + + .. _PLNSOL_notes: + + :ref:`plnsol` displays the solution results as continuous contours across element boundaries for the + selected nodes and elements. + + For example, :ref:`plnsol`,S,X displays the X component of stress S (that is, the SX stress + component). Various element results depend upon the recalculation method and the selected results + location ( :ref:`avprin`, :ref:`rsys`, :ref:`layer`, :ref:`shell`, and :ref:`nsel` ). + + Contours are determined by linear interpolation within each element from the nodal values, averaged + at a node whenever two or more elements connect to the same node. (The exception is FMAG, which is + summed at the node.) + + For `reinforcing + `_ + elements (REINF ``nnn`` ), contours are determined by interpolation within each reinforcing member + of reinforcing elements from the results of the base elements. Element results of members within the + same reinforcing element are smoothed based on the order of its base element. :ref:`plnsol` displays + constant results for a reinforcing element if the base elements are low-order, and linear results + when the base elements are high-order. + + For PowerGraphics displays ( :ref:`graphics`,POWER), results are plotted for the model exterior + surface only. Items not supported by PowerGraphics are noted in :ref:`plnsol_tab_1`. + + To plot midside nodes, first issue :ref:`efacet`,2. + + If `nodal-averaged results + `_ ( + :ref:`outres`,NAR or another nodal-averaged label) are in the database, then :ref:`plnsol` uses the + nodal-averaged data for the applicable items (S, EPEL, EPPL, EPCR, EPTH, EPSW) by default. You can + change this behavior via the ``DataKey`` argument. Keep these points in mind when using nodal- + averaged results: + + * The :ref:`layer` and :ref:`rsys`,SOLU commands are not valid with nodal-averaged results. If these + commands are used, the element solution is plotted instead if applicable. + + * Issuing :ref:`esel` before plotting nodal-averaged results has no effect on the output. + + * PowerGraphics is supported. The output is equivalent to the full model graphics output, but only + the appropriate surface nodes are plotted. See `Postprocessing Nodal-Averaged Results + `_ + + For ``Item`` = SRES, selected result ( :ref:`osresult` ) values are output. See :ref:`PLNSOL_tab_2`. + + .. _plnsol_tab_1: + + PLNSOL - Valid Item and Component Labels + **************************************** + + .. flat-table:: General Item and Component Labels :ref:`plnsol`, ``Item, Comp`` + :header-rows: 1 + + * - Item + - Comp + - Description + * - **Valid item and component labels for nodal degree of freedom results are:** + * - U + - X, Y, Z, SUM + - X, Y, or Z structural displacement or vector sum. + * - ROT + - X, Y, Z, SUM + - X, Y, or Z structural rotation or vector sum. + * - TEMP For ``SHELL131`` and ``SHELL132`` elements with KEYOPT(3) = 0 or 1, use the labels TBOT, TE2, TE3, ..., TTOP instead of TEMP to view the individual temperature degree of freedom. When other thermal elements are included in the model, deselect them to avoid plotting undefined information. To view all temperatures in the same plot, set :ref:`eshape` ,1 and :ref:`graphics`,POWER and issue :ref:`plnsol`,TEMP. + - + - Temperature. + * - PRES + - + - Pressure. + * - GFV1, GFV2, GFV3 + - + - Nonlocal field values 1, 2, and 3. + * - VOLT + - + - Electric potential. + * - MAG + - + - Magnetic scalar potential. + * - CONC + - + - Concentration. Not supported by PowerGraphics. + * - V + - X, Y, Z, SUM + - X, Y, or Z fluid velocity or vector sum in a fluid analysis. + * - A + - X, Y, Z, SUM + - X, Y, or Z magnetic vector potential or vector sum in an electromagnetic analysis. + * - VEL + - X, Y, Z, SUM + - X, Y, or Z velocity or vector sum in a structural transient dynamic analysis ( :ref:`antype`,TRANS). + * - ACC + - X, Y, Z, SUM + - X, Y, or Z acceleration or vector sum in a structural transient dynamic analysis ( :ref:`antype`,TRANS). + * - OMG + - X, Y, Z, SUM + - X, Y, or Z rotational velocity or vector sum in a structural transient dynamic analysis ( :ref:`antype`,TRANS). + * - DMG + - X, Y, Z, SUM + - X, Y, or Z rotational acceleration or vector sum in a structural transient dynamic analysis ( :ref:`antype`,TRANS). + * - WARP + - + - Warping. + * - :rspan:`1` NRRE + - FX, FY, FZ, FNRM, MX, MY, MZ, MNRM + - Plot the Newton-Raphson residuals from the file you obtained via the :ref:`nldiag`,NRRE,ON command. The FNRM and MNRM labels are computed as the square root of the sum of the squares of the residual component forces or moments (FX,FY,FZ, MX, MY, MZ). When plotting Newton-Raphson residual items ( ``Item`` = NRRE) from a file on the deformed geometry, the displacements are based on the current set of results in the database. These displacements may not correspond to the loadstep and substep in the :file:`.nrxxxxx` file. (For more information about :file:`.nrxxxxx` files and nonlinear diagnostics postprocessing, see the description of the :ref:`nldpost` command and.) + * - SPL + - + - Sound pressure level. + * - SPLA + - + - A-weighted sound pressure level (dBA). + * - VNS + - + - Normal velocity on the structural surface. Valid only for ``SHELL181``, ``SOLID185``, ``SOLID186``, ``SOLID187``, ``SOLSH190``, and ``SHELL281``. + * - ENKE + - + - Acoustic diffusion energy density + * - **Valid item and component labels for element results are:** + * - :rspan:`3` S + - X, Y, Z, XY, YZ, XZ + - Component stress. This item plots the solution using `nodal-averaged results `_ if they are available on the results file. + * - 1, 2, 3 + - Principal stress. + * - INT + - Stress intensity. + * - EQV + - Equivalent stress. + * - :rspan:`3` EPEL + - X, Y, Z, XY, YZ, XZ + - Component elastic strain. + * - 1, 2, 3 + - Principal elastic strain. + * - INT + - Elastic strain intensity. + * - EQV + - Elastic equivalent strain. + * - :rspan:`3` EPTH + - X, Y, Z, XY, YZ, XZ + - Component thermal strain. + * - 1, 2, 3 + - Principal thermal strain. + * - INT + - Thermal strain intensity. + * - EQV + - Thermal equivalent strain. + * - :rspan:`3` EPDI + - X, Y, Z, XY, YZ, XZ + - Component diffusion strain. + * - 1, 2, 3 + - Principal diffusion strain. + * - INT + - Diffusion strain intensity. + * - EQV + - Diffusion equivalent strain. + * - :rspan:`3` EPPL + - X, Y, Z, XY, YZ, XZ + - Component plastic strain. + * - 1, 2, 3 + - Principal plastic strain. + * - INT + - Plastic strain intensity. + * - EQV + - Plastic equivalent strain. + * - :rspan:`3` EPCR + - X, Y, Z, XY, YZ, XZ + - Component creep strain. + * - 1, 2, 3 + - Principal creep strain. + * - INT + - Creep strain intensity. + * - EQV + - Creep equivalent strain. + * - EPSW + - + - Swelling strain. + * - :rspan:`3` EPTO + - X, Y, Z, XY, YZ, XZ + - Component total mechanical strain (EPEL + EPPL + EPCR). + * - 1, 2, 3 + - Principal total mechanical strain. + * - INT + - Total mechanical strain intensity. + * - EQV + - Total mechanical equivalent strain. + * - :rspan:`3` EPTT + - X, Y, Z, XY, YZ, XZ + - Component total mechanical, thermal, diffusion, and swelling strain (EPEL + EPPL + EPCR + EPTH + EPDI + EPSW). + * - 1, 2, 3 + - Principal total, mechanical, thermal, diffusion, and swelling strain. + * - INT + - Total mechanical, thermal, diffusion, and swelling strain intensity. + * - EQV + - Total mechanical, thermal, diffusion, and swelling equivalent strain. + * - :rspan:`3` ESIG + - X,Y,Z,XY,YZ,ZX + - Components of Biot``s effective stress. + * - 1, 2, 3 + - Principal stresses of Biot``s effective stress. + * - INT + - Stress intensity of Biot``s effective stress. + * - EQV + - Equivalent stress of Biot``s effective stress. + * - :rspan:`2` DPAR + - TPOR + - Total porosity (Gurson material model). + * - GPOR + - Porosity due to void growth. + * - NPOR + - Porosity due to void nucleation. + * - :rspan:`6` NL + - SEPL + - Equivalent stress (from stress-strain curve). + * - SRAT + - Stress state ratio. + * - HPRES + - Hydrostatic pressure. + * - EPEQ + - Accumulated equivalent plastic strain. + * - CREQ + - Accumulated equivalent creep strain. + * - PSV + - Plastic state variable. + * - PLWK + - Plastic work/volume. + * - :rspan:`7` SEND + - ELASTIC The results for this postprocessing SEND component are invalid for ``ELBOW290`` if that element is used with viscoelastic or viscohyperelastic materials. + - Elastic strain energy density. (For `viscoelastic `_ and `sintering `_ materials, the `stored energy `_.) + * - PLASTIC + - Plastic strain energy density. + * - CREEP + - Creep strain energy density. + * - DAMAGE + - Damage strain energy density. + * - VDAM + - Viscoelastic dissipation energy density. + * - VREG + - Visco-regularization strain energy density. + * - DISS + - Structural-thermal dissipation. + * - ENTO + - Total strain energy density (sum of ELASTIC, PLASTIC, and CREEP strain energy densities). + * - :rspan:`1` CDM + - DMG + - Damage variable. + * - LM + - Maximum previous strain energy for virgin material. + * - :rspan:`13` FAIL + - MAX + - Maximum of all active failure criteria defined at the current location. (See :ref:`fctyp`.) Works only if failure criteria are provided ( :ref:`fc` and :ref:`tb` ). + * - EMAX + - Maximum Strain Failure Criterion. + * - SMAX + - Maximum Stress Failure Criterion. + * - TWSI + - Tsai-Wu Strength Index Failure Criterion. + * - TWSR + - Inverse of Tsai-Wu Strength Ratio Index Failure Criterion. + * - HFIB + - Hashin Fiber Failure Criterion. Must first be added ( :ref:`fctyp` ). + * - HMAT + - Hashin Matrix Failure Criterion. + * - PFIB + - Puck Fiber Failure Criterion. + * - PMAT + - Puck Matrix Failure Criterion. + * - L3FB + - LaRc03 Fiber Failure Criterion. + * - L3MT + - LaRc03 Matrix Failure Criterion. + * - L4FB + - LaRc04 Fiber Failure Criterion. + * - L4MT + - LaRc04 Matrix Failure Criterion. + * - USR1, USR2,..., USR9 + - User-defined failure criteria. USR1 through USR9 require a failure-criteria routine. + * - :rspan:`4` PFC + - MAX Failure criteria are based on the effective stresses in the damaged material. + - Maximum of all failure criteria defined at current location. + * - FT + - Fiber tensile failure criteria. + * - FC + - Fiber compressive failure criteria. + * - MT + - Matrix tensile failure criteria. + * - MC + - Matrix compressive failure criteria. + * - :rspan:`7` PDMG + - STAT + - Damage status (0 = undamaged, 1 = damaged, 2 = completely damaged). + * - FT + - Fiber tensile damage variable. + * - FC + - Fiber compressive damage variable. + * - MT + - Matrix tensile damage variable. + * - MC + - Matrix compressive damage variable. + * - S + - Shear damage variable (S). + * - SED + - Energy dissipated per unit volume. + * - SEDV + - Energy per unit volume due to viscous damping. + * - SVAR + - 1, 2, 3,... N + - State variable. + * - GKS + - X, XY, XZ + - Gasket component stress. + * - GKD + - X, XY, XZ + - Gasket component total closure. + * - GKDI + - X, XY, XZ + - Gasket component total inelastic closure. + * - GKTH + - X, XY, XZ + - Gasket component thermal closure. + * - SS + - X, XY, XZ + - Interface traction (stress). + * - SD + - X, XY, XZ + - Interface separation. + * - FICT + - TEMP + - Fictive temperature. + * - :rspan:`9` CONT For contact results, PowerGraphics is supported for 3D models only. For the CONT items for elements ``CONTA172``, ``CONTA174``, ``CONTA175``, and ``CONTA177``, the reported data is averaged across the element. To obtain a more meaningful STAT value, use :ref:`plesol`. + - STAT + - Contact status For MPC-based contact definitions, the value of STAT can be negative, indicating that one or more contact constraints were intentionally removed to prevent overconstraint. STAT = -3 is used for MPC bonded contact; STAT = -2 is used for MPC no-separation contact. : * 3 = closed and sticking * 2 = closed and sliding * 1 = open but near contact * 0 = open and not near contact + * - PENE + - Contact penetration. + * - PRES + - Contact pressure. + * - SFRIC + - Contact friction stress. + * - STOT + - Contact total stress (pressure plus friction). + * - SLIDE + - Contact sliding distance. + * - GAP + - Contact gap distance. + * - FLUX + - Total heat flux at contact surface. + * - CNOS + - Total number of contact status changes during substep. + * - FPRS + - Fluid penetration pressure. + * - TG ``Comp`` = SUM is not supported for coupled pore-pressure-thermal (CPT ``nnn`` ) elements. + - X, Y, Z, SUM + - Component thermal gradient or vector sum. + * - TF + - X, Y, Z, SUM + - Component thermal flux or vector sum. + * - PG + - X, Y, Z, SUM + - Component or vector sum of velocity or energy density flux (room acoustics). + * - EF + - X, Y, Z, SUM + - Component electric field or vector sum. + * - D + - X, Y, Z, SUM + - Component electric flux density or vector sum. + * - H + - X, Y, Z, SUM + - Component magnetic field intensity or vector sum. + * - B + - X, Y, Z, SUM + - Component magnetic flux density or vector sum. + * - CG + - X, Y, Z, SUM + - Component concentration gradient or vector sum. + * - DF + - X, Y, Z, SUM + - Component diffusion flux density or vector sum. + * - CAP + - C0,X0,K0,ZONE, DPLS,VPLS + - Material cap plasticity model only: Cohesion; hydrostatic compaction yielding stress; I1 at the transition point at which the shear and compaction envelopes intersect; zone = 0: elastic state, zone = 1: compaction zone, zone = 2: shear zone, zone = 3: expansion zone; effective deviatoric plastic strain; volume plastic strain. + * - EDPC + - CSIG,CSTR + - Material EDP creep model only (not including the cap model): Equivalent creep stress; equivalent creep strain. + * - FFLX + - X,Y,Z + - Fluid flow flux in poromechanics. + * - FGRA + - X,Y,Z + - Fluid pore-pressure gradient in poromechanics. + * - FMAG + - X, Y, Z, SUM + - Component electromagnetic force or vector sum. + * - JC + - X, Y, Z, SUM + - Conduction current density for elements that support conduction current calculation. Components (X, Y, Z) and vector sum (SUM). + * - BFE + - TEMP + - Body temperatures (calculated from applied temperatures) as used in solution (area and volume elements only). + * - PMSV + - VRAT, PPRE, DSAT, RPER + - Void volume ratio, pore pressure, degree of saturation, and relative permeability for coupled pore-pressure-thermal elements. + * - NS + - X, Y, Z, XY, YZ, XZ + - `Nominal strain `_ for hyperelastic material, reported in the current configuration (unaffected by :ref:`rsys` ). + * - MPLA + - DMAC, DMAX + - Microplane damage, macroscopic and maximum values. + * - MPDP + - TOTA, TENS, COMP, RW + - Microplane homogenized total, tension, and compression damages (TOTA, TENS, COMP), and split weight factor (RW). + * - DAMAGE + - 1,2,3,MAX + - Damage in directions 1, 2, 3 (1, 2, 3) and the maximum damage (MAX). + * - GDMG + - + - Damage + * - IDIS + - + - Structural-thermal dissipation rate + * - BKS + - X, Y, Z, XY, YZ, XZ + - Total `nonlinear kinematic backstress `_ reported in the current configuration (unaffected by :ref:`rsys` ). Available for 3D, plane strain, and axisymmetric elements. + * - BKS1,...,BKS5 + - X, Y, Z, XY, YZ, XZ + - Superimposed components of the total `nonlinear kinematic backstress`_ reported in the current configuration (unaffected by :ref:`rsys` ). Available for 3D, plane strain, and axisymmetric elements when more than one superimposed back-stress component is defined. + * - EPFR + - + - Free strain in porous media + * - SNDI + - X, Y, Z, SUM + - Component sound intensity or vector sum. + * - FC1S + - 1,2,3,4,5,6 + - First set of six components of FCC crystal slip. Available for 3D elements only. + * - FC2S + - 1,2,3,4,5,6 + - Second set of six components of FCC crystal slip. Available for 3D elements only. + * - HC1S + - 1,2,3,4,5,6 + - Six components of HCP crystal slip on basal and prismatic systems. Available for 3D elements only. + * - HC2S + - 1,2,3,4,5,6 + - Six components of HCP crystal slip on pyramidal system. Available for 3D elements only. + * - HC3S + - 1,2,3,4,5,6 + - First set of six components of HCP crystal slip on the first-order pyramidal system. Available for 3D elements only. + * - HC4S + - 1,2,3,4,5,6 + - Second set of six components of HCP crystal slip on the first-order pyramidal system. Available for 3D elements only. + * - HC5S + - 1,2,3,4,5,6 + - Six components of HCP crystal slip on the second-order pyramidal system. Available for 3D elements only. + * - BC1S + - 1,2,3,4,5,6 + - First set of six components of BCC slip on 111 plane. Available for 3D elements only. + * - BC2S + - 1,2,3,4,5,6 + - Second set of six components of BCC slip on 111 plane. Available for 3D elements only. + * - BC3S + - 1,2,3,4,5,6 + - First set of six components of BCC slip on 112 plane. Available for 3D elements only. + * - BC4S + - 1,2,3,4,5,6 + - Second set of six components of BCC slip on 112 plane. Available for 3D elements only. + * - BC5S + - 1,2,3,4,5,6 + - First set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - BC6S + - 1,2,3,4,5,6 + - Second set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - BC7S + - 1,2,3,4,5,6 + - Third set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - BC8S + - 1,2,3,4,5,6 + - Fourth set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - FC1H + - 1,2,3,4,5,6 + - First set of six components of FCC crystal hardness. Available for 3D elements only. + * - FC2H + - 1,2,3,4,5,6 + - Second set of six components of FCC crystal hardness. Available for 3D elements only. + * - HC1H + - 1,2,3,4,5,6 + - Sixcomponents of HCP crystal hardness on basal and prismatic systems. Available for 3D elements. + * - HC2H + - 1,2,3,4,5,6 + - Six components of HCP crystal hardness on pyramidal system. Available for 3D elements only. + * - HC3H + - 1,2,3,4,5,6 + - First set of six components of HCP crystal hardness on the first-order pyramidal system. Available for 3D elements only. + * - HC4H + - 1,2,3,4,5,6 + - Second set of six components of HCP crystal hardness on the first-order pyramidal system. Available for 3D elements only. + * - HC5H + - 1,2,3,4,5,6 + - Six components of HCP crystal hardness on the second-order pyramidal system. Available for 3D elements only. + * - BC1H + - 1,2,3,4,5,6 + - First set of six components of BCC hardness on 111 plane. Available for 3D elements only. + * - BC2H + - 1,2,3,4,5,6 + - Second set of six components of BCC hardness on 111 plane. Available for 3D elements only. + * - BC3H + - 1,2,3,4,5,6 + - First set of six components of BCC hardness on 112 plane. Available for 3D elements only. + * - BC4H + - 1,2,3,4,5,6 + - Second set of six components of BCC hardness on 112 plane. Available for 3D elements only. + * - BC5H + - 1,2,3,4,5,6 + - First set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - BC6H + - 1,2,3,4,5,6 + - Second set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - BC7H + - 1,2,3,4,5,6 + - Third set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - BC8H + - 1,2,3,4,5,6 + - Fourth set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - XELG + - 1,2,3,45,6,EQV + - Crystal Lagrangian strain in 11, 22, 33, 12, 23,13 directions and its equivalent. Available for 3D elements only. + * - SINT + - RHO, ETA, SSTR, GRAIN + - Sintering relative density, viscosity, sintering stress, and average grain size values. + + + .. _PLNSOL_tab_2: + + PLNSOL - Selected Result Component Labels + ***************************************** + + .. flat-table:: Selected Result Component Labels :ref:`plnsol`,SRES, ``Comp`` + :header-rows: 1 + + * - Comp + - Description + * - SVAR ``n`` + - The ``n`` th state variable. + * - FLDUF0 ``n`` + - The ``n`` th user-defined field variable. + + """ + command = f"PLNSOL,{item},{comp},{kund},{fact},{fileid},{avg},{datakey}" + return self.run(command, **kwargs) + + def plorb(self, **kwargs): + r"""Displays the orbital motion of a rotating structure + + Mechanical APDL Command: `PLORB `_ + + Notes + ----- + When a structure is rotating and the Coriolis or gyroscopic effect is taken into account ( + :ref:`coriolis` ), nodes lying on the rotation axis generally exhibit an elliptical orbital motion. + The :ref:`plorb` command displays the `orbit + `_ + of each rotating node as well as the deformed shape at time t = 0 (the real part of the solution). + + To print the characteristics of the orbital path traversed by each node, issue the :ref:`prorb` + command. + + The :ref:`plorb` command is valid for line elements (such as ``BEAM188``, ``BEAM189``, ``PIPE288``, + and ``PIPE289`` ). :ref:`plorb` is not supported for beam elements with the warping degree of + freedom activated. + + Your model must also involve a rotational velocity ( :ref:`omega` or :ref:`cmomega` ) with Coriolis + enabled ( :ref:`coriolis` ). + + Because orbit data is written in the database, a :ref:`set` command must be issued after the + :ref:`plorb` command to ensure proper output for subsequent postprocessing commands. + + The coordinate system for displaying nodal results must be global Cartesian ( :ref:`rsys`, ``KCN`` = + 0). :ref:`plorb` is not supported if nodes are rotated in a cylindrical coordinate system. + """ + command = "PLORB" + return self.run(command, **kwargs) + + def plvect( + self, + item: str = "", + lab2: str = "", + lab3: str = "", + labp: str = "", + mode: str = "", + loc: str = "", + edge: str = "", + kund: int | str = "", + **kwargs, + ): + r"""Displays results as vectors. + + Mechanical APDL Command: `PLVECT `_ + + Parameters + ---------- + item : str + Predefined vector item (from :ref:`plvect_tab_1` below) or a label identifying the i-component + of a user-defined vector. + + lab2 : str + Label identifying the j-component of a user-defined vector. In most cases, this value must be + blank if ``Item`` is selected from :ref:`plvect_tab_1`. Individual principal stresses ( ``Item`` + = S) or principal strains ( ``Item`` = EP ``xx`` ) may be plotted by specifying the value as 1, + 2, or 3. + + lab3 : str + Label identifying the k-component of a user-defined vector. Must be blank if ``Item`` is + selected from list below or for 2D user defined vector. + + labp : str + Label assigned to resultant vector for display labeling (defaults to ``Item`` ). + + mode : str + Vector or raster mode override key: + + * ``(blank)`` - Use the setting of ``KEY`` on the :ref:`device` command. + + * ``RAST`` - Use raster mode for :ref:`plvect` displays. + + * ``VECT`` - Use vector mode for :ref:`plvect` displays. + + loc : str + Vector location for display of field element results: + + * ``ELEM`` - Display at element centroid (default). + + * ``NODE`` - Display at element nodes. + + Nodal results quantities will only be displayed at nodes, not at element centroids. + + edge : str + Edge display override key: + + * ``(blank)`` - Use the setting of Key on the :ref:`edge` command. + + * ``OFF`` - Deactivate the edge display. + + * ``ON`` - Activate the edge display. + + kund : int or str + Undisplaced shape key: + + * ``0`` - Display vectors on undeformed mesh or geometry. + + * ``1`` - Display vectors on deformed mesh or geometry. + + Notes + ----- + + .. _PLVECT_notes: + + Displays various solution results as vectors (arrows) for the selected nodes and/or elements + (elements must contain at least three nodes that are not colinear). For example, :ref:`plvect`,U + displays the displacement vector for all selected nodes. For section displays ( :ref:`slashtype` ), + the vectors are shown only on the section face (that is, cutting plane). The :ref:`plvect` display + of principal strains and stresses ( ``Item`` = S, EPTO, EPEL, EPPL, EPCR, or EPTH) on a "cut" of the + model ( :ref:`slashtype`,,1,5,7,8, or 9) is not supported. The resulting plot displays the vectors + on all selected elements, not on just the sliced surface. See the :ref:`vscale` command to scale + vector lengths. Vector magnitudes may be shown as a contour display with the :ref:`plnsol` command. + Various results also depend upon the recalculation method and the selected results location ( + :ref:`layer`, :ref:`shell`, and :ref:`nsel` ). + + Items may be selected from a set of recognized vector labels ( ``Item`` ) or a vector may be defined + from up to three scalar labels ( ``Item``, ``Lab2``, ``Lab3`` ). Scalar labels may be user-defined + with the :ref:`etable` command. The vectors appear on an element display as arrows showing the + relative magnitude of the vector and its direction. The predefined items will be shown either at the + node or at the element centroid, depending on what item is being displayed and depending on the + ``Loc`` setting. User defined :ref:`etable` items will be shown at the element centroid, regardless + of the ``Loc`` setting. Stress vectors appear as arrows at the element centroid, with the arrowheads + pointing away from each other for tension and toward each other for compression. + + For PowerGraphics, vector arrow displays are generated in Global Cartesian ( :ref:`rsys` = 0). All + subsequent displays will revert to your original coordinate system. + + When vector mode is active ( ``Mode`` = VECT), use the Z-buffered display type ( :ref:`slashtype` + ,,6) to maximize speed of :ref:`plvect` plots (other hidden display types may make plotting slow). + For PowerGraphics ( :ref:`graphics`,POWER), the items marked with [ :ref:`plvect_tab3-43note1` ] are + not supported by PowerGraphics. + + It is possible to plot principal stresses ( ``Item`` = S) or principal strains ( ``Item`` = EP + ``xx`` ) individually. To do so, specify a ``Lab2`` value of 1, 2, or 3. For example, the following + are valid commands: + + * :ref:`plvect`,S,1,,,VECT,ELEM,ON,0 + * :ref:`plvect`,EPEL,3,,,VECT,NODE,ON,0 + + .. _plvect_tab_1: + + PLVECT - Valid Item Labels + ************************** + + .. flat-table:: + :header-rows: 1 + + * - Item + - Description + * - **Valid item labels for nodal degree of freedom vector results are:** + * - U + - Structural displacement vector. + * - ROT + - Structural rotation vector. + * - V + - Velocity vector. + * - A + - Magnetic vector potential vector. + * - FFLX + - Fluid flux in poromechanics. + * - **Valid item labels for structural element results are:** + * - S + - Principal stresses [ :ref:`plvect_tab3-43note1` ]. + * - EPTO + - Principal total strain (EPEL + EPPL + EPCR) [ :ref:`plvect_tab3-43note1` ]. + * - EPEL + - Principal elastic strains [ :ref:`plvect_tab3-43note1` ]. + * - EPPL + - Principal plastic strains [ :ref:`plvect_tab3-43note1` ]. + * - EPCR + - Principal creep strains [ :ref:`plvect_tab3-43note1` ]. + * - EPTH + - Principal thermal strains [ :ref:`plvect_tab3-43note1` ]. + * - EPDI + - Principal diffusion strains [ :ref:`plvect_tab3-43note1` ]. + * - **Valid item labels for field element results are:** + * - TG + - Thermal gradient vector. + * - TF + - Thermal flux vector. + * - PG + - Velocity vector or energy density flux vector (room acoustics). + * - EF + - Electric field vector. + * - D + - Electric flux density vector. + * - H + - Magnetic field intensity vector. If Lab2 is blank, Item is interpreted as one of the predefined labels; otherwise, Item is interpreted as a user-defined :ref:`et` label and the program requests a nonblank Lab2 / Lab3 according to the dimension of the problem. + * - B + - Magnetic flux density vector. + * - CG + - Concentration gradient vector. + * - DF + - Diffusion flux density vector. + * - FMAG + - Electromagnetic force vector. + * - P + - Poynting vector. + * - JS + - Source current density vector for low-frequency magnetic analyses. Total current density vector (sum of conduction and displacement current densities) in low frequency electric analyses. + * - JT + - Total measureable current density vector in low-frequency electromagnetic analyses. (Conduction current density vector in a low-frequency electric analysis.) + * - JC + - Conduction current density vector for elements that support conduction current calculation. + * - SNDI + - Sound intensity vector [ :ref:`plvect_tab3-43note1` ]. + + .. _plvect_tab3-43note1: + + Not supported by PowerGraphics + """ + command = f"PLVECT,{item},{lab2},{lab3},{labp},{mode},{loc},{edge},{kund}" + return self.run(command, **kwargs) + + def prcint(self, id_: str = "", node: str = "", dtype: str = "", **kwargs): + r"""Lists fracture parameter ( :ref:`cint` ) results data. + + Mechanical APDL Command: `PRCINT `_ + + Parameters + ---------- + id_ : str + Crack ID number. + + node : str + Crack tip node number. Default = ALL. Valid only for 3D analysis. + + dtype : str + Data type to output: + + * ``JINT`` - J-integral + + * ``IIN1`` - Interaction integral 1 + + * ``IIN2`` - Interaction integral 2 + + * ``IIN3`` - Interaction integral 3 + + * ``K1`` - Mode 1 stress-intensity factor + + * ``K2`` - Mode 2 stress-intensity factor + + * ``K3`` - Mode 3 stress-intensity factor + + * ``G1`` - Mode 1 energy release rate + + * ``G2`` - Mode 2 energy release rate + + * ``G3`` - Mode 3 energy release rate + + * ``GT`` - Total energy release rate + + * ``MFTX`` - Total material force X + + * ``MFTY`` - Total material force Y + + * ``MFTZ`` - Total material force Z + + * ``TSTRESS`` - T-stress + + * ``CEXT`` - Crack extension + + * ``CSTAR`` - C\2-integral + + * ``STTMAX`` - Maximum circumferential stress + + * ``PSMAX`` - Maximum circumferential stress when :math:`equation_not_available` + + * ``DLTA`` - Incremental crack extension in a `fatigue crack-growth analysis + `_ + + * ``DLTN`` - Number of incremental cycles in a fatigue crack-growth analysis + + * ``DLTK`` - Equivalent stress intensity factors in a fatigue crack-growth analysis + + * ``R`` - Stress (load) ratio in a fatigue crack-growth analysis + + * ``UFAC`` - U-factor (crack closure) in a fatigue crack-growth analysis + + * ``CRDX`` - X coordinate of the crack tip + + * ``CRDY`` - Y coordinate of the crack tip + + * ``CRDZ`` - Z coordinate of the crack tip + + * ``APOS`` - Position attribute of the crack-tip node: + + * ``Positive integer`` - The subcrack Subcracks typically appear in `SMART + `_ + crack-growth analyses and are uncommon in other types of fracture analyses. + + ID number to which this tip belongs. For a crack with only a single subcrack, this value is 1. + + * ``Negative integer`` - The absolute value of the negative integer is the subcrack ID number to + which this tip belongs. + + The negative sign indicates that this crack tip is the end of this subcrack, and that this subcrack + is a closed polygon. It must be connected to the first tip of this subcrack when the crack front is + plotted. + + For more information, see :ref:`aposexamples`. + + Notes + ----- + **Examples: APOS Usage** + + .. _aposexamples: + + The following examples show how APOS values Issuing :ref:`get` is an effective way to obtain APOS + values. + + are applied in several cases for fracture analysis. + + The most common situation is that an open crack exists in ``N`` crack tips, and all tips are + connected into a single subcrack. The APOS values for each tip are: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + For a closed crack without extra subcracks, the APOS values are: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + The following crack has two subcracks, the first open and the second closed. Assuming ``M`` tips on + the first subcrack and ``N`` tips on the second, the APOS values are: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + .. _PRCINT_notes: + + When a crack tip node is defined, the values associated with the specified node are listed. + + ``Dtype`` = STTMAX or PSMAX are valid for `phantom-node-based + `_ + XFEM analyses only. + + ``Dtype`` = CRDX, CRDY, CRDZ, and APOS are valid only in a fatigue/static crack-growth analysis + using `SMART + `_ + or `singularity-based + `_ + XFEM. + + ``Dtype`` = DLTA, DLTN, DLTK, R are valid only in a `fatigue crack-growth analysis + `_ using `SMART + `_ + or `singularity-based + `_ + XFEM. + + ``Dtype`` = UFAC is valid only in a fatigue crack-growth analysis using `SMART + `_. + """ + command = f"PRCINT,{id_},{node},{dtype}" + return self.run(command, **kwargs) + + def prenergy( + self, + energytype: str = "", + cname1: str = "", + cname2: str = "", + cname3: str = "", + cname4: str = "", + cname5: str = "", + cname6: str = "", + **kwargs, + ): + r"""Prints the total energies of a model or the energies of the specified components. + + Mechanical APDL Command: `PRENERGY `_ + + Parameters + ---------- + energytype : str + Type of energies to be printed: + + * ``ALL`` - All energies are printed: potential, kinetic, artificial hourglass/drill stiffness, + contact stabilization energy, and artificial stabilization energy when applicable. This is the + default. + + * ``SENE`` - Potential energy (stiffness energy). + + * ``KENE`` - Kinetic energy. + + * ``DENE`` - Damping energy. + + * ``WEXT`` - Work done by external loads. + + cname1 : str + Component names for energies of the components printout. + + If ``Cname1`` is blank, the total energies are listed. + + If ``Cname1`` = ALL, the energies are listed for all selected components. + + If ``Cname1`` is neither blank nor ALL, it is the name of an existing component. The energies + are listed for up to 6 selected components named in ``Cname1`` to ``Cname6``. + + cname2 : str + Component names for energies of the components printout. + + If ``Cname1`` is blank, the total energies are listed. + + If ``Cname1`` = ALL, the energies are listed for all selected components. + + If ``Cname1`` is neither blank nor ALL, it is the name of an existing component. The energies + are listed for up to 6 selected components named in ``Cname1`` to ``Cname6``. + + cname3 : str + Component names for energies of the components printout. + + If ``Cname1`` is blank, the total energies are listed. + + If ``Cname1`` = ALL, the energies are listed for all selected components. + + If ``Cname1`` is neither blank nor ALL, it is the name of an existing component. The energies + are listed for up to 6 selected components named in ``Cname1`` to ``Cname6``. + + cname4 : str + Component names for energies of the components printout. + + If ``Cname1`` is blank, the total energies are listed. + + If ``Cname1`` = ALL, the energies are listed for all selected components. + + If ``Cname1`` is neither blank nor ALL, it is the name of an existing component. The energies + are listed for up to 6 selected components named in ``Cname1`` to ``Cname6``. + + cname5 : str + Component names for energies of the components printout. + + If ``Cname1`` is blank, the total energies are listed. + + If ``Cname1`` = ALL, the energies are listed for all selected components. + + If ``Cname1`` is neither blank nor ALL, it is the name of an existing component. The energies + are listed for up to 6 selected components named in ``Cname1`` to ``Cname6``. + + cname6 : str + Component names for energies of the components printout. + + If ``Cname1`` is blank, the total energies are listed. + + If ``Cname1`` = ALL, the energies are listed for all selected components. + + If ``Cname1`` is neither blank nor ALL, it is the name of an existing component. The energies + are listed for up to 6 selected components named in ``Cname1`` to ``Cname6``. + + Notes + ----- + + .. _PRENERGY_Notes: + + The :ref:`prenergy` command prints out either the total energies of the entire model or the energies + of the components depending on the ``Cname1`` specification. + + Only existing components based on elements (defined with the :ref:`cm` command) are supported when + component energies are listed. + + Damping energy (DENE) and work done by external loads (WEXT) are available only if the following + were set prior to the analysis solution: ``EngCalc`` = YES on the :ref:`trnopt`, :ref:`hrout` or + :ref:`mxpand` command; and ``Item`` = VENG, ESOL, or ALL on the :ref:`outres` command. + + If ``EngCalc`` = YES on the :ref:`hrout` or :ref:`mxpand` command, average, amplitude, and peak + values are returned for potential (SENE) and kinetic (KENE) energies. + + The energy values can be retrieved using the :ref:`get` command with ``Entity`` = PRENERGY. + + This command applies to structural elements only. + """ + command = f"PRENERGY,{energytype},{cname1},{cname2},{cname3},{cname4},{cname5},{cname6}" + return self.run(command, **kwargs) + + def presol(self, item: str = "", comp: str = "", **kwargs): + r"""Prints the solution results for elements. + + Mechanical APDL Command: `PRESOL `_ + + Parameters + ---------- + item : str + Label identifying the item. Valid item labels are shown in the table below. Some items also + require a component label. + + comp : str + Component of the item (if required). Valid component labels are shown in the table below. + + Notes + ----- + + .. _PRESOL_notes: + + :ref:`presol` prints the solution results for the selected elements in the sorted sequence. + + For example, :ref:`presol`,S prints the stress items SX, SY, SZ, SXY, SYZ, and SXZ for the node + locations of the element. Various element results depend on the calculation method ( :ref:`avprin` + ). + + Component results are in the global Cartesian coordinate directions unless transformed ( :ref:`rsys` + ). + + Shell elements print values at the top, then bottom of the element (or layer). If KEYOPT(8) = 2 (for + ``SHELL181``, ``SHELL208``, ``SHELL209``, ``SHELL281``, or ``ELBOW290`` ), the results are printed + in the order TOP, BOT and then MID of each element, (or layer). The MID value is the actual value to + the results file. + + Items are listed as columns of a table versus element number. An exception occurs for item ELEM, + which uses an element format (where all applicable line element results are listed per element) + instead of a tabular format. + + You can issue :ref:`force` to define which component of the nodal load is to be used (static, + damping, inertia, or total). + + To print items not available via :ref:`presol` (such as line element results), see :ref:`etable` and + :ref:`pretab`. + + For PowerGraphics ( :ref:`graphics`,POWER), results are listed only for the element surface. Items + not supported by PowerGraphics are noted in :ref:`presol_tab_1`. + + The results printed by :ref:`presol` are unaffected by any requested nodal-averaged results ( + :ref:`outres`,NAR). For more information, see `Nodal-Averaged Results + `_ + + For ``Item`` = SRES, selected result components ( :ref:`osresult` ) are output. See + :ref:`presol_tab_2`. + + .. _presol_tab_1: + + PRESOL - General Result Item and Component Labels + ************************************************* + + .. flat-table:: General Item and Component Labels :ref:`presol`, ``Item, Comp`` + :header-rows: 1 + + * - Item + - Comp + - Description + * - :rspan:`1` S + - COMP or blank + - Component (X, Y, Z, XY, YZ, XZ) stresses. + * - PRIN + - Principal stresses (1, 2, 3), stress intensity (INT), and equivalent stress (EQV). + * - :rspan:`1` EPEL + - COMP or blank + - Component (X, Y, Z, XY, YZ, XZ) elastic strains. + * - PRIN + - Principal elastic strains (1, 2, 3), strain intensity (INT), and equivalent strain (EQV). + * - :rspan:`1` EPTH + - COMP or blank + - Component (X, Y, Z, XY, YZ, XZ) thermal strains. + * - PRIN + - Principal thermal strains (1, 2, 3), strain intensity (INT), and equivalent strain (EQV). + * - :rspan:`1` EPDI + - COMP or blank + - Component (X, Y, Z, XY, YZ, XZ) diffusion strains. + * - PRIN + - Principal diffusion strains (1, 2, 3), strain intensity (INT), and equivalent strain (EQV). + * - :rspan:`1` EPPL + - COMP or blank + - Component (X, Y, Z, XY, YZ, XZ) plastic strains. + * - PRIN + - Principal plastic strains (1, 2, 3), strain intensity (INT), and equivalent strain (EQV). + * - :rspan:`1` EPCR + - COMP or blank + - Component (X, Y, Z, XY, YZ, XZ) creep strains. + * - PRIN + - Principal creep strains (1, 2, 3), strain intensity (INT), and equivalent strain (EQV). + * - EPSW + - + - Swelling strain. + * - :rspan:`1` EPTO + - COMP or blank + - Component (X, Y, Z, XY, YZ, XZ) total mechanical strains (EPEL + EPPL + EPCR). + * - PRIN + - Principal total mechanical strains (1, 2, 3), strain intensity (INT), and equivalent strain (EQV). + * - :rspan:`1` EPTT + - COMP or blank + - Component (X, Y, Z, XY, YZ, XZ) total mechanical, thermal, diffusion, and swelling strains (EPEL + EPPL + EPCR + EPTH + EPDI + EPSW). + * - PRIN + - Principal total mechanical, diffusion, thermal, and swelling strains (1, 2, 3), strain intensity (INT), and equivalent strain (EQV). + * - NL + - + - Nonlinear items (SEPL, SRAT, HPRES, EPEQ, CREQ, PSV, PLWK). + * - :rspan:`7` SEND + - ELASTIC The results for this postprocessing SEND component are invalid for ``ELBOW290`` if that element is used with viscoelastic or viscohyperelastic materials. + - Elastic strain energy density. (For `viscoelastic `_ and `sintering `_ materials, the `stored energy `_.) + * - PLASTIC + - Plastic strain energy density. + * - CREEP + - Creep strain energy density. + * - DAMAGE + - Damage strain energy density. + * - VDAM + - Viscoelastic dissipation energy density. + * - VREG + - Visco-regularization strain energy density. + * - DISS + - Structural-thermal dissipation. + * - ENTO + - Total strain energy density (sum of ELASTIC, PLASTIC, and CREEP strain energy densities). + * - :rspan:`1` CDM + - DMG + - Damage variable. + * - LM + - Maximum previous strain energy for virgin material. + * - FAIL + - + - Failure criteria for virgin material. Not supported by PowerGraphics. Works only if failure criteria are provided ( :ref:`fc` and :ref:`tb` ). **Default components:** Maximum of all failure criteria defined at current location (MAX), maximum strain (EMAX), maximum stress (SMAX), Tsai-Wu Strength Index (TWSI), inverse of Tsai-Wu Strength Ratio Index (TWSR). **Other available components:** Hashin Fiber Failure (HFIB), Hashin Matrix Failure (HMAT), Puck Fiber Failure (PFIB), Puck Matrix Failure (PMAT), LaRc03 Fiber Failure (L3FB), LaRc03 Matrix Failure (L3MT), LaRc04 Fiber Failure (L4FB), LaRc04 Matrix Failure (L4MT), and any user-defined failure criteria (USR1 through USR9). USR1 through USR9 require a failure-criteria routine. Issue :ref:`fctyp` to activate or remove failure criteria. + * - PFC + - + - Failure criteria based on the effective stresses in the damaged material. **Components:** Maximum of all failure criteria defined at current location (MAX), fiber tensile failure (FT), fiber compressive failure (FC), matrix tensile failure (MT), and matrix compressive (MC). + * - PDMG + - + - Progressive damage parameters. **Components:** Damage status (STAT, 0 = undamaged, 1 = damaged, 2 = complete damage), fiber tensile damage variable (FT), fiber compressive damage variable (FC), matrix tensile damage variable (MT), matrix compressive damage variable (MC), shear damage variable (S), energy dissipated per unit volume (SED), energy per unit volume due to viscous damping (SEDV). + * - FCMX + - + - Maximum failure criterion over the entire element. **Components:** Layer number where the maximum occurs (LAY), name of the maximum failure criterion (FC), and value of the maximum failure criterion (VAL). + * - SVAR + - 1,2,3,... N + - State variable. + * - GKS + - + - Gasket component (X, XY, XZ) stress. + * - GKD + - + - Gasket component (X, XY, XZ) total closure. + * - GKDI + - + - Gasket component (X, XY, XZ) total inelastic closure. + * - GKTH + - + - Gasket component (X, XY, XZ) thermal closure. + * - CONT + - + - Contact items (STAT, PENE, PRES, SFRIC, STOT, SLIDE, GAP, FLUX, CNOS, FPRS). See component descriptions in :ref:`plesol`. + * - TG + - + - Component (X, Y, Z) thermal gradients and vector sum (SUM). No vector sum is calculated for coupled pore-pressure-thermal (CPT ``nnn`` ) elements. + * - TF + - + - Component (X, Y, Z) thermal fluxes and vector sum (SUM). + * - PG + - + - Component (X, Y, Z) and vector sum (SUM) for velocity or energy density flux (room acoustics). + * - EF + - + - Component (X, Y, Z) electric fields and vector sum (SUM). + * - D + - + - Component (X, Y, Z) electric flux densities and vector sum (SUM). + * - H + - + - Component (X, Y, Z) magnetic field intensities and vector sum (SUM). + * - B + - + - Component (X, Y, Z) magnetic flux densities and vector sum (SUM). + * - CG + - + - Component concentration gradient or vector sum. + * - DF + - + - Component diffusion flux density or vector sum. + * - FMAG + - + - Component (X, Y, Z) electromagnetic forces and vector sum (SUM). + * - P + - + - Poynting vector components (X, Y, Z) and sum (SUM). + * - CG + - + - Concentration gradient. + * - F + - + - Component (X, Y, Z) structural forces. Use :ref:`force` for type. Do not use :ref:`presol` to obtain contact forces for contact elements, as the force values reported may not be accurate for these elements. Use :ref:`etable` instead. + * - M + - + - Component (X, Y, Z) structural moments. + * - HEAT + - + - Heat flow. + * - FLOW + - + - Fluid flow. + * - AMPS + - + - Current flow. + * - CHRG + - + - Charge. + * - FLUX + - + - Magnetic flux. + * - CSG + - + - Component (X, Y, Z) magnetic current segments. + * - FORC + - + - All available force items (F to CSG above). (10 maximum). + * - RATE + - + - Diffusion flow rate. + * - BFE + - TEMP For reinforcing elements ``REINF264`` and ``REINF265``, issue :ref:`presol` ,BFE,TEMP to print the intersection-point temperature of each member. You can also print intersection-point temperature gradients ( :ref:`presol`,TG) and intersection-point heat flux ( :ref:`plesol`,TF). For higher- order reinforcing members (generated when using higher-order base elements), the midpoint values are not available for the reinforcing members. + - Body temperatures (calculated from applied temperatures) as used in solution (area and volume elements only). + * - ELEM + - + - All applicable element results (available only for ``LINK180`` and previous-generation structural line elements). + * - SERR Some element- and material-type limitations apply. See :ref:`prerr`. + - + - Structural error energy. + * - SDSG + - + - Absolute value of the maximum variation of any nodal stress component. + * - TERR + - + - Thermal error energy. + * - TDSG + - + - Absolute value of the maximum variation of any nodal thermal gradient component. + * - SENE + - + - "Stiffness" energy or thermal heat dissipation. Same as TENE. + * - STEN + - + - Elemental energy dissipation due to `stabilization `_. + * - TENE + - + - Thermal heat dissipation or "stiffness" energy. Same as SENE. + * - KENE + - + - Kinetic energy. + * - ASENE + - + - Amplitude "stiffness" energy. + * - PSENE + - + - Peak "stiffness" energy. + * - AKENE + - + - Amplitude kinetic energy. + * - PKENE + - + - Peak kinetic energy. + * - DENE + - + - Damping energy. + * - WEXT WEXT is calculated for element-based loading only (and not for nodal-force loading). WEXT is stored on elements to which loading has been applied; if surface elements are added on top of other elements, for example, and pressure loading is applied to the surface elements, WEXT is available for the surface elements only. + - + - Work due to external load. + * - AENE + - + - Artificial energy due to hourglass control/drill stiffness or due to contact stabilization. + * - JHEAT + - + - Element Joule heat generation (coupled-field calculation). + * - JS + - + - Source current density for low-frequency magnetic analyses. Total current density (sum of conduction and displacement current densities) in low frequency electric analyses. Components (X, Y, Z) and vector sum (SUM). + * - JT + - + - Total measureable current density in low-frequency electromagnetic analyses. (Conduction current density in a low-frequency electric analysis.) Components (X, Y, Z) and vector sum (SUM). + * - JC + - + - Conduction current density for elements that support conduction current calculation. Components (X, Y, Z) and vector sum (SUM). + * - MRE + - + - Magnetic Reynolds number. + * - VOLU + - + - Volume of volume element. + * - CENT + - + - Centroid X, Y, or Z location (based on shape function) in the active coordinate system. + * - LOCI + - + - Integration point location. + * - SMISC + - ``snum`` + - Element summable miscellaneous data value at sequence number ``snum`` (shown in the Output Data section of each element description). + * - NMISC + - ``snum`` + - Element nonsummable miscellaneous data value at sequence number ``snum`` (shown in the Output Data section of each element description). + * - CAP + - + - Material cap plasticity model only: Cohesion (C0); hydrostatic compaction yielding stress (X0); I1 at the transition point at which the shear and compaction envelopes intersect (K0); ZONE = 0: elastic state, ZONE = 1: compaction zone, ZONE = 2: shear zone, ZONE = 3: expansion zone; effective deviatoric plastic strain (DPLS); volume plastic strain (VPLS). + * - EDPC + - + - Material EDP creep model only (not including the cap model): Equivalent creep stress (CSIG); equivalent creep strain (CSTR). + * - FICT + - TEMP + - Fictive temperature. + * - :rspan:`3` ESIG + - COMP or blank + - Components of Biot``s effective stress. + * - PRIN + - Principal stresses of Biot``s effective stress. + * - INT + - Stress intensity of Biot``s effective stress. + * - EQV + - Equivalent stress of Biot``s effective stress. + * - :rspan:`2` DPAR + - TPOR + - Total porosity (Gurson material model). + * - GPOR + - Porosity due to void growth. + * - NPOR + - Porosity due to void nucleation. + * - FFLX + - COMP + - Fluid flow flux components in poromechanics. + * - FGRA + - COMP + - Fluid pore-pressure gradient components in poromechanics. + * - MENE + - + - Acoustic potential energy. + * - PMSV + - COMP + - Void volume ratio, pore pressure, degree of saturation, and relative permeability for coupled pore-pressure CPT elements. + * - FPIDX + - TF01,SF01, TF02,SF02, TF03,SF03, TF04,SF04 + - Failure plane surface activity status for concrete and joint rock material models: 1 = yielded, 0 = not yielded. Tension and shear failure status are available for all four sets of failure planes. + * - YSIDX + - TENS,SHEA + - Yield surface activity status for Mohr-Coulomb, soil, concrete, and joint rock material models: 1 = yielded, 0 = not yielded. + * - NS + - COMP + - `Nominal strain `_ for hyperelastic material, reported in the current configuration (unaffected by :ref:`rsys` ). + * - MPLA + - DMAC,DMAX + - Microplane damage, macroscopic and maximum values. + * - MPDP + - + - Microplane homogenized total, tension, and compression damages (TOTA, TENS, COMP), and split weight factor (RW). + * - DAMAGE + - + - Damage in directions 1, 2, 3 (1, 2, 3) and the maximum damage (MAX). + * - GDMG + - + - Damage + * - IDIS + - + - Structural-thermal dissipation rate + * - BKS + - X, Y, Z, XY, YZ, XZ + - Total `nonlinear kinematic backstress `_ reported in the current configuration (unaffected by :ref:`rsys` ). Available for 3D, plane strain, and axisymmetric elements. + * - BKS1,...,BKS5 + - X, Y, Z, XY, YZ, XZ + - Superimposed components of the total `nonlinear kinematic backstress`_ reported in the current configuration (unaffected by :ref:`rsys` ). Available for 3D, plane strain, and axisymmetric elements when more than one superimposed back-stress component is defined. + * - EPFR + - + - Free strain in porous media + * - SNDI + - + - Component (X, Y, Z) sound intensity and vector sum (SUM). + * - FC1S + - 1,2,3,4,5,6 + - First set of six components of FCC crystal slip. Available for 3D elements only. + * - FC2S + - 1,2,3,4,5,6 + - Second set of six components of FCC crystal slip. Available for 3D elements only. + * - HC1S + - 1,2,3,4,5,6 + - Six components of HCP crystal slip on basal and prismatic systems. Available for 3D elements only. + * - HC2S + - 1,2,3,4,5,6 + - Six components of HCP crystal slip on pyramidal system. Available for 3D elements only. + * - HC3S + - 1,2,3,4,5,6 + - First set of six components of HCP crystal slip on the first-order pyramidal system. Available for 3D elements only. + * - HC4S + - 1,2,3,4,5,6 + - Second set of six components of HCP crystal slip on the first-order pyramidal system. Available for 3D elements only. + * - HC5S + - 1,2,3,4,5,6 + - Six components of HCP crystal slip on the second-order pyramidal system. Available for 3D elements only. + * - BC1S + - 1,2,3,4,5,6 + - First set of six components of BCC slip on 111 plane. Available for 3D elements only. + * - BC2S + - 1,2,3,4,5,6 + - Second set of six components of BCC slip on 111 plane. Available for 3D elements only. + * - BC3S + - 1,2,3,4,5,6 + - First set of six components of BCC slip on 112 plane. Available for 3D elements only. + * - BC4S + - 1,2,3,4,5,6 + - Second set of six components of BCC slip on 112 plane. Available for 3D elements only. + * - BC5S + - 1,2,3,4,5,6 + - First set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - BC6S + - 1,2,3,4,5,6 + - Second set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - BC7S + - 1,2,3,4,5,6 + - Third set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - BC8S + - 1,2,3,4,5,6 + - Fourth set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - FC1H + - 1,2,3,4,5,6 + - First set of six components of FCC crystal hardness. Available for 3D elements only. + * - FC2H + - 1,2,3,4,5,6 + - Second set of six components of FCC crystal hardness. Available for 3D elements only. + * - HC1H + - 1,2,3,4,5,6 + - Sixcomponents of HCP crystal hardness on basal and prismatic systems. Available for 3D elements. + * - HC2H + - 1,2,3,4,5,6 + - Six components of HCP crystal hardness on pyramidal system. Available for 3D elements only. + * - HC3H + - 1,2,3,4,5,6 + - First set of six components of HCP crystal hardness on the first-order pyramidal system. Available for 3D elements only. + * - HC4H + - 1,2,3,4,5,6 + - Second set of six components of HCP crystal hardness on the first-order pyramidal system. Available for 3D elements only. + * - HC5H + - 1,2,3,4,5,6 + - Six components of HCP crystal hardness on the second-order pyramidal system. Available for 3D elements only. + * - BC1H + - 1,2,3,4,5,6 + - First set of six components of BCC hardness on 111 plane. Available for 3D elements only. + * - BC2H + - 1,2,3,4,5,6 + - Second set of six components of BCC hardness on 111 plane. Available for 3D elements only. + * - BC3H + - 1,2,3,4,5,6 + - First set of six components of BCC hardness on 112 plane. Available for 3D elements only. + * - BC4H + - 1,2,3,4,5,6 + - Second set of six components of BCC hardness on 112 plane. Available for 3D elements only. + * - BC5H + - 1,2,3,4,5,6 + - First set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - BC6H + - 1,2,3,4,5,6 + - Second set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - BC7H + - 1,2,3,4,5,6 + - Third set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - BC8H + - 1,2,3,4,5,6 + - Fourth set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - XELG + - 1,2,3,45,6,EQV + - Crystal Lagrangian strain in 11, 22, 33, 12, 23,13 directions and its equivalent. Available for 3D elements only. + * - SINT + - RHO, ETA, SSTR, GRAIN + - Sintering relative density, viscosity, sintering stress, and average grain size values. + + + .. _presol_tab_2: + + PRESOL - Selected Result Component Labels + ***************************************** + + .. flat-table:: Selected Result Component Labels :ref:`presol`,SRES, ``Comp`` + :header-rows: 1 + + * - Comp + - Description + * - SVAR ``n`` + - The ``n`` th state variable. + * - FLDUF0 ``n`` + - The ``n`` th user-defined field variable. + + """ + command = f"PRESOL,{item},{comp}" + return self.run(command, **kwargs) + + def prjsol(self, item: str = "", comp: str = "", **kwargs): + r"""Prints joint element output. + + Mechanical APDL Command: `PRJSOL `_ + + Parameters + ---------- + item : str + Label identifying the item. Some items also require a component label. + + * ``DISP`` - Relative displacements. + + * ``ROT`` - Relative rotations. + + * ``VEL`` - Relative linear velocities. + + * ``OMG`` - Relative angular velocities. + + * ``ACC`` - Relative linear accelerations. + + * ``DMG`` - Relative angular accelerations. + + * ``SMISC`` - Summable miscellaneous quantities. + + comp : str + Component of the item (if required). For ``Item`` = DISP, ROT, VEL, OMG, ACC, and DMG, enter the + direction label, X, Y, or Z. For ``Item`` = SMISC, enter a valid number. + + Notes + ----- + + .. _PRJSOL_notes: + + Prints element output for the ``MPC184`` joint element. The joint element quantities printed are the + values for the free or unconstrained relative degrees of freedom. + + Only :ref:`prjsol`,SMISC is available in linear, modal, and linear perturbation analyses. + + This command is valid in POST1 only. + """ + command = f"PRJSOL,{item},{comp}" + return self.run(command, **kwargs) + + def prnld(self, lab: str = "", tol: int | str = "", item: str = "", **kwargs): + r"""Prints the summed element nodal loads. + + Mechanical APDL Command: `PRNLD `_ + + Parameters + ---------- + lab : str + Nodal reaction load type. If blank, use the first ten of all available labels. Valid labels are: + + * **Structural force labels** : FX, FY or FZ (forces); F (FX, FY and FZ); MX, MY or MZ (moments); M + (MX, MY and MZ). + * **Thermal force labels** : HEAT, HBOT, HE2, HE3,..., HTOP (heat flow). + * **Fluid force labels** : FLOW (fluid flow); VFX, VFY and VFZ (fluid "forces"); VF (VFX, VFY and + VFZ). + * **Electric force labels** : AMPS (current flow); CHRG (charge); CURT (current); VLTG (voltage + drop). + * **Magnetic force labels** : FLUX (magnetic flux); CSGZ (magnetic current segment). + * **Diffusion label** : RATE (diffusion flow rate). + + tol : int or str + Tolerance value about zero within which loads are not printed, as follows: + + * ``> 0`` - Relative tolerance about zero within which loads are not printed. In this case, the tolerance is ``TOL`` \* ``Load``, where ``Load`` is the absolute value of the maximum load on the selected nodes. + + * ``0`` - Print all nodal loads. + + * ``> 0`` - Absolute tolerance about zero within which loads are not printed. + + Defaults to 1.0E-9 times the absolute value of the maximum load on the selected nodes. + + item : str + Selected set of nodes. + + * ``(blank)`` - Prints the summed element nodal loads for all selected nodes (default), excluding + contact elements. + + * ``CONT`` - Prints the summed element nodal loads for contact nodes only. + + * ``BOTH`` - Prints the summed element nodal loads for all selected nodes, including contact nodes. + + Notes + ----- + + .. _PRNLD_notes: + + Prints the summed element nodal loads (forces, moments, heat flows, flux, etc.) for the selected + nodes in the sorted sequence. Results are in the global Cartesian coordinate directions unless + transformed ( :ref:`rsys` ). Zero values (within a tolerance range) are not printed. Loads applied + to a constrained degree of freedom are not included. The :ref:`force` command can be used to define + which component of the nodal load is to be used (static, damping, inertia, or total). + + By default, :ref:`prnld` excludes elements ``TARGE169`` - ``CONTA177``. Setting ``ITEM`` = CONT will + only account for nodal forces on selected contact elements ( ``CONTA172``, ``CONTA174``, + ``CONTA175``, and ``CONTA177`` ). Setting ``ITEM`` = BOTH will account for nodal forces on all + selected nodes, including contact nodes. + + **Using PRNLD in a Spectrum or PSD Analysis ( ANTYPE, SPECTR)** + When using :ref:`prnld` in a spectrum analysis (after the combination file has been input through + :ref:`input`,,MCOM and when :ref:`spopt` has not been issued with ``Elcalc`` = YES during the + spectrum analysis), or in a PSD analysis when postprocessing 1-sigma results (loadstep 3, 4, or 5), + the following message will display in the printout header: + + (Spectrum analysis summation is used) + + This message means that the summation of the element nodal forces is performed prior to the + combination of those forces. In this case, :ref:`rsys` does not apply. The forces are in the nodal + coordinate systems, and the vector sum is always printed in the global coordinate system. + + The spectrum analysis summation is available when the element results are written to the mode file, + :file:`Jobname.mode` ( ``MSUPkey`` = Yes on the :ref:`mxpand` command). + + Because modal displacements cannot be used to calculate contact element nodal forces, ``ITEM`` does + not apply to spectrum and PSD analyses. + """ + command = f"PRNLD,{lab},{tol},{item}" + return self.run(command, **kwargs) + + def prnsol( + self, item: str = "", comp: str = "", avg: str = "", datakey: str = "", **kwargs + ): + r"""Prints nodal solution results. + + Mechanical APDL Command: `PRNSOL `_ + + Parameters + ---------- + item : str + Label identifying the item. Valid item labels are shown in the table below. Some items also + require a component label. + + comp : str + Component of the item (if required). Valid component labels are shown in the table below. + Default = COMP. + + avg : str + Specifies whether random acoustic results are averaged. Valid only for ``Item`` = U and PRES. + + * ``(blank)`` - No averaging (default). + + * ``AVG`` - Print averaged results for random acoustics. + + datakey : str + Key to specify which data is printed: + + * ``AUTO`` - `Nodal-averaged results + `_ are + used if available; otherwise, the element-based data is used, if available. (Default.) + + * ``ESOL`` - Only element-based results are used. If they are not available, the command is ignored. + + * ``NAR`` - Only nodal-averaged results are used. If they are not available, the command is ignored. + + Notes + ----- + + .. _PRNSOL_notes: + + Prints the nodal solution results for the selected nodes in the sorted sequence. For `reinforcing + `_ + elements (REINF ``nnn`` ), results are printed at intersection points of reinforcing elements and + base elements. + + For example, :ref:`prnsol`,U,X prints the X component of displacement vector U (that is, the UX + degree of freedom). + + Component results are in the global Cartesian coordinate directions unless transformed ( :ref:`rsys` + ). + + Various element results also depend upon the recalculation method and the selected results location + ( :ref:`avprin`, :ref:`rsys`, :ref:`layer`, :ref:`shell`, and :ref:`nsel` ). + + If :ref:`layer` is issued, the resulting output is listed in full graphics mode ( + :ref:`graphics`,FULL). + + You can define which component of the nodal load (static, damping, inertia, or total) should be used + ( :ref:`force` ). + + PowerGraphics can affect your nodal solution listings. For PowerGraphics ( :ref:`graphics`,POWER), + results are listed for the model exterior surfaces only. + + When shell element types are present, results are output on a surface-by-surface basis. For shell + elements (such as ``SHELL181`` or ``SHELL281`` ), and for ``ELBOW290``, printed output is for both + the top and bottom surfaces. For solid elements such as ``SOLID185``, the output is averaged for + each surface and printed as follows: + + * **Node at a vertex:** Three lines are output (one printed line for each surface). + + * **Node on an edge:** Two lines are output (one printed line for each surface). + + * **Nodes on a face:** One value is output. + + * **Nodes interior to the volume:** No printed values are output. + + If a node is common to more than one element, or if a geometric discontinuity exists, several + conflicting listings may result. For example, a corner node incorporating results from solid + elements and shell elements could yield as many as nine different results; the printed output would + be averages at the top and bottom for the three shell surfaces plus averages at the three surfaces + for the solid, for a total of nine lines of output. The program does not average result listings + across geometric discontinuities when shell element types are present. It is important to analyze + the listings at discontinuities to ascertain the significance of each set of data. + + When only `reinforcing + `_ + elements (REINF ``nnn`` ) are selected, results are listed for intersection points of reinforcing + elements and base elements. Prints include coordinates of intersection points in global Cartesian + coordinate system and results. Results are interpolated from the results of base elements. If a + point is common to more than one reinforcing element, or reinforcing member within one reinforcing + element, averaged results are printed. Prints also include minimum and maximum values. + + The printed output for full graphics ( :ref:`graphics`,FULL) averages results at the node. For shell + elements, the default for display is TOP so that the results for the top of the shell are averaged + with the other elements attached to that node. + + If :ref:`nsort`, :ref:`esort` or :ref:`eshape` is issued with PowerGraphics enabled ( + :ref:`graphics`,POWER), :ref:`prnsol` behaves as though full graphics mode is enabled ( + :ref:`graphics`,FULL). + + Items not supported by PowerGraphics are noted in :ref:`prnsol_tab_1`. + + For ``Item`` = SRES, selected result component ( :ref:`osresult` ) values are output. See + :ref:`PRNSOL_tab_2`. + + To print midside nodes, first issue :ref:`efacet`,2. + + To learn more about the specific behaviors of :ref:`prnsol` in a cyclic symmetry analysis and + printing results for nodes at cyclic edges, see `Using the /CYCEXPAND Command + `_ + + If `nodal-averaged results + `_ ( + :ref:`outres`,NAR or another nodal-averaged label) are in the database, then :ref:`prnsol` uses the + nodal-averaged data for the applicable items (S, EPEL, EPPL, EPCR, EPTH, EPSW) by default. You can + change this behavior via the ``DataKey`` argument. Keep these points in mind when using nodal- + averaged results: + + * The :ref:`layer` and :ref:`rsys`,SOLU commands are not valid with nodal-averaged results. If these + commands are used, the element solution is printed instead if applicable. + + * Issuing :ref:`esel` before printing nodal-averaged results has no effect on the output. + + * PowerGraphics is supported. The output is equivalent to the full model graphics output, but only + the appropriate surface nodes are printed. See `Postprocessing Nodal-Averaged Results + `_ + + .. _prnsol_tab_1: + + PRNSOL - General Result Item and Component Labels + ************************************************* + + .. flat-table:: General Item and Component Labels :ref:`prnsol`, ``Item,Comp`` + :header-rows: 1 + + * - Item + - Comp + - Description + * - **Valid item and component labels for nodal degree of freedom results are:** + * - :rspan:`1` U + - X, Y, Z + - X, Y, or Z structural displacement. + * - COMP + - X, Y, and Z structural displacements and vector sum. + * - :rspan:`1` ROT + - X, Y, Z + - X, Y, or Z structural rotation. + * - COMP + - X, Y, and Z structural rotations and vector sum. + * - TEMP For ``SHELL131`` and ``SHELL132`` elements with KEYOPT(3) = 0 or 1, use the labels TBOT, TE2, TE3, ..., TTOP instead of TEMP. + - + - Temperature. + * - PRES + - + - Pressure. + * - VOLT + - + - Electric potential. + * - GFV1, GFV2, GFV3 + - + - Nonlocal field values 1, 2, and 3. + * - MAG + - + - Magnetic scalar potential. + * - CONC + - + - Concentration. Not supported by PowerGraphics. + * - :rspan:`1` V + - X, Y, Z + - X, Y, or Z fluid velocity in a fluid analysis. + * - COMP + - X, Y, and Z fluid velocity and vector sum in a fluid analysis. + * - :rspan:`1` A + - X, Y, Z + - X, Y, or Z magnetic vector potential in an electromagnetic analysis. + * - COMP + - X, Y, and Z magnetic vector potential and vector sum in an electromagnetic analysis. + * - :rspan:`1` VEL + - X, Y, Z + - X, Y, or Z velocity in a structural transient dynamic analysis ( :ref:`antype`,TRANS). + * - COMP + - X, Y, and Z velocity and vector sum in a structural transient dynamic analysis ( :ref:`antype`,TRANS). + * - :rspan:`1` ACC + - X, Y, Z + - X, Y, or Z acceleration in a structural transient dynamic analysis ( :ref:`antype`,TRANS). + * - COMP + - X, Y, and Z acceleration and vector sum in a structural transient dynamic analysis ( :ref:`antype`,TRANS). + * - :rspan:`1` OMG + - X, Y, Z + - X, Y, or Z rotational velocity in a structural transient dynamic analysis ( :ref:`antype`,TRANS). + * - COMP + - X, Y, and Z rotational velocity and vector sum in a structural transient dynamic analysis ( :ref:`antype`,TRANS). + * - :rspan:`1` DMG + - X, Y, Z + - X, Y, or Z rotational acceleration in a structural transient dynamic analysis ( :ref:`antype`,TRANS). + * - COMP + - X, Y, and Z rotational acceleration and vector sum in a structural transient dynamic analysis ( :ref:`antype`,TRANS). + * - CURR + - + - Current. + * - EMF + - + - Electromotive force drop. + * - DOF + - + - All available degree of freedom labels (10 maximum). + * - FICT + - TEMP + - Fictive temperature. + * - SPL + - + - Sound pressure level. + * - SPLA + - + - A-weighted sound pressure level (dBA). + * - VNS + - + - Normal velocity on the structural surface. Valid only for ``SHELL181``, ``SOLID185``, ``SOLID186``, ``SOLID187``, ``SOLSH190``, and ``SHELL281``. + * - ENKE + - + - Acoustic diffusion energy density + * - **Valid item and component labels for element results are:** + * - :rspan:`1` S + - COMP + - X, Y, Z, XY, YZ, and XZ component stresses. This item outputs `nodal-averaged results `_ if they are available on the results file. + * - PRIN + - S1, S2, S3 principal stresses, SINT stress intensity, and SEQV equivalent stress. + * - :rspan:`2` EPEL + - COMP + - Component elastic strains. + * - PRIN + - Principal elastic strains, strain intensity, and equivalent strain. + * - FAIL + - Maximum Strain Failure Criteria. Works only if failure criteria are provided ( :ref:`fc` and :ref:`tb` ). + * - :rspan:`1` EPTH + - COMP + - Component thermal strains. + * - PRIN + - Principal thermal strains, strain intensity, and equivalent strain. + * - :rspan:`1` EPDI + - COMP + - Component diffusion strains. + * - PRIN + - Principal diffusion strains, strain intensity, and equivalent strain. + * - :rspan:`1` EPPL + - COMP + - Component plastic strains. + * - PRIN + - Principal plastic strains, strain intensity, and equivalent strain. + * - :rspan:`1` EPCR + - COMP + - Component creep strains. + * - PRIN + - Principal creep strains, strain intensity, and equivalent strain. + * - EPSW + - + - Swelling strain. + * - :rspan:`1` EPTO + - COMP + - Component total mechanical strains (EPEL + EPPL + EPCR). + * - PRIN + - Principal total mechanical strains, strain intensity, and equivalent strain. + * - :rspan:`1` EPTT + - COMP + - Component total mechanical, thermal, diffusion, and swelling strains (EPEL + EPPL + EPCR + EPTH + EPDI + EPSW). + * - PRIN + - Principal total mechanical, thermal, diffusion, and swelling strains, strain intensity, and equivalent strain. + * - NL + - + - Nonlinear items (SEPL, SRAT, HPRES, EPEQ, CREQ, PSV, PLWK). + * - :rspan:`7` SEND + - ELASTIC The results for this postprocessing SEND component are invalid for ``ELBOW290`` if that element is used with viscoelastic or viscohyperelastic materials. + - Elastic strain energy density. (For `viscoelastic `_ and `sintering `_ materials, the `stored energy `_.) + * - PLASTIC + - Plastic strain energy density. + * - CREEP + - Creep strain energy density. + * - DAMAGE + - Damage strain energy density. + * - VDAM + - Viscoelastic dissipation energy density. + * - VREG + - Visco-regularization strain energy density. + * - DISS + - Structural-thermal dissipation. + * - ENTO + - Total strain energy density (sum of ELASTIC, PLASTIC, and CREEP strain energy densities). + * - :rspan:`1` CDM + - DMG + - Damage variable. + * - LM + - Maximum previous strain energy for virgin material. + * - FAIL + - + - Failure criteria. **Default components:** Maximum of all failure criteria defined at current location (MAX), maximum strain (EMAX), maximum stress (SMAX), Tsai-Wu Strength Index (TWSI), inverse of Tsai-Wu Strength Ratio Index (TWSR). **Other available components:** Other available components: Hashin Fiber Failure (HFIB), Hashin Matrix Failure (HMAT), Puck Fiber Failure (PFIB), Puck Matrix Failure (PMAT), LaRc03 Fiber Failure (L3FB), LaRc03 Matrix Failure (L3MT), LaRc04 Fiber Failure (L4FB), LaRc04 Matrix Failure (L4MT), and any user-defined failure criteria (USR1 through USR9). USR1 through USR9 require a failure-criteria routine. Issue :ref:`fctyp` to activate or remove failure criteria. + * - PFC + - + - Failure criteria based on the effective stresses in the damaged material. **Components:** Maximum of all failure criteria defined at current location (MAX), fiber tensile failure (FT), fiber compressive failure (FC), matrix tensile failure (MT), and matrix compressive (MC). + * - PDMG + - + - Progressive damage parameters. **Components:** Damage status (STAT, 0 = undamaged, 1 = damaged, 2 = complete damage), fiber tensile damage variable (FT), fiber compressive damage variable (FC), matrix tensile damage variable (MT), matrix compressive damage variable (MC), shear damage variable (S), energy dissipated per unit volume (SED), energy per unit volume due to viscous damping (SEDV). + * - SVAR Not supported by PowerGraphics. + - 1, 2, 3,... N + - State variable. + * - GKS + - COMP + - X, XY, XZ component gasket stress. + * - GKD + - COMP + - X, XY, XZ component gasket total closure. + * - GKDI + - COMP + - X, XY, XZ component gasket total inelastic closure. + * - GKTH + - COMP + - X, XY, XZ component thermal closure. + * - SS + - X, XY, XZ + - Interface traction (stress). + * - SD + - X, XY, XZ + - Interface separation. + * - CONT + - + - Contact items (STAT For contact elements ``CONTA172``, ``CONTA174``, ``CONTA175``, and ``CONTA177``, the reported data are averaged across the element. To obtain a more meaningful STAT value, use :ref:`presol`., PENE, PRES, SFRIC, STOT, SLIDE, GAP, FLUX, CNOS, FPRS). See component descriptions in :ref:`plnsol`. + * - TG + - COMP + - Component thermal gradients and vector sum. No vector sum is calculated for coupled pore-pressure-thermal (CPT ``nnn`` ) elements. + * - TF + - COMP + - Component thermal fluxes and vector sum. + * - PG + - COMP + - Components and vector sum for velocity or energy density flux (room acoustics). + * - EF + - COMP + - Component electric fields and vector sum. + * - D + - COMP + - Component electric flux densities and vector sum. + * - H + - COMP + - Component magnetic field intensities and vector sum. + * - B + - COMP + - Component magnetic flux densities and vector sum. + * - CG + - COMP + - Component concentration gradient or vector sum. + * - DF + - COMP + - Component diffusion flux density or vector sum. + * - FMAG + - COMP + - Component electromagnetic forces and vector sum. + * - JC + - COMP + - Conduction current density for elements that support conduction current calculation. Components (X, Y, Z) and vector sum (SUM). + * - BFE + - + - Body temperatures (calculated from applied temperatures) as used in solution (area and volume elements only). + * - CAP + - + - Material cap plasticity model only: Cohesion (C0); hydrostatic compaction yielding stress (X0); I1 at the transition point at which the shear and compaction envelopes intersect (K0); ZONE = 0: elastic state, ZONE = 1: compaction zone, ZONE = 2: shear zone, ZONE = 3: expansion zone; effective deviatoric plastic strain (DPLS); volume plastic strain (VPLS). + * - EDPC + - + - Material EDP creep model only (not including the cap model): Equivalent creep stress (CSIG); equivalent creep strain (CSTR). + * - :rspan:`3` ESIG + - COMP or blank + - Components of Biot``s effective stress. + * - PRIN + - Principal stresses of Biot``s effective stress. + * - INT + - Stress intensity of Biot``s effective stress. + * - EQV + - Equivalent stress of Biot``s effective stress. + * - :rspan:`2` DPAR + - TPOR + - Total porosity (Gurson material model). + * - GPOR + - Porosity due to void growth. + * - NPOR + - Porosity due to void nucleation. + * - FFLX + - COMP + - Fluid flow flux in poromechanics. + * - FGRA + - COMP + - Fluid pore pressure gradient components in poromechanics. + * - PMSV + - COMP + - Void volume ratio, pore pressure, degree of saturation, and relative permeability for coupled pore-pressure CPT elements. + * - NS + - COMP + - `Nominal strain `_ for hyperelastic material, reported in the current configuration (unaffected by :ref:`rsys` ). + * - MPLA + - DMAC, DMAX + - Microplane damage, macroscopic and maximum values. + * - MPDP + - + - Microplane homogenized total, tension, and compression damages (TOTA, TENS, COMP), and split weight factor (RW). + * - DAMAGE + - + - Damage in directions 1, 2, 3 (1, 2, 3) and the maximum damage (MAX). + * - GDMG + - + - Damage + * - IDIS + - + - Structural-thermal dissipation rate + * - BKS + - X, Y, Z, XY, YZ, XZ + - Total `nonlinear kinematic backstress `_ reported in the current configuration (unaffected by :ref:`rsys` ). Available for 3D, plane strain, and axisymmetric elements. + * - BKS1,...,BKS5 + - X, Y, Z, XY, YZ, XZ + - Superimposed components of the total `nonlinear kinematic backstress`_ reported in the current configuration (unaffected by :ref:`rsys` ). Available for 3D, plane strain, and axisymmetric elements when more than one superimposed back-stress component is defined. + * - EPFR + - + - Free strain in porous media + * - SNDI + - COMP + - Component sound intensity and vector sum. + * - FC1S + - 1,2,3,4,5,6 + - First set of six components of FCC crystal slip. Available for 3D elements only. + * - FC2S + - 1,2,3,4,5,6 + - Second set of six components of FCC crystal slip. Available for 3D elements only. + * - HC1S + - 1,2,3,4,5,6 + - Six components of HCP crystal slip on basal and prismatic systems. Available for 3D elements only. + * - HC2S + - 1,2,3,4,5,6 + - Six components of HCP crystal slip on pyramidal system. Available for 3D elements only. + * - HC3S + - 1,2,3,4,5,6 + - First set of six components of HCP crystal slip on the first-order pyramidal system. Available for 3D elements only. + * - HC4S + - 1,2,3,4,5,6 + - Second set of six components of HCP crystal slip on the first-order pyramidal system. Available for 3D elements only. + * - HC5S + - 1,2,3,4,5,6 + - Six components of HCP crystal slip on the second-order pyramidal system. Available for 3D elements only. + * - BC1S + - 1,2,3,4,5,6 + - First set of six components of BCC slip on 111 plane. Available for 3D elements only. + * - BC2S + - 1,2,3,4,5,6 + - Second set of six components of BCC slip on 111 plane. Available for 3D elements only. + * - BC3S + - 1,2,3,4,5,6 + - First set of six components of BCC slip on 112 plane. Available for 3D elements only. + * - BC4S + - 1,2,3,4,5,6 + - Second set of six components of BCC slip on 112 plane. Available for 3D elements only. + * - BC5S + - 1,2,3,4,5,6 + - First set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - BC6S + - 1,2,3,4,5,6 + - Second set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - BC7S + - 1,2,3,4,5,6 + - Third set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - BC8S + - 1,2,3,4,5,6 + - Fourth set of six components of BCC slip on 123 plane. Available for 3D elements only. + * - FC1H + - 1,2,3,4,5,6 + - First set of six components of FCC crystal hardness. Available for 3D elements only. + * - FC2H + - 1,2,3,4,5,6 + - Second set of six components of FCC crystal hardness. Available for 3D elements only. + * - HC1H + - 1,2,3,4,5,6 + - Sixcomponents of HCP crystal hardness on basal and prismatic systems. Available for 3D elements. + * - HC2H + - 1,2,3,4,5,6 + - Six components of HCP crystal hardness on pyramidal system. Available for 3D elements only. + * - HC3H + - 1,2,3,4,5,6 + - First set of six components of HCP crystal hardness on the first-order pyramidal system. Available for 3D elements only. + * - HC4H + - 1,2,3,4,5,6 + - Second set of six components of HCP crystal hardness on the first-order pyramidal system. Available for 3D elements only. + * - HC5H + - 1,2,3,4,5,6 + - Six components of HCP crystal hardness on the second-order pyramidal system. Available for 3D elements only. + * - BC1H + - 1,2,3,4,5,6 + - First set of six components of BCC hardness on 111 plane. Available for 3D elements only. + * - BC2H + - 1,2,3,4,5,6 + - Second set of six components of BCC hardness on 111 plane. Available for 3D elements only. + * - BC3H + - 1,2,3,4,5,6 + - First set of six components of BCC hardness on 112 plane. Available for 3D elements only. + * - BC4H + - 1,2,3,4,5,6 + - Second set of six components of BCC hardness on 112 plane. Available for 3D elements only. + * - BC5H + - 1,2,3,4,5,6 + - First set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - BC6H + - 1,2,3,4,5,6 + - Second set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - BC7H + - 1,2,3,4,5,6 + - Third set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - BC8H + - 1,2,3,4,5,6 + - Fourth set of six components of BCC hardness on 123 plane. Available for 3D elements only. + * - XELG + - 1,2,3,45,6,EQV + - Crystal Lagrangian strain in 11, 22, 33, 12, 23,13 directions and its equivalent. Available for 3D elements only. + * - SINT + - RHO, ETA, SSTR, GRAIN + - Sintering relative density, viscosity, sintering stress, and average grain size values. + + + .. _PRNSOL_tab_2: + + PRNSOL - Selected Result Component Labels + ***************************************** + + .. flat-table:: Selected Result Component Labels :ref:`prnsol`,SRES, ``Comp`` + :header-rows: 1 + + * - Comp + - Description + * - SVAR ``n`` + - The ``n`` th state variable. + * - FLDUF0 ``n`` + - The ``n`` th user-defined field variable. + + """ + command = f"PRNSOL,{item},{comp},,,,{avg},{datakey}" + return self.run(command, **kwargs) + + def prorb(self, whrlnodkey: str = "", **kwargs): + r"""Prints the orbital motion characteristics of a rotating structure + + Mechanical APDL Command: `PRORB `_ + + Parameters + ---------- + whrlnodkey : str + Flag to print the whirl for each node: + + * ``1 (ON or YES)`` - Print the whirl for each node. + + * ``0 (OFF or NO)`` - No printout. This value is the default. + + Notes + ----- + When a structure is rotating and the Coriolis or gyroscopic effect is taken into account ( + :ref:`coriolis` ), nodes lying on the rotation axis generally exhibit an elliptical orbital motion. + The :ref:`prorb` command prints out the `orbit + `_ + characteristics A, B, PSI, PHI, YMAX, ZMAX, and Whirl of each rotating node, where + + * A is the semi-major axis. + * B is the semi-minor axis. + * PSI is the angle between local y axis and major axis. + * PHI is the angle between initial position (t = 0) and major axis. + * YMAX is the maximum displacement along local y axis. + * ZMAX is the maximum displacement along local z axis. + * Whirl is the direction of an orbital motion (BW for backward whirl and FW for forward whirl). + + Angles PSI and PHI are in degrees and within the range of -180 through +180. + + To display the characteristics of the orbital path traversed by each node, issue the :ref:`plorb` + command. + + The :ref:`prorb` command is valid for line elements (such as ``BEAM188``, ``BEAM189``, ``PIPE288``, + and ``PIPE289`` ). :ref:`prorb` is not supported for beam elements with the warping degree of + freedom activated. + + Your model must also involve a rotational velocity ( :ref:`omega` or :ref:`cmomega` ) with Coriolis + enabled ( :ref:`coriolis` ). + + Because orbit data is written in the database, a :ref:`set` command must be issued after the + :ref:`prorb` command to ensure proper output for subsequent postprocessing commands. + + The coordinate system for displaying nodal results must be global Cartesian ( :ref:`rsys`, ``KCN`` = + 0). :ref:`prorb` is not supported if nodes are rotated in a cylindrical coordinate system. + """ + command = f"PRORB,{whrlnodkey}" + return self.run(command, **kwargs) + + def prrfor(self, lab: str = "", **kwargs): + r"""Prints the constrained node reaction solution. Used with the :ref:`force` command. + + Mechanical APDL Command: `PRRFOR `_ + + Parameters + ---------- + lab : str + Nodal reaction load type. If blank, use the first ten of all available labels. Valid labels are: + + * **Structural force labels** : FX, FY or FZ (forces); F (FX, FY and FZ); MX, MY or MZ (moments); M + (MX, MY and MZ). + * **Thermal force labels** : HEAT, HBOT, HE2, HE3,..., HTOP (heat flow). + * **Fluid force labels** : FLOW (fluid flow); VFX, VFY and VFZ (fluid forces); VF (VFX, VFY and + VFZ). + * **Electric force labels** : AMPS (current flow); CHRG (charge); CURT (current); VLTG (voltage + drop). + * **Magnetic force labels** : FLUX (magnetic flux); CSGZ (magnetic current segment); CURT (current), + VLTG (voltage drop). + * **Diffusion labels** : RATE (diffusion flow rate). + + Notes + ----- + + .. _PRRFOR_notes: + + :ref:`prrfor` has the same functionality as the :ref:`prrsol` command; use :ref:`prrfor` instead of + :ref:`prrsol` when a :ref:`force` command has been issued. + + In a non-spectrum analysis, if either contact or pretension elements exist in the model, + :ref:`prrfor` uses the :ref:`prrsol` command internally and the :ref:`force` setting is ignored. + + Because modal displacements cannot be used to calculate contact element nodal forces, those forces + are not included in the spectrum and PSD analyses reaction solution. As a consequence, the + :ref:`prrfor` command is not supported when constraints on contact element pilot nodes are present. + + :ref:`prrfor` is not valid when using the amplitude or phase results set ( ``KIMG`` = AMPL or PHAS + on the :ref:`set` command). Use :ref:`prrsol` instead. + + **Using PRRFOR in a Spectrum or PSD Analysis ( ANTYPE,SPECTR)** + When using :ref:`prrfor` in a spectrum analysis (after the combination file has been input through + :ref:`input`,,MCOM and when :ref:`spopt` has not been issued with ``Elcalc`` = YES during the + spectrum analysis), or in a PSD analysis when postprocessing 1-sigma results (loadstep 3, 4, or 5), + the following message will display in the printout header: + + .. code:: apdl + + (Spectrum analysis summation is used) + + This message means that the summation of the element nodal forces is performed prior to the + combination of those forces. In this case, :ref:`rsys` does not apply, and the reaction forces are + in the nodal coordinate systems. Unlike :ref:`prrsol`, which retrieves the forces from the database, + the :ref:`prrfor` command calculates the forces in the postprocessor. + + The spectrum analysis summation is available when the element results are written to the mode file, + :file:`Jobname.mode` ( ``MSUPkey`` = Yes on :ref:`mxpand` ). + + The spectrum analysis summation is not available after reading a load case ( :ref:`lcwrite`, + :ref:`lczero`, :ref:`lcase` ). + """ + command = f"PRRFOR,{lab}" + return self.run(command, **kwargs) + + def prrsol(self, lab: str = "", **kwargs): + r"""Prints the constrained node reaction solution. + + Mechanical APDL Command: `PRRSOL `_ + + Parameters + ---------- + lab : str + Nodal reaction load type. If blank, use the first ten of all available labels. Valid labels are: + + * **Structural force labels** : FX, FY or FZ (forces); F (FX, FY and FZ); MX, MY or MZ (moments); M + (MX, MY and MZ); BMOM (bimoments). + * **Thermal force labels** : HEAT, HBOT, HE2, HE3,..., HTOP (heat flow). + * **Fluid force labels** : FLOW (fluid flow); VFX, VFY and VFZ (fluid forces); VF (VFX, VFY and + VFZ). + * **Electric force labels** : AMPS (current flow); CHRG (charge); CURT (current); VLTG (voltage + drop). + * **Magnetic force labels** : FLUX (magnetic flux); CSGZ (magnetic current segment); CURT (current), + VLTG (voltage drop). + * **Diffusion labels** : RATE (diffusion flow rate). + + Notes + ----- + + .. _PRRSOL_notes: + + Prints the constrained node reaction solution for the selected nodes in the sorted sequence. For + coupled nodes and nodes in constraint equations, the sum of all reactions in the coupled or + constraint equation set appears at the primary node of the set. Results are in the global Cartesian + coordinate directions unless transformed ( :ref:`rsys` ). + + :ref:`prrsol` is not valid if any load is applied to a constrained node in the direction of the + constraint and any of the following is true: + + * :ref:`lcoper` has been used. + + * :ref:`lcase` has been used to read from a load case file. + + * The applied loads and constraints in the database are not the ones used to create the results data + being processed. + + :ref:`prrsol` provides the total reaction solution (static, plus damping, plus inertial, as + appropriate based on the analysis type); however, modal reactions include only the static + contribution. + + Use :ref:`prrfor` instead of :ref:`prrsol` with the :ref:`force` command to obtain only the static, + damping, or inertial components. + + When using distributed-memory parallel processing, in a spectrum analysis or a PSD analysis + performed with ``Elcalc`` = YES on the :ref:`spopt` command, use :ref:`prrfor` instead of + :ref:`prrsol` to print the maximum reaction forces (spectrum analysis) or reaction forces variances + of 1-σ solutions, as :ref:`prrsol` may lead to more conservative results. + """ + command = f"PRRSOL,{lab}" + return self.run(command, **kwargs) + + def prvect( + self, item: str = "", lab2: str = "", lab3: str = "", labp: str = "", **kwargs + ): + r"""Prints results as vector magnitude and direction cosines. + + Mechanical APDL Command: `PRVECT `_ + + Parameters + ---------- + item : str + Predefined vector item (from :ref:`prvect_tab_1` below) or a label identifying the i-component + of a user-defined vector. + + lab2 : str + Label identifying the j-component of a user-defined vector. In most cases, this value must be + blank if ``Item`` is selected from :ref:`prvect_tab_1`. Individual principal stresses ( ``Item`` + = S) or principal strains ( ``Item`` = EP ``xx`` ) may be printed by specifying the value as 1, + 2, or 3. + + lab3 : str + Label identifying the k-component of a user-defined vector. Must be blank if ``Item`` is + selected from list below or for 2D user defined vector. + + labp : str + Label assigned to resultant vector for printout labeling (defaults to ``Item`` ). + + Notes + ----- + + .. _PRVECT_notes: + + Prints various solution results as vector magnitude and direction cosines for the selected nodes + and/or elements. For example, :ref:`prvect`,U prints the displacement magnitude and its direction + cosines for all selected nodes. For nodal degree of freedom vector results, direction cosines are + with respect to the results coordinate system RSYS. For element results, direction cosines are with + respect to the global Cartesian system. Item components may be printed with the :ref:`prnsol` + command. Various results also depend upon the recalculation method and the selected results location + ( :ref:`layer`, :ref:`shell`, :ref:`nsel`, and :ref:`esel` ). Items may be selected from a set of + recognized vector labels ( ``Item`` ) or a vector may be defined from up to three scalar labels ( + ``Item``, ``Lab2``, ``Lab3`` ). Scalar labels may be user-defined with the :ref:`etable` command. + + Portions of this command are not supported by PowerGraphics ( :ref:`graphics`,POWER). + + .. _prvect_tab_1: + + PRVECT - Valid Item and Component Labels + **************************************** + + .. flat-table:: + :header-rows: 1 + + * - Item + - Comp + - Description + * - Valid item labels for nodal degree of freedom vector results are: + * - U + - + - Structural displacement vector magnitude and direction cosines. + * - ROT + - + - Structural rotation vector magnitude and direction cosines. + * - V + - + - Velocity vector magnitude and direction cosines. + * - A + - + - Magnetic vector potential vector magnitude and direction cosines. + * - Valid item labels for element results are: + * - S + - + - Principal stresses and direction cosines. + * - EPTO + - + - Principal total strains (EPEL + EPPL + EPCR) and direction cosines. + * - EPEL + - + - Principal elastic strains and direction cosines. + * - EPPL + - + - Principal plastic strains and direction cosines. + * - EPCR + - + - Principal creep strains and direction cosines. + * - EPTH + - + - Principal thermal strains and direction cosines. + * - EPDI + - + - Principal diffusion strains and direction cosines. + * - TG + - + - Thermal gradient vector sum and direction cosines. + * - TF + - + - Thermal flux vector sum and direction cosines. + * - PG + - + - Velocity or energy density flux (room acoustics) vector sum and direction cosines. + * - EF + - + - Electric field vector sum and direction cosines. + * - D + - + - Electric flux density vector sum and direction cosines. + * - H + - + - Magnetic field intensity vector sum and direction cosines. If ``Lab2`` is blank, Item is interpreted as one of the predefined labels; otherwise, Item is interpreted as a user-defined :ref:`et` label and the program requests a non-blank ``Lab2`` / ``Lab3`` according to the dimension of the problem. + * - B + - + - Magnetic flux density vector sum and direction cosines. + * - CG + - + - Concentration gradient vector sum and direction cosines. + * - DF + - + - Diffusion flux density vector sum and direction cosines. + * - FMAG + - + - Electromagnetic force vector sum and direction cosines. + * - P + - + - Poynting vector sum and direction cosines. + * - JS + - + - Source current density vector sum and direction cosines for low-frequency magnetic analyses. Total current density vector sum and direction cosines (sum of conduction and displacement current densities) in low frequency electric analyses. + * - JT + - + - Total measurable current density vector sum and direction cosines in low-frequency electromagnetic analyses. (Conduction current density vector sum and direction cosines in a low-frequency electric analysis.) + * - JC + - + - Conduction current density vector sum and direction cosines for elements that support conduction current calculation. + * - SNDI + - + - Sound intensity vector sum and direction cosines. + + """ + command = f"PRVECT,{item},{lab2},{lab3},{labp}" + return self.run(command, **kwargs) + + def sumtype(self, label: str = "", **kwargs): + r"""Sets the type of summation to be used in the following load case operations. + + Mechanical APDL Command: `SUMTYPE `_ + + Parameters + ---------- + label : str + Summation type + + * ``COMP`` - Combine element component stresses only. Stresses such as average nodal stresses, + principal stresses, equivalent stresses, and stress intensities are derived from the combined + element component stresses. Default. + + * ``PRIN`` - Combine principal stress, equivalent stress, and stress intensity directly as stored on + the results file. Component stresses are not available with this option. + + Notes + ----- + + .. _SUMTYPE_notes: + + Issue :ref:`sumtype`,PRIN when you want to have a load case operation ( :ref:`lcoper` ) act on the + principal / equivalent stresses instead of the component stresses. Also issue :ref:`sumtype`,PRIN + when you want to read in load cases ( :ref:`lcase` ). Note that the :ref:`sumtype` setting is not + maintained between /POS T1 sessions. + + :ref:`sumtype`,PRIN also causes principal nodal values to be the average of the contibuting + principal element nodal values (see :ref:`avprin`,1). + + ``BEAM188`` and ``BEAM189`` elements compute principal stress, equivalent stress, and stress + intensity values on request instead of storing them on the results file; :ref:`sumtype`,PRIN does + not apply for these elements. + """ + command = f"SUMTYPE,{label}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1/set_up.py b/src/ansys/mapdl/core/_commands/post1/set_up.py new file mode 100644 index 0000000000..2b7430bf5c --- /dev/null +++ b/src/ansys/mapdl/core/_commands/post1/set_up.py @@ -0,0 +1,1135 @@ +# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + + +class SetUp: + + def append( + self, + lstep: str = "", + sbstep: str = "", + fact: str = "", + kimg: int | str = "", + time: str = "", + angle: str = "", + nset: str = "", + **kwargs, + ): + r"""Reads data from the results file and appends it to the database. + + Mechanical APDL Command: `APPEND `_ + + Parameters + ---------- + lstep : str + Load step number of the data set to be read. Defaults to 1. If FIRST, ignore ``SBSTEP`` and + ``TIME`` and read the first data set. If LAST, ignore ``SBSTEP`` and ``TIME`` and read the last + data set. If NEXT, ignore ``SBSTEP`` and ``TIME`` and read the next data set. If already at the + last data set, the next set is the first data set. If NEAR, ignore ``SBSTEP`` and read the data + set nearest to ``TIME``. If ``TIME`` is blank, read the first data set. If LIST, scan the + results file to produce a summary of each load step ( ``FACT``, ``KIMG``, ``TIME`` and ``ANGLE`` + are ignored). + + sbstep : str + Substep number (within ``LSTEP`` ) (defaults to last substep of load step). For the Buckling ( + :ref:`antype`,BUCKLE) or Modal ( :ref:`antype`,MODAL) analysis, the substep corresponds to the + mode number (defaults to first mode). If ``LSTEP`` = LIST, ``SBSTEP`` = 0 or 1 will list the + basic load step information; ``SBSTEP`` = 2 will also list the load step title, and label the + imaginary data sets if they exist. + + fact : str + Scale factor applied to data read from the file. If zero (or blank), a value of 1.0 is used. + Harmonic velocities or accelerations may be calculated from the displacement results from a + modal or harmonic ( :ref:`antype`,HARMIC) analyses. If ``FACT`` = VELO, the harmonic velocities + (v) are calculated from the displacements (d) at a particular frequency (f) according to the + relationship v = 2 πfd. Similarly, if ``FACT`` = ACEL, the harmonic accelerations (a) are + calculated as a = (2 πf) :sup:`2` d. + + kimg : int or str + Used only with results from complex analyses: + + * ``0`` - Store real part of complex solution. + + * ``1`` - Store imaginary part. + + time : str + Time-point identifying the data set to be read. For harmonic analyses, time corresponds to the + frequency. For the buckling analysis, time corresponds to the load factor. Used only in the + following cases: If ``LSTEP`` is NEAR, read the data set nearest to ``TIME``. If both ``LSTEP`` + and ``SBSTEP`` are zero (or blank), read data set at time = ``TIME``. If ``TIME`` is between two + solution time points on the results file, a linear interpolation is done between the two data + sets. Solution items not written to the results file ( :ref:`outres` ) for either data set will + result in a null item after data set interpolation. If ``TIME`` is beyond the last time point on + the file, the last time point is used. + + angle : str + Circumferential location (0° to 360°). Defines the circumferential location for the harmonic + calculations used when reading from the results file. The harmonic factor (based on the + circumferential angle) is applied to the harmonic elements ( ``PLANE25``, ``PLANE75``, + ``PLANE78``, ``PLANE83``, and ``SHELL61`` ) of the load case. See the `Mechanical APDL Theory + Reference `_ + for details. Note that factored values of applied constraints and loads will overwrite any + values existing in the database. + + nset : str + Data set number of the data set to be read. If a positive value for ``NSET`` is entered, + ``LSTEP``, ``SBSTEP``, ``KIMG``, and ``TIME`` are ignored. Available set numbers can be + determined by :ref:`append`,LIST. To determine if data sets are real or imaginary, issue + :ref:`append`,LIST,2 which labels imaginary data sets. + + Notes + ----- + + .. _APPEND_notes: + + Reads a data set from the results file and appends it to the existing data in the database for the + selected model only. The existing database is not cleared (or overwritten in total), allowing the + requested results data to be merged into the database. Various operations may also be performed + during the read operation. The database must have the model geometry available (or used the + :ref:`resume` command before the :ref:`append` command to restore the geometry from :file:`File.DB` + ). + """ + command = f"APPEND,{lstep},{sbstep},{fact},{kimg},{time},{angle},{nset}" + return self.run(command, **kwargs) + + def desol( + self, + elem: str = "", + node: str = "", + item: str = "", + comp: str = "", + v1: str = "", + v2: str = "", + v3: str = "", + v4: str = "", + v5: str = "", + v6: str = "", + **kwargs, + ): + r"""Defines or modifies solution results at a node of an element. + + Mechanical APDL Command: `DESOL `_ + + Parameters + ---------- + elem : str + Element number for which results are defined or modified. If ALL, apply to all selected elements + ( :ref:`esel` ). + + node : str + Node of element (actual node number, not the position) to which results are specified. If ALL, + specify results for all selected nodes ( :ref:`nsel` ) of element. If ``NODE`` = P, graphical + picking is enabled and all remaining command fields are ignored (valid only in the GUI). A + component name may also be substituted for ``NODE``. + + item : str + Label identifying results. Valid item labels are shown in :ref:`DESOL_tab_1` below. Some items + also require a component label ( ``Comp`` ). + + comp : str + Component of the item (if required); see :ref:`DESOL_tab_1`. + + v1 : str + Additional values (if any) assigned to the remaining components (in the order corresponding to + the ``Comp`` list shown below) for the specified ``Item`` (starting from the specified ``Comp`` + label and proceeding to the right). + + v2 : str + Additional values (if any) assigned to the remaining components (in the order corresponding to + the ``Comp`` list shown below) for the specified ``Item`` (starting from the specified ``Comp`` + label and proceeding to the right). + + v3 : str + Additional values (if any) assigned to the remaining components (in the order corresponding to + the ``Comp`` list shown below) for the specified ``Item`` (starting from the specified ``Comp`` + label and proceeding to the right). + + v4 : str + Additional values (if any) assigned to the remaining components (in the order corresponding to + the ``Comp`` list shown below) for the specified ``Item`` (starting from the specified ``Comp`` + label and proceeding to the right). + + v5 : str + Additional values (if any) assigned to the remaining components (in the order corresponding to + the ``Comp`` list shown below) for the specified ``Item`` (starting from the specified ``Comp`` + label and proceeding to the right). + + v6 : str + Additional values (if any) assigned to the remaining components (in the order corresponding to + the ``Comp`` list shown below) for the specified ``Item`` (starting from the specified ``Comp`` + label and proceeding to the right). + + Notes + ----- + + .. _DESOL_notes: + + The :ref:`desol` command defines or modifies solution results in the database at a node of an area + or volume element. For example, :ref:`desol`,35,50,S,X,1000,2000,1000 assigns values 1000, 2000, and + 1000 to SX, SY, and SZ (respectively) of node 50 of element 35. + + The settings of the POST1 :ref:`force`, :ref:`shell`, and :ref:`layer` commands, if applicable, + further specify which database items are affected. + + For layered composite shells, specify the current element layer ( :ref:`layer` ) before issuing the + :ref:`desol` command. + + All data is stored in the solution coordinate system but is displayed in the results coordinate + system ( :ref:`rsys` ). To list the current results, use the :ref:`presol` command. + + Modified solution results are not saved automatically. To save separate records of modified results, + use either the :ref:`rappnd` or :ref:`lcwrite` command. + + Result items are available depending on element type; check the individual element for availability. + Valid item and component labels for element results are: + + .. _DESOL_tab_1: + + DESOL - Valid Item and Component Labels + *************************************** + + .. flat-table:: + :header-rows: 1 + + * - Item + - Comp + - Description + * - ELEM + - + - Element number. + * - S + - X, Y, Z, XY, YZ, XZ + - Component stress. + * - EPEL + - X, Y, Z, XY, YZ, XZ + - Component elastic strain. + * - EPTH + - X, Y, Z, XY, YZ, XZ + - Component thermal strain. + * - EPPL + - X, Y, Z, XY, YZ, XZ + - Component plastic strain. + * - EPCR + - X, Y, Z, XY, YZ, XZ + - Component creep 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. + * - SEND + - ELASTIC + - Elastic strain energy density. + * - " + - PLASTIC + - Plastic strain energy density. + * - " + - CREEP + - Creep strain energy density. + * - 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. + * - CG + - X, Y, Z + - Concentration gradient + * - DF + - X, Y, Z + - Diffusion flux density + * - FMAG + - X, Y, Z + - Component electromagnetic force. + * - F + - X, Y, Z + - X, Y, or Z structural force. + * - M + - X, Y, Z + - X, Y, or Z structural moment. + * - HEAT + - + - Heat flow. + * - FLOW + - + - Fluid flow. + * - AMPS + - + - Current flow. + * - FLUX + - + - Magnetic flux. + * - CSG + - X, Y, Z + - X, Y, or Z magnetic current segment component. + * - RATE + - + - Diffusion flow rate + + """ + command = f"DESOL,{elem},{node},{item},{comp},{v1},{v2},{v3},{v4},{v5},{v6}" + return self.run(command, **kwargs) + + def detab( + self, + elem: str = "", + lab: str = "", + v1: str = "", + v2: str = "", + v3: str = "", + v4: str = "", + v5: str = "", + v6: str = "", + **kwargs, + ): + r"""Modifies element table results in the database. + + Mechanical APDL Command: `DETAB `_ + + Parameters + ---------- + elem : str + Element for which results are to be modified. If ALL, modify all selected elements ( :ref:`esel` + ) results. If ``ELEM`` = P, graphical picking is enabled and all remaining command fields are + ignored (valid only in the GUI). A component name may also be substituted for ``ELEM``. + + lab : str + Label identifying results. Valid labels are as defined with the :ref:`etable` command. Issue + :ref:`etable`, ``STAT`` to display labels and values. + + v1 : str + Additional values (if any) assigned to consecutive element table columns. + + v2 : str + Additional values (if any) assigned to consecutive element table columns. + + v3 : str + Additional values (if any) assigned to consecutive element table columns. + + v4 : str + Additional values (if any) assigned to consecutive element table columns. + + v5 : str + Additional values (if any) assigned to consecutive element table columns. + + v6 : str + Additional values (if any) assigned to consecutive element table columns. + + Notes + ----- + + .. _DETAB_notes: + + Modifies element table ( :ref:`etable` ) results in the database. For example, :ref:`detab` + ,35,ABC,1000,2000,1000 assigns 1000, 2000, and 1000 to the first three table columns starting with + label ABC for element 35. Use the :ref:`pretab` command to list the current results. After deleting + a column of data using :ref:`etable`, ``Lab``,ERASE, the remaining columns of data are not shifted + to compress the empty slot. Therefore, the user must allocate null (blank) values for ``V1``, + ``V2``... ``V6`` for any ETABLE entries which have been deleted by issuing :ref:`etable`, + ``Lab``,ERASE. All data are stored in the solution coordinate system but will be displayed in the + results coordinate system ( :ref:`rsys` ). + """ + command = f"DETAB,{elem},{lab},{v1},{v2},{v3},{v4},{v5},{v6}" + return self.run(command, **kwargs) + + def dnsol( + self, + node: str = "", + item: str = "", + comp: str = "", + v1: str = "", + v2: str = "", + v3: str = "", + v4: str = "", + v5: str = "", + v6: str = "", + datakey: str = "", + **kwargs, + ): + r"""Defines or modifies solution results at a node. + + Mechanical APDL Command: `DNSOL `_ + + Parameters + ---------- + node : str + Node for which results are specified. If ALL, apply to all selected nodes ( :ref:`nsel` ). If + ``NODE`` = P, graphical picking is enabled and all remaining command fields are ignored (valid + only in the GUI). A component name may also be substituted for ``NODE``. + + item : str + Label identifying results, see :ref:`DNSOL_tab_1`. Some items also require a component label. + + comp : str + Component of the item. Valid component labels are shown :ref:`DNSOL_tab_1` below. + + v1 : str + Value assigned to result. If zero, a zero value will be assigned. If blank, the value remains + unchanged. Additional values (if any) assigned to the remaining components (in the order + corresponding to the ``Comp`` list shown below for the specified ``Item`` (starting from the + specified ``Comp`` label and proceeding to the right). + + v2 : str + Value assigned to result. If zero, a zero value will be assigned. If blank, the value remains + unchanged. Additional values (if any) assigned to the remaining components (in the order + corresponding to the ``Comp`` list shown below for the specified ``Item`` (starting from the + specified ``Comp`` label and proceeding to the right). + + v3 : str + Value assigned to result. If zero, a zero value will be assigned. If blank, the value remains + unchanged. Additional values (if any) assigned to the remaining components (in the order + corresponding to the ``Comp`` list shown below for the specified ``Item`` (starting from the + specified ``Comp`` label and proceeding to the right). + + v4 : str + Value assigned to result. If zero, a zero value will be assigned. If blank, the value remains + unchanged. Additional values (if any) assigned to the remaining components (in the order + corresponding to the ``Comp`` list shown below for the specified ``Item`` (starting from the + specified ``Comp`` label and proceeding to the right). + + v5 : str + Value assigned to result. If zero, a zero value will be assigned. If blank, the value remains + unchanged. Additional values (if any) assigned to the remaining components (in the order + corresponding to the ``Comp`` list shown below for the specified ``Item`` (starting from the + specified ``Comp`` label and proceeding to the right). + + v6 : str + Value assigned to result. If zero, a zero value will be assigned. If blank, the value remains + unchanged. Additional values (if any) assigned to the remaining components (in the order + corresponding to the ``Comp`` list shown below for the specified ``Item`` (starting from the + specified ``Comp`` label and proceeding to the right). + + datakey : str + Key to specify which data is modified: + + * ``AUTO`` - `Nodal-averaged results + `_ are + used if available. Otherwise, the element-based data is used if available. (Default) + + * ``ESOL`` - Only element-based results are used. If they are not available, the command is ignored. + + * ``NAR`` - Only nodal-averaged results are used. If they are not available, the command is ignored. + + Notes + ----- + + .. _DNSOL_notes: + + :ref:`dnsol` can be used only with FULL graphics activated ( :ref:`graphics`,FULL); it will not work + correctly with PowerGraphics activated. + + :ref:`dnsol` defines or modifies solution results in the database at a node. For example, + :ref:`dnsol`,35,U,X,.001,.002,.001 assigns values 0.001, 0.002, and 0.001 to UX, UY, and UZ + (respectively) for node 35. All results that are changed in the database, including the nodal degree + of freedom results, are available for all subsequent operations. All data is stored in the solution + coordinate system but is displayed in the results coordinate system ( :ref:`rsys` ). Use + :ref:`prnsol` to list the current results. + + Data input by :ref:`dnsol` is stored in temporary space and does not replace information in the + database. Therefore, data input by this command may be overwritten if a change is made to the + selected set of nodes or if an output operation acts on a new ``Item``. + + Issuing :ref:`dnsol` requires you to place the data type (stress/strain) in the element nodal + records. To work around this requirement, use the :ref:`desol` command or equivalent path to add a + dummy element stress/strain record. + + Result items are available depending on element type; check the individual element for availability. + Valid item and component labels for element results are shown in :ref:`DNSOL_tab_1`. + + Using :ref:`dnsol` with Nodal-Averaged Results + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + If `nodal-averaged results + `_ ( + :ref:`outres`,NAR or another nodal-averaged label) are in the database, then :ref:`dnsol` acts on + the nodal-averaged data for the applicable items (S, EPEL, EPPL, EPCR, EPTH, EPSW) by default. You + can change this behavior via the ``DataKey`` argument. + + :ref:`dnsol` behavior differs when the command acts on `nodal-averaged results + `_. + The nodal-averaged results that are defined or modified will be apparent in subsequent command + operations (for example :ref:`prnsol`, :ref:`plnsol` ) in both full model graphics mode ( + :ref:`graphics`,FULL) and PowerGraphics mode ( :ref:`graphics`,POWER). The resultant data is stored + in the global Cartesian coordinate system but is displayed in the results coordinate system ( + :ref:`rsys` ). :ref:`dnsol` can only be applied to nodal-averaged results if they are already in the + database; otherwise, the modifications are applied to the element-based solution in temporary + memory. The modified nodal-averaged results are not saved to the results file automatically. To save + separate records of modified nodal-averaged results, use :ref:`lcwrite`, :ref:`rappnd`, or + :ref:`reswrite`. + + :ref:`dnsol` can only modify component values ( ``Comp`` = X, Y, Z, XY, YZ, or XZ) for nodal- + averaged results. If you attempt to modify principal values using :ref:`dnsol` with ``DataKey`` = + AUTO, then the modification is applied to element-based results if they are available. + + .. _DNSOL_tab_1: + + DNSOL - Valid Item and Component Labels + *************************************** + + .. flat-table:: Valid Item and Component Labels for Nodal DOF Results + :header-rows: 1 + + * - Item + - Comp + - Description + * - U + - X, Y, Z + - X, Y, or Z structural displacement. + * - ROT + - X, Y, Z + - X, Y, or Z structural rotation. + * - TEMP[ :ref:`DNSOL_temp` ] + - + - Temperature. + * - PRES + - + - Pressure. + * - VOLT + - + - Electric potential. + * - MAG + - + - Magnetic scalar potential. + * - V + - X, Y, Z + - X, Y, or Z fluid velocity. + * - A + - X, Y, Z + - X, Y, or Z magnetic vector potential. + * - CONC + - + - Concentration. + + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + .. _DNSOL_temp: + + For ``SHELL131`` and ``SHELL132`` elements with KEYOPT(3) = 0 or 1, use the labels TBOT, TE2, + TE3,..., TTOP instead of TEMP. + + .. _DNSOL_NAR: + + For these component values, `nodal-averaged results + `_ are + modified if they are available in the results file and ``DataKey`` = AUTO or NAR. + + .. _DNSOL_NAR_2: + + Modifying principal values of nodal-averaged results is not supported. + """ + command = f"DNSOL,{node},{item},{comp},{v1},{v2},{v3},{v4},{v5},{v6},{datakey}" + return self.run(command, **kwargs) + + def hrcplx( + self, + loadstep: str = "", + substep: str = "", + omegat: str = "", + firstlcase: str = "", + secondlcase: str = "", + **kwargs, + ): + r"""Computes and stores in the database the time-harmonic solution at a prescribed phase angle. + + Mechanical APDL Command: `HRCPLX `_ + + Parameters + ---------- + loadstep : str + Load step number of the data set to be read (defaults to 1). + + substep : str + Substep number within ``LOADSTEP``. + + omegat : str + Angle in degrees (Ω (angle) times T (time)). + + * If ≥ 360°, the amplitude is supplied. + + * All others supply results at that angle. For example, if the angle is set to 0.0°, the real part + of the solution is supplied. If the angle is set to -90° the imaginary part of the solution is + supplied. + + firstlcase : str + First load case number (defaults to 1). + + secondlcase : str + Second load case number (defaults to 2). + + Notes + ----- + + .. _HRCPLX_notes: + + :ref:`hrcplx` invokes a macro that combines the real and imaginary parts of the solution. If the + angle is specified, it produces the following: + + .. math:: + + equation_not_available + + R R and R I are, respectively, the real and imaginary parts of the results quantity (e.g. the nodal + displacements, the reaction forces,...). + + α is the angle (OMEGAT). + + ``1STLCASE`` and ``2NDLCASE`` are internally generated load cases. You may want to specify these to + avoid overwriting an existing load case number 1 or 2. + + Not all results computed by this command are valid. See `Summable, Non-Summable and Constant Data + `_ in + the `Basic Analysis Guide + `_ for more + information. When the amplitude of the solution is requested ( ``OMEGAT`` >= + 360°), averaged values (such as the nodal component stresses, which are an average of element nodal + component stresses) are calculated by averaging the amplitudes. Because the degrees of freedom + results have different phases, derived results (such as the equivalent stress SEQV) are not valid. + See `POST1 and POST26 - Complex Results Postprocessing + `_ + + For postprocessing amplitudes, the only appropriate coordinate system is the solution coordinate + system ( :ref:`rsys`,SOLU). When displaying the displacement amplitudes, use a contour display ( + :ref:`plnsol` command). Because a deformed shape display ( :ref:`pldisp` command) could lead to a + non-physical shape, the displacement scaling is off by default ( :ref:`slashdscale`,,OFF). + + For postprocessing cylindrical geometry, it is suggested that you rotate the element coordinate + systems into the appropriate cylindrical system ( ``EMODIF,,ESYS`` ) before running the solution and + then view the results in this system ( ``RSYS,SOLU`` ) in POST1. + + Since :ref:`hrcplx` performs load case combinations, it alters most of the data in the database. In + particular, it alters applied loads such as forces and imposed displacements. To restore the + original loads in the database for a subsequent analysis, reissue the :ref:`set` command in POST1 to + retrieve the real and imaginary set data. + + To animate the solution over one period, use the :ref:`anharm` command. + + ``OMEGAT`` is not equal to the phase shift. + + This command is not supported after a cyclic symmetry analysis; use :ref:`cycexpand`,,PHASEANG + instead. + """ + command = f"HRCPLX,{loadstep},{substep},{omegat},{firstlcase},{secondlcase}" + return self.run(command, **kwargs) + + def rescombine( + self, + numfiles: str = "", + fname: str = "", + ext: str = "", + lstep: str = "", + sbstep: str = "", + fact: str = "", + kimg: str = "", + time: str = "", + angle: str = "", + nset: str = "", + order: str = "", + **kwargs, + ): + r"""Reads results from local results files into the database after a distributed-memory parallel + solution. + + Mechanical APDL Command: `RESCOMBINE `_ + + Parameters + ---------- + numfiles : str + Number of local results files that are to be read into the database from the distributed-memory + parallel solution. This number should be equal to the number of processes used in the parallel + solution. + + fname : str + File name (jobname) used during the distributed parallel solution. The file name must be an + alphanumeric string (up to 32 characters) enclosed in single quotes. + + ext : str + File extension for the results files (for example, RST, RTH, RMG, etc.). The file extension must + be an alphanumeric string (up to 8 characters) enclosed in single quotes. + + lstep : str + Load step number of the data set to be read (defaults to 1): + + * ``N`` - Read load step ``N``. + + * ``FIRST`` - Read the first data set ( ``Sbstep`` and ``TIME`` are ignored). + + * ``LAST`` - Read the last data set ( ``Sbstep`` and ``TIME`` are ignored). + + * ``NEXT`` - Read the next data set ( ``Sbstep`` and ``TIME`` are ignored). If at the last data set, + the first data set will be read as the next. + + * ``PREVIOUS`` - Read the previous data set ( ``Sbstep`` and ``TIME`` are ignored). If at the first + data set, the last data set will be read as the previous. + + * ``NEAR`` - Read the data set nearest to ``TIME`` ( ``Sbstep`` is ignored). If ``TIME`` is blank, + read the first data set. + + * ``LIST`` - Scan the results files and list a summary of each load step ( ``KIMG``, ``TIME``, + ``ANGLE``, ``NSET``, and ``ORDER`` are ignored.) + + sbstep : str + Substep number within ``Lstep`` (defaults to the last substep of the load step). For a buckling + ( :ref:`antype`,BUCKLE) or modal ( :ref:`antype`,MODAL) analysis, ``Sbstep`` corresponds to the + mode number (defaults to the first mode). Specify ``Sbstep`` = LAST to store the last substep + for the specified load step. + + If ``Lstep`` = LIST, ``Sbstep`` = 0 or 1 lists the basic step information; ``Sbstep`` = 2 also + lists the basic step information, but includes the load step title, and labels imaginary data + sets if they exist. + + fact : str + Scale factor applied to data read from the files. If zero (or blank), a value of 1.0 is used. A + nonzero factor excludes non-summable items. Harmonic velocities or accelerations may be + calculated from the displacement results from a modal ( :ref:`antype`,MODAL) or harmonic ( + :ref:`antype`,HARMIC) analysis. If ``Fact`` = VELO, the harmonic velocities (v) are calculated + from the displacements (d) at a particular frequency (f) according to the relationship v = 2πfd. + Similarly, if ``Fact`` = ACEL, the harmonic accelerations (a) are calculated as a = (2πf) + :sup:`2` d. + + kimg : str + Used only with complex results (harmonic and complex modal analyses). + + * ``0 or REAL`` - Store the real part of a complex solution (default). + + * ``1, 2 or IMAG`` - Store the imaginary part of a complex solution. + + time : str + Time-point identifying the data set to be read. For a harmonic analysis, time corresponds to the + frequency. For a buckling analysis, time corresponds to the load factor. Used only in the + following cases: If ``Lstep`` = NEAR, read the data set nearest to ``TIME``. If both ``Lstep`` + and ``Sbstep`` are zero (or blank), read data set at time = ``TIME``. If ``TIME`` is between two + solution time points on the results file, a linear interpolation is done between the two data + sets. Solution items not written to the results file ( :ref:`outres` ) for either data set will + result in a null item after data set interpolation. If ``TIME`` is beyond the last time point on + the file, the last time point will be used. + + angle : str + Circumferential location (0.0 to 360°). Defines the circumferential location for the harmonic + calculations used when reading from the results file. The harmonic factor (based on the + circumferential angle) is applied to the harmonic elements ( ``PLANE25``, ``PLANE75``, + ``PLANE78``, ``PLANE83``, and ``SHELL61`` ) of the load case. See the `Mechanical APDL Theory + Reference `_ + for details. Note that factored values of applied constraints and loads will overwrite any + values existing in the database. + + nset : str + Data set number of the data set to be read. If a positive value for ``NSET`` is entered, + ``Lstep``, ``Sbstep``, ``KIMG``, and ``TIME`` are ignored. Available set numbers can be + determined by :ref:`rescombine`,,,,LIST. + + order : str + Key to sort the harmonic index results. This option applies to `cyclic symmetry `_ buckling and modal analyses only, and is valid only when ``Lstep`` = FIRST, LAST, NEXT, PREVIOUS, NEAR or LIST. + + * ``ORDER`` - Sort the harmonic index results in ascending order of eigenfrequencies or buckling + load multipliers. + + * ``(blank)`` - No sorting takes place. + + Notes + ----- + + .. _RESCOMBINE_notes: + + :ref:`rescombine` is a Mechanical APDL command macro enabling you to combine results from a + distributed- + memory parallel ( DMP ) solution. A character string input for any argument must be enclosed in + single quotes (for example, 'FIRST' input for ``Lstep`` ). + + In a distributed memory parallel solution, a global results file is saved by default. However, if + you issued :ref:`dmpoption`,RST,NO in the parallel solution, no global results file is written and + all local results files will be kept. In this case, you can use :ref:`rescombine` in the general + postprocessor ( :ref:`post1` ) to read results into the database for postprocessing. + + :ref:`rescombine` cannot be used to combine results from local files generated during a distributed- + memory parallel solution that used the frequency or cyclic harmonic index domain decomposition + method ( :ref:`ddoption`,FREQ or :ref:`ddoption`,CYCHI). + + To use :ref:`rescombine`, all local results files from the distributed-memory parallel solution must + be in the current working directory. If running on a single machine, the local results files are + saved in the working directory by default. If running on a cluster, the local results files are kept + in the working directory on each compute node. For the latter case, copy the local results files to + the working directory on the primary compute node. + + Similar to :ref:`set`, :ref:`rescombine` defines the data set to be read from the results files into + the database. Various operations can also be performed during the read operation. (See :ref:`set` + for more information.) The database must have the model data available (or issue :ref:`resume` + before :ref:`rescombine` to restore the geometry from :file:`Jobname.DB` ). + + After issuing :ref:`rescombine` to combine a set of data into the database, you can issue + :ref:`reswrite` to write the data set into a new results file. The new results file will essentially + contain the current set of results data for the entire (that is, global) model. + + Upon completion of a :ref:`rescombine` operation, the current file for postprocessing ( ``FILE`` ) + is set to the last local results file specified via :ref:`rescombine`. For example, if reading in + four local results files, the results file for POST1 is specified as :file:`Jobname3.RST` when + :ref:`rescombine` is complete. Therefore, be aware that some downstream postprocessing actions (such + as :ref:`set` ) may be operating on only this one local results file. + + :ref:`rescombine` is intended for use in POST1. If you want to postprocess DMP solution results + using the POST26 time-history postprocessor, combine your local results files into one global + results file ( :ref:`dmpoption`,RST,YES). + + The load case commands in the general postprocessor (such as :ref:`lcdef`, :ref:`lcfile`, + :ref:`lcoper`, etc.) are not supported when using :ref:`rescombine`. Those commands set up pointers + in the results file used for postprocessing; they cannot be used with the local results files used + by :ref:`rescombine`. + + :ref:`cycexpand`, which performs a cyclic expansion, cannot be used with :ref:`rescombine`. + """ + command = f"RESCOMBINE,{numfiles},{fname},{ext},{lstep},{sbstep},{fact},{kimg},{time},{angle},{nset},{order}" + return self.run(command, **kwargs) + + def reset(self, **kwargs): + r"""Resets all POST1 or POST26 specifications to initial defaults. + + Mechanical APDL Command: `RESET `_ + + Notes + ----- + + .. _RESET_notes: + + Has the same effect as entering the processor the first time within the run. In POST1, resets all + specifications to initial defaults, erases all element table items, path table data, and load case + pointers. In POST26, resets all specifications to initial defaults, erases all variables defined, + and zeroes the data storage space. + """ + command = "RESET" + return self.run(command, **kwargs) + + def set( + self, + lstep: str = "", + sbstep: str = "", + fact: str = "", + kimg: str = "", + time: str = "", + angle: str = "", + nset: str = "", + order: str = "", + **kwargs, + ): + r"""Defines the data set to be read from the results file. + + Mechanical APDL Command: `SET `_ + + Parameters + ---------- + lstep : str + Load step number of the data set to be read (defaults to 1): + + * ``N`` - Read load step ``N``. + + * ``FIRST`` - Read the first data set ( ``Sbstep`` and ``TIME`` are ignored). + + * ``LAST`` - Read the last data set ( ``Sbstep`` and ``TIME`` are ignored). + + * ``NEXT`` - Read the next data set ( ``Sbstep`` and ``TIME`` are ignored). If at the last data set, + the first data set will be read as the next. + + * ``PREVIOUS`` - Read the previous data set ( ``Sbstep`` and ``TIME`` are ignored). If at the first + data set, the last data set will be read as the previous. + + * ``NEAR`` - Read the data set nearest to ``TIME`` ( ``Sbstep`` is ignored). If ``TIME`` is blank, + read the first data set. + + * ``LIST`` - Scan the results file and list a summary of each load step. ( ``KIMG``, ``TIME``, + ``ANGLE``, and ``NSET`` are ignored.) + + sbstep : str + Substep number (within ``Lstep`` ). Defaults to the last substep of the load step (except in a + buckling or modal analysis). For a buckling ( :ref:`antype`,BUCKLE) or modal ( :ref:`antype` + ,MODAL) analysis, ``Sbstep`` corresponds to the mode number. Specify ``Sbstep`` = LAST to store + the last substep for the specified load step (that is, issue a :ref:`set`, ``Lstep``,LAST + command). + + If ``Lstep`` = LIST, ``Sbstep`` = 0 or 1 lists the basic step information. ``Sbstep`` = 2 also + lists the basic step information, but includes the load step title, and labels imaginary data + sets if they exist. + + fact : str + Scale factor applied to data read from the file. If zero (or blank), a value of 1.0 is used. A + nonzero factor excludes non-summable items. + + Harmonic velocities or accelerations can be calculated from the displacement results from a + modal ( :ref:`antype`,MODAL) or harmonic ( :ref:`antype`,HARMIC) analysis. If ``Fact`` = VELO, + the harmonic velocities (v) are calculated from the displacements (d) at a particular frequency + (f) according to the relationship v = 2 πfd. Similarly, if ``Fact`` = ACEL, the harmonic + accelerations (a) are calculated as a = (2 πf) :sup:`2` d. + + If ``Lstep`` = LIST in an analysis using rezoning, ``Fact`` across all rezoning data sets is + listed. + + kimg : str + Used only with complex results (harmonic and complex modal analyses). + + * ``0 or REAL`` - Store the real part of complex solution (default). + + * ``1, 2 or IMAG`` - Store the imaginary part of a complex solution. + + * ``3 or AMPL`` - Store the amplitude + + * ``4 or PHAS`` - Store the phase angle. The angle value, expressed in degrees, will be between + -180° and +180°. + + time : str + Time-point identifying the data set to be read. For a harmonic analyses, time corresponds to the + frequency. + + For a buckling analysis, time corresponds to the load factor. + + Used only in the following cases: If ``Lstep`` = NEAR, read the data set nearest to ``TIME``. If + both ``Lstep`` and ``Sbstep`` are zero (or blank), read data set at time = ``TIME``. + + Do not use ``TIME`` to identify the data set to be read if you used the arc-length method ( + :ref:`arclen` ) in your solution. + + If ``TIME`` is between two solution time points in the results file, a linear interpolation + occurs between the two data sets (except in cases where `rezoning + `_ or + selected results output ( :ref:`osresult` ) is used). + + Solution items not written to the results file ( :ref:`outres` ) for either data set will result + in a null item after data set interpolation. + + If ``TIME`` is beyond the last time point on the file, the last time point will be used. + + If ``TIME`` is between two solution time points and both ``Lstep`` and ``Sbstep`` are zero (or + blank), no interpolation is performed for the :ref:`prcint` / :ref:`plcint` commands. (That is, + for results generated by the :ref:`cint` command, only the data set associated with the lower of + the solution time points is used.) + + angle : str + For harmonic elements ( ``PLANE25``, ``PLANE75``, ``PLANE78``, ``PLANE83``, and ``SHELL61`` ), + ``ANGLE`` specifies the circumferential location (0.0 to 360°) used when reading from the + results file. The harmonic factor (based on the circumferential angle) is applied to the + displacements and element results, and to the applied constraints and loads which overwrites any + values existing in the database. If ``ANGLE`` = NONE, all harmonic factors are set to 1 and + postprocessing yields the solution output. + + When using ``ANGLE`` = NONE with ``MODE`` > 0, the combined stresses and strains are not valid. + + The default value of ``ANGLE`` is 0.0; however if the :ref:`set` command is not used, the + effective default is NONE. + + For full harmonic analyses with the amplitude option ( ``KIMG`` = 3 or AMPL), ``ANGLE`` is the + prescribed phase angle at which the amplitude is computed. + + nset : str + Data set number of the data set to be read. If a positive value for ``NSET`` is entered, + ``Lstep``, ``Sbstep``, ``KIMG``, and ``TIME`` are ignored. Available set numbers can be + determined by :ref:`set`,LIST. + + order : str + Key to sort the harmonic index results. This option applies to `cyclic symmetry `_ buckling and modal analyses only, and is valid only when ``Lstep`` = FIRST, LAST, NEXT, PREVIOUS, NEAR or LIST. + + * ``ORDER`` - Sort the harmonic index results in ascending order of eigenfrequencies or buckling + load multipliers. + + * ``(blank)`` - No sorting takes place. + + Notes + ----- + + .. _SET_notes: + + Defines the data set to be read from the results file into the database. Various operations may also + be performed during the read operation. The database must have the model geometry available (or use + the :ref:`resume` command before the :ref:`set` command to restore the geometry from + :file:`Jobname.DB` ). Values for applied constraints ( :ref:`d` ) and loads ( :ref:`f` ) in the + database will be replaced by their corresponding values on the results file, if available. (See the + description of the :ref:`outres` command.) In a single load step analysis, these values are usually + the same, except for results from harmonic elements. (See the description of the ``ANGLE`` value + above.) + + In an interactive run, the sorted list ( ``ORDER`` option) is also available for results-set reading + via a GUI pick option. + + You can postprocess results without issuing a :ref:`set` command if the solution results were saved + to the database file ( :file:`Jobname.db` ). A distributed-memory parallel simulation, however, can + only postprocess using the results file (for example, :file:`Jobname.rst` ) and cannot use the + :file:`Jobname.db` file since no solution results are written to the database. Therefore, you must + issue a :ref:`set` command or a :ref:`rescombine` command before postprocessing in a distributed- + memory parallel run. + + When postprocessing amplitudes or phases ( ``KIMG`` = AMPL or PHAS): + + * The only appropriate coordinate system is the solution coordinate system ( :ref:`rsys`,SOLU). For + layered elements, a layer ( :ref:`layer` ) must also be specified. When displaying the + displacement amplitudes, use a contour display ( :ref:`plnsol` command). Because a deformed shape + display ( :ref:`pldisp` command) could lead to a non-physical shape, the displacement scaling is + off by default ( :ref:`slashdscale`,,OFF). + + * The conversion is not valid for averaged results, derived results (such as principal + stress/strain, equivalent stress/strain, and USUM), or summed results obtained using :ref:`fsum`, + :ref:`nforce`, :ref:`prnld`, and :ref:`prrfor`. + + * Cyclic symmetry and multistage cyclic symmetry analysis results are not supported. + + * Coupled-field analysis results are supported when ``KIMG`` = AMPL, but they are not supported when + ``KIMG`` = PHAS. + + Issuing :ref:`expand` in a Cyclic Symmetry Modal Analysis + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + After issuing :ref:`expand`, ``Nrepeat`` in a cyclic symmetry modal analysis, subsequent :ref:`set` + commands read data from the results file and expand them to ``Nrepeat`` sectors. + + Issuing :ref:`msopt`,EXPAND in a Multistage Cyclic Symmetry Analysis + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + When issuing :ref:`msopt`,EXPAND in a multistage cyclic symmetry analysis, subsequent :ref:`set` + commands read the data set from the specified results file and expand the nodes and elements to the + stages and sectors specified via :ref:`msopt`,EXPAND. + """ + command = f"SET,{lstep},{sbstep},{fact},{kimg},{time},{angle},{nset},{order}" + return self.run(command, **kwargs) + + def subset( + self, + lstep: str = "", + sbstep: str = "", + fact: str = "", + kimg: int | str = "", + time: str = "", + angle: str = "", + nset: str = "", + **kwargs, + ): + r"""Reads results for the selected portions of the model. + + Mechanical APDL Command: `SUBSET `_ + + Parameters + ---------- + lstep : str + Load step number of the data set to be read (defaults to 1): + + * ``N`` - Read load step ``N``. + + * ``FIRST`` - Read the first data set ( ``SBSTEP`` and ``TIME`` are ignored). + + * ``LAST`` - Read the last data set ( ``SBSTEP`` and ``TIME`` are ignored). + + * ``NEXT`` - Read the next data set ( ``SBSTEP`` and ``TIME`` are ignored). If at the last data set, + the first data set will be read as the next. + + * ``NEAR`` - Read the data set nearest to ``TIME`` ( ``SBSTEP`` is ignored). If ``TIME`` is blank, + read the first data set. + + * ``LIST`` - Scan the results file and list a summary of each load step. ( ``FACT``, ``KIMG``, + ``TIME`` and ``ANGLE`` are ignored.) + + sbstep : str + Substep number (within ``Lstep`` ). For the buckling ( :ref:`antype`,BUCKLE) analysis or the + modal ( :ref:`antype`,MODAL) analysis, the substep corresponds to the mode number. Defaults to + last substep of load step (except for :ref:`antype`,BUCKLE or MODAL). If ``Lstep`` = LIST, + ``SBSTEP`` = 0 or 1 lists the basic step information, whereas ``SBSTEP`` = 2 also lists the load + step title, and labels imaginary data sets if they exist. + + fact : str + Scale factor applied to data read from the file. If zero (or blank), a value of 1.0 is used. + Harmonic velocities or accelerations may be calculated from the displacement results from a + modal ( :ref:`antype`,MODAL) or harmonic ( :ref:`antype`,HARMIC) analyses. If ``FACT`` = VELO, + the harmonic velocities (v) are calculated from the displacements (d) at a particular frequency + (f) according to the relationship v = 2 πfd. Similarly, if ``FACT`` = ACEL, the harmonic + accelerations (a) are calculated as a = (2 πf) :sup:`2` d. + + kimg : int or str + Used only with results from complex analyses: + + * ``0`` - Store real part of complex solution + + * ``1`` - Store imaginary part. + + time : str + Time-point identifying the data set to be read. For harmonic analyses, time corresponds to the + frequency. For the buckling analysis, time corresponds to the load factor. Used only in the + following cases: If ``Lstep`` is NEAR, read the data set nearest to ``TIME``. If both ``Lstep`` + and ``SBSTEP`` are zero (or blank), read data set at time = ``TIME``. If ``TIME`` is between two + solution time points on the results file, a linear interpolation is done between the two data + sets. Solution items not written to the results file ( :ref:`outres` ) for either data set will + result in a null item after data set interpolation. If ``TIME`` is beyond the last time point on + the file, use the last time point. + + angle : str + Circumferential location (0.0 to 360°). Defines the circumferential location for the harmonic + calculations used when reading from the results file. The harmonic factor (based on the + circumferential angle) is applied to the harmonic elements ( ``PLANE25``, ``PLANE75``, + ``PLANE78``, ``PLANE83``, and ``SHELL61`` ) of the load case. See the `Mechanical APDL Theory + Reference `_ + for details. Note that factored values of applied constraints and loads will overwrite any + values existing in the database. + + nset : str + Data set number of the data set to be read. If a positive value for ``NSET`` is entered, + ``Lstep``, ``SBSTEP``, ``KIMG``, and ``TIME`` are ignored. Available set numbers can be + determined by :ref:`set`,LIST. + + Notes + ----- + + .. _SUBSET_notes: + + Reads a data set from the results file into the database for the selected portions of the model + only. Data that has not been specified for retrieval from the results file by the :ref:`inres` + command will be listed as having a zero value. Each time that the :ref:`subset` command is issued, + the data currently in the database will be overwritten with a new set of data. Various operations + may also be performed during the read operation. The database must have the model geometry available + (or used the :ref:`resume` command before the :ref:`subset` command to restore the geometry from + :file:`File.DB` ). + """ + command = f"SUBSET,{lstep},{sbstep},{fact},{kimg},{time},{angle},{nset}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1/special_purpose.py b/src/ansys/mapdl/core/_commands/post1/special_purpose.py new file mode 100644 index 0000000000..fa279bcdf8 --- /dev/null +++ b/src/ansys/mapdl/core/_commands/post1/special_purpose.py @@ -0,0 +1,4250 @@ +# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + + +class SpecialPurpose: + + def bfint( + self, + fname1: str = "", + ext1: str = "", + fname2: str = "", + ext2: str = "", + kpos: int | str = "", + clab: str = "", + kshs: int | str = "", + tolout: str = "", + tolhgt: str = "", + **kwargs, + ): + r"""Activates the body force interpolation operation. + + Mechanical APDL Command: `BFINT `_ + + Parameters + ---------- + fname1 : str + File name and directory path (248 characters maximum, including directory) from which to read + data for interpolation. If you do not specify a directory path, it will default to your working + directory and you can use all 248 characters for the file name. + + The file name defaults to :file:`Jobname`. + + ext1 : str + Filename extension (eight-character maximum). The extension defaults to NODE if ``Fname1`` is + blank. + + fname2 : str + File name and directory path (248 characters maximum, including directory) to which **BF** commands are written. If you do not specify a directory path, it will default to your working + directory and you can use all 248 characters for the file name. + + The file name defaults to :file:`Jobname`. + + ext2 : str + Filename extension (eight-character maximum). The extension defaults to BFIN if ``Fname2`` is + blank. + + kpos : int or str + Position on ``Fname2`` to write block of **BF** commands: + + * ``0`` - Beginning of file (overwrite existing file). + + * ``1`` - End of file (append to existing file). + + clab : str + Label (8 characters maximum, including the colon) for this block of **BF** commands in ``Fname2``. This label is appended to the colon (:). Defaults to BF ``n``, where ``n`` is the cumulative iteration number for the data set currently in the database. + + kshs : int or str + Shell-to-solid submodeling key: + + * ``0`` - Solid-to-solid or shell-to-shell submodel. + + * ``1`` - Shell-to-solid submodel. + + tolout : str + Extrapolation tolerance about elements, based on a fraction of the element dimension. Submodel + nodes outside the element by more than ``TOLOUT`` are not accepted as candidates for DOF + extrapolation. Defaults to 0.5 (50%). + + tolhgt : str + Height tolerance above or below shell elements, in units of length. Used only for shell-to-shell + submodeling ( ``KSHS`` = 0). Submodel nodes off the element surface by more than ``TOLHGT`` are not + accepted as candidates for DOF interpolation or extrapolation. Defaults to 0.0001 times the maximum + element dimension. + + .. warning:: + + Relaxing this tolerance to allow submodel nodes to be found may cause poor submodel results. + + Notes + ----- + + .. _BFINT_notes: + + File ``Fname1`` should contain a node list for which body forces are to be interpolated ( + :ref:`nwrite` ). File ``Fname2`` is created, and contains interpolated body forces written as a + block of nodal :ref:`bf` commands. + + Body forces are interpolated from elements having TEMP as a valid body force or degree of freedom, + and only the label TEMP is written on the nodal :ref:`bf` commands. Interpolation is performed for + all nodes on file ``Fname1`` using the results data currently in the database. For layered elements, + use the :ref:`layer` command to select the locations of the temperatures to be used for + interpolation. Default locations are the bottom of the bottom layer and the top of the top layer. + + The block of :ref:`bf` commands begins with an identifying colon label command and ends with a + ``/EOF`` command. The colon label command has the form : ``Clab``. Interpolation from multiple + results sets can be performed by looping through the results file in a user-defined macro. + Additional blocks can be appended to ``Fname2`` by using ``KPOS`` and unique colon labels. Issue + :ref:`input`, with the appropriate colon label, to read the block of commands. + + If the model has coincident (or very close) nodes, :ref:`bfint` must be applied to each part of the + model separately to ensure that the mapping of the nodes is correct. For example, if nodes belonging + to two adjacent parts linked by springs are coincident, the operation should be performed on each + part of the model separately. + """ + command = f"BFINT,{fname1},{ext1},,{fname2},{ext2},,{kpos},{clab},{kshs},{tolout},{tolhgt}" + return self.run(command, **kwargs) + + def cbdof( + self, + fname1: str = "", + ext1: str = "", + fname2: str = "", + ext2: str = "", + kpos: int | str = "", + clab: str = "", + kshs: int | str = "", + tolout: str = "", + tolhgt: str = "", + tolthk: str = "", + **kwargs, + ): + r"""Activates cut-boundary interpolation (for submodeling). + + Mechanical APDL Command: `CBDOF `_ + + Parameters + ---------- + fname1 : str + File name and directory path (248 characters maximum, including directory) from which to read + boundary node data. If no specified directory path exists, the path defaults to your working + directory and you can use all 248 characters for the file name. + + The file name defaults to :file:`Jobname`. + + ext1 : str + Filename extension (eight-character maximum). The extension defaults to NODE if ``Fname1`` is + blank. + + fname2 : str + File name and directory path (248 characters maximum, including directory) to which cut-boundary **D** commands are written. If no specified directory path exists, the path defaults to your working + directory and you can use all 248 characters for the file name. + + The file name defaults to :file:`Jobname`. + + ext2 : str + Filename extension (eight-character maximum). The extension defaults to CBDO if ``Fname2`` is + blank. + + kpos : int or str + Position on ``Fname2`` to write block of :ref:`d` commands: + + * ``0`` - Beginning of file (overwrite existing file). + + * ``1`` - End of file (append to existing file). + + clab : str + Label (eight characters maximum, including the colon) for this block of :ref:`d` commands on + ``Fname2``. his label is appended to the colon (:). Defaults to CB ``n``, where ``n`` is the + cumulative iteration number for the data set currently in the database. For imaginary data (see + KIMG on the :ref:`starset` command), ``Clab`` defaults to CI ``n``. + + kshs : int or str + Shell-to-solid submodeling key: + + * ``0`` - Solid-to-solid or shell-to-shell submodel. + + * ``1`` - Shell-to-solid submodel. + + tolout : str + Extrapolation tolerance about elements, based on a fraction of the element dimension. Submodel + nodes outside the element by more than ``TOLOUT`` are not accepted as candidates for DOF + extrapolation. Defaults to 0.5 (50 percent). + + tolhgt : str + Height tolerance above or below shell elements, in units of length. Used only for shell-to-shell + submodeling ( ``KSHS`` = 0). Submodel nodes off the element surface by more than ``TOLHGT`` are + not accepted as candidates for degree-of-freedom interpolation or extrapolation. Defaults to + 0.0001 times the maximum element dimension. + + tolthk : str + Height tolerance above or below shell elements, based on a fraction of the shell element + thickness. Used only for shell-to-solid submodeling (KSHS = 1). Submodel nodes off the element + surface by more than ``TOLTHK`` are not accepted as candidates for DOF interpolation or + extrapolation. Defaults to 0.1 times the average shell thickness. + + Notes + ----- + + .. _CBDOF_notes: + + File ``Fname1`` should contain a node list for which boundary conditions are to be interpolated ( + :ref:`nwrite` ). File ``Fname2`` is created to contain interpolated boundary conditions written as a + block of :ref:`d` commands. + + Boundary conditions are written for the active degree-of-freedom set for the element from which + interpolation is performed. Interpolation occurs on the selected set of elements. The block of + :ref:`d` commands begins with an identifying colon label and ends with a ``/EOF`` command. The colon + label is of the form : ``Clab`` (described above). + + Interpolation from multiple results sets can be performed by looping through the results file in a + user-defined macro. Additional blocks can be appended to ``Fname2`` by using ``KPOS`` and unique + colon labels. To read the block of commands, issue the :ref:`input` command with the appropriate + colon label. + + If the model has coincident (or very close) nodes, the :ref:`cbdof` must be applied to each part of + the model separately to ensure that the mapping of the nodes is correct. For example, if nodes + belonging to two adjacent parts linked by springs are coincident, the operation should be performed + on each part of the model separately. + + Resume the coarse model database at the beginning of the cut-boundary procedure. The database should + have been saved after the first coarse model solution, as the number of nodes in the database and + the results file must match, and internal nodes are sometimes created during the solution. + + This command cannot be used to interpolate the magnetic edge-flux (AZ) degree of freedom. + + .. warning:: + + Relaxing the TOLHGTor TOLTHKtolerances to allow submodel nodes to be “found” can produce poor + submodel results. + """ + command = f"CBDOF,{fname1},{ext1},,{fname2},{ext2},,{kpos},{clab},{kshs},{tolout},{tolhgt},{tolthk}" + return self.run(command, **kwargs) + + def cmsfile( + self, + option: str = "", + fname: str = "", + ext: str = "", + cmskey: str = "", + **kwargs, + ): + r"""Specifies a list of component mode synthesis (CMS) results files for plotting results on the + assembly. + + Mechanical APDL Command: `CMSFILE `_ + + **Command default:** + + .. _CMSFILE_default: + + If issued with no arguments, the :ref:`cmsfile` command uses these defaults: + + :ref:`cmsfile`,ADD, ``Jobname``,rst,ON + + The command adds the component results file :file:`Jobnamerst`. + + Parameters + ---------- + option : str + Specifies the command operation: + + * ``ADD`` - Add the specified component results file ( ``Fname`` ) to the list of files to plot. + This option is the default. + + * ``DELETE`` - Remove the specified component results file ( ``Fname`` ) from the list of files to + plot. + + * ``LIST`` - List all specified component results files. + + * ``CLEAR`` - Clear all previous files added. + + * ``ALL`` - Add all component results ( :file:`.rst` ) files from the working directory to the list + of files to plot. + + fname : str + The file name (with full directory path) of the component results file. The default file name is + the :file:`Jobname` (specified via the :ref:`filname` command). + + ext : str + The file name ( ``Fname`` ) extension. The default extension is :file:`rst`. + + cmskey : str + Valid only when adding a results file ( ``Option`` = ADD or ALL), this key specifies whether or not to check the specified :file:`.rst` file to determine if it was created via a CMS expansion pass: + + * ``ON`` - Check (default). + + * ``OFF`` - Do not check. + + Notes + ----- + + .. _CMSFILE_notes: + + The :ref:`cmsfile` command specifies the list of component mode synthesis (CMS) results files to + include when plotting the mode shape of an assembly. + + During postprocessing ( :ref:`post1` ) of a CMS analysis, issue the :ref:`cmsfile` command to point + to component results files of interest. (You can issue the command as often as needed to include all + or some of the component results files.) Issue the :ref:`set` command to acquire the frequencies and + mode shapes from substeps for all specified results files. Execute a plot ( :ref:`plnsol` ) or print + ( :ref:`prnsol` ) operation to display the mode shape of the entire assembly. + + When you specify a results file to add to the plot list, the default behavior of the command ( + ``CmsKey`` = ON) is to first verify that the file is from a CMS analysis and that the frequencies of + the result sets on the file match the frequencies on the first file in the list. If ``CmsKey`` = + OFF, you can add any :file:`.rst` file to the list of files to plot, even if the file was not + expanded via a CMS expansion pass. + + If ``CmsKey`` = ON (default), output from the command appears as: ``ADD CMS FILE =`` filename.rst + ``CmsKey`` = OFF, output from the command appears as: ``ADD FILE =`` filename.rst + + If ``Option`` = DELETE or CLEAR, you must clear the database ( ``/CLEAR`` ), then re-enter the + postprocessor ( :ref:`post1` ) and issue a :ref:`set` command for the change to take effect on + subsequent plots. + + Clearing the database does not clear the list of files specified via the :ref:`cmsfile` command. + Specify ``Option`` = CLEAR to clear the list of files. + """ + command = f"CMSFILE,{option},{fname},{ext},{cmskey}" + return self.run(command, **kwargs) + + def cyccalc( + self, fileprefix: str = "", fileformat: str = "", separator: str = "", **kwargs + ): + r"""Calculates results from a cyclic harmonic mode-superposition analysis using the specifications + defined by :ref:`cycspec`. + + Mechanical APDL Command: `CYCCALC `_ + + **Command default:** + + .. _CYCCALC_default: + + Write the result tables to the output file. + + Parameters + ---------- + fileprefix : str + Each result table (corresponding to each :ref:`cycspec` specification) is written to a file + beginning with ``FilePrefix``. If blank (default), the result tables are written to the output + file. + + fileformat : str + If ``FilePrefix`` is specified, then use ``FileFormat`` to specify the format of the file to be + written: + + * ``FORM`` - Formatted file (default) + + * ``CSV`` - Comma-separated value file + + separator : str + If ``FileFormat`` is CSV, use ``Separator`` to specify the field separator: + + * ``COMMA`` - Use a comma () as the field separator (default) + + * ``COLON`` - Use a colon (:) as the field separator + + * ``DOT`` - Use a period (.) as the field separator + + Notes + ----- + + .. _CYCCALC_notes: + + :ref:`cyccalc` loops through the specification given by :ref:`cycspec` and computes the requested + outputs. The outputs are given in a table format, with the rows corresponding to each frequency + solution from the harmonic analysis, and the columns corresponding to each sector. The table entries + are the maximum value of the specified quantity at the specified location in the sector. In + addition, columns containing the maximum value at the frequency, the sector in which it occurs, and + the node in the sector at which it occurs are output. + + If ``FilePrefix`` is specified, a file is created for each output table with the name + :file:`FilePrefix_node_type.ext`, where ``node`` is the node number or component name, ``type`` is + the item/component requested, and the file extension ``.ext`` is either :file:`.txt` or + :file:`.csv`, depending on ``FileFormat``. + + A :ref:`set` command must precede the :ref:`cyccalc` command. + + The :ref:`cyccalc` results are based on the currently active :ref:`rsys`, :ref:`shell`, + :ref:`layer`, and :ref:`avprin` settings. + + The :ref:`cyccalc` command only supports matched nodes. For more details on matching cyclic edge + node pairs see `Edge Component Pairs + `_ + """ + command = f"CYCCALC,{fileprefix},{fileformat},{separator}" + return self.run(command, **kwargs) + + def cycfiles( + self, + fnamerst: str = "", + extrst: str = "", + fnamerfrq: str = "", + extrfrq: str = "", + **kwargs, + ): + r"""Specifies the data files where results are to be found for a cyclic symmetry mode-superposition + harmonic analysis. + + Mechanical APDL Command: `CYCFILES `_ + + **Command default:** + + .. _CYCFILES_default: + + No defaults are available for the :ref:`cycfiles` command. You must issue this command to properly + postprocess the results of a cyclic symmetry mode-superposition harmonic analysis. If issued with no + arguments, the postprocessing will be done using :file:`Jobname.rst` and :file:`Jobname.rfrq` from + the current working directory. + + Parameters + ---------- + fnamerst : str + The file name and directory path of the results file from the cyclic modal solution. Defaults to + :file:`Jobname`. + + extrst : str + File name extension for ``FnameRst``. Defaults to :file:`rst`. + + fnamerfrq : str + The file name and directory path of the results file from the cyclic mode-superposition harmonic + solution. Defaults to the value of the ``FnameRst`` argument. + + extrfrq : str + File name extension for ``FnameRfrq``. Defaults to :file:`rfrq`. + """ + command = f"CYCFILES,{fnamerst},{extrst},{fnamerfrq},{extrfrq}" + return self.run(command, **kwargs) + + def cycphase(self, type_: str = "", option: str = "", **kwargs): + r"""Provides tools for determining minimum and maximum possible result values from frequency couplets + produced in a modal cyclic symmetry analysis. + + Mechanical APDL Command: `CYCPHASE `_ + + **Command default:** + + .. _CYCPHASE_default: + + No defaults are available for the :ref:`cycphase` command. You must specify an argument ( ``TYPE`` ) + when issuing the command. Other values which may be necessary ( ``OPTION`` ) depend upon which + ``TYPE`` argument you specify. + + Parameters + ---------- + type_ : str + The type of operation requested: + + * ``DISP`` - Calculate the maximum and minimum possible displacement at each node in the original + sector model. Store the values and the phase angle at which they occurred. + + * ``STRESS`` - Calculate the maximum and minimum possible stresses at each node in the original + sector model. Store the values and the phase angle at which they occurred. + + * ``STRAIN`` - Calculate the maximum and minimum possible strains at each node in the original + sector model. Store the values and the phase angle at which they occurred. + + * ``ALL`` - Calculate the maximum and minimum possible displacement, stress and strain at each node + in the original sector model. Store the values and the phase angle at which they occurred. + + * ``GET`` - Places the value of a MAX or MIN item into the _CYCVALUE parameter, the node for that + value in the _CYCNODE parameter, and the phase angle for the value in the _CYCPHASE parameter. + + * ``PUT`` - Put resulting sweep values for printing (via the :ref:`prnsol` command ) or plotting + (via the :ref:`plnsol` command). + + * ``LIST`` - List the current minimum/maximum displacement, stress and strain nodal values. + + * ``STAT`` - Summarize the results of the last phase sweep. + + * ``CLEAR`` - Clear phase-sweep information from the database. + + option : str + If TYPE = DISP, STRAIN, STRESS or ALL, controls the sweep angle increment to use in the search: + + * ``Angle`` - The sweep angle increment in degrees, greater than 0.1 and less than 10. The default + is 1. + + If TYPE = PUT, controls which values are placed onto the model: + + * ``MAX`` - Put all existing nodal maximum values onto the model. This option is the default. + + * ``MIN`` - Put all existing nodal minimum values onto the model. + + If TYPE = GET, controls the values placed into cyclic parameters: + + * ``Item`` - Specifies the type of values on which to operate: + + * U -- Displacement + * S -- Stress + * EPEL -- Strain + * ``Comp`` - Specifies the specific component of displacement, stress or strain for which to get information: + + * X,Y,Z -- Basic components + * XY,YZ,XZ -- Shear components + * 1,2,3 -- Principal values + * EQV -- Equivalent value + * SUM -- USUM + * ``MxMn`` - Specifies whether the requested value information is for the maximum or minimum value: + + * MAX -- Maximum value. + * MIN -- Minimum value. + + Notes + ----- + + .. _CYCPHASE_notes: + + When you `expand the results of a modal cyclic symmetry analysis + `_ + (via the :ref:`cycexpand` or :ref:`expand` command), the program combines the real and imaginary + results for a given nodal diameter, assuming no phase shift between them; however, the modal + response can occur at any phase shift. + + :ref:`cycphase` response results are valid only for the first cyclic sector. To obtain the response + at any part of the expanded model, Ansys, Inc. recommends using `cyclic symmetry results + expansion + `_ + at the phase angle obtained via :ref:`cycphase`. + + The phase angles returned by :ref:`cycphase` contain the minimum and maximum values for USUM, SEQV + and other scalar principal stress and strain quantities; however, they do not always return the true + minimum and maximum values for directional quantities like UX or SX unless the values fall in the + first sector. + + :ref:`cycphase` does not consider midside node values when evaluating maximum and minimum values, + which may affect display quantities but no others. (Typically, the program ignores midside node + stresses and strains during postprocessing.) + + Issuing :ref:`cycphase`,PUT clears the result values for midside nodes on high order elements; + therefore, this option sets element faceting ( :ref:`efacet` ) to 1. The command reports that + midside nodal values are set to zero and indicates that element faceting is set to 1. + + If the sweep values are available after issuing a :ref:`cycphase`,PUT command, the :ref:`prnsol` or + :ref:`plnsol` command will print or plot (respectively) the sweep values of structure displacement + Ux, Uy, Uz, component stress/strain X, Y, Z, XY, YZ, ZX, principal stress/strain 1, 2, 3 and + equivalent stress/strain EQV. The vector sum of displacement (USUM) and stress/strain intensity + (SINT) are not valid phase-sweep results. + + You can specify any coordinate system via the :ref:`rsys` command for displaying or printing + :ref:`cycphase` results. However, after :ref:`cycphase` results have been extracted, you cannot then + transform them via the :ref:`rsys` command. If you try to do so, the program issues a warning + message. + + The :ref:`cycphase` command is valid in :ref:`post1` and for cyclically symmetric models only. + + To learn more about analyzing a cyclically symmetric structure, see the `Cyclic Symmetry Analysis + Guide `_. + """ + command = f"CYCPHASE,{type_},{option}" + return self.run(command, **kwargs) + + def cycspec( + self, label: str = "", node: str = "", item: str = "", comp: str = "", **kwargs + ): + r"""Defines the set of result items for a subsequent :ref:`cyccalc` command in postprocessing a cyclic + harmonic mode-superposition analysis. + + Mechanical APDL Command: `CYCSPEC `_ + + **Command default:** + + .. _CYCSPEC_default: + + No defaults are available for the :ref:`cycspec` command. You must issue this command to define the + set of result items for evaluation in a subsequent :ref:`cyccalc` command used in computing results + of a cyclic harmonic mode-superposition analysis. + + Parameters + ---------- + label : str + One of the following labels: + + * ``ADD`` - Adds a new specification to the set (default). The maximum number of specifications that + can be defined is 50. + + * ``LIST`` - Lists the current set of specifications. ``Node``, ``Item``, ``Comp`` are ignored. + + * ``ERASE`` - Erases the current set of specifications. ``Node``, ``Item``, ``Comp`` are ignored. + + * ``DELETE`` - Deletes an existing specification. ``Item``, ``Comp`` are ignored. + + node : str + The node at which to evaluate the results. If ``Node`` is a nodal component, then all nodes in + the component are included. All sectors containing this node (or set of nodes) are evaluated. + + For ``LABEL`` = DELETE, use ``Node`` to indicate which specification in the set to delete. + + item : str + Specifies the type of values to evaluate: + + * ``U`` - Displacement + + * ``S`` - Stress + + * ``EPEL`` - Elastic strain + + comp : str + Specifies the specific component of displacement, stress, or strain to evaluate: + + * ``X,Y,Z`` - Direct components + + * ``XY,YZ,XZ`` - Shear components (stress and strain only) + + * ``1,2,3`` - Principal values (stress and strain only) + + * ``EQV`` - Equivalent value (stress and strain only) + + * ``SUM`` - Vector sum (displacement only) + + * ``NORM`` - L2 norm for the set of nodes (displacement only) + + Notes + ----- + + .. _CYCSPEC_notes: + + Up to 50 specifications can be defined for use in a subsequent :ref:`cyccalc` command. If more than + 50 specifications are desired, erase the table after the :ref:`cyccalc` operation and add new + specifications and repeat the :ref:`cyccalc` command. All the specified nodes, items, and components + are evaluated for all sectors and the maximum amplitude value output. For combined stresses and + strains ( ``Comp`` = 1,2,3 or EQV) or displacement vector sum ( ``Comp`` = SUM), a 360 degree phase + sweep is performed at each location to determine the maximum. + + Additional POST1 controls are used to refine the specification. For component values, components are + in the :ref:`rsys` direction. For shell elements, the results are at the :ref:`shell` location. For + EPEL,EQV, the results are based on the ``EFFNU`` value on the :ref:`avprin` command. The controls + active when the :ref:`cyccalc` command is issued determine the result values. If results at another + :ref:`shell` location are desired, issue the new :ref:`shell` command and then re-issue the + :ref:`cyccalc` command. + + If a single node is input, the ``Item`` / ``Comp`` value at that location in each sector is output. + If a node component is given, then the maximum ``Item`` / ``Comp`` value within the set of nodes of + each sector is output, one value for each sector (the node of the maximum may vary from sector to + sector). For stress and strain items, only corner nodes are valid. + + For the displacement norm option ( ``Item`` = U, ``Comp`` = NORM), the L2 norm computed from all the + nodes in the component is output, one per sector. + """ + command = f"CYCSPEC,{label},{node},{item},{comp}" + return self.run(command, **kwargs) + + def exoption(self, ldtype: str = "", option: str = "", value: str = "", **kwargs): + r"""Specifies the :ref:`exprofile` options for the Mechanical APDL to Ansys CFX profile file transfer. + + Mechanical APDL Command: `EXOPTION `_ + + Parameters + ---------- + ldtype : str + Load type: + + * ``SURF`` - Surface load + + * ``VOLU`` - Volume load + + option : str + Surface options: + + * ``Precision`` - Number of significant digits for the fractional part of real data + + * ``Connectivity`` - Key to include face connectivity in the exported profile file + + Volume options: + + * ``Precision`` - Number of significant digits after the decimal for real data + + value : str + Specify the value for either Precision or Connectivity. + + For Precision, specify the number of significant digits. Can be any value between 1 to 20, default + 8. When 0 or an invalid value is specified, the program will use the default value of 8 and issue a + warning message. + + For Connectivity, specify the key to include the element face connectivity data for surface loads + (does not support volume loads): + + * ``OFF`` - Do not include the connectivity data in the exported file (default) + + * ``ON`` - Include the connectivity data in the exported file + """ + command = f"EXOPTION,{ldtype},{option},{value}" + return self.run(command, **kwargs) + + def expand( + self, + nrepeat: str = "", + modal: str = "", + hindex: str = "", + icsys: str = "", + sctang: str = "", + phase: str = "", + **kwargs, + ): + r"""Displays the results of a modal cyclic symmetry analysis. + + Mechanical APDL Command: `EXPAND `_ + + Parameters + ---------- + nrepeat : str + Number of sector repetitions for expansion. The default is 0 (no expansion). + + modal : str + Specifies that the expansion is for a modal cyclic symmetry analysis. + + hindex : str + The harmonic index ID for the results to expand. + + icsys : str + The coordinate system number used in the modal cyclic symmetry solution. The default is the + global cylindrical coordinate system (specified via the :ref:`csys` command where ``KCN`` = 1). + + sctang : str + The sector angle in degrees, equal to 360 divided by the number of cyclic sectors. + + phase : str + The phase angle in degrees to use for the expansion. The default is 0. Typically, the value is + the peak displacement (or stress/strain) phase angle obtained via the :ref:`cycphase` command. + + Notes + ----- + + .. _EXPAND_notes: + + Issue this command to display the results of a modal cyclic symmetry analysis. + + When you issue the :ref:`expand`, ``Nrepeat`` command, subsequent :ref:`set` commands read data from + the results file and expand them to ``Nrepeat`` sectors. As long as no entities have been modified, + this expansion can be negated (that is, reverted to single sector) by issuing :ref:`expand` with no + arguments. If you modify entities and wish to return to the partial model, use the Session Editor + (see Restoring Database Contents in the `Operations Guide + `_). + + :ref:`expand` displays the results and allows you to print them, as if for a full model. The + harmonic index (automatically retrieved from the results file) appears in the legend column. + + When plotting or printing element strain energy (SENE), the :ref:`expand` command works with brick + or tet models only. Element kinetic energy (KENE) plotting or printing is not supported. + + :ref:`expand` is a specification command valid only in POST1. It is significantly different from the + :ref:`cycexpand` command in several respects, (although you can use either command to display the + results of a modal cyclic symmetry analysis): + + * :ref:`expand` has none of the limitations of the :ref:`cycexpand` command. + + * :ref:`expand` changes the database by modifying the geometry, the nodal displacements, and element + stresses as they are read from the results file, whereas the :ref:`cycexpand` command does not + change the database. + + .. warning:: + + The EXPAND command creates new nodes and elements; therefore, saving (or issuing the /EXIT, ALL + command) after issuing the EXPAND command can result in large databases. + """ + command = f"EXPAND,{nrepeat},{modal},{hindex},{icsys},{sctang},,{phase}" + return self.run(command, **kwargs) + + def exprofile( + self, + ldtype: str = "", + load: str = "", + value: str = "", + pname: str = "", + fname: str = "", + fext: str = "", + fdir: str = "", + **kwargs, + ): + r"""Exports Mechanical APDL interface data on selected nodes to an Ansys CFX Profile file. + + Mechanical APDL Command: `EXPROFILE `_ + + Parameters + ---------- + ldtype : str + Load type: + + * ``SURF`` - Surface load. + + * ``VOLU`` - Volumetric load. + + load : str + Surface loads: + + * ``DISP`` - Displacement (in a static analysis) or mode shape and global parameters (in a modal + analysis). + + * ``MODE`` - Normalized mode shape and global parameters (in a modal analysis only). + + * ``TEMP`` - Temperature. + + * ``HFLU`` - Heat flux. + + Volumetric loads: + + * ``DISP`` - Displacement. + + * ``FORC`` - Force. + + * ``HGEN`` - Heat generation. + + value : str + If a positive integer, specifies the number of the surface or volume interface. If zero + (default), the selected nodes or Named Selection are used. + + pname : str + Field name in CFX Profile file (32-character maximum). Defaults to :file:`jobname_bcploadnumber` + for a surface load and :file:`jobname_subdloadnumber` for volumetric load. + + fname : str + The CFX Profile filename (248-character maximum). Defaults to :file:`jobname_bcploadnumber` for + a surface load and :file:`jobname_subdloadnumber` for a volumetric load. + + fext : str + The Profile file extension (8-character maximum). Defaults to :file:`csv`. + + fdir : str + The Profile file directory (248-character maximum). Defaults to current directory. + + Notes + ----- + By default, the :ref:`exprofile` command assumes the data it writes to the Profile file are in SI + units. For models not described in SI units, issue the :ref:`exunit` command as needed to write the + correct unit labels on the Profile file. + + For a modal analysis, if ``Load`` = DISP or MODE, global parameters including mass, frequency, and + maximum displacement are also written to the Ansys CFX Profile file. You should therefore issue the + :ref:`exunit` command for DISP, TIME, and MASS. + + Verify that the coordinate system is set to the global Cartesian ( :ref:`rsys`,0) before using this + command. + + To transfer multiple loads across an interface, specify a unique file name and extension for each + load. + + Force (FORC) and heat generation (HGEN) are per-unit volume. + + For modal analysis, this command will write global parameters including mass, frequency, and maximum + displacement to the profile file. If using cyclic symmetry analysis, this command will also write + harmonic indices to the profile file. + + For modal analysis, this command does not support the following mode-extraction methods ( + :ref:`modopt` ): unsymmetric matrix (UNSYM), the damped system (DAMP), or the QR-damped system + (QRDAMP). + + To write the normalized (instead of non-normalized) mode shapes from a modal analysis to the file: + + * Use ``Load`` = MODE. + + * Verify that the mode shapes are normalized to the mass matrix ( :ref:`modopt`,,,,,,OFF), the + default behavior. + + * Verify that the scale factor is set to 1.0 ( :ref:`set`,,,1.0), the default value. + + The nodes and underlying elements must be selected in order to be exported. See for details. + + For loads not specified directly via commands (such as :ref:`sf` and :ref:`bf` ), loads must first + be read into the database ( :ref:`set` or :ref:`lcase` ). + """ + command = f"EXPROFILE,{ldtype},{load},{value},{pname},{fname},{fext},{fdir}" + return self.run(command, **kwargs) + + def exunit( + self, + ldtype: str = "", + load: str = "", + untype: str = "", + name: str = "", + **kwargs, + ): + r"""Specifies the interface data unit labels to be written to the profile file from Mechanical APDL to + Ansys CFX transfer. + + Mechanical APDL Command: `EXUNIT `_ + + Parameters + ---------- + ldtype : str + Load type: + + * ``SURF`` - Surface load. + + * ``VOLU`` - Volumetric load. + + load : str + Surface loads: + + * ``DISP`` - Displacement in a static analysis. Mode shape in a modal analysis. + + * ``TIME`` - Time. The unit for frequency is the inverse of the unit for time. + + * ``MASS`` - Mass. + + * ``TEMP`` - Temperature. + + * ``HFLU`` - Heat flux. + + Volumetric loads: + + * ``DISP`` - Displacement. + + * ``FORC`` - Force + + * ``HGEN`` - Heat generation + + untype : str + Unit type: + + * ``COMM`` - Predefined unit + + * ``USER`` - User-specified unit + + name : str + Commonly used predefined unit name or user-specified unit name. + + * ``SI`` - International System of units (meter-kilogram-second) (default) + + * ``FT`` - English System of units (feet-pound-second) + + In the SI system, surface loads are in units of m for DISP, degrees K for TEMP, and W/m :sup:`2` for + HFLU; volumetric loads are in units of m for DISP, N/m :sup:`3` for FORC, and W/m :sup:`3` for HGEN. + + In the English system, surface loads are in units of ft for DISP, degrees F for TEMP, and BTU/sec-ft + :sup:`2` for HFLU; volumetric loads are in units of ft for DISP, pdl/ft :sup:`3` for FORC, and + BTU/sec-ft :sup:`3` for HGEN. A pdl is a poundal, and 32.174 pdl = 1 lbf. + + Notes + ----- + This command only specifies which unit labels are to be written to the file when the + :ref:`exprofile` is issued. It does not perform unit conversions. + """ + command = f"EXUNIT,{ldtype},{load},{untype},{name}" + return self.run(command, **kwargs) + + def fssparm(self, port1: str = "", port2: str = "", **kwargs): + r"""Calculates reflection and transmission properties of a frequency selective surface. + + Mechanical APDL Command: `FSSPARM `_ + + Parameters + ---------- + port1 : str + Port number of input port. Defaults to 1. + + port2 : str + Port number of output port. Defaults to 1. + + Notes + ----- + :ref:`fssparm` calculates reflection and transmission coefficients, power reflection and + transmission coefficients, and return and insertion losses of a frequency selective surface. + """ + command = f"FSSPARM,{port1},{port2}" + return self.run(command, **kwargs) + + def fsum(self, lab: str = "", item: str = "", **kwargs): + r"""Sums the nodal force and moment contributions of elements. + + Mechanical APDL Command: `FSUM `_ + + Parameters + ---------- + lab : str + Coordinate system in which to perform summation. + + * ``(blank)`` - Sum all nodal forces in global Cartesian coordinate system (default). + + * ``RSYS`` - Sum all nodal forces in the currently active RSYS coordinate system. + + item : str + Selected set of nodes. + + * ``(blank)`` - Sum all nodal forces for all selected nodes (default), excluding contact elements. + + * ``CONT`` - Sum all nodal forces for contact nodes only. + + * ``BOTH`` - Sum all nodal forces for all selected nodes, including contact elements. + + Notes + ----- + + .. _FSUM_notes: + + Sums and prints, in each component direction for the total selected node set, the nodal force and + moment contributions of the selected elements attached to the node set. Selecting a subset of nodes + ( :ref:`nsel` ) and then issuing this command will give the total force acting on that set of nodes + (default), excluding surface-to-surface, node-to-surface, line-to-line, and line-to-surface contact + elements ( ``TARGE169``, ``TARGE170``, ``CONTA172``, ``CONTA174``, ``CONTA175``, and ``CONTA177`` ). + + Setting ``ITEM`` = CONT sums the nodal forces and moment contributions of the selected contact + elements ( ``CONTA172``, ``CONTA174``, ``CONTA175``, and ``CONTA177`` ). Setting ``ITEM`` = BOTH + sums the nodal forces for all selected nodes, including contact elements. + + Nodal forces associated with surface loads are not included. The effects of nodal coupling and + constraint equations are ignored. Moment summations are about the global origin unless another point + is specified with the :ref:`spoint` command. This vector sum is printed in the global Cartesian + system unless it is transformed ( :ref:`rsys` ) and a point is specified with the :ref:`spoint` + command. By default, the sum is done in global Cartesian, and the resulting vector is transformed to + the requested system. + + The ``LAB`` = RSYS option transforms each of the nodal forces into the active coordinate system + before summing and printing. The :ref:`force` command can be used to specify which component + (static, damping, inertia, or total) of the nodal load is to be used. This command output is + included in the :ref:`nforce` command. + + The command should not be used with axisymmetric elements because it might calculate a moment where + none exists. Consider, for example, the axial load on a pipe modeled with an axisymmetric shell + element. The reaction force on the end of the pipe is the total force (for the full 360 degrees) at + that location. The net moment about the centerline of the pipe would be zero, but the program would + incorrectly calculate a moment at the end of the element as the force multiplied by the radius. + + The command is not valid for elements that operate solely within the nodal coordinate system with 1D + option activated and rotated nodes ( :ref:`nrotat` ). + + **Using FSUM with the NLGEOM Command** + If you have activated large deflection ( :ref:`nlgeom`, ON ), the :ref:`fsum` command generates the + following message: + + Summations based on final geometry and will not agree with solution reactions. + + The message warns that the moment summations may not equal the real moment reactions. When + calculating moment summations, the :ref:`fsum` command assumes that the summation of rotations + applies; however, it does not apply for large rotations, which require pseudovector representation + to sum the rotations. + + In contrast, the results for force reactions will be correct because they depend upon linear + displacement vectors (which can be added). + + **Using FSUM in a Spectrum or PSD Analysis ( ANTYPE, SPECTR)** + When using :ref:`fsum` in a spectrum analysis (after the combination file has been input through + :ref:`input`,,MCOM and when :ref:`spopt` has not been issued with ``Elcalc`` = YES during the + spectrum analysis), or in a PSD analysis when postprocessing 1-sigma results (loadstep 3, 4, or 5), + the following message will display in the printout header: + + (Spectrum analysis summation is used) + + This message means that the summation of the element nodal forces is performed prior to the + combination of those forces. In this case, :ref:`rsys` does not apply. The forces are in the nodal + coordinate systems, and the vector sum is always printed in the global coordinate system. + + The spectrum analysis summation is available when the element results are written to the mode file, + :file:`Jobname.mode` ( ``MSUPkey`` = Yes on the :ref:`mxpand` command). + + Because modal displacements cannot be used to calculate contact element nodal forces, ``ITEM`` does + not apply to spectrum and PSD analyses. + """ + command = f"FSUM,{lab},{item}" + return self.run(command, **kwargs) + + def hfang( + self, + lab: str = "", + phi1: str = "", + phi2: str = "", + theta1: str = "", + theta2: str = "", + **kwargs, + ): + r"""Defines or displays spatial angles of a spherical radiation surface for sound radiation parameter + calculations. + + Mechanical APDL Command: `HFANG `_ + + Parameters + ---------- + lab : str + Spatial angle label. + + * ``ANGLE`` - Define spatial angles (default). + + * ``STATE`` - Display spatial angles. ``PHI1``, ``PHI2``, ``THETA1``, and ``THETA2`` are ignored. + + phi1 : str + Starting and ending ϕ angles (degrees) in the spherical coordinate system. ``PHI1`` defaults to + 0 and ``PHI2`` defaults to 360. + + phi2 : str + Starting and ending ϕ angles (degrees) in the spherical coordinate system. ``PHI1`` defaults to + 0 and ``PHI2`` defaults to 360. + + theta1 : str + Starting and ending θ angles (degrees) in the spherical coordinate system. ``THETA1`` defaults + to 0 and ``THETA2`` defaults to 180. + + theta2 : str + Starting and ending θ angles (degrees) in the spherical coordinate system. ``THETA1`` defaults + to 0 and ``THETA2`` defaults to 180. + + Notes + ----- + + .. _HFANG_notes: + + Defines or displays spatial angles of a spherical radiation surface. + + Use this command only with :ref:`plfar`, ``Lab`` = PRES, or :ref:`prfar`, ``Lab`` = PRES. + """ + command = f"HFANG,{lab},{phi1},{phi2},{theta1},{theta2}" + return self.run(command, **kwargs) + + def hfsym( + self, kcn: str = "", xkey: str = "", ykey: str = "", zkey: str = "", **kwargs + ): + r"""Indicates the presence of symmetry planes for the computation of acoustic fields in the near and far + field domains (beyond the finite element region). + + Mechanical APDL Command: `HFSYM `_ + + Parameters + ---------- + kcn : str + Coordinate system reference number. ``KCN`` may be 0 (Cartesian), or any previously defined + local Cartesian coordinate system number (>10). Defaults to 0. + + xkey : str + Key for acoustic field boundary condition, as prescribed for the solution, corresponding to the x = + constant plane: + + * ``None`` - No sound soft or sound hard boundary conditions (default). + + * ``SSB`` - Sound soft boundary (pressure = 0). + + * ``SHB`` - Sound hard boundary (normal velocity = 0). + + ykey : str + Key for acoustic field boundary condition, as prescribed for the solution, corresponding to the y = + constant plane: + + * ``None`` - No sound soft or sound hard boundary conditions (default). + + * ``SSB`` - Sound soft boundary (pressure = 0). + + * ``SHB`` - Sound hard boundary (normal velocity = 0). + + zkey : str + Key for acoustic field boundary condition, as prescribed for the solution, corresponding to the z = + constant plane: + + * ``None`` - No sound soft or sound hard boundary conditions (default). + + * ``SSB`` - Sound soft boundary (pressure = 0). + + * ``SHB`` - Sound hard boundary (normal velocity = 0). + + Notes + ----- + + .. _HFSYM_notes: + + :ref:`hfsym` uses the image principle to indicate symmetry planes (x, y, or z = constant plane) for + acoustic field computations outside the modeled domain. A sound hard boundary condition must be + indicated even though it occurs as a natural boundary condition. + + No menu paths are available for acoustic applications. + """ + command = f"HFSYM,{kcn},{xkey},{ykey},{zkey}" + return self.run(command, **kwargs) + + def macopt(self, **kwargs): + r"""Specifies modal assurance criterion (MAC) or frequency response function (FRF) correlation criteria + calculation options for :ref:`rstmac`. + + Mechanical APDL Command: `MACOPT `_ + + **Command default:** + If :ref:`macopt` is not issued prior to :ref:`rstmac`, node matching based on location is used by + default in MAC calculations performed by :ref:`rstmac`. Unless otherwise specified, an absolute + tolerance (ABSTOLN) value of 0.01 is used for the node matching. + + Notes + ----- + + .. _MACOPT_notes: + + The :ref:`rstmac` command calculates the MAC or FRF criteria values based on the options specified + via :ref:`macopt`. The :ref:`macopt` command must be issued before the :ref:`rstmac` command. These + commands enable you to compare nodal solutions from two results files ( :file:`.rst` or + :file:`.rstp` ) or from one results file and one Universal Format file ( :file:`.unv` ). Multiple + :ref:`macopt` commands can be issued to specify which results are compared and how. + + As listed in the table above, model solutions can be compared using three different mehtods: + matching nodes based on location, matching nodes based on node number, or by node mapping and + solution interpolation. + + When node mapping and solution interpolation is performed ( ``Option`` = NODMAP), the following + applies: + + * ``File1`` on :ref:`rstmac` must correspond to a model meshed in solid and/or shell elements. Other + types of elements can be present, but the node mapping is not performed for these elements. + + * You should only compare solutions of models having the same dimension (both models are 2D or both + models are 3D). Comparing models with different dimensions may lead to incorrect results if the + solution at mapped/matched nodes is not representative of the global solution. + + * Interpolation is performed on UX, UY, and UZ degrees of freedom. + + Node pair MAC computation ( ``Option`` = NMAC) is only supported when a matching procedure is used + and a specific substep number is requested for each solution ( ``Sbstep1``, ``Sbstep2`` on + :ref:`rstmac` command). + + Non-structural degrees of freedom in coupled-field analyses are supported for the matching methods ( + ``Option`` = ABSTOLN or NUMMATCH). Multiple :ref:`macopt`, DOF commands can be issued consecutively + to combine different degrees of freedom. + + .. _MACOPT_FRF: + + The FRF option is not compatible with any MAC calculation options (DOF, NMAC and KEYMASS) and can + only be used with node matching procedures. + + **Example Usage** + + .. _MACOPT_example: + + For a detailed discussion on using :ref:`macopt` with examples, see `Comparing Nodal Solutions From + Two Models or From One Model and Experimental Data (RSTMAC) + `_ + """ + command = "MACOPT" + return self.run(command, **kwargs) + + def nforce(self, item: str = "", **kwargs): + r"""Sums the nodal forces and moments of elements attached to nodes. + + Mechanical APDL Command: `NFORCE `_ + + Parameters + ---------- + item : str + Specifies the selected set of nodes for summing forces and moments for contact elements. + + * ``(blank)`` - Sums the nodal forces of elements for all selected nodes and excludes contact + elements (elements 169-177). + + * ``CONT`` - Sums the nodal forces of elements for contact nodes only. + + * ``BOTH`` - Sums the nodal forces of elements for all selected nodes, including contact elements. + + Notes + ----- + + .. _NFORCE_notes: + + Sums and prints, in each component direction for each selected node, the nodal force and moment + contributions of the selected elements attached to the node. If all elements are selected, the sums + are usually zero except where constraints or loads are applied. The nodal forces and moments may be + displayed ( :ref:`pbc`,FORC and :ref:`pbc`,MOME). Use :ref:`presol` to print nodal forces and + moments on an element-by-element basis. You can use the :ref:`force` command to specify which + component (static, damping, inertia, or total) of the nodal load is to be used. Nodal forces + associated with surface loads are not included. + + This vector sum is printed in the global Cartesian system. Moment summations are about the global + origin unless another point is specified with the :ref:`spoint` command. The summations for each + node are printed in the global Cartesian system unless transformed ( :ref:`rsys` ). This command is + generally not applicable to axisymmetric models because moment information from the NFORCE command + is not correct for axisymmetric elements. + + Selecting a subset of elements ( :ref:`esel` ) and then issuing this command will give the forces + and moments required to maintain equilibrium of that set of elements. The effects of nodal coupling + and constraint equations are ignored. The option ``ITEM`` = CONT provides the forces and moments for + the contact elements ( ``CONTA172``, ``CONTA174``, ``CONTA175``, and ``CONTA177`` ). Setting + ``ITEM`` = BOTH provides the forces and moments for all selected nodes, including contact elements. + + This command also includes the :ref:`fsum` command function which vectorially sums and prints, in + each component direction for the total selected node set, the nodal force and moment contributions + of the selected elements attached to the selected node set. + + **Using NFORCE in a Spectrum or PSD Analysis ( ANTYPE, SPECTR)** + When using :ref:`nforce` in a spectrum analysis (after the combination file has been input through + :ref:`input`,,MCOM and when :ref:`spopt` has not been issued with ``Elcalc`` = YES during the + spectrum analysis), or in a PSD analysis when postprocessing 1-sigma results (loadstep 3, 4, or 5), + the following message will display in the printout header: + + (Spectrum analysis summation is used) + + This message means that the summation of the element nodal forces is performed prior to the + combination of those forces. In this case, :ref:`rsys` does not apply. The forces are in the nodal + coordinate systems, and the vector sum is always printed in the global coordinate system. + + The spectrum analysis summation is available when the element results are written to the mode file, + :file:`Jobname.MODE` ( ``MSUPkey`` = Yes on the :ref:`mxpand` command). + + Because modal displacements cannot be used to calculate contact element nodal forces, ``ITEM`` does + not apply to spectrum and PSD analyses. + """ + command = f"NFORCE,{item}" + return self.run(command, **kwargs) + + def nldpost( + self, + label: str = "", + key: str = "", + fileid: str = "", + prefix: str = "", + **kwargs, + ): + r"""Gets element component information from nonlinear diagnostic files. + + Mechanical APDL Command: `NLDPOST `_ + + Parameters + ---------- + label : str + Specifies the type of command operation: + + * ``EFLG`` - Element flag for nonlinear diagnostics. + + * ``NRRE`` - Newton-Raphson residuals. + + key : str + Specifies the command action: + + * ``STAT`` - List information about the diagnostic files ( :file:`Jobname.ndxxx` or + :file:`Jobname.nrxxx` ) in the current directory. + + For ``Label`` = EFLG, the listing gives a summary that associates the loadstep, substep, time, + equilibrium iteration number, cumulative iteration number, and the number of elements that fail each + criteria with a specific file ID ( :file:`Jobname.ndxxx` ). Use the list to create element + components (via the CM option) based on the cumulative iteration number. + + For ``Label`` = NRRE, the listing provides a summary that associates the loadstep, substep, time, + equilibrium iteration number, and cumulative iteration number with a specific file ID ( + :file:`Jobname.nrxxx` ). Use the list to identify the respective file ID for creating Newton-Raphson + residual contour plots ( :ref:`plnsol`,NRRE,..., ``FileID`` ). + + * ``DEL`` - Delete :file:`Jobname.ndxxx` or :file:`Jobname.nrxxx` files in the working directory, if + any exist. + + * ``CM`` - Create components for elements that violate criteria. This value is valid only when + ``Label`` = EFLG. + + fileid : str + Valid only when ``Label`` = EFLG and ``Key`` = CM, this value specifies file IDs: + + * ``IDnum`` - The file ID number. Creates the element components from the diagnostic files + corresponding to the specified file ID number in the working directory. + + * ``ALL`` - Creates element components from all available diagnostic files residing in the working + directory. This value is the default if you do not specify an ``IDnum`` value. + + prefix : str + Sets the prefix name for components. Specify up to 21 alphanumeric characters. + + Notes + ----- + + .. _NLDPOST_notes: + + Based on the nonlinear diagnostic results (created via the :ref:`nldiag`,EFLG command), the + :ref:`nldpost` command creates element components with predefined names. + + The following table lists the diagnostic criteria and component names (with specified prefix and + without). Here ``xxx`` corresponds to the file ID ( ``FileID`` ) of :file:`Jobname.ndxxx` or + :file:`Jobnamenrxxx`. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + If you have trouble viewing specific element components, see `Viewing Hidden Element Components + `_ + + For more information, see Performing Nonlinear Diagnostics. + """ + command = f"NLDPOST,{label},{key},{fileid},{prefix}" + return self.run(command, **kwargs) + + def plas( + self, + lab: str = "", + ldstep: str = "", + substep: str = "", + freqb: str = "", + freqe: str = "", + logopt: str = "", + plottype: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + **kwargs, + ): + r"""Plots a specified acoustic quantity during postprocessing of an acoustic analysis. + + Mechanical APDL Command: `PLAS `_ + + Parameters + ---------- + lab : str + The acoustic quantity to calculate: + + * ``SIMP`` - Specific acoustic impedance on the selected surface. + + * ``AIMP`` - Acoustic impedance on the selected surface. + + * ``MIMP`` - Mechanical impedance on the selected surface. + + * ``PRES`` - Average pressure on the selected surface. + + * ``FORC`` - Force on the selected surface. + + * ``POWE`` - Acoustic power on the selected surface. + + * ``ERP`` - Equivalent radiated power on the selected structural surface (valid only for + ``SHELL181``, ``SOLID185``, ``SOLID186``, ``SOLID187``, ``SOLSH190``, ``SOLID225``, ``SOLID226``, + ``SOLID227``, and ``SHELL281`` ). + + * ``ERPL`` - Equivalent radiated power level on the selected structural surface (valid only for + ``SHELL181``, ``SOLID185``, ``SOLID186``, ``SOLID187``, ``SOLSH190``, ``SOLID225``, ``SOLID226``, + ``SOLID227``, and ``SHELL281`` ). + + * ``BSPL`` - Frequency-band sound pressure level on selected nodes. + + * ``BSPA`` - A-weighted frequency-band sound pressure level on selected nodes. + + * ``MENE`` - Acoustic potential energy on the selected elements. + + * ``KENE`` - Acoustic kinetic energy on the selected elements. + + * ``TENE`` - Acoustic total energy on the selected elements. + + * ``PL2V`` - Average square of the L2 norm of pressure on the selected elements. + + * ``LWIN`` - Input sound power level on defined port. + + * ``LWOUT`` - Output sound power level on defined driven port. + + * ``RL`` - Return loss on defined port. + + * ``ALPHA`` - Absorption coefficient on defined port. + + * ``TL`` - Transmission loss on defined ports. + + * ``DFSTL`` - Transmission loss of random acoustic analysis. + + * ``DFSPW`` - Radiated power in random acoustic analysis. + + ldstep : str + Specified load step. Defaults to the load step number specified on the :ref:`set` command, or defaults to 1 if :ref:`set` has not been issued. This default applies to all ``Lab`` values except DFSTL and DFSPW. + + * ``n`` - Load step number. + + * ``ALL`` - All load steps. + + * ``AVG or 0`` - Average result of multiple samplings in a random acoustic analysis (see the + :ref:`msolve` command). This option is used only for ``Lab`` = DFSTL and DFSPW, and it is the + default for these labels. + + substep : str + Specified substep. Defaults to the substep number specified on the :ref:`set` command, or defaults to ALL (all substeps at the specified load step) if :ref:`set` has not been issued. For ``Lab`` = BSPL or BSPA, ALL is the only valid value. + + * ``n`` - Substep number. + + * ``ALL`` - All substeps. + + freqb : str + Frequency value representing one of the following: + + * Beginning frequency of the frequency range ( ``FREQB`` to ``FREQE`` ) for the defined load step(s) + and substeps ( ``SUBSTEP`` = ALL). If a ``SUBSTEP`` value is specified, ``FREQB`` is invalid. + + * Central frequency of octave bands, used when ``LogOpt`` = OB1, OB2, OB3, OB6, OB12, or OB24 and + ``FREQE`` is blank. + + freqe : str + Ending frequency of the frequency range ( ``FREQB`` to ``FREQE`` ) for the defined load step(s) + and substeps ( ``SUBSTEP`` = ALL). If blank, ``FREQE`` is set to ``FREQB``. If a ``SUBSTEP`` + value is specified, ``FREQE`` is invalid. + + logopt : str + Octave bands: + + * ``OB0`` - Narrow bands (default). + + * ``OB1`` - Octave bands. + + * ``OB2`` - 1/2 octave bands. + + * ``OB3`` - 1/3 octave bands. + + * ``OB6`` - 1/6 octave bands. + + * ``OB12`` - 1/12 octave bands. + + * ``OB24`` - 1/24 octave bands. + + plottype : str + Type of plot: + + * ``LINE`` - Line plot (default). + + * ``BAR`` - Bar pattern plot, used only for ``Lab`` = BSPL or BSPA. + + * ``CONT`` - Waterfall diagram, used only for ``Lab`` = ERP or ERPL. + + val1 : str + Input port number for ``Lab`` = LWIN, LWOUT, RL, ALPHA, or TL. + + val2 : str + Output port number for ``Lab`` = TL. + + val3 : str + Reference power for ``Lab`` = LWIN, LWOUT, or EPRL (defaults to 1x10 :sup:`-12` W). + + val4 : str + Fluid mass density for ``Lab`` = ERP or ERPL (defaults to 1.2041 kg/m :sup:`3` ). + + val5 : str + Speed of sound in the fluid for ``Lab`` = ERP or ERPL (defaults to 343.25 m/s). + + val6 : str + Radiation efficiency for ``Lab`` = ERP or ERPL (defaults to 1). + + Notes + ----- + The :ref:`plas` command plots the specified acoustic quantity on the selected exterior surface, the + energy on selected elements, or the sound pressure level over frequency bands. The calculation is + based on the pressure and velocity solution or the frequency-band sound pressure level (SPL). + + The total pressure and velocity are used if the selected surface is the excitation source surface. + To calculate the incoming and outgoing acoustic power and other sound power parameters on the input + and output surfaces, issue the :ref:`sf`,,PORT command in the preprocessor to define port numbers. + + The sound pressure level of the octave bands and general frequency band (defined via the + :ref:`harfrq` command) is calculated at the selected nodes in the model. + """ + command = f"PLAS,{lab},{ldstep},{substep},{freqb},{freqe},{logopt},{plottype},{val1},{val2},{val3},{val4},{val5},{val6}" + return self.run(command, **kwargs) + + def plcamp( + self, + option: str = "", + slope: str = "", + unit: str = "", + freqb: str = "", + cname: str = "", + stabval: int | str = "", + keyallfreq: str = "", + keynegfreq: str = "", + **kwargs, + ): + r"""Plots Campbell diagram data for applications involving rotating structure dynamics. + + Mechanical APDL Command: `PLCAMP `_ + + Parameters + ---------- + option : str + Flag to activate or deactivate sorting of forward or backward whirl frequencies: + + * ``0 (OFF, or NO)`` - No sorting. + + * ``1 (ON, or YES)`` - Sort. This value is the default. + + slope : str + The slope of the line to be printed. This value must be positive. + + * ``SLOPE > 0`` - In the stationary reference frame ( ``RefFrame`` = YES on the :ref:`coriolis` + command), the line represents the number of excitations per revolution of the rotor. For example, + ``SLOPE`` = 1 represents one excitation per revolution, usually resulting from unbalance. + + In the rotating reference frame ( ``RefFrame`` = NO on the :ref:`coriolis` command), the line + represents the number of excitations per revolution of the rotor minus 1. + + * ``SLOPE = 0`` - The line represents the stability threshold for stability values or logarithmic + decrements printout ( ``STABVAL`` = 1, 2, or 3 ) + + unit : str + Specifies the unit of measurement for rotational angular velocities: + + * ``RDS`` - Rotational angular velocities in radians per second (rad/s). This value is the default. + + * ``RPM`` - Rotational angular velocities in revolutions per minute (RPMs). + + freqb : str + The beginning, or lower end, of the frequency range of interest. The default is zero. + + cname : str + The rotating component name. + + stabval : int or str + Flag to plot the stability values: + + * ``0 (OFF, or NO)`` - Plot the frequencies (the imaginary parts of the eigenvalues in Hz). This + value is the default. + + * ``1 (ON, or YES)`` - Plot the stability values (the real parts of the eigenvalues in Hz). + + * ``2`` - Plot the inverse of the logarithmic decrements. A negative logarithmic decrement indicates + stable motion. + + * ``3`` - Plot the logarithmic decrements. A positive logarithmic decrement indicates stable motion + and is consistent with API (American Petroleum Institute) standards. + + For more information about complex eigenmodes and corresponding logarithmic decrements, see `Complex + Eigensolutions + `_ + in the `Mechanical APDL Theory Reference `_. + + keyallfreq : str + Key to specify if all frequencies above FREQB are plotted: + + * ``0 (OFF, or NO)`` - A maximum of 10 frequencies are plotted. This value is the default. + + * ``1 (ON, or YES)`` - All frequencies are plotted. + + keynegfreq : str + Key to specify if the negative frequencies are plotted. It only applies to solutions obtained with + the damped eigensolver ( ``Method`` = DAMP on the :ref:`modopt` command): + + * ``0 (OFF, or NO)`` - Only positive frequencies are plotted. This value is the default. + + * ``1 (ON, or YES)`` - Negative and positive frequencies are plotted. + + Notes + ----- + The following items are required when generating a Campbell diagram: + + * Activate the Coriolis effect ( :ref:`coriolis` command) in the solution phase ( :ref:`slashsolu` + ). + + * Run a modal analysis using the QR damped ( :ref:`modopt`,QRDAMP) or damped ( :ref:`modopt`,DAMP) + method. Complex eigenmodes are necessary ( :ref:`modopt`,QRDAMP, ``Cpxmod`` = ON), and you must + specify the number of modes to expand ( :ref:`mxpand` ). + + * Define two or more load step results with an ascending order of rotational velocity ( :ref:`omega` + or :ref:`cmomega` ). + + In some cases where modes are not in the same order from one load step to the other, sorting the + frequencies ( ``Option`` = 1) can help to obtain a correct plot. Sorting is based on the comparison + between complex mode shapes calculated at two successive load steps. + + At each load step, the application compares the mode shape to the loads at other load steps to + determine whirl direction at the load step. If applicable, a label appears (in the plot legend) + representing each whirl mode (BW for backward whirl and FW for forward whirl). + + At each load step, the program checks for instability (based on the sign of the real part of the + eigenvalue). The labels "stable" or "unstable" appear in the plot legend for each frequency curve. + + The rotational velocities of a named component ( ``Cname`` ) are displayed on the X-axis. + + For information on plotting a Campbell diagram for a prestressed structure, see `Solving for a + Subsequent Campbell Analysis of a Prestressed Structure Using the Linear Perturbation Procedure + `_ + + For a usage example of the :ref:`plcamp` command, see `Campbell Diagram + `_ + + Damped modal cyclic symmetry ( :ref:`cyclic` ) analyses do not support the :ref:`plcamp` command. + """ + command = f"PLCAMP,{option},{slope},{unit},{freqb},{cname},{stabval},{keyallfreq},{keynegfreq}" + return self.run(command, **kwargs) + + def plcfreq(self, spec: str = "", sectbeg: str = "", sectend: str = "", **kwargs): + r"""Plots the frequency response for the given :ref:`cycspec` specification. + + Mechanical APDL Command: `PLCFREQ `_ + + Parameters + ---------- + spec : str + :ref:`cycspec` specification number (ordered 1 to N in the order input; use :ref:`cycspec`,LIST + to view the current list order). Defaults to 1. + + sectbeg : str + Beginning sector number to plot. Defaults to 1. + + sectend : str + Ending sector number to plot. Defaults to the total number of sectors expanded ( + :ref:`cycexpand` ). + + Notes + ----- + + .. _PLCFREQ_notes: + + Following a cyclic mode-superposition harmonic analysis, this command plots the result item given by + a :ref:`cycspec` specification versus the harmonic frequency, one curve for each of the specified + sectors. A :ref:`cyccalc` command must have been issued prior to this command. + """ + command = f"PLCFREQ,{spec},{sectbeg},{sectend}" + return self.run(command, **kwargs) + + def plchist(self, spec: str = "", freqpt: str = "", **kwargs): + r"""Plots a histogram of the frequency response of each sector for the given :ref:`cycspec` + specification. + + Mechanical APDL Command: `PLCHIST `_ + + Parameters + ---------- + spec : str + :ref:`cycspec` specification number (ordered 1 to N in the order input; use :ref:`cycspec`,LIST + to view the current list order). Defaults to 1. + + freqpt : str + Harmonic frequency point to plot (the data set number NSET or CUMULATIVE on :ref:`set`,LIST). + Defaults to the current :ref:`set` frequency. + + Notes + ----- + + .. _PLCHIST_notes: + + Following a cyclic mode-superposition harmonic analysis, this command creates a histogram plot of + the result item given by a :ref:`cycspec` specification versus the sector number. A :ref:`cyccalc` + command must have been issued prior to this command. + """ + command = f"PLCHIST,{spec},{freqpt}" + return self.run(command, **kwargs) + + def plfar( + self, + lab: str = "", + option: str = "", + var1b: str = "", + var1e: str = "", + nvar1: str = "", + var2b: str = "", + var2e: str = "", + nvar2: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + ldstep: str = "", + substep: str = "", + freqb: str = "", + freqe: str = "", + plottype: str = "", + logopt: str = "", + **kwargs, + ): + r"""Plots pressure far fields and far-field parameters. + + Mechanical APDL Command: `PLFAR `_ + + Parameters + ---------- + lab : str + Parameters to plot : + + * ``PRES`` - Acoustic parameters + + * ``PROT`` - Acoustic parameters with the y-axis rotated extrusion (not valid for 2D elements) + + * ``PLAT`` - Acoustic parameters radiated by a vibrating structural panel (not valid for 2D + elements) + + option : str + Plot option, based on the specified plot parameter type: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + var1b : str + Starting and ending values for the first variable associated with ``PlotType`` as described + below. + + When ``PlotType`` = blank (default) or SPHR: Starting and ending phi (φ) angles (in degrees) in + the spherical coordinate system. Defaults to 0. + + When ``PlotType`` = PLXY: Starting and ending x value in the Cartesian coordinate system. + Defaults to 0. + + When ``PlotType`` = PLYZ: Starting and ending y value in the Cartesian coordinate system. + Defaults to 0. + + When ``PlotType`` = PLXZ: Starting and ending x value in the Cartesian coordinate system. + Defaults to 0. + + var1e : str + Starting and ending values for the first variable associated with ``PlotType`` as described + below. + + When ``PlotType`` = blank (default) or SPHR: Starting and ending phi (φ) angles (in degrees) in + the spherical coordinate system. Defaults to 0. + + When ``PlotType`` = PLXY: Starting and ending x value in the Cartesian coordinate system. + Defaults to 0. + + When ``PlotType`` = PLYZ: Starting and ending y value in the Cartesian coordinate system. + Defaults to 0. + + When ``PlotType`` = PLXZ: Starting and ending x value in the Cartesian coordinate system. + Defaults to 0. + + nvar1 : str + Number of divisions between the starting and ending ``VAR1`` values for data computations. + Defaults to 0. + + var2b : str + Starting and ending values for the second variable associated with ``PlotType`` as described + below. + + When ``PlotType`` = blank (default) or SPHR: Starting and ending theta (θ) angles (in degrees) + in the spherical coordinate system. Defaults to 0 for a 3D model and 90 for a 2D extrusion + model. + + When ``PlotType`` = PLXY: Starting and ending y value in the Cartesian coordinate system. + Defaults to 0. + + When ``PlotType`` = PLYZ: Starting and ending z value in the Cartesian coordinate system. + Defaults to 0. + + When ``PlotType`` = PLXZ: Starting and ending z value in the Cartesian coordinate system. + Defaults to 0. + + var2e : str + Starting and ending values for the second variable associated with ``PlotType`` as described + below. + + When ``PlotType`` = blank (default) or SPHR: Starting and ending theta (θ) angles (in degrees) + in the spherical coordinate system. Defaults to 0 for a 3D model and 90 for a 2D extrusion + model. + + When ``PlotType`` = PLXY: Starting and ending y value in the Cartesian coordinate system. + Defaults to 0. + + When ``PlotType`` = PLYZ: Starting and ending z value in the Cartesian coordinate system. + Defaults to 0. + + When ``PlotType`` = PLXZ: Starting and ending z value in the Cartesian coordinate system. + Defaults to 0. + + nvar2 : str + Number of divisions between the starting and ending ``VAR2`` values for data computations. + Defaults to 0. + + val1 : str + ``VAL1`` is additional input. Its meaning depends on the ``PlotType`` argument as described + below. + + When ``PlotType`` = blank (default) or SPHR: Radius of the sphere surface. + + When ``PlotType`` = PLXY: Fixed z value for an X-Y plane in the Cartesian coordinate system. + Defaults to 0. + + When ``PlotType`` = PLYZ: Fixed x value for a Y-Z plane in the Cartesian coordinate system. + Defaults to 0. + + When ``PlotType`` = PLXZ: Fixed y value for an X-Z plane in the Cartesian coordinate system, + Defaults to 0. + + val2 : str + When ``Option`` = SPLC, SPLP, SPAC, or SPAP: Reference rms sound pressure. Defaults to 2x10 + :sup:`-5` Pa. + + When ``Option`` = PWL: Reference sound power. Defaults to 1x10 :sup:`-12` watts. + + val3 : str + When ``Lab`` = PRES: Thickness of 2D model extrusion in the z direction (no default). + + When ``Lab`` = PROT: Angle of the y-axis rotated extrusion model (no default). + + val4 : str + When ``Lab`` = PLAT: Mass density of acoustic fluid. + + val5 : str + When ``Lab`` = PLAT: Sound speed in acoustic fluid. + + ldstep : str + Specified load step. Defaults to the load step number specified on the :ref:`set` command, or defaults to 1 if :ref:`set` has not been issued. + + * ``n`` - Load step number. + + * ``ALL`` - All load steps. + + substep : str + Specified substep. Defaults to the substep number specified on the :ref:`set` command, or defaults to ALL (all substeps at the specified load step) if :ref:`set` has not been issued. + + * ``n`` - Substep number. + + * ``ALL`` - All substeps. + + freqb : str + Frequency value representing one of the following: + + * Beginning frequency of the frequency range ( ``FREQB`` to ``FREQE`` ) for the defined load step(s) + and substeps ( ``SUBSTEP`` = ALL). If a ``SUBSTEP`` value is specified, ``FREQB`` is invalid. + + * Central frequency of octave bands, used when ``LogOpt`` = OB1, OB2, OB3, OB6, OB12, or OB24 and + ``FREQE`` is blank. + + freqe : str + Ending frequency of the frequency range ( ``FREQB`` to ``FREQE`` ) for the defined load step(s) + and substeps ( ``SUBSTEP`` = ALL). If blank, ``FREQE`` is set to ``FREQB``. If a ``SUBSTEP`` + value is specified, ``FREQE`` is invalid. + + plottype : str + Type of plot: + + * ``ANGX`` - x-y chart with angle as the x-axis variable (default). + + * ``FRQX`` - x-y chart with frequency as the x-axis variable. + + * ``CONT`` - Waterfall diagram of a field parameter with variables (frequency, angle). + + * ``MRPM`` - Waterfall diagram of a field parameter with variables (frequency, RPM). + + * ``PLXY`` - Contour plot on an X-Y plane. + + * ``PLYZ`` - Contour plot on a Y-Z plane. + + * ``PLXZ`` - Contour plot on an X-Z plane. + + * ``SPHR`` - Contour plot on a sphere surface. + + logopt : str + Octave bands (used only when Option = SPLC, SPLP, SPAC, SPAP, or PWL) : + + * ``OB0`` - Narrow bands (default). + + * ``OB1`` - Octave bands. + + * ``OB2`` - 1/2 octave bands. + + * ``OB3`` - 1/3 octave bands. + + * ``OB6`` - 1/6 octave bands. + + * ``OB12`` - 1/12 octave bands. + + * ``OB24`` - 1/24 octave bands. + + Notes + ----- + + .. warning:: + + This function contains specificities regarding the argument definitions. + Please refer to the `command documentation `_ + for further explanations. + + .. _PLFAR_notes: + + The :ref:`plfar` command plots pressure far fields and far-field parameters as determined by the + equivalent source principle. Use this command to plot pressure and acoustic parameters. See the + :ref:`hfsym` command for the model symmetry and the :ref:`hfang` command for spatial radiation + angles. + + Plotting acoustic parameters radiated by a vibrating structural panel ( ``Lab`` = PLAT) is supported + by elements ``SOLID185``, ``SOLID186``, ``SOLID187``, ``SHELL181``, ``SHELL281``, and ``SOLSH190``. + The vibration surface of the panel must be flagged by the :ref:`sf`,,MXWF command. + + A maximum of ten curves can be plotted on a 2D chart. + + The waterfall diagram is plotted only in Cartesian coordinates. + """ + command = f"PLFAR,{lab},{option},{var1b},{var1e},{nvar1},{var2b},{var2e},{nvar2},{val1},{val2},{val3},{val4},{val5},{ldstep},{substep},{freqb},{freqe},{plottype},{logopt}" + return self.run(command, **kwargs) + + def plmc( + self, + lstep: str = "", + sbstep: str = "", + timfrq: str = "", + kimg: int | str = "", + hibeg: str = "", + hiend: str = "", + **kwargs, + ): + r"""Plots the modal coordinates from a mode-superposition solution. + + Mechanical APDL Command: `PLMC `_ + + Parameters + ---------- + lstep : str + Plot the solution identified as load step ``LSTEP`` and substep ``SBSTEP`` + + sbstep : str + Plot the solution identified as load step ``LSTEP`` and substep ``SBSTEP`` + + timfrq : str + As an alternative to ``LSTEP`` and ``SBSTEP``, plot the solution at the time value ``TIMFRQ`` + (for :ref:`antype`,TRANS) or frequency value ``TIMFRQ`` (for :ref:`antype`,HARMIC). ``LSTEP`` + and ``SBSTEP`` should be left blank. + + kimg : int or str + Key for plotting real or imaginary solution. Valid only for :ref:`antype`,HARMIC. + + * ``0 (or blank)`` - Plot the real solution (default). + + * ``1`` - Plot the imaginary solution. + + * ``2`` - Plot the amplitude. + + hibeg : str + For cyclic symmetry solutions, plot the solutions in the harmonic index solution range ``HIbeg`` + to ``HIend``. Defaults to all harmonic indices (all modes). + + hiend : str + For cyclic symmetry solutions, plot the solutions in the harmonic index solution range ``HIbeg`` + to ``HIend``. Defaults to all harmonic indices (all modes). + + Notes + ----- + + .. _PLMC_notes: + + :ref:`plmc` plots a histogram of the modal coordinates (the factors which modes may be multiplied by + to obtain their contribution to the response) at a certain time point (transient analyses) or + frequency point (harmonic analyses). The absolute values of the modal coordinates are plotted. Use + :ref:`xrange` to plot only modes in a certain range, if desired. + + For transient analyses, a :file:`.rdsp` None file must be available. For harmonic analyses, a + :file:`.rfrq` None file must be available. The content of these files depends on the :ref:`outres` + command settings. Note that the default for mode-superposition transient analysis is to write the + reduced displacement file every 4th substep. For more information, see Command Default in the + :ref:`outres` command description. + + For a cyclic harmonic mode-superposition analysis, use the :ref:`cycfiles` command to identify the + :file:`.rfrq` None and modal :file:`.rst` None file. For other analyses, use the ``FILE`` command to + specify the :file:`.rdsp` or :file:`.rfrq` file. + + You may limit the plot to display only those modes in a certain harmonic index range. The modes + having the same harmonic index are each plotted in a unique color. If there are less than 10 + harmonic indices, they are identified in the graphics legend. + + This is a graphical representation of the optional :file:`Jobname.mcf` text file (see the + :ref:`trnopt` and :ref:`hropt` commands). To print the modal coordinates, use the :ref:`prmc` + command. For more information on modal coordinates, see `Mode-Superposition Method + `_ + in the `Mechanical APDL Theory Reference + `_. + + **Example Usage** + + .. _PLMC_examples: + + `Example Mode-Superposition Harmonic Cyclic Symmetry Analysis with Mistuning + `_ + + Example: Forced Response with Mistuning and Aero Coupling + """ + command = f"PLMC,{lstep},{sbstep},{timfrq},{kimg},{hibeg},{hiend}" + return self.run(command, **kwargs) + + def plnear( + self, + lab: str = "", + opt: str = "", + kcn: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + val7: str = "", + val8: str = "", + val9: str = "", + **kwargs, + ): + r"""Plots the pressure in the near zone exterior to the equivalent source surface. + + Mechanical APDL Command: `PLNEAR `_ + + Parameters + ---------- + lab : str + Plot the maximum pressure or sound pressure level: + + * ``SPHERE`` - on the spherical structure + + * ``PATH`` - along the path + + opt : str + * ``PSUM`` - Maximum complex pressure for acoustics. + + * ``PHAS`` - Phase angle of complex pressure for acoustics. + + * ``SPL`` - Sound pressure level for acoustics. + + * ``SPLA`` - A-weighted sound pressure level for acoustics (dBA). + + kcn : str + KCN is the coordinate system reference number. It may be 0 (Cartesian) or any previously defined + local coordinate system number (>10). Defaults to 0. + + val1 : str + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`plnear` computes the electric field or pressure for the path data + points for the path currently defined by the :ref:`path` and :ref:`ppath` commands. + + val2 : str + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`plnear` computes the electric field or pressure for the path data + points for the path currently defined by the :ref:`path` and :ref:`ppath` commands. + + val3 : str + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`plnear` computes the electric field or pressure for the path data + points for the path currently defined by the :ref:`path` and :ref:`ppath` commands. + + val4 : str + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`plnear` computes the electric field or pressure for the path data + points for the path currently defined by the :ref:`path` and :ref:`ppath` commands. + + val5 : str + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`plnear` computes the electric field or pressure for the path data + points for the path currently defined by the :ref:`path` and :ref:`ppath` commands. + + val6 : str + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`plnear` computes the electric field or pressure for the path data + points for the path currently defined by the :ref:`path` and :ref:`ppath` commands. + + val7 : str + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`plnear` computes the electric field or pressure for the path data + points for the path currently defined by the :ref:`path` and :ref:`ppath` commands. + + val8 : str + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`plnear` computes the electric field or pressure for the path data + points for the path currently defined by the :ref:`path` and :ref:`ppath` commands. + + val9 : str + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`plnear` computes the electric field or pressure for the path data + points for the path currently defined by the :ref:`path` and :ref:`ppath` commands. + + Notes + ----- + + .. _PLNEAR_notes: + + :ref:`plnear` uses the equivalent source principle to calculate the pressure in the near zone + exterior to the equivalent source surface (flagged with the Maxwell surface flag in the + preprocessor) for one of the following locations: + + * A spherical surface in the KCN coordinate system + + * A path defined by the :ref:`path` and :ref:`ppath` commands + + To plot the pressure results for a path, use the :ref:`plpagm` or :ref:`plpath` commands. See the + :ref:`hfsym` command for the model symmetry. + + To retrieve saved equivalent source data, issue the :ref:`set`, ``Lstep``, ``Sbstep``,,REAL command. + """ + command = f"PLNEAR,{lab},{opt},{kcn},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8},{val9}" + return self.run(command, **kwargs) + + def plzz(self, rotvel: str = "", deltarotvel: str = "", **kwargs): + r"""Plots the interference diagram from a cyclic modal analysis. + + Mechanical APDL Command: `PLZZ `_ + + Parameters + ---------- + rotvel : str + Rotational speed in revolutions per minute (RPM) used to define the speed line. If blank, use + the rotational speed (from :ref:`omega` ) specified in the prestressing step of the linear + perturbation analysis. If explicitly input as 0, or if the linear perturbation was not used, no + speed lines are plotted. + + deltarotvel : str + Adds speed lines about the ``RotVel`` speed line corresponding to ``RotVel`` ± ``DeltaRotVel``. + Only plotted if ``RotVel`` is known. + + Notes + ----- + + .. _PLZZ_notes: + + :ref:`plzz` plots the cyclic modal frequencies as points on a frequency vs. harmonic index (nodal + diameter) graph. If rotational speed ( ``RotVel`` ) is provided, the speed line is also plotted, + leading to the interference diagram (also known as the SAFE or ZZENF diagram). If ``DeltaRotVel`` is + also provided, two additional speed lines are plotted, enveloping the safe speed line itself. + + For more information, see `Postprocessing a Modal Cyclic Symmetry Analysis + `_ + """ + command = f"PLZZ,{rotvel},{deltarotvel}" + return self.run(command, **kwargs) + + def pras( + self, + lab: str = "", + ldstep: str = "", + substep: str = "", + freqb: str = "", + freqe: str = "", + logopt: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + **kwargs, + ): + r"""Prints a specified acoustic quantity during postprocessing of an acoustic analysis. + + Mechanical APDL Command: `PRAS `_ + + Parameters + ---------- + lab : str + The acoustic quantity to calculate: + + * ``SIMP`` - Specific acoustic impedance on the selected surface. + + * ``AIMP`` - Acoustic impedance on the selected surface. + + * ``MIMP`` - Mechanical impedance on the selected surface. + + * ``PRES`` - Average pressure on the selected surface. + + * ``FORC`` - Force on the selected surface. + + * ``POWE`` - Acoustic power on the selected surface. + + * ``ERP`` - Equivalent radiated power on the selected structural surface (valid only for + ``SHELL181``, ``SOLID185``, ``SOLID186``, ``SOLID187``, ``SOLSH190``, ``SOLID225``, ``SOLID226``, + ``SOLID227``, and ``SHELL281`` ). + + * ``ERPL`` - Equivalent radiated power level on the selected structural surface (valid only for + ``SHELL181``, ``SOLID185``, ``SOLID186``, ``SOLID187``, ``SOLSH190``, ``SOLID225``, ``SOLID226``, + ``SOLID227``, and ``SHELL281`` ). + + * ``BSPL`` - Frequency-band sound pressure level on selected nodes. + + * ``BSPA`` - A-weighted frequency-band sound pressure level on selected nodes. + + * ``MENE`` - Acoustic potential energy on the selected elements. + + * ``KENE`` - Acoustic kinetic energy on the selected elements. + + * ``TENE`` - Acoustic total energy on the selected elements. + + * ``PL2V`` - Average square of the L2 norm of pressure on the selected elements. + + * ``LWIN`` - Input sound power level on defined port. + + * ``LWOUT`` - Output sound power level on defined driven port. + + * ``RL`` - Return loss on defined port. + + * ``ALPHA`` - Absorption coefficient on defined port. + + * ``TL`` - Transmission loss on defined ports. + + * ``PALL`` - All port-related parameters (LWIN, LWOUT, RL, ALPHA, TL). + + * ``DFSTL`` - Transmission loss of random acoustic analysis. + + * ``DFSPW`` - Radiated power in random acoustic analysis. + + * ``DALL`` - All random acoustic related parameters (DFSTL, DFSPW). + + ldstep : str + Specified load step. Defaults to the load step number specified on the :ref:`set` command, or defaults to 1 if :ref:`set` has not been issued. This default applies to all ``Lab`` values except DFSTL, DFSPW, and DALL. + + * ``n`` - Load step number. + + * ``ALL`` - All load steps. + + * ``AVG or 0`` - Average result of multiple samplings in a random acoustic analysis (see the + :ref:`msolve` command). This option is used only for ``Lab`` = DFSTL, DFSPW, and DALL, and it is the + default for these labels. + + substep : str + Specified substep. Defaults to the substep number specified on the :ref:`set` command, or defaults to ALL (all substeps at the specified load step) if :ref:`set` has not been issued. For ``Lab`` = BSPL or BSPA, ALL is the only valid value. + + * ``n`` - Substep number. + + * ``ALL`` - All substeps. + + freqb : str + Frequency value representing one of the following: + + * Beginning frequency of the frequency range ( ``FREQB`` to ``FREQE`` ) for the defined load step(s) + and substeps ( ``SUBSTEP`` = ALL). If a ``SUBSTEP`` value is specified, ``FREQB`` is invalid. + + * Central frequency of octave bands, used when ``LogOpt`` = OB1, OB2, OB3, OB6, OB12, or OB24 and + ``FREQE`` is blank. + + freqe : str + Ending frequency of the frequency range ( ``FREQB`` to ``FREQE`` ) for the defined load step(s) + and substeps ( ``SUBSTEP`` = ALL). If blank, ``FREQE`` is set to ``FREQB``. If a ``SUBSTEP`` + value is specified, ``FREQE`` is invalid. + + logopt : str + Octave bands: + + * ``OB0`` - Narrow bands (default). + + * ``OB1`` - Octave bands. + + * ``OB2`` - 1/2 octave bands. + + * ``OB3`` - 1/3 octave bands. + + * ``OB6`` - 1/6 octave bands. + + * ``OB12`` - 1/12 octave bands. + + * ``OB24`` - 1/24 octave bands. + + val1 : str + Input port number for ``Lab`` = LWIN, LWOUT, RL, ALPHA, TL, or PALL. + + val2 : str + Output port number for ``Lab`` = TL or PALL. + + val3 : str + Reference power for ``Lab`` = LWIN, LWOUT, PALL or EPRL (defaults to 1x10 :sup:`-12` W). + + val4 : str + Fluid mass density for ``Lab`` = ERP or ERPL (defaults to 1.2041 kg/m :sup:`3` ). + + val5 : str + Speed of sound in the fluid for ``Lab`` = ERP or ERPL (defaults to 343.25 m/s). + + val6 : str + Radiation efficiency for ``Lab`` = ERP or ERPL (defaults to 1). + + Notes + ----- + The :ref:`pras` command lists the specified acoustic quantity on the selected exterior surface, the + energy on selected elements, or the sound pressure level over frequency bands. The calculation is + based on the pressure and velocity solution or the frequency-band sound pressure level (SPL). + + The total pressure and velocity are used if the selected surface is the excitation source surface. + To calculate the incoming and outgoing acoustic power and other sound power parameters on the input + and output surfaces, issue the :ref:`sf`,,PORT command in the preprocessor to define port numbers. + + The sound pressure level of the octave bands and general frequency band (defined via the + :ref:`harfrq` command) is calculated at the selected nodes in the model. + """ + command = f"PRAS,{lab},{ldstep},{substep},{freqb},{freqe},{logopt},,{val1},{val2},{val3},{val4},{val5},{val6}" + return self.run(command, **kwargs) + + def prcamp( + self, + option: str = "", + slope: str = "", + unit: str = "", + freqb: str = "", + cname: str = "", + stabval: int | str = "", + keyallfreq: str = "", + keynegfreq: str = "", + keywhirl: str = "", + **kwargs, + ): + r"""Prints Campbell diagram data for applications involving rotating structure dynamics. + + Mechanical APDL Command: `PRCAMP `_ + + Parameters + ---------- + option : str + Flag to activate or deactivate sorting of forward or backward whirl frequencies: + + * ``0 (OFF, or NO)`` - No sorting. + + * ``1 (ON, or YES)`` - Sort. This value is the default. + + slope : str + The slope of the line to be printed. This value must be positive. + + * ``SLOPE > 0`` - In the stationary reference frame ( ``RefFrame`` = YES on the :ref:`coriolis` + command), the line represents the number of excitations per revolution of the rotor. For example, + ``SLOPE`` = 1 represents one excitation per revolution, usually resulting from unbalance. + + In the rotating reference frame ( ``RefFrame`` = NO on the :ref:`coriolis` command), the line + represents the number of excitations per revolution of the rotor minus 1. + + * ``SLOPE = 0`` - The line represents the stability threshold for stability values or logarithmic + decrements printout ( ``STABVAL`` = 1, 2, or 3 ) + + unit : str + Specifies the unit of measurement for rotational angular velocities: + + * ``RDS`` - Rotational angular velocities in radians per second (rad/s). This value is the default. + + * ``RPM`` - Rotational angular velocities in revolutions per minute (RPMs). + + freqb : str + The beginning, or lower end, of the frequency range of interest. The default is zero. + + cname : str + The rotating component name. + + stabval : int or str + Flag to print the stability values: + + * ``0 (OFF, or NO)`` - Print the frequencies (the imaginary parts of the eigenvalues in Hz). This + value is the default. + + * ``1 (ON, or YES)`` - Print the stability values (the real parts of the eigenvalues in Hz). + + * ``2`` - Print the inverse of the logarithmic decrements. A negative logarithmic decrement + indicates stable motion. + + * ``3`` - Print the logarithmic decrements. A positive logarithmic decrement indicates stable motion + and is consistent with API (American Petroleum Institute) standards. + + For more information about complex eigenmodes and corresponding logarithmic decrements, see `Complex + Eigensolutions + `_ + in the `Mechanical APDL Theory Reference `_. + + keyallfreq : str + Key to specify if all frequencies above FREQB are printed out: + + * ``0 (OFF, or NO)`` - A maximum of 10 frequencies are printed out. They correspond to the + frequencies displayed via the :ref:`plcamp` command. This value is the default. + + * ``1 (ON, or YES)`` - All frequencies are printed out. + + keynegfreq : str + Key to specify if the negative frequencies are printed out. It only applies to solutions obtained + with the damped eigensolver ( ``Method`` =DAMP on the :ref:`modopt` command): + + * ``0 (OFF, or NO)`` - Only positive frequencies are printed out. This value is the default. + + * ``1 (ON, or YES)`` - Negative and positive frequencies are printed out. + + keywhirl : str + Flag to print the whirl and instability keys for each load step: + + * ``0 (OFF, or NO)`` - Print the whirl for the last load step. This value is the default. + + * ``1 (ON, or YES)`` - Print the whirl and instability keys for each load step. + + Notes + ----- + The following items are required when generating a Campbell diagram: + + * Activate the Coriolis effect ( :ref:`coriolis` command) in the solution phase ( :ref:`slashsolu` + ). + + * Run a modal analysis using the QR damped ( :ref:`modopt`,QRDAMP) or damped ( :ref:`modopt`,DAMP) + method. Complex eigenmodes are necessary ( :ref:`modopt`,QRDAMP, ``Cpxmod`` = ON), and you must + specify the number of modes to expand ( :ref:`mxpand` ). + + * Define two or more load step results with an ascending order of rotational velocity ( :ref:`omega` + or :ref:`cmomega` ). + + In some cases where modes are not in the same order from one load step to the other, sorting the + frequencies ( ``Option`` = 1) can help to obtain a correct printout. Sorting is based on the + comparison between complex mode shapes calculated at two successive load steps. + + At each load step, the application compares the mode shape to the loads to determine the whirl + direction. If applicable, a label appears (on the rows of output data) representing the whirl mode + (BW for backward whirl and FW for forward whirl). + + If you specify a non-zero slope ( ``SLOPE`` > 0), the command prints the critical speeds + corresponding to the intersection points of the frequency curves and the added line. In the case of + a named component ( ``Cname`` ), critical speeds relate to the rotational velocity of the component. + Critical speeds are available only if the frequencies are printed ( STABVAL = OFF). + + If you specify a zero slope ( ``SLOPE`` = 0), the command prints the stability threshold + corresponding to the sign change of the stability values (or logarithmic decrements). In the case of + a named component ( ``Cname`` ), stability thresholds relate to the rotational velocity of the + component. Stability thresholds are available only if the stability values or logarithmic decrements + are printed ( ``STABVAL`` = 1, 2, or 3 ). + + At each load step, the program checks for instability (based on the sign of the real part of the + eigenvalue). The label "U" appears on the printout for each unstable frequency. + + If specified, the rotational velocities of the named component ( ``Cname`` ) are printed out along + with the natural frequencies. + + For information on printing a Campbell diagram for a prestressed structure, see `Solving for a + Subsequent Campbell Analysis of a Prestressed Structure Using the Linear Perturbation Procedure + `_ + + For a usage example of the companion command :ref:`plcamp` (used for plotting a Campbell diagram), + see `Example: Campbell Diagram Analysis of a Simply Supported Beam + `_ + + For more information on Campbell diagram generation, see `Campbell Diagram + `_ + + Damped modal cyclic symmetry ( :ref:`cyclic` ) analyses do not support the :ref:`prcamp` command. + """ + command = f"PRCAMP,{option},{slope},{unit},{freqb},{cname},{stabval},{keyallfreq},{keynegfreq},{keywhirl}" + return self.run(command, **kwargs) + + def prfar( + self, + lab: str = "", + option: str = "", + var1b: str = "", + var1e: str = "", + nvar1: str = "", + var2b: str = "", + var2e: str = "", + nvar2: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + ldstep: str = "", + substep: str = "", + freqb: str = "", + freqe: str = "", + printtype: str = "", + logopt: str = "", + **kwargs, + ): + r"""Prints acoustic far field parameters. + + Mechanical APDL Command: `PRFAR `_ + + Parameters + ---------- + lab : str + Parameters to print: + + * ``PRES`` - Acoustic parameters + + * ``PROT`` - Acoustic parameters with the y-axis rotated extrusion (not valid for 2D elements) + + * ``PLAT`` - Acoustic parameters radiated by a vibrating structural panel (not valid for 2D + elements) + + option : str + Print option, based on the specified print parameter type: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + var1b : str + Starting and ending values for the first variable associated with ``PrintType`` as described + below. + + When ``PrintType`` = blank (default) or SPHR: Starting and ending phi (φ) angles (in degrees) in + the spherical coordinate system. Defaults to 0. + + When ``PrintType`` = PLXY: Starting and ending x value in the Cartesian coordinate system. + Defaults to 0. + + When ``PrintType`` = PLYZ: Starting and ending y value in the Cartesian coordinate system. + Defaults to 0. + + When ``PrintType`` = PLXZ: Starting and ending x value in the Cartesian coordinate system. + Defaults to 0. + + var1e : str + Starting and ending values for the first variable associated with ``PrintType`` as described + below. + + When ``PrintType`` = blank (default) or SPHR: Starting and ending phi (φ) angles (in degrees) in + the spherical coordinate system. Defaults to 0. + + When ``PrintType`` = PLXY: Starting and ending x value in the Cartesian coordinate system. + Defaults to 0. + + When ``PrintType`` = PLYZ: Starting and ending y value in the Cartesian coordinate system. + Defaults to 0. + + When ``PrintType`` = PLXZ: Starting and ending x value in the Cartesian coordinate system. + Defaults to 0. + + nvar1 : str + Number of divisions between the starting and ending ``VAR1`` values for data computations. + Defaults to 0. + + var2b : str + Starting and ending values for the second variable associated with ``PrintType`` as described + below. + + When ``PrintType`` = blank (default) or SPHR: Starting and ending theta (θ) angles (in degrees) + in the spherical coordinate system. Defaults to 0 for a 3D model and 90 for a 2D extrusion + model. + + When ``PrintType`` = PLXY: Starting and ending y value in the Cartesian coordinate system. + Defaults to 0. + + When ``PrintType`` = PLYZ: Starting and ending z value in the Cartesian coordinate system. + Defaults to 0. + + When ``PrintType`` = PLXZ: Starting and ending z value in the Cartesian coordinate system. + Defaults to 0. + + var2e : str + Starting and ending values for the second variable associated with ``PrintType`` as described + below. + + When ``PrintType`` = blank (default) or SPHR: Starting and ending theta (θ) angles (in degrees) + in the spherical coordinate system. Defaults to 0 for a 3D model and 90 for a 2D extrusion + model. + + When ``PrintType`` = PLXY: Starting and ending y value in the Cartesian coordinate system. + Defaults to 0. + + When ``PrintType`` = PLYZ: Starting and ending z value in the Cartesian coordinate system. + Defaults to 0. + + When ``PrintType`` = PLXZ: Starting and ending z value in the Cartesian coordinate system. + Defaults to 0. + + nvar2 : str + Number of divisions between the starting and ending ``VAR2`` values for data computations. + Defaults to 0. + + val1 : str + ``VAL1`` is additional input. Its meaning depends on the ``PrintType`` argument as described + below. + + When ``PrintType`` = blank (default) or SPHR: Radius of the sphere surface. + + When ``PrintType`` = PLXY: Fixed z value for an X-Y plane in the Cartesian coordinate system. + Defaults to 0. + + When ``PrintType`` = PLYZ: Fixed x value for a Y-Z plane in the Cartesian coordinate system. + Defaults to 0. + + When ``PrintType`` = PLXZ: Fixed y value for an X-Z plane in the Cartesian coordinate system, + Defaults to 0. + + val2 : str + When ``Option`` = SPLC or SPAC: Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + When ``Option`` = PWL: Reference sound power. Defaults to 1x10 :sup:`-12` watts. + + val3 : str + When ``Lab`` = PRES: Thickness of 2D model extrusion in the z direction (no default). + + When ``Lab`` = PROT: Angle of the y-axis rotated extrusion model (no default) + + val4 : str + When ``Lab`` = PLAT: Mass density of acoustic fluid. + + val5 : str + When ``Lab`` = PLAT: Sound speed in acoustic fluid. + + ldstep : str + Specified load step. Defaults to the load step number specified on the :ref:`set` command, or defaults to 1 if :ref:`set` has not been issued. + + * ``n`` - Load step number. + + * ``ALL`` - All load steps. + + substep : str + Specified substep. Defaults to the substep number specified on the :ref:`set` command, or defaults to ALL (all substeps at the specified load step) if :ref:`set` has not been issued. + + * ``n`` - Substep number. + + * ``ALL`` - All substeps. + + freqb : str + Frequency value representing one of the following: + + * Beginning frequency of the frequency range ( ``FREQB`` to ``FREQE`` ) for the defined load step(s) + and substeps ( ``SUBSTEP`` = ALL). If a ``SUBSTEP`` value is specified, ``FREQB`` is invalid. + + * Central frequency of octave bands, used when ``LogOpt`` = OB1, OB2, OB3, OB6, OB12, or OB24 and + ``FREQE`` is blank. + + freqe : str + Ending frequency of the frequency range ( ``FREQB`` to ``FREQE`` ) for the defined load step(s) + and substeps ( ``SUBSTEP`` = ALL). If blank, ``FREQE`` is set to ``FREQB``. If a ``SUBSTEP`` + value is specified, ``FREQE`` is invalid. + + printtype : str + Print out far-field parameters on a plane or sphere (used when ``Option`` = SUMC, PHSC, SPLC, SPAC, DGCT, PSCT, or TSCT). No default. + + * ``PLXY`` - On an X-Y plane. + + * ``PLYZ`` - On a Y-Z plane. + + * ``PLXZ`` - On an X-Z plane. + + * ``SPHR`` - On a sphere surface. + + logopt : str + Octave bands (used only when Option = SPLC, SPAC, or PWL) : + + * ``OB0`` - Narrow bands (default). + + * ``OB1`` - Octave bands. + + * ``OB2`` - 1/2 octave bands. + + * ``OB3`` - 1/3 octave bands. + + * ``OB6`` - 1/6 octave bands. + + * ``OB12`` - 1/12 octave bands. + + * ``OB24`` - 1/24 octave bands. + + Notes + ----- + + .. warning:: + + This function contains specificities regarding the argument definitions. + Please refer to the `command documentation `_ + for further explanations. + + .. _PRFAR_notes: + + The :ref:`prfar` command prints pressure far fields and far field parameters as determined by the + equivalent source principle. Use this command to print pressure and acoustic parameters. See the + :ref:`hfsym` command for the model symmetry and the :ref:`hfang` command for spatial radiation + angles. + + Printing acoustic parameters radiated by a vibrating structural panel ( ``Lab`` = PLAT) is supported + by elements ``SOLID185``, ``SOLID186``, ``SOLID187``, ``SHELL181``, ``SHELL281``, and ``SOLSH190``. + The vibration surface of the panel must be flagged by the :ref:`sf`,MXWF command. + """ + command = f"PRFAR,{lab},{option},{var1b},{var1e},{nvar1},{var2b},{var2e},{nvar2},{val1},{val2},{val3},{val4},{val5},{ldstep},{substep},{freqb},{freqe},{printtype},{logopt}" + return self.run(command, **kwargs) + + def prmc( + self, + lstep: str = "", + sbstep: str = "", + timfrq: str = "", + kimg: int | str = "", + hibeg: str = "", + hiend: str = "", + matrix: str = "", + **kwargs, + ): + r"""Prints the modal coordinates from a mode-superposition solution. + + Mechanical APDL Command: `PRMC `_ + + Parameters + ---------- + lstep : str + Print the solution identified as load step ``LSTEP`` and substep ``SBSTEP``. + + sbstep : str + Print the solution identified as load step ``LSTEP`` and substep ``SBSTEP``. + + timfrq : str + As an alternative to ``LSTEP`` and ``SBSTEP``, print the solution at the time value ``TIMFRQ`` + (for :ref:`antype`,TRANS) or frequency value ``TIMFRQ`` (for :ref:`antype`,HARMIC). ``LSTEP`` + and ``SBSTEP`` should be left blank. + + kimg : int or str + Key for printing real or imaginary solution. Valid only for :ref:`antype`,HARMIC. + + * ``0 (or blank)`` - Print the real solution (default). + + * ``1`` - Print the imaginary solution. + + * ``2`` - Print the amplitude. + + hibeg : str + For cyclic symmetry solutions, print the solutions in the harmonic index solution range + ``HIbeg`` to ``HIend``. Defaults to all harmonic indices (all modes). + + hiend : str + For cyclic symmetry solutions, print the solutions in the harmonic index solution range + ``HIbeg`` to ``HIend``. Defaults to all harmonic indices (all modes). + + matrix : str + Create an APDL Math dense matrix with the name entered on this field (up to 32 characters; for + nomenclature guidelines see `Guidelines for Parameter Names + `_ + ``Matrix`` = blank), no APDL Math matrix is created. + + Notes + ----- + + .. _PRMC_notes: + + :ref:`prmc` prints the modal coordinates (the factors which modes may be multiplied by to obtain + their contribution to the response) at a certain time point (transient analyses) or frequency point + (harmonic analyses). + + The printout contains four columns: the mode number (labelled MODE), the modal frequency (labelled + FREQ), the modal coordinate or mode multiplier (labelled MULT), and the normalized modal coordinate + (labelled NORM). The normalized modal coordinate is the ratio of absolute value of the mode + multiplier divided by the sum of the absolute values of all multipliers listed (at a solution + time/frequency and harmonic index). It may be useful for identifying the dominant modes. Maximum + values of each column are also listed at the end of each report. + + By default, the real part of the modal coordinate values are printed even if the modal coordinates + are complex. + + When ``Matrix`` is specified, an APDL Math dense matrix similar to the one created with the + :ref:`dmat` command is created. If :ref:`prmc` is issued multiple times with the same name entered + on ``Matrix`` or if a matrix with the specified name already exists, the matrix is overwritten. This + matrix contains four to five columns depending on the analysis. The first four columns are the ones + printed by :ref:`prmc`. The fifth column contains the harmonic index for cyclic analysis only. This + matrix can then be used in APDL Math data processing and file handling (See `APDL Math + `_ :ref:`export` + can be issued to export the :ref:`prmc` data to a :file:`.csv` file. + + For transient analyses, a :file:`.rdsp` None file must be available. For harmonic analyses, a + :file:`.rfrq` None file must be available. The content of these files depends on the :ref:`outres` + command settings. Note that the default for mode-superposition transient analysis is to write the + reduced displacement file every 4th substep. For more information, see Command Default in the + :ref:`outres` command description. + + For a cyclic harmonic mode-superposition analysis, use the :ref:`cycfiles` command to identify the + :file:`.rfrq` None and modal :file:`.rst` None files. For other analyses, use the ``FILE`` command + to specify the :file:`.rdsp` or :file:`.rfrq` file. + + This information can also be obtained from the optional :file:`Jobname.mcf` text file (see the + :ref:`trnopt` and :ref:`hropt` commands), and it can be plotted using the :ref:`plmc` command. For + more information on modal coordinates, see `Mode-Superposition Method + `_ + in the `Mechanical APDL Theory Reference + `_ + + **Example Usage** + + .. code:: apdl + + /POST1 + + FILE,,rdsp ! Specify Jobname.rdsp file from a previous MSUP transient analysis ! Print modal + coordinates from the second loadstep and fourth substep PRMC,2,4,,,,,MAT ! also create an APDL Math + matrix called MAT \*EXPORT,MAT,CSV,PRMCFILE.CSV ! Export MAT to a.csv file + """ + command = f"PRMC,{lstep},{sbstep},{timfrq},{kimg},{hibeg},{hiend},{matrix}" + return self.run(command, **kwargs) + + def prnear( + self, + lab: str = "", + opt: str = "", + kcn: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + val7: str = "", + val8: str = "", + val9: str = "", + **kwargs, + ): + r"""Prints the pressure in the near zone exterior to the equivalent source surface. + + Mechanical APDL Command: `PRNEAR `_ + + Parameters + ---------- + lab : str + Print the maximum pressure or sound pressure level: + + * ``POINT`` - at the point (x,y,z) + + * ``SPHERE`` - on the spherical structure + + * ``PATH`` - along the path + + opt : str + * ``PSUM`` - Maximum complex pressure for acoustics. + + * ``PHAS`` - Phase angle of complex pressure for acoustics. + + * ``SPL`` - Sound pressure level for acoustics. + + * ``SPLA`` - A-weighted sound pressure level for acoustics (dBA). + + kcn : str + KCN is the coordinate system reference number. It may be 0 (Cartesian) or any previously defined + local coordinate system number (>10). Defaults to 0. + + val1 : str + For ``Lab`` = POINT: + + * ``VAL1`` - x coordinate value + + * ``VAL2`` - y coordinate value + + * ``VAL3`` - z coordinate value + + * ``VAL4 -, VAL8`` - not used + + * ``VAL9`` - Thickness of model in z direction (defaults to 0). + + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`prnear` computes the pressure for the path data points for the path + currently defined by the :ref:`path` and :ref:`ppath` commands. + + val2 : str + For ``Lab`` = POINT: + + * ``VAL1`` - x coordinate value + + * ``VAL2`` - y coordinate value + + * ``VAL3`` - z coordinate value + + * ``VAL4 -, VAL8`` - not used + + * ``VAL9`` - Thickness of model in z direction (defaults to 0). + + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`prnear` computes the pressure for the path data points for the path + currently defined by the :ref:`path` and :ref:`ppath` commands. + + val3 : str + For ``Lab`` = POINT: + + * ``VAL1`` - x coordinate value + + * ``VAL2`` - y coordinate value + + * ``VAL3`` - z coordinate value + + * ``VAL4 -, VAL8`` - not used + + * ``VAL9`` - Thickness of model in z direction (defaults to 0). + + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`prnear` computes the pressure for the path data points for the path + currently defined by the :ref:`path` and :ref:`ppath` commands. + + val4 : str + For ``Lab`` = POINT: + + * ``VAL1`` - x coordinate value + + * ``VAL2`` - y coordinate value + + * ``VAL3`` - z coordinate value + + * ``VAL4 -, VAL8`` - not used + + * ``VAL9`` - Thickness of model in z direction (defaults to 0). + + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`prnear` computes the pressure for the path data points for the path + currently defined by the :ref:`path` and :ref:`ppath` commands. + + val5 : str + For ``Lab`` = POINT: + + * ``VAL1`` - x coordinate value + + * ``VAL2`` - y coordinate value + + * ``VAL3`` - z coordinate value + + * ``VAL4 -, VAL8`` - not used + + * ``VAL9`` - Thickness of model in z direction (defaults to 0). + + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`prnear` computes the pressure for the path data points for the path + currently defined by the :ref:`path` and :ref:`ppath` commands. + + val6 : str + For ``Lab`` = POINT: + + * ``VAL1`` - x coordinate value + + * ``VAL2`` - y coordinate value + + * ``VAL3`` - z coordinate value + + * ``VAL4 -, VAL8`` - not used + + * ``VAL9`` - Thickness of model in z direction (defaults to 0). + + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`prnear` computes the pressure for the path data points for the path + currently defined by the :ref:`path` and :ref:`ppath` commands. + + val7 : str + For ``Lab`` = POINT: + + * ``VAL1`` - x coordinate value + + * ``VAL2`` - y coordinate value + + * ``VAL3`` - z coordinate value + + * ``VAL4 -, VAL8`` - not used + + * ``VAL9`` - Thickness of model in z direction (defaults to 0). + + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`prnear` computes the pressure for the path data points for the path + currently defined by the :ref:`path` and :ref:`ppath` commands. + + val8 : str + For ``Lab`` = POINT: + + * ``VAL1`` - x coordinate value + + * ``VAL2`` - y coordinate value + + * ``VAL3`` - z coordinate value + + * ``VAL4 -, VAL8`` - not used + + * ``VAL9`` - Thickness of model in z direction (defaults to 0). + + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`prnear` computes the pressure for the path data points for the path + currently defined by the :ref:`path` and :ref:`ppath` commands. + + val9 : str + For ``Lab`` = POINT: + + * ``VAL1`` - x coordinate value + + * ``VAL2`` - y coordinate value + + * ``VAL3`` - z coordinate value + + * ``VAL4 -, VAL8`` - not used + + * ``VAL9`` - Thickness of model in z direction (defaults to 0). + + For ``LAB`` = SPHERE: + + * ``VAL1`` - Radius of spherical surface in spherical coordinate system. + + * ``VAL2`` - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL3`` - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. + + * ``VAL4`` - Number of divisions between the starting and ending φ angles for data + computations. Defaults to 0. + + * ``VAL5`` - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL6`` - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in 3D + and 90 in 2D extension. + + * ``VAL7`` - Number of divisions between the starting and ending θ angles for data + computations. Defaults to 0. + + * ``VAL8`` - Reference rms sound pressure. Defaults to 2x10 :sup:`-5` Pa. + + * ``VAL9`` - Thickness of 2D model extension in z direction (defaults to 0). + + For ``Lab`` = :ref:`path`, :ref:`prnear` computes the pressure for the path data points for the path + currently defined by the :ref:`path` and :ref:`ppath` commands. + + Notes + ----- + + .. _PRNEAR_notes: + + The command uses the equivalent source principle to calculate the pressure in the near zone exterior + to the equivalent source surface (flagged with the Maxwell surface flag in the preprocessor) for one + of the following locations: + + * A point X, Y, Z in the KCN coordinate system + + * A spherical surface in the KCN coordinate system + + * A path defined by the :ref:`path` and :ref:`ppath` commands + + To list the pressure results for a path, use the :ref:`prpath` command. See :ref:`hfsym` command for + the model symmetry. + + To retrieve saved equivalent source data, issue the :ref:`set`, ``Lstep``, ``Sbstep``,,REAL command. + """ + command = f"PRNEAR,{lab},{opt},{kcn},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8},{val9}" + return self.run(command, **kwargs) + + def reswrite(self, fname: str = "", cflag: int | str = "", **kwargs): + r"""Appends results data from the database to a results file. + + Mechanical APDL Command: `RESWRITE `_ + + Parameters + ---------- + fname : str + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. + + The file name extension varies as follows: + + * :file:`.rst` for structural, fluid, or coupled-field analyses + * :file:`.rth` for thermal or electrical analyses + * :file:`.rmg` for magnetic analyses + + cflag : int or str + * ``0`` - The complex results flag is set to 0 in the results file header. This is the default + option. + + * ``1`` - The complex results flag is set to 1 in the results file header. + + Notes + ----- + + .. _RESWRITE_notes: + + The :ref:`reswrite` command appends a data set to the specified file by writing the results data + currently in the database. If the intended results file does not exist, it will be created and will + include the geometry records. The current load step, substep, and time (or frequency) value are + maintained. All data (summable and nonsummable) are written. + + When complex results are appended, ``cFlag`` must be set to 1 so that the header is consistent with + the results written on the file. + + The command is primarily intended for use in a top-down substructuring analysis, where the full + model is resumed and the results data read from the `use pass + `_ + results file ( :ref:`set` ), and subsequently from all substructure `expansion pass + `_ + results files ( :ref:`append` ). The full set of data in memory can then be written out via the + :ref:`reswrite` command to create a complete results file (as though you had run a nonsubstructured + analysis). + + The :ref:`reswrite` command can also be used to write a global results file for a distributed-memory + parallel ( DMP ) solution. This should only be necessary if the :ref:`rescombine` command was used + to combine results from local results files into the database. The :ref:`reswrite` command can then + be used to write the combined results into a new results file. This new results file will + essentially contain the current set of results data for the entire (that is, global) model. + """ + command = f"RESWRITE,{fname},,,,{cflag}" + return self.run(command, **kwargs) + + def rmflvec(self, **kwargs): + r"""Writes eigenvectors of fluid nodes to a file for use in damping parameter extraction. + + Mechanical APDL Command: `RMFLVEC `_ + + Notes + ----- + + .. _RMFLVEC_notes: + + :ref:`rmflvec` extracts the modal information from the modal results file for all nodes specified in + a node component called 'FLUN'. This component should include all nodes which are located at the + fluid-structural interface. Mode shapes, element normal orientation, and a scaling factor are + computed and stored in a file :file:`Jobname.EFL`. For damping parameter extraction, use the + :ref:`dmpext` command macro. See for more information on thin film analyses. + + ``FLUID136`` and ``FLUID138`` are used to model the fluid interface. Both the structural and fluid + element types must be active. The fluid interface nodes must be grouped into a component 'FLUN'. A + results file of the last modal analysis must be available. + """ + command = "RMFLVEC" + return self.run(command, **kwargs) + + def rsplit( + self, + option: str = "", + label: str = "", + name1: str = "", + name2: str = "", + name3: str = "", + name4: str = "", + name5: str = "", + name6: str = "", + name7: str = "", + name8: str = "", + name9: str = "", + name10: str = "", + name11: str = "", + name12: str = "", + name13: str = "", + name14: str = "", + name15: str = "", + name16: str = "", + **kwargs, + ): + r"""Creates one or more results file(s) from the current results file based on subsets of elements. + + Mechanical APDL Command: `RSPLIT `_ + + **Command default:** + Write all data available for the element subset. + + Parameters + ---------- + option : str + Specify which results to include for the subset of elements. + + * ``ALL`` - Write all nodal and element results based on the subset of elements (default). + + * ``EXT`` - Write only the nodal and element results that are on the exterior surface of the element + subset. The results data will be averaged as in PowerGraphics (see :ref:`avres` ) when this results + file is brought into POST1. Only valid for solid elements. + + label : str + Define where the element subset is coming from. + + * ``ALL`` - Use all selected element components ( :ref:`cmsel` ) (default). + + * ``ESEL`` - Use the currently selected ( :ref:`esel` ) set of elements. ``Name1`` defines the + results file name. + + * ``LIST`` - Use ``Name1`` to ``Name16`` to list the element component and/or assembly names (that + contain element components). + + name1 : str + Up to 16 element component and/or assembly names (that contain element components). + + name2 : str + Up to 16 element component and/or assembly names (that contain element components). + + name3 : str + Up to 16 element component and/or assembly names (that contain element components). + + name4 : str + Up to 16 element component and/or assembly names (that contain element components). + + name5 : str + Up to 16 element component and/or assembly names (that contain element components). + + name6 : str + Up to 16 element component and/or assembly names (that contain element components). + + name7 : str + Up to 16 element component and/or assembly names (that contain element components). + + name8 : str + Up to 16 element component and/or assembly names (that contain element components). + + name9 : str + Up to 16 element component and/or assembly names (that contain element components). + + name10 : str + Up to 16 element component and/or assembly names (that contain element components). + + name11 : str + Up to 16 element component and/or assembly names (that contain element components). + + name12 : str + Up to 16 element component and/or assembly names (that contain element components). + + name13 : str + Up to 16 element component and/or assembly names (that contain element components). + + name14 : str + Up to 16 element component and/or assembly names (that contain element components). + + name15 : str + Up to 16 element component and/or assembly names (that contain element components). + + name16 : str + Up to 16 element component and/or assembly names (that contain element components). + + Notes + ----- + Results files will be named based on the element component or assembly name, for example, + :file:`Cname.rst`, except for the ESEL option, for which you must specify the results file name (no + extension) using the ``Name1`` field. Note that the :file:`.rst` filename will be written in all + uppercase letters ( :file:`CNAME.rst` ) (unless using the ESEL option); when you read the file, you + must specify the filename using all uppercase letters (that is, :file:`file`,CNAME). You may repeat + the :ref:`rsplit` command as often as needed. All results sets on the results file are processed. + Use :ref:`aux3` to produce a results file with just a subset of the results sets. + + Use :ref:`inres` to limit the results data written to the results files. + + The subset geometry is also written so that no database file is required to postprocess the subset + results files. You must not resume any database when postprocessing one of these results files. The + input results file must have geometry written to it (that is, do not use :ref:`config`,NORSTGM,1). + + Applied forces and reaction forces are not apportioned if their nodes are shared by multiple element + subsets. Their full values are written to each results file. + + Each results file renumbers its nodes and elements starting with 1. + + This feature is useful when working with large models. For more information on the advantages and + uses of the :ref:`rsplit` command, see `Splitting Large Results Files + `_ in the + `Basic Analysis Guide + `_. + """ + command = f"RSPLIT,{option},{label},{name1},{name2},{name3},{name4},{name5},{name6},{name7},{name8},{name9},{name10},{name11},{name12},{name13},{name14},{name15},{name16}" + return self.run(command, **kwargs) + + def rstmac( + self, + file1: str = "", + lstep1: str = "", + sbstep1: str = "", + file2: str = "", + lstep2: str = "", + sbstep2: str = "", + maclim: str = "", + cname: str = "", + keyprint: int | str = "", + **kwargs, + ): + r"""Calculates modal assurance criterion (MAC/FRF) and matches nodal solutions from two results files or + from one results file and one universal format file. + + Mechanical APDL Command: `RSTMAC `_ + + Parameters + ---------- + file1 : str + File name ( 248 characters maximum) corresponding to the first results file ( :file:`.rst` or + :file:`.rstp` file). If the file name does not contain the extension, it defaults to + :file:`rst`. + + lstep1 : str + Load step number of the results to be read in ``File1``. + + * ``N`` - Reads load step ``N``. Defaults to 1. + + sbstep1 : str + Substep number of the results to be read in ``File1``. + + * ``N`` - Reads substep ``N``. Only valid for MAC. + + * ``All`` - Reads all substeps. This value is the default. + + file2 : str + File name ( 248 characters maximum) corresponding to the second file ( :file:`.rst`, + :file:`.rstp`, or :file:`.unv` file). If the file name does not contain the extension, it + defaults to :file:`rst`. + + lstep2 : str + Load step number of the results to be read in ``File2``. + + * ``N`` - Reads load step ``N``. Defaults to 1. + + sbstep2 : str + Substep number of the results to be read in ``File2``. + + * ``N`` - Reads substep ``N``. Only valid for MAC. + + * ``All`` - Reads all substeps. This value is the default. + + maclim : str + Smallest acceptable criterion value. Must be :math:`equation_not_available` 0 and + :math:`equation_not_available` 1. The default value is 0.90. + + cname : str + Name of the component from the first file ( ``File1`` ). The component must be based on nodes. + If unspecified, all nodes are matched and used for MAC calculations. If a component name is + specified, only nodes included in the specified component are used. Not applicable to node + mapping ( ``Option`` = NODMAP on :ref:`macopt` ). + + keyprint : int or str + Printout options: + + * ``0`` - Printout matched solutions table. This value is the default. + + * ``1`` - Printout matched solutions table and full MAC table. + + * ``2`` - Printout matched solutions table, full MAC table and matched nodes table. + + Notes + ----- + The :ref:`rstmac` command allows the comparison of the solutions from either: + + * Two different results files. Valid only for MAC calculations. + + * One result file ( :file:`.rst` ) and one universal format file ( :file:`.unv` ). + + Either the modal assurance criterion (MAC) or the frequency response function (FRF) correlation + method is used. (For more details see `POST1 - Modal Assurance Criterion (MAC) + `_ + `POST1 - Frequency response function correlation + `_ + + The meshes read from ``File1`` and ``File2`` may be different. The nodes of ``File1`` are matched + with the nodes of ``File2`` based on either node location (default) or node number. The solutions + are compared for the identified pair of matched nodes. The nodes can also be mapped and the + solutions interpolated from ``File1``. See the :ref:`macopt` command for all options. + + Units and coordinate systems must be the same for both models. + + Results may be real or complex; however, if results in ``File1`` have a different type than results + in ``File2``, only the real parts of the solutions are taken into account in MAC calculations. The + analysis type can be arbitrary for MAC while only harmonic analysis is supported for FRF criteria + calculations. + + Non-structural degrees of freedom can be considered. Degrees of freedom can vary between ``File1`` + and ``File2``, but at least one common degree of freedom must exist. + + The solutions read on the results files are not all written to the database; therefore, subsequent + plotting or printing of solutions is not possible. A :ref:`set` command must be issued after the + :ref:`rstmac` command to post-process each solution. + + The corresponding database file ( :file:`.db` ) for :file:`File1` on :ref:`rstmac` must be resumed + before running the command in the following cases: + + * A component ( ``Cname`` ) is used on :ref:`rstmac`. + + * The nodes are mapped ( :ref:`macopt`,NODMAP,YES). + + * The nodes are matched using a relative tolerance ( :ref:`macopt`,RELTOLN). + + :ref:`rstmac` comparison on cyclic symmetry analysis works only if the number of sectors on + ``File1`` and ``File2`` are the same, and the database is saved after the solution is finished. + Also, a comparison cannot be made between cyclic symmetry results and the full 360 degree model + results ( ``File1`` - cyclic solution, ``File2`` - full 360 degree model solution). Comparing cyclic + symmetry solutions written on a selected set of nodes ( :ref:`outres` ) is not supported. + + The modal assurance criterion values can be retrieved as parameters using the :ref:`get` command ( + ``Entity`` = :ref:`rstmac` ). + + FRF correlation is only supported for the comparison of an :file:`.rst` and a :file:`.unv` file. All + substeps are considered for both files to define the frequency domain for criteria calculations. The + printout options consist of listing the table of the criterion results for each frequency in the + frequency domain ( ``KeyPrint`` = 0, 1, or 2) and the matched nodes table ( ``KeyPrint`` = 2). + + **Example Usage** + + .. _RSTMAC_example: + + For a detailed discussion on using RSTMAC with examples see `Comparing Nodal Solutions From Two + Models (RSTMAC) + `_ RSTMAC ) in + the `Basic Analysis Guide + `_. + """ + command = f"RSTMAC,{file1},{lstep1},{sbstep1},{file2},{lstep2},{sbstep2},,{maclim},{cname},{keyprint}" + return self.run(command, **kwargs) + + def slashexpand( + self, + nrepeat1: str = "", + type1: str = "", + method1: str = "", + dx1: str = "", + dy1: str = "", + dz1: str = "", + nrepeat2: str = "", + type2: str = "", + method2: str = "", + dx2: str = "", + dy2: str = "", + dz2: str = "", + nrepeat3: str = "", + type3: str = "", + method3: str = "", + dx3: str = "", + dy3: str = "", + dz3: str = "", + **kwargs, + ): + r"""Allows the creation of a larger graphic display than represented by the actual finite element + analysis model. + + Mechanical APDL Command: `/EXPAND `_ + + Parameters + ---------- + nrepeat1 : str + The number of repetitions required for the element pattern. The default is 0 (no expansion). + + type1 : str + The type of expansion requested. + + * ``RECT`` - Causes a Cartesian transformation of DX, DY, and DZ for each pattern (default). + + * ``POLAR`` - Causes a polar transformation of DR, D-Theta and DZ for each pattern. + + * ``AXIS`` - Causes 2D axisymmetric expansion (that is, rotates a 2D model created in the X-Y plane + about the Y axis to create a 3D model). + + * ``LRECT`` - Causes a Cartesian transformation of DX, DY, and DZ for each pattern about the current + local coordinate system (specified via the :ref:`csys` command). + + * ``LPOLAR`` - Causes a polar transformation of DR, D-Theta, and DZ for each pattern about the local + coordinate system (specified via the :ref:`csys` command). + + method1 : str + The method by which the pattern is repeated. + + * ``FULL`` - Causes a normal repeat of the pattern (default). + + * ``HALF`` - Uses a symmetry transformation for alternate repeats (to produce an image of a complete + circular gear from the image of half a tooth, for example). + + dx1 : str + The Cartesian or polar increments between the repeated patterns. Also determines the reflection + plane. Reflection is about the plane defined by the normal vector (DX, DY, DZ). If you want no + translation, specify a small nonzero value. For a half-image expansion, the increment DX, DY, or + DZ is doubled so that POLAR,HALF,,45 produces full images on 90° centers, and RECT,HALF,,1 + produces full images on 2-meter centers. + + dy1 : str + The Cartesian or polar increments between the repeated patterns. Also determines the reflection + plane. Reflection is about the plane defined by the normal vector (DX, DY, DZ). If you want no + translation, specify a small nonzero value. For a half-image expansion, the increment DX, DY, or + DZ is doubled so that POLAR,HALF,,45 produces full images on 90° centers, and RECT,HALF,,1 + produces full images on 2-meter centers. + + dz1 : str + The Cartesian or polar increments between the repeated patterns. Also determines the reflection + plane. Reflection is about the plane defined by the normal vector (DX, DY, DZ). If you want no + translation, specify a small nonzero value. For a half-image expansion, the increment DX, DY, or + DZ is doubled so that POLAR,HALF,,45 produces full images on 90° centers, and RECT,HALF,,1 + produces full images on 2-meter centers. + + nrepeat2 : str + The number of repetitions required for the element pattern. The default is 0 (no expansion). + + type2 : str + The type of expansion requested. + + * ``RECT`` - Causes a Cartesian transformation of DX, DY, and DZ for each pattern (default). + + * ``POLAR`` - Causes a polar transformation of DR, D-Theta and DZ for each pattern. + + * ``AXIS`` - Causes 2D axisymmetric expansion (that is, rotates a 2D model created in the X-Y plane + about the Y axis to create a 3D model). + + * ``LRECT`` - Causes a Cartesian transformation of DX, DY, and DZ for each pattern about the current + local coordinate system (specified via the :ref:`csys` command). + + * ``LPOLAR`` - Causes a polar transformation of DR, D-Theta, and DZ for each pattern about the local + coordinate system (specified via the :ref:`csys` command). + + method2 : str + The method by which the pattern is repeated. + + * ``FULL`` - Causes a normal repeat of the pattern (default). + + * ``HALF`` - Uses a symmetry transformation for alternate repeats (to produce an image of a complete + circular gear from the image of half a tooth, for example). + + dx2 : str + The Cartesian or polar increments between the repeated patterns. Also determines the reflection + plane. Reflection is about the plane defined by the normal vector (DX, DY, DZ). If you want no + translation, specify a small nonzero value. For a half-image expansion, the increment DX, DY, or + DZ is doubled so that POLAR,HALF,,45 produces full images on 90° centers, and RECT,HALF,,1 + produces full images on 2-meter centers. + + dy2 : str + The Cartesian or polar increments between the repeated patterns. Also determines the reflection + plane. Reflection is about the plane defined by the normal vector (DX, DY, DZ). If you want no + translation, specify a small nonzero value. For a half-image expansion, the increment DX, DY, or + DZ is doubled so that POLAR,HALF,,45 produces full images on 90° centers, and RECT,HALF,,1 + produces full images on 2-meter centers. + + dz2 : str + The Cartesian or polar increments between the repeated patterns. Also determines the reflection + plane. Reflection is about the plane defined by the normal vector (DX, DY, DZ). If you want no + translation, specify a small nonzero value. For a half-image expansion, the increment DX, DY, or + DZ is doubled so that POLAR,HALF,,45 produces full images on 90° centers, and RECT,HALF,,1 + produces full images on 2-meter centers. + + nrepeat3 : str + The number of repetitions required for the element pattern. The default is 0 (no expansion). + + type3 : str + The type of expansion requested. + + * ``RECT`` - Causes a Cartesian transformation of DX, DY, and DZ for each pattern (default). + + * ``POLAR`` - Causes a polar transformation of DR, D-Theta and DZ for each pattern. + + * ``AXIS`` - Causes 2D axisymmetric expansion (that is, rotates a 2D model created in the X-Y plane + about the Y axis to create a 3D model). + + * ``LRECT`` - Causes a Cartesian transformation of DX, DY, and DZ for each pattern about the current + local coordinate system (specified via the :ref:`csys` command). + + * ``LPOLAR`` - Causes a polar transformation of DR, D-Theta, and DZ for each pattern about the local + coordinate system (specified via the :ref:`csys` command). + + method3 : str + The method by which the pattern is repeated. + + * ``FULL`` - Causes a normal repeat of the pattern (default). + + * ``HALF`` - Uses a symmetry transformation for alternate repeats (to produce an image of a complete + circular gear from the image of half a tooth, for example). + + dx3 : str + The Cartesian or polar increments between the repeated patterns. Also determines the reflection + plane. Reflection is about the plane defined by the normal vector (DX, DY, DZ). If you want no + translation, specify a small nonzero value. For a half-image expansion, the increment DX, DY, or + DZ is doubled so that POLAR,HALF,,45 produces full images on 90° centers, and RECT,HALF,,1 + produces full images on 2-meter centers. + + dy3 : str + The Cartesian or polar increments between the repeated patterns. Also determines the reflection + plane. Reflection is about the plane defined by the normal vector (DX, DY, DZ). If you want no + translation, specify a small nonzero value. For a half-image expansion, the increment DX, DY, or + DZ is doubled so that POLAR,HALF,,45 produces full images on 90° centers, and RECT,HALF,,1 + produces full images on 2-meter centers. + + dz3 : str + The Cartesian or polar increments between the repeated patterns. Also determines the reflection + plane. Reflection is about the plane defined by the normal vector (DX, DY, DZ). If you want no + translation, specify a small nonzero value. For a half-image expansion, the increment DX, DY, or + DZ is doubled so that POLAR,HALF,,45 produces full images on 90° centers, and RECT,HALF,,1 + produces full images on 2-meter centers. + + Notes + ----- + + .. _s-EXPAND_notes: + + You can use the :ref:`slashexpand` command to perform up to three symmetry expansions at once (that + is, X, Y, and Z which is equal to going from a 1/8 model to a full model). Polar expansions allow + you to expand a wheel section into a half wheel, then into the half section, and then into the + whole. + + The command displays elements/results when you issue the :ref:`eplot` command or postprocessing + commands. + + The command works on all element and result displays, except as noted below. As the graphic display + is created, the elements (and results) are repeated as many times as necessary, expanding the + geometry and, if necessary, the displacements and stresses. + + Derived results are not supported. + + The :ref:`slashexpand` command has the following limitations: + + * It does not support solid model entities. + + * POLAR, FULL or HALF operations are meaningful only in global cylindrical systems and are + unaffected by the :ref:`rsys` or :ref:`dsys` commands. Cartesian symmetry or unsymmetric + operations also occur about the global Cartesian system. + + * It does not average nodal results across sector boundaries, even for averaged plots (such as those + obtained via the :ref:`plnsol` command). + + * Axisymmetric harmonic element results are not supported for ``Type`` = AXIS. + + The :ref:`slashexpand` command differs significantly from the :ref:`expand` command in several + respects: + + * The uses of :ref:`slashexpand` are of a more general nature, whereas the :ref:`expand` command is + intended primarily to expand modal cyclic symmetry results. + + * :ref:`slashexpand` does not change the database as does the :ref:`expand` command. + + * You cannot print results displayed via :ref:`slashexpand`. + + """ + command = f"/EXPAND,{nrepeat1},{type1},{method1},{dx1},{dy1},{dz1},{nrepeat2},{type2},{method2},{dx2},{dy2},{dz2},{nrepeat3},{type3},{method3},{dx3},{dy3},{dz3}" + return self.run(command, **kwargs) + + def spmwrite( + self, + method: str = "", + nmode: str = "", + inputs: str = "", + inputlabels: str = "", + outputs: str = "", + outputlabels: str = "", + nic: str = "", + velacckey: str = "", + fileformat: int | str = "", + **kwargs, + ): + r"""Calculates the state-space matrices and writes them to the SPM file. + + Mechanical APDL Command: `SPMWRITE `_ + + Parameters + ---------- + method : str + Reduction method for the calculation of the state-space matrices. + + * ``MODAL`` - Method based on modal analysis results from LANB, LANPCG, SNODE, or SUBSP eigensolver + (default). + + nmode : str + Number of modes to be used. Defaults to all modes. + + inputs : str + Definition of the inputs. Defaults to all load vectors on the MODE file. + + If an integer is entered, it specifies the number of load vectors from the MODE file used for + the definition of the inputs. The first ``Inputs`` load vectors are used. + + If ``Inputs`` is an array parameter, the first column is the node number and the second column + is the structural degree of freedom (1=UX, 2=UY, 3=UZ, 4=ROTX, 5=ROTY, 6=ROTZ) indicating input + points. The number of rows in the array parameter is equal to the number of inputs. + + inputlabels : str + Definition of the input labels. Defaults to the load vector numbers or input definition (node + and degree of freedom array parameter), depending on the ``Inputs`` specification. + + If a character array parameter is entered (Type=CHAR in the :ref:`dim` command), each 8 + character string represents an input label. Only valid when ``Inputs`` is an array parameter + + outputs : str + Definition of the outputs. Defaults to the inputs. + + If an array parameter is entered, the first column is the node number and the second column is + the structural degree of freedom (1=UX, 2=UY, 3=UZ, 4=ROTX, 5=ROTY, 6=ROTZ) of the output + points. The number of rows in the array parameter is equal to the number of outputs. + + outputlabels : str + Definition of the output labels. Defaults to the output definition (node and degree of freedom) + if used, else defaults to the ``InputLabels``. + + If a character array parameter is entered (Type=CHAR in the \*DIM command), each 8 character + string represents an output label. + + nic : str + Load vector on the ``MODE`` file used for the calculation of the initial conditions. Defaults to + no initial condition. + + velacckey : str + Output velocities and accelerations key. + + * ``OFF`` - Output displacements only (default). + + * ``ON`` - Output displacements, velocities and accelerations. + + fileformat : int or str + The format of the SPM file. + + * ``0`` - Dense format. + + * ``1`` - Matrix Market Exchange format (non-zero terms only). + + * ``2`` - Twin Builder SML format without reference (default). + + * ``3`` - Twin Builder SML format with common reference. + + * ``4`` - Twin Builder SML format with independent references. + + Notes + ----- + + .. _SPMWRITE_notes: + + The SPMWRITE generates the file :file:`Jobname.SPM` containing the state-space matrices and other + information. + + The following applies to the SML formats (FileFormat = 2, 3, and 4): + + * For conservative systems where the outputs are equal to the inputs ( ``Outputs`` is left blank): + + * The labels for the inputs ( ``InputLabels`` ) are required. + + * The ``Inputs`` must use the array parameter option so that the input degrees of freedom (DOFs) are + known. + + * For non-conservative systems where the outputs are not equal to the inputs: + + * The labels for the outputs ( ``OutputLabels`` ) are required. + + * The file formats with references ( ``FileFormat`` = 3 and 4) do not apply. + + * Velocity and acceleration results are not included in the state-space matrices calculation + (VelAccKey = OFF) + + * File format with common reference (FileFormat = 3) does not apply if the inputs are based on DOFs + of a different nature. All input DOFs must be either all rotational or all translational and not a + mix of the two. + + * A graphics file ( :file:`Jobname_SPM.PNG` ) is generated. It contains an element plot of the + model. + + For more details about the reduction method and the generation of the state-space matrices, see + `Reduced-Order Modeling for State-Space Matrices Export + `_ + + For examples of the command usage, see `State-Space Matrices Export + `_ + """ + command = f"SPMWRITE,{method},{nmode},{inputs},{inputlabels},{outputs},{outputlabels},{nic},{velacckey},{fileformat}" + return self.run(command, **kwargs) + + def spoint( + self, + node: str = "", + x: str = "", + y: str = "", + z: str = "", + inertiakey: str = "", + **kwargs, + ): + r"""Defines a point for force/moment summations or inertia calculation + + Mechanical APDL Command: `SPOINT `_ + + Parameters + ---------- + node : str + Node number of the desired point. If zero, use ``X``, ``Y``, ``Z`` to describe point. + + x : str + Global Cartesian coordinates of the desired summation point. Used if ``NODE`` is 0. Defaults to + (0,0,0). + + y : str + Global Cartesian coordinates of the desired summation point. Used if ``NODE`` is 0. Defaults to + (0,0,0). + + z : str + Global Cartesian coordinates of the desired summation point. Used if ``NODE`` is 0. Defaults to + (0,0,0). + + inertiakey : str + Inertia key: + + * ``OFF`` - Point or node is used for the force/moment summations (default). + + * ``ON`` - Point or node is used for the calculation of total inertia. + + Notes + ----- + + .. _SPOINT_notes: + + By default ( ``InertiaKey`` = OFF), defines a point (any point other than the origin) about which + the tabular moment summations are computed. If force summations are desired in other than the global + Cartesian directions, a node number must be specified on the ``NODE`` field, and the desired + coordinate system must be activated with :ref:`rsys`. The command must be issued in the :ref:`post1` + module. + + When the inertia key is activated ( ``InertiaKey`` = ON), the total inertia printed in the precise + mass summary is calculated with respect to the point or node in the global Cartesian system. In this + case, the command must be issued during the first load step in the :ref:`slashsolu` module. + """ + command = f"SPOINT,{node},{x},{y},{z},{inertiakey}" + return self.run(command, **kwargs) + + def vtkwrite(self, fname: str = "", item: str = "", **kwargs): + r"""Writes the current displacement data to a :file:`.VTK` file. + + Mechanical APDL Command: `VTKWRITE `_ + + 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. Default: :file:`Jobname`. + + item : str + The output item (U, S, EPEL, or EPPL) to write to the file. Default: U. + + Notes + ----- + + .. _VTKWRITE_notes: + + Writes the requested data currently in memory ( :ref:`set` ) to a :file:`.VTK` file that can be read + by any VTK-compatible viewer (such as ParaView). + + Only data associated with the currently selected element set is written. + + Support is available for the displacements of 8-node brick elements (such as ``SOLID185`` ) only. If + your model uses multiple element types, select only the 8-node elements before issuing + :ref:`vtkwrite`. + """ + command = f"VTKWRITE,{fname},{item}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1/status.py b/src/ansys/mapdl/core/_commands/post1/status.py new file mode 100644 index 0000000000..ed8598e164 --- /dev/null +++ b/src/ansys/mapdl/core/_commands/post1/status.py @@ -0,0 +1,216 @@ +# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + + +class Status: + + def calc(self, **kwargs): + r"""Specifies "Calculation settings" as the subsequent status topic. + + Mechanical APDL Command: `CALC `_ + + Notes + ----- + + .. _CALC_notes: + + This is a status ( :ref:`stat` ) topic command. Status topic commands are generated by the GUI and + will appear in the log file ( :file:`Jobname.LOG` ) if status is requested for some items under + Utility Menu> List> Status. This command will be immediately followed by a :ref:`stat` command, + which will report the status for the specified topic. + + If entered directly into the program, the :ref:`stat` command should immediately follow this + command. + """ + command = "CALC" + return self.run(command, **kwargs) + + def datadef(self, **kwargs): + r"""Specifies "Directly defined data status" as the subsequent status topic. + + Mechanical APDL Command: `DATADEF `_ + + Notes + ----- + + .. _DATADEF_notes: + + This is a status ( :ref:`stat` ) topic command. Status topic commands are generated by the GUI and + will appear in the log file ( :file:`Jobname.LOG` ) if status is requested for some items under + Utility Menu> List> Status. This command will be immediately followed by a :ref:`stat` command, + which will report the status for the specified topic. + + If entered directly into the program, the :ref:`stat` command should immediately follow this + command. + """ + command = "DATADEF" + return self.run(command, **kwargs) + + def define(self, **kwargs): + r"""Specifies "Data definition settings" as the subsequent status topic. + + Mechanical APDL Command: `DEFINE `_ + + Notes + ----- + + .. _DEFINE_notes: + + This is a status ( :ref:`stat` ) topic command. Status topic commands are generated by the GUI and + will appear in the log file ( :file:`Jobname.LOG` ) if status is requested for some items under + Utility Menu> List> Status. This command will be immediately followed by a :ref:`stat` command, + which will report the status for the specified topic. + + If entered directly into the program, the :ref:`stat` command should immediately follow this + command. + """ + command = "DEFINE" + return self.run(command, **kwargs) + + def display(self, **kwargs): + r"""Specifies "Display settings" as the subsequent status topic. + + Mechanical APDL Command: `DISPLAY `_ + + Notes + ----- + + .. _DISPLAY_notes: + + This is a status ( :ref:`stat` ) topic command. Status topic commands are generated by the GUI and + will appear in the log file ( :file:`Jobname.LOG` ) if status is requested for some items under + Utility Menu> List> Status. This command will be immediately followed by a :ref:`stat` command, + which will report the status for the specified topic. + + If entered directly into the program, the :ref:`stat` command should immediately follow this + command. + """ + command = "DISPLAY" + return self.run(command, **kwargs) + + def lccalc(self, **kwargs): + r"""Specifies "Load case settings" as the subsequent status topic. + + Mechanical APDL Command: `LCCALC `_ + + Notes + ----- + + .. _LCCALC_notes: + + This is a status ( :ref:`stat` ) topic command. Status topic commands are generated by the GUI and + will appear in the log file ( :file:`Jobname.LOG` ) if status is requested for some items under + Utility Menu> List> Status. This command will be immediately followed by a :ref:`stat` command, + which will report the status for the specified topic. + + If entered directly into the program, the :ref:`stat` command should immediately follow this + command. + + This command is also valid for `rezoning + `_. + """ + command = "LCCALC" + return self.run(command, **kwargs) + + def point(self, **kwargs): + r"""Specifies "Point flow tracing settings" as the subsequent status topic. + + Mechanical APDL Command: `POINT `_ + + Notes + ----- + + .. _POINT_notes: + + This is a status ( :ref:`stat` ) topic command. Status topic commands are generated by the GUI and + will appear in the log file ( :file:`Jobname.LOG` ) if status is requested for some items under + Utility Menu> List> Status. This command will be immediately followed by a :ref:`stat` command, + which will report the status for the specified topic. + + If entered directly into the program, the :ref:`stat` command should immediately follow this + command. + """ + command = "POINT" + return self.run(command, **kwargs) + + def print(self, **kwargs): + r"""Specifies "Print settings" as the subsequent status topic. + + Mechanical APDL Command: `PRINT `_ + + Notes + ----- + + .. _PRINT_notes: + + This is a status ( :ref:`stat` ) topic command. Status topic commands are generated by the GUI and + will appear in the log file ( :file:`Jobname.LOG` ) if status is requested for some items under + Utility Menu> List> Status. This command will be immediately followed by a :ref:`stat` command, + which will report the status for the specified topic. + + If entered directly into the program, the :ref:`stat` command should immediately follow this + command. + """ + command = "PRINT" + return self.run(command, **kwargs) + + def sort(self, **kwargs): + r"""Specifies "Sort settings" as the subsequent status topic. + + Mechanical APDL Command: `SORT `_ + + Notes + ----- + + .. _SORT_notes: + + This is a status ( :ref:`stat` ) topic command. Status topic commands are generated by the GUI and + will appear in the log file ( :file:`Jobname.LOG` ) if status is requested for some items under + Utility Menu> List> Status. This command will be immediately followed by a :ref:`stat` command, + which will report the status for the specified topic. + + If entered directly into the program, the :ref:`stat` command should immediately follow this + command. + """ + command = "SORT" + return self.run(command, **kwargs) + + def spec(self, **kwargs): + r"""Specifies "Miscellaneous specifications" as the subsequent status topic. + + Mechanical APDL Command: `SPEC `_ + + Notes + ----- + + .. _SPEC_notes: + + This is a status ( :ref:`stat` ) topic command. Status topic commands are generated by the GUI and + will appear in the log file ( :file:`Jobname.LOG` ) if status is requested for some items under + Utility Menu> List> Status. This command will be immediately followed by a :ref:`stat` command, + which will report the status for the specified topic. + + If entered directly into the program, the :ref:`stat` command should immediately follow this + command. + """ + command = "SPEC" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1/surface_operations.py b/src/ansys/mapdl/core/_commands/post1/surface_operations.py new file mode 100644 index 0000000000..c4302fea49 --- /dev/null +++ b/src/ansys/mapdl/core/_commands/post1/surface_operations.py @@ -0,0 +1,561 @@ +# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + + +class SurfaceOperations: + + def sucalc( + self, + rsetname: str = "", + lab1: str = "", + oper: str = "", + lab2: str = "", + fact1: str = "", + fact2: str = "", + const: str = "", + **kwargs, + ): + r"""Create new result data by operating on two existing result data sets on a given surface. + + Mechanical APDL Command: `SUCALC `_ + + Parameters + ---------- + rsetname : str + Eight character name for new result data. + + lab1 : str + First result data upon which to operate. + + oper : str + Mathematical operation to perform. + + * ``ADD`` - ( ``lab1`` + ``lab2`` + ``const`` ) + + * ``SUB`` - ( ``lab1`` - ``lab2`` + ``const`` ) + + * ``MULT`` - ( ``lab1`` \* ``lab2`` + ``const`` ) + + * ``DIV`` - ( ``lab1`` / ``lab2`` + ``const`` ) + + * ``EXP`` - ( ``lab1`` ^ ``fact1`` + ``lab2`` ^ ``fact2`` + ``const`` ) + + * ``COS`` - (cos ( ``lab1`` ) + ``const`` ) + + * ``SIN`` - (sin ( ``lab1`` ) + ``const`` ) + + * ``ACOS`` - (acos ( ``lab1`` ) + ``const`` ) + + * ``ASIN`` - (asin ( ``lab1`` ) + ``const`` ) + + * ``ATAN`` - (atan ( ``lab1`` ) + ``const`` ) + + * ``ATA2`` - (atan2 ( ``lab1`` / ``lab2`` ) + ``const`` ) + + * ``LOG`` - (log ( ``lab1`` ) + ``const`` ) + + * ``ABS`` - (abs ( ``lab1`` ) + ``const`` ) + + * ``ZERO`` - (0 + ``const`` ) + + lab2 : str + Second result data upon which to operate. + + fact1 : str + First scaling factor (for EXP option only). + + fact2 : str + Second scaling factor (for EXP option only). + + const : str + Constant added to the values in the resulting data. + """ + command = f"SUCALC,{rsetname},{lab1},{oper},{lab2},{fact1},{fact2},{const}" + return self.run(command, **kwargs) + + def sucr( + self, + surfname: str = "", + surftype: str = "", + nrefine: str = "", + radius: str = "", + tolout: str = "", + **kwargs, + ): + r"""Create a surface. + + Mechanical APDL Command: `SUCR `_ + + Parameters + ---------- + surfname : str + Eight character surface name. + + surftype : str + Surface type. + + * ``CPLANE`` - Surface is defined by the cutting plane in window one (controlled by the working + plane (/CPLANE,1), NOT the view settings (/CPLANE,0)). + + * ``SPHERE`` - Surface is defined by a spherical surface centered about the working plane origin. + + * ``INFC`` - Surface is defined by a cylindrical surface centered about the working plane origin and + extending indefinitely in the positive and negative Z directions. + + nrefine : str + Refinement level. + + * ``For SurfType = CPLANE`` - The refinement level of the surface mesh. This will be an integer + between 0 and 3 (default = 0). See Notes below. + + * ``For SurfType = SPHERE`` - The number of divisions along a 90° arc (minimum = 9). The default is + 9. + + * ``For SurfType = INFC`` - The number of divisions along a 90° arc (minimum = 9). The default is 9. + + radius : str + Appropriate radius value (for INFC or SPHERE). + + tolout : str + Tolerance value for inclusion of element facets within a prescribed volume. (for INFC) + + Notes + ----- + + .. _SUCR_notes: + + This command creates a new surface and stores the following data for that surface: + + * GCX, GCY, GCZ - global Cartesian coordinates at each point on the surface. + * NORMX, NORMY, NORMZ - components of the unit normal at each point on the surface. + * DA - the contributory area of each point. + + For ``SurfType`` = CPLANE, ``nRefine`` refers to the number of points that define the surface. An + ``nRefine`` value of zero is used for points where the element face intersects the cutting plane. + + If ``SurfType`` = CPLANE and ``nRefine`` = 0, the points reside at the section cuts where the + element intersects the cutting plane. Increasing ``nRefine`` from 0 to 1 will subdivide each surface + facet into 4 subfacets, and increase the number of points at which results can be interpolated. + + For ``SurfType`` = CPLANE, the setting from the :ref:`efacet` command will affect the creation of + surface facets and the quality of the fit of the surface in the model. :ref:`sucr` employs geometry + data from PowerGraphics to aid in determining where the surface intersects the model. If + :ref:`efacet`,1 is in effect when the :ref:`sucr` command is issued, then the curvature of high + order elements (that is, elements with midside nodes) will be ignored. If your model contains high + order elements, you can see a better fit for your surface if /EFACET,2 is in effect when the + :ref:`sucr` command is issued. Currently, the :ref:`sucr` command interprets :ref:`efacet`,4 to + mean :ref:`efacet`,2. + + For ``SurfType`` = INFC, a default tolerance of 0.01 will be applied to include the vertices of any + facets that fall out of the cylinder definition. This tolerance increases the facet size by one + percent to check for inclusion. Excluding facets under such a small tolerance may yield unacceptable + (aesthetically) results. Increasing the tolerance by a larger amount (0.1 or 10%) will sometimes + yield smother edges along the surface you create. + + + """ + command = f"SUCR,{surfname},{surftype},{nrefine},{radius},,,{tolout}" + return self.run(command, **kwargs) + + def sudel(self, surfname: str = "", **kwargs): + r"""Delete geometry information as well as any mapped results for specified surface. + + Mechanical APDL Command: `SUDEL `_ + + Parameters + ---------- + surfname : str + Eight character surface name. + + ``SurfName`` = ALL will delete all surface geometry and result infromation. + """ + command = f"SUDEL,{surfname}" + return self.run(command, **kwargs) + + def sueval(self, parm: str = "", lab1: str = "", oper: str = "", **kwargs): + r"""Perform operations on a mapped item and store result in a scalar parameter. + + Mechanical APDL Command: `SUEVAL `_ + + Parameters + ---------- + parm : str + APDL parameter name. + + lab1 : str + Eight character set name for the first set used in calculation. + + oper : str + Operation to perform: + + * ``SUM`` - Sum of ``lab1`` result values. + + * ``INTG`` - Integral of ``lab1`` over surface. + + * ``AVG`` - Area-weighted average of a result item [Σ( ``lab1`` \*DA) / Σ(DA)] + + Notes + ----- + + .. _SUEVAL_notes: + + The result of this operation is a scalar APDL parameter value. If multiple surfaces are selected + when this command is issued, then the operation is carried out on each surface individually and the + parameter reperesents the culmulative value of the operation on all selected surfaces. + """ + command = f"SUEVAL,{parm},{lab1},{oper}" + return self.run(command, **kwargs) + + def suget( + self, + surfname: str = "", + rsetname: str = "", + parm: str = "", + geom: str = "", + **kwargs, + ): + r"""Moves surface geometry and mapped results to an array parameter. + + Mechanical APDL Command: `SUGET `_ + + Parameters + ---------- + surfname : str + Eight character surface name. + + rsetname : str + Eight character result name. + + parm : str + APDL array parameter name (up to 32 characters). + + geom : str + Switch controlling how data is written. + + * ``ON (or 1 or YES)`` - Writes geometry data and interpolated results information to the parameter. + + * ``OFF (or 0 or NO)`` - Writes only interpolated results information to the parameter. (Default) + + Notes + ----- + + .. _SUGET_notes: + + For ``Geom`` = OFF (or 0 or NO), only results information is written to this parameter. + + For ``Geom`` = ON (or 1 or YES), both geometry data and results information are written to this + parameter. Geometry data includes 7 data items: (GCX, GCY, GCZ, NORMX, NORMY, NORMZ, and DA). + Results information is then written to the 8th column of the parameter. SetNames of GCX, GCY, GCZ, + NORMX, NORMY, NORMZ, and DA are predefined and computed when :ref:`sucr` is issued. + """ + command = f"SUGET,{surfname},{rsetname},{parm},{geom}" + return self.run(command, **kwargs) + + def sumap(self, rsetname: str = "", item: str = "", comp: str = "", **kwargs): + r"""Map results onto selected surface(s). + + Mechanical APDL Command: `SUMAP `_ + + Parameters + ---------- + rsetname : str + Eight-character name for the result being mapped. + + item : str + Label identifying the item. + + Valid item labels are defined via :ref:`plnsol`. Some items also require a component label. + + If ``Item`` = CLEAR, the specified result set is deleted from all selected surfaces + + comp : str + Component label of item (if required). + + Notes + ----- + + .. _SUMAP_notes: + + The :ref:`sumap` command maps results in the current coordinate system ( :ref:`rsys` ) using the + selected set of elements. + + The command interpolates and stores the results data on to each of the selected surfaces. + + :ref:`sumap`,ALL,CLEAR deletes all results sets from all selected surfaces. + """ + command = f"SUMAP,{rsetname},{item},{comp}" + return self.run(command, **kwargs) + + def supl( + self, surfname: str = "", rsetname: str = "", kwire: int | str = "", **kwargs + ): + r"""Plot result data on all selected surfaces or on a specified surface. + + Mechanical APDL Command: `SUPL `_ + + Parameters + ---------- + surfname : str + Eight-character surface name. ALL plots all selected surfaces. + + rsetname : str + Eight-character result name. + + kwire : int or str + Plot in context of model. + + * ``0`` - Plot results without the outline of selected elements. + + * ``1`` - Plot results with the outline of selected elements. + + Notes + ----- + + .. _SUPL_notes: + + If ``RSetName`` is not specified, the surface geometry is plotted. If the Setname portion of the + argument is a vector prefix (that is, if result sets of name SetNameX, SetNameY, and SetNameZ + exist), Mechanical APDL plots the vectors on the surface as arrows. For example, + :ref:`supl`,ALL,NORM plots + the surface normals as vectors on all selected surfaces, as NORMX, NORMY, and NORMZ are predefined + geometry items. + """ + command = f"SUPL,{surfname},{rsetname},{kwire}" + return self.run(command, **kwargs) + + def supr(self, surfname: str = "", rsetname: str = "", **kwargs): + r"""Print global status, geometry information and/or result information. + + Mechanical APDL Command: `SUPR `_ + + Parameters + ---------- + surfname : str + Eight character surface name. If ``SurfName`` = ALL, repeat printout for all selected surfaces. + + rsetname : str + Eight character result set name. + + Notes + ----- + + .. _SUPR_notes: + + When no arguments are specified, :ref:`supr` generates a global status summary of all defined + surfaces. If only ``SurfName`` is specified, the geometry information for that surface is printed. + If both ``SurfName`` and ``RSetName`` are specified, the value of the results set at each point, in + addition to the geometry information, is printed. + """ + command = f"SUPR,{surfname},{rsetname}" + return self.run(command, **kwargs) + + def suresu(self, fname: str = "", fext: str = "", fdir: str = "", **kwargs): + r"""Read a set of surface definitions and result items from a file and make them the current set. + + Mechanical APDL Command: `SURESU `_ + + Parameters + ---------- + + fname : str + Eight character name. + + fext : str + Extension name. + + fdir : str + Optional path specification. + + Notes + ----- + + .. _SURESU_notes: + + Reading (and therefore resuming) surface and result definitions from a file overwritea any existing + surface definitions. + + Reading surfaces back into the postprocessor ( :ref:`post1` ) does not insure that the surfaces (and + their results) are appropriate for the model currently residing in :ref:`post1`. + """ + command = f"SURESU,,{fname},{fext},{fdir}" + return self.run(command, **kwargs) + + def susave( + self, lab: str = "", fname: str = "", fext: str = "", fdir: str = "", **kwargs + ): + r"""Saves surface definitions to a file. + + Mechanical APDL Command: `SUSAVE `_ + + Parameters + ---------- + lab : str + Eight-character surface name. + + If ``Lab`` = ALL (default), then all surfaces are saved to the file. + + If ``Lab`` = S, only currently selected surfaces are saved to the file. + + fname : str + File name and directory path (248 character maximum, including directory). If you do not specify + a directory path, the default is your working directory and you can use all 248 characters for + the file name. The file name defaults to the jobname. + + fext : str + File name extension (eight-character maximum). The extension defaults to "surf". + + fdir : str + Optional path specification. + + Notes + ----- + + .. _SUSAVE_notes: + + The :ref:`susave` command saves surface definitions (geometry information)--and any result items + mapped onto the surfaces--to a file. + + Issuing the :ref:`susave` command has no effect on the database. The database remains unchanged. + + Subsequent executions of the :ref:`susave` command overwrite previous data in the file. + + To read the contents of the file created via the :ref:`susave` command, issue the :ref:`suresu` + command. + """ + command = f"SUSAVE,{lab},{fname},{fext},{fdir}" + return self.run(command, **kwargs) + + def susel( + self, + type_: str = "", + name1: str = "", + name2: str = "", + name3: str = "", + name4: str = "", + name5: str = "", + name6: str = "", + name7: str = "", + name8: str = "", + **kwargs, + ): + r"""Selects a subset of surfaces + + Mechanical APDL Command: `SUSEL `_ + + Parameters + ---------- + type_ : str + Label identifying the type of select: + + * ``S`` - Selects a new set (default). + + * ``R`` - Reselects a set from the current set. + + * ``A`` - Additionally selects a set and extends the current set. + + * ``U`` - Unselects a set from the current set. + + * ``ALL`` - Also selects all surfaces. + + * ``NONE`` - Unselects all surfaces. + + name1 : str + Eight character surface names + + name2 : str + Eight character surface names + + name3 : str + Eight character surface names + + name4 : str + Eight character surface names + + name5 : str + Eight character surface names + + name6 : str + Eight character surface names + + name7 : str + Eight character surface names + + name8 : str + Eight character surface names + + Notes + ----- + + .. _SUSEL_notes: + + The selected set of surfaces is used in the following operations: :ref:`sumap`, :ref:`sudel`, + :ref:`sucalc`, :ref:`sueval`, and :ref:`suvect`. + """ + command = f"SUSEL,{type_},{name1},{name2},{name3},{name4},{name5},{name6},{name7},{name8}" + return self.run(command, **kwargs) + + def suvect( + self, + rsetname: str = "", + lab1: str = "", + oper: str = "", + lab2: str = "", + offset: str = "", + **kwargs, + ): + r"""Create new result data by operating on two existing result vectors on a given surface. + + Mechanical APDL Command: `SUVECT `_ + + Parameters + ---------- + rsetname : str + Eight character name of the result data output. There will be one or three ``RSetName`` values + depending on the operation specified in ``Oper``. + + lab1 : str + Eight character name of the mapped data that forms vector 1. Specified sets must exist on all + selected surfaces for this operation to take place. The names NORM and GC will be reserved for + normals and for global (x, y, z). + + oper : str + * ``DOT`` - Computes dot product between ``lab1`` and ``lab2`` vectors. The result is a scalar + parameter ( ``RSetName`` ) and each value within the set can be modified (incremented) via + ``Offset``. + + * ``CROSS`` - Computes cross product between ``lab1`` and ``lab2`` vectors. Each X, Y, Z value in + the result can be modified (incremented) via ``Offset``. + + * ``SMULT`` - Scales (lab1x, lab1y, lab1z) vector by scalar ``lab2``. Each X,Y,Z value in the result + can be modified (incremented) via ``Offset``. + + lab2 : str + Eight character name of the mapped data that forms vector 2. Sets with names Lab2X, Lab2Y, and + Lab2Z must exist on all selected surfaces for operation to take place. For ``Oper`` = SMULT a + scalar value or another predefined scalar item (for example, DA) can be supplied. + + offset : str + An offset value to be applied to the resultant ``RSetName``. One value is specified for ``Oper`` + = DOT, and three values are specified for ``Oper`` = SMULT. + """ + command = f"SUVECT,{rsetname},{lab1},{oper},{lab2},{offset}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1/trace_points.py b/src/ansys/mapdl/core/_commands/post1/trace_points.py new file mode 100644 index 0000000000..fa928d1437 --- /dev/null +++ b/src/ansys/mapdl/core/_commands/post1/trace_points.py @@ -0,0 +1,295 @@ +# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + + +class TracePoints: + + def pltrac( + self, + analopt: str = "", + item: str = "", + comp: str = "", + trpnum: str = "", + name: str = "", + mxloop: str = "", + toler: str = "", + escl: str = "", + mscl: str = "", + **kwargs, + ): + r"""Displays a charged particle trace on an element display. + + Mechanical APDL Command: `PLTRAC `_ + + Parameters + ---------- + analopt : str + Analysis option + + * ``ELEC`` - Particle trace in electric field + + * ``MAGN`` - Particle trace in magnetic field + + * ``EMAG`` - Particle trace in presence of both electric and magnetic fields (default) + + item : str + Label identifying the item to be contoured. Valid item labels are shown in :ref:`pltrac_tab_1` + below. Some items also require a component label. If ``Item`` is blank, display only the path + trajectory. + + comp : str + Component of the item (if required). Valid component labels are shown in :ref:`pltrac_tab_1` + below. + + trpnum : str + Trace point number for storing trajectory data for use with :ref:`path` logic. Defaults to 0 (no + trajectory path data is stored for further processing with :ref:`path` logic). + + name : str + Name of prefix of array variable. Defaults to TRAC. ``Name`` POIN stores trajectory path points + for trace point number ``TRPNum``. If ``Analopt`` = ELEC, MAGN, or EMAG, two additional array + parameters, ``Name`` DATA and ``Name`` LABL, store trajectory path data and labels for the same + ``TRPNum``. + + mxloop : str + Maximum number of loops traced by a particle. Defaults to 1000. + + toler : str + Length tolerance used for particle trajectory geometry calculation. Valid for ``Analopt`` = + ELEC, MAGN, or EMAG. If particle trace appears to terminate inside an element, adjusting the + length tolerance may be necessary. Defaults to 1.0 x 10 :sup:`-8`. + + escl : str + Electric field scale factor. Setting this scale factor affects only the tracing, not the field + solution results. A negative factor corresponds to the opposite vector direction. Valid only for + ``Analopt`` = ELEC or EMAG. Defaults to 1. + + mscl : str + Magnetic field scale factor. Setting this scale factor affects only the tracing, not the field + solution results. A negative factor corresponds to the opposite vector direction. Valid only for + ``Analopt`` = MAGN or EMAG. Defaults to 1. + + Notes + ----- + + .. _PLTRAC_notes: + + For a specified item, the variation of the item is displayed along the particle trace as a color- + contoured ribbon. The :ref:`trpoin` command must be used to define a point on the trajectory path. + Multiple traces may be displayed simultaneously by defining multiple trace points. Issue the + :ref:`trplis` command to list the current tracing points. Issue the :ref:`trpdel` command to delete + tracing points defined earlier. Use the :ref:`paput` command with the POIN option to retrieve the + particle trajectory points as path points. + + The model must be 3D for the ELEC, MAGN, and EMAG analysis options. + + Three array parameters are created at the time of the particle trace: TRACPOIN, TRACDATA and + TRACLABL. These array parameters can be used to put the particle velocity and the elapsed time into + path form. The procedure to put the arrays into a path named PATHNAME is as follows: + + .. code:: apdl + + *get,npts,PARM,TRACPOIN,DIM,x + PATH,PATHNAME,npts,9,1 + PAPUT,TRACPOIN,POINTS + PAPUT,TRACDATA,TABLES + PAPUT,TRACLABL,LABELS + PRPATH,S,T_TRACE,VX_TRACE,VY_TRACE,VZ_TRACE,VS_TRACE + + If working in the GUI, use the "All information" option to retrieve information from all three + arrays at once. + + .. _pltrac_tab_1: + + PLTRAC - Valid Item and Component Labels + **************************************** + + .. flat-table:: + :header-rows: 1 + + * - Item + - Comp + - Description + * - **Valid item labels for** ``Analopt`` = ELEC nodal results are: + * - VOLT + - + - Electric potential. + * - **Valid item labels for** ``Analopt`` = MAGN or EMAG nodal results are: + * - None + - + - Color contour displayed. + + See the `Basic Analysis Guide + `_ for more + information on charged particle traces. See `Animation + `_ in the + `Basic Analysis Guide + `_ for information + on particle trace animation. + """ + command = f"PLTRAC,{analopt},{item},{comp},{trpnum},{name},{mxloop},{toler},,{escl},{mscl}" + return self.run(command, **kwargs) + + def trpdel(self, ntrp1: str = "", ntrp2: str = "", trpinc: str = "", **kwargs): + r"""Deletes charged particle trace points. + + Mechanical APDL Command: `TRPDEL `_ + + Parameters + ---------- + ntrp1 : str + Delete points from ``NTRP1`` to ``NTRP2`` (defaults to ``NTRP1`` ) in steps of ``TRPINC`` + (defaults to 1). If ``NTRP1`` = ALL, ``NTRP2`` and ``TRPINC`` are ignored and all trace points + are deleted. If ``NTRP1`` = P, graphical picking is enabled and all remaining command fields are + ignored (valid only in the GUI). + + ntrp2 : str + Delete points from ``NTRP1`` to ``NTRP2`` (defaults to ``NTRP1`` ) in steps of ``TRPINC`` + (defaults to 1). If ``NTRP1`` = ALL, ``NTRP2`` and ``TRPINC`` are ignored and all trace points + are deleted. If ``NTRP1`` = P, graphical picking is enabled and all remaining command fields are + ignored (valid only in the GUI). + + trpinc : str + Delete points from ``NTRP1`` to ``NTRP2`` (defaults to ``NTRP1`` ) in steps of ``TRPINC`` + (defaults to 1). If ``NTRP1`` = ALL, ``NTRP2`` and ``TRPINC`` are ignored and all trace points + are deleted. If ``NTRP1`` = P, graphical picking is enabled and all remaining command fields are + ignored (valid only in the GUI). + + Notes + ----- + + .. _TRPDEL_notes: + + Deletes charged particle trace points defined with the :ref:`trpoin` command. + """ + command = f"TRPDEL,{ntrp1},{ntrp2},{trpinc}" + return self.run(command, **kwargs) + + def trplis( + self, + ntrp1: str = "", + ntrp2: str = "", + trpinc: str = "", + opt: str = "", + **kwargs, + ): + r"""Lists charged particle trace points. + + Mechanical APDL Command: `TRPLIS `_ + + Parameters + ---------- + ntrp1 : str + List points from ``NTRP1`` to ``NTRP2`` (defaults to ``NTRP1`` ) in steps of ``TRPINC`` + (defaults to 1). If ``NTRP1`` = ALL, ``NTRP2`` and ``TRPINC`` are ignored and all trace points + are listed. If ``NTRP1`` = P, graphical picking is enabled and all remaining command fields are + ignored (valid only in the GUI). + + ntrp2 : str + List points from ``NTRP1`` to ``NTRP2`` (defaults to ``NTRP1`` ) in steps of ``TRPINC`` + (defaults to 1). If ``NTRP1`` = ALL, ``NTRP2`` and ``TRPINC`` are ignored and all trace points + are listed. If ``NTRP1`` = P, graphical picking is enabled and all remaining command fields are + ignored (valid only in the GUI). + + trpinc : str + List points from ``NTRP1`` to ``NTRP2`` (defaults to ``NTRP1`` ) in steps of ``TRPINC`` + (defaults to 1). If ``NTRP1`` = ALL, ``NTRP2`` and ``TRPINC`` are ignored and all trace points + are listed. If ``NTRP1`` = P, graphical picking is enabled and all remaining command fields are + ignored (valid only in the GUI). + + opt : str + ``Opt`` = LOC lists the trace point number location (X, Y, Z). Default. + + ``Opt`` = PART lists the trace point number particle settings (velocity, charge, mass). + + Notes + ----- + + .. _TRPLIS_notes: + + Lists the charged particle trace points in the active display coordinate system ( :ref:`dsys` ). + Trace points are defined with the :ref:`trpoin` command. + """ + command = f"TRPLIS,{ntrp1},{ntrp2},{trpinc},{opt}" + return self.run(command, **kwargs) + + def trpoin( + self, + x: str = "", + y: str = "", + z: str = "", + vx: str = "", + vy: str = "", + vz: str = "", + chrg: str = "", + mass: str = "", + **kwargs, + ): + r"""Defines a point through which a charged particle trace will travel. + + Mechanical APDL Command: `TRPOIN `_ + + Parameters + ---------- + x : str + Coordinate location of the trace point (in the active coordinate system). If ``X`` = P, + graphical picking is enabled and all remaining command fields are ignored (valid only in the + GUI). + + y : str + Coordinate location of the trace point (in the active coordinate system). If ``X`` = P, + graphical picking is enabled and all remaining command fields are ignored (valid only in the + GUI). + + z : str + Coordinate location of the trace point (in the active coordinate system). If ``X`` = P, + graphical picking is enabled and all remaining command fields are ignored (valid only in the + GUI). + + vx : str + Particle velocities in the X, Y and Z directions (in the active coordinate system). + + vy : str + Particle velocities in the X, Y and Z directions (in the active coordinate system). + + vz : str + Particle velocities in the X, Y and Z directions (in the active coordinate system). + + chrg : str + Particle charge. + + mass : str + Particle mass. + + Notes + ----- + + .. _TRPOIN_notes: + + Defines a point through which a charged particle trace ( :ref:`pltrac` ) will travel. Multiple + points (50 maximum) may be defined which will result in multiple particle traces. Use :ref:`trplis` + to list the currently defined trace points and :ref:`trpdel` to delete trace points. + + The VX, VY, VZ, CHRG, and MASS arguments only apply to charged particles. + """ + command = f"TRPOIN,{x},{y},{z},{vx},{vy},{vz},{chrg},{mass}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1_/__init__.py b/src/ansys/mapdl/core/_commands/post1_/__init__.py deleted file mode 100644 index 150b0a38b9..0000000000 --- a/src/ansys/mapdl/core/_commands/post1_/__init__.py +++ /dev/null @@ -1,32 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - -from . import ( - magnetics_calc, - path_operations, - results, - setup, - special, - status, - surface_operations, - trace_points, -) diff --git a/src/ansys/mapdl/core/_commands/post1_/magnetics_calc.py b/src/ansys/mapdl/core/_commands/post1_/magnetics_calc.py deleted file mode 100644 index 640e6fbcfd..0000000000 --- a/src/ansys/mapdl/core/_commands/post1_/magnetics_calc.py +++ /dev/null @@ -1,297 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class MagneticsCalc: - def curr2d(self, **kwargs): - """Calculates current flow in a 2-D conductor. - - APDL Command: CURR2D - - Notes - ----- - CURR2D invokes an ANSYS macro which calculates the total current - flowing in a conducting body for a 2-D planar or axisymmetric magnetic - field analysis. The currents may be applied source currents or induced - currents (eddy currents). The elements of the conducting region must - be selected before this command is issued. The total current - calculated by the macro is stored in the parameter TCURR. Also, the - total current and total current density are stored on a per-element - basis in the element table [ETABLE] with the labels TCURR and JT, - respectively. Use the PLETAB and PRETAB commands to plot and list the - element table items. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"CURR2D," - return self.run(command, **kwargs) - - def emagerr(self, **kwargs): - """Calculates the relative error in an electrostatic or electromagnetic - - APDL Command: EMAGERR - field analysis. - - Notes - ----- - The relative error is an approximation of the mesh discretization error - associated with a solution. It is based on the discrepancy between the - unaveraged, element-nodal field values and the averaged, nodal field - values. The calculation is valid within a material boundary and does - not consider the error in continuity of fields across dissimilar - materials. - - For electrostatics, the field values evaluated are the electric field - strength (EFSUM) and the electric flux density (DSUM). A relative error - norm of each is calculated on a per-element basis and stored in the - element table [ETABLE] with the labels EF_ERR and D_ERR. Normalized - error values EFN_ERR and DN_ERR are also calculated and stored in the - element table. Corresponding quantities for electromagnetics are H_ERR, - B_ERR, HN_ERR, and BN_ERR, which are calculated from the magnetic field - intensity (HSUM) and the magnetic flux density (BSUM). The normalized - error value is the relative error norm value divided by the peak - element-nodal field value for the currently selected elements. - - Use the PLETAB and PRETAB commands to plot and list the error norms and - normalized error values. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"EMAGERR," - return self.run(command, **kwargs) - - def emf(self, **kwargs): - """Calculates the electromotive force (emf), or voltage drop along a - - APDL Command: EMF - predefined path. - - Notes - ----- - EMF invokes an ANSYS macro which calculates the electromotive force - (emf), or voltage drop along a predefined path (specified with the PATH - command). It is valid for both 2-D and 3-D electric field analysis or - high-frequency electromagnetic field analysis. The calculated emf value - is stored in the parameter EMF. - - You must define a line path (via the PATH command) before issuing the - EMF command macro. The macro uses calculated values of the electric - field (EF), and uses path operations for the calculations. All path - items are cleared when the macro finishes executing. - - The EMF macro sets the "ACCURATE" mapping method and "MAT" - discontinuity option on the PMAP command. The ANSYS program retains - these settings after executing the macro. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"EMF," - return self.run(command, **kwargs) - - def emft(self, **kwargs): - """Summarizes electromagnetic forces and torques. - - APDL Command: EMFT - - Notes - ----- - Use this command to summarize electromagnetic force and torque in both - static electric and magnetic problems. To use this command, select the - nodes in the region of interest and make sure that all elements are - selected. If RSYS = 0, the force is reported in the global Cartesian - coordinate system. If RSYS ≠ 0, force is reported in the specified - coordinate system. However, for torque, if RSYS ≠ 0, this command will - account for the shift and rotation as specified by RSYS, but will - report only the Cartesian components. - - Forces are stored as items _FXSUM, _FYSUM, _FZSUM, and _FSSUM. Torque - is stored as items _TXSUM, _TYSUM, _TZSUM, and _TSSUM. - - This command is valid only with PLANE121, SOLID122, SOLID123, PLANE233, - SOLID236 and SOLID237 elements. For any other elements, you must use - FMAGSUM. - """ - command = f"EMFT," - return self.run(command, **kwargs) - - def fluxv(self, **kwargs): - """Calculates the flux passing through a closed contour. - - APDL Command: FLUXV - - Notes - ----- - FLUXV invokes an ANSYS macro which calculates the flux passing through - a closed contour (path) predefined by PATH. The calculated flux is - stored in the parameter FLUX. In a 2-D analysis, at least two nodes - must be defined on the path. In 3-D, a path of nodes describing a - closed contour must be specified (i.e., the first and last node in the - path specification must be the same). A counterclockwise ordering of - nodes on the PPATH command will give the correct sign on flux. Path - operations are used for the calculations, and all path items are - cleared upon completion. This macro is only available for vector - potential formulations. - """ - command = f"FLUXV," - return self.run(command, **kwargs) - - def mmf(self, **kwargs): - """Calculates the magnetomotive force along a path. - - APDL Command: MMF - - Notes - ----- - MMF invokes an ANSYS macro which calculates the magnetomotive force - (mmf) along a predefined path [PATH]. It is valid for both 2-D and - 3-D magnetic field analyses. The calculated mmf value is stored in the - parameter MMF. - - A closed path [PATH], passing through the magnetic circuit for which - mmf is to be calculated, must be defined before this command is issued. - A counterclockwise ordering of points on the PPATH command will yield - the correct sign on the mmf. The mmf is based on Ampere's Law. The - macro makes use of calculated values of field intensity (H), and uses - path operations for the calculations. All path items are cleared upon - completion. The MMF macro sets the "ACCURATE" mapping method and "MAT" - discontinuity option of the PMAP command. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MMF," - return self.run(command, **kwargs) - - def plf2d(self, ncont="", olay="", anum="", win="", **kwargs): - """Generates a contour line plot of equipotentials. - - APDL Command: PLF2D - - Parameters - ---------- - ncont - Number of contour lines to display. Issue in multiples of 9 (i.e., - 9, 18, 27, etc.). Default is 27 contour lines. - - olay - Overlay: - - 0 - Overlay edge outlines by material number. - - 1 - Overlay edge outlines by real constant number. - - anum - Highest material or real constant attribute number. Command will - cycle through ANUM element display overlays. Defaults to 10. - - win - Window number to which command applies. Defaults to 1. - - Notes - ----- - PLF2D invokes an ANSYS macro which plots equipotentials of the degree - of freedom AZ. These equipotential lines are parallel to flux lines - and thus give a good representation of flux patterns. In the - axisymmetric case, the display is actually ``r*AZ`` where "r" is the node - radius. The macro overlays (OLAY) edge outlines by material number or - real constant number (ANUM) and allows user control over the number of - contour lines to display (NCONT). - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"PLF2D,{ncont},{olay},{anum},{win}" - return self.run(command, **kwargs) - - def powerh(self, **kwargs): - """Calculates the rms power loss in a conductor or lossy dielectric. - - APDL Command: POWERH - - Notes - ----- - POWERH invokes an ANSYS macro which calculates the time-averaged (rms) - power loss in a conductor or lossy dielectric material from a harmonic - analysis. The power loss is stored in the parameter PAVG. Conductor - losses include solid conductors and surface conductors approximated by - impedance or shielding boundary conditions. The power loss density for - solid conductors or dielectrics is stored in the element table with the - label PLOSSD and may be listed [PRETAB] or displayed [PLETAB]. PLOSSD - does not include surface losses. The elements of the conducting region - must be selected before this command is issued. POWERH is valid for - 2-D and 3-D analyses. - """ - command = f"POWERH," - return self.run(command, **kwargs) - - def senergy(self, opt="", antype="", **kwargs): - """Determines the stored magnetic energy or co-energy. - - APDL Command: SENERGY - - Parameters - ---------- - opt - Item to be calculated: - - 0 - Stored magnetic energy. - - 1 - Stored magnetic co-energy. - - antype - Analysis type: - - 0 - Static or transient. - - 1 - Harmonic. - - Notes - ----- - SENERGY invokes an ANSYS macro which calculates the stored magnetic - energy or co-energy for all selected elements. (For a harmonic - analysis, the macro calculates a time-averaged (rms) stored energy.) A - summary table listing the energy by material number is produced. The - energy density is also calculated and stored on a per-element basis in - the element table [ETABLE] with the label MG_ENG (energy density) or - MG_COENG (co-energy density). The macro erases all other items in the - element table [ETABLE] and only retains the energy density or co-energy - density. Use the PLETAB and PRETAB commands to plot and list the - energy density. The macro is valid for static and low-frequency - magnetic field formulations. The macro will not calculate stored - energy and co-energy for the following cases: - - Orthotropic nonlinear permanent magnets. - - Orthotropic nonlinear permeable materials. - - Temperature dependent materials. - - SENERGY is restricted to MKSA units. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"SENERGY,{opt},{antype}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1_/path_operations.py b/src/ansys/mapdl/core/_commands/post1_/path_operations.py deleted file mode 100644 index ba7794fb83..0000000000 --- a/src/ansys/mapdl/core/_commands/post1_/path_operations.py +++ /dev/null @@ -1,986 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class PathOperations: - def padele(self, delopt="", **kwargs): - """Deletes a defined path. - - APDL Command: PADELE - - Parameters - ---------- - delopt - Path delete option (one of the following): - - ALL - Delete all defined paths. - - NAME - Delete a specific path from the list of path definitions. (Substitute the - actual path name for NAME.) - - Notes - ----- - Paths are identified by individual path names. To review the current - list of path names, issue the command PATH,STATUS. - - This command is valid in the general postprocessor. - """ - command = f"PADELE,{delopt}" - return self.run(command, **kwargs) - - def paget(self, parray="", popt="", **kwargs): - """Writes current path information into an array variable. - - APDL Command: PAGET - - Parameters - ---------- - parray - The name of the array parameter that the ANSYS program creates to - store the path information. If the array parameter already exists, - it will be replaced with the current path information. - - popt - Determines how data will be stored in the parameter specified with - PARRAY: - - POINTS - Store the path points, the nodes (if any), and coordinate system. (For - information on defining paths and path points, see the - descriptions of the PATH and PPATH commands.) - - TABLE - Store the path data items. (See the PDEF command description for path data - items.) - - LABEL - Stores path data labels. - - Notes - ----- - Use the PAGET command together with the PAPUT command to store and - retrieve path data in array variables for archiving purposes. When - retrieving path information, restore the path points (POINTS option) - first, then the path data (TABLE option), and then the path labels - (LABEL option). - """ - command = f"PAGET,{parray},{popt}" - return self.run(command, **kwargs) - - def paput(self, parray="", popt="", **kwargs): - """Retrieves path information from an array variable. - - APDL Command: PAPUT - - Parameters - ---------- - parray - Name of the array variable containing the path information. - - popt - Specifies which path data to retrieve: - - POINTS - Retrieve path point information (specified with the PPATH command and stored - with the PAGET,POINTS command). The path data name will - be assigned to the path points. - - TABLE - Retrieve path data items (defined via the PDEF command and stored with the - PAGET,,TABLE command). - - LABEL - Retrieve path labels stored with the PAGET,,LABEL command. - - Notes - ----- - When retrieving path information, restore path points (POINTS option) - first, then the path data (TABLE option), and then the path labels - (LABEL option). - """ - command = f"PAPUT,{parray},{popt}" - return self.run(command, **kwargs) - - def paresu(self, lab="", fname="", ext="", **kwargs): - """Restores previously saved paths from a file. - - APDL Command: PARESU - - Parameters - ---------- - lab - Read operation: - - S - Saves only selected paths. - - ALL - Read all paths from the selected file (default). - - Pname - Saves the named path (from the PSEL 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. - - The file name defaults to Jobname. - - ext - Filename extension (eight-character maximum). The - extension defaults to PATH if Fname is blank. - - Notes - ----- - This command removes all paths from virtual memory and then - reads path data from a file written with the PASAVE command. - All paths on the file will be restored. All paths currently - in memory will be deleted. - """ - command = f"PARESU,{lab},{fname},{ext}" - return self.run(command, **kwargs) - - def pasave(self, lab="", fname="", ext="", **kwargs): - """Saves selected paths to an external file. - - APDL Command: PASAVE - - Parameters - ---------- - lab - Write operation: - - S - Saves only selected paths. - - ALL - Saves all paths (default). - - Pname - Saves the named path (from the PSEL 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). - - Notes - ----- - Saves the paths selected with the PSEL command to an external file - (Jobname.path by default). Previous paths on this file, if any, will - be overwritten. The path file may be read with the PARESU command. - - This command is valid in POST1. - """ - command = f"PASAVE,{lab},{fname},{ext}" - return self.run(command, **kwargs) - - def path(self, name="", npts="", nsets="", ndiv="", **kwargs): - """Defines a path name and establishes parameters for the path. - - APDL Command: PATH - - Parameters - ---------- - name - Name for this path (eight characters maximum. If nPts is blank, set - the current path to the path with this name. If nPts is greater - than zero, create a path of this name. If a path with this name - already exists, replace it with a new path. If the NAME value is - STATUS, display the status for path settings. - - npts - The number of points used to define this path. The minimum number - is two, and the maximum is 1000. Default is 2. - - nsets - The number of sets of data which you can map to this path. You - must specify at least four: X, Y, Z, and S. Default is 30. - - ndiv - The number of divisions between adjacent points. Default is 20. - There is no maximum number of divisions. - - Notes - ----- - The PATH command is used to define parameters for establishing a path. - The path geometry is created by the PPATH command. Multiple paths may - be defined and named; however, only one path may be active for data - interpolation [PDEF] and data operations [PCALC, etc.]. Path geometry - points and data are stored in memory while in POST1. If you leave - POST1, the path information is erased. Path geometry and data may be - saved in a file by archiving the data using the PASAVE command. Path - information may be restored by retrieving the data using the PARESU - command. - - For overlapping nodes, the lowest numbered node is assigned to the - path. - - The number of divisions defined using nDiv does NOT affect the number - of divisions used by PLSECT and PRSECT. - - For information on displaying paths you have defined, see the Basic - Analysis Guide. - """ - command = f"PATH,{name},{npts},{nsets},{ndiv}" - return self.run(command, **kwargs) - - def pcalc( - self, - oper="", - labr="", - lab1="", - lab2="", - fact1="", - fact2="", - const="", - **kwargs, - ): - """Forms additional labeled path items by operating on existing path - - APDL Command: PCALC - items. - - Parameters - ---------- - oper - Type of operation to be performed. See "Notes" below for specific - descriptions of each operation: - - ADD - Adds two existing path items. - - MULT - Multiplies two existing path items. - - DIV - Divides two existing path items (a divide by zero results in a value of zero). - - EXP - Exponentiates and adds existing path items. - - DERI - Finds a derivative. - - INTG - Finds an integral. - - SIN - Sine. - - COS - Cosine. - - ASIN - Arcsine. - - ACOS - Arccosine. - - LOG - Natural log. - - labr - Label assigned to the resulting path item. - - lab1 - First labeled path item in operation. - - lab2 - Second labeled path item in operation. Lab2 must not be blank for - the MULT, DIV, DERI, and INTG operations. - - fact1 - Factor applied to Lab1. A (blank) or '0' entry defaults to 1.0. - - fact2 - Factor applied to Lab2. A (blank) or '0' entry defaults to 1.0. - - const - Constant value (defaults to 0.0). - - Notes - ----- - If Oper = ADD, the command format is: - - PCALC,ADD,LabR,Lab1,Lab2,FACT1,FACT2,CONST - - This operation adds two existing path items according to the operation: - - LabR = (FACT1 x Lab1) + (FACT2 x Lab2) + CONST - - It may be used to scale the results for a single path item. - - If Oper = MULT, the command format is: - - PCALC,MULT,LabR,Lab1,Lab2,FACT1 - - Lab2 must not be blank. This operation multiplies two existing path - items according to the operation: - - LabR = Lab1 x Lab2 x FACT1 - - If Oper = DIV, the command format is: - - PCALC,DIV,LabR,Lab1,Lab2,FACT1 - - Lab2 must not be blank. This operation divides two existing path items - according to the operation: - - LabR = (Lab1/Lab2) x FACT1 - - If Oper = EXP, the command format is: - - PCALC,EXP,LabR,Lab1,Lab2,FACT1,FACT2 - - This operation exponentiates and adds existing path items according to - the operation: - - ``LabR = (|Lab1|FACT1) + (|Lab2|FACT2|)`` - - If Oper = DERI, the command format is: - - ``PCALC,DERI,LabR,Lab1,Lab2,FACT1`` - - Lab2 must not be blank. This operation finds a derivative according to - the operation: - - ``LabR = FACT1 x d(Lab1)/d(Lab2)`` - - If Oper = INTG, the command format is: - - ``PCALC,INTG,LabR,Lab1,Lab2,FACT1`` - - Lab2 must not be blank. This operation finds an integral according to - the operation: - - Use S for Lab2 to integrate Lab1 with respect to the path length. S, - the distance along the path, is automatically calculated by the program - when a path item is created with the PDEF command. - - If Oper = SIN, COS, ASIN, ACOS, or LOG, the command format is: - - ``PCALC,Oper,LabR,Lab1,,FACT1,CONST`` - - where the function (SIN, COS, ASIN, ACOS or LOG) is substituted for - Oper and Lab2 is blank. - - The operation finds the resulting path item according to one of the - following formulas: - - ``LabR = FACT2 x sin(FACT1 x Lab1) + CONST`` - - ``LabR = FACT2 x cos(FACT1 x Lab1) + CONST`` - - ``LabR = FACT2 x sin-1(FACT1 x Lab1) + CONST`` - - ``LabR = FACT2 x cos-1(FACT1 x Lab1) + CONST`` - - ``LabR = FACT2 x log(FACT1 x Lab1) + CONST`` - """ - command = f"PCALC,{oper},{labr},{lab1},{lab2},{fact1},{fact2},{const}" - return self.run(command, **kwargs) - - def pcross( - self, - labxr="", - labyr="", - labzr="", - labx1="", - laby1="", - labz1="", - labx2="", - laby2="", - labz2="", - **kwargs, - ): - """Calculates the cross product of two path vectors along the current - - APDL Command: PCROSS - path. - - Parameters - ---------- - labxr - Label assigned to X-component of resultant vector. - - labyr - Label assigned to Y-component of resultant vector. - - labzr - Label assigned to Z-component of resultant vector. - - labx1 - X-component of first vector label (labeled path item). - - laby1 - Y-component of first vector label. - - labz1 - Z-component of first vector label. - - labx2 - X-component of second vector label (labeled path item). - - laby2 - Y-component of second vector label. - - labz2 - Z-component of second vector label. - """ - command = f"PCROSS,{labxr},{labyr},{labzr},{labx1},{laby1},{labz1},{labx2},{laby2},{labz2}" - return self.run(command, **kwargs) - - def pdef(self, lab="", item="", comp="", avglab="", **kwargs): - """Interpolates an item onto a path. - - APDL Command: PDEF - - Parameters - ---------- - lab - Label assigned to the resulting path item (8 characters maximum). - This item may be used as input for other path operations. - - item - Label identifying the item for interpolation. Valid item labels - are shown in Table 216: PDEF - valid Item and Component Labels - below. Some items also require a component label. - - comp - Component of the item (if required). Valid component labels are - shown in Table 216: PDEF - valid Item and Component Labels below. - - avglab - Option to average across element boundaries: - - AVG - Average element results across elements (default). - - NOAV - Do not average element results across elements. If the parameter DISCON = MAT - on the PMAP command, this option is automatically invoked. - - Notes - ----- - Defines and interpolates a labeled path item along a predefined path - (PATH). Path item results are in the global Cartesian coordinate - directions unless transformed (RSYS). A path item must be defined - before it can be used with other path operations. Additional path - items may be defined from the PVECT, PCALC, PDOT, and PCROSS commands. - Path items may be listed (PRPATH) or displayed (PLPATH, PLPAGM). A - maximum number of path items permitted is established by the nSets - argument specified with the PATH command. - - When you create the first path item (PDEF or PVECT), the program - automatically interpolates four path items which are used to describe - the geometry of the path. These predefined items are the position of - the interpolated path points (labels XG, YG, and ZG) in global - Cartesian coordinates, and the path length (label S). For alternate - methods of mapping the path geometry (to include, for example, material - discontinuity) see the PMAP command. These items may also be listed or - displayed with the PRPATH, PLPATH, and PLPAGM commands. - - If specifying that load case operations act on principal/equivalent - stresses (SUMTYPE,PRIN), derived quantities (principal and equivalent - stresses/strains) will be zero for path plots. A typical use for such a - case involves mode combinations in a response spectrum analysis. - - The number of interpolation points on the path is defined by the nDiv - argument on the PATH command. See Mapping Nodal and Element Data onto - the Path in the Mechanical APDL Theory Reference for details. Use - PDEF,STAT to list the path item labels. Use PDEF,CLEAR to erase all - labeled path items, except the path geometry items (XG, YG, ZG, S). - - For SHELL131 and SHELL132 elements with KEYOPT(3) = 0 or 1, use the - labels TBOT, TE2, TE3, ..., TTOP instead of TEMP. - - For more information on the meaning of contact status and its possible - values, see Reviewing Results in POST1 in the Contact Technology Guide. - """ - command = f"PDEF,{lab},{item},{comp},{avglab}" - return self.run(command, **kwargs) - - def pdot( - self, - labr="", - labx1="", - laby1="", - labz1="", - labx2="", - laby2="", - labz2="", - **kwargs, - ): - """Calculates the dot product of two path vectors along the current path. - - APDL Command: PDOT - - Parameters - ---------- - labr - Label assigned to dot product result. - - labx1 - X-component of first vector label (labeled path item). - - laby1 - Y-component of first vector label (labeled path item). - - labz1 - Z-component of first vector label (labeled path item). - - labx2 - X-component of second vector label (labeled path item). - - laby2 - Y-component of second vector label (labeled path item). - - labz2 - Z-component of second vector label (labeled path item). - """ - command = f"PDOT,{labr},{labx1},{laby1},{labz1},{labx2},{laby2},{labz2}" - return self.run(command, **kwargs) - - def plpagm(self, item="", gscale="", nopt="", **kwargs): - """Displays path items along the path geometry. - - APDL Command: PLPAGM - - Parameters - ---------- - item - The path data item to be displayed on the currently active path - (defined by the PATH command). Valid path items are those defined - with the PDEF or PLNEAR commands. - - gscale - Scale factor for the offset from the path for the path data item - displays. Defaults to 1.0. - - nopt - Determines how data is displayed: - - (blank) - Do not display nodes, and scale the display based on the currently selected - node set (default). - - NODE - Display path item data along with the currently selected set of nodes. The - display geometry is scaled to the selected node set. - - Notes - ----- - You can use the Gscale argument to scale the contour display offset - from the path for clarity. You need to type all six characters to issue - this command. - """ - command = f"PLPAGM,{item},{gscale},{nopt}" - return self.run(command, **kwargs) - - def plpath(self, lab1="", lab2="", lab3="", lab4="", lab5="", lab6="", **kwargs): - """Displays path items on a graph. - - APDL Command: PLPATH - - Parameters - ---------- - lab1, lab2, lab3, . . . , lab6 - Labels identifying the path items to be displayed. Up to six items - may be drawn per frame. Predefined path geometry items XG, YG, ZG, - and S [PDEF] may also be displayed. - - Notes - ----- - The path must have been defined by the PATH and PPATH commands. Path - items and their labels must have been defined with the PDEF, PVECT, - PCALC, PDOT, PCROSS, or PLNEAR commands. Path items may also be - printed with the PRPATH command. Graph scaling may be controlled with - the /XRANGE, /YRANGE, and PRANGE commands. You need to type all six - characters to issue this command. - """ - command = f"PLPATH,{lab1},{lab2},{lab3},{lab4},{lab5},{lab6}" - return self.run(command, **kwargs) - - def plsect(self, item="", comp="", rho="", kbr="", **kwargs): - """Displays membrane and membrane-plus-bending linearized stresses. - - APDL Command: PLSECT - - Parameters - ---------- - item - Label identifying the item to be processed. Valid item labels are - shown in Table 221: PLSECT - Valid Item and Component Labels below. - Items also require a component label. - - comp - Component of the item. Valid component labels are shown in - Table 221: PLSECT - Valid Item and Component Labels below. - - rho - In-plane (X-Y) average radius of curvature of the inside and - outside surfaces of an axisymmetric section. If zero (or blank), a - plane or 3-D structure is assumed. If nonzero, an axisymmetric - structure is assumed. Use a very large number (or -1) for an - axisymmetric straight section. - - kbr - Through-thickness bending stresses key for an axisymmetric analysis - (RHO ≠ 0): - - 0 - Include the thickness-direction bending stresses. - - 1 - Ignore the thickness-direction bending stresses. - - 2 - Include the thickness-direction bending stress using the same formula as the Y - (axial direction ) bending stress. Also use the same formula - for the shear stress. - - Notes - ----- - Calculates and displays the membrane and membrane-plus-bending - linearized stresses (as described for the PRSECT command) along a path - section [PATH] as a graph. The path section is defined by two points - specified with the PPATH command. For linearized stress calculations, - the path must be defined with nodes. The path must be entirely within - the selected elements (that is, there must not be any element gaps - along the path). The total stress (equivalent to the PLPATH display) is - also displayed. This command always uses 48 divisions along the path, - regardless of the number of divisions defined by PATH. - - Portions of this command are not supported by PowerGraphics - [/GRAPHICS,POWER]. - - Table: 221:: : PLSECT - Valid Item and Component Labels - """ - command = f"PLSECT,{item},{comp},{rho},{kbr}" - return self.run(command, **kwargs) - - def pmap(self, form="", discon="", **kwargs): - """Creates mapping of the path geometry by defining path interpolation - - APDL Command: PMAP - division points. - - Parameters - ---------- - form - Defines the mapping method: - - UNIFORM - Maps uniform divisions (specified on the nDiv argument of the PATH command) - between specified points. This is the default. - - ACCURATE - Map geometry using a small division at the beginning and end of each segment. - This gives you accurate derivatives, integrals, - tangents, and normals for curves which do not have - continuous slopes at the specified points. To create - nonuniform divisions, the nDiv argument of the PATH - command must be greater than 2. - - discon - Sets mapping for discontinuities in the field. The divisions are - modified to put a point just before and just after the - discontinuity. The valid label is MAT, for a material - discontinuity. No discontinuity is the default. Discontinuity - mapping involves the NOAV option on the PDEF command. - """ - command = f"PMAP,{form},{discon}" - return self.run(command, **kwargs) - - def ppath(self, point="", node="", x="", y="", z="", cs="", **kwargs): - """Defines a path by picking or defining nodes, or locations on the - - APDL Command: PPATH - currently active working plane, or by entering specific coordinate - locations. - - Parameters - ---------- - point - The point number. It must be greater than zero and less than or - equal to the nPts value specified on the PATH command if graphical - picking is not being used. - - node - The node number defining this point. If blank, use the X, Y, Z - coordinates to define the point. A valid node number will override - X, Y, Z coordinate arguments. - - x, y, z - The location of the point in the global Cartesian coordinate - system. Use these arguments only if you omit the NODE argument. - - cs - The coordinate system for interpolation of the path between the - previous point and this point. Omit this argument if you wish to - use the currently active (CSYS) coordinate system. If the - coordinate system of two adjacent points is different, the CS value - of the latter point will be used. - - Notes - ----- - For linearized stress calculations, the path must be defined with - nodes. - - This command is designed and works best in interactive (GUI) mode, - using the menu paths listed below. For command line operations, issue - PPATH,P to define your path by picking nodes. - - For information on displaying paths you have defined, see Defining Data - to be Retrieved in the Basic Analysis Guide. - """ - command = f"PPATH,{point},{node},{x},{y},{z},{cs}" - return self.run(command, **kwargs) - - def prange(self, linc="", vmin="", vmax="", xvar="", **kwargs): - """Determines the path range. - - APDL Command: PRANGE - - Parameters - ---------- - linc, vmin, vmax - Set the range for listing or displaying the table locations between - a minimum value (VMIN) and a maximum value (VMAX) of the path - distance with a location increment of LINC (defaults to 1). The - first location begins at VMIN. - - xvar - Path variable item to be used as the x-axis plot variable. Any - valid path variable may be used (PDEF command). Default variable - is the path distance, S. - - Notes - ----- - Determines the path distance range for use with the PRPATH and PLPATH - commands. - """ - command = f"PRANGE,{linc},{vmin},{vmax},{xvar}" - return self.run(command, **kwargs) - - def prpath(self, lab1="", lab2="", lab3="", lab4="", lab5="", lab6="", **kwargs): - """Prints path items along a geometry path. - - APDL Command: PRPATH - - Parameters - ---------- - lab1, lab2, lab3, . . . , lab6 - Labels identifying the path items to be printed. Up to six items - may be printed at a time. Predefined path geometry items XG, YZ, - ZG, and S [PDEF] may also be printed. - - Notes - ----- - Prints path items with respect to a geometry path (as defined by the - PATH and PPATH commands). Path items and their labels must have been - defined with the PDEF, PVECT, PCALC, PDOT, PCROSS, or PRNEAR commands. - Path items may also be displayed with the PLPATH and PLPAGM commands. - See the PRANGE command for range control of the path. - """ - command = f"PRPATH,{lab1},{lab2},{lab3},{lab4},{lab5},{lab6}" - return self.run(command, **kwargs) - - def prsect(self, rho="", kbr="", **kwargs): - """Calculates and prints linearized stresses along a section path. - - APDL Command: PRSECT - - Parameters - ---------- - rho - In-plane (X-Y) average radius of curvature of the inside and - outside surfaces of an axisymmetric section. If zero (or blank), a - plane or 3-D structure is assumed. If nonzero, an axisymmetric - structure is assumed. Use any large number (or -1) for an - axisymmetric straight section. - - kbr - Through-thickness bending stresses key for an axisymmetric analysis - (RHO ≠ 0): - - 0 - Include the thickness-direction bending stresses. - - 1 - Ignore the thickness-direction bending stresses. - - 2 - Include the thickness-direction bending stress using the same formula as the Y - (axial direction ) bending stress. Also use the same formula - for the shear stress. - - Notes - ----- - You may choose to linearize the stresses through a section and separate - them into categories for various code calculations. PRSECT calculates - and reports linearized stresses along a section path. The linearized - stresses are also separated into membrane, bending, membrane plus - bending, peak, and total stress categories. - - First, define your section path using the PATH and PPATH (with the NODE - option) commands. Your path must lie entirely within the selected set - of elements (that is, there must be no element gaps along the path). - PATH and PPATH are used only to retrieve the two end nodes. The path - data is not retained. The section path is defined by the two end - nodes, and by 47 intermediate points that are automatically determined - by linear interpolation in the active display coordinate system [DSYS]. - The number and location of the intermediate points are not affected by - the number of divisions set by PATH,,,,nDiv. - - Your linearized component stress values are obtained by interpolating - each element’s average corner nodal values along the section path - points within each path element. PRSECT reports the linearized - component and principal stresses for each stress category at the - beginning, mid-length, and end of the section path. PRPATH can be used - to report the total stresses at the intermediate points. - - Section paths may be through any set of solid (2-D plane, 2-D - axisymmetric or 3-D) elements. However, section paths are usually - defined to be through the thickness of the structure and normal to the - inner and outer structure surfaces. Section paths (in-plane only) may - also be defined for shell element structures. See the Mechanical APDL - Theory Reference for details. - - If the RHO option is set to indicate the axisymmetric option (non- - zero), PRSECT reports the linearized stresses in the section - coordinates (SX – along the path, SY – normal to the path, and SZ – - hoop direction). If the RHO option is set to indicate the 2-D planar - or 3-D option (zero or blank), PRSECT reports the linearized stresses - in the active results coordinate system [RSYS]. If the RHO option is - zero or blank and either RSYS, SOLU or RSYS, -1 are active, the - linearized stresses are calculated and reported in the global Cartesian - coordinate system. It is recommended that linearized stress - calculations be performed in a rectangular coordinate system. - Principal stresses are recalculated from the component stresses and are - invariant with the coordinate system as long as SX is in the same - direction at all points along the defined path. The PLSECT command - displays the linearized stresses in the same coordinate system as - reported by PRSECT. - - Stress components through the section are linearized by a line integral - method and separated into constant membrane stresses, bending stresses - varying linearly between end points, and peak stresses (defined as the - difference between the actual (total) stress and the membrane plus - bending combination). - - For nonaxisymmetric structures, the bending stresses are calculated - such that the neutral axis is at the midpoint of the path. - Axisymmetric results include the effects of both the radius of - revolution (automatically determined from the node locations) and the - in-plane average radius of curvature of the section surfaces (user - input). - - For axisymmetric cases, Mechanical APDL calculates the linearized - bending stress in the through-thickness direction as the difference - between the total outer fiber stress and the membrane stress if KBR = - 1. The calculation method may be conservative for locations with a - highly nonlinear variation of stress in the through-thickness - direction. Alternatively, you can specify KBR = 2 to calculate the - bending stress using the same method and formula as the Y (axial - direction) bending stress. For more information, see the discussion of - axisymmetric cases (specifically Equation: 17–40) in the Mechanical - APDL Theory Reference. - - Portions of this command are not supported by PowerGraphics - [/GRAPHICS,POWER]. - """ - command = f"PRSECT,{rho},{kbr}" - return self.run(command, **kwargs) - - def psel( - self, - type_="", - pname1="", - pname2="", - pname3="", - pname4="", - pname5="", - pname6="", - pname7="", - pname8="", - pname9="", - pname10="", - **kwargs, - ): - """Selects a path or paths. - - APDL Command: PSEL - - Parameters - ---------- - type\\_ - Label identifying the type of select: - - S - Select a new path. - - R - Reselect a path from the current set of paths. - - A - Additionally select a path and extend the current set of paths. - - U - Unselect a path from the current set of paths. - - ALL - Restore the full set of paths. - - NONE - Unselect the full set of paths. - - INV - Invert the current set of paths (selected becomes unselected and vice versa). - - pname1, pname2, pname3, . . . , pname10 - Name of existing path(s). - - Notes - ----- - Selects a path or multiple paths, up to ten. Data are flagged as - selected and unselected; no data are actually deleted from the - database. There is no default for this command; you must specify a - type and pathname. - """ - command = f"PSEL,{type_},{pname1},{pname2},{pname3},{pname4},{pname5},{pname6},{pname7},{pname8},{pname9},{pname10}" - return self.run(command, **kwargs) - - def pvect(self, oper="", labxr="", labyr="", labzr="", **kwargs): - """Interpolates a set of items onto a path. - - APDL Command: PVECT - - Parameters - ---------- - oper - Valid operations for geometry operations along a path are: - - NORM - Defines a unit normal vector at each interpolation point in the direction of - the cross product of the tangent to the path and the active - Z axis. Resulting vector components are in the active - coordinate system (which must be Cartesian). - - TANG - Defines a unit vector tangent to the path at each interpolation point. Vector - components are in the active coordinate system (which must - be Cartesian). - - RADI - Defines the position vector of each interpolation point of the path from the - center of the active coordinate system (which must be - Cartesian). - - labxr - Label (8 characters maximum) assigned to X-component of the - resulting vector. - - labyr - Label (8 characters maximum) assigned to Y-component of the - resulting vector. - - labzr - Label (8 characters maximum) assigned to Z-component of the - resulting vector. - - Notes - ----- - Defines and interpolates a set of labeled path items along predefined - path [PATH] and performs various geometric operations on these path - items. A path item must be defined before it can be used with other - path operations. Additional path items may be defined with the PDEF, - PCALC, PDOT, and PCROSS commands. Path items may be listed or - displayed with the PLPATH, PLPAGM and PRPATH commands. Path geometry - items (XG, YG, ZG, S) are automatically interpolated (in the active - CSYS) if not done so previously with the PDEF command. - """ - command = f"PVECT,{oper},{labxr},{labyr},{labzr}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1_/results.py b/src/ansys/mapdl/core/_commands/post1_/results.py deleted file mode 100644 index 1b588fad57..0000000000 --- a/src/ansys/mapdl/core/_commands/post1_/results.py +++ /dev/null @@ -1,1037 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class Results: - def nsort(self, item="", comp="", order="", kabs="", numb="", sel="", **kwargs): - """Sorts nodal data. - - APDL Command: NSORT - - Parameters - ---------- - item - Label identifying the item to be sorted on. Valid item labels are - shown in the table below. Some items also require a component - label. - - comp - Component of the item (if required). Valid component labels are - shown in the table below. - - order - Order of sort operation: - - 0 - Sort into descending order. - - 1 - Sort into ascending order. - - kabs - Absolute value key: - - 0 - Sort according to real value. - - 1 - Sort according to absolute value. - - numb - Number of nodal data records to be sorted in ascending or - descending order (ORDER) before sort is stopped (remainder will be - in unsorted sequence) (defaults to all nodes). - - sel - Allows selection of nodes in the sorted field. - - (blank) - No selection (default). - - SELECT - Select the nodes in the sorted list. - - Notes - ----- - Values are in the active coordinate system [CSYS for input data or RSYS - for results data]. Various element results also depend upon the - recalculation method and the selected results location [AVPRIN, RSYS, - SHELL, ESEL, and NSEL]. If simultaneous load cases are stored, the - last sorted sequence formed from any load case applies to all load - cases. Use NUSORT to restore the original order. This command is not - valid with PowerGraphics. - - Table: 213:: : NSORT - Valid Item and Component Labels - - Table: 214:: : NSORT - Valid Item and Component Labels for Nodal DOF - Result Values - - Table: 215:: : NSORT - Valid Item and Component Labels for Element - Result Values - - Works only if failure criteria information is provided. (For more - information, see the documentation for the FC and TB commands.) - - Must be added via the FCTYP command first. - """ - command = f"NSORT,{item},{comp},{order},{kabs},{numb},{sel}" - return self.run(command, **kwargs) - - def nusort(self, **kwargs): - """Restores original order for nodal data. - - APDL Command: NUSORT - - Notes - ----- - This command restores the nodal data to its original order (sorted in - ascending node number sequence) after an NSORT command. Changing the - selected nodal set [NSEL] also restores the original nodal order. - """ - command = f"NUSORT," - return self.run(command, **kwargs) - - def plcint(self, action="", id_="", node="", cont="", dtype="", **kwargs): - """Plots the fracture parameter (CINT) result data. - - APDL Command: PLCINT - - Parameters - ---------- - action - PATH - - PATH - Plots CINT quantities according to path number (default). - - FRONT - Plots CINT quantities distribution along the crack front. - - id\\_ - Crack ID number. - - node - Crack tip node number (default = ALL). - - cont - Contour number (Default = ALL). - - dtype - Data type to output: - - JINT - J-integral (default) - - IIN1 - Interaction integral 1 - - IIN2 - Interaction integral 2 - - IIN3 - Interaction integral 3 - - K1 - Mode 1 stress-intensity factor - - K2 - Mode 2 stress-intensity factor - - K3 - Mode 3 stress-intensity factor - - G1 - Mode 1 energy release rate - - G2 - Mode 2 energy release rate - - G3 - Mode 3 energy release rate - - GT - Total energy release rate - - MFTX - Total material force X - - MFTY - Total material force Y - - MFTZ - Total material force Z - - TSTRESS - T-stress - - CEXT - Crack extension - - CSTAR - C*-integral - - Notes - ----- - The PLCINT command is not available for XFEM-based crack growth - analyses results processing. - """ - command = f"PLCINT,{action},{id_},{node},{cont},{dtype}" - return self.run(command, **kwargs) - - def pldisp(self, kund="", **kwargs): - """Displays the displaced structure. - - APDL Command: PLDISP - - Parameters - ---------- - kund - Undisplaced shape key: - - 0 - Display only displaced structure. - - 1 - Overlay displaced display with similar undisplaced - display (appearance is system-dependent). - - 2 - Same as 1 except overlay with undisplaced edge display - (appearance is system-dependent). - - Notes - ----- - Displays the displaced structure for the selected elements. - - For information on true scale plots, refer to the description of the - /DSCALE command [/DSCALE,,1.0]. - """ - command = f"PLDISP,{kund}" - return self.run(command, **kwargs) - - def plesol(self, item="", comp="", kund="", fact="", **kwargs): - """Displays the solution results as discontinuous element contours. - - APDL Command: PLESOL - - Parameters - ---------- - item - Label identifying the item. Valid item labels are shown in - Table 219: PLESOL - Valid Item and Component Labels for Element - Results below. Some items also require a component label. - - comp - Component of the item (if required). Valid component labels are - shown in Table 219: PLESOL - Valid Item and Component Labels for - Element Results below. - - kund - Undisplaced shape key: - - 0 - Do not overlay undeformed structure display - - 1 - Overlay displaced contour plot with undeformed display (appearance is system- - dependent) - - 2 - Overlay displaced contour plot with undeformed edge display (appearance is - system-dependent) - - fact - Scale factor for 2-D display of contact items (defaults to 1). A - negative scaling factor may be used to invert the display. - - Notes - ----- - Displays the solution results as element contours discontinuous across - element boundaries for the selected elements. For example, PLESOL,S,X - displays the X component of stress S (that is, the SX stress - component). Various element results depend on the calculation method - and the selected results location (AVPRIN, RSYS, and ESEL). Contours - are determined by linear interpolation within each element, unaffected - by the surrounding elements (i.e., no nodal averaging is performed). - The discontinuity between contours of adjacent elements is an - indication of the gradient across elements. Component results are - displayed in the active results coordinate system [RSYS] (default is - the global Cartesian). See the ETABLE and PLETAB commands for - displaying items not available through this command (such as line - element results). - - For PowerGraphics displays [/GRAPHICS,POWER], results are plotted only - for the model exterior surface. The items marked with [1] in Table: - 219:: PLESOL - Valid Item and Component Labels for Element Results are - not supported by PowerGraphics. - - Table: 219:: : PLESOL - Valid Item and Component Labels for Element - Results - """ - command = f"PLESOL,{item},{comp},{kund},{fact}" - return self.run(command, **kwargs) - - def plnsol(self, item="", comp="", kund="", fact="", fileid="", **kwargs): - """Displays results as continuous contours. - - APDL Command: PLNSOL - - Parameters - ---------- - item - Label identifying the item. Valid item labels are shown in - Table 220: PLNSOL - Valid Item and Component Labels below. Some - items also require a component label. - - comp - Component of the item (if required). Valid component labels are - shown in Table 220: PLNSOL - Valid Item and Component Labels - below. - - kund - Undisplaced shape key: - - 0 - Do not overlay undeformed structure display - - 1 - Overlay displaced contour plot with undeformed display (appearance is system- - dependent) - - 2 - Overlay displaced contour plot with undeformed edge display (appearance is - system-dependent) - - fact - Scale factor for 2-D display for contact items. Default value is - 1. A negative scaling factor may be used to invert the display. - - fileid - The file index number (obtained via the NLDIAG,NRRE,ON command). - Valid only for Item = NRRE. - - Notes - ----- - Displays the solution results as continuous contours across element - boundaries for the selected nodes and elements. For example, PLNSOL,S,X - displays the X component of stress S (that is, the SX stress - component). Various element results depend upon the recalculation - method and the selected results location [AVPRIN, RSYS, LAYER, SHELL, - and NSEL]. Contours are determined by linear interpolation within each - element from the nodal values, which are averaged at a node whenever - two or more elements connect to the same node (except for FMAG, which - is summed at the node). - - For PowerGraphics displays [/GRAPHICS,POWER], results are plotted only - for the model exterior surface. The items marked with [2] are not - supported by PowerGraphics. To plot midside nodes, you must first issue - /EFACET,2. - - Table: 220:: : PLNSOL - Valid Item and Component Labels - """ - command = f"PLNSOL,{item},{comp},{kund},{fact},{fileid}" - return self.run(command, **kwargs) - - def plorb(self, **kwargs): - """Displays the orbital motion of a rotating structure - - APDL Command: PLORB - - Notes - ----- - When a structure is rotating and the Coriolis or gyroscopic effect is - taken into account (CORIOLIS), nodes lying on the rotation axis - generally exhibit an elliptical orbital motion. The PLORB command - displays the orbit of each rotating node as well as the deformed shape - at time t = 0 (the real part of the solution). - - To print the characteristics of the orbital path traversed by each - node, issue the PRORB command. - - The PLORB command is valid for line elements (such as BEAM188, BEAM189, - PIPE288, and PIPE289). - - Your model must also involve a rotational velocity (OMEGA or CMOMEGA) - with Coriolis enabled in a stationary reference frame - (CORIOLIS,,,,RefFrame = ON). - - A SET command should be issued after PLORB to ensure proper output for - subsequent postprocessing commands. - - The coordinate system for displaying nodal results must be global - Cartesian (RSYS,KCN = 0). - """ - command = f"PLORB," - return self.run(command, **kwargs) - - def prenergy( - self, - energytype="", - cname1="", - cname2="", - cname3="", - cname4="", - cname5="", - cname6="", - **kwargs, - ): - """Prints the total energies of a model or the energies of the specified - - APDL Command: PRENERGY - components. - - Parameters - ---------- - energytype - Type of energies to be printed: - - ALL - All energies are printed: potential, kinetic, artificial hourglass/drill - stiffness, contact stabilization energy, and artificial - stabilization energy when applicable. This is the default. - - SENE - Potential energy. - - KENE - Kinetic energy. - - cname1, cname2, cname3,… - Component names for energies of the components printout. - - Notes - ----- - The PRENERGY command prints out either the total energies of the entire - model or the energies of the components depending on the Cname1 - specification. - - Only existing components based on elements (defined with the CM - command) are supported when component energies are listed. - - This command applies to structural elements only. - """ - command = f"PRENERGY,{energytype},{cname1},{cname2},{cname3},{cname4},{cname5},{cname6}" - return self.run(command, **kwargs) - - def prorb(self, **kwargs): - """Prints the orbital motion characteristics of a rotating structure - - APDL Command: PRORB - - Notes - ----- - When a structure is rotating and the Coriolis or gyroscopic effect is - taken into account (CORIOLIS), nodes lying on the rotation axis - generally exhibit an elliptical orbital motion. The PRORB command - prints out the orbit characteristics A, B, PSI, PHI, YMAX and ZMAX of - each rotating node, where - - Angles PSI and PHI are in degrees and within the range of -180 through - +180. For more information about orbit definition, see Orbits in the - Advanced Analysis Guide. - - To display the characteristics of the orbital path traversed by each - node, issue the PLORB command. - - The PRORB command is valid for line elements (such as BEAM188, BEAM189, - PIPE288, and PIPE289). - - Your model must also involve a rotational velocity (OMEGA or CMOMEGA) - with Coriolis enabled in a stationary reference frame - (CORIOLIS,,,,RefFrame = ON). - - A SET command should be issued after PRORB to ensure proper output for - subsequent postprocessing commands. - - The coordinate system for displaying nodal results must be global - Cartesian (RSYS,KCN = 0). - """ - command = f"PRORB," - return self.run(command, **kwargs) - - def plvect( - self, - item="", - lab2="", - lab3="", - labp="", - mode="", - loc="", - edge="", - kund="", - **kwargs, - ): - """Displays results as vectors. - - APDL Command: PLVECT - - Parameters - ---------- - item - Predefined vector item (from Table 223: PLVECT - Valid Item Labels - below) or a label identifying the i-component of a user-defined - vector. - - lab2 - Label identifying the j-component of a user-defined vector. In most - cases, this value must be blank if Item is selected from - Table 223: PLVECT - Valid Item Labels. Individual principal - stresses (Item = S) or principal strains (Item = EPxx) may be - plotted by specifying the value as 1, 2, or 3. - - lab3 - Label identifying the k-component of a user-defined vector. Must - be blank if Item is selected from list below or for 2-D user - defined vector. - - labp - Label assigned to resultant vector for display labeling (defaults - to Item). - - mode - Vector or raster mode override key: - - (blank) - Use the setting of KEY on the /DEVICE command. - - RAST - Use raster mode for PLVECT displays. - - VECT - Use vector mode for PLVECT displays. - - loc - Vector location for display of field element results: - - ELEM - Display at element centroid (default). - - NODE - Display at element nodes. - - edge - Edge display override key: - - (blank) - Use the setting of Key on the /EDGE command. - - OFF - Deactivate the edge display. - - ON - Activate the edge display. - - kund - Undisplaced shape key: - - 0 - Display vectors on undeformed mesh or geometry. - - 1 - Display vectors on deformed mesh or geometry. - - Notes - ----- - Displays various solution results as vectors (arrows) for the selected - nodes and/or elements (elements must contain at least three nodes that - are not colinear). For example, PLVECT,U displays the displacement - vector for all selected nodes. For section displays [/TYPE], the - vectors are shown only on the section face (i.e., cutting plane). The - PLVECT display of principal strains and stresses (Item = S, EPTO, - EPEL, EPPL, EPCR, or EPTH) on a "cut" of the model (/TYPE,,1 ,5,7,8, or - 9) is not supported. The resulting plot displays the vectors on all - selected elements, not on just the sliced surface. See the /VSCALE - command to scale vector lengths. Vector magnitudes may be shown as a - contour display with the PLNSOL command. Various results also depend - upon the recalculation method and the selected results location [LAYER, - SHELL, and NSEL]. - - Items may be selected from a set of recognized vector labels (Item) or - a vector may be defined from up to three scalar labels - (Item,Lab2,Lab3). Scalar labels may be user-defined with the ETABLE - command. The vectors appear on an element display as arrows showing - the relative magnitude of the vector and its direction. The predefined - items will be shown either at the node or at the element centroid, - depending on what item is being displayed and depending on the Loc - setting. User defined ETABLE items will be shown at the element - centroid, regardless of the Loc setting. Stress vectors appear as - arrows at the element centroid, with the arrowheads pointing away from - each other for tension and toward each other for compression. - - For PowerGraphics, vector arrow displays are generated in Global - Cartesian (RSYS = 0). All subsequent displays will revert to your - original coordinate system. - - When vector mode is active (Mode = VECT), use the Z-buffered display - type [/TYPE,,6] to maximize speed of PLVECT plots (other hidden - display types may make plotting slow). For PowerGraphics - [/GRAPHICS,POWER], the items marked with [1] are not supported by - PowerGraphics. - - It is possible to plot principal stresses (Item = S) or principal - strains (Item = EPxx) individually. To do so, specify a Lab2 value of - 1, 2, or 3. For example, the following are valid commands: - - Table: 223:: : PLVECT - Valid Item Labels - - Not supported by PowerGraphics - """ - command = f"PLVECT,{item},{lab2},{lab3},{labp},{mode},{loc},{edge},{kund}" - return self.run(command, **kwargs) - - def prcint(self, id_="", node="", dtype="", **kwargs): - """Lists the fracture parameter (CINT) results data. - - APDL Command: PRCINT - - Parameters - ---------- - id\\_ - Crack ID number. - - node - Crack tip node number. Default = ALL. Valid only for 3-D analysis. - - dtype - Data type to output: - - JINT - J-integral - - IIN1 - Interaction integral 1 - - IIN2 - Interaction integral 2 - - IIN3 - Interaction integral 3 - - K1 - Mode 1 stress-intensity factor - - K2 - Mode 2 stress-intensity factor - - K3 - Mode 3 stress-intensity factor - - G1 - Mode 1 energy release rate - - G2 - Mode 2 energy release rate - - G3 - Mode 3 energy release rate - - GT - Total energy release rate - - MFTX - Total material force X - - MFTY - Total material force Y - - MFTZ - Total material force Z - - TSTRESS - T-stress - - CEXT - Crack extension - - CSTAR - C*-integral - - STTMAX - Maximum circumferential stress - - PSMAX - Maximum circumferential stress when - - Notes - ----- - When a crack tip node is defined, the values associated with the - specified node are listed. - - Dtype = STTMAX or PSMAX are valid for XFEM-based crack growth analyses - only. - - In an XFEM-based analysis, issue the command using this syntax: - - PRCINT, ID, , STTMAX (or PSMAX) - """ - command = f"PRCINT,{id_},{node},{dtype}" - return self.run(command, **kwargs) - - def presol(self, item="", comp="", **kwargs): - """Prints the solution results for elements. - - APDL Command: PRESOL - - Parameters - ---------- - item - Label identifying the item. Valid item labels are shown in - Table 224: PRESOL - Valid Item and Component Labels for Element - Results below. Some items also require a component label. - - comp - Component of the item (if required). Valid component labels are - shown in Table 224: PRESOL - Valid Item and Component Labels for - Element Results below. - - Notes - ----- - Prints the solution results for the selected elements in the sorted - sequence. For example, PRESOL,S prints the stress items SX, SY, SZ, - SXY, SYZ, and SXZ for the node locations of the element. Component - results are in the global Cartesian coordinate directions unless - transformed (RSYS). - - Shell elements print values at the top, then bottom of the element (or - layer). If KEYOPT(8) = 2 (for SHELL181, SHELL208, SHELL209, SHELL281, - or ELBOW290), the results are printed in the order TOP, BOT and then - MID of each element, (or layer). The MID value will be the actual value - as written to the results file. - - Items are listed as columns of a table versus element number. An - exception occurs for item ELEM which uses an element format (all - applicable line element results are listed per element) instead of a - tabular format. - - The FORCE command can be used to define which component of the nodal - load is to be used (static, damping, inertia, or total). See the - ETABLE and PRETAB commands for printing items not available through - this command (such as line element results). - - For PowerGraphics [/GRAPHICS,POWER], results are listed only for the - element surface. The items marked with [1] are not supported by - PowerGraphics. - - Table: 224:: : PRESOL - Valid Item and Component Labels for Element - Results - - Failure criteria for virgin material [1][2]. - - Default components: Maximum of all failure criteria defined at current - location (MAX), maximum strain (EMAX), maximum stress (SMAX), Tsai-Wu - Strength Index (TWSI), inverse of Tsai-Wu Strength Ratio Index (TWSR). - - Other available components: Hashin Fiber Failure (HFIB), Hashin Matrix - Failure (HMAT), Puck Fiber Failure (PFIB), Puck Matrix Failure (PMAT), - LaRc03 Fiber Failure (L3FB), LaRc03 Matrix Failure (L3MT), LaRc04 - Fiber Failure (L4FB), LaRc04 Matrix Failure (L4MT), and any user- - defined failure criteria (USR1 through USR9) [4]. - - Issue the FCTYP command to activate or remove failure criteria. - - Failure criteria based on the effective stresses in the damaged - material. - - Components: Maximum of all failure criteria defined at current location - (MAX), fiber tensile failure (FT), fiber compressive failure (FC), - matrix tensile failure (MT), and matrix compressive (MC). - - Progressive damage parameters. - - Components: Damage status (STAT, 0 - undamaged, 1 - damaged, 2 - - complete damage), fiber tensile damage variable (FT), fiber compressive - damage variable (FC), matrix tensile damage variable (MT), matrix - compressive damage variable (MC), shear damage variable (S), energy - dissipated per unit volume (SED), energy per unit volume due to viscous - damping (SEDV). - """ - command = f"PRESOL,{item},{comp}" - return self.run(command, **kwargs) - - def prjsol(self, item="", comp="", **kwargs): - """Prints joint element output. - - APDL Command: PRJSOL - - Parameters - ---------- - item - Label identifying the item. Some items also require a component - label. - - DISP - Relative displacements. - - ROT - Relative rotations. - - VEL - Relative linear velocities. - - OMG - Relative angular velocities. - - ACC - Relative linear accelerations. - - DMG - Relative angular accelerations. - - SMISC - Summable miscellaneous quantities. - - comp - Component of the item (if required). For Item = DISP, ROT, VEL, - OMG, ACC, and DMG, enter the direction label, X, Y, or Z. For Item - = SMISC, enter a valid number. - - Notes - ----- - Prints element output for the MPC184 joint element. The joint element - quantities printed are the values for the free or unconstrained - relative degrees of freedom. - - This command is valid in POST1 only. - """ - command = f"PRJSOL,{item},{comp}" - return self.run(command, **kwargs) - - def prnld(self, lab="", tol="", item="", **kwargs): - """Prints the summed element nodal loads. - - APDL Command: PRNLD - - Parameters - ---------- - lab - Nodal reaction load type. If blank, use the first ten of all - available labels. Valid labels are: - - tol - Tolerance value about zero within which loads are not printed, as - follows: - - > 0 - Relative tolerance about zero within which loads are not printed. In this case, - the tolerance is TOL * Load, where Load is the absolute - value of the maximum load on the selected nodes. - - 0 - Print all nodal loads. - - > 0 - Absolute tolerance about zero within which loads are not printed. - - item - Selected set of nodes. - - (blank) - Prints the summed element nodal loads for all selected nodes (default), - excluding contact elements. - - CONT - Prints the summed element nodal loads for contact nodes only. - - BOTH - Prints the summed element nodal loads for all selected nodes, including contact - nodes. - - Notes - ----- - Prints the summed element nodal loads (forces, moments, heat flows, - flux, etc.) for the selected nodes in the sorted sequence. Results are - in the global Cartesian coordinate directions unless transformed - [RSYS]. Zero values (within a tolerance range) are not printed. Loads - applied to a constrained degree of freedom are not included. The FORCE - command can be used to define which component of the nodal load is to - be used (static, damping, inertia, or total). - - By default, PRNLD excludes elements TARGE169 - CONTA177. Setting ITEM = - CONT will only account for nodal forces on selected contact elements - (CONTA171 - CONTA177). Setting ITEM = BOTH will account for nodal - forces on all selected nodes, including contact nodes. - """ - command = f"PRNLD,{lab},{tol},{item}" - return self.run(command, **kwargs) - - def prnsol(self, item="", comp="", **kwargs): - """Prints nodal solution results. - - APDL Command: PRNSOL - - Parameters - ---------- - item - Label identifying the item. Valid item labels are shown in - Table 225: PRNSOL - Valid Item and Component Labels below. Some - items also require a component label. - - comp - Component of the item (if required). Valid component labels are - shown in Table 225: PRNSOL - Valid Item and Component Labels below. - Defaults to COMP. - - Notes - ----- - Prints the nodal solution results for the selected nodes in the sorted - sequence. For example, PRNSOL,U,X prints the X component of - displacement vector U (that is, the UX degree of freedom). Component - results are in the global Cartesian coordinate directions unless - transformed (RSYS). Various element results also depend upon the - recalculation method and the selected results location (AVPRIN, RSYS, - LAYER, SHELL, and NSEL). If the LAYER command is issued, then the - resulting output is listed in full graphics mode (/GRAPHICS,FULL). You - can use the FORCE command to define which component of the nodal load - (static, damping, inertia, or total) should be used. - - PowerGraphics can affect your nodal solution listings. For - PowerGraphics (/GRAPHICS,POWER), results are listed only for the model - exterior surfaces. - - When shell element types are present, results are output on a surface- - by-surface basis. For shell elements, such as SHELL181 or SHELL281, and - for ELBOW290, printed output is for both the top and bottom surfaces. - For solid elements such as SOLID185, the output is averaged for each - surface and printed as follows: - - For a node at a vertex, three lines are output (one printed line for - each surface). - - For a node on an edge, two lines are output (one printed line for each - surface). - - For nodes on a face, one value is output. - - For nodes interior to the volume, no printed values are output. - - If a node is common to more than one element, or if a geometric - discontinuity exists, several conflicting listings may result. For - example, a corner node incorporating results from solid elements and - shell elements could yield as many as nine different results; the - printed output would be averages at the top and bottom for the three - shell surfaces plus averages at the three surfaces for the solid, for a - total of nine lines of output. ANSYS does not average result listings - across geometric discontinuities when shell element types are present. - It is important to analyze the listings at discontinuities to ascertain - the significance of each set of data. - - The printed output for full graphics (/GRAPHICS,FULL) follows the - standard ANSYS convention of averaging results at the node. For shell - elements, the default for display is TOP so that the results for the - top of the shell are averaged with the other elements attached to that - node. - - If an NSORT, ESORT or /ESHAPE command is issued with PowerGraphics - activated, then the PRNSOL listings will be the same as in full - graphics mode (/GRAPHICS,FULL). The items marked with [2] are not - supported by PowerGraphics. To print midside nodes, you must first - issue an /EFACET,2 command. - - Table: 225:: : PRNSOL - Valid Item and Component Labels - - Failure criteria [2][4]. - - Default components: Maximum of all failure criteria defined at current - location (MAX), maximum strain (EMAX), maximum stress (SMAX), Tsai-Wu - Strength Index (TWSI), inverse of Tsai-Wu Strength Ratio Index (TWSR). - """ - command = f"PRNSOL,{item},{comp}" - return self.run(command, **kwargs) - - def prrfor(self, lab="", **kwargs): - """Prints the constrained node reaction solution. Used with the FORCE - - APDL Command: PRRFOR - command. - - Parameters - ---------- - lab - Nodal reaction load type. If blank, use the first ten of all - available labels. Valid labels are: - - Notes - ----- - PRRFOR has the same functionality as the PRRSOL command; use PRRFOR - instead of PRRSOL when a FORCE command has been issued. - - In a non-spectrum analysis, if either contact or pretension elements - exist in the model, PRRFOR uses the PRRSOL command internally and the - FORCE setting is ignored. - - Because modal displacements cannot be used to calculate contact element - nodal forces,: those forces are not included in the spectrum and PSD - analyses reaction solution. As a consequence, the: PRRFOR: command is - not supported when constraints on contact element pilot nodes are - present. - """ - command = f"PRRFOR,{lab}" - return self.run(command, **kwargs) - - def prrsol(self, lab="", **kwargs): - """Prints the constrained node reaction solution. - - APDL Command: PRRSOL - - Parameters - ---------- - lab - Nodal reaction load type. If blank, use the first ten of all - available labels. Valid labels are: - - Notes - ----- - Prints the constrained node reaction solution for the selected nodes in - the sorted sequence. For coupled nodes and nodes in constraint - equations, the sum of all reactions in the coupled or constraint - equation set appears at the primary node of the set. Results are in - the global Cartesian coordinate directions unless transformed (RSYS). - - PRRSOL is not valid if any load is applied to a constrained node in the - direction of the constraint and any of the following is true: - - LCOPER has been used. - - LCASE has been used to read from a load case file. - - The applied loads and constraints in the database are not the ones used - to create the results data being processed. - - PRRSOL provides the total reaction solution (static, plus damping, plus - inertial, as appropriate based on the analysis type); however, modal - reactions include only the static contribution. - - Use PRRFOR instead of PRRSOL with the FORCE command to obtain only the - static, damping, or inertial components. - """ - command = f"PRRSOL,{lab}" - return self.run(command, **kwargs) - - def prvect(self, item="", lab2="", lab3="", labp="", **kwargs): - """Prints results as vector magnitude and direction cosines. - - APDL Command: PRVECT - - Parameters - ---------- - item - Predefined vector item (from Table 226: PRVECT - Valid Item and - Component Labels below) or a label identifying the i-component of a - user-defined vector. - - lab2 - Label identifying the j-component of a user-defined vector. In most - cases, this value must be blank if Item is selected from - Table 226: PRVECT - Valid Item and Component Labels. Individual - principal stresses (Item = S) or principal strains (Item = EPxx) - may be printed by specifying the value as 1, 2, or 3. - - lab3 - Label identifying the k-component of a user-defined vector. Must - be blank if Item is selected from list below or for 2-D user - defined vector. - - labp - Label assigned to resultant vector for printout labeling (defaults - to Item). - - Notes - ----- - Prints various solution results as vector magnitude and direction - cosines for the selected nodes and/or elements. For example, PRVECT,U - prints the displacement magnitude and its direction cosines for all - selected nodes. For nodal degree of freedom vector results, direction - cosines are with respect to the results coordinate system RSYS. For - element results, direction cosines are with respect to the global - Cartesian system. Item components may be printed with the PRNSOL - command. Various results also depend upon the recalculation method and - the selected results location [LAYER, SHELL, NSEL, and ESEL]. Items - may be selected from a set of recognized vector labels (Item) or a - vector may be defined from up to three scalar labels (Item,Lab2,Lab3). - Scalar labels may be user-defined with the ETABLE command. - - Portions of this command are not supported by PowerGraphics - [/GRAPHICS,POWER]. - - Table: 226:: : PRVECT - Valid Item and Component Labels - """ - command = f"PRVECT,{item},{lab2},{lab3},{labp}" - return self.run(command, **kwargs) - - def sumtype(self, label="", **kwargs): - """Sets the type of summation to be used in the following load case - - APDL Command: SUMTYPE - operations. - - Parameters - ---------- - label - Summation type - - COMP - Combine element component stresses only. Stresses such as average nodal - stresses, principal stresses, equivalent stresses, and - stress intensities are derived from the combined element - component stresses. Default. - - PRIN - Combine principal stress, equivalent stress, and stress intensity directly as - stored on the results file. Component stresses are not - available with this option. - - Notes - ----- - Issue SUMTYPE,PRIN when you want to have a load case operation (LCOPER) - act on the principal / equivalent stresses instead of the component - stresses. Also issue SUMTYPE,PRIN when you want to read in load cases - (LCASE). Note that the SUMTYPE setting is not maintained between /POST1 - sessions. - - SUMTYPE,PRIN also causes principal nodal values to be the average of - the contributing principal element nodal values (see AVPRIN,1). - - BEAM188 and BEAM189 elements compute principal stress, equivalent - stress, and stress intensity values on request instead of storing them - on the results file; SUMTYPE,PRIN does not apply for these elements. - """ - command = f"SUMTYPE,{label}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1_/setup.py b/src/ansys/mapdl/core/_commands/post1_/setup.py deleted file mode 100644 index cea5f10075..0000000000 --- a/src/ansys/mapdl/core/_commands/post1_/setup.py +++ /dev/null @@ -1,768 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class Setup: - def append( - self, - lstep="", - sbstep="", - fact="", - kimg="", - time="", - angle="", - nset="", - **kwargs, - ): - """Reads data from the results file and appends it to the database. - - APDL Command: APPEND - - Parameters - ---------- - lstep - Load step number of the data set to be read. Defaults to 1. If - FIRST, ignore SBSTEP and TIME and read the first data set. If - LAST, ignore SBSTEP and TIME and read the last data set. If NEXT, - ignore SBSTEP and TIME and read the next data set. If already at - the last data set, the next set is the first data set. If NEAR, - ignore SBSTEP and read the data set nearest to TIME. If TIME is - blank, read the first data set. If LIST, scan the results file to - produce a summary of each load step (FACT, KIMG, TIME and ANGLE - are ignored). - - sbstep - Substep number (within LSTEP) (defaults to last substep of load - step). For the Buckling (ANTYPE,BUCKLE) or Modal (ANTYPE,MODAL) - analysis, the substep corresponds to the mode number (defaults to - first mode). If LSTEP = LIST, SBSTEP = 0 or 1 will list the basic - load step information; SBSTEP = 2 will also list the load step - title, and label the imaginary data sets if they exist. - - fact - Scale factor applied to data read from the file. If zero (or - blank), a value of 1.0 is used. Harmonic velocities or - accelerations may be calculated from the displacement results from - a modal or harmonic (ANTYPE,HARMIC) analyses. If FACT = VELO, the - harmonic velocities (v) are calculated from the displacements (d) - at a particular frequency (f) according to the relationship v = - 2 πfd. Similarly, if FACT = ACEL, the harmonic accelerations (a) - are calculated as a = (2 πf)2d. - - kimg - Used only with results from complex analyses: - - 0 - Store real part of complex solution. - - 1 - Store imaginary part. - - time - Time-point identifying the data set to be read. For harmonic - analyses, time corresponds to the frequency. For the buckling - analysis, time corresponds to the load factor. Used only in the - following cases: If LSTEP is NEAR, read the data set nearest to - TIME. If both LSTEP and SBSTEP are zero (or blank), read data set - at time = TIME. If TIME is between two solution time points on the - results file, a linear interpolation is done between the two data - sets. Solution items not written to the results file [OUTRES] for - either data set will result in a null item after data set - interpolation. If TIME is beyond the last time point on the file, - the last time point is used. - - angle - Circumferential location (0° to 360°). Defines the circumferential - location for the harmonic calculations used when reading from the - results file. The harmonic factor (based on the circumferential - angle) is applied to the harmonic elements (PLANE25, PLANE75, - PLANE78, PLANE83, and SHELL61) of the load case. See the - Mechanical APDL Theory Reference for details. Note that factored - values of applied constraints and loads will overwrite any values - existing in the database. - - nset - Data set number of the data set to be read. If a positive value - for NSET is entered, LSTEP, SBSTEP, KIMG, and TIME are ignored. - Available set numbers can be determined by APPEND,LIST. To - determine if data sets are real or imaginary, issue APPEND,LIST,2 - which labels imaginary data sets. - - Notes - ----- - Reads a data set from the results file and appends it to the existing - data in the database for the selected model only. The existing - database is not cleared (or overwritten in total), allowing the - requested results data to be merged into the database. Various - operations may also be performed during the read operation. The - database must have the model geometry available (or used the RESUME - command before the APPEND command to restore the geometry from - File.DB). - """ - command = f"APPEND,{lstep},{sbstep},{fact},{kimg},{time},{angle},{nset}" - return self.run(command, **kwargs) - - def desol( - self, - elem="", - node="", - item="", - comp="", - v1="", - v2="", - v3="", - v4="", - v5="", - v6="", - **kwargs, - ): - """Defines or modifies solution results at a node of an element. - - APDL Command: DESOL - - Parameters - ---------- - elem - Element number for which results are defined or modified. If ALL, - apply to all selected elements [ESEL]. - - node - Node of element (actual node number, not the position) to which - results are specified. If ALL, specify results for all selected - nodes [NSEL] of element. If NODE = P, graphical picking is enabled - and all remaining command fields are ignored (valid only in the - GUI). A component name may also be substituted for NODE. - - item - Label identifying results. Valid item labels are shown in - Table 129: DESOL - Valid Item and Component Labels below. Some - items also require a component label (Comp). - - comp - Component of the item (if required); see Table 129: DESOL - Valid - Item and Component Labels. - - v1 - Value (in the element coordinate system) assigned to the database - item (and component, if any). If zero, a zero value will be - assigned. If blank, value remains unchanged. - - v2, v3, v4, . . . , v6 - Additional values (if any) assigned to the remaining components (in - the order corresponding to the Comp list shown below) for the - specified Item (starting from the specified Comp label and - proceeding to the right). - - Notes - ----- - The DESOL command defines or modifies solution results in the database - at a node of an area or volume element. For example, - DESOL,35,50,S,X,1000,2000,1000 assigns values 1000, 2000, and 1000 to - SX, SY, and SZ (respectively) of node 50 of element 35. - - The settings of the POST1 FORCE, SHELL, and LAYER commands, if - applicable, further specify which database items are affected. - - For layered composite shells, specify the current element layer (LAYER) - before issuing the DESOL command. - - All data is stored in the solution coordinate system but is displayed - in the results coordinate system (RSYS). To list the current results, - use the PRESOL command. - - Modified solution results are not saved automatically. To save separate - records of modified results, use either the RAPPND or LCWRITE command. - - Result items are available depending on element type; check the - individual element for availability. Valid item and component labels - for element results are: - - Table: 129:: : DESOL - Valid Item and Component Labels - """ - command = f"DESOL,{elem},{node},{item},{comp},{v1},{v2},{v3},{v4},{v5},{v6}" - return self.run(command, **kwargs) - - def dnsol( - self, - node="", - item="", - comp="", - v1="", - v2="", - v3="", - v4="", - v5="", - v6="", - **kwargs, - ): - """Defines or modifies solution results at a node. - - APDL Command: DNSOL - - Parameters - ---------- - node - Node for which results are specified. If ALL, apply to all - selected nodes [NSEL]. If NODE = P, graphical picking is enabled - and all remaining command fields are ignored (valid only in the - GUI). A component name may also be substituted for NODE. - - item - Label identifying results, see Table 131: DNSOL - Valid Item and - Component Labels. Items also require a component label. - - comp - Component of the item. Valid component labels are shown - Table 131: DNSOL - Valid Item and Component Labels below. - - v1, v2, v3, . . . , v6 - Value assigned to result. If zero, a zero value will be assigned. - If blank, the value remains unchanged. Additional values (if any) - assigned to the remaining components (in the order corresponding to - the Comp list shown below for the specified Item (starting from the - specified Comp label and proceeding to the right). - - Notes - ----- - DNSOL can be used only with FULL graphics activated (/GRAPHICS,FULL); - it will not work correctly with PowerGraphics activated. - - DNSOL defines or modifies solution results in the database at a node. - For example, DNSOL,35,U,X,.001,.002,.001 assigns values 0.001, 0.002, - and 0.001 to UX, UY, and UZ (respectively) for node 35. All results - that are changed in the database, including the nodal degree of freedom - results, are available for all subsequent operations. All data is - stored in the solution coordinate system, but will be displayed in the - results coordinate system [RSYS]. Use the PRNSOL command to list the - current results. - - Data input by DNSOL is stored in temporary space and does not replace - information in the database. Therefore, data input by this command may - be overwritten if a change is made to the selected set of nodes. - - Issuing the DNSOL command or its GUI equivalent requires you to place - the data type (stress/strain) in the element nodal records. To get - around this requirement, use the DESOL command or equivalent path to - add a "dummy" element stress/strain record. - - Result items are available depending on element type; check the - individual element for availability. Valid item and component labels - for element results are: - - Table: 131:: : DNSOL - Valid Item and Component Labels - - For SHELL131 and SHELL132 elements with KEYOPT(3) = 0 or 1, use the - labels TBOT, TE2, TE3, ..., TTOP instead of TEMP. - """ - command = f"DNSOL,{node},{item},{comp},{v1},{v2},{v3},{v4},{v5},{v6}" - return self.run(command, **kwargs) - - def hrcplx( - self, - loadstep="", - substep="", - omegat="", - firstlc_ase="", - secondlc_ase="", - **kwargs, - ): - """Computes and stores in the database the time-harmonic solution at a - - APDL Command: HRCPLX - prescribed phase angle. - - Parameters - ---------- - loadstep - Load step number of the data set to be read (defaults to 1). - - substep - Substep number within LOADSTEP. - - omegat - Angle in degrees (Ω (angle) times T (time)). - - 1stlcase - First load case number (defaults to 1). - - 2ndlcase - Second load case number (defaults to 2). - - Notes - ----- - HRCPLX invokes a macro that combines the real and imaginary parts of - the solution. If the angle is specified, it produces the following: - - Where: - - RR and RI are, respectively, the real and imaginary parts of the - results quantity (e.g. the nodal displacements, the reaction forces, - ...). - - α is the angle (OMEGAT). - - 1STLCASE and 2NDLCASE are internally generated load cases. You may want - to specify these to avoid overwriting an existing load case number 1 or - 2. - - Not all results computed by this command are valid. See Summable, Non- - Summable and Constant Data in the Basic Analysis Guide for more - information. When the amplitude of the solution is requested (OMEGAT >= - 360°), averaged values (such as the nodal component stresses, which are - an average of element nodal component stresses) are calculated by - averaging the amplitudes. Because the degrees of freedom results have - different phases, derived results (such as the equivalent stress SEQV) - are not valid. See POST1 and POST26 – Complex Results Postprocessing - for more details about post-processing complex results. - - For postprocessing amplitudes, the only appropriate coordinate system - is the solution coordinate system (RSYS ,SOLU). When displaying the - displacement amplitudes, use a contour display (PLNSOL command). - Because a deformed shape display (PLDISP command) could lead to a non- - physical shape, the displacement scaling is off by default - (/DSCALE,,OFF). - - For postprocessing cylindrical geometry, it is suggested that you - rotate the element coordinate systems into the appropriate cylindrical - system (EMODIF,,ESYS) before running the solution and then view the - results in this system (RSYS,SOLU) in POST1. - - Since HRCPLX performs load case combinations, it alters most of the - data in the database. In particular, it alters applied loads such as - forces and imposed displacements. To restore the original loads in the - database for a subsequent analysis, reissue the SET command in POST1 to - retrieve the real and imaginary set data. - - To animate the solution over one period, use the ANHARM command. - - OMEGAT is not equal to the phase shift. - - This command is not supported after a cyclic symmetry analysis; use - /CYCEXPAND,,PHASEANG instead. - """ - command = f"HRCPLX,{loadstep},{substep},{omegat},{firstlc_ase},{secondlc_ase}" - return self.run(command, **kwargs) - - def rescombine( - self, - numfiles="", - fname="", - ext="", - lstep="", - sbstep="", - fact="", - kimg="", - time="", - angle="", - nset="", - order="", - **kwargs, - ): - """Reads results from local results files into the database after a - - APDL Command: RESCOMBINE - distributed memory parallel (Distributed ANSYS) solution. - - Parameters - ---------- - numfiles - Number of local results files that are to be read into the database - from the distributed memory parallel solution. This number should - be equal to the number of processes used in the parallel solution. - - fname - File name (jobname) used during the distributed parallel solution. - The file name must be an alphanumeric string (up to 32 characters) - enclosed in single quotes. - - ext - File extension for the results files (for example, RST, RTH, RMG, - etc.). The file extension must be an alphanumeric string (up to 8 - characters) enclosed in single quotes. - - lstep - Load step number of the data set to be read (defaults to 1): - - N - Read load step N. - - FIRST - Read the first data set (Sbstep and TIME are ignored). - - LAST - Read the last data set (Sbstep and TIME are ignored). - - NEXT - Read the next data set (Sbstep and TIME are ignored). If at the last data set, - the first data set will be read as the next. - - PREVIOUS - Read the previous data set (Sbstep and TIME are ignored). If at the first data - set, the last data set will be read as the previous. - - NEAR - Read the data set nearest to TIME (Sbstep is ignored). If TIME is blank, read - the first data set. - - LIST - Scan the results files and list a summary of each load step (KIMG, TIME, ANGLE, - NSET, and ORDER are ignored.) - - sbstep - Substep number within Lstep (defaults to the last substep of the - load step). For a buckling (ANTYPE,BUCKLE) or modal (ANTYPE,MODAL) - analysis, Sbstep corresponds to the mode number (defaults to the - first mode). Specify Sbstep = LAST to store the last substep for - the specified load step. - - fact - Scale factor applied to data read from the files. If zero (or - blank), a value of 1.0 is used. A nonzero factor excludes non- - summable items. Harmonic velocities or accelerations may be - calculated from the displacement results from a modal - (ANTYPE,MODAL) or harmonic (ANTYPE,HARMIC) analysis. If Fact = - VELO, the harmonic velocities (v) are calculated from the - displacements (d) at a particular frequency (f) according to the - relationship v = 2πfd. Similarly, if Fact = ACEL, the harmonic - accelerations (a) are calculated as a = (2πf)2d. - - kimg - Used only with complex results (harmonic and complex modal - analyses). - - 0 or REAL - Store the real part of a complex solution (default). - - 1, 2 or IMAG - Store the imaginary part of a complex solution. - - 3 or AMPL - Store the amplitude. - - 4 or PHAS - Store the phase angle. The angle value, expressed in degrees, will be between - -180° and +180°. - - time - Time-point identifying the data set to be read. For a harmonic - analysis, time corresponds to the frequency. For a buckling - analysis, time corresponds to the load factor. Used only in the - following cases: If Lstep = NEAR, read the data set nearest to - TIME. If both Lstep and Sbstep are zero (or blank), read data set - at time = TIME. If TIME is between two solution time points on the - results file, a linear interpolation is done between the two data - sets. Solution items not written to the results file (OUTRES) for - either data set will result in a null item after data set - interpolation. If TIME is beyond the last time point on the file, - the last time point will be used. - - angle - Circumferential location (0.0 to 360°). Defines the circumferential - location for the harmonic calculations used when reading from the - results file. The harmonic factor (based on the circumferential - angle) is applied to the harmonic elements (PLANE25, PLANE75, - PLANE78, PLANE83, and SHELL61) of the load case. See the Mechanical - APDL Theory Reference for details. Note that factored values of - applied constraints and loads will overwrite any values existing in - the database. - - nset - Data set number of the data set to be read. If a positive value for - NSET is entered, Lstep, Sbstep, KIMG, and TIME are ignored. - Available set numbers can be determined by RESCOMBINE,,,,LIST. - - order - Key to sort the harmonic index results. This option applies to - cyclic symmetry buckling and modal analyses only, and is valid only - when Lstep = FIRST, LAST, NEXT, PREVIOUS, NEAR or LIST. - - ORDER - Sort the harmonic index results in ascending order of eigenfrequencies or - buckling load multipliers. - - (blank) - No sorting takes place. - - Notes - ----- - RESCOMBINE is an ANSYS command macro that allows you to combine results - from a distributed memory parallel (Distributed ANSYS) solution. In a - distributed memory parallel solution, a global results file is saved by - default. However, if you issued DMPOPTION,RST,NO in the parallel - solution, no global results file is written and all local results files - will be kept. In this case, you can use the RESCOMBINE command macro in - the general postprocessor (/POST1) to read results into the database - for postprocessing. - - In order to use the RESCOMBINE command, all local results files from - the distributed memory parallel solution must be in the current working - directory. If running on a single machine, the local results files are - saved in the working directory by default. If running on a cluster, the - local results files are kept in the working directory on each compute - node. For this latter case, you must copy the local results files to - the working directory on the primary compute node. - - Similar to the SET command, the RESCOMBINE command macro defines the - data set to be read from the results files into the database. Various - operations may also be performed during the read operation (see the SET - command for more details). The database must have the model data - available (or use the RESUME command before the RESCOMBINE command to - restore the geometry from Jobname.DB). - - After a set of data is combined into the database using RESCOMBINE, the - RESWRITE command can be used to write this set of data into a new - results file. This new results file will essentially contain the - current set of results data for the entire (i.e., global) model. - """ - command = f"RESCOMBINE,{numfiles},{fname},{ext},{lstep},{sbstep},{fact},{kimg},{time},{angle},{nset},{order}" - return self.run(command, **kwargs) - - def set( - self, - lstep="", - sbstep="", - fact="", - kimg="", - time="", - angle="", - nset="", - order="", - **kwargs, - ): - """Defines the data set to be read from the results file. - - APDL Command: SET - - Parameters - ---------- - lstep - Load step number of the data set to be read (defaults to 1): - - N - Read load step N. - - FIRST - Read the first data set (``Sbstep`` and ``TIME`` are ignored). - - LAST - Read the last data set (``Sbstep`` and ``TIME`` are ignored). - - NEXT - Read the next data set (``Sbstep`` and ``TIME`` are ignored). If at the last data set, - the first data set will be read as the next. - - PREVIOUS - Read the previous data set (``Sbstep`` and ``TIME`` are ignored). If at the first data - set, the last data set will be read as the previous. - - NEAR - Read the data set nearest to ``TIME`` (``Sbstep`` is ignored). If ``TIME`` is blank, read - the first data set. - - LIST - Scan the results file and list a summary of each load step. (``KIMG``, ``TIME``, - ``ANGLE``, and ``NSET`` are ignored.) - - .. versionchanged:: 0.64 - From version 0.64 you can use the methods ``to_list`` and - ``to_array`` on the object returning from ``mapdl.set("list")``. - - sbstep - Substep number (within Lstep). Defaults to the last substep of the - load step (except in a buckling or modal analysis). For a buckling - (``ANTYPE,BUCKLE``) or modal (``ANTYPE,MODAL``) analysis, ``Sbstep`` - corresponds to the mode number. Specify ``Sbstep = LAST`` to store the - last substep for the specified load step (that is, issue a - ``SET,Lstep,LAST`` command). - - fact - Scale factor applied to data read from the file. If zero (or - blank), a value of 1.0 is used. This scale factor is only applied - to displacement and stress results. A nonzero factor excludes non- - summable items. - - kimg - Used only with complex results (harmonic and complex modal - analyses). - - 0 or REAL - Store the real part of complex solution (default). - - 1, 2 or IMAG - Store the imaginary part of a complex solution. - - 3 or AMPL - Store the amplitude - - 4 or PHAS - Store the phase angle. The angle value, expressed in degrees, - will be between -180° and +180°. - - time - Time-point identifying the data set to be read. For a harmonic - analyses, time corresponds to the frequency. - - angle - Circumferential location (0.0 to 360°). Defines the - circumferential location for the harmonic calculations used when - reading from the results file. - - nset - Data set number of the data set to be read. If a positive value - for ``NSET`` is entered, ``Lstep``, ``Sbstep``, ``KIMG``, and ``TIME`` are ignored. - Available set numbers can be determined by ``SET,LIST``. - - order - Key to sort the harmonic index results. This option applies to - cyclic symmetry buckling and modal analyses only, and is valid only - when ``Lstep = FIRST, LAST, NEXT, PREVIOUS, NEAR or LIST``. - - ORDER - Sort the harmonic index results in ascending order of eigenfrequencies or - buckling load multipliers. - - (blank) - No sorting takes place. - - Notes - ----- - Defines the data set to be read from the results file into the - database. Various operations may also be performed during the read - operation. The database must have the model geometry available (or use - the ``RESUME`` command before the ``SET`` command to restore the geometry from - ````). Values for applied constraints [``D``] and loads [``F``] in the - database will be replaced by their corresponding values on the results - file, if available. (See the description of the ``OUTRES`` command.) In a - single load step analysis, these values are usually the same, except - for results from harmonic elements. (See the description of the ANGLE - value above.) - - In an interactive run, the sorted list (``ORDER`` option) is also available - for results-set reading via a GUI pick option. - - You can postprocess results without issuing a ``SET`` command if the - solution results were saved to the database file (````). - Distributed ANSYS, however, can only postprocess using the results file - (for example, Jobname.RST) and cannot use the ```` file since no - solution results are written to the database. Therefore, you must issue - a ``SET`` command or a ``RESCOMBINE`` command before postprocessing in - Distributed ANSYS. - """ - command = f"SET,{lstep},{sbstep},{fact},{kimg},{time},{angle},{nset},{order}" - return self.run(command, **kwargs) - - def subset( - self, - lstep="", - sbstep="", - fact="", - kimg="", - time="", - angle="", - nset="", - **kwargs, - ): - """Reads results for the selected portions of the model. - - APDL Command: SUBSET - - Parameters - ---------- - lstep - Load step number of the data set to be read (defaults to 1): - - N - Read load step N. - - FIRST - Read the first data set (``SBSTEP`` and ``TIME`` are ignored). - - LAST - Read the last data set (``SBSTEP`` and ``TIME`` are ignored). - - NEXT - Read the next data set (``SBSTEP`` and ``TIME`` are ignored). If at the last data set, - the first data set will be read as the next. - - NEAR - Read the data set nearest to ``TIME`` (``SBSTEP`` is ignored). If ``TIME`` is blank, read - the first data set. - - LIST - Scan the results file and list a summary of each load step. (``FACT``, ``KIMG``, ``TIME`` - and ``ANGLE`` are ignored.) - - sbstep - Substep number (within Lstep). For the buckling (``ANTYPE,BUCKLE``) - analysis or the modal (``ANTYPE,MODAL``) analysis, the substep - corresponds to the mode number. Defaults to last substep of load - step (except for ``ANTYPE,BUCKLE or MODAL``). If ``Lstep = LIST, SBSTEP - = 0 or 1`` lists the basic step information, whereas ``SBSTEP = 2`` also - lists the load step title, and labels imaginary data sets if they - exist. - - fact - Scale factor applied to data read from the file. If zero (or - blank), a value of 1.0 is used. Harmonic velocities or - accelerations may be calculated from the displacement results from - a modal (``ANTYPE,MODAL``) or harmonic (``ANTYPE,HARMIC``) analyses. If - ``FACT = VELO``, the harmonic velocities (v) are calculated from the - displacements (d) at a particular frequency (f) according to the - relationship v = 2 πfd. Similarly, if ``FACT = ACEL``, the harmonic - accelerations (a) are calculated as a = (2 πf)2d. - - kimg - Used only with results from complex analyses: - - 0 - Store real part of complex solution - - 1 - Store imaginary part. - - time - Time-point identifying the data set to be read. For harmonic - analyses, time corresponds to the frequency. For the buckling - analysis, time corresponds to the load factor. Used only in the - following cases: If Lstep is ``NEAR``, read the data set nearest to - ``TIME``. If both Lstep and ``SBSTEP`` are zero (or blank), read data set - at time = ``TIME``. If ``TIME`` is between two solution time points on the - results file, a linear interpolation is done between the two data - sets. Solution items not written to the results file [OUTRES] for - either data set will result in a null item after data set - interpolation. If ``TIME`` is beyond the last time point on the file, - use the last time point. - - angle - Circumferential location (0.0 to 360°). Defines the - circumferential location for the harmonic calculations used when - reading from the results file. The harmonic factor (based on the - circumferential angle) is applied to the harmonic elements - (``PLANE25``, ``PLANE75``, ``PLANE78``, ``PLANE83``, and ``SHELL61``) of the load case. - See the Mechanical APDL Theory Reference for details. Note that - factored values of applied constraints and loads will overwrite any - values existing in the database. - - nset - Data set number of the data set to be read. If a positive value - for ``NSET`` is entered, ``Lstep``, ``SBSTEP``, ``KIMG``, and ``TIME`` are ignored. - Available set numbers can be determined by ``*SET,LIST``. - - Notes - ----- - Reads a data set from the results file into the database for the - selected portions of the model only. Data that has not been specified - for retrieval from the results file by the ``INRES`` command will be listed - as having a zero value. Each time that the ``SUBSET`` command is issued, - the data currently in the database will be overwritten with a new set - of data. Various operations may also be performed during the read - operation. The database must have the model geometry available (or - used the RESUME command before the ``SUBSET`` command to restore the - geometry from ``File.DB``). - """ - command = f"SUBSET,{lstep},{sbstep},{fact},{kimg},{time},{angle},{nset}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1_/special.py b/src/ansys/mapdl/core/_commands/post1_/special.py deleted file mode 100644 index 2f3333963f..0000000000 --- a/src/ansys/mapdl/core/_commands/post1_/special.py +++ /dev/null @@ -1,2523 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class Special: - def bfint( - self, - fname1="", - ext1="", - fname2="", - ext2="", - kpos="", - clab="", - kshs="", - tolout="", - tolhgt="", - **kwargs, - ): - """Activates the body force interpolation operation. - - APDL Command: BFINT - - Parameters - ---------- - fname1 - File name and directory path (248 characters maximum, - including directory) from which to read data for - interpolation. If you do not specify a directory path, it - will default to your working directory and you can use all - 248 characters for the file name. - - ext1 - Filename extension (eight-character maximum). - - fname2 - File name and directory path (248 characters maximum, - including directory) to which BF commands are written. If - you do not specify a directory path, it will default to - your working directory and you can use all 248 characters - for the file name. - - ext2 - Filename extension (eight-character maximum). - - kpos - Position on Fname2 to write block of BF commands: - - 0 - Beginning of file (overwrite existing file). - - 1 - End of file (append to existing file). - - clab - Label (8 characters maximum, including the colon) for this - block of BF commands in Fname2. This label is appended to - the colon (:). Defaults to BFn, where n is the cumulative - iteration number for the data set currently in the - database. - - kshs - Shell-to-solid submodeling key: - - 0 - Solid-to-solid or shell-to-shell submodel. - - 1 - Shell-to-solid submodel. - - tolout - Extrapolation tolerance about elements, based on a - fraction of the element dimension. Submodel nodes outside - the element by more than TOLOUT are not accepted as - candidates for DOF extrapolation. Defaults to 0.5 (50%). - - tolhgt - Height tolerance above or below shell elements, in units - of length. Used only for shell-to-shell submodeling (KSHS - = 0). Submodel nodes off the element surface by more than - TOLHGT are not accepted as candidates for DOF - interpolation or extrapolation. Defaults to 0.0001 times - the maximum element dimension. - - Notes - ----- - File Fname1 should contain a node list for which body forces are to be - interpolated [NWRITE]. File Fname2 is created, and contains - interpolated body forces written as a block of nodal BF commands. - - Body forces are interpolated from elements having TEMP as a valid body - force or degree of freedom, and only the label TEMP is written on the - nodal BF commands. Interpolation is performed for all nodes on file - Fname1 using the results data currently in the database. For layered - elements, use the LAYER command to select the locations of the - temperatures to be used for interpolation. Default locations are the - bottom of the bottom layer and the top of the top layer. - - The block of BF commands begins with an identifying colon label command - and ends with a /EOF command. The colon label command is of the form - :Clab, where Clab is described above. Interpolation from multiple - results sets can be performed by looping through the results file in a - user-defined macro. Additional blocks can be appended to Fname2 by - using KPOS and unique colon labels. A /INPUT command, with the - appropriate colon label, may be used to read the block of commands. - - If the model has coincident (or very close) nodes, BFINT must be - applied to each part of the model separately to ensure that the mapping - of the nodes is correct. For example, if nodes belonging to two - adjacent parts linked by springs are coincident, the operation should - be performed on each part of the model separately. - """ - command = f"BFINT,{fname1},{ext1},,{fname2},{ext2},,{kpos},{clab},{kshs},{tolout},{tolhgt}" - return self.run(command, **kwargs) - - def cbdof( - self, - fname1="", - ext1="", - fname2="", - ext2="", - kpos="", - clab="", - kshs="", - tolout="", - tolhgt="", - tolthk="", - **kwargs, - ): - """Activates cut-boundary interpolation (for submodeling). - - APDL Command: CBDOF - - Parameters - ---------- - fname1 - File name and directory path (248 characters maximum, - including directory) from which to read boundary node - data. If no specified directory path exists, the path - defaults to your working directory and you can use all 248 - characters for the file name. - - ext1 - Filename extension (eight-character maximum). - - fname2 - File name and directory path (248 characters maximum, - including directory) to which cut-boundary D commands are - written. If no specified directory path exists, the path - defaults to your working directory and you can use all 248 - characters for the file name. - - ext2 - Filename extension (eight-character maximum). - - kpos - Position on Fname2 to write block of D commands: - - 0 - Beginning of file (overwrite existing file). - - 1 - End of file (append to existing file). - - clab - Label (eight characters maximum, including the colon) for - this block of D commands on Fname2. his label is appended - to the colon (:). Defaults to CBn, where n is the - cumulative iteration number for the data set currently in - the database. For imaginary data (see KIMG on the ``*SET`` - command), Clab defaults to CIn. - - kshs - Shell-to-solid submodeling key: - - 0 - Solid-to-solid or shell-to-shell submodel. - - 1 - Shell-to-solid submodel. - - tolout - Extrapolation tolerance about elements, based on a - fraction of the element dimension. Submodel nodes outside - the element by more than TOLOUT are not accepted as - candidates for DOF extrapolation. Defaults to 0.5 (50 - percent). - - tolhgt - Height tolerance above or below shell elements, in units - of length. Used only for shell-to-shell submodeling (KSHS - = 0). Submodel nodes off the element surface by more than - TOLHGT are not accepted as candidates for - degree-of-freedom interpolation or extrapolation. - Defaults to 0.0001 times the maximum element dimension. - - tolthk - Height tolerance above or below shell elements, based on a - fraction of the shell element thickness. Used only for - shell-to-solid submodeling (KSHS = 1). Submodel nodes off - the element surface by more than TOLTHK are not accepted - as candidates for DOF interpolation or - extrapolation. Defaults to 0.1 times the average shell - thickness. - - Notes - ----- - File Fname1 should contain a node list for which boundary - conditions are to be interpolated (NWRITE). File Fname2 is - created to contain interpolated boundary conditions written as - a block of D commands. - - Boundary conditions are written for the active - degree-of-freedom set for the element from which interpolation - is performed. Interpolation occurs on the selected set of - elements. The block of D commands begins with an identifying - colon label and ends with a /EOF command. The colon label is - of the form :Clab (described above). - - Interpolation from multiple results sets can be performed by - looping through the results file in a user-defined macro. - Additional blocks can be appended to Fname2 by using KPOS and - unique colon labels. To read the block of commands, issue the - /INPUT command with the appropriate colon label. - - If the model has coincident (or very close) nodes, the CBDOF - must be applied to each part of the model separately to ensure - that the mapping of the nodes is correct. For example, if - nodes belonging to two adjacent parts linked by springs are - coincident, the operation should be performed on each part of - the model separately. - - Resume the coarse model database at the beginning of the - cut-boundary procedure. The database should have been saved - after the first coarse model solution, as the number of nodes - in the database and the results file must match, and internal - nodes are sometimes created during the solution. - - Caution: Relaxing the TOLHGT or TOLTHK tolerances to allow - submodel nodes to be "found" can produce poor submodel - results. - """ - command = f"CBDOF,{fname1},{ext1},,{fname2},{ext2},,{kpos},{clab},{kshs},{tolout},{tolhgt},{tolthk}" - return self.run(command, **kwargs) - - def cmsfile(self, option="", fname="", ext="", cmskey="", **kwargs): - """Specifies a list of component mode synthesis (CMS) results files for - - APDL Command: CMSFILE - plotting results on the assembly. - - Parameters - ---------- - option - Specifies the command operation: - - ADD - Add the specified component results file (Fname) to the list of files to plot. - This option is the default. - - DELETE - Remove the specified component results file (Fname) from the list of files to - plot. - - LIST - List all specified component results files. - - CLEAR - Clear all previous files added. - - ALL - Add all component results (.rst) files from the working directory to the list - of files to plot. - - fname - The file name (with full directory path) of the component results - file. The default file name is the Jobname (specified via the - /FILNAME command). - - ext - The file name (Fname) extension. The default extension is .rst. - - cmskey - Valid only when adding a results file (Option = ADD or ALL), this - key specifies whether or not to check the specified .rst file to - determine if it was created via a CMS expansion pass: - - ON - Check (default). - - OFF - Do not check. - - Notes - ----- - The CMSFILE command specifies the list of component mode synthesis - (CMS) results files to include when plotting the mode shape of an - assembly. - - During postprocessing (/POST1) of a CMS analysis, issue the CMSFILE - command to point to component results files of interest. (You can issue - the command as often as needed to include all or some of the component - results files.) Issue the SET command to acquire the frequencies and - mode shapes from substeps for all specified results files. Execute a - plot (PLNSOL) or print (PRNSOL) operation to display the mode shape of - the entire assembly. - - When you specify a results file to add to the plot list, the default - behavior of the command (CmsKey = ON) is to first verify that the file - is from a CMS analysis and that the frequencies of the result sets on - the file match the frequencies on the first file in the list. If CmsKey - = OFF, you can add any .rst file to the list of files to plot, even if - the file was not expanded via a CMS expansion pass. - - If CmsKey = ON (default), output from the command appears as: ADD CMS - FILE = filename.rst. : If CmsKey = OFF, output from the command appears - as: ADD FILE = filename.rst. - - If Option = DELETE or CLEAR, you must clear the database (/CLEAR), then - re-enter the postprocessor (/POST1) and issue a SET command for the - change to take effect on subsequent plots. - - Clearing the database does not clear the list of files specified via - the CMSFILE command. Specify Option = CLEAR to clear the list of files. - """ - command = f"CMSFILE,{option},{fname},{ext},{cmskey}" - return self.run(command, **kwargs) - - def cyccalc(self, fileprefix="", fileformat="", **kwargs): - """Calculates results from a cyclic harmonic mode-superposition analysis - - APDL Command: CYCCALC - using the specifications defined by CYCSPEC. - - Parameters - ---------- - fileprefix - Each result table (corresponding to each CYCSPEC specification) is - written to a file beginning with FilePrefix. If blank (default), - the result tables are written to the output file. - - fileformat - If FilePrefix is specified, then use FileFormat to specify the - format of the file to be written: - - FORM - Formatted file (default) - - CSV - Comma-separated value file - - Notes - ----- - CYCCALC loops through the specification given by CYCSPEC and computes - the requested outputs. The outputs are given in a table format, with - the rows corresponding to each frequency solution from the harmonic - analysis, and the columns corresponding to each sector. The table - entries are the maximum value of the specified quantity at the - specified location in the sector. In addition, columns containing the - maximum value at the frequency, the sector in which it occurs, and the - node in the sector at which it occurs are output. - - If FilePrefix is specified, a file is created for each output table - with the name FilePrefix_node_type.ext, where node is the node number - or component name, type is the item/component requested, and the file - extension .ext is either .txt or .csv, depending on FileFormat. - - A SET command must precede the CYCCALC command. - - The CYCCALC results are based on the currently active RSYS, SHELL, - LAYER, and AVPRIN settings. - """ - command = f"CYCCALC,{fileprefix},{fileformat}" - return self.run(command, **kwargs) - - def cycfiles(self, fnamerst="", extrst="", fnamerfrq="", extrfrq="", **kwargs): - """Specifies the data files where results are to be found for a cyclic - - APDL Command: CYCFILES - symmetry mode-superposition harmonic analysis. - - Parameters - ---------- - fnamerst - The file name and directory path of the results file from the - cyclic modal solution. Defaults to Jobname. - - extrst - File name extension for FnameRst. Defaults to rst. - - fnamerfrq - The file name and directory path of the results file from the - cyclic mode-superposition harmonic solution. Defaults to the value - of the FnameRst argument. - - extrfrq - File name extension for FnameRfrq. Defaults to rfrq. - """ - command = f"CYCFILES,{fnamerst},{extrst},{fnamerfrq},{extrfrq}" - return self.run(command, **kwargs) - - def cycphase(self, type_="", option="", **kwargs): - """Provides tools for determining minimum and maximum possible result - - APDL Command: CYCPHASE - values from frequency couplets produced in a modal cyclic symmetry - analysis. - - Parameters - ---------- - type\\_ - The type of operation requested: - - DISP - Calculate the maximum and minimum possible displacement at each node in the - original sector model. Store the values and the phase angle - at which they occurred. - - STRESS - Calculate the maximum and minimum possible stresses at each node in the - original sector model. Store the values and the phase - angle at which they occurred. - - STRAIN - Calculate the maximum and minimum possible strains at each node in the original - sector model. Store the values and the phase angle at - which they occurred. - - ALL - Calculate the maximum and minimum possible displacement, stress and strain at - each node in the original sector model. Store the values and - the phase angle at which they occurred. - - GET - Places the value of a MAX or MIN item into the _CYCVALUE parameter, the node - for that value in the _CYCNODE parameter, and the phase angle - for the value in the _CYCPHASE parameter. - - PUT - Put resulting sweep values for printing (via the PRNSOL command ) or plotting - (via the PLNSOL command). - - LIST - List the current minimum/maximum displacement, stress and strain nodal values. - - STAT - Summarize the results of the last phase sweep. - - CLEAR - Clear phase-sweep information from the database. - - option - If TYPE = DISP, STRAIN, STRESS or ALL, controls the sweep angle - increment to use in the search: - - Angle - The sweep angle increment in degrees, greater than 0.1 and less than 10. The - default is 1. - - Notes - ----- - When you expand the results of a modal cyclic symmetry analysis (via - the /CYCEXPAND or EXPAND command), ANSYS combines the real and - imaginary results for a given nodal diameter, assuming no phase shift - between them; however, the modal response can occur at any phase shift. - - CYCPHASE response results are valid only for the first cyclic sector. - To obtain the response at any part of the expanded model, ANSYS, Inc. - recommends using cyclic symmetry results expansion at the phase angle - obtained via CYCPHASE. - - The phase angles returned by CYCPHASE contain the minimum and maximum - values for USUM, SEQV and other scalar principal stress and strain - quantities; however, they do not always return the true minimum and - maximum values for directional quantities like UX or SX unless the - values fall in the first sector. - - CYCPHASE does not consider midside node values when evaluating maximum - and minimum values, which may affect DISPLAY quantities but no others. - (Typically, ANSYS ignores midside node stresses and strains during - postprocessing.) - - Issuing CYCPHASE,PUT clears the result values for midside nodes on high - order elements; therefore, this option sets element faceting (/EFACET) - to 1. The command reports that midside nodal values are set to zero and - indicates that element faceting is set to 1. - - If the sweep values are available after issuing a CYCPHASE,PUT command, - the PRNSOL or PLNSOL command will print or plot (respectively) the - sweep values of structure displacement Ux, Uy, Uz, component - stress/strain X, Y, Z, XY, YZ, ZX, principal stress/strain 1, 2, 3 and - equivalent stress/strain EQV. The vector sum of displacement (USUM) - and stress/strain intensity (SINT) are not valid phase-sweep results. - - You can specify any coordinate system via the RSYS command for - displaying or printing CYCPHASE results. However, after CYCPHASE - results have been extracted, you cannot then transform them via the - RSYS command. If you try to do so, ANSYS issues a warning message. - - The CYCPHASE command is valid in /POST1 and for cyclically symmetric - models only. - - To learn more about analyzing a cyclically symmetric structure, see the - Cyclic Symmetry Analysis Guide. - """ - command = f"CYCPHASE,{type_},{option}" - return self.run(command, **kwargs) - - def cycspec(self, label="", node="", item="", comp="", **kwargs): - """Defines the set of result items for a subsequent CYCCALC command in - - APDL Command: CYCSPEC - postprocessing a cyclic harmonic mode-superposition analysis. - - Parameters - ---------- - label - One of the following labels: - - ADD - Adds a new specification to the set (default). The maximum number of - specifications that can be defined is 50. - - LIST - Lists the current set of specifications. Node, Item, Comp are ignored. - - ERASE - Erases the current set of specifications. Node, Item, Comp are ignored. - - DELETE - Deletes an existing specification. Item, Comp are ignored. - - node - The node at which to evaluate the results. If Node is a nodal - component, then all nodes in the component are included. All - sectors containing this node (or set of nodes) are evaluated. - - item - Specifies the type of values to evaluate: - - U - Displacement - - S - Stress - - EPEL - Elastic strain - - comp - Specifies the specific component of displacement, stress, or strain - to evaluate: - - X,Y,Z - Direct components - - XY,YZ,XZ - Shear components (stress and strain only) - - 1,2,3 - Principal values (stress and strain only) - - EQV - Equivalent value (stress and strain only) - - SUM - Vector sum (displacement only) - - NORM - L2 norm for the set of nodes (displacement only) - - Notes - ----- - Up to 50 specifications can be defined for use in a subsequent CYCCALC - command. If more than 50 specifications are desired, erase the table - after the CYCCALC operation and add new specifications and repeat the - CYCCALC command. All the specified nodes, items, and components are - evaluated for all sectors and the maximum amplitude value output. For - combined stresses and strains (Comp = 1,2,3 or EQV) or displacement - vector sum (Comp = SUM), a 360 degree phase sweep is performed at each - location to determine the maximum. - - Additional POST1 controls are used to refine the specification. For - component values, components are in the RSYS direction. For shell - elements, the results are at the SHELL location. For EPEL,EQV, the - results are based on the EFFNU value on the AVPRIN command. The - controls active when the CYCCALC command is issued determine the result - values. If results at another SHELL location are desired, issue the new - SHELL command and then re-issue the CYCCALC command. - - If a single node is input, the Item/Comp value at that location in each - sector is output. If a node component is given, then the maximum - Item/Comp value within the set of nodes of each sector is output, one - value for each sector (the node of the maximum may vary from sector to - sector). For stress and strain items, only corner nodes are valid. - - For the displacement norm option (Item = U, Comp = NORM), the L2 norm - computed from all the nodes in the component is output, one per sector. - """ - command = f"CYCSPEC,{label},{node},{item},{comp}" - return self.run(command, **kwargs) - - def exoption(self, ldtype="", option="", value="", **kwargs): - """Specifies the EXPROFILE options for the Mechanical APDL to ANSYS CFX profile file transfer. - - APDL Command: EXOPTION - - Parameters - ---------- - ldtype - Load type: - - * ``"SURF"`` : Surface load - - * ``"VOLU"`` : Volume load - - option - Surface options: - - * ``"Precision"`` : Number of significant digits for the - fractional part of real data - - * ``"Connectivity"`` : Key to include face connectivity in the - exported profile file - - * ``"Precision"`` : Number of significant digits after the - decimal for real data - - value - Specify the value for either Precision or Connectivity. - - For Precision, specify the number of significant digits. Can - be any value between 1 to 20, default 8. When 0 or an invalid - value is specified, the program will use the default value of - 8 and issue a warning message. - - For Connectivity, specify the key to include the element face - connectivity data for surface loads (does not support volume - loads): - - * ``"OFF"`` : Do not include the connectivity data in the exported file (default) - - * ``"ON"`` : Include the connectivity data in the exported file - - Notes - ----- - This command is not supported in Distributed ANSYS. - """ - return self.run(f"EXOPTION,{ldtype},{option},{value}", **kwargs) - - def expand(self, nrepeat="", hindex="", icsys="", sctang="", phase="", **kwargs): - """Displays the results of a modal cyclic symmetry analysis. - - APDL Command: EXPAND - - Parameters - ---------- - nrepeat - Number of sector repetitions for expansion. The default is 0 (no - expansion). - - modal - Specifies that the expansion is for a modal cyclic symmetry - analysis. - - hindex - The harmonic index ID for the results to expand. - - icsys - The coordinate system number used in the modal cyclic symmetry - solution. The default is the global cylindrical coordinate system - (specified via the CSYS command where KCN = 1). - - sctang - The sector angle in degrees, equal to 360 divided by the number of - cyclic sectors. - - -- - This field is reserved for future use. - - phase - The phase angle in degrees to use for the expansion. The default is - 0. Typically, the value is the peak displacement (or stress/strain) - phase angle obtained via the CYCPHASE command. - - Notes - ----- - Issue this command to display the results of a modal cyclic symmetry - analysis. - - When you issue the EXPAND,Nrepeat command, subsequent SET commands read - data from the results file and expand them to Nrepeat sectors. As long - as no entities have been modified, this expansion can be negated (that - is, reverted to single sector) by issuing EXPAND with no arguments. If - you modify entities and wish to return to the partial model, use the - Session Editor (see Restoring Database Contents in the Operations - Guide). - - EXPAND displays the results and allows you to print them, as if for a - full model. The harmonic index (automatically retrieved from the - results file) appears in the legend column. - - When plotting or printing element strain energy (SENE), the EXPAND - command works with brick or tet models only. Element kinetic energy - (KENE) plotting or printing is not supported. - - EXPAND is a specification command valid only in POST1. It is - significantly different from the /CYCEXPAND command in several - respects, (although you can use either command to display the results - of a modal cyclic symmetry analysis): - - EXPAND has none of the limitations of the /CYCEXPAND command. - - EXPAND changes the database by modifying the geometry, the nodal - displacements, and element stresses as they are read from the results - file, whereas the /CYCEXPAND command does not change the database. - - Caution:: : The EXPAND command creates new nodes and elements; - therefore, saving (or issuing the /EXIT, ALL command) after issuing the - EXPAND command can result in large databases. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"EXPAND,{nrepeat},{hindex},{icsys},{sctang},{phase}" - return self.run(command, **kwargs) - - def exprofile( - self, - ldtype="", - load="", - value="", - pname="", - fname="", - fext="", - fdir="", - **kwargs, - ): - """Exports interface loads or loads on selected nodes to an ANSYS CFX - - APDL Command: EXPROFILE - Profile file. - - Parameters - ---------- - ldtype - Load type: - - SURF - Surface load. - - VOLU - Volumetric load. - - load - Surface loads: - - DISP - Displacement (in a static analysis) or mode shape and global parameters (in a - modal analysis). - - MODE - Normalized mode shape and global parameters (in a modal analysis only). - - TEMP - Temperature. - - HFLU - Heat flux. - - value - If a positive integer, specifies the number of the surface or - volume interface. If 0 (zero), the selected nodes or Named - Selection are used. - - pname - Field name in CFX Profile file (32-character maximum). Defaults to - jobname_bcploadnumber for a surface load and jobname_subdloadnumber - for volumetric load. - - fname - The CFX Profile filename (248-character maximum). Defaults to - jobname_bcploadnumber for a surface load and jobname_subdloadnumber - for a volumetric load. - - fext - The Profile file extension (8-character maximum). Defaults to.csv. - - fdir - The Profile file directory (8-character maximum). Defaults to - current directory. - - Notes - ----- - By default, the EXPROFILE command assumes the data it writes to the - Profile file are in SI units. For models not described in SI units, - issue the EXUNIT command as needed to write the correct unit labels on - the Profile file. - - For a modal analysis, if Load = DISP or MODE, global parameters - including mass, frequency, and maximum displacement are also written to - the ANSYS CFX Profile file. You should therefore issue the EXUNIT - command for DISP, TIME, and MASS. - - Verify that the coordinate system is set to the global Cartesian - (RSYS,0) before using this command. - - To transfer multiple loads across an interface, specify a unique file - name and extension for each load. - - Force (FORC) and heat generation (HGEN) are per-unit volume. - - For modal analysis, this command does not support the following mode- - extraction methods (MODOPT): unsymmetric matrix (UNSYM), the damped - system (DAMP), or the QR-damped system (QRDAMP). - - To write the normalized (instead of non-normalized) mode shapes from a - modal analysis to the file: - - Use Load = MODE. - - Verify that the mode shapes are normalized to the mass matrix - (MODOPT,,,,,,OFF), the default behavior. - - Verify that the scale factor is set to 1.0 (SET,,,1.0), the default - value. - - For loads not specified directly via commands (such as SF and BF), - loads must first be read into the database (SET or LCASE). - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"EXPROFILE,{ldtype},{load},{value},{pname},{fname},{fext},{fdir}" - return self.run(command, **kwargs) - - def exunit(self, ldtype="", load="", untype="", name="", **kwargs): - """Specifies the interface load unit labels to be written to the export - - APDL Command: EXUNIT - file for ANSYS to CFX transfer. - - Parameters - ---------- - ldtype - Load type: - - SURF - Surface load. - - VOLU - Volumetric load. - - load - Surface loads: - - DISP - Displacement in a static analysis. Mode shape in a modal analysis. - - TIME - Time. The unit for frequency is the inverse of the unit for time. - - MASS - Mass. - - TEMP - Temperature. - - HFLU - Heat flux. - - untype - Unit type: - - COMM - Predefined unit - - USER - User-specified unit - - name - Commonly used predefined unit name or user-specified unit name. - - SI - International System of units (meter-kilogram-second) (default) - - FT - English System of units (feet-pound-second) - - Notes - ----- - This command only specifies which unit labels are to be written to the - file when the EXPROFILE is issued. It does not perform unit - conversions. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"EXUNIT,{ldtype},{load},{untype},{name}" - return self.run(command, **kwargs) - - def fssparm(self, port1="", port2="", **kwargs): - """Calculates reflection and transmission properties of a frequency - - APDL Command: FSSPARM - selective surface. - - Parameters - ---------- - port1 - Port number of input port. Defaults to 1. - - port2 - Port number of output port. Defaults to 1. - - Notes - ----- - FSSPARM calculates reflection and transmission coefficients, power - reflection and transmission coefficients, and return and insertion - losses of a frequency selective surface. - """ - command = f"FSSPARM,{port1},{port2}" - return self.run(command, **kwargs) - - def fsum(self, lab="", item="", **kwargs): - """Sums the nodal force and moment contributions of elements. - - APDL Command: FSUM - - Parameters - ---------- - lab - Coordinate system in which to perform summation. - - (blank) - Sum all nodal forces in global Cartesian coordinate system (default). - - RSYS - Sum all nodal forces in the currently active RSYS coordinate system. - - item - Selected set of nodes. - - (blank) - Sum all nodal forces for all selected nodes (default), excluding contact - elements. - - CONT - Sum all nodal forces for contact nodes only. - - BOTH - Sum all nodal forces for all selected nodes, including contact elements. - - Notes - ----- - Sums and prints, in each component direction for the total selected - node set, the nodal force and moment contributions of the selected - elements attached to the node set. Selecting a subset of nodes [NSEL] - and then issuing this command will give the total force acting on that - set of nodes (default), excluding surface-to-surface, node-to-surface, - line-to-line, and line-to-surface contact elements (TARGE169, TARGE170, - CONTA171, CONTA172, CONTA173, CONTA174, CONTA175, CONTA176, and - CONTA177). - - Setting ITEM = CONT sums the nodal forces and moment contributions of - the selected contact elements (CONTA171, CONTA172, CONTA173, CONTA174, - CONTA175, CONTA176, and CONTA177). Setting ITEM = BOTH sums the nodal - forces for all selected nodes, including contact elements. - - Nodal forces associated with surface loads are not included. The - effects of nodal coupling and constraint equations are ignored. Moment - summations are about the global origin unless another point is - specified with the SPOINT command. This vector sum is printed in the - global Cartesian system unless it is transformed [RSYS] and a point is - specified with the SPOINT command. By default, the sum is done in - global Cartesian, and the resulting vector is transformed to the - requested system. - - The LAB = RSYS option transforms each of the nodal forces into the - active coordinate system before summing and printing. The FORCE command - can be used to specify which component (static, damping, inertia, or - total) of the nodal load is to be used. This command output is included - in the NFORCE command. - - The command should not be used with axisymmetric elements because it - might calculate a moment where none exists. Consider, for example, the - axial load on a pipe modeled with an axisymmetric shell element. The - reaction force on the end of the pipe is the total force (for the full - 360 degrees) at that location. The net moment about the centerline of - the pipe would be zero, but the program would incorrectly calculate a - moment at the end of the element as the force multiplied by the radius. - - The command is not valid for elements that operate solely within the - nodal coordinate system with 1-D option activated and rotated nodes - (NROTAT). - """ - command = f"FSUM,{lab},{item}" - return self.run(command, **kwargs) - - def hfang(self, lab="", phi1="", phi2="", theta1="", theta2="", **kwargs): - """Defines or displays spatial angles of a spherical radiation surface for - - APDL Command: HFANG - sound radiation parameter calculations. - - Parameters - ---------- - lab - Spatial angle label. - - ANGLE - Define spatial angles (default). - - STATE - Display spatial angles. PHI1, PHI2, THETA1, and THETA2 are ignored. - - phi1, phi2 - Starting and ending ϕ angles (degrees) in the spherical coordinate - system. Defaults to 0. - - theta1, theta2 - Starting and ending θ angles (degrees) in the spherical coordinate - system. Defaults to 0. - - Notes - ----- - Defines or displays spatial angles of a spherical radiation surface. - - Use this command only with PLFAR,Lab = PRES, or PRFAR,Lab = PRES. - """ - command = f"HFANG,{lab},{phi1},{phi2},{theta1},{theta2}" - return self.run(command, **kwargs) - - def hfsym(self, kcn="", xkey="", ykey="", zkey="", **kwargs): - """Indicates the presence of symmetry planes for the computation of - - APDL Command: HFSYM - acoustic fields in the near and far field domains (beyond the finite - element region). - - Parameters - ---------- - kcn - Coordinate system reference number. KCN may be 0 (Cartesian), or - any previously defined local Cartesian coordinate system number - (>10). Defaults to 0. - - xkey - Key for acoustic field boundary condition, as prescribed for the - solution, corresponding to the x = constant plane: - - None - No sound soft or sound hard boundary conditions (default). - - SSB - Sound soft boundary (pressure = 0). - - SHB - Sound hard boundary (normal velocity = 0). - - ykey - Key for acoustic field boundary condition, as prescribed for the - solution, corresponding to the y = constant plane: - - None - No sound soft or sound hard boundary conditions (default). - - SSB - Sound soft boundary (pressure = 0). - - SHB - Sound hard boundary (normal velocity = 0). - - zkey - Key for acoustic field boundary condition, as prescribed for the - solution, corresponding to the z = constant plane: - - None - No sound soft or sound hard boundary conditions (default). - - SSB - Sound soft boundary (pressure = 0). - - SHB - Sound hard boundary (normal velocity = 0). - - Notes - ----- - HFSYM uses the image principle to indicate symmetry planes (x, y, or z - = constant plane) for acoustic field computations outside the modeled - domain. A sound hard boundary condition must be indicated even though - it occurs as a natural boundary condition. - - No menu paths are available for acoustic applications. - """ - command = f"HFSYM,{kcn},{xkey},{ykey},{zkey}" - return self.run(command, **kwargs) - - def intsrf(self, lab="", **kwargs): - """Integrates nodal results on an exterior surface. - - APDL Command: INTSRF - - Parameters - ---------- - lab - Label indicating degree of freedom to be integrated: - - PRES - Pressure. - - TAUW - Wall shear stress. - - FLOW - Both pressure and wall shear stress. - - Notes - ----- - Integrates nodal results on a surface. Use node selection (such as the - EXT option of the NSEL command) to indicate the surface(s) of element - faces to be used in the integration. A surface can be "created" by - unselecting elements (such as unselecting non-fluid elements that are - adjacent to fluid elements for the postprocessing of fluid flow - result). Element faces attached to the selected nodes will be - automatically determined. All nodes on a face must be selected for the - face to be used. The integration results will cancel for nodes on - common faces of adjacent selected elements. - - Integration results are in the active coordinate system (see the RSYS - command). The type of results coordinate system must match the type - used in the analysis. However, you may translate and rotate forces and - moments as needed. Use the ``*GET`` command (Utility Menu> Parameters> Get - Scalar Data) to retrieve the results. - """ - command = f"INTSRF,{lab}" - return self.run(command, **kwargs) - - def kcalc(self, kplan="", mat="", kcsym="", klocpr="", **kwargs): - """Calculates stress intensity factors in fracture mechanics analyses. - - APDL Command: KCALC - - Parameters - ---------- - kplan - Key to indicate stress state for calculation of stress intensity - factors: - - 0 - Plane strain and axisymmetric condition (default). - - 1 - Plane stress condition. - - mat - Material number used in the extrapolation (defaults to 1). - - kcsym - Symmetry key: - - 0 or 1 - Half-crack model with symmetry boundary conditions [DSYM] in the crack-tip - coordinate system. KII = KIII = 0. Three nodes are - required on the path. - - 2 - Like 1 except with antisymmetric boundary conditions (KI = 0). - - 3 - Full-crack model (both faces). Five nodes are required on the path (one at the - tip and two on each face). - - klocpr - Local displacements print key: - - 0 - Do not print local crack-tip displacements. - - 1 - Print local displacements used in the extrapolation technique. - - Notes - ----- - Calculates the stress intensity factors (KI, KII, and KIII) associated - with homogeneous isotropic linear elastic fracture mechanics. A - displacement extrapolation method is used in the calculation (see POST1 - - Crack Analysis in the Mechanical APDL Theory Reference). This method - assumes that the displacement calculations are for the plane strain - state. If the displacement calculations are performed using a plane - stress formulation, the calculation of the stress intensity factors can - be converted to the plane strain state by using KPLAN = 1. ANSYS Uses - minor Poisson's ratio (MP,NUXY) for the stress intensity factor - calculation, therefore the material's Poisson's ratio must be defined - using MP,NUXY command. The PATH and PPATH commands must be used to - define a path with the crack face nodes (NODE1 at the crack tip, NODE2 - and NODE3 on one face, NODE4 and NODE5 on the other (optional) face). - A crack-tip coordinate system, having x parallel to the crack face (and - perpendicular to the crack front) and y perpendicular to the crack - face, must be the active RSYS and CSYS before KCALC is issued. - """ - command = f"KCALC,{kplan},{mat},{kcsym},{klocpr}" - return self.run(command, **kwargs) - - def nforce(self, item="", **kwargs): - """Sums the nodal forces and moments of elements attached to nodes. - - APDL Command: NFORCE - - Parameters - ---------- - item - Specifies the selected set of nodes for summing forces and moments - for contact elements. - - (blank) - Sums the nodal forces of elements for all selected nodes and excludes contact - elements (elements 169-177). - - CONT - Sums the nodal forces of elements for contact nodes only. - - BOTH - Sums the nodal forces of elements for all selected nodes, including contact - elements. - - Notes - ----- - Sums and prints, in each component direction for each selected node, - the nodal force and moment contributions of the selected elements - attached to the node. If all elements are selected, the sums are - usually zero except where constraints or loads are applied. The nodal - forces and moments may be displayed [/PBC,FORC and /PBC,MOME]. Use - PRESOL to print nodal forces and moments on an element-by-element - basis. You can use the FORCE command to specify which component - (static, damping, inertia, or total) of the nodal load is to be used. - Nodal forces associated with surface loads are not included. - - This vector sum is printed in the global Cartesian system. Moment - summations are about the global origin unless another point is - specified with the SPOINT command. The summations for each node are - printed in the global Cartesian system unless transformed [RSYS]. This - command is generally not applicable to axisymmetric models because - moment information from the NFORCE command is not correct for - axisymmetric elements. - - Selecting a subset of elements [ESEL] and then issuing this command - will give the forces and moments required to maintain equilibrium of - that set of elements. The effects of nodal coupling and constraint - equations are ignored. The option ITEM = CONT provides the forces and - moments for the contact elements (CONTA171, CONTA172, CONTA173, - CONTA174, CONTA175, CONTA176, and CONTA177). Setting ITEM = BOTH - provides the forces and moments for all selected nodes, including - contact elements. - - This command also includes the FSUM command function which vectorially - sums and prints, in each component direction for the total selected - node set, the nodal force and moment contributions of the selected - elements attached to the selected node set. - """ - command = f"NFORCE,{item}" - return self.run(command, **kwargs) - - def nldpost(self, label="", key="", fileid="", prefix="", **kwargs): - """Gets element component information from nonlinear diagnostic files. - - APDL Command: NLDPOST - - Parameters - ---------- - label - Specifies the type of command operation: - - EFLG - Element flag for nonlinear diagnostics. - - NRRE - Newton-Raphson residuals. - - key - Specifies the command action: - - STAT - List information about the diagnostic files (Jobname.ndxxx or Jobname.nrxxx) in - the current directory. - - For Label = EFLG, the listing gives a summary that associates the loadstep, substep, time, equilibrium iteration number, cumulative iteration number, and the number of elements that fail each criteria with a specific file ID (Jobname.ndxxx). Use the list to create element components (via the CM option) based on the cumulative iteration number. - For Label = NRRE, the listing provides a summary that associates the loadstep, - substep, time, equilibrium iteration number, and - cumulative iteration number with a specific file - ID (Jobname.nrxxx). Use the list to identify the - respective file ID for creating Newton-Raphson - residual contour plots (PLNSOL,NRRE,…,FileID). - - DEL - Delete Jobname.ndxxx or Jobname.nrxxx files in the working directory, if any - exist. - - CM - Create components for elements that violate criteria. This value is valid only - when Label = EFLG. - - fileid - Valid only when Label = EFLG and Key = CM, this value specifies - file IDs: - - IDnum - The file ID number. Creates the element components from the diagnostic files - corresponding to the specified file ID number in the - working directory. - - ALL - Creates element components from all available diagnostic files residing in the - working directory. This value is the default if you do not - specify an IDnum value. - - prefix - Sets the prefix name for components. Specify up to 21 alphanumeric - characters. - - Notes - ----- - Based on the nonlinear diagnostic results (created via the NLDIAG,EFLG - command), the NLDPOST command creates element components with - predefined names. - - The following table lists the diagnostic criteria and component names - (with specified prefix and without). Here xxx corresponds to the file - ID (FileID) of Jobname.ndxxx or Jobname.nrxxx. - - If you have trouble viewing specific element components, see Viewing - Hidden Element Components in the Basic Analysis Guide. - - For more information, see Performing Nonlinear Diagnostics. - """ - command = f"NLDPOST,{label},{key},{fileid},{prefix}" - return self.run(command, **kwargs) - - def plcamp( - self, - option="", - slope="", - unit="", - freqb="", - cname="", - stabval="", - keyallfreq="", - keynegfreq="", - **kwargs, - ): - """Plots Campbell diagram data for applications involving rotating - - APDL Command: PLCAMP - structure dynamics. - - Parameters - ---------- - option - Flag to activate or deactivate sorting of forward or backward whirl - frequencies: - - 0 (OFF or NO) - No sorting. - - 1 (ON or YES) - Sort. This value is the default. - - slope - The slope of the line to be printed. This value must be positive. - - SLOPE > 0 - The line represents the number of excitations per revolution of the rotor. For - example, SLOPE = 1 represents one excitation per - revolution, usually resulting from unbalance. - - SLOPE = 0 - The line represents the stability threshold for stability values or logarithmic - decrements printout (STABVAL = 1 or 2) - - unit - Specifies the unit of measurement for rotational angular - velocities: - - RDS - Rotational angular velocities in radians per second (rad/s). This value is the - default. - - RPM - Rotational angular velocities in revolutions per minute (RPMs). - - freqb - The beginning, or lower end, of the frequency range of interest. - The default is zero. - - cname - The rotating component name. - - stabval - Flag to plot the stability values: - - 0 (OFF or NO) - Plot the frequencies (the imaginary parts of the eigenvalues in Hz). This value - is the default. - - 1 (ON or YES) - Plot the stability values (the real parts of the eigenvalues in Hz). - - 2 - Plot the logarithmic decrements. - - keyallfreq - Key to specify if all frequencies above FREQB are plotted: - - 0 (OFF or NO) - A maximum of 10 frequencies are plotted. This value is the default. - - 1 (ON or YES) - All frequencies are plotted. - - keynegfreq - Key to specify if the negative frequencies are plotted. It only - applies to solutions obtained with the damped eigensolver (Method = - DAMP on the MODOPT command): - - 0 (OFF or NO) - Only positive frequencies are plotted. This value is the default. - - 1 (ON or YES) - Negative and positive frequencies are plotted. - - Notes - ----- - The following items are required when generating a Campbell diagram: - - Take the gyroscopic effect into account by issuing the CORIOLIS command - in the SOLUTION module. - - Run a modal analysis using the QR damped (MODOPT,QRDAMP) or damped - (MODOPT,DAMP) method. Complex eigenmodes are necessary - (MODOPT,QRDAMP,,,,Cpxmod = ON), and you must specify the number of - modes to expand (MXPAND). - - Define two or more load step results with an ascending order of - rotational velocity (OMEGA or CMOMEGA). - - In some cases where modes are not in the same order from one load step - to the other, sorting the frequencies (Option = 1) can help to obtain a - correct plot. Sorting is based on the comparison between complex mode - shapes calculated at two successive load steps. - - At each load step, the application compares the mode shape to the loads - at other load steps to determine whirl direction at the load step. If - applicable, a label appears (in the plot legend) representing each - whirl mode (BW for backward whirl and FW for forward whirl). - - At each load step, the program checks for instability (based on the - sign of the real part of the eigenvalue). The labels "stable" or - "unstable" appear in the plot legend for each frequency curve. - - The rotational velocities of a named component (Cname) are displayed on - the X-axis. - - For information on plotting a Campbell diagram for a prestressed - structure, see Solving for a Subsequent Campbell Analysis of a - Prestressed Structure Using the Linear Perturbation Procedure in the - Rotordynamic Analysis Guide. - - In general, plotting a Campbell diagram is recommended only when your - analysis is performed in a stationary reference frame - (CORIOLIS,,,,RefFrame = ON). - - For a usage example of the PLCAMP command, see Campbell Diagram in the - Rotordynamic Analysis Guide. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"PLCAMP,{option},{slope},{unit},{freqb},{cname},{stabval},{keyallfreq},{keynegfreq}" - return self.run(command, **kwargs) - - def plcfreq(self, spec="", sectbeg="", sectend="", **kwargs): - """Plots the frequency response for the given CYCSPEC specification. - - APDL Command: PLCFREQ - - Parameters - ---------- - spec - CYCSPEC specification number (ordered 1 to N in the order input; - use CYCSPEC,LIST to view the current list order). Defaults to 1. - - sectbeg - Beginning sector number to plot. Defaults to 1. - - sectend - Ending sector number to plot. Defaults to the total number of - sectors expanded (/CYCEXPAND). - - Notes - ----- - Following a cyclic mode-superposition harmonic analysis, this command - plots the result item given by a CYCSPEC specification versus the - harmonic frequency, one curve for each of the specified sectors. A - CYCCALC command must have been issued prior to this command. - """ - command = f"PLCFREQ,{spec},{sectbeg},{sectend}" - return self.run(command, **kwargs) - - def plchist(self, spec="", freqpt="", **kwargs): - """Plots a histogram of the frequency response of each sector for the - - APDL Command: PLCHIST - given CYCSPEC specification. - - Parameters - ---------- - spec - CYCSPEC specification number (ordered 1 to N in the order input; - use CYCSPEC,LIST to view the current list order). Defaults to 1. - - freqpt - Harmonic frequency point to plot (the data set number NSET or - CUMULATIVE on SET,LIST). Defaults to the current SET frequency. - - Notes - ----- - Following a cyclic mode-superposition harmonic analysis, this command - creates a histogram plot of the result item given by a CYCSPEC - specification versus the sector number. A CYCCALC command must have - been issued prior to this command. - """ - command = f"PLCHIST,{spec},{freqpt}" - return self.run(command, **kwargs) - - def plfar( - self, - lab="", - option="", - phi1="", - phi2="", - nph1="", - theta1="", - theta2="", - ntheta="", - val1="", - val2="", - val3="", - **kwargs, - ): - """Plots pressure far fields and far field parameters. - - APDL Command: PLFAR - - Parameters - ---------- - lab - Parameters to plot : - - PRES - Acoustic parameters - - PROT - Acoustic parameters with the y-axis rotated extrusion - - option - Plot option, based on the specified plot parameter type: - - phi1, phi2 - Starting and ending φ angles (degrees) in the spherical coordinate - system. Defaults to 0. - - nphi - Number of divisions between the starting and ending φ angles for - data computations. Defaults to 0. - - theta1, theta2 - Starting and ending θ angles (degrees) in the spherical coordinate - system. Defaults to 0 in 3-D and 90 in 2-D. - - ntheta - Number of divisions between the starting and ending θ angles for - data computations. Defaults to 0. - - val1 - Radius of the sphere surface. Used only when Option = SUMC, SUMP, - PHSC, PHSP, SPLC, SPLP, SPAC, SPAP, PSCT, PSPL, TSCT, or TSPL. - - val2 - When Option = SPLC, SPLP, SPAC, or SPAP: Reference rms sound - pressure. Defaults to 2x10-5 Pa. - - val3 - When Lab = PRES: Thickness of 2-D model extrusion in the z - direction (no default). - - Notes - ----- - The PLFAR command plots pressure far fields and far field parameters as - determined by the equivalent source principle. Use this command to plot - pressure and acoustic parameters. See the HFSYM command for the - model symmetry and the HFANG command for spatial radiation angles. - - When Option = PWL no plot is generated, but the sound power level - appears in the output. - - To retrieve saved equivalent source data, issue the - SET,Lstep,Sbstep,,REAL command. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"PLFAR,{lab},{option},{phi1},{phi2},{nph1},{theta1},{theta2},{ntheta},{val1},{val2},{val3}" - return self.run(command, **kwargs) - - def plmc( - self, - lstep="", - sbstep="", - timfrq="", - kimg="", - hibeg="", - hiend="", - **kwargs, - ): - """Plots the modal coordinates from a mode-superposition solution. - - APDL Command: PLMC - - Parameters - ---------- - lstep, sbstep - Plot the solution identified as load step LSTEP and substep SBSTEP - - timfrq - As an alternative to LSTEP and SBSTEP, plot the solution at the - time value TIMFRQ (for ANTYPE,TRANS) or frequency value TIMFRQ (for - ANTYPE,HARMIC). LSTEP and SBSTEP should be left blank. - - kimg - If 0 (or blank), plot the real solution. If 1, plot the imaginary - solution. Only valid for ANTYPE,HARMIC. - - hibeg, hiend - For cyclic symmetry solutions, plot the solutions in the harmonic - index solution range HIbeg to HIend. Defaults to all harmonic - indices (all modes). - - Notes - ----- - PLMC plots a histogram of the modal coordinates (the response - amplitudes applied to each mode shape) at a certain time point - (transient analyses) or frequency point (harmonic analyses). The - absolute values of the modal coordinates are plotted. Use /XRANGE to - plot only modes in a certain range, if desired. - - For transient analyses, the Jobname.RDSP file must be available. For - harmonic analyses, the Jobname.RFRQ must be available. No SET command - is required and no expansion pass is required. - - For a cyclic harmonic mode-superposition analysis, use the CYCFILES - command to identify the Jobname.RFRQ and modal Jobname.RST file. You - may limit the plot to display only those modes in a certain harmonic - index range. The modes having the same harmonic index are each plotted - in a unique color. If there are less than 10 harmonic indices, they are - identified in the graphics legend. - - This is a graphical representation of the optional Jobname.MCF text - file. (see the TRNOPT and HROPT commands). For more information on - modal coordinates, see Mode-Superposition Method in the Mechanical APDL - Theory Reference. - """ - command = f"PLMC,{lstep},{sbstep},{timfrq},{kimg},{hibeg},{hiend}" - return self.run(command, **kwargs) - - def plnear( - self, - lab="", - opt="", - kcn="", - val1="", - val2="", - val3="", - val4="", - val5="", - val6="", - val7="", - val8="", - val9="", - **kwargs, - ): - """Plots the pressure in the near zone exterior to the equivalent source - - APDL Command: PLNEAR - surface. - - Parameters - ---------- - lab - Plot the maximum pressure or sound pressure level: - - SPHERE - on the spherical structure - - PATH - along the path - - opt - PSUM - - PSUM - Maximum complex pressure for acoustics. - - PHAS - Phase angle of complex pressure for acoustics. - - SPL - Sound pressure level for acoustics. - - SPLA - A-weighted sound pressure level for acoustics (dBA). - - kcn - KCN is the coordinate system reference number. It may be 0 - (Cartesian) or any previously defined local coordinate system - number (>10). Defaults to 0. - - val1, val2, val3, . . . , val9 - For LAB = SPHERE: - - VAL1 - Radius of spherical surface in spherical coordinate system. - - VAL2 - Starting φ angle (degree) in the spherical coordinate system. Defaults to 0. - - VAL3 - Ending φ angle (degree) in the spherical coordinate system. Defaults to 0. - - VAL4 - Number of divisions between the starting and ending φ angles for data - computations. Defaults to 0. - - VAL5 - Starting θ angle (degrees) in the spherical coordinate system. Defaults to 0 in - 3-D and 90 in 2-D extension. - - VAL6 - Ending θ angle (degrees) in the spherical coordinate system. Defaults to 0 in - 3-D and 90 in 2-D extension. - - VAL7 - Number of divisions between the starting and ending θ angles for data - computations. Defaults to 0. - - VAL8 - Reference rms sound pressure. Defaults to 2x10-5 Pa. - - VAL9 - Thickness of 2-D model extension in z direction (defaults to 0). - - Notes - ----- - PLNEAR uses the equivalent source principle to calculate the pressure - in the near zone exterior to the equivalent source surface (flagged - with the Maxwell surface flag in the preprocessor) for one of the - following locations: - - A spherical surface in the KCN coordinate system - - A path defined by the PATH and PPATH commands - - To plot the pressure results for a path, use the PLPAGM or PLPATH - commands. See the HFSYM command for the model symmetry. - - To retrieve saved equivalent source data, issue the - SET,Lstep,Sbstep,,REAL command. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"PLNEAR,{lab},{opt},{kcn},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8},{val9}" - return self.run(command, **kwargs) - - def plzz(self, rotvel="", deltarotvel="", **kwargs): - """Plots the interference diagram from a cyclic modal analysis. - - APDL Command: PLZZ - - Parameters - ---------- - rotvel - Rotational speed in revolutions per minute (RPM) used to define the - speed line. If blank, use the rotational speed (from OMEGA) - specified in the prestressing step of the linear perturbation - analysis. If explicitly input as 0, or if the linear perturbation - was not used, no speed lines are plotted. - - deltarotvel - Adds speed lines about the RotVel speed line corresponding to - RotVel ± DeltaRotVel. Only plotted if RotVel is known. - - Notes - ----- - PLZZ plots the cyclic modal frequencies as points on a frequency vs. - harmonic index (nodal diameter) graph. If rotational speed (RotVel) is - provided, the speed line is also plotted, leading to the interference - diagram (also known as the SAFE or ZZENF diagram). If DeltaRotVel is - also provided, two additional speed lines are plotted, enveloping the - safe speed line itself. - - For more information, see Postprocessing a Modal Cyclic Symmetry - Analysis in the Cyclic Symmetry Analysis Guide. - """ - command = f"PLZZ,{rotvel},{deltarotvel}" - return self.run(command, **kwargs) - - def pras(self, quantity="", loadstep="", substep="", **kwargs): - """Calculates a specified acoustic quantity on the selected exterior - - APDL Command: PRAS - surface or the frequency-band sound pressure level (SPL). - - Parameters - ---------- - quantity - The acoustic quantity to calculate: - - SIMP - Specific acoustic impedance on the selected surface. - - AIMP - Acoustic impedance on the selected surface. - - MIMP - Mechanical impedance on the selected surface. - - PRES - Average pressure on the selected surface. - - FORC - Force on the selected surface. - - POWE - Acoustic power on the selected surface. - - BSPL - Frequency-band sound pressure level. - - BSPA - A-weighted frequency-band sound pressure level. - - loadstep - Specified load step. Default = 1. - - substep - Specified substep. Default = All substeps at the specified load - step. Not valid for Quantity = BSPL or BSPA. - - Notes - ----- - The PRAS command calculates a specified acoustic quantity on the - selected exterior surface in postprocessing. The calculation is based - on the pressure and velocity solution or the frequency-band sound - pressure level (SPL). - - The total pressure and velocity are used if the selected surface is the - excitation source surface. To calculate the incoming and outgoing - acoustic power, and other sound power parameters, on the excitation - source surface, issue the SF,,PORT and SPOWER commands. - - The sound pressure level of the octave bands and general frequency band - (defined via the HARFRQ command) is calculated at the selected nodes in - the model. - """ - command = f"PRAS,{quantity},{loadstep},{substep}" - return self.run(command, **kwargs) - - def prcamp( - self, - option="", - slope="", - unit="", - freqb="", - cname="", - stabval="", - keyallfreq="", - keynegfreq="", - keywhirl="", - **kwargs, - ): - """Prints Campbell diagram data for applications involving rotating - - APDL Command: PRCAMP - structure dynamics. - - Parameters - ---------- - option - Flag to activate or deactivate sorting of forward or backward whirl - frequencies: - - 0 (OFF or NO) - No sorting. - - 1 (ON or YES) - Sort. This value is the default. - - slope - The slope of the line to be printed. This value must be positive. - - SLOPE > 0 - The line represents the number of excitations per - revolution of the rotor. For example, SLOPE = 1 represents one - excitation per revolution, usually resulting from unbalance. - - SLOPE = 0 - The line represents the stability threshold for stability - values or logarithmic decrements printout (STABVAL = 1 or 2) - - unit - Specifies the unit of measurement for rotational angular - velocities: - - RDS - Rotational angular velocities in radians per second (rad/s). This value is the default. - - RPM - Rotational angular velocities in revolutions per minute (RPMs). - - freqb - The beginning, or lower end, of the frequency range of interest. - The default is zero. - - cname - The rotating component name. - - stabval - Flag to print the stability values: - - 0 (OFF or NO) - Print the frequencies (the imaginary parts of the - eigenvalues in Hz). This value is the default. - - 1 (ON or YES) - Print the stability values (the real parts of the eigenvalues in Hz). - - 2 - Print the logarithmic decrements. - - keyallfreq - Key to specify if all frequencies above FREQB are printed out: - - 0 (OFF or NO) - A maximum of 10 frequencies are printed out. They - correspond to the frequencies displayed via the PLCAMP command. This value is the default. - - 1 (ON or YES) - All frequencies are printed out. - - keynegfreq - Key to specify if the negative frequencies are printed out. It only - applies to solutions obtained with the damped eigensolver - (Method=DAMP on the MODOPT command): - - 0 (OFF or NO) - Only positive frequencies are printed out. This value is the default. - - 1 (ON or YES) - Negative and positive frequencies are printed out. - - keywhirl - Flag to print the whirl and instability keys for each load step: - - 0 (OFF or NO) - Print the whirl for the last load step. This value is the default. - 1 (ON or YES) - Print the whirl and instability keys for each load step. - - Notes - ----- - The following items are required when generating a Campbell diagram: - - Take the gyroscopic effect into account by issuing the CORIOLIS command - in the SOLUTION module. - - Run a modal analysis using the QR damped (MODOPT,QRDAMP) or damped - (MODOPT,DAMP) method. Complex eigenmodes are necessary - (MODOPT,QRDAMP,,,,Cpxmod = ON), and you must specify the number of - modes to expand (MXPAND). - - Define two or more load step results with an ascending order of - rotational velocity (OMEGA or CMOMEGA). - - In some cases where modes are not in the same order from one load step - to the other, sorting the frequencies (Option = 1) can help to obtain a - correct printout. Sorting is based on the comparison between complex - mode shapes calculated at two successive load steps. - - At each load step, the application compares the mode shape to the loads - to determine the whirl direction. If applicable, a label appears (on - the rows of output data) representing the whirl mode (BW for backward - whirl and FW for forward whirl). - - If you specify a non-zero slope (SLOPE > 0), the command prints the - critical speeds corresponding to the intersection points of the - frequency curves and the added line. In the case of a named component - (Cname), critical speeds relate to the rotational velocity of the - component. Critical speeds are available only if the frequencies are - printed (STABVAL = OFF). - - If you specify a zero slope (SLOPE = 0), the command prints the - stability threshold corresponding to the sign change of the stability - values (or logarithmic decrements). In the case of a named component - (Cname), stability thresholds relate to the rotational velocity of the - component. Stability thresholds are available only if the stability - values or logarithmic decrements are printed (STABVAL = 1 or 2). - - At each load step, the program checks for instability (based on the - sign of the real part of the eigenvalue). The label "U" appears on the - printout for each unstable frequency. - - If specified, the rotational velocities of the named component (Cname) - are printed out along with the natural frequencies. - - In general, printing a Campbell diagram is recommended only when your - analysis is performed in a stationary reference frame - (CORIOLIS,,,,RefFrame = ON). - - For information on printing a Campbell diagram for a prestressed - structure, see Solving for a Subsequent Campbell Analysis of a - Prestressed Structure Using the Linear Perturbation Procedure in the - Rotordynamic Analysis Guide. - - For a usage example of the companion command PLCAMP (used for plotting - a Campbell diagram), see Example Campbell Diagram Analysis. - - For more information on Campbell diagram generation, see Campbell - Diagram in the Rotordynamic Analysis Guide. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"PRCAMP,{option},{slope},{unit},{freqb},{cname},{stabval},{keyallfreq},{keynegfreq},{keywhirl}" - return self.run(command, **kwargs) - - def prfar( - self, - lab="", - option="", - phi1="", - phi2="", - nph1="", - theta1="", - theta2="", - ntheta="", - val1="", - val2="", - val3="", - **kwargs, - ): - """Prints pressure far fields and far field parameters. - - APDL Command: PRFAR - - Parameters - ---------- - lab - Parameters to print: - - PRES - Acoustic parameters - - PROT - Acoustic parameters with the y-axis rotated extrusion - - option - Print option, based on the specified print parameter type: - - phi1, phi2 - Starting and ending φ angles (degrees) in the spherical coordinate - system. Defaults to 0. - - nphi - Number of divisions between the starting and ending φ angles for - data computations. Defaults to 0. - - theta1, theta2 - Starting and ending θ angles (degrees) in the spherical coordinate - system. Defaults to 0 in 3-D and 90 in 2-D. - - ntheta - Number of divisions between the starting and ending θ angles for - data computations. Defaults to 0. - - val1 - Radius of the sphere surface. Used only when Option = SUMC, PHSC, - SPLC, SPAC, PSCT, or TSCT. - - val2 - When Option = SPLC or SPAC: Reference rms sound pressure. Defaults - to 2x10-5 Pa. - - val3 - When Lab = PRES: Thickness of 2-D model extrusion in the z - direction (no default). - - Notes - ----- - The PRFAR command prints pressure far fields and far field parameters - as determined by the equivalent source principle. Use this command - to print pressure and acoustic parameters. See the HFSYM command for - the model symmetry and the HFANG command for spatial radiation - angles. - - To retrieve saved equivalent source data, issue the - SET,Lstep,Sbstep,,REAL command. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"PRFAR,{lab},{option},{phi1},{phi2},{nph1},{theta1},{theta2},{ntheta},{val1},{val2},{val3}" - return self.run(command, **kwargs) - - def prnear( - self, - lab="", - opt="", - kcn="", - val1="", - val2="", - val3="", - val4="", - val5="", - val6="", - val7="", - val8="", - val9="", - **kwargs, - ): - """Prints the pressure in the near zone exterior to the equivalent source - - APDL Command: PRNEAR - surface. - - Parameters - ---------- - lab - Print the maximum pressure or sound pressure level: - - POINT - at the point (x,y,z) - - SPHERE - on the spherical structure - - PATH - along the path - - opt - PSUM - - PSUM - Maximum complex pressure for acoustics. - - PHAS - Phase angle of complex pressure for acoustics. - - SPL - Sound pressure level for acoustics. - - SPLA - A-weighted sound pressure level for acoustics (dBA). - - kcn - KCN is the coordinate system reference number. It may be 0 - (Cartesian) or any previously defined local coordinate system - number (>10). Defaults to 0. - - val1, val2, val3, . . . , val9 - For Lab = POINT: - - VAL1 - x coordinate value - - VAL2 - y coordinate value - - VAL3 - z coordinate value - - VAL4 - VAL8 - not used - - VAL9 - Thickness of model in z direction (defaults to 0). - - Notes - ----- - The command uses the equivalent source principle to calculate the - pressure in the near zone exterior to the equivalent source surface - (flagged with the Maxwell surface flag in the preprocessor) for one of - the following locations: - - A point X, Y, Z in the KCN coordinate system - - A spherical surface in the KCN coordinate system - - A path defined by the PATH and PPATH commands - - To list the pressure results for a path, use the PRPATH command. See - HFSYM command for the model symmetry. - - To retrieve saved equivalent source data, issue the - SET,Lstep,Sbstep,,REAL command. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"PRNEAR,{lab},{opt},{kcn},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8},{val9}" - return self.run(command, **kwargs) - - def reswrite(self, fname="", cflag="", **kwargs): - """Appends results data from the database to a results file. - - APDL Command: RESWRITE - - Parameters - ---------- - fname - File name and directory path (248 characters maximum, - including the characters needed for the directory - path). An unspecified directory path defaults to the - working directory; in this case, you can use all 248 - characters for the file name. The file name extension - varies as follows: - - - .RST for structural, fluid, or coupled-field analyses - - .RTH for thermal or electrical analyses - - .RMG for magnetic analyses - - cflag - 0 - The complex results flag is set to 0 in the results - file header. This is the default option. - - 1 - The complex results flag is set to 1 in the results - file header. - - Notes - ----- - The RESWRITE command appends a data set to the specified file - by writing the results data currently in the database. If the - intended results file does not exist, it will be created and - will include the geometry records. The current load step, - substep, and time (or frequency) value are maintained. All - data (summable and nonsummable) are written. - - When complex results are appended, cFlag must be set to 1 so - that the header is consistent with the results written on the - file. - - The command is primarily intended for use in a top-down - substructuring analysis, where the full model is resumed and - the results data read from the use pass results file (SET), - and subsequently from all substructure expansion pass results - files (APPEND). The full set of data in memory can then be - written out via the RESWRITE command to create a complete - results file (as though you had run a nonsubstructured - analysis). - - The RESWRITE command can also be used to write a global - results file for a distributed parallel (Distributed ANSYS) - solution. This should only be necessary if the RESCOMBINE - command was used to combine results from local results files - into the database. The RESWRITE command can then be used to - write the combined results into a new results file. This new - results file will essentially contain the current set of - results data for the entire (i.e., global) model. - """ - - return self.run(f"RESWRITE,{fname},,,,{cflag}", **kwargs) - - def rmflvec(self, **kwargs): - """Writes eigenvectors of fluid nodes to a file for use in damping - - APDL Command: RMFLVEC - parameter extraction. - - Notes - ----- - RMFLVEC extracts the modal information from the modal results file for - all nodes specified in a node component called 'FLUN'. This component - should include all nodes which are located at the fluid-structural - interface. Mode shapes, element normal orientation, and a scaling - factor are computed and stored in a file Jobname.EFL. For damping - parameter extraction, use the DMPEXT command macro. See Introduction - for more information on thin film analyses. - - FLUID136 and FLUID138 are used to model the fluid interface. Both the - structural and fluid element types must be active. The fluid interface - nodes must be grouped into a component 'FLUN'. A results file of the - last modal analysis must be available. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"RMFLVEC," - return self.run(command, **kwargs) - - def rsplit( - self, - option="", - label="", - name1="", - name2="", - name3="", - name4="", - name5="", - name6="", - name7="", - name8="", - name9="", - name10="", - name11="", - name12="", - name13="", - name14="", - name15="", - name16="", - **kwargs, - ): - """Creates one or more results file(s) from the current results file based - - APDL Command: RSPLIT - on subsets of elements. - - Parameters - ---------- - option - Specify which results to include for the subset of elements. - - ALL - Write all nodal and element results based on the subset of elements (default). - - EXT - Write only the nodal and element results that are on the exterior surface of - the element subset. The results data will be averaged as in - PowerGraphics (see AVRES) when this results file is brought - into POST1. Only valid for solid elements. - - label - Define where the element subset is coming from. - - ALL - Use all selected element components (CMSEL) (default). - - ESEL - Use the currently selected (ESEL) set of elements. Name1 defines the results - file name. - - LIST - Use Name1 to Name16 to list the element component and/or assembly names (that - contain element components). - - name1, name2, name3, . . . , name16 - Up to 16 element component and/or assembly names (that contain - element components). - - Notes - ----- - Results files will be named based on the element component or assembly - name, e.g., Cname.rst, except for the ESEL option, for which you must - specify the results file name (no extension) using the Name1 field. - Note that the .rst filename will be written in all uppercase letters - (CNAME.rst) (unless using the ESEL option); when you read the file, you - must specify the filename using all uppercase letters (i.e., - file,CNAME). You may repeat the RSPLIT command as often as needed. All - results sets on the results file are processed. Use /AUX3 to produce a - results file with just a subset of the results sets. - - Use INRES to limit the results data written to the results files. - - The subset geometry is also written so that no database file is - required to postprocess the subset results files. You must not resume - any database when postprocessing one of these results files. The input - results file must have geometry written to it (i.e., do not use - /CONFIG,NORSTGM,1). - - Applied forces and reaction forces are not apportioned if their nodes - are shared by multiple element subsets. Their full values are written - to each results file. - - Each results file renumbers its nodes and elements starting with 1. - - This feature is useful when working with large models. For more - information on the advantages and uses of the RSPLIT command, see - Splitting Large Results Files in the Basic Analysis Guide. - """ - command = f"RSPLIT,{option},{label},{name1},{name2},{name3},{name4},{name5},{name6},{name7},{name8},{name9},{name10},{name11},{name12},{name13},{name14},{name15},{name16}" - return self.run(command, **kwargs) - - def rstmac( - self, - file1="", - lstep1="", - sbstep1="", - file2="", - lstep2="", - sbstep2="", - maclim="", - cname="", - keyprint="", - **kwargs, - ): - """APDL Command: RSTMAC - - Calculates modal assurance criterion (MAC) and matches nodal solutions - from two results files or from one results file and one universal - format file. - - Parameters - ---------- - file1 - File name (32 characters maximum) corresponding to the first - results file (.rst or .rstp file). If the file name does not - contain the extension, it defaults to .rst. - - lstep1 - Load step number of the results to be read in File1. - - N - Reads load step N. Defaults to 1. - - sbstep1 - Substep number of the results to be read in File1. - - N - Reads substep N. - - All - Reads all substeps. This value is the default. - - file2 - File name (32 characters maximum) corresponding to the second file - (.rst, .rstp, or .unv file). If the file name does not contain the - extension, it defaults to .rst. - - lstep2 - Load step number of the results to be read in File2. - - N - Reads load step N. Defaults to 1. - - sbstep2 - Substep number of the results to be read in File2. - - N - Reads substep N. - - All - Reads all substeps. This value is the default. - - maclim - Smallest acceptable MAC value. Must be 0 and 1. The default value - is 0.90. - - cname - Name of the component from the first file (File1). The component - must be based on nodes. If unspecified, all nodes are matched and - used for MAC calculations. If a component name is specified, only - nodes included in the specified component are used. Not applicable - to node mapping (TolerN=-1). - - keyprint - Printout options: - - 0 - Printout matched solutions table. This value is the default. - - 1 - Printout matched solutions table and full MAC table. - - 2 - Printout matched solutions table, full MAC table and matched nodes table. - - Notes - ----- - The RSTMAC command allows the comparison of the solutions from - either: - - Two different results files - - One result file and one universal format file - - The modal assurance criterion (MAC) is used. - - The meshes read on File1 and File2 may be different. If TolerN>0, - the nodes are matched. This is the default. If TolerN = -1, the - nodes are mapped and the solutions are interpolated from File1. - - Units and coordinate systems must be the same for both - models. When a universal format file is used, the nodal - coordinates can be scaled using UNVscale. - - The corresponding database file (.db) for File1 must be resumed - before running the command only if a component (Cname) is used or - if the nodes are mapped (TolerN = -1). - - Results may be real or complex; however, if results from File1 - have a different type from results in File2, only the real parts - of the solutions are taken into account in MAC calculations. The - analysis type can be arbitrary. - - Only structural degrees of freedom are considered. Degrees of - freedom can vary between File1 and File2, but at least one common - degree of freedom must exist. - - When node mapping and solution interpolation is performed - (TolerN=-1), File1 must correspond to a model meshed in solid - and/or shell elements. Other types of elements can be present but - the node mapping is not performed for those - elements. Interpolation is performed on UX, UY, and UZ degrees of - freedom. - - The solutions read on the results files are not all written to the - database, therefore, subsequent plotting or printing of solutions - is not possible. A SET command must be issued after the RSTMAC - command to post-process each solution. - - RSTMAC comparison on cyclic symmetry analysis works only if the - number of sectors on File1 and File2 are the same. Also comparison - cannot be made between cyclic symmetry results and full 360 degree - model results (File1 – cyclic solution, File2 – full 360 degree - model solution). Comparing cyclic symmetry solutions written on - selected set of node (OUTRES) is not supported. - - The modal assurance criterion values can be retrieved as - parameters using the ``*GET`` command (Entity = RSTMAC). - - For more information and an example, see Comparing Nodal Solutions - From Two Models (RSTMAC) in the Basic Analysis Guide. - """ - command = f"RSTMAC,{file1},{lstep1},{sbstep1},{file2},{lstep2},{sbstep2},,{maclim},{cname},{keyprint}" - return self.run(command, **kwargs) - - def spoint(self, node="", x="", y="", z="", **kwargs): - """Defines a point for moment summations. - - APDL Command: SPOINT - - Parameters - ---------- - node - Node number of the desired point. If zero, use X,Y,Z to describe - point. - - x, y, z - Global Cartesian coordinates of the desired summation point. Used - if NODE is 0. Defaults to (0,0,0). - - Notes - ----- - Defines a point (any point other than the origin) about which the - tabular moment summations are computed [NFORCE, FSUM]. If force - summations are desired in other than the global Cartesian directions, a - node number must be specified on the NODE field, and the desired - coordinate system must be activated with RSYS. - """ - command = f"SPOINT,{node},{x},{y},{z}" - return self.run(command, **kwargs) - - def spmwrite( - self, - method="", - nmode="", - inputs="", - inputlabels="", - outputs="", - outputlabels="", - nic="", - velacckey="", - fileformat="", - **kwargs, - ): - """Calculates the state-space matrices and writes them to the SPM file. - - APDL Command: SPMWRITE - - Parameters - ---------- - method - Reduction method for the calculation of the state-space matrices. - - MODAL - Method based on modal analysis results from LANB, LANPCG, SNODE, or SUBSP - eigensolver (default). - - nmode - Number of modes to be used. Defaults to all modes. - - inputs - Definition of the inputs. Defaults to all load vectors on the MODE - file. - - inputlabels - Definition of the input labels. Defaults to the load vector numbers - or input definition (node and degree of freedom array parameter), - depending on the Inputs specification. - - outputs - Definition of the outputs. Defaults to the inputs. - - outputlabels - Definition of the output labels. Defaults to the output definition - (node and degree of freedom) if used, else defaults to the - InputLabels. - - nic - Load vector on the MODE file used for the calculation of the - initial conditions. Defaults to no initial condition. - - velacckey - Output velocities and accelerations key. - - OFF - Output displacements only (default). - - ON - Output displacements, velocities and accelerations. - - fileformat - The format of the SPM file. - - 0 - Dense format. - - 1 - Matrix Market Exchange format (non-zero terms only). - - 2 - Simplorer SML format without reference (default). - - 3 - Simplorer SML format with common reference. - - 4 - Simplorer SML format with independent references. - - Notes - ----- - The SPMWRITE generates the file Jobname.SPM containing the state-space - matrices and other information. - - The following applies to the SML formats (FileFormat = 2, 3, and 4): - - For conservative systems where the outputs are equal to the inputs - (Outputs is left blank): - - The labels for the inputs (InputLabels) are required. - - The Inputs must use the array parameter option so that the input - degrees of freedom (DOFs) are known. - - For non-conservative systems where the outputs are not equal to the - inputs: - - The labels for the outputs (OutputLabels) are required. - - The file formats with references (FileFormat = 3 and 4) do not apply. - - Velocity and acceleration results are not included in the state-space - matrices calculation (VelAccKey = OFF) - - File format with common reference (FileFormat = 3) does not apply if - the inputs are based on DOFs of a different nature. All input DOFs - must be either all rotational or all translational and not a mix of the - two. - - A graphics file (Jobname_SPM.PNG) is generated. It contains an element - plot of the model. - - For more details about the reduction method and the generation of the - state-space matrices, see Reduced-Order Modeling for State-Space - Matrices Export in the Mechanical APDL Theory Reference. - - For examples of the command usage, see State-Space Matrices Export. - """ - command = f"SPMWRITE,{method},{nmode},{inputs},{inputlabels},{outputs},{outputlabels},{nic},{velacckey},{fileformat}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1_/status.py b/src/ansys/mapdl/core/_commands/post1_/status.py deleted file mode 100644 index f636aa2207..0000000000 --- a/src/ansys/mapdl/core/_commands/post1_/status.py +++ /dev/null @@ -1,141 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class Status: - def calc(self, **kwargs): - """Specifies "Calculation settings" as the subsequent status topic. - - APDL Command: CALC - - 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"CALC," - return self.run(command, **kwargs) - - def datadef(self, **kwargs): - """Specifies "Directly defined data status" as the subsequent status - - APDL Command: DATADEF - topic. - - 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"DATADEF," - return self.run(command, **kwargs) - - def display(self, **kwargs): - """Specifies "Display settings" as the subsequent status topic. - - APDL Command: DISPLAY - - 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"DISPLAY," - return self.run(command, **kwargs) - - def lccalc(self, **kwargs): - """Specifies "Load case settings" as the subsequent status topic. - - APDL Command: LCCALC - - 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. - - This command is also valid for rezoning. - """ - command = f"LCCALC," - return self.run(command, **kwargs) - - def point(self, **kwargs): - """Specifies "Point flow tracing settings" as the subsequent status topic. - - APDL Command: POINT - - 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"POINT," - return self.run(command, **kwargs) - - def spec(self, **kwargs): - """Specifies "Miscellaneous specifications" as the subsequent status - - APDL Command: SPEC - topic. - - 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"SPEC," - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1_/surface_operations.py b/src/ansys/mapdl/core/_commands/post1_/surface_operations.py deleted file mode 100644 index d60f543ca6..0000000000 --- a/src/ansys/mapdl/core/_commands/post1_/surface_operations.py +++ /dev/null @@ -1,512 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class SurfaceOperations: - def sucalc( - self, - rsetname="", - lab1="", - oper="", - lab2="", - fact1="", - fact2="", - const="", - **kwargs, - ): - """Create new result data by operating on two existing result data sets on - - APDL Command: SUCALC - a given surface. - - Parameters - ---------- - rsetname - Eight character name for new result data. - - lab1 - First result data upon which to operate. - - oper - Mathematical operation to perform. - - ADD - (lab1 + lab2 + const) - - SUB - (lab1 - lab2 + const) - - MULT - (lab1 * lab2 + const) - - DIV - (lab1 / lab2 + const) - - EXP - (lab1 ^ fact1 + lab2 ^ fact2 + const) - - COS - (cos (lab1) + const) - - SIN - (sin (lab1) + const) - - ACOS - (acos (lab1) + const) - - ASIN - (asin (lab1) + const) - - ATAN - (atan (lab1) + const) - - ATA2 - (atan2 (lab1 / lab2) + const) - - LOG - (log (lab1) + const) - - ABS - (abs (lab1) + const) - - ZERO - (0 + const) - - lab2 - Second result data upon which to operate. - - fact1 - First scaling factor (for EXP option only). - - fact2 - Second scaling factor (for EXP option only). - - const - Constant added to the values in the resulting data. - """ - command = f"SUCALC,{rsetname},{lab1},{oper},{lab2},{fact1},{fact2},{const}" - return self.run(command, **kwargs) - - def sucr( - self, - surfname="", - surftype="", - nrefine="", - radius="", - tolout="", - **kwargs, - ): - """Create a surface. - - APDL Command: SUCR - - Parameters - ---------- - surfname - Eight character surface name. - - surftype - Surface type. - - CPLANE - Surface is defined by the cutting plane in window one (controlled by the - working plane (/CPLANE,1), NOT the view settings - (/CPLANE,0)). - - SPHERE - Surface is defined by a spherical surface centered about the working plane - origin. - - INFC - Surface is defined by a cylindrical surface centered about the working plane - origin and extending indefinitely in the positive and - negative Z directions. - - nrefine - Refinement level. - - For SurfType = CPLANE - The refinement level of the surface "mesh". This will be an integer between 0 - and 3 (default = 0). See Notes below. - - For SurfType = SPHERE - The number of divisions along a 90° arc (minimum = 9). The default is 9. - - For SurfType = INFC - The number of divisions along a 90° arc (minimum = 9). The default is 9. - - radius - Appropriate radius value (for INFC or SPHERE). - - tolout - Tolerance value for inclusion of element facets within a prescribed - volume. (for INFC) - - Notes - ----- - This command creates a new surface and stores the following data for - that surface: - - For SurfType = CPLANE, nRefine refers to the number of points that - define the surface. An nRefine value of zero is used for points where - the element face intersects the cutting plane. - - If SurfType = CPLANE and nRefine = 0, the points reside at the section - cuts where the element intersects the cutting plane. Increasing nRefine - from 0 to 1 will subdivide each surface facet into 4 subfacets, and - increase the number of points at which results can be interpolated. - - For SurfType = CPLANE , the setting from the /EFACET command will - affect the creation of surface facets and the quality of the fit of the - surface in the model. SUCR employs geometry data from PowerGraphics to - aid in determining where the surface intersects the model. If - /EFACET,1 is in effect when the SUCR command is issued, then the - curvature of high order elements (that is, elements with midside nodes) - will be ignored. If your model contains high order elements, you can - see a better fit for your surface if /EFACET,2 is in effect when the - SUCR command is issued. Currently, the SUCR command interprets - /EFACET,4 to mean /EFACET,2. - - For SurfType = INFC, a default tolerance of 0.01 will be applied to - include the vertices of any facets that fall out of the cylinder - definition. This tolerance increases the facet size by one percent to - check for inclusion. Excluding facets under such a small tolerance may - yield unacceptable (aesthetically) results. Increasing the tolerance by - a larger amount (0.1 or 10%) will sometimes yield smother edges along - the surface you create. - """ - command = f"SUCR,{surfname},{surftype},{nrefine},{radius},{tolout}" - return self.run(command, **kwargs) - - def sudel(self, surfname="", **kwargs): - """Delete geometry information as well as any mapped results for specified - - APDL Command: SUDEL - surface. - - Parameters - ---------- - surfname - Eight character surface name. - """ - command = f"SUDEL,{surfname}" - return self.run(command, **kwargs) - - def sueval(self, parm="", lab1="", oper="", **kwargs): - """Perform operations on a mapped item and store result in a scalar - - APDL Command: SUEVAL - parameter. - - Parameters - ---------- - parm - APDL parameter name. - - lab1 - Eight character set name for the first set used in calculation. - - oper - Operation to perform: - - SUM - Sum of lab1 result values. - - INTG - Integral of lab1 over surface. - - AVG - Area-weighted average of a result item ``[Σ(lab1*DA) / Σ(DA)]`` - - Notes - ----- - The result of this operation is a scalar APDL parameter value. If - multiple surfaces are selected when this command is issued, then the - operation is carried out on each surface individually and the parameter - represents the cumulative value of the operation on all selected - surfaces. - """ - command = f"SUEVAL,{parm},{lab1},{oper}" - return self.run(command, **kwargs) - - def suget(self, surfname="", rsetname="", parm="", geom="", **kwargs): - """Moves surface geometry and mapped results to an array parameter. - - APDL Command: SUGET - - Parameters - ---------- - surfname - Eight character surface name. - - rsetname - Eight character result name. - - parm - APDL array parameter name (up to 32 characters). - - geom - Switch controlling how data is written. - - ON (or 1 or YES) - Writes geometry data and interpolated - results information to the parameter. - - OFF (or 0 or NO) - Writes only interpolated results - information to the parameter. (Default) - - Notes - ----- - For Geom = OFF (or 0 or NO), only results information is written to - this parameter. - - For Geom = ON (or 1 or YES), both geometry data and results information - are written to this parameter. Geometry data includes 7 data items: - (GCX, GCY, GCZ, NORMX, NORMY, NORMZ, and DA). Results information is - then written to the 8th column of the parameter. SetNames of GCX, GCY, - GCZ, NORMX, NORMY, NORMZ, and DA are predefined and computed when SUCR - is issued. - """ - command = f"SUGET,{surfname},{rsetname},{parm},{geom}" - return self.run(command, **kwargs) - - def sumap(self, rsetname="", item="", comp="", **kwargs): - """Map results onto selected surface(s). - - APDL Command: SUMAP - - Parameters - ---------- - rsetname - Eight-character name for the result being mapped. - - item - Label identifying the item. - - comp - Component label of item (if required). - - Notes - ----- - The SUMAP command maps results in the current coordinate system (RSYS) - using the selected set of elements. - - The command interpolates and stores the results data on to each of the - selected surfaces. - - SUMAP,ALL,CLEAR deletes all results sets from all selected surfaces. - """ - command = f"SUMAP,{rsetname},{item},{comp}" - return self.run(command, **kwargs) - - def supl(self, surfname="", rsetname="", kwire="", **kwargs): - """Plot result data on all selected surfaces or on a specified surface. - - APDL Command: SUPL - - Parameters - ---------- - surfname - Eight character surface name. ALL will plot all selected surfaces. - - rsetname - Eight character result name. - - kwire - Plot in context of model. - - 0 - Plot results without the outline of selected elements. - - 1 - Plot results with the outline of selected elements. - - Notes - ----- - If RSetName is left blank, then the surface geometry will be plotted. - If the Setname portion of the argument is a vector prefix (i.e. if - result sets of name SetNameX, SetNameY and SetNameZ exist), ANSYS will - plot these vectors on the surface as arrows. For example, SUPL, ALL, - NORM will plot the surface normals as vectors on all selected surfaces, - since NORMX NORMY and NORMZ are pre-defined geometry items. - """ - command = f"SUPL,{surfname},{rsetname},{kwire}" - return self.run(command, **kwargs) - - def supr(self, surfname="", rsetname="", **kwargs): - """Print global status, geometry information and/or result information. - - APDL Command: SUPR - - Parameters - ---------- - surfname - Eight character surface name. If SurfName = ALL, repeat printout - for all selected surfaces. - - rsetname - Eight character result set name. - - Notes - ----- - When no arguments are specified, SUPR generates a global status summary - of all defined surfaces. If only SurfName is specified, the geometry - information for that surface is printed. If both SurfName and RSetName - are specified, the value of the results set at each point, in addition - to the geometry information, is printed. - """ - command = f"SUPR,{surfname},{rsetname}" - return self.run(command, **kwargs) - - def suresu(self, fname="", fext="", fdir="", **kwargs): - """Read a set of surface definitions and result items from a file - - APDL Command: SURESU - and make them the current set. - - Parameters - ---------- - fname - Eight character name. - - fext - Extension name. - - fdir - Optional path specification. - - Notes - ----- - Reading (and therefore resuming) surface and result - definitions from a file overwritea any existing surface - definitions. - - Reading surfaces back into the postprocessor (/POST1) does not - insure that the surfaces (and their results) are appropriate - for the model currently residing in /POST1. - """ - return self.run(f"SURESU,,{fname},{fext},{fdir}", **kwargs) - - def susave(self, lab="", fname="", fext="", fdir="", **kwargs): - """Saves surface definitions to a file. - - APDL Command: SUSAVE - - Parameters - ---------- - lab - Eight-character surface name. - - fname - File name and directory path (248 character maximum, including - directory). If you do not specify a directory path, the default is - your working directory and you can use all 248 characters for the - file name. The file name defaults to the jobname. - - fext - File name extension (eight-character maximum). The extension - defaults to "surf". - - fdir - Optional path specification. - - Notes - ----- - The SUSAVE command saves surface definitions (geometry - information)--and any result items mapped onto the surfaces--to a file. - - Issuing the SUSAVE command has no effect on the database. The database - remains unchanged. - - Subsequent executions of the SUSAVE command overwrite previous data in - the file. - - To read the contents of the file created via the SUSAVE command, issue - the SURESU command. - """ - command = f"SUSAVE,{lab},{fname},{fext},{fdir}" - return self.run(command, **kwargs) - - def susel( - self, - type_="", - name1="", - name2="", - name3="", - name4="", - name5="", - name6="", - name7="", - name8="", - **kwargs, - ): - """Selects a subset of surfaces - - APDL Command: SUSEL - - Parameters - ---------- - type\\_ - Label identifying the type of select: - - S - Selects a new set (default). - - R - Reselects a set from the current set. - - A - Additionally selects a set and extends the current set. - - U - Unselects a set from the current set. - - ALL - Also selects all surfaces. - - NONE - Unselects all surfaces. - - name1, name2, name3, . . . , name8 - Eight character surface names - - Notes - ----- - The selected set of surfaces is used in the following operations: - SUMAP, SUDEL, SUCALC, SUEVAL, and SUVECT. - """ - command = f"SUSEL,{type_},{name1},{name2},{name3},{name4},{name5},{name6},{name7},{name8}" - return self.run(command, **kwargs) - - def suvect(self, rsetname="", lab1="", oper="", lab2="", offset="", **kwargs): - """Create new result data by operating on two existing result vectors on a - - APDL Command: SUVECT - given surface. - - Parameters - ---------- - rsetname - Eight character name of the result data output. There will be one - or three RSetName values depending on the operation specified in - Oper. - - lab1 - Eight character name of the mapped data that forms vector 1. - Specified sets must exist on all selected surfaces for this - operation to take place. The names NORM and GC will be reserved for - normals and for global (x, y, z). - - oper - DOT - - DOT - Computes dot product between lab1 and lab2 vectors. The result is a scalar - parameter (RSetName) and each value within the set can be - modified (incremented) via Offset. - - CROSS - Computes cross product between lab1 and lab2 vectors. Each X, Y, Z value in the - result can be modified (incremented) via Offset. - - SMULT - Scales (lab1x, lab1y, lab1z) vector by scalar lab2. Each X,Y,Z value in the - result can be modified (incremented) via Offset. - - lab2 - Eight character name of the mapped data that forms vector 2. Sets - with names Lab2X, Lab2Y, and Lab2Z must exist on all selected - surfaces for operation to take place. For Oper = SMULT a scalar - value or another predefined scalar item (e.g., DA) can be supplied. - - offset - An offset value to be applied to the resultant RSetName. One value - is specified for Oper = DOT, and three values are specified for - Oper = SMULT. - """ - command = f"SUVECT,{rsetname},{lab1},{oper},{lab2},{offset}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/post1_/trace_points.py b/src/ansys/mapdl/core/_commands/post1_/trace_points.py deleted file mode 100644 index c0e81cb8fb..0000000000 --- a/src/ansys/mapdl/core/_commands/post1_/trace_points.py +++ /dev/null @@ -1,237 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class TracePoints: - def pltrac( - self, - analopt="", - item="", - comp="", - trpnum="", - name="", - mxloop="", - toler="", - option="", - escl="", - mscl="", - **kwargs, - ): - """Displays a particle flow or charged particle trace on an element - - APDL Command: PLTRAC - display. - - Parameters - ---------- - analopt - Analysis option - - FLUID - Particle trace in fluid flow (default) - - ELEC - Particle trace in electric field - - MAGN - Particle trace in magnetic field - - EMAG - Particle trace in presence of both electric and magnetic fields - - item - Label identifying the item to be contoured. Valid item labels are - shown in Table 222: PLTRAC - Valid Item and Component Labels - below. Some items also require a component label. If Item is - blank, display only the path trajectory. - - comp - Component of the item (if required). Valid component labels are - shown in Table 222: PLTRAC - Valid Item and Component Labels below. - - trpnum - Trace point number for storing trajectory data for use with PATH - logic. Defaults to 0 (no trajectory path data is stored for further - processing with PATH logic). - - name - Name of prefix of array variable. Defaults to TRAC. NamePOIN stores - trajectory path points for trace point number TRPNum. If Analopt = - ELEC, MAGN, or EMAG, two additional array parameters, NameDATA and - NameLABL, store trajectory path data and labels for the same - TRPNum. - - mxloop - Maximum number of loops traced by a particle. Defaults to 25 for - Opt = FLUID; otherwise, defaults to 1000. - - toler - Length tolerance used for particle trajectory geometry calculation. - Valid only for Analopt = ELEC, MAGN, or EMAG. If particle trace - appears to terminate inside an element, adjusting the length - tolerance may be necessary. Defaults to 1.0 x 10-8. - - option - Flow trace option: - - 0 - Use the undeformed mesh for computing the flow trace. - - 1 - Use the deformed mesh for computing the flow trace. - - escl - Electric field scale factor. Setting this scale factor affects only - the tracing, not the field solution results. A negative factor - corresponds to the opposite vector direction. Valid only for - Analopt = ELEC or EMAG. Defaults to 1. - - mscl - Magnetic field scale factor. Setting this scale factor affects only - the tracing, not the field solution results. A negative factor - corresponds to the opposite vector direction. Valid only for - Analopt = MAGN or EMAG. Defaults to 1. - - Notes - ----- - For a specified item, the variation of the item is displayed along the - particle trace as a color-contoured ribbon. The TRPOIN command must be - used to define a point on the trajectory path. Multiple traces may be - displayed simultaneously by defining multiple trace points. Issue the - TRPLIS command to list the current tracing points. Issue the TRPDEL - command to delete tracing points defined earlier. Use the PAPUT - command with the POIN option to retrieve the particle trajectory points - as path points. - - The model must be 3-D for the ELEC, MAGN, and EMAG analysis options. - - Three array parameters are created at the time of the particle trace: - TRACPOIN, TRACDATA and TRACLABL. These array parameters can be used to - put the particle velocity and the elapsed time into path form. The - procedure to put the arrays into a path named PATHNAME is as follows: - - Not used if Analopt = FLUID. If working in the GUI, use the "All - information" option to retrieve information from all three arrays at - once. - - If OPTION is set to 1, the deformed mesh is based on the displacement - degrees of freedom UX, UY, and UZ, which must be available in the load - step. - - Table: 222:: : PLTRAC - Valid Item and Component Labels - - See the Basic Analysis Guide for more information on particle flow and - charged particle traces. See Animation in the Basic Analysis Guide for - information on particle trace animation. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"PLTRAC,{analopt},{item},{comp},{trpnum},{name},{mxloop},{toler},{option},{escl},{mscl}" - return self.run(command, **kwargs) - - def trpdel(self, ntrp1="", ntrp2="", trpinc="", **kwargs): - """Deletes particle flow or charged particle trace points. - - APDL Command: TRPDEL - - Parameters - ---------- - ntrp1, ntrp2, trpinc - Delete points from NTRP1 to NTRP2 (defaults to NTRP1) in steps of - TRPINC (defaults to 1). If NTRP1 = ALL, NTRP2 and TRPINC are - ignored and all trace points are deleted. If NTRP1 = P, graphical - picking is enabled and all remaining command fields are ignored - (valid only in the GUI). - - Notes - ----- - Deletes particle flow or charged particle trace points defined with the - TRPOIN command. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"TRPDEL,{ntrp1},{ntrp2},{trpinc}" - return self.run(command, **kwargs) - - def trplis(self, ntrp1="", ntrp2="", trpinc="", opt="", **kwargs): - """Lists the particle flow or charged particle trace points. - - APDL Command: TRPLIS - - Parameters - ---------- - ntrp1, ntrp2, trpinc - List points from NTRP1 to NTRP2 (defaults to NTRP1) in steps of - TRPINC (defaults to 1). If NTRP1 = ALL, NTRP2 and TRPINC are - ignored and all trace points are listed. If NTRP1 = P, graphical - picking is enabled and all remaining command fields are ignored - (valid only in the GUI). - - opt - Opt = LOC lists the trace point number location (X, Y, Z). Default. - - Notes - ----- - Lists the particle flow or charged particle trace points in the active - display coordinate system [DSYS]. Trace points are defined with the - TRPOIN command. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"TRPLIS,{ntrp1},{ntrp2},{trpinc},{opt}" - return self.run(command, **kwargs) - - def trpoin(self, x="", y="", z="", vx="", vy="", vz="", chrg="", mass="", **kwargs): - """Defines a point through which a particle flow or charged particle trace - - APDL Command: TRPOIN - will travel. - - Parameters - ---------- - x, y, z - Coordinate location of the trace point (in the active coordinate - system). If X = P, graphical picking is enabled and all remaining - command fields are ignored (valid only in the GUI). - - vx, vy, vz - Particle velocities in the X, Y and Z directions (in the active - coordinate system). - - chrg - Particle charge. - - mass - Particle mass. - - Notes - ----- - Defines a point through which a particle flow or charged particle trace - [PLTRAC] will travel. Multiple points (50 maximum) may be defined - which will result in multiple flow traces. Use TRPLIS to list the - currently defined trace points and TRPDEL to delete trace points. - - The VX, VY, VZ, CHRG, and MASS arguments only apply to charged - particles. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"TRPOIN,{x},{y},{z},{vx},{vy},{vz},{chrg},{mass}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/commands.py b/src/ansys/mapdl/core/commands.py index 96427cfe3f..8fdd0f7e55 100644 --- a/src/ansys/mapdl/core/commands.py +++ b/src/ansys/mapdl/core/commands.py @@ -46,7 +46,6 @@ map, misc, post1, - post1_, post26, preproc, reduced, @@ -441,14 +440,14 @@ class Post1Commands( post1.failure_criteria.FailureCriteria, post1.listing.Listing, post1.load_case_calculations.LoadCaseCalculations, - post1_.magnetics_calc.MagneticsCalc, - post1_.path_operations.PathOperations, - post1_.results.Results, - post1_.setup.Setup, - post1_.special.Special, - post1_.status.Status, - post1_.surface_operations.SurfaceOperations, - post1_.trace_points.TracePoints, + post1.magnetics_calculations.MagneticsCalculations, + post1.path_operations.PathOperations, + post1.results.Results, + post1.set_up.SetUp, + post1.special_purpose.SpecialPurpose, + post1.status.Status, + post1.surface_operations.SurfaceOperations, + post1.trace_points.TracePoints, ): pass